Using SeqAn in CMake-based projects¶
Overview¶
CMake is a cross-platform build system generator where you describe different executables, binaries and their dependencies in CMakeLists.txt
files.
Then, CMake generates build systems such as Makefiles or Visual Studio projects from these files. This article describes only the most basic things about CMake in general and focuses on how to use SeqAn easily from within CMake projects.
In CMake projects, one uses modules to find libraries such as SeqAn. SeqAn ships with such a module.
In the following we assume that you have installed CMake on your operating system. If you have not yet, install it via the operating systems mechanisms (see also Setting up SeqAn) and/or download from the CMake homepage.
You should also have a valid C++-Compiler installed. Refer to the GitHub-README to see which compilers are currently supported.
A Running Example¶
Create a folder somewhere, e.g. ~/devel/my_project
and in it the following two files:
my_project.cpp
#include <iostream>
#include <seqan/basic.h>
#include <seqan/sequence.h>
#include <seqan/stream.h>
using namespace seqan2;
int main() {
std::cout << CharString("Hello SeqAn!") << std::endl;
return 0;
}
CMakeLists.txt
# Minimum cmake version
cmake_minimum_required (VERSION 3.12)
# Name of project and that it is C++ only.
project (my_project CXX)
# ----------------------------------------------------------------------------
# Dependencies
# ----------------------------------------------------------------------------
# Search for zlib as a dependency for SeqAn.
find_package (ZLIB)
# Load the SeqAn module and fail if not found.
find_package (SeqAn REQUIRED)
# ----------------------------------------------------------------------------
# Build Setup
# ----------------------------------------------------------------------------
# Add include directories.
include_directories (${SEQAN_INCLUDE_DIRS})
# Add definitions set by find_package (SeqAn).
add_definitions (${SEQAN_DEFINITIONS})
# Add CXX flags found by find_package (SeqAn).
set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${SEQAN_CXX_FLAGS}")
# Add executable and link against SeqAn dependencies.
add_executable (my_project my_project.cpp)
target_link_libraries (my_project ${SEQAN_LIBRARIES})
Building The Project¶
First you should create a build directory, i.e. for cmake-builds everything happens in a different directory, than in the source directory. In our case create the directory ~/devel/my_project-build
and in there a folder release
. More on why we use two levels here.
# mkdir -p ~/devel/my_project-build/release
# cd ~/devel/my_project-build/release
Cmake supports two different modes to load settings from an external project: The module and the config mode. Please read the cmake documentation to learn more about this feature.
Install SeqAn from package maintainer¶
The recommended way for SeqAn 2.3 or newer is to use the config mode.
If you installed/updated SeqAn from one of the downstream package maintainer listed in Getting Started with SeqAn, then a file called seqan-config.cmake
was installed in a system path that is automatically searched by the cmake system (see the cmake documentation for find_package).
If everything was done with default settings, than you can simply build your project like:
# cmake ../../my_project
Install SeqAn into user defined prefix or clone from GitHub¶
In case you obtained SeqAn from a git clone, or installed SeqAn into a user defined location, you need to specify the install location by setting the CMAKE_PREFIX_PATH
in your cmake call.
In addition you also have to specify the SEQAN_INCLUDE_PATH
variable to find the SeqAn headers.
Assume you have cloned SeqAn into ~/devel/seqan
, then your setup could look as the following:
# cmake ../../my_project \
-DCMAKE_PREFIX_PATH="$HOME/devel/seqan/util/cmake" \
-DSEQAN_INCLUDE_PATH="$HOME/devel/seqan/include"
Backwards compatibility¶
Before SeqAn 2.3 we used the module mode to setup SeqAn as an external project.
To allow backwards compatibility we added a redirect from the FindSeqAn.cmake
to seqan-config.cmake
in our sources.
In this case configuing your project with the old approach using the CMAKE_MODULE_PATH
variable, will still work:
# cmake ../../my_project \
-DCMAKE_MODULE_PATH="$HOME/devel/seqan/util/cmake" \
-DSEQAN_INCLUDE_PATH="$HOME/devel/seqan/include"
Tip
Depending on your setup you might need to manually choose a more modern compiler! Please read this page for more information on configuring CMake builds. Don’t forget to clean your CMake build directory after changing the compiler!
Finally you can then build the application by calling
on Makefile-based builds (Linux/Mac/BSD):
# make
Windows
# cmake --build .
The above step is the only step you need to repeat when changing your source code. You only have to run CMake again, if you have changed the CMakeLists.txt
.
You can then execute the application in the usual way
on Makefile-based builds (Linux/Mac/BSD):
# ./my_project
Windows
# my_project
Using IDEs¶
On Linux and BSD many IDEs directly support cmake, just open/import the CMakeLists.txt
with e.g. KDevelop or QtCreator.
To use XCode on Mac with your CMake-based project, add -G Xcode
to the cmake call above and then run open TODO
.
On Windows a Visual Studio generator is used by default and you will find a .vcxproj
in the source directory that you can open with Visual Studio.
See this page for more details.
Checking for newer Versions of SeqAn (optional)¶
The argument parser has a new feature to check for updates for the SeqAn library or for an application. This can be a very helpful reminder to stay up to date since SeqAn evolves rapidly to resolve issues or to supply new functionality. If none of the following options are selected the version update feature is activated by default.
Cmake Option
Description
-DSEQAN_VERSION_CHECK_OPT_IN
Turn update feature on but make it opt-in.
-DSEQAN_DISABLE_VERSION_CHECK
Turn update feature off.
Note
This does only affect applications or scipts that use the SeqAn Argument Parser!
Details of the SeqAn Module¶
As mentioned above, this line is the important line for including SeqAn:
find_package (SeqAn REQUIRED)
If SeqAn is only an optional dependency of your program, you can omit the REQUIRED
keyword. In this case you should check the contents of the SEQAN_FOUND
CMake-variable and depending on that configure your build, e.g. with custom Macros.
You can also check for the definition of SeqAn’s version macros from within your code:
SEQAN_VERSION_STRING
Concatenated version string,
${SEQAN_VERSION_MAJOR}.${SEQAN_VERSION_MINOR}.${SEQAN_VERSION_PATCH}
SEQAN_VERSION_MAJOR
Major version.
SEQAN_VERSION_MINOR
Minor version.
SEQAN_VERSION_PATCH
Patch-level version.
Dependencies¶
SeqAn itself has some optional dependencies. Certain features in SeqAn will be enabled or disabled, depending on whether the dependencies could be found.
Caution
Optional dependencies of SeqAn have to be searched before the SeqAn module is searched!
Currently, the following dependencies enable optional features:
ZLIB
zlib compression library
BZip2
libbz2 compression library
OpenMP
OpenMP language extensions to C/C++
An example of where you only want ZLIB and OpenMP support, but not BZip2, would look like this:
find_package (ZLIB)
find_package (OpenMP)
find_package (SeqAn)
From within CMake you can check the variables ZLIB_FOUND
or OpenMP_FOUND
to see the results of these dependency searches, but you can also use the following macros from within your source code to escape certain optional code paths:
SEQAN_HAS_ZLIB
TRUE
if zlib was found.SEQAN_HAS_BZIP2
TRUE
if libbz2 was found._OPENMP
TRUE
if OpenMP was found.
CMake build variables¶
As can be seen from the example above, the following variables need to be passed to include_directories()
, target_link_directories()
, and add_definitions()
in your CMakeLists.txt
:
SEQAN_INCLUDE_DIRS
A list of include directories.
SEQAN_LIBRARIES
A list of libraries to link against.
SEQAN_DEFINITIONS
A list of definitions to be passed to the compiler.
Required additions to C++ compiler flags are in the following variable:
SEQAN_CXX_FLAGS
C++ Compiler flags to add.
Caution
Please note that these variables include whatever has been added by the dependencies mentioned above so do not add e.g.
${OpenMP_CXX_FLAGS}
yourself!
Intel Compiler specifics¶
The Intel Compiler does not ship a c++ standard library on its own and will use the one pre-installed on the system (e.g., the one from g++). This can be a problem [especially for cluster users through the use of a module system], if the standard library by a default g++ installation is to old.
Please check with the following command which g++ version is being used and make sure it matches the supported gcc versions.
# icpc -v
icpc version 17.0.2 (gcc version 5.4.0 compatibility)
If you have multiple g++ installations, you can choose the standard library by
icpc -gxx-name=g++-5.4.0 -gcc-name=gcc-5.4.0 …
. Use
cmake -DCMAKE_CXX_FLAGS="-gxx-name=g++-5.4.0 -gcc-name=gcc-5.4.0" …
to propagate those options through cmake.
You may have to add the path of the library to `$LD_LIBRARY_PATH
for the
linker.
Static builds¶
If you want to build your app statically, please do not use gcc-4.9 or make sure you add the -static
flag before calling find_package (SeqAn)
. Otherwise a broken binary will be built that crashes immediately.