| |
|
||||||
|
|
|||||||
libFAUDES C++ sources are largely POSIX compliant and have been verified to compile on various platforms, incl. Linux, Mac OsX and MS Windows. 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.
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. If you experience errors regarding missing/incompatible libraries, you will need to re-compile. Sorry for the inconvenience.
Note on Linux binary compatibility. As of 2022, we compile on a somewhat outdated Linux distribution to obtain binaries that are compatible to some extend. In earlier days, we used to link the precomiled binaries against so called LSB 3.2 system library stubs which we considered a great approach for cross-distribution binary compatibility. However, LSB was last updated in 2015 and common Linux distributions stepped out from then on. If you want/need to run early versions of libFAUDES or derived software, you may need to install the LSB loader.
Example: installing LSB packages on Ubuntu 18.04LTS
> aptitude install lsb
Example: installing LSB packages on Fedora 14
> yum install redhat-lsb
Example: installing LSB packages on Fedora 14, 64-bit distribution, to use 32-bit libFAUDES components
> yum install redhat-lsb > yum install redhat-lsb.i686
All binary compatibility issues are readily resolved if you re-compile your copy of libFAUDES; see the instructions below.
macOS: There is no dedicated libFAUDES distribution for macOS, compilation follows the same path as for Linux, see below. Alternatively, you may download one of the application packages (e.g. DESTool or FlexFact) and extract the relevant binaries from the bundle file. Our current test target is macOS 12 (dated 2021) and binaries should be compatible back to the introduction of Apple Silicon M1. Earlier application packages have been compiled on OS X 10.7 64-bit (x86 archiracture, dated approx 2011) or even OS X 10.4 32-bit (dated approx 2006); see our archive.
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. As of libFAUDES 2.27, the library is compiled with MS Visual C++ 2015 compilers for 64-bit environments with Windows 7 as our test target. Allthough libFAUDES itself is not a Visual C++ project, dependend applications can be developed with the community edition of this particular version of MS Visual C++. Earlier distributions of libFAUDES were compiled for 32-bit using MinGW compilers and targeting Windows XP and can be found in our archive.
For all other system environments you need to use the standard libFAUDES distribution and re-compile. The required steps are described below.
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 are supported.
default to compile the library (either shared or static) and utility executables,
libfaudes to compile just the library (either shared or static),
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
./libFAUDES> make -j20 ./libFAUDES> make -j20 tutorial ./libFAUDES> make test
to re-compile libFAUDES. Technically, the GNU-make tool extracts the rules of how exactly the targets are to be built from the the Makefile. The option -j20 tells make to run up to 20 jobs in parallel which significantly speeds up the build process. 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 macOS GNU-make is part of the system toolchain and, thus, is 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-w64 project provides a variant of the GNU-toolchain toolchain for native MS Windows development and it includes a compatible make tool. The easiest way to get this going is to first install MSYS2 and then to obtain the GNU-toolchain within this environment; e.g., run the package manager from an MSYS2 terminal window:
pacman -S base-devel gcc
Then, explicitly set the target platform and compile libFAUDES from a MSYS2 terminal:
./libFAUDES> make -j20 FAUDES_PLATFORM=gcc_msys ./libFAUDES> make -j20 FAUDES_PLATFORM=gcc_msys tutorial ./libFAUDES> make FAUDES_PLATFORM=gcc_msys testAs an alternative to MSYS2, you can resort to a plain MinGW toolchain, set the PATH variable and use an MS Windows commandline to run
set PATH=%PATH%;C:\Wherever_MinGW_is\bin C:\libFAUDES> mingw64-make -j20 FAUDES_PLATFORM=gcc_win C:\libFAUDES> mingw64-make -j20 FAUDES_PLATFORM=gcc_win tutorial C:\libFAUDES> mingw64-make FAUDES_PLATFORM=gcc_win test
The provided Makefile supports five flavors to shape the build process.
The four platforms gcc_linux, gcc_osx, gcc_win and gcc_msys all refer to the GNU-toolchain (or close relatives LLVM/Clang). The corresponding tools can be obtained by the system packamanager (Linux), as part of the XCode developer tool (macOS) or via MSYS2 as indicated above (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 point for further tuning. Since libFAUDES is largely developped within gcc_linux and/or gcc_osx environments, it adapts well to the GNU-toolchain.
The fourth platform cl_win addresses the MS compiler cl.exe provided by MS Visual Studio. To use MS Visual C for the development of a libFAUDES based application, it is strongly recommended to compile libFAUDES with the same version of cl.exe as it will be used for application developement, an specically to do so with matching compiler/linker options. Among the vast number of precivable 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 tested to compile with the community edition of MS Vusial C 2015. From the MS Winddows commandline, run
call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86_amd64 > mingw64-make -j20 FAUDES_PLATFORM=cl_win FAUDES_LINKING="static debug"
The batch file provided by MS Visual C sets up the environment to the 64bit compilers. Then "FAUDES_LINKING="static debug" directs make to build the archieve faudesd.lib. While it links dynamically against the C libraries in their debug variant, faudesd.lib isitself is meant for static linking with an host application. Relevant compiler options are /MDd and /EHsc, in some cases /Zi may also be of interest. Note that applications 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
> mingw64-make -j20 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.
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/reference (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 or above for the luabindings plug-in), and
dist-clean to remove any non-source files.
Most Linux distributions come with Perl, doxygen and SWIG. The latter may require installation, e.g., for Debian
sudo apt install swig
Here, the particular version can be crucial --- we have positive confirmation ranging from v1.3.36 up to v4.1.1; cross-configuration for Windows/VS-compiler requires at least 3.02, however, the early 3.xx series seems to produce some spurious warnings with Linux/gcc. In the case you rely on older versions of SWIG, you may want to test the a tweaked versions of typemaps.i archieved as ./plugins/luabindings/src/ and taken from SWIG v2.0.10.
For development on a macOS system, there are various ways to obtain the required tools. As of libFAUDES 2.04, we use MacPorts to install SWIG and doxygen, e.g.,
port install swig doxygen
For development on a Windows system, we recommend to use either Cygwin or MSYS2 as close-to-POSIX environments. As of libFAUDES 2.32b, we are testing with MSYS2 version 20240113 on Windows 10. Required packages can be installed from a MSYS2 terminal window, e.g.:
pacman -S swig doxygen ncurses-devel libreadline-devel
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 edit the main Makefile to only eanable a minimal set of plug-ins. This will keep compilation times reasonably short. In particular, the luabindings plug-in depends on every single header file and the build process will recreate all luabindings from scratch when you edit any one header file.
libFAUDES uses doxygen as a professional tool to generate the C++ API documentation. However, 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 developers to (a) contribute to the user-reference to advertise their plug-ins 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 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>
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:
the attbribute chapter must be set to Reference, i.e. chapter="Reference";
for plug-ins, the attribute section should match the plug-in name; for the documentation of built-in functions, there is the reserved section CoreFaudes;
the attribute page identifies the reference page in the context of a section; it is recommended to compose the page attribute from a page number and a page label, e.g., page="2_Example"; each section must provide exacly one reference page with page="Index"; the corresponding source file must be named nameofsection_index.fref, where nameofsection is the name of the respective section;
the attribute title is set to a selcontained title that summarizes section and page, e.g., title="CoreFaudes - Index" for the index page for built-in functions.
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.
Page summary for annotated tables of contents: this element is recorded for later processing and swallowed when generating the usual HTML output (i.e., the provided summary will *not* be visible on the documentation page where is defined, but it is used for the table of contents, e.g. here). Example:
<fsummary> [ ... 2-3 lines of text for an index page ...] [ ... one line of text for other pages ...] </fsummary>
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_REFERENCE, FAUDES_LUAFAUDES 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>
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.
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.32b --- 2024.03.01 --- with "synthesis-observer-observability-diagnosis-hiosys-iosystem-multitasking-coordinationcontrol-timed-simulator-iodevice-luabindings-hybrid-example-pybindings"