The CompileDES project was originally designed to serve as a template for libFAUDES applications and to document the steps required for the build process. While libFAUDES itself largely consists of platform independent C++ code, the build process is quite involved and naturally depends on the choice/availability of compilers, linkers and the operating system.
We provide a complete run-through for the CompileDES project. Relevant files are
./src/*.h sources of CompileDES, C-headers ./src/*.cpp sources of CompileDES, C-code ./src/doxygen* doxygen configuration for HTML-documentation ./doc/* HTML-documentation produced by doxygen ./examples/* test data for CompileDES ./libfaudes_sources/* minimally configured libFAUDES ./libfaudes_linux/* ... pre-compiled for Linux ./libfaudes_win/* ... pre-ompiled for Windows ./libfaudes_osx/* ... pre-compiled for Mac OsX ./bin/* pre-compiled binaries for Linux/OsX/Windows ./Makefile_GnuMake plain Makefile to build with the GNU-toolchain ./CompileDES_QMakeProjekt.pro project file to build with Qt IDE Creator ./CompileDES_Msvc2015Project.vcxproj project file to build with MS Visual C 2015 IDE
For those familiar with either choice of plain GNU-Makefiles, the Qt Creator IDE or the MS Visual IDE, just go ahead, inspect the respective project file and build CompileDES. Note that, for simplicity, the pre-compiled libFAUDES distributed with this package uses static linking in deployment mode. If you require a different style of linking or if you experience any errors during linkage please read the detailed instructions below.
The CompileDES project statically links to a pre-compiled copy of libFAUDES, provided in three flavours for convenience. This section documents how the copies have been obtained from the libFAUDS source distribution. Follow these instructions in order to compile a copy of libFAUDES tailored to your needs.
To prepare, download and extract libFAUDES sources libfaudes-x_yz.tgz to reside within the project directory, say in
./compiledes/libfaudes_source/*
Instructions to build libFAUDES are provided in the online documentation; see libFAUDES->Developer->Build-System. The process is organised in two consecutive stages.
libFAUDES can be configured to include specific plug-ins and to control the run-time behaviour like progress report and the level of warning messages. However, libFAUDES configuration requires servels tools form the Unix domain to be available on your system. Therefore the standard source distribution of libFAUDES is preconfigured to include all plug-ins and to exhibit a sensible level of verbosity.
For documentation purposes the particular configuration for the copy included with CompileDES has been generated by the script copyfaudes.sh (functional for Linux/MacOsX environments). The configuration includes specific plug-ins as required for the CompileDES project. If you are happy with this configuration, you can use the sources ../compiledes/libfaudes_source provided with the CompileDES package as a slim alternative to the complete libFAUDES source distribution.
Once libFAUDES sources are configured they can be compiled using the provided GNU-Makefile. This requires the specific GNU-Make tool on your system, regardless whether the application development later on uses the GNU-tool chain. Inspect the libFAUDES Makefile with a text editor. There are two relevant switches for compilation, namely FAUDES_PLATFORM and FAUDES_LINKING.
FAUDES_PLATFORM adapts the build process to the toolchain and to the operating system, prominent choices being gcc_linux, gcc_osx and cl_win. FAUDES_LINKING selects static vs dynamic linking and debug vs release C-libraries. For application development static debug is the choice to go.
Example command-line to build with Linux or Mac OS X using the nominal system toolchain
~/compiledes> make -C libfaudes_source FAUDES_LINKING="static debug" clean ~/compiledes> make -C libfaudes_source FAUDES_LINKING="static debug"
or, on MS Windows with MS Visual C and MinGW mingw32-make
C:\compiledes> set PATH=%PATH%;C:\MinGW\bin C:\compiledes> call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86_amd64 C:\compiledes> mingw32-make -C libfaudes_source LINKING="static debug" clean C:\compiledes> mingw32-make -C libfaudes_source LINKING="static debug"
The resulting compiled libFAUDES is included with the CompileDES project in the three flavours lsb_linux, gcc_osx and cl_win. If your toolchain is a close enough relative of either flavour, the pre-compiled libFAUDES is fine to continue with the CompileDES project. In general, it is recommended to recompile.
There are several choices for the organisation of a C++ application project. For the CompileDES, the provided sources are located in
./compiledes/src/*.h ./compiledes/src/*.cpp
We provide some directions on how to build ComplieDES with a particular focus on how to link it with libFAUDES.
A Makefile is a specialised form of a script to organise a build process and to document dependencies. The make tool, as used for the compilation of libFAUDES discussed above, will conclude from the Makefile how compilers and linkers need to be invoked in oder to build the application.
The CompileDES project comes with a Makefile in the GNU-make dialect. It has been verified to be functional for Mac OsX and Linux. In particular, it uses the same nominal system compiler/linker that was used when compiling libFAUDES by the above instructions. The provided Makefile links CompileDES statically with libFAUDES and thereby matches the local copy of libFAUDES prepared for this purpose.
To build CompileDES, run
./compiledes> make -f Makefile_GnuMake
and check for the executable compiledes in ./build. Adaption to other make dialects (e.g. nmake from MS Visual Studio) is straight forward, except of course that one needs to know about ones toolchain and its options. If you feel that managing makefiles is somewhat cumbersome and spoils the platform independence of your application, read ahead for a modern variation of textual build process specifications.
The platform dependent aspects of a Makefile can be equalised by various automatic Makefile generators using an abstract specification of how the application should be built. One such tool is qmake, provided by the Qt project. It is available for all major platforms, including one-click installers for Linux, MacOsX and MS Windows.
The CompileDES project comes with the qmake project file CompileDES_QMakeProject.pro which can be processed by qmake to generate a Makefile that matches the environment specific dialect and that considers other platform dependent details. Compared with a native Makefile, a qmake project file can be organised to be much less complex, basically specifying the project type and the list of sources. The only libFAUDES specific lines are the extra include path and the directions to statically link with libFAUDES.
./compiledes> qmake CompileDES_QMakeProject.pro
will generate Makefile_by_QMake which in turn builds the application.
As with the plain Makefile discussed above, qmake will use "the native C compiler" for Mac OsX and Linux. This should match the compiler in the system path and therefore is the same one as picked up by the libFAUDES build system. In consequence,
./compiledes> make -f Makefile_by_QMake
should faithfully build CompileDES. Check for the executable compiledes in ./build.
For MS Windows, Qt is available for different toolchains, including MS Visual C in editions 2011, 2012 or 2015, as well as MinGW gcc in 32bit and 64bit variants. These compilers are compatible only to a very limited degree. As outlined above, it is crucial to use a copy of libFAUDES that has been compiled with the same toolchain as the one used for application development. This affects in particular compiler switches used when building in debug mode. The general advice here is to observe the relevant tools, compiler switches and linker options that qmake chooses to build the application. If the final linking step fails, do not be confused by experts-only error-reports. Simply go back and compile libFAUDES in the same fashion and with the same options. A prominent example here is the linkage style to the std-c-libraries by the options /MDd, /MD, /MT or /MTd for the MS Visual C compiler — any mismatch will break linking with libFAUDES (which by default uses /MD or, with FAUDES_LINKING set on debug, /MDd, which we believe is a sensible choice as of MS Visual C 2015).
Example command line to build CompileDES for MS Windows
C:\compiledes> qmake CompileDES_QMakeProject.pro C:\compiledes> nmake /F Makefile_by_QMake
The Qt project also provides an integrated development environment (IDE) called Creator. To use the IDE, open the provided qmake project file and click on the build button. If the build fails due to "can not find libfaudes.a" uncheck "shadow build" or manually copy the provided libfaudes.a to the relevant build directory.
To run (and/or debug) compiledes from within Creator, use Creator->Projects->Run-Settings to provide command line arguments and to specify the working directory. The CompileDES hello-world example is invoked by
./compiledes> ./build/compiledes -t atm examples/blink/blink_atm.cgc".
Creator can also be used to generate projects from scratch, avoiding the textual project description altogether. For the CompileDES project one may alternatively get started by creating a project "CompileDES" by the new-project wizard
Creator->New-Project->non-Qt-project->Plain-C++-project
This creates a folder CompileDES and a template source main.cpp.
To direct Creator to the location of libFAUDES, use
Creator->CompileDES->Context-Menu->Add-Library
and choose "add external library" to specify libfaudes.a (Linux/MaxOsx) or faudes.a (MS Windows) and set ./libfaudes_xxxx/include as the include path; if you prefer all relevant files to be within the CompileDES folder, you should move them there beforehand.
Finally, add the CompileDES sources by
Creator->CompileDES->Context-Menu->Add-Existing-Files
and remove the automatically generated template main.cpp; again, you may opt for copying your sources to be located within the CompileDES folder.
The steps required here are essentially the same as for Creator, except that the details are a bit more involved. Let MS Visual C generate a new "Console C++" project, use "Project Properties" to direct MS Visual C to libFAUDES and dump in your sources.
In order to be able to build in MS Visual C debug-mode, libFAUDES must have been compiled with the /MDd option; see discussion above. If you want to be able to debug into libFAUDES, you also need /ZI. Be aware, /ZI will need a substantial amount of disk space for debugging information.
The code-generator project comes with the MS Visual project file CompileDES_MsVcProject.pro which has been configured to
faudes.lib in libfaudes_winlibfaudes_win/includewinmm.lib and wsock32.libRegarding CompileDES, which is distributed under terms of the GPL, derived work can only be distributed as GPL open source. If you require access to CompileDES under different terms, please let us know, this can be arranged. If you want to distribute your own libFAUDES-based project as closed source and/or commercially, configure libFAUDES to include only the LGPL plug-ins and make sure to use dynamic linking (!). There are some further administrative requirements which can be met easily — check the provided license file.