libFAUDES C++ sources are POSIX compliant and have been verified to compile on various platforms, incl. Linux, Mac OsX and MS Windows. Still, the build process can be a hassle. The download page therefore provides precompiled libFAUDES archives including executables of luafaudes and other utilities.
Linux: The standard libFAUDES distribution ships as tar.gz archive and includes Linux binaries. Simply extract the archive file and test by e.g. running a luafaudes tutorial script.
In order to improve cross distribution compatibility, the precompiled binaries link against so called LSB 3.2 system library stubs in their 32-bit variant. In the case your system does not have the relevant LSB packages installed, you may either re-compile libFAUDES (see below) or install the missing packages.
Example: installing LSB packages on Ubuntu 10.04, both 32-bit and 64-bit distributions.
> aptitude install lsb
Example: installing LSB packages on Fedora 14, 32-bit distribution
> yum install redhat-lsb
Example: installing LSB packages on Fedora 14, 64-bit distribution
> yum install redhat-lsb > yum install redhat-lsb.i686
If you experience errors for missing libraries or unresolved symbols, please let us know.
MS Windows: Precompiled packages come as setup.exe installers and can be found in the archive of the libFAUDES download page. They contain the HTML documentation, precompiled libFAUDES incl luafaudes and some examples.
For all other system environments you need to use the standard libFAUDES distribution and re-compile. The required steps are described below.
The standard distribution ships with a configured source tree and provides a GNU-make Makefile that supports the following application developer targets.
default to compile the library (both shared and static) and utility executables,
tutorial to compile the provided tutorials
test to validate against reference protocols, and
clean to remove temporary object files.
After extracting the libFAUDES archive to e.g. ./libfaudes, open a shell (aka console, command line, etc) and run
> make clean > make > make tutorial > make test
from within ./libfaudes to re-compile libFAUDES. On a multi-processor system, you may try
> make -j nn
where nn specifies the number of jobs to run in parallel. This has been tested only for the default target and is not expected to be functional for any other targets.
The Makefile uses some GNU-make specific extensions, so you are best of using the GNU tool-chain. Most Linux Distributions offer a C++ development package. For Mac OsX, the GNU tool-chain is provided by Apple's Developer Package or the Darwin project.
For MS Windows, libFAUDES has been verified to compile with Cygwin or MinGW. The former provides an almost POSIX environment and you can go ahead with the same instructions as for Linux/Unix. For MinGW you can use the supplied Makefile. However, you may need to specify the platform explicitly by e.g.
C:\libfaudes> make clean FAUDES_PLATFORM=gcc_win C:\libfaudes> make default FAUDES_PLATFORM=gcc_win C:\libfaudes> make tutorial FAUDES_PLATFORM=gcc_win
Note that the MinGW make, g++ and gcc must be specified in your PATH environment variable.
If you want to use MS Visual C++, the starting point is to grab the configured libFAUDES source and dump them into a Visual C++ project. When we last tested this, there was an issue with STL const_iterators, which was resolved by installing an SGI implementation of STL. Let us know if MS Visual C++ is crucial for your application.
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:
includes to set-up the overall include directory and to update debugging switches (you may need to manually remove all files from the include directory before);
rti/rti-clean to set up the libFAUDES RTI incl HTML user-reference in ./doc/registry (requires Perl),
doc/doc-clean to set up the doxygen and static HTML documentation in the ./doc directory (requires all of the above plus doxygen v1.4.4 or above),
configure to do an overall configuration (requires all of the above plus SWIG v1.3.36 for the luabindings plug-in), and
dist-clean to remove any non-source files.
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.1). The libFAUDES archive provides the SWIG sources used for libFAUDES development.
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.
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.
A plug-in should provide one or more RTI definition files that define an URL and a list of keywords per user relevant faudes-function or faudes-type. The first two keywords will be interpreted as section- and subsection name, respectively. 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 Functions generator language concatenate </Keywords> [...] </FunctionDefinition>
A plug-in must provide documentation files corresponding to the URLs defined in the RTI definition files. By convention, there must be an index file per section, named nameofsection_index.html. As all libFAUDES documentation, the provided files are processed by ref2html. Documentation source files are expected to be well-formed XML and use the outer tag <ReferencePage> to indicate chapter, section and title. By convention, the chapter of the user-reference is Reference. The provided data is used to automatically generate consistent navigation. Any HTML markup in the documentation source will be passed through.
Note: An experimental 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.
Note: Up to libFAUDES 2.18b, documentation was processed by GTML and therefore used a different file format (*.gtml files). The new format introduced with 2.19a was designed to obtain XML compatibility. Conversion support is available on request.
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" 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 some additional markup to support a consistent layout.
Documentation of a faudes type: is substituted by a headline, incl. the anchor defined in the RTI definition. Example:
<ftype_reference name="Name_Of_Type"> [... text ...] </ftype_reference>
Documentation of a faudes function: is substituted by a headline, incl. the anchor defined in the RTI definition; the provided documentation text and signature from the run-time-interface. Example:
<ffnct_reference name="Name_Of_Function"> [... text ...] </ffnct_reference>
Standard headlines within faudes type or faudes function documentation: are substituted by the respective heading. Example:
<fdetails/> <fexample/> <fconditions/>
URL to faudes type or faudes function documentation: is substituted by the type- or function name, incl. a link to the respective documentation. Example:
<ftype>Name_Of_Type</ftype> <ffnct>Name_Of_Function</ffnct>
URL attributes to other documentation: the non HTML attributes fhref and fsrc are replaced by the HTML attributes href and src, respectively; any occurrence of FAUDES_IMAGES, FAUDES_CSOURCE, FAUDES_REGISTRY or FAUDES_ONLINE in the value is replaced by an appropriate string. Example:
<img fsrc="FAUDES_IMAGES/some_image.png"/> <a fhref="FAUDES_ONLINE">click here</a>
Generator image: is substituted by HTML markup to embed the respective .png image, incl a link to the corresponding token stream and an .svg version; all relevant files must be provided, perhaps conveniently generated by a script in the tutorial directory. Example:
<fimage fsrc="tmp_concat_g5"/>
Math formulas, in-lined or displayed: are substituted by HTML to mimic a reasonably simple LaTeX formated formula; the conversion is *very* basic and tailored to existing plug-ins (no TeX macro definitions, no nested groups, etc); for the time being, we recommend you to specify your LaTeX formula as simple as possible, to observe the generated HTML and to notify us about undesired effects; alternatively, you may render your formula directly in HTML. Example:
<fimath> L_m(G) \subseteq \Sigma^* <fimath> <fdmath> L_m(G) \subseteq \Sigma^* <fdmath>
Literature and citations: are substituted by HTML incl. an anchor for citation; by convention, literature may only be introduced in the section index pages. Example:
<fliterature name="C1"> <fauthors>W.M. Wonham</fauthors> <ftitle>Supervisory Control of Discrete-Event Systems</ftitle> <fpublisher>available at <a href="http://www.control.toronto.edu [...] ">University of Toronto</a></fpublisher> <fyear>2009 (revised)</fyear> </fliterature>
<p> [...] see also <fcite name="C1"/> [...] </p>
To trigger a re-build of the user-reference, use
> make rti-clean > make rti
This will
Assemble the overall RTI definition file ./include/libfaudes.rti and compile the HTML generator tool ref2html.
Process the reference pages with ref2html in order to perform the above substitutions.
libFAUDES 2.22k --- 2013.04.02 --- with "timed-iodevice-simulator"