SAFECode Install Guide

Written by the LLVM Research Group. Includes text from LLVM contributors which is licensed under the University of Illinois/NCSA Open Source license.

Overview

Welcome to the SAFECode compiler! This manual provides instructions for downloading and compiling SAFECode. It also provides information on software that you must have in order to install SAFECode.

Requirements
Software and Build Tool Dependencies

SAFECode depends upon several other pieces of software. SAFECode is built using the LLVM Compiler Infrastructure, so you must have LLVM. SAFECode also uses libraries from the Automatic Pool Allocation project. Directions on how to download these will be provided with the directions on downloading SAFECode.

SAFECode comes pre-compiled for some architectures, but the best way to get it is as as source code. If building from source, you will need the proper tools (namely GCC and GNU make) to compile it. The necessary requirements are those needed by LLVM and are listed here.

Supported Platforms

SAFECode is currently supported on Linux and Mac OS X running on x86 processors.

Getting the Source Code

There are two ways to get SAFECode: downloading the tar archive or downloading it from the public Subversion repository.

Source TAR Archive

Complete source TAR archives of SAFECode can be found here. These archives include LLVM as well as the Automatic Pool Allocation and SAFECode projects located within the llvm/projects directory. You will need GNU Zip (gunzip) and the tar utility (tar) to unpack the archive (these are available on practically all Unix systems today).

Subversion Repository Download

SAFECode, the Automatic Pool Allocation project, and LLVM are all stored in the public Subversion repository at llvm.org. You can retrieve the source code for these projects using a standard Subversion client as described below.

By default, you should put Automatic Pool Allocation and SAFECode into the projects subdirectory of the LLVM source distribution. The following commands should download all of the source code into the appropriate places (note that, in this example, we are grabbing the version of SAFECode from the release_32 branch which works with LLVM 3.2):

You may optionally want to get the LLVM Test Suite (test-suite) source code:

If you use the LLVM Test Suite, you will also need the LLVM GCC front-end, and you will need to configure LLVM so that it knows where to find llvm-gcc and llvm-g++. Directions for downloading and installing the front-end can be found in the LLVM Getting Started Guide .

Configuring the Source Code

Once you have the source code checked out, you should be able to configure LLVM, the poolalloc project, and the SAFECode project using just the top level LLVM configure script (the LLVM configure script configures the poolalloc and safecode projects automatically if they're present in the projects subdirectory). Simply configure LLVM as you normally would (e.g., run ./configure in the LLVM source tree), and SAFECode will be configured automatically for you.

If you have any problems configuring SAFECode (or you're doing something unconventional), you can try adding the following options to the command line when running configure:

Additional options for the SAFECode configure script include:

The overall process will look like the following if you are building Automatic Pool Allocation and SAFECode in the the projects subdirectory of the LLVM object tree:
Compiling SAFECode

To build SAFECode, first compile the LLVM tools and then SAFECode itself:

SAFECode will, by default, perform the same type of build that LLVM does. For example, if LLVM is configured to do a Release build by default, SAFECode will do a Release build by default as well. There are three types of builds:

If you only want to use SAFECode, use a Release build. If you are doing development work on SAFECode, use the Debug or Profile builds as appropriate.

Installing SAFECode
Installing the SAFECode Compiler

Once SAFECode has been built, you can install it using the following commands:

Like LLVM, installing SAFECode is not necessary for using it; however, performing the installation may place the SAFECode binaries and libraries into directories that are more convenient. By default, clang and clang++ are installed into /usr/local/bin, and the libraries are installed in /usr/local/lib; however, these locations can be changed by using the --prefix option to the LLVM configure script.

Installing the SAFECode Link-Time Optimizer (Optional)

SAFECode uses a set of whole program analysis techniques to make its run-time checks more stringent and to optimize away unneeded run-time checks. To perform whole-program analysis, SAFECode provides a replacement libLTO plugin for the linker that performs these analyses and transformations.

Installing SAFECode's libLTO plugin is not necessary for using SAFECode, but it will make SAFECode's run-time checks more thorough, so you will want to install it if you can.

The install instructions differ based on platform:

Mac OS X:
For Mac OS X, you simply need to backup the original LTO plugin (/usr/lib/libLTO.dylib) and replace it with the one from the SAFECode build (this will, sadly, require root access). To do that, do the following: Linux:
For Linux, you will need to install new, LTO-compatible versions of the ld, nm, and ar utilities. You will then need to configure, compile, and install LLVM and SAFECode. More specifically, you will need to do the following:
  1. Select a directory into which all the tools will be installed
    It will be much easier to use libLTO if you install all the software into a directory. Call this directory $PREFIX.

  2. Build LTO-compatible versions of ld, nm, and ar
    The directions to build LTO-compatible versions of ld, nm, and ar are found in the LLVM Gold Plugin document at http://llvm.org/docs/GoldPlugin.html. However, you will want to install all of binutils into $PREFIX; to do that, make sure to add a --prefix=$PREFIX option to the configure command line and use "make install" instead of "make all-gold." In other words, you will want to do the following:
    • mkdir binutils
    • cd binutils
    • cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
    • {enter "anoncvs" as the password}
    • cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
    • mkdir build
    • cd build
    • ../src/configure --prefix=$PREFIX --enable-gold --enable-plugins
    • make
    • make install

  3. Configure, Build, and Install LLVM and SAFECode
    You will need to tell LLVM where to find the Binutils header files, and you will need to configure it to install into the same directory as Binutils:
    • cd LLVM-object-directory
    • LLVM-source-directory/configure --prefix=$PREFIX --with-binutils-include=/path/to/binutils/src/include [additional options]
    • make install
    • cd projects/poolalloc
    • make install
    • cd ../safecode
    • make install

  4. Switch the Linker to the Gold Linker
    By default, Binutils will create three files: $PREFIX/bin/ld, $PREFIX/bin/ld.bfd, and $PREFIX/bin/ld.gold. You need to change $PREFIX/bin/ld so that it is a hard link to $PREFIX/bin/ld.bfd:
    • rm $PREFIX/bin/ld
    • ln $PREFIX/bin/ld.gold $PREFIX/bin/ld

  5. Change your $PATH so that $PREFIX/bin is first
    Now that everything is installed, change your $PATH environment variable so that $PREFIX/bin is the first directory that is searched. This will make SAFECode's clang and SAFECode's libLTO the default ones that are used.

With all of that done, you should now have a working SAFECode with libLTO installation on your system.