Build-System

libFAUDES C++ sources are largely POSIX compliant and have been verified to compile on various platforms, incl. Linux, Mac OsX and MS Windows, both 32-bit and 64-bit variants. Still, the build process is quite involved and requires certain additional tools. The download page therefore provides precompiled libFAUDES archives including executables of luafaudes and other relevant utilities.

For all other system environments you need to use the standard libFAUDES distribution and re-compile. The required steps are described below.

Application-Developer Targets

For application develoment (i.e. using but not extending libFAUDES) the library should be compiled with the same toolchain as used for the application. We have set up CompileDES as an example on how to organise the development of libFAUDES based applications, including the utilisation of modern IDEs like Qt Creator and MS Visual Studio. We provide some more technical detail on the supported toolchains.

The standard distribution ships with a configured source tree and provides a GNU-Makefile for compilation within POSIX compliant environments. The following application developer targets arte supported.

After extracting the libFAUDES archive to e.g. ./libfaudes, open a shell (aka console, command line, etc) and run

> make
> make tutorial
> make test

from within ./libfaudes to re-compile libFAUDES where the GNU-make tool extracts the rules of how exactly the targets are to be built from the the Makefile. There are a number of details to be addressed here.

Each make-tool comes with a specific dialect and the provided Makefile requires specifically GNU-make to expand in the intended manner. On Linux and Mac OS X GNU-make is part of the system toolchain and, thus, readily available by installing C++-development packages or XCode, respectively. On MS Windows there is no concept af a designated system toolchain, even though MS Visual C became quite common with the free-of-cost community editions. Unfortunately, the included nmake-tool will not build libFAUDES. To this end, the MinGW project provides a variant of the GNU-toolchain toolchain for native MS Windows development and it includes the compatible make tool mingw32-make. Dont be confused by the 32 in the name: the organisation of the build process has no implication on the bitiness of the result. So for MS Windows, the above build sequence looks like this

set PATH=%PATH%;C:\MinGW\bin
C:\libfaudes> mingw32-make FAUDES_PLATFORM=gcc_win
C:\libfaudes> mingw32-make FAUDES_PLATFORM=gcc_win tutorial 
C:\libfaudes> mingw32-make FAUDES_PLATFORM=gcc_win test 

Note the set-path directive to specify the location of make, g++ and gcc. Also of interest is the FAUDES_PLATFORM definition that directs the make tool to invoke the compiler/linker with tailored switches to match the respective environment. The provided Makefile supports four or theese flavors to shape the build process.

The three platforms gcc_linux, gcc_osx and gcc_win all refer to the GNU-toolchain (or close relatives). The corresponding tool can be obtained by the system packamanager (Linux), as part of the XCode developer tool (Mac OsX) or with the MinGW project (MS Windows). In order to adjust the various compiler/linker options to the application at hand, it is recommende to cut&past the respective section from the Makefile as a starting oint for further tuning. Since linFAUDES is largely developped with the gcc_linux and gcc_osx setup, it adapts well the GNU-toolchain.

The fourth platform cl_win addresses the compiler cl.exe provided by MS Visual Studio on MS Windows. To use MS Visual C for the development of a libFAUDES based application, it is a prerequisite to compile libFAUDES with the same version of cl.exe as it will be used for application developement, an with matching compiler/linker options. Among the vast number of preceivable usecases, libFAUDES is currently distributed in two orthogonal shapes that can be selected with the FAUDES_LINKING switch as demonstrated below and that have both been compiled with the community edition of MS Vusial C 2015.

call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat"  x86_amd64
C:\libfaudes> mingw32-make FAUDES_PLATFORM=cl_win FAUDES_LINKING="static debug"

First, the batch file provided by MS Visual C sets up the environment to the 64bit compilers. Then "FAUDES_LINKING="static debug" builds the archieve faudesd.lib> that links dynamically against the C libraries in their debug variant but isitself is meant for static linking with an host application. Relevant compiler options are /MDd and /EHsc, in some cases may /Zi also be of interest. Note that binaries with static linking to libFAUDES may only be distributed under terms of the GPL license. For dynamic linking in release mode, we have set up

C:\libfaudes> mingw32-make FAUDES_PLATFORM=cl_win FAUDES_LINKING="shared"

to build the shared object faudes.dll along with the linker archieve faudes.lib, now using /MD and /EHsc. For application development in release mode, one directs the linker to faudes.lib which results in a dynamic linkage with faudes.dll, i.e., one may distribute the application together with the file faudes.dll.

Library-Developer Targets

When adding or removing libFAUDES plug-ins, the build-system needs to configure the source tree and generate UI and API documentation. In this stage, the current build-system relies on a number of more or less common Unix tools. For the following library developer targets we recommend a Unix-style environment:

Most Linux distributions come with both Perl and SWIG, the latter may require installation. Regarding SWIG, the particular version can be crucial --- we have positive confirmation for v1.3.36, v1.3.40 and v2.0.10; cross-configuration for Windows/64-bit/VS-compiler requires 3.02, however, the early 3.xx series seems to produce some spurious warnings with Linux/gcc; as a technical detail, libFAUDES comes with a tweaked version of typemaps.i in ./plugins/luabindings/src/ taken from SWIG v2.0.10, which you may need to remove for newer SWIG versions.

For libFAUDES development on a Windows system, we recommend to use the Cygwin environment. This has been tested with Cygwin version 1.7.9-1, choosing the devel package from the Cygwin installer. At the time of writing, Graphviz/dot was not available via Cygwin, however, a native Windows binary can be obtained directly from Graphviz

To re-configure and compile libFAUDES sources from scratch, you may run

> make dist-clean
> make configure
> make 
> make tutorial
> make test

When developing a plug-in, it is advisable to first edit the main Makefile to only enable those plug-ins, that are required in the development process. This will keep compilation times reasonably short. In particular, the luabindings depend on every single header file and the build process will recreate all luabindings from scratch when you edit any single header.

Reference Documentation Processing

While libFAUDES uses doxygen as a professional tool to generate the C++ API documentation, we did not yet find a similar tool for the user-reference. In order to still have some systematic approach to a user-level documentation, the libFAUDES build-system uses the run-time-interface as a basis. The compilation process invokes a number of home-grown tools which may need a re-design in due course. However, some care has been taken to have a consistent input format that encodes relevant structural data. In the meanwhile, we would like to encourage plug-in developers to (a) contribute to the user-reference to advertise the plug-in and (b) stick to the below conventions where ever possible to ease revisions of the build process.

RTI Definitions

A plug-in should provide one or more RTI definition files that define a URL and a list of keywords per user relevant faudes-function or faudes-type. The first keyword will be interpreted as section-name. Thus, the provided RTI definition files implicitly define the overall section structure of the user-reference. The section name typically matches the plug-in name. By convention, the URL consists of a filename and a location. The filename should start with the section name followed by an underscore. The location should match the respective function or type name.

Example, taken from cfl_definitions.rti

<FunctionDefinition name="CoreFaudes::LanguageConcatenate" [...] > 
<Documentation ref="corefaudes_regular.html#LanguageConcatenate"> 
Concatenates two languages.
</Documentation> 
<Keywords> 
CoreFaudes    "regular expressions"   generator     language      concatenate   
</Keywords> 
[...]
</FunctionDefinition> 

Documentation Source Files

A plug-in must provide documentation files corresponding to the URLs defined in the RTI definition files. As all libFAUDES documentation, the provided files have the extension *.fref and are processed by ref2html to generate plain XHTML output. The contents of an *.fref-file is expected to be well-formed XML with outer tag <ReferencePage> and otherwise using XHTML markup. More precisely, the outer tag <ReferencePage> corresponds to the <Body> tag from XHTML. For a selfcontained organization of the overall reference documentation, <ReferencePage> supports attributes to indicate chapter, section, page and title of the respective page. The following conventions apply:

Given all reference pages, the chapter, section and page-attributes implicitly define the overall documentation structure, used to automatically generate tables of contents and to provide consistent navigation. The title-attributes are cosemetic.

Example, taken from corefaudes_regular.fref

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE ReferencePage SYSTEM "http://www.faudes.org/dtd/1.0/referencepage.dtd">
<ReferencePage chapter="Reference" section="CoreFaudes" page="RegularExpressions" title="CoreFaudes - Regular Expressions">

<h1>
Functions related to Regular Expressions
</h1>

<p>
Regular expressions extend the <a href="corefaudes_langboolean.html">boolean algebra on languages</a> 
by the Kleene-closure and language concatenation operation. Additionally,  functions for the generating 
elements are provided, i.e. full- and alphabet language.
</p>

[... more HTML markup ... ]

</ReferencePage>

For convenience, the tool ref2html will recognise and substitute additional markup to support a consistent layout.

Note: A DTD file for the validation of documentation input files is provided. It is recommended to use an XML tool like xmllint or an XML editor in the process of editing documentation files.

Processing

To trigger a re-build of the user-reference, use

> make rti-clean
> make rti

This will

 

 

libFAUDES 2.28a --- 2016.09.13 --- with "timed-iodevice-simulator"