Context Navigation

Getting Started With SeqAn

This page describes how to setup the SeqAn CMake build system. This system is used for building the applications, demos, tutorials and tests. It was designed with the aim of providing an environment for SeqAn developers, students and people learning SeqAn. If you want to use SeqAn in your library, see How To: Use SeqAn In Your Projects.

Differences Between Subversion Checkouts And Release Archives

Caution: If you are using the release version and not the Subversion trunk then please read this getting started page.

Getting Started On Linux / Mac Os X (Makefiles)

Prerequisites

We assume that you have the following software installed:

Subversion for version control and retrieving
Gnu Compiler Collection for the Gnu C++ compiler g++ (>= 4.1).
CMake for building applications.
Python for building forwards in version >= 2.5 (a version 2.x, Python 3.x is not supported yet).

You should be able to install these programs with the package manager of your Linux distribution. If you are using Mac Os X, you should be able to download binary packages from the projects' homepages or install them using MacPorts or Homebrew.

Main directory structure

In the following we show you how to check out SeqAn and compile your first program using different development environments like Makefiles, Xcode or Visual C++.

After checking out, your main directory structure will look like this:

Those are the main directories for code. All others are auxiliary. Lets get started with Makefiles. If you are interested in Xcode or Visual C++, please scroll down.

Downloading SeqAn And A First Build using Makefiles

First, use Subversion to retrieve the current SeqAn trunk:

# cd Development
# svn co http://svn.mi.fu-berlin.de/seqan/trunk/seqan seqan-trunk

Alternatively, if you have an account at the FU Berlin, you can checkout via HTTPS.

# svn co https://svn.mi.fu-berlin.de/seqan/trunk/seqan seqan-trunk

Some users report problems like missing files with the first Subversion checkout. To fix it simply call svn update now:

# svn update seqan-trunk

Now, go into the build directory. This is where you execute CMake to build the tests, demos and applications. We create another directory Debug inside this directory for debug builds. (The most important build types that CMake knows are "Debug" and "Release" for "no optimization, debug symbols, for debugging" and "high optimization, no debug symbols, for deployment.)

# cd seqan-trunk
# mkdir -p build/Debug
# cd build/Debug
# cmake ../.. -DCMAKE_BUILD_TYPE=Debug

You can now try to build all of Seqan:

# make

Creating Your First Application

You can create new applications by either using the code generator or using a prepackaged sandbox ZIP archive. We will outline both ways here.

First, we have to create a new sandbox. This sandbox will be your local workspace and you might want to have it versionized on your own Subversion repository at a later point. All of your development will happen in your sandbox. (Eventually, if your application or library module is mature enough, you might want to consider submitting it as a SeqAn app to the SeqAn team, but let's learn to walk before we try to fly.)

We use the code generator to create a new sandbox:

# cd ../..
# ./util/bin/skel.py repository sandbox/my_sandbox
...

Within this sandbox, we can now create a new application using the code generator.

# ./util/bin/skel.py app my_app sandbox/my_sandbox
...

Alternatively, you can download this ZIP archive that contains the result of the steps above:

# cd ../../sandbox
# wget http://trac.seqan.de/attachment/wiki/Tutorial/GettingStarted/my_sandbox.zip
# unzip my_sandbox.zip
# cd ..

Now, have a look at the generated file in /sandbox/my_sandbox/apps/my_app. If you want to create another app without using the code generator (although it is highly recommended to use the code generator), then you can use the files in this directory as a template.

Now, we go back into the build directory and call CMake again:

# cd build/Debug
# cmake .

This will make cmake detect your new application directory. You have to call cmake . every time after adding a new application, but only once. Afterwards, you can simply compile and run your application with (again in build/Debug). Note that we did not specify the build mode again, CMake will remember this setting after the first call (the same is true for selected generators).

# make my_app
# ./sandbox/my_sandbox/apps/my_app/my_app

And you should see this output:

**********************
* my_app *
**********************

(c) 2011 by Your Name <your.email@example.net>
Usage: my_app app_template [OPTIONS] TEXT+
Try 'my_app --help' for more information.

Congratulations, you have successfully created your first application within the SeqAn build system with Makefiles.

Getting Started On Mac OS X (Xcode)

Prerequisites

We assume that you have the following software installed:

Subversion for version control and retrieving
Apples Xcode SDK (the link is for the different Xcode versions). Choose version 4.2 or lower, because the current version has problems working with.
CMake for generating project files

Downloading SeqAn And A First Build

Please proceed exactly as described above for Makefiles to checkout SeqAn, namely like this:

# cd Development
# svn co http://svn.mi.fu-berlin.de/seqan/trunk/seqan seqan-trunk

Alternatively, if you have an account at the FU Berlin, you can checkout via HTTPS.

# svn co https://svn.mi.fu-berlin.de/seqan/trunk/seqan seqan-trunk

The checkout may take a few minutes.

# cd seqan-trunk
# mkdir -p build/Debug
# cd build/Debug
# cmake ../.. -DCMAKE_BUILD_TYPE=Debug -G "Xcode"

This will generate several Xcode project files, namely for the SeqAn core applications, demos and test. Likewise this will happen for the extras and sandbox directories.

Note There currently is a problem with the generated forwards and Xcode projects. Do the following steps in each build directory you create.

Open seqan.xcodeproj in the root directory of the build files.
Select the target "test_stream".
Build this one target.

You now have built generated forwards for all projects in the build directory and can use any project file therein. If you create a new build directory, then you have to follow these steps again.

If you open for example the demo and tutorial project with the following command

# open core/demos/seqan_core_demos.xcodeproj

You will see (depending on your xcode version) something similar like this:

In the top you can see that the tutorial_index_search executable is chosen for compiling. On the right you see the individual demo targets and also with the red/white circles group targets. Pressing on the top left the play button will compile tutorial_index_search. On the bottom you can see the console ouput of the program.

Creating Your First Application

We recommend to create a separate folder for your own applications, tests and demo programs. The file my_sandbox.zip provides the suggested file structure and corresponding CMake files. Download it and unzip it to the sandbox folder in your SeqAn directory.

If you have Python installed, you can alternativly use the code generator for automatic genearation of a sandbox and applications.

Go to the apps folder of your own just created sandbox, i.e. seqan/sandbox/my_sandbox/apps. Here you will already find template files for an application.

# ls sandbox/my_sandbox/apps/my_app/
CMakeLists.txt	INFO		my_app.cpp	my_app.h

You may also want to edit the INFO file to contain information about your application. Open the file my_app.cpp and replace its content by:

#include <iostream>
#include <seqan/sequence.h>  // CharString, ...
#include <seqan/file.h>      // to stream a CharString into cout

int main(int, char **) {
    std::cout << "Hello World!" << std::endl;
    seqan::CharString mySeqanString = "Hello SeqAn!";
    std::cout << mySeqanString << std::endl;
    return 1;
}

Save the file and go back to the build/Debug directory executing the cmake command again:

# cmake ../.. -DCMAKE_BUILD_TYPE=Debug  -G "Xcode"

You can open now your Xcode sandbox project, for example by

# open sandbox/my_sandbox/seqan_sandbox_my_sandbox.xcodeproj

Choosing on the top left your my_app as traget and pressing the play button, your first app will compile and execute.

At the bottom you see the console output where you greet the world and SeqAn.

Hello World!
Hello SeqAn!

Congratulations, you have successfully created your first application within the SeqAn build system using Xcode.

Getting Started On Windows

MS Visual Studio

Prerequisites

We assume that you have the following software installed:

TortoiseSVN for version control and retrieving
Microsoft Visual Studio for compiling C++ code
CMake for generating project files

Downloading SeqAn And A First Build

First, create a new folder in your Windows Explorer for the SeqAn files. Right click on this folder and choose SVN Checkout... from the context menu.

Type in the field URL of repository

http://svn.mi.fu-berlin.de/seqan/trunk/seqan

or, alternatively, if you have an account at FU Berlin (HTTPS),

https://svn.mi.fu-berlin.de/seqan/trunk/seqan

The Checkout repository should be the folder you just created. Leave the other settings set to their default (fully recursive, HEAD revision) and click OK.

The checkout may take a few minutes.

Now, start a Windows Command Prompt (Start -> All Programs -> Accessories -> Command Prompt), move to the folder containing the SeqAn directory and create a new folder build, e.g.:

> cd "Users\user_name\My Documents"
> mkdir build
> cd build

Make sure that cmake has been added to the system path. Execute CMake by typing

> cmake ..\seqan_trunk -G "Visual Studio 9 2008"

If you use another version of Visual Studio, you can find out the correct parameter by typing cmake --help. If you plan to use different versions of Visual Studio we recommend to use subdirectories as described below in Generating IDE Project Files.

Note that you have to choose the "Win64" variants of the "Visual Studio" generators if you want to build 64 bit binaries.

Now, you can open the project file from the Windows explorer: Move to the build directory and double click on the file Seqan.sln. In the Solution Explorer to the left you will find all applications and demos of SeqAn, as well as the complete library in the folders SeqAnCore and SeqAnExtras.

As an example you can open, compile and execute the alignment demo: Click on the + in front of alignment in the Solution Explorer and also on the + in front of Source Files. Double click on the file alignment.cpp to open it in the main window. Right click on alignment in the Solution Explorer and choose Set as StartUp Project from the context menu.

To compile and execute the demo, choose Debug -> Start Without Debugging from the main menu or press Ctrl+F5.

For applications that need command line arguments you can specify these by right clicking on the application in the Solution Explorer and choosing Properties from the context menu. In the Configuration Properties on the left choose Debugging and on the right type in the Command arguments. Click OK and start the application by pressing Ctrl+F5 or Debug -> Start Without Debugging in the main menu.

Creating Your First Application

If you have Python installed, you can alternativly use the code generator for automatic genearation of a sandbox and applications. Here, we focus on using the ZIP archive to create a first application and refer to the linux section for a simple usage description of the code generator.

Move to the apps folder of your own just created sandbox, i.e. seqan/sandbox/my_sandbox/apps. Here you will already find a template for an application. We suggest to copy the folder my_app with all its content and keep my_app as a template. Choose a name for your app, e.g. first_app, and rename the copied folder as well as the cpp file contained in the folder. Replace all occurences of my_app in the files CMakeLists.txt by first_app. Delete the header file my_app.h since we will not need it. You may also want to edit the INFO file to contain information about your application.

Open the file first_app.cpp and replace its content by:

#include <iostream>
#include <seqan/sequence.h>  // CharString, ...
#include <seqan/file.h>      // to stream a CharString into cout

int main(int, char **) {
    std::cout << "Hello World!" << std::endl;
    seqan::CharString mySeqanString = "Hello SeqAn!";
    std::cout << mySeqanString << std::endl;
    return 1;
}

Save the file and go back to the Windows Command Prompt to execute CMake again:

> cd seqan\build
> cmake .. -G "Visual Studio 9 2008"

When you now close Visual Studio and again open the file Seqan.sln from the build folder, you will find your app first_app in the Solution Explorer. Set it as StartUp project as described in the previous section and execute it by pressing Ctrl+F5.

If everything went well, it will compile and you should get the following output:

Hello World!
Hello SeqAn!

Congratulations, you have successfully created your first application within the SeqAn build system using Visual studio.

Eclipse and CDT

Prerequisites

In contrast to MS Visual Studio, Eclipse does not bring its own c++ toolchain by default. You need to install the tools for building, linking and compiling the projects separately. We recommend to use MinGW for this purpose because of its simplicity and all components like debugging work fine under eclipse. You can download the installer from the project's homepage http://www.mingw.org/ During the installation you are prompted to choose your installation packages. Select c++ compiler and make sure that MSYS is not checked.

After the installation you are required to add the bin folder of the MinGW installation to the PATH environment variable (e.g., %PATH%;drive:\path\to\MinGW\bin). For a detailed description on how to permanently change environment variables see http://vlaurie.com/computers2/Articles/environment.htm.

Download Eclipse from the project's site. Make sure that all necessary plugins are installed.

Downloading SeqAn And A First Build

Create a new folder for your workspace in the directory of your choice.

> mkdir workspace_seqan

Open Eclipse and select the workspace when prompted. Switch to the workbench and open the SVN Repository Exploring perspective (you can select the perspective on the register at the upper right corner of the workbench). Add a new repository and fill in the forms to get access to the seqan project files.

Right click on the recently added repository location and check out the project. After finishing the check out switch to the c++ perspective and right click on the project in the project explorer (view on the left hand side). Select New -> Convert to a C/C++ Project (Adds C/C++ Nature). In the appeared dialog select Makefile Project and select MinGW GCC toolchain and press Finish.

After the worbench has refreshed the indexer starts automatically. Note, that indexing the project can take some minutes. In the meantime you can build the projec in an out-of-source-build. You can build the files in the seqan/build directory as described in the other tutorials above. But, we recommend to create a separate build folder parallel to the seqan-trunk folder that includes all your source files. In that case build and source files will be organized in separated projects in your workspace which simplifies the workflow of editing code and building the targets. To do so you need to open the command line interpreter cmd and switch to your workspace location. Create a build directory next to the seqan folder which contains the source files of SeqAn.

> cd workspace_seqan
> mkdir build\Debug

When executing dir in the current directory you should see something similar to this.

Go into the build directory and invoke the Eclipse cmake generator using MinGW Makefiles.

> cd build\Debug
> cmake -G "Eclipse CDT4 - MinGW Makefiles" -D CMAKE_BUILD_TYPE=Debug ..\..\seqan

After configuration and building is done you can simply import the build files as an existing project into your Eclipse workspace. Select the Project Explorer in Eclipse (C++ perspective) and right click somewhere into the view. Select Import... and choose Existing Project into Workspace in the current dialog. Select Next and browse to your build directory in your workspace. Eclipse recognizes that there is a project file and selects it automatically. Confirm the selection with Finish.

Before you build any target you should change the launch preferences of Eclipse. In the menu select Window -> Preferences. Go to the menu Run/Debug -> Launching and uncheck Build (if required) before launching. It prevents the project for building the target all (deault preference), which can take quite a while depending on the system you are using. This can happen if, e.g. you accidentally run a binary before building the target after you changed some code.

Now you have successfully setup Eclipse and can build your targets using the Make Target view (usually on the right hand side of the workbench).

Creating Your First Application

Follow the instructions under Creating Your First Application of the MS Visual Studio tutorial. When you are done with creating the first_app.cpp and replacing its content with the suggested code, then you need to invoke cmake again.

> cd workspace_seqan\build\Debug
> cmake .

After cmake is done with building the project files you can simply refresh the imported build project in Eclipse in order to make the applied changes working. Browse to your target in the Make Target view. Double click on the target of your application and the binary is built immediately. After the build is complete go into the menu and select Run -> Run Configurations. Add a new C/C++ Application. Under Project select the seqan-build project. Then you can select your recently built binary under C/C++ Application:. Finally, you can give your application a name. Confirm your selection with Apply and hit the Run button in the bottom of the dialog. Done!

If everything went well, you will see something similar to this:

Congratulations, you have successfully created your first application within the SeqAn build system using Eclipse and CDT.

Known Problems

Currently, there is a known bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=236330 with the 64 bit version of Eclipse and CDT 8.0.0. The console displays no output. The bug has been already fixed. Though, the bug fix becomes available first with the next minor release of CDT 8.0.1.

Other Platforms

Since Eclipse is a pure java application it runs on every platform that has java installed, e.g. Mac OS and Linux. Both systems provide a complete c++ toolchain, i.e. no further requirements are necessary. Just go to the eclipse project site and download the appropriate eclipse version and follow the instructions for creating your first app above (of course you will use the terminal instead of the cmd).

Note, we also have detected unstable behavior of the 64 bit version of Eclipse running under OS 10.6.x. It froze more than once the complete system when the auto completion action had been invoked. This is also a known bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=345970 which cannot be fixed as it is presumably a problem of the JVM. One can hope that this problem gets fixed by the new release of Java 7 as there are some changes that have been made to the JVM. At least it runs stable with the 32 bit Eclipse version for Mac OS X. At the moment, we have not tested eclipse under Linux distributions yet. But we complete the tutorial for such systems asap.

Generating Parallel IDE Project Files (Visual Studio, Xcode etc.)

CMake can generate project files for various IDEs such as Xcode and Visual Studio. You will only be able to generate files for Xcode when on Mac Os X, for Visual Studio when on Windows and so on.

It is possible to create multiple build file types at the same time. For this, you have to create a subdirectory for each IDE to build project/Make files for.

This is useful when testing your programs for portability in multiple Visual Studio versions, for example. First, we have to remove the file CMakeCache.txt and the directory CMakeFiles from the directory build/Debug.

On Linux/Mac Os X:

# cd build/Debug
# rm CMakeCache.txt
# rm -r CMakeFiles

On Windows:

> cd build\Debug
> del CMakeCache.txt CMakeFiles

Then, create a new subdirectory, e.g. for Xcode or Visual Studio 2009

# mkdir Xcode/Debug
# cd Xcode/Debug

> mkdir VS2009\Debug
> cd VS2009\Debug

Here, we use CMake to generate the project files by specifying a generator with the parameter -G:

# cmake -G "Xcode" -D CMAKE_BUILD_TYPE=Debug ../../..

> cmake -G "Visual Studio 9 2008" -D CMAKE_BUILD_TYPE=Debug ../../..

Now, we can open the project files. The following commands show how to generate project files for other Visual Studio versions:

> mkdir VS2008\Debug
> cd VS2008\Debug
> cmake -G "Visual Studio 9 2008" -D CMAKE_BUILD_TYPE=Debug ../../..
> cd ..\..
> mkdir VS2005\Debug
> cd VS2005\Debug
> cmake -G "Visual Studio 8 2005" -D CMAKE_BUILD_TYPE=Debug ../../..
> cd ..\..
> mkdir VS2003\Debug
> cd VS2003\Debug
> cmake -G "Visual Studio 7 .NET 2003" -D CMAKE_BUILD_TYPE=Debug ../../..
> cd ..\..

How To Make Release/Debug builds

When using the Makefile generator, it is useful to have multiple build types. CMake supports the following build types:

Debug: No optimization, with debug symbols.
Release: Optimization, without debug symbols.
RelWithDebInfo: Optimization, with debug symbols. Useful for profiling.
MinSizeRel: Size-optimized release binary without debug symbols.

We recommend to have one build directory for each build type. First, we have to remove the file CMakeCache.txt and the directory CMakeFiles from the directory build/Debug.

# cd build
# rm CMakeCache.txt
# rm -r CMakeFiles

Then, create one build directory for each build type you want to use:

# mkdir Debug; cd Debug
# cmake ../.. -DCMAKE_BUILD_TYPE=Debug
# cd ..
# mkdir Release; cd Release
# cmake ../.. -DCMAKE_BUILD_TYPE=Release
# cd ..
# mkdir RelWithDebInfo; cd RelWithDebInfo
# cmake ../.. -DCMAKE_BUILD_TYPE=RelWithDebInfo
# cd ..
# mkdir MinSizeRel; cd MinSizeRel
# cmake ../.. -DCMAKE_BUILD_TYPE=MinSizeRel
# cd ..

CMake Debug Mode

When generating Makefiles with CMake, you can enable a debug mode to see which commands are executed by the Makefile.

There are two ways:

Set the environment variable VERBOSE or give VERBOSE=1 to the make command (VERBOSE=1 make [targets] or make VERBOSE=1 [targets]).
Add the parameter -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON to the cmake command line. Note that you have to remove to file CMakeCache.txt first and include the parameter -DCMAKE_BUILD_TYPE again.

Submit a comment

If you found a mistake, or have suggestions about an improvement of this page press: submit your comment

Attachments

my_sandbox.zip (12.3 KB) - added by holtgrew 12 months ago. Readymade sandbox for the Getting Started tutorial.

Download in other formats:

Plain Text

Context Navigation

Table of Contents

Getting Started With SeqAn

Differences Between Subversion Checkouts And Release Archives

Getting Started On Linux / Mac Os X (Makefiles)

Prerequisites

Main directory structure

Downloading SeqAn And A First Build using Makefiles

Creating Your First Application

Getting Started On Mac OS X (Xcode)

Prerequisites

Downloading SeqAn And A First Build

Creating Your First Application

Getting Started On Windows

MS Visual Studio

Prerequisites

Downloading SeqAn And A First Build

Creating Your First Application

Eclipse and CDT

Prerequisites

Downloading SeqAn And A First Build

Creating Your First Application

Known Problems

Other Platforms

Generating Parallel IDE Project Files (Visual Studio, Xcode etc.)

How To Make Release/Debug builds

CMake Debug Mode

Submit a comment

Attachments

Download in other formats: