Learning Objective:
In this short guide you will learn how to set up SeqAn and how to compile a small example to test whether everything works.
Difficulty | Easy |
Duration | 30 Minutes |
Prerequisite tutorials | No prerequisites |
Recommended reading | |
Software
Requirements:
- gcc >= 11
- cmake >= 3.5
- git
Installing GCC
SeqAn requires GCC >= 11. Current versions of LLVM/Clang and VisualStudio/MSVC are not yet supported. We will briefly explain how to install GCC-11 (or the latest GCC if such an option is available) on some popular operating systems. We recommend using the latest version of GCC available. For more information, refer to your operating system's documentation.
Linux
- Ubuntu >= 22.04
# Installs default compiler version (gcc-11 for Ubuntu 22.04).
sudo apt install g++
# To install gcc-12, follow instructions for Ubuntu < 22.04.
- Ubuntu < 22.04
sudo add-apt-repository --no-update --yes ppa:ubuntu-toolchain-r/ppa
sudo add-apt-repository --no-update --yes ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt install g++-11
- Using conda To avoid interference with system packages, we recommend creating a new environment when using conda.
conda create -n conda_gcc_env -c conda-forge gcc_linux-64
conda activate conda_gcc_env
This will put GCC in a separate environment conda_gcc_env
which can be activated via conda activate conda_gcc_env
and deactivated via conda deactivate
.
macOS
- Using Homebrew
- Using Macports
Windows
The Windows Subsystem for Linux offers an easy way to run a Linux distribution under Windows. Follow Microsoft's setup guide to install WSL and then follow the steps listed for Linux-based systems.
Browser
- Using gitpod.io gitpod.io allows you to edit, compile and run code from within your browser. The free version includes 50 hours of use per month, which is plenty for our tutorials. A GitHub account is required. Click here to open SeqAn3 in gitpod.
- Using GitHub Codespaces GitHub Codespaces offer a service similar to gitpod, including a free monthly quota. Click here to open SeqAn3 in Codespaces.
- Attention
- After installing,
g++ --version
should print the desired GCC version. If not, you may have to use, for example, g++-11 --version
or even specify the full path to your compiler.
Similarly, you may need to install CMake and git, e.g. apt install cmake git
.
Directory Structure
In this section we will use the tree
command to show the directory structure. This program may not be installed on your system. If so, you may wish to install it or verify the directory structure in other ways, e.g. by using ls -l
.
For this project, we recommend following directory layout:
tutorial
├── source
├── build
└── seqan3
To set these directories up you can follow this script:
mkdir tutorial
cd tutorial
mkdir build
mkdir source
git clone https://github.com/seqan/seqan3.git
The output of the command tree -L 2
should now look like this:
.
├── build
├── seqan3
│ ├── CHANGELOG.md
│ ├── CMakeLists.txt
│ ├── ...
│ └── test
└── source
8 directories, 6 files
Compiling and Running
To test whether everything works, we will now compile and run a small example.
First we create the file hello_world.cpp
in the source
directory with the following contents:
int main()
{
return 0;
}
Provides seqan3::debug_stream and related types.
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:37
To compile it, we first create a CMakeLists.txt
file in the source
directory:
cmake_minimum_required (VERSION 3.5...3.30)
project (seqan3_tutorial CXX)
# add seqan3 to search path
list (APPEND CMAKE_PREFIX_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../seqan3/cmake")
# require seqan3 with a version between >=3.0.0 and <4.0.0
find_package (
seqan3 3.0 REQUIRED)
# build app with seqan3
add_executable (hello_world hello_world.cpp)
target_link_libraries (hello_world seqan3::seqan3)
The main SeqAn3 namespace.
Definition aligned_sequence_concept.hpp:26
The directories should now look like this:
.
├── build
├── seqan3
│ ├── CHANGELOG.md
│ ├── CMakeLists.txt
│ ├── ...
│ └── test
└── source
├── CMakeLists.txt
└── hello_world.cpp
Now we can switch to the directory build
and run:
cmake -DCMAKE_BUILD_TYPE=Release ../source
make
./hello_world
The output should be Hello World!
. Note that the build type is specified with -DCMAKE_BUILD_TYPE=Release
. Specifying Release
enables an optimized build where no debug information is available. Release mode is therefore suitable for the end user. Programs built using -DCMAKE_BUILD_TYPE=Debug
will run slower, but also make the detection of errors easier. Debug
is suitable for contributors, and we recommend using it while working with our Tutorials.
Adding a new source file to your project
If you create a new cpp
file and want to compile it, you need to add another add_executable
and target_link_libraries
directive to you CMakeLists.txt
. For example, after adding another_program.cpp
your CMakeLists.txt
may look like this:
cmake_minimum_required (VERSION 3.5...3.30)
project (seqan3_tutorial CXX)
# add seqan3 to search path
list (APPEND CMAKE_PREFIX_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../seqan3/cmake")
# require seqan3 with a version between >=3.0.0 and <4.0.0
find_package (
seqan3 3.0 REQUIRED)
# build app with seqan3
add_executable (hello_world hello_world.cpp)
target_link_libraries (hello_world seqan3::seqan3)
add_executable (another_program another_program.cpp)
target_link_libraries (another_program seqan3::seqan3)
Including SeqAn3 as external project
cmake_minimum_required (VERSION 3.14...3.30)
project (my_app LANGUAGES CXX VERSION 1.0.0)
set (seqan3_git_tag "#.#.#") # adapt as needed, e.g. "3.2.0" or "main"
message (STATUS "Fetching SeqAn3 ${seqan3_git_tag}:")
include (FetchContent)
FetchContent_Declare (
seqan3_fetch_content
GIT_REPOSITORY "https://github.com/seqan/seqan3.git"
GIT_TAG "${seqan3_git_tag}"
)
# Download and make SeqAn3 available.
FetchContent_MakeAvailable (seqan3_fetch_content)
add_executable (my_app my_app.cpp)
# Set up everything needed to use SeqAn3 with my_app:
target_link_libraries (my_app PUBLIC seqan3::seqan3)
Encountered issues
- Using conda's gcc package:
/usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'CXXABI_1.3.11' not found
Try setting LD_LIBRARY_PATH
: export LD_LIBRARY_PATH=<conda_install_path>/envs/conda_gcc_env/lib/
where <conda_install_path>
must be replaced by the path yo your conda installation.
Usually this corresponds to the path printed by conda info --base
and may look similar to /home/user/miniconda3/
.
- Assembler not found:
... could not understand flag m ...
Try adding /usr/bin
to your PATH
: export PATH=/usr/bin:$PATH
and run cmake
again.
- Incorrect compiler:
Your compiler is not supported.
or Only GCC is supported.
The incorrect compiler is used (e.g., Apple Clang instead of GCC). Be sure to set -DCMAKE_CXX_COMPILER=
. For an example, see this remark.