A documentation on how to configure the different features of RNAlib, how to install the ViennaRNA Package, and finally, how to link you own programs against RNAlib.

Installing the ViennaRNA Package

For best portability the ViennaRNA package uses the GNU autoconf and automake tools. The instructions below are for installing the ViennaRNA package from source. However, pre-compiled binaries for various Linux distributions, as well as for Windows users are available from Download section of the main ViennaRNA homepage.

Quick-start

Usually you'll just unpack, configure and make. To do this type:

tar -zxvf ViennaRNA-2.4.14.tar.gz
cd ViennaRNA-2.4.14
./configure
make
sudo make install

Installation without root privileges

If you do not have root privileges on your computer, you might want to install the ViennaRNA Package to a location where you actually have write access to. To do so, you can set the installation prefix of the ./configure script like so:

./configure --prefix=/home/username/ViennaRNA
make install

This will install the entire ViennaRNA Package into a new directory ViennaRNA directly into the users username home directory.

Notes for MacOS X users

Although users will find /usr/bin/gcc and /usr/bin/g++ executables in their directory tree, these programs are not at all what they pretend to be. Instead of including the GNU programs, Apple decided to install clang/llvm in disguise. Unfortunately, the default version of clang/llvm does not support OpenMP (yet), but only complains at a late stage of the build process when this support is required. Therefore, it seems necessary to deactivate OpenMP support by passing the option –disable-openmp to the ./configure script.

Additionally, since MacOS X 10.5 the perl and python installation distributed with MacOS X always include so called universal-binaries (a.k.a. fat-binaries), i.e. binaries for multiple architecture types. In order to compile and link the programs, library, and scripting language interfaces of the ViennaRNA Package for multiple architectures, we've added a new configure switch that sets up the required changes automatically:

./configure --enable-universal-binary

Note: Note, that with link time optimization turned on, MacOS X's default compiler (llvm/clang) generates an intermediary binary format that can not easily be combined into a multi-architecture library. Therefore, the –enable-universal-binary switch turns off link time optimization!

Configuring RNAlib features

The ViennaRNA Package includes additional executable programs such as RNAforester, Kinfold, and Kinwalker. Furthermore, we include several features in our C-library that may be activated by default, or have to be explicitly turned on at configure-time. Below we list a selection of the available configure options that affect the features included in all executable programs, the RNAlib C-library, and the corresponding scripting language interface(s).

Streaming SIMD Extension (SSE) support

Since version 2.3.5 our sources contain code that implements a faster multibranch loop decomposition in global MFE predictions, as used e.g. in RNAfold. This implementation makes use of modern processors capability to execute particular instructions on multiple data simultaneously (SIMD - single instruction multiple data, thanks to W. B. Langdon for providing the modified code). Consequently, the time required to assess the minimum of all multibranch loop decompositions is reduced up to about one half compared to the runtime of the original implementation. This feature is enabled by default since version 2.4.11 and a dispatcher ensures that the correct implementation will be selected at runtime. If for any reason you want to disable this feature at compile-time use the following configure flag:

./configure --disable-simd

Scripting Interfaces

The ViennaRNA Package comes with scripting language interfaces for Perl 5, Python 2, and Python 3 (provided by swig), that allow one to use the implemented algorithms directly without the need of calling an executable program. The interfaces are build by default whenever the autoconf tool-chain detects the required build tools on your system. You may, however, explicitly turn off particular scripting language interface support at configure-time, for instance for Perl 5 and Python 2, before the actual installation.

Example:

./configure --without-perl --without-python

Disabling the scripting language support all-together can be accomplished using the following switch:

./configure --without-swig

Cluster Analysis

The programs AnalyseSeqs and AnalyseDists offer some cluster analysis tools (split decomposition, statistical geometry, neighbor joining, Ward's method) for sequences and distance data. To also build these programs add

--with-cluster

to your configure options.

Kinfold

The Kinfold program can be used to simulate the folding dynamics of an RNA molecule, and is compiled by default. Use the

--without-kinfold

option to skip compilation and installation of Kinfold.

RNAforester

The RNAforester program is used for comparing secondary structures using tree alignment. Similar to Kinfold, use the

--without-forester

option to skip compilation and installation of RNAforester.

Kinwalker

The Kinwalker algorithm performs co-transcriptional folding of RNAs, starting at a user specified structure (default: open chain) and ending at the minimum free energy structure. Compilation and installation of this program is deactivated by default. Use the

--with-kinwalker

option to enable building and installation of Kinwalker.

Link Time Optimization (LTO)

To increase the performance of our implementations, the ViennaRNA Package tries to make use of the Link Time Optimization (LTO) feature of modern C-compilers. If you are experiencing any troubles at make-time or run-time, or the configure script for some reason detects that your compiler supports this feature although it doesn't, you can deactivate it using the flag

./configure --disable-lto

Note, that GCC before version 5 is known to produce unreliable LTO code, especially in combination with SSE (see config_sse). We therefore recommend using a more recent compiler (GCC 5 or above) or to turn off one of the two features, LTO or SSE optimized code.

OpenMP support

To enable concurrent computation of our implementations and in some cases parallelization of the algorithms we make use of the OpenMP API. This interface is well understood by most modern compilers. However, in some cases it might be necessary to deactivate OpenMP support and therefore transform RNAlib into a C-library that is not entirely thread-safe. To do so, add the following configure option

./configure --disable-openmp

POSIX threads (pthread) support

To enable concurrent computation of multiple input data in RNAfold, and for our implementation of the concurrent unordered insert, ordered output flush data structure vrna_ostream_t we make use of POSIX threads. This should be supported on all modern platforms and usually does not pose any problems. Unfortunately, we use a threadpool implementation that is not compatible with Microsoft Windows yet. Thus, POSIX thread support can not be activated for Windows builds until we have fixed this problem. If you want to compile RNAfold and RNAlib without POSIX threads support for any other reasons, add the following configure option

./configure --disable-pthreads

Stochastic backtracking using Boustrophedon scheme

Stochastic backtracking for single RNA sequences, e.g. available through the RNAsubopt program, received a major speedup by implementing a Boustrophedon scheme (see this article for details). If for some reason you want to deactivate this feature, you can do that by adding the following switch to the configure script:

./configure --disable-boustrophedon

SVM Z-score filter in RNALfold

By default, RNALfold that comes with the ViennaRNA Package allows for z-score filtering of its predicted results using a support vector machine (SVM). However, the library we use to implement this feature (libsvm) is statically linked to our own RNAlib. If this introduces any problems for your own third-party programs that link against RNAlib, you can safely switch off the z-scoring implementation using

./configure --without-svm

GNU Scientific Library

The new program RNApvmin computes a pseudo-energy perturbation vector that aims to minimize the discrepancy of predicted, and observed pairing probabilities. For that purpose it implements several methods to solve the optimization problem. Many of them are provided by the GNU Scientific Library, which is why the RNApvmin program, and the RNAlib C-library are required to be linked against libgsl. If this introduces any problems in your own third-party programs that link against RNAlib, you can turn off a larger portion of available minimizers in RNApvmin and linking against libgsl all-together, using the switch

./configure --without-gsl

Disable C11/C++11 feature support

By default, we use C11/C++11 features in our implementations. This mainly accounts for unnamed unions/structs within RNAlib. The configure script automatically detects whether or not your compiler understands these features. In case you are using an older compiler, these features will be deactivated by setting a specific pre-processor directive. If for some reason you want to deactivate C11/C++11 features despite the capabilities of your compiler, use the following configure option:

./configure --disable-c11

Enable warnings for use of deprecated symbols

Since version 2.2 we are in the process of transforming the API of our RNAlib. Hence, several symbols are marked as deprecated whenever they have been replaced by the new API. By default, deprecation warnings at compile time are deactivated. If you want to get your terminal spammed by tons of deprecation warnings, enable them using:

./configure --enable-warn-deprecated

Single precision partition function

Calculation of partition functions (via RNAfold -p) uses double precision floats by default, to avoid overflow errors on longer sequences. If your machine has little memory and you don't plan to fold sequences over 1000 bases in length you can compile the package to do the computations in single precision by running

./configure --enable-floatpf

Note: Using this option is discouraged and not necessary on most modern computers.

Help

For a complete list of all ./configure options and important environment variables, type

./configure --help

For more general information on the build process see the INSTALL file.

Linking against RNAlib

In order to use our implemented algorithms you simply need to link your program to our RNAlib C-library that usually comes along with the ViennaRNA Package installation. If you've installed the ViennaRNA Package as a pre-build binary package, you probably need the corresponding development package, e.g. viennarna-devel, or viennarna-dev. The only thing that is left is to include the ViennaRNA header files into your source code, e.g.:

#include <ViennaRNA/mfe.h>

and start using our fast and efficient algorithm implementations.

See also: In the mp_example and Some Examples using RNAlib API v3.0 sections, we list a small set of example code that usually is a good starting point for your application.

Compiler and Linker flags

Of course, simply adding the ViennaRNA header files into your source code is usually not enough. You probably need to tell your compiler where to find the header files, and sometimes add additional pre-processor directives. Whenever your installation of RNAlib was build with default settings and the header files were installed into their default location, a simple

-I/usr/include

pre-processor/compile flag should suffice. It can even be omitted in this case, since your compiler should search this directory by default anyway. You only need to change the path from /usr/include to the correct location whenever the header files have been installed into a non-standard directory.

On the other hand, if you've compiled RNAlib with some non-default settings then you probably need to define some additional pre-processor macros:

VRNA_DISABLE_C11_FEATURES $\ldots$ Disable C11/C++11 features.
Warning
Add this directive to your pre-processor/compile flags only if RNAlib was build with the –disable-c11 configure option.

See also
Disable C11/C++11 feature support and vrna_C11_features()
VRNA_WARN_DEPRECATED $\ldots$ Enable warnings for using deprecated symbols.
Note
Adding this directive enables compiler warnings whenever you use symbols in RNAlib that are marked deprecated.

See also
Enable warnings for use of deprecated symbols and Deprecated List
USE_FLOAT_PF $\ldots$ Use single precision floating point operations instead of double precision in partition function computations.
Warning
Define this macro only if RNAlib was build with the –enable-floatpf configure option!

See also
Single precision partition function

Simply add the corresponding definition(s) to your pre-processor/compile flags, for instance:

-DVRNA_DISABLE_C11_FEATURES

Finally, linking against RNAlib is achieved by adding the following linker flag

-L/usr/lib -lRNA -fopenmp

Again, the path to the library, /usr/lib, may be omitted if this path is searched for libraries by default. The second flag tells the linker to include libRNA.a, and the remaining two flags activate Link Time Optimization (LTO) and OpenMP support support, respectively.

Note: Depending on your linker, the last two flags may differ.; Depending on your configure time decisions, you can drop one or both of the last flags.; In case you've compiled RNAlib with LTO support (See Link Time Optimization (LTO)) and you are using the same compiler for your third-party project that links against our library, you may add the
-flto
flag to enable Link Time Optimization.

The pkg-config tool

Instead of hard-coding the required compiler and linker flags, you can also let the pkg-config tool automatically determine the required flags. This tool is usually packaged for any Linux distribution and should be available for MacOS X and MinGW as well. We ship a file RNAlib2.pc which is installed along with the static libRNA.a C-library and populated with all required compiler and linker flags that correspond to your configure time decisions.

The compiler flags required for properly building your code that uses RNAlib can be easily obtained via

pkg-config --cflags RNAlib2

You get the corresponding linker flags using

pkg-config --libs RNAlib2

With this widely accepted standard it is also very easy to integrate RNAlib in your autotools project, just have a look at the PKG_CHECK_MODULES macro.

Go to the next Chapter "Free Energy of Secondary Structures"

Table of Contents