ROSE  0.9.9.5
Installing ROSE

How to install ROSE from source code.

Downloading ROSE

ROSE is free (libre) software distributed under a modified BSD license. The ROSE team at Lawrence Livermore National Laboratory makes two kinds of public source releases both as Git repositories.

ROSE can be downloaded with standard Git commands. Do not use Github's "Download ZIP" button since this strips necessary version information from the ZIP archive.

Development Repository

git clone https://github.com/rose-compiler/rose-develop rose
cd rose/

Release Repository

git clone https://github.com/rose-compiler/rose
cd rose/

Versioning Scheme

ROSE uses a continuous delivery paradigm. To obtain the identification for a particular version of ROSE, run "git rev-parse HEAD" in the ROSE source directory (the reported SHA1 hash can be abbreviated to 7 or so characters for convenience). ROSE also has a loosely-coupled dotted quad version number which can be found in the ROSE_VERSION file, but the Git SHA1 hash is more precise.

The repositories listed above are the official release points; other repositories might be available but are unofficial. Some members of the ROSE team also distribute custom builds in virtual machines, which can be a good way to get up and playing quickly. Query one of the ROSE mailing lists to find this information, which changes from time to time.

Hardware requirements

ROSE is tested and supported on Redhat Enterprise Linux RHEL6 and RHEL7 running on Intel x86-64 hardware. Some developers are able to use other operating systems and platforms, including Debian and Ubuntu.

The ROSE library consists of approximately two million lines of C++ and requires substantial resources to compile. The machine should have at least eight gigabytes of free RAM available, and the build system can make use of multiple CPU cores. Compiling the ROSE library (no projects or tests) with all features enabled will take approximately 30 minutes on a 12 core machine with 48 gigabytes of RAM. Developers working on ROSE itself may want to consider using ccache to speed up recompiles; rebuilding the library takes about two minutes on the same hardware with ccache.

Software dependencies

In order to build ROSE from source code, software dependencies should first be installed.

Software component Necessity Supported Versions Regularly tested

Purpose

Git Required Any recent version 1.7.2.5

Used for cloning the ROSE release repository to your local machine. See Installing Git.

wget Required Any recent version 1.12

Used to download the EDG binary tarball, a C/C++ parser. This is currently (Sep 2015) required even when ROSE is configured without the C/C++ frontend languages. See Installing wget.

GNU Compiler Collection Required GCC-4.2.4 through 4.8.4 GCC-4.4.5

To compile ROSE. The gcc, g++, and gfortran compilers are required. Furthermore, all libraries on which ROSE depends should be compiled with the same compiler for best results. See Installing the GNU Compiler Collection.

GNU autotools Required (or cmake) automake-1.11.1 or later; autoconf-2.59 or later; libtool-1.5.6 or later automake-1.11.1, autoconf-2.67, libtool-2.2.6b

Automake, autoconf, and libtool are used to configure ROSE and generate makefiles. You can install either this dependency or the cmake dependency. See Installing GNU Autotools.

CMake Required (or autotools) 2.8.12 or later 2.8.12

Configures ROSE and generates makefiles. You can install either this dependency or the GNU autotools. See Installing CMake.

Flex and bison Required Any recent version flex-2.5.35, bison-2.4.1

Generates code for lexical analyzers and parsers. See Installing flex and bison..

Java Virtual Machine Required Sun/Oracle version 7 1.7.0_51

Runtime for Java and Fortran frontends in ROSE. See Installing the Java runtime environment.

Java Development Kit Required (cmake) Any version 7 OpenJDK 7

A JDK is required when configuring ROSE with cmake, even if the Java and Fortran frontends are disabled. See Installing the Java development kit. Avoid Sun/Oracle version 1.7.0_25.

Python Required 3 3.1.3

ATerm support in ROSE when using autoconf regardless of whether such support is enabled. See Installing Python.

Boost Required 1.51 through 1.61, except 1.54 1.51 through 1.61, except 1.54

C++ portable runtime features. ROSE and/or software used by ROSE requires the following Boost libraries: chrono, date_time, filesystem, iostreams, program_options, random, regex, signals, system, thread, and wave. See Installing Boost. More info here.

Doxygen Optional 1.8.1 through 1.8.10 1.8.1

Generates local copies of the online documentation. See Installing Doxygen.

GraphViz Optional Any recent version ?

For visualizing graphs such as control flow graphs. See Installing GraphViz.

ZGRViewer Optional Any recent version ?

A free Java program for interactive visualization of graphs, supporting features like zooming and panning. See Installing ZGRViewer.

LaTeX Optional Any recent version pdfTeX 3.1415926

For generating PDF documentation from TeX/LaTeX sources.

dot2tex Optional Any recent version ?

Generates TeX versions of graphs for inclusion into documentation.

Qt Optional 4 4

For building ROSE's tools that have a graphical user interface. See Installing Qt.

GraphicsMagick Optional ? ?

See Installing GraphicsMagick.

Relational database system Optional SQLite3 and/or PostgreSQL SQLite-3.7.3; libpqxx-3.0; postgresql-8.4

For tools that store results in a database. See Installing a Relational Database Management System.

GNU readline Optional ? ?

For command-line editing in interactive tools. See Installing GNU readline.

libmagic Optional 3 3

For identifying magic numbers in binary analysis. See Installing libmagic.

yaml-cpp Optional 0.5.1 through 0.5.3 0.5.1 through 0.5.3

For reading YAML or JSON configuration files and storing results. Yaml-cpp must be compiled against the same version of boost used by ROSE. See Installing YAML-cpp.

Dlib Optional 18.11 - 18.18 18.11 - 18.18

For certain binary analysis algorithms. See Installing Dlib.

Wt Optional 3.3.3 through 3.3.5 3.3.3 through 3.3.5

For binary analysis tools that present results through a web server. Wt must be compiled against the same version of Boost used by ROSE. See Installing Wt.

Yices Optional 1.0.34 1.0.34

An SMT solver used by certain binary analysis algorithms.

Cryptography libs Optional libssl, libxml-2, libgcrypt-11 libxml-2; libgcrypt-11

For various analysis algorithms that use cryptographic functions. See Installing cryptography libraries.

libxml2 Optional Any recent version ?

For parsing XML files in certain tools such as roseHPCT and BinaryContextLookup. See Installing libxml2.

MPI Optional ? ?

For features in ROSE that allow for distributed parallel AST traversals.

Haskell compiler Optional ghc-6.10.x ghc-? For ROSE API Haskell bindings so that tools can be written in Haskell. ROSE does not parse or support source-to-source analysis and transformation of the Haskell language. See Installing Haskell.

Configuring ROSE

ROSE must be configured before it can be built. Two mechanisms are supported: GNU autotools and CMake. Most tests, tools, and projects can only be built with autotools at this time (Sep 2015). Both methods boil down to running some configuration step that detects (or is told) what optional software is available, and this produces a set of makefiles for building ROSE.

In the instructions that follow, "$ROSE_SRC" is the top-level directory holding the ROSE source code, and "$ROSE_BLD" is a build directory that these instructions have you create to hold files generated during the build.

Configuring with GNU autotools

If you desire to configure ROSE with GNU autotools instead of CMake, follow these steps:

ROSE_SRC=/absolute/path/to/the/rose/source/tree
BOOST_ROOT=/path/to/my/boost/installation/directory
export LD_LIBRARY_PATH="$BOOST_ROOT/lib:$LD_LIBRARY_PATH"
cd $ROSE_BLD
$ROSE_SRC/configure --prefix=$HOME/my-rose-installation --enable-languages=c,c++ --with-boost=$BOOST_ROOT

Configuring with CMake

If you desire to configure ROSE with CMake instead of GNU autotools, Follow these steps:

cd $ROSE_BLD
ROSE_SRC=../relative/path/to/the/rose/source/tree
BOOST_ROOT=/path/to/my/boost/installation/directory
export LD_LIBRARY_PATH="$BOOST_ROOT/lib:$LD_LIBRARY_PATH"
cmake $ROSE_SRC -DCMAKE_INSTALL_PREFIX=$HOME/my-rose-installation -DBOOST_ROOT=$BOOST_ROOT

Building the library

To build and install the ROSE library, run "cd $ROSE_BLD" and then "make install-rose-library" (equivalently, "make -C $ROSE_BLD install-rose-library"). If you run "make" without specifying the "install-rose-library" target then additional tests, projects, and tutorials are also built. Projects are typically not tested to the same degree as the core library. You may specify an amount of parallelism with make's "-j N" switch. Ensure that your machine meets the minimum hardware requirements before starting. A parallel build will require more than the minimum.

If you encounter errors about downloading EDG binary tarballs, see Installing EDG.

If you modify a ROSE header file then run "make -C $ROSE_BLD clean" before rebuilding if you're using GNU automake (not necessary for CMake).

If you're installing a different version of ROSE (or you've made modifications and are re-running "make install"), it is prudent to first remove the original installation directory to prevent the new installation from containing a mix of old and new versions.

The "check" targets in the makefiles run a variety of tests, most of which are also run by the automated continuous integration and release testing.

Using the library

Once the ROSE library has been configured, built, and installed it can be used. Any program that uses ROSE will likely need to be compiled with the same switches and software components as ROSE itself. The easiest way to get this information is by running "rose-config --help".

Here's an example makefile:

1 # Sample makefile for programs that use the ROSE library.
2 #
3 # ROSE has a number of configuration details that must be present when
4 # compiling and linking a user program with ROSE, and some of these
5 # details are difficult to get right. The most foolproof way to get
6 # these details into your own makefile is to use the "rose-config"
7 # tool.
8 #
9 #
10 # This makefile assumes:
11 # 1. The ROSE library has been properly installed (refer to the
12 # documentation for configuring, building, and installing ROSE).
13 #
14 # 2. The top of the installation directory is $(ROSE_INSTALLED). This
15 # is the same directory you specified for the "--prefix" argument
16 # of the "configure" script, or the "CMAKE_INSTALL_PREFIX" if using
17 # cmake. E.g., "/usr/local".
18 #
19 # The "rose-config" tool currently only works for ROSE configured with
20 # GNU auto tools (e.g., you ran "configure" when you built and
21 # installed ROSE). The "cmake" configuration is not currently
22 # supported by "rose-config" [September 2015].
23 ##############################################################################
24 
25 # Standard C++ compiler stuff (see rose-config --help)
26 CXX = $(shell $(ROSE_INSTALLED)/bin/rose-config cxx)
27 CPPFLAGS = $(shell $(ROSE_INSTALLED)/bin/rose-config cppflags)
28 CXXFLAGS = $(shell $(ROSE_INSTALLED)/bin/rose-config cxxflags)
29 LDFLAGS = $(shell $(ROSE_INSTALLED)/bin/rose-config ldflags)
30 LIBDIRS = $(shell $(ROSE_INSTALLED)/bin/rose-config libdirs)
31 
32 MOSTLYCLEANFILES =
33 
34 ##############################################################################
35 # Assuming your source code is "demo.C" to build an executable named "demo".
36 
37 all: demo
38 
39 demo.o: demo.C
40  $(CXX) $(CPPFLAGS) $(CXXFLAGS) -o $@ -c $^
41 
42 demo: demo.o
43  $(CXX) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
44  @echo "Remember to set:"
45  @echo " LD_LIBRARY_PATH=$(LIBDIRS):$$LD_LIBRARY_PATH"
46 
47 MOSTLYCLEANFILES += demo demo.o
48 
49 ##############################################################################
50 # Standard boilerplate
51 
52 .PHONY: clean
53 clean:
54  rm -f $(MOSTLYCLEANFILES)

Next steps

If you're interested in source code analysis or source-to-source translation, read the ROSE tutorial. If you're interested in binary analysis try Binary analysis tutorial.

This page is generated from $ROSE/docs/Rose/Installation/100_Installation.dox