The SeqAn Repository

This article describes the SeqAn repository structure and how to work with full SeqAn sources.

Getting Started

We assume that you have read Installing SeqAn and have cloned or unzipped the full SeqAn sources to ~/devel/seqan (not the “library sources” described in other places).

SeqAn supports the usual CMake build types and we recommend using multiple build directories. Start like this:

# mkdir -p ~/devel/seqan-build/release
# cd ~/devel/seqan-build/release
# cmake ../../seqan -DCMAKE_BUILD_TYPE=Release

In addition to CMAKE_BUILD_TYPE there is also the SEQAN_BUILD_SYSTEM parameter which can be one of

  1. DEVELOP – all build targets (apps, demos, tests) and documentation (dox, manual) are created (the default).

  2. SEQAN_RELEASE_LIBRARY – only dox and library targets are created.

  3. SEQAN_RELEASE_APPS – all app targets are created, but nothing else.

  4. APP:$APPNAME – only a single app target is created for the chosen app.

All build systems other than DEVELOP are only relevant to packaging releases.

As usual, calling make $TARGET will build a single target and just make will build all targets. On Windows, run cmake --build . --target $TARGET or just cmake --build instead.

Overview

The main repository structure is shown in the following picture.

seqan
  |-- CMakeLists.txt    CMake script file.
  |
  |-- LICENSE           Top-Level Information Files
  |-- README.md
  |
  |-- apps              Applications
  |
  |-- demos             Demos
  |
  |-- dox               API documentation system
  |
  |-- include/seqan     SeqAn header ("the library")
  |
  |-- manual            Manuals
  |
  |-- tests             Unit tests for library modules
  |
  `-- util              Miscellaneous and Utility Code

The repository root contains some information files such as the LICENSE and README.md. The other folders are as follows:

apps

The apps folder contains many applications, and each application directory contains one CMakeLists.txt file and the files for compiling at least one binary. Usually, apps have tests, too. In this case, there is a subdirectory tests. Writing application tests is covered in detail in the article Writing App Tests.

The general structure of an app is as follows:

seqan/apps/razers
  |-- CMakeLists.txt      CMake script file
  |
  |-- README              Documentation and License Files
  |-- LICENSE
  |
  |-- example             Small Example Files
  |     |-- genome.fa
  |     |-- reads.fa
  |     `-- ...
  |
  |-- razers.cpp          Source Files for Executables
  |-- razers.h
  |-- ...
  |
  `-- tests               App Tests Files

Note that some applications have binary names (make targets) that are not identical to the app-name, e.g. yara has yara_mapper and yara_indexer.

demos

The demos are short programs and code snippets that are used in the dox or the manual. They serve as small examples and also functions as additional unit tests.

dox

The SeqAn API documentation is created using a customly-written system called dox. It is very similar to doxygen, you can find out more about the syntax in API Documentation System (dox).

You can build the documentation in the dox subfolder of the source folder:

~   # cd ~/devel/seqan/dox
dox # ./dox_only.sh

This will build the documentation into the sub directory html.

include/seqan

This is the actual library consisting of multiple modules:

include/
  |-- seqan/
  |     |-- basic/                       Library Module basic
  |     |     |-- aggregate_concept.h
  |     |     |-- debug_test_system.h
  |     |     `-- ...
  |     |-- basic.h
  |     |
  |     |-- sequence/                    Library Module sequence
  |     |-- sequence.h
  |     |
  |     `-- ...                          Other Library Modules

On the top level, there is the folder seqan that contains the library modules. Inside the folder seqan, there is one directory and one header for each module.

The folder <module-name> contains the headers for the module module-name. The header <module-name>.h includes the headers from the module module-name. Including the header makes the code in the module available.

Note

Header only library

Remember that SeqAn is a template library that consists entirely of headers. No build steps are required for building the library and no shared objects will be created.

manual

The SeqAn manual is created using the Sphinx documentation system.

Follow these instructions to set up a local sphinx environment and build the manual:

$ virtualenv ~/seqan-manual-env
$ source ~/seqan-manual-env/bin/activate
(seqan-manual-env) $ cd ~/seqan/manual
(seqan-manual-env) $ pip install -r requirements.txt
(seqan-manual-env) $ make html

Note that you have to first build the dox documentation since plugins for generating the :dox: links rely on the generated search index for checks. In order to get correct dox-links within the generated manuals, you have to specify the correct branch version. If you are working on the main branch there is nothing to do, since 'main' is set by default.

(seqan-manual-env) $ export READTHEDOCS_VERSION='main'

before you call make html as described in the previous step. This will generate the correct links to the main version of the dox, i.e., https://docs.seqan.de/seqan/main/

tests

The folder tests contains the unit tests for the library modules.

For each library module, there is a directory below tests with the same name that contains the tests for this module. Simpler modules have one tests executable, whereas there might be multiple tests executables for larger modules. For example, the module index has multiple test programs test_index_qgram, test_index_shapes etc. Writing tests is explained in detail in the article Writing Unit Tests.