This page contains information about how to set up and use genesis.
Genesis is a C++11 library, which can be used in other C++ projects. It is however also possible to use its stand-alone features, e.g. for running Demos and Apps.
Currently, we test and use Genesis on Linux and macOS systems. It is currently tested with Ubuntu 14.04, 16.04, and 18.04, as well as all macOS (OS X) versions starting from 10.10 (Yosemite) up to 10.14 (Mojave). If you are using a different operating system, you can either try yourself, or use a virtual machine. Please report any issues, questions or solutions to our Google Group.
Genesis is open source software under the GNU GPL v3 license.
To get the source, you can download the latest release.
Alternatively, in order to stay up to date, you can clone the repository. For this, you need to have Git installed. Then, call
git clone https://github.com/lczech/genesis.git
in some directory. This will create a sub-directory genesis
, containing all files. In case new commits are pushed to the GitHub repository, you can call
git pull
from within the genesis
directory to get them. Don't forget to build Genesis again after pulling (see next section for details). We recommend this method, as this is the easiest way to get new features, bug fixes etc.
Furthermore, if you want to contribute code of your own, you can also fork the project on GitHub.
In the stand-alone variant, to build all of Genesis, call
make
in the main directory. This builds all parts of Genesis for which the dependencies are fulfilled.
Requirements:
For details, see the Build Process page.
Optional:
genesis/test
directory for more information.If you just pulled new commits from the repository, or added new files to be compiled (either an app, some lib function, or tests), you can call
make update
to include those files without need for recompiling everything (a so-called incremental build). See Build Process for more information on incremental builds.
The genesis/apps
directory is provided for conveniently and quickly developing small C++ applications which use Genesis as their main library. This is a way of using C++ similar to a scripting language. Thus, it is useful if you want to try out the Tutorials and Demos or if you quickly want to test an idea or get some experience with Genesis. Using those apps is the main purpose of the stand-alone variant of Genesis.
To create a new application, create a *.cpp
file in the genesis/apps
directory and provide it with a main function:
Include all needed headers (or, for simplicity, the genesis.hpp
header like above, which includes all of Genesis) and write the desired functionality. Of course, you can use other local functions in addition to the main function in order to structure your code.
The app is automatically compiled by the main build process and linked against the shared library version of Genesis by calling
make update
in the main directory. The resulting executable is placed in genesis/bin/apps
and named after the *.cpp
file (without the ending).
Apart from that, there are no further requirements. Simply include the needed genesis headers (or any other headers you might need) and compile. Happy coding!
The only limitation of using Apps is that everything has to be in a single compilation unit. Thus, additional headers work, but linking against the build output of other .cpp
files does not work. For this, you'd have to start a normal project that links against Genesis, instead of using the Apps.
The apps are only a convenience for users. Genesis can of course also be used like any other C++ library by including its headers and linking against its binaries.
If you include Genesis in bigger projects which are separately compiled, you need to make sure to use compatible options for compiling the Genesis binaries. For example, if you want to link against the shared library, the settings for threads (e.g., Pthreads, OpenMP) should to be the same for every compilation unit. See the main Cmake script for the available compiler options.
The easiest way to use Genesis as a library is via the CMake add_subdirectory
command. In your main CMakeLists.txt
, use:
Genesis internally uses some specialties that might lead to trouble if not taken care of, e.g. Pthreads and OpenMP (if they are available). Thus, it is best to also offer the needed flags to your binary, too. In case that Pthreads or OpenMP are not used/found, those variables are empty. In case they are used by Genesis, but not your program, nothing bad happens. So better make them available to the compiler:
After this setup, you can add your executables/libraries in CMake as usual (e.g, via add_executable
and add_library
). Then, for each target that uses Genesis:
This links against the static version of Genesis, which should be the most common use case when using Genesis as a dependency/library. See Shared vs Static Library for details.