|
|||
|
|
|
|||
|
|
OGDF » Developer's Guide » Build Guide
The OGDF build configuration is generated using CMake.
CMake is a meta-build system that will generate your actual build system. The most common build systems include Unix Makefiles, Visual Studio project files, and XCode project files. We refer to Running CMake for extensive information on using CMake.
Note that CMake allows you to place the generated build system in a separate folder, thus allowing several parallel build configurations (called out-of-source builds). We recommend following this approach.
All of the examples cover unix systems. On windows, CMake provides a self-explanatory graphical user interface.
We assume that the directory ~/OGDF contains a clone of this repository. In each of the examples we are initially located in the home directory ~.
CMake will present you with several options for configuring your build. All of these options are explained by the CMake interface.
This will generate the default build system inside the OGDF directory. Such a configuration is sufficient if you want to compile the Library with a single configuration only.
Assuming your system supports Unix Makefiles you could now start the actual build: Note that invoking make with the -j flag will execute jobs in parallel thus speeding up your build.
If the compilation of your code results in an error containing -Werror or C2220, change the default configuration using
and retry building the project.
An out-of-source build does not modify the source directory. Thus, generating a second out-of-source build will not create any conflicts with the previous one.
Note that the documentation is always built in-source.
Creating multiple build configurations is of no use if the configurations do not differ. Run ccmake instead of cmake to modify the build configuration before generating the build system.
This includes the specification of the linear program solver, whether to include OGDF specific assertions (and how to handle them), additional include directories, and the likes. Running ccmake also allows you to specify the compiler, linker and the respective flags. Note that the availability of some options may depend on other configuration values.
OGDF code has a lot of extra assertions in its code, partly adding running time. These assertions are only activated in debug mode and if the advanced option OGDF_DEBUG_MODE is either set to REGULAR (it is by default) or HEAVY (even more assertions). The assertions (plus a backtrace of the calls) might be very valuable and helpful for debugging (user) code.
There are two modes how failed assertions are handled.
If OGDF_USE_ASSERT_EXCEPTIONS is turned off (default), an assert() call exits the program. Note that enabling this might hide failed assertions when catch (...) is used. You can get a call stack trace if the program was invoked with a debugger (which is part of many IDEs).
If turned on, an ogdf::AssertionFailed exception is thrown instead. The informational string returned by the what() method contains the failed expression, its source code file, line, and function. By also setting the OGDF_USE_ASSERT_EXCEPTIONS_WITH_STACK_TRACE variable to ON_LIBDW (if libdw is installed, recommended), ON_LIBBFD (if libbfd from binutils is installed), or ON_LIBUNWIND (if libunwind is installed), a stack trace will be part of the exception's what() return string. As far as we know, this feature only works on Linux.
System-wide installation of OGDF is supported through the standard mechanisms provided by CMake. This support, however, is not thoroughly tested and may change in the future.
Current limitations are that Debug and Release installations are not supported at the same time. We also do not provide version information at the moment.
When you want to build user code that uses OGDF, you have to take care of the correct include paths. You should use <OGDF build directory>/include and <OGDF source directory>/include as include paths, and your OGDF build directory as library path. In case of an in-source build, the build and source directories coincide. It is not supported to have in-source and out-of-source builds at the same time. In case you want to remove an in-source build entirely, do not forget to remove the file include/ogdf/basic/internal/config_autogen.h.
If you are running into linking errors, undefined behavior or crashes at runtime, a typical mistake is that OGDF and user code is compiled in different modes (like Debug mode and Release mode). To make sure that your configuration is correct, you might use the file examples/special/check-build-mode.cpp and try to compile it using your configuration.
On Unix systems, typical compilation and linkage of user code would look like this:
Since OGDF uses CMake, it is convenient for you to use CMake, too. The file examples/special/CMakeLists.txt contains a basic configuration to start with.
