This article describes the SeqAn repository structure. After reading it, you will have knowledge about the repository structure and the reasons for the design decisions.
Note that this article describes the structure of the Subversion repository, not the structure of the release version of SeqAn which you can download as a ZIP archive.
The main repository structure is shown in the following picture.
seqan |-- CMakeLists.txt CMake script file. | |-- GETTING_STARTED |-- LICENSE Top-Level Information Files |-- README | |-- core Core Area | |-- extras Extras Area | |-- sandbox Sandboxes Area | |-- docs Documentation System |-- docs2 | |-- misc Miscellaneous and Utility Code `-- util
- The repository root contains some information files such as the LICENSE, README, and GETTING_STARTED files. The file names should speak for themselves.
- The folder core contains the core area with apps, tests, and library modules that are (1) stable and (2) of general interest. Furthermore, it contains demos for the library modules in the SeqAn core.
- The folder extras contains the extras area with apps, tests, and library modules that are either (1) not stable enough yet or (2) of special interest only, as well as demos for the SeqAn extras library modules.
- The folder sandbox contains the sandbox area. Users can create their own user areas inside this folder as described in the section Sandboxes.
- The folders docs and docs2 contain the scripts for the documentation system. At the moment, there are two concurrent documentation systems. In the midterm future, we aim to replace this by one new documentation system.
- The folders misc and util contain miscellaneous files and utility code. For example the Code Generator Python scripts are located here as well as SeqAn logo image files and CMake modules.
The core area is structured as follows. Note that we generally refer to such a structure as a repository below.
seqan/core |-- CMakeLists.txt CMake script file | |-- apps Applications | |-- demos Demo Programs | |-- include SeqAn Library Modules | `-- tests Tests for Library Modules
- The apps directory contains applications. Each application directory contains the source files for one or more binaries, documentation, example files, and app tests. More information is available in the section Application Structure.
- The demos directory contains demo programs. The CMakeLists.txt file in this directory is written such that each file ending in .cpp is compiled into an executable with default SeqAn flag options.
- The include directory contains library modules. This is described in more detail in the section Library Modules.
- The tests directory contains tests for 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 Tests.
Each application directory contains one CMakeLists.txt file and the files for compiling 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
The library modules area looks as follows:
seqan/core/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.
The extras area has the same “repository” structure as the core area. The main difference is that it contains code that is not stable enough or not of general interest.
The sandbox area is a location where users can place their own repositories (i.e. directory trees having the same structure as the core and extras area) into. Currently, the sandboxes are also stored in the SeqAn SVN repository but that will change in the near future. Sandboxes can be generated using the skel.py Code Generator.
The following example shows how to create a user sandbox in the sandboxes area in an already existing Subversion repository. We assume that https://svn.example.com/trunk is an empty directory in a Subversion repository.
seqan # cd sandbox sandbox # svn co https://svn.example.com/trunk sandbox_example ... sandbox # cd .. seqan # ./util/bin/skel.py --force repository sandbox/sandbox_example
Next, we can create an application from a simple template in this sandbox:
seqan # ./util/bin/skel.py app first_app sandbox/sandbox_example
Finally, commit this new sandbox into your Subversion repository:
seqan # cd sandbox/sandbox_example seqan # svn add * ... seqan # svn commit -m "Initial sandbox structure with one app." ...
Note that for the Subversion repository containing sandboxes, we recommend the following layout. Using the classic SVN trunk, tags, branches structure allows for tagging releases or points of returns. Furthermore, you can create folders parallel to those for documentation (for example a folder slides parallel to trunk) without polluting your repository structure:
Subversion repository root |-- trunk | |-- CMakeLists.txt | |-- apps | |-- demos | |-- include | `-- tests |-- tags `-- branches
The folders docs and docs2 are used for building the documentation with the old and the new documentation system. You can build them by going into the directory and then calling ./make.sh. This will build the documentation into the sub directory html:
seqan # cd docs docs # ./make.sh ... seqan # cd ../docs2 docs2 # ./make.sh ...
If you want to include documentation for code from your sandbox then you can pass the path to the library (or library module) in your sandbox as a parameter to ./make.sh:
docs2 # ./make.sh ../sandbox/sandbox_example/include ... docs2 # ./make.sh ../sandbox/sandbox_example/include/jus_this_module ...