|
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 therefor 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, 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 default
from within ./libfaudes to re-compile libFAUDES.
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
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.
For library extensions by 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:
include 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 GTML/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.
The libFAUDES archive provides a copy of GTML and SWIG for convenience. Assuming you have Perl installed anyway, the provided GTML will be functional as it is. SWIG, however, requires installation.
To re-configure libFAUDES sources from scratch, you may run
> make dist-clean > make configure
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 actual process invokes a number of home-grown tools and is perhaps due for a thorough re-design. 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. By convention, the URL consists of a filename and a location. The filename should start with the section name (which usually matches the plug-in name) followed by an underscore. The location should match the respective function or type name.
Example: URL corefaudes_regular.html#LanguageConcatenate, Keywords CoreFaudes, Regular Expressions, Languages, ... .
A plug-in must provide documentation files corresponding to the URLs defined in the RTI definition files. In order to minimize redundancy and still have a consistent layout (navigation etc.), the documentation files are processed by the Perl script GTML. Each provided documentation file should contain valid HTML as it appears between the <body> and </body> tags and use the below GTML macros:
<<TYPEBEGIN(type-name)>>. Indicates the begin of the documentation of a faudes type. The macro expands to a headline, incl the anchor defined in the RTI definition.
<<TYPEEND>>. Indicates the end of the documentation of a faudes-type.
<<FUNCTIONBEGIN(function-name)>>. Indicates the begin of the documentation of a function. The macro expands to a headline, the short text from the RTI definition and the signatures from the RTI definition.
<<FUNCTIONEND>>. Indicates the end of the documentation of a function.
<<PAR(parameter)>>. This macro expands to the function parameter, currently using italic font.
<<FTYPE(type-name)>>. Expands to the given type-name, incl a link to the respective documentation.
<<FFNCT(function-name)>>. Expands to the given function-name, incl a link to the respective documentation.
<<DETAILS>>, <<CONDITIONS>>, <<EXAMPLE>>. These macros expand to the corresponding headlines.
<<HIMAGE(image-file)>>. Includes an image with extension .png and a link to a corresponding .html file. This macro is used e.g. for generator graphs with corresponding token IO in an extra HTML file. All example data should be generated by a shell script from the tutorial directory.
<<IMATH(latex-formula)>>, <<DMATH(latex-formula)>>. Expand to the specified text interpreted as LaTeX formatted formula, inline or displayed, respectively. The LaTeX formula is meant to be reasonably simple (no TeX macro definitions, no nested groups {xyz {abc}}, don't contain a double quote "). The current version of the underlying Perl script that interprets the formula is very basic and makes no attempt to produce LaTeX style output.
The above macros are defined in ./src/doxygen/faudes_macros.html (general) and ./src/registry/registry_macros.html (registry specific). For the plug-in yourplugin, you can define additional macros by providing a file ./plugins/yourplugin/src/registry/yourplugin_macros.html. This mechanism is used for a preliminary approach to manage literature references:
Define a label by
#define LABEL_label XYZ
where XYZ is the label how it should show when you cite the reference in your document.
Define the actual reference by
#define PAPER_label Interesting paper, page 7, important book
where Interesting paper, ... is the text to appear in the list of references. For technical reasons, the text may not contain any single quotes '.
By convention, define the macros
#define CITE_label <a href="yourplugin_index.html#lit_<<LABEL_label>>">[<<LABEL_label>>]</a> #define LLIT_label <<LITERATURE(<<LABEL_label>>,'<<PAPER_label>>')>> #define+ LITERATURE_ALL <<LLIT_label>>
In the index file of your section yourplugin_index.gtml, include the actual reference by
<h2>Literature</h2> <<LLIT_label>> <<LLIT_otherlabel>>
Use <<CITE_label>> to cite the reference in your documentation.
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 ./bin/rti2html. The latter reads RTI definition files and produces HTML formatted section lists, linked function-names etc, in order to assist in resolving the above macros.
Copy all provided documentation sources to the ./obj/registry build directory. Assemble the file ./obj/registry_xmacros by merging plug-in sources *_marcos.gtml.
Process the reference pages with GTML in order to expand the above macros. The actual registry pages are based on the template ./src/registry/registry_template.html, macros are included from ./src/registry/registry_macros.html and ./obj/registry_xmacros.
libFAUDES 2.18b --- 2010-12-17 --- plugins "example synthesis observer diagnosis hiosys iosystem multitasking timed simulator iodevice luabindings"