path: root/docs/GettingStarted.rst

.. _getting_started:

====================================
Getting Started with the LLVM System  
====================================

Overview
========

Welcome to LLVM! In order to get started, you first need to know some basic
information.

First, LLVM comes in three pieces. The first piece is the LLVM suite. This
contains all of the tools, libraries, and header files needed to use LLVM.  It
contains an assembler, disassembler, bitcode analyzer and bitcode optimizer.  It
also contains basic regression tests that can be used to test the LLVM tools and
the Clang front end.

The second piece is the `Clang <http://clang.llvm.org/>`_ front end.  This
component compiles C, C++, Objective C, and Objective C++ code into LLVM
bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the
LLVM tools from the LLVM suite.

There is a third, optional piece called Test Suite.  It is a suite of programs
with a testing harness that can be used to further test LLVM's functionality
and performance.

Getting Started Quickly (A Summary)
===================================

The LLVM Getting Started documentation may be out of date.  So, the `Clang
Getting Started <http://clang.llvm.org/get_started.html>`_ page might also be a
good place to start.

Here's the short story for getting up and running quickly with LLVM:

#. Read the documentation.
#. Read the documentation.
#. Remember that you were warned twice about reading the documentation.
#. Checkout LLVM:

   * ``cd where-you-want-llvm-to-live``
   * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``

#. Checkout Clang:

   * ``cd where-you-want-llvm-to-live``
   * ``cd llvm/tools``
   * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``

#. Checkout Compiler-RT:

   * ``cd where-you-want-llvm-to-live``
   * ``cd llvm/projects``
   * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``

#. Get the Test Suite Source Code **[Optional]**

   * ``cd where-you-want-llvm-to-live``
   * ``cd llvm/projects``
   * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite``

#. Configure and build LLVM and Clang:

   * ``cd where-you-want-to-build-llvm``
   * ``mkdir build`` (for building without polluting the source dir)
   * ``cd build``
   * ``../llvm/configure [options]``
     Some common options:

     * ``--prefix=directory`` ---

       Specify for *directory* the full pathname of where you want the LLVM
       tools and libraries to be installed (default ``/usr/local``).

     * ``--enable-optimized`` ---

       Compile with optimizations enabled (default is NO).

     * ``--enable-assertions`` ---

       Compile with assertion checks enabled (default is YES).

   * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
     simultaneously.  This builds both LLVM and Clang for Debug+Asserts mode.
     The --enabled-optimized configure option is used to specify a Release
     build.

   * ``make check-all`` --- This run the regression tests to ensure everything
     is in working order.
  
   * ``make update`` --- This command is used to update all the svn repositories
     at once, rather then having to ``cd`` into the individual repositories and
     running ``svn update``.

   * It is also possible to use CMake instead of the makefiles. With CMake it is
     possible to generate project files for several IDEs: Xcode, Eclipse CDT4,
     CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.

   * If you get an "internal compiler error (ICE)" or test failures, see
     `below`.

Consult the `Getting Started with LLVM`_ section for detailed information on
configuring and compiling LLVM.  See `Setting Up Your Environment`_ for tips
that simplify working with the Clang front end and LLVM tools.  Go to `Program
Layout`_ to learn about the layout of the source code tree.

Requirements
============

Before you begin to use the LLVM system, review the requirements given below.
This may save you some trouble by knowing ahead of time what hardware and
software you will need.

Hardware
--------

LLVM is known to work on the following platforms:

+-----------------+----------------------+-------------------------+
|OS               |  Arch                | Compilers               |
+=================+======================+=========================+
|AuroraUX         | x86\ :sup:`1`        | GCC                     |
+-----------------+----------------------+-------------------------+
|Linux            | x86\ :sup:`1`        | GCC                     |
+-----------------+----------------------+-------------------------+
|Linux            | amd64                | GCC                     |
+-----------------+----------------------+-------------------------+
|Solaris          | V9 (Ultrasparc)      | GCC                     |
+-----------------+----------------------+-------------------------+
|FreeBSD          | x86\ :sup:`1`        | GCC                     |
+-----------------+----------------------+-------------------------+
|FreeBSD          | amd64                | GCC                     |
+-----------------+----------------------+-------------------------+
|MacOS X\ :sup:`2`| PowerPC              | GCC                     |
+-----------------+----------------------+-------------------------+
|MacOS X\ :sup:`9`| x86                  | GCC                     |
+-----------------+----------------------+-------------------------+
|Cygwin/Win32     | x86\ :sup:`1, 8, 11` | GCC 3.4.X, binutils 2.20|
+-----------------+----------------------+-------------------------+

LLVM has partial support for the following platforms:

+-------------------+----------------------+-------------------------------------------+
|OS                 |  Arch                | Compilers                                 |
+===================+======================+===========================================+
| Windows           | x86\ :sup:`1`        | Visual Studio 2000 or higher\ :sup:`4,5`  |
+-------------------+----------------------+-------------------------------------------+
| AIX\ :sup:`3,4`   | PowerPC              | GCC                                       |
+-------------------+----------------------+-------------------------------------------+
| Linux\ :sup:`3,5` | PowerPC              | GCC                                       |
+-------------------+----------------------+-------------------------------------------+
| Linux\ :sup:`7`   | Alpha                | GCC                                       |
+-------------------+----------------------+-------------------------------------------+
| Linux\ :sup:`7`   | Itanium (IA-64)      | GCC                                       |
+-------------------+----------------------+-------------------------------------------+
| HP-UX\ :sup:`7`   | Itanium (IA-64)      | HP aCC                                    |
+-------------------+--------------------