Porting from SeqAn2

Table of Contents

• Important differences to prior versions
  • Naming
  • Initialisation
  • Return values and parameters
• Using SeqAn3 and SeqAn2 in the same application
  • Versions
  • Paths and Namespaces
  • Mixing types
  • The argument parser version check feature
  • SeqAn2 features missing from SeqAn3

SeqAn3 is a completely new library so there is no easy or automated way of porting applications from SeqAn2. We recommend that everyone go through the tutorial, learn the new idioms and then re-write their application. We know this is a big burden and we promise that next major versions will be incremental updates again. The notes on this page may help transitioning and/or maintaining dependencies to SeqAn2 and SeqAn3.

Important differences to prior versions

Please see C++ Concepts and Ranges for some of the fundamental, structural differences and design choices of SeqAn3.

Naming

SeqAn3 uses snake_case instead of CamelCase for naming all entities other than concepts. Concepts are named using CamelCase. This should be very close to the standard library.

Initialisation

SeqAn3 uses brace initialisation, also known as "uniform initialisation" for all class types. Built-in arithmetic types like uint64_t may be initialised via =.

There are many online resources on "uniform initialisation", e.g.:

• https://arne-mertz.de/2015/07/new-c-features-uniform-initialization-and-initializer_list/

Return values and parameters

SeqAn1 and SeqAn2 used out-parameters as the primary way of returning values, SeqAn3 uses plain return values. This is no less efficient nowadays, because there is guaranteed copy elision since C++17.

The details of copy elision are described here:

• https://en.cppreference.com/w/cpp/language/copy_elision

Using SeqAn3 and SeqAn2 in the same application

SeqAn2 and SeqAn3 can coexist in the same application, however certain care should be taken.

Versions

There are some incompatibilities between SeqAn-2.4 and SeqAn3, please update to the master-branch of SeqAn2 or use the 2.5 release (when available).

Paths and Namespaces

For SeqAn1 and SeqAn2 the following entities are called "seqan":

• the primary namespace
• the include folder
• the CMake library name

All of the above are named "seqan3" for the SeqAn3 library so coexistence should be possible on all levels.

We discourage having any using namespace seqan; or using namespace seqan3; statements in your application and and suggest replacing any occurrences of the former with fully qualified lookups, e.g. writing seqan::readRecord. Clearly marking all SeqAn2-code as such will help identify (and replace) it later on and is a good step before introducing SeqAn3 into your code. We are working on a script to help with this.

Mixing types

Many SeqAn2 interfaces handle standard library containers and strings and we are working on adding a support layer to SeqAn2 that handles SeqAn3-alphabets. For now you may have to convert data structures if using old and new interfaces within the same application.

Some components that are rather independent and good first targets to start porting are:

• The argument parser.
• Input and Output.

The argument parser version check feature

The major change is that we do not provide a cmake-level directive to turn off version checking. Instead, the current implementation lets you disable the version check in the following ways:

1. The developer can disable the feature permanently on construction of the seqan3::argument_parser.
2. The administrator or user can deactivate the feature globally on their system via the environment variable SEQAN3_NO_VERSION_CHECK.
3. The user can disable the feature temporarily for one day via a command-line option when calling the application.

Otherwise, if non of the above happened, the user will be prompted at the first call of the application to select a configuration (Never/Always/Yes/No). However, if the application is executed in a non-terminal process, e.g within a cron job or a workflow, no prompt will be issued but instead the version check will be triggered in the background. This will happen no more than once per day.

If you are interested in the new argument parser design, take a look at our tutorial Parsing command line arguments with Sharg.

SeqAn2 features missing from SeqAn3

This is a non-exhaustive list of features that are currently missing, but will be ported:

• Annotation file formats (GFF, GTF, VCF...)
• Blast tabular file formats
• Memory Mapping support
• Journaled String Tree
• k-mer/q-gram based indexing/searching

This is a non-exhaustive list of features that we do not plan to port:

• The Store module
• Online-Search algorithms (not used in practice)
• The Graph module (use the lemon library instead)
• Uncompressed suffix arrays (no benefit over FM indexes)