SAFECode Install Guide

Written by the LLVM Research Group

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:

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, first follow the directions for installing libLTO in the LLVM Gold Plugin document (http://llvm.org/docs/GoldPlugin.html). Briefly, you will need to compile new versions of the ld, nm, and ar utilities if the versions on your machine do not support the Gold plugin, and your LLVM source tree will be configured to build the gold plugin (LLVMGold.so).

If you used make install in the SAFECode object tree to install Clang, then SAFECode's libLTO.so and LLVM's LLVMGold.so plugins should already be installed in Clang's installation directory and should be ready to use. To verify that they have been installed, look for them in PREFIX/lib where PREFIX is the location into which you installed SAFECode.

If you are using Clang from within the LLVM object tree, you will need to copy SAFECode's libLTO.so over the libLTO.so built in the LLVM object tree. Assuming you performed a Debug build, the commands would be: