General Build Information

Do I need to build the package?

RNAstructure is provided both as source code and as prebuilt executables. Prebuilt executables are currently available for 32-bit Linux, 64-bit Linux, Max OS, 32-bit Windows, and 64-bit Windows. If you are using one of these operating systems, then you probably do not need to build the package. The available executables will work fine.

DATAPATH Variable

In order to successfully use the data tables in the RNAstructure repository during calculations, an environment variable called DATAPATH must be set to the location of the data tables folder on the current machine.

For example, in BASH, this is accomplished with:
  $ export DATAPATH=<PATH-TO-RNAstructure>/data_tables/

---

Building the RNAstructure JAVA GUI

The RNAstructure Graphical User Interface (GUI) is composed of two important components:  the graphical front-end, written in Java and the native back-end, RNAstructure_GUI libary written in C++. The two are linked using the Java Native Interface (JNI). In addition, SWIG is used to generate C++ and Java "glue code" to provide necessary bindings on each side.

Due to this architecture, there are three phases to building the GUI, of which only two are usually required:

1. (Optional) Generating the SWIG code
2. Compiling the C++ libarary
3. Compiling the Java source code into class files and/or a Java JAR file.

The first step involves running swig, which reads *.i files and parses C++ header files to generate *.cxx files that are later included in the compilation of the native RNAstructure_GUI libary. However, the RNAstructure distrubution already includes the pre-generated SWIG files, so it is NOT necessary to run SWIG or even to have it installed unless you plan to make changes to the public interface of the RNAstructure_GUI library (i.e. to the header files inside the java_interface\SWIG directory: RNAstructureBackendCalculator.h, DotPlotBackend.h, or StructureBackend.h)

Compilation of the C++ libary and the Java interface BOTH require installation of the Oracle Java SE JDK. (The latest version is recommended for security reasons, but the minimum version is 1.8).  The Java JDK is required (instead of just the JRE) because it includes javac, the Java compiler, as well as several C++ JNI header files that are necessary for compiling the native library.  Usually the location of javac as well as the JNI header files can be determined automatically (during the "Make" commands, below) however it might be necessary to modify some variables inside the file "compile-java.h", especially on Linux systems, where the installation location of Java can vary widely from one Linux distributionand/or package manager to another.

All steps involved in building the GUI are performed using a Makefile in the RNAstructure/java_interface directory.  Importantly, this Makefile is distinct from the Makefile in the root RNAstructure directory, however it does include several of the same files (e.g. compiler.h). These java-specific commands can be run in a terminal/shell from within the RNAstructure/java_interface directory:

• make gui - Bulilds the native C++ libary as well as the Java JAR file. This is usually the only operation most users will need to perform.
• make swig - Generates the SWIG "glue code" (only necessary if changing the public interface of the native library)
• make tester - Builds the Java GUI Regression test program  (only necessary for perfoming automated regression tests on the GUI)
• make all - Performs all of the above build operations.
• make help - Show a list of all valid Makefile goals.

When the JAVA GUI is built correctly, two new files will exist in the RNAstructure/exe directory: a single large dynamic RNAstructure library (whose name depends on the operating system), and a JAVA JAR archive, called RNAstructure.jar. See Running the RNAstructure JAVA GUI for details on how to use these files.

---

Building the Command Line (Text) Interfaces

Configuring the Build on Unix/Linux/OS-X

The command line (text) interfaces for RNAstructure are built using the Makefile in the main directory (RNAstructure/). The definitions for compiler and flags are in RNAstructure/compiler.h. The Makefile will automatically detect the environment for most operating systems and set the proper build flags. Linux, Cygwin running on Windows, and Mac OS are automatically detected. The Cygwin environment is used to build the Windows distribution of RNAstructure.

Building on Unix/Linux/Cygwin running on Windows

To build the package, use the command "make all" in RNAstructure/. The command line executables are built and placed in RNAstructure/exe/. Both the serial (one core) and smp (multiple core) versions of the executables will be made. You should probably then update your PATH variable to include this directory.

Building on Mac OS

On Mac OS, use the comman "make serial" to make the one core version of all the programs. Note that the smp (parallel) versions require OpenMP, which is not supported by the Clang compiler. The executables will be placed in RNAstructure/exe/. You should probably update your PATH variable to include this directory.

Building on Mac OS requires XCode. Youc an download this fof free from the app store.

Building CUDA on Unix/Linux/OS-X

In adition, if you have a CUDA compiler, you can build partition-cuda by typing "make cuda" in the RNAstructure directory. This can then be run if you have a CUDA-capable graphics card.

An optional "make install" command will copy all the executables to the /usr/local/RNAstructure/ directory. This is helpful in a shared computing environment. This command can only be executed as root.

Building Multifind

Multifind is built separately from the rest of the package. It depends on an installation of libsvm, which handles the support vector machine calculation. To build it, set the INCLUDESVM variable in compiler.h to point to the libsvm installation and uncomment the line "#MF = Multifind~" by removing the "#". Multifind will then be included with the list of standard RNAstructure programs and can be built with the command make Multifind or make Multifind-smp (for the parallel version).

Building on Windows

• Linux-style build process using Cygwin and MingW-W64
  Cygwin provides a complete POSIX environment on Windows and allows compilation of RNAstructure using the same framework as on Linux (i.e. gcc/g++ and GNU make). 
• Text (Command-line) Interfaces:
  In the root RNAstructure folder run "make all". The compiled executables will be placed in the RNAstructure/exe directory.
  
• RNAstructure_GUI library (required for the Java GUI)
  In the folder RNAstructure/java_interface, run "make gui" 
  The compiled Java JAR file (RNAstructure.jar) and native library (RNAstructure_GUI.dll) will will be placed in the RNAstructure/exe directory.
• Microsoft Visual Studio 
  
  • Text (Command-line) Interfaces:
    There are Visual Studio solutions in the folder for each command line interface. These can be opened in Visual Studio and the target can be built. Additionally, in the folder Windows_text_interfaces, the solution  Windows_text_interfaces.sln is available. This solution can be used to build all the command line interfaces.The executables will be deposited in the Release sub-folder.
  • RNAstructure_GUI library (required for the Java GUI)
    In the folder Windows_gui_dll, use Visual Studio 2012 to open the solution  RNAstructure_GUI.sln
    Then build using Visual Studio. The executables will be deposited in the Release sub-folder.
    

---

Testing the Build

RNAstructure has a set of regression tests for the command line interfaces found in tests/. Use make serial to test all the serial programs. Use make smp to test the smp programs (openmp and pthreads) programs. Use make cuda to test the cuda programs. Use make all to run serial, smp, and cuda tests.

---