1==================================== 2Getting Started with the LLVM System 3==================================== 4 5.. contents:: 6 :local: 7 8Overview 9======== 10 11Welcome to LLVM! In order to get started, you first need to know some basic 12information. 13 14First, LLVM comes in three pieces. The first piece is the LLVM suite. This 15contains all of the tools, libraries, and header files needed to use LLVM. It 16contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It 17also contains basic regression tests that can be used to test the LLVM tools and 18the Clang front end. 19 20The second piece is the `Clang <http://clang.llvm.org/>`_ front end. This 21component compiles C, C++, Objective C, and Objective C++ code into LLVM 22bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the 23LLVM tools from the LLVM suite. 24 25There is a third, optional piece called Test Suite. It is a suite of programs 26with a testing harness that can be used to further test LLVM's functionality 27and performance. 28 29Getting Started Quickly (A Summary) 30=================================== 31 32The LLVM Getting Started documentation may be out of date. So, the `Clang 33Getting Started <http://clang.llvm.org/get_started.html>`_ page might also be a 34good place to start. 35 36Here's the short story for getting up and running quickly with LLVM: 37 38#. Read the documentation. 39#. Read the documentation. 40#. Remember that you were warned twice about reading the documentation. 41#. Checkout LLVM: 42 43 * ``cd where-you-want-llvm-to-live`` 44 * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 45 46#. Checkout Clang: 47 48 * ``cd where-you-want-llvm-to-live`` 49 * ``cd llvm/tools`` 50 * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang`` 51 52#. Checkout Compiler-RT: 53 54 * ``cd where-you-want-llvm-to-live`` 55 * ``cd llvm/projects`` 56 * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt`` 57 58#. Get the Test Suite Source Code **[Optional]** 59 60 * ``cd where-you-want-llvm-to-live`` 61 * ``cd llvm/projects`` 62 * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite`` 63 64#. Configure and build LLVM and Clang: 65 66 * ``cd where-you-want-to-build-llvm`` 67 * ``mkdir build`` (for building without polluting the source dir) 68 * ``cd build`` 69 * ``../llvm/configure [options]`` 70 Some common options: 71 72 * ``--prefix=directory`` --- Specify for *directory* the full pathname of 73 where you want the LLVM tools and libraries to be installed (default 74 ``/usr/local``). 75 76 * ``--enable-optimized`` --- Compile with optimizations enabled (default 77 is NO). 78 79 * ``--enable-assertions`` --- Compile with assertion checks enabled 80 (default is YES). 81 82 * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run 83 simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. 84 The ``--enable-optimized`` configure option is used to specify a Release 85 build. 86 87 * ``make check-all`` --- This run the regression tests to ensure everything 88 is in working order. 89 90 * It is also possible to use `CMake <CMake.html>`_ instead of the makefiles. 91 With CMake it is possible to generate project files for several IDEs: 92 Xcode, Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks 93 generator), KDevelop3. 94 95 * If you get an "internal compiler error (ICE)" or test failures, see 96 `below`. 97 98Consult the `Getting Started with LLVM`_ section for detailed information on 99configuring and compiling LLVM. See `Setting Up Your Environment`_ for tips 100that simplify working with the Clang front end and LLVM tools. Go to `Program 101Layout`_ to learn about the layout of the source code tree. 102 103Requirements 104============ 105 106Before you begin to use the LLVM system, review the requirements given below. 107This may save you some trouble by knowing ahead of time what hardware and 108software you will need. 109 110Hardware 111-------- 112 113LLVM is known to work on the following host platforms: 114 115================== ===================== ============= 116OS Arch Compilers 117================== ===================== ============= 118Linux x86\ :sup:`1` GCC, Clang 119Linux amd64 GCC, Clang 120Linux ARM\ :sup:`4` GCC, Clang 121Linux PowerPC GCC, Clang 122Solaris V9 (Ultrasparc) GCC 123FreeBSD x86\ :sup:`1` GCC, Clang 124FreeBSD amd64 GCC, Clang 125MacOS X\ :sup:`2` PowerPC GCC 126MacOS X x86 GCC, Clang 127Cygwin/Win32 x86\ :sup:`1, 3` GCC 128Windows x86\ :sup:`1` Visual Studio 129Windows x64 x86-64 Visual Studio 130================== ===================== ============= 131 132.. note:: 133 134 #. Code generation supported for Pentium processors and up 135 #. Code generation supported for 32-bit ABI only 136 #. To use LLVM modules on Win32-based system, you may configure LLVM 137 with ``--enable-shared``. 138 #. MCJIT not working well pre-v7, old JIT engine not supported any more. 139 140Note that you will need about 1-3 GB of space for a full LLVM build in Debug 141mode, depending on the system (it is so large because of all the debugging 142information and the fact that the libraries are statically linked into multiple 143tools). If you do not need many of the tools and you are space-conscious, you 144can pass ``ONLY_TOOLS="tools you need"`` to make. The Release build requires 145considerably less space. 146 147The LLVM suite *may* compile on other platforms, but it is not guaranteed to do 148so. If compilation is successful, the LLVM utilities should be able to 149assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation 150should work as well, although the generated native code may not work on your 151platform. 152 153Software 154-------- 155 156Compiling LLVM requires that you have several software packages installed. The 157table below lists those required packages. The Package column is the usual name 158for the software package that LLVM depends on. The Version column provides 159"known to work" versions of the package. The Notes column describes how LLVM 160uses the package and provides other details. 161 162=========================================================== ============ ========================================== 163Package Version Notes 164=========================================================== ============ ========================================== 165`GNU Make <http://savannah.gnu.org/projects/make>`_ 3.79, 3.79.1 Makefile/build processor 166`GCC <http://gcc.gnu.org/>`_ >=4.7.0 C/C++ compiler\ :sup:`1` 167`python <http://www.python.org/>`_ >=2.7 Automated test suite\ :sup:`2` 168`GNU M4 <http://savannah.gnu.org/projects/m4>`_ 1.4 Macro processor for configuration\ :sup:`3` 169`GNU Autoconf <http://www.gnu.org/software/autoconf/>`_ 2.60 Configuration script builder\ :sup:`3` 170`GNU Automake <http://www.gnu.org/software/automake/>`_ 1.9.6 aclocal macro generator\ :sup:`3` 171`libtool <http://savannah.gnu.org/projects/libtool>`_ 1.5.22 Shared library manager\ :sup:`3` 172`zlib <http://zlib.net>`_ >=1.2.3.4 Compression library\ :sup:`4` 173=========================================================== ============ ========================================== 174 175.. note:: 176 177 #. Only the C and C++ languages are needed so there's no need to build the 178 other languages for LLVM's purposes. See `below` for specific version 179 info. 180 #. Only needed if you want to run the automated test suite in the 181 ``llvm/test`` directory. 182 #. If you want to make changes to the configure scripts, you will need GNU 183 autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You 184 will also need automake (1.9.6). We only use aclocal from that package. 185 #. Optional, adds compression / uncompression capabilities to selected LLVM 186 tools. 187 188Additionally, your compilation host is expected to have the usual plethora of 189Unix utilities. Specifically: 190 191* **ar** --- archive library builder 192* **bzip2** --- bzip2 command for distribution generation 193* **bunzip2** --- bunzip2 command for distribution checking 194* **chmod** --- change permissions on a file 195* **cat** --- output concatenation utility 196* **cp** --- copy files 197* **date** --- print the current date/time 198* **echo** --- print to standard output 199* **egrep** --- extended regular expression search utility 200* **find** --- find files/dirs in a file system 201* **grep** --- regular expression search utility 202* **gzip** --- gzip command for distribution generation 203* **gunzip** --- gunzip command for distribution checking 204* **install** --- install directories/files 205* **mkdir** --- create a directory 206* **mv** --- move (rename) files 207* **ranlib** --- symbol table builder for archive libraries 208* **rm** --- remove (delete) files and directories 209* **sed** --- stream editor for transforming output 210* **sh** --- Bourne shell for make build scripts 211* **tar** --- tape archive for distribution generation 212* **test** --- test things in file system 213* **unzip** --- unzip command for distribution checking 214* **zip** --- zip command for distribution generation 215 216.. _below: 217.. _check here: 218 219Host C++ Toolchain, both Compiler and Standard Library 220------------------------------------------------------ 221 222LLVM is very demanding of the host C++ compiler, and as such tends to expose 223bugs in the compiler. We are also planning to follow improvements and 224developments in the C++ language and library reasonably closely. As such, we 225require a modern host C++ toolchain, both compiler and standard library, in 226order to build LLVM. 227 228For the most popular host toolchains we check for specific minimum versions in 229our build systems: 230 231* Clang 3.1 232* GCC 4.7 233* Visual Studio 2012 234 235Anything older than these toolchains *may* work, but will require forcing the 236build system with a special option and is not really a supported host platform. 237Also note that older versions of these compilers have often crashed or 238miscompiled LLVM. 239 240For less widely used host toolchains such as ICC or xlC, be aware that a very 241recent version may be required to support all of the C++ features used in LLVM. 242 243We track certain versions of software that are *known* to fail when used as 244part of the host toolchain. These even include linkers at times. 245 246**GCC 4.6.3 on ARM**: Miscompiles ``llvm-readobj`` at ``-O3``. A test failure 247in ``test/Object/readobj-shared-object.test`` is one symptom of the problem. 248 249**GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long 250warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was 251defined in a discarded section. You can safely ignore these messages as they are 252erroneous and the linkage is correct. These messages disappear using ld 2.17. 253 254**GNU binutils 2.17**: Binutils 2.17 contains `a bug 255<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link 256times (minutes instead of seconds) when building LLVM. We recommend upgrading 257to a newer version (2.17.50.0.4 or later). 258 259**GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug 260<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes 261intermittent failures when building LLVM with position independent code. The 262symptom is an error about cyclic dependencies. We recommend upgrading to a 263newer version of Gold. 264 265**Clang 3.0 with libstdc++ 4.7.x**: a few Linux distributions (Ubuntu 12.10, 266Fedora 17) have both Clang 3.0 and libstdc++ 4.7 in their repositories. Clang 2673.0 does not implement a few builtins that are used in this library. We 268recommend using the system GCC to compile LLVM and Clang in this case. 269 270**Clang 3.0 on Mageia 2**. There's a packaging issue: Clang can not find at 271least some (``cxxabi.h``) libstdc++ headers. 272 273**Clang in C++11 mode and libstdc++ 4.7.2**. This version of libstdc++ 274contained `a bug <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53841>`__ which 275causes Clang to refuse to compile condition_variable header file. At the time 276of writing, this breaks LLD build. 277 278Getting a Modern Host C++ Toolchain 279^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 280 281This section mostly applies to Linux and older BSDs. On Mac OS X, you should 282have a sufficiently modern Xcode, or you will likely need to upgrade until you 283do. On Windows, just use Visual Studio 2012 as the host compiler, it is 284explicitly supported and widely available. FreeBSD 10.0 and newer have a modern 285Clang as the system compiler. 286 287However, some Linux distributions and some other or older BSDs sometimes have 288extremely old versions of GCC. These steps attempt to help you upgrade you 289compiler even on such a system. However, if at all possible, we encourage you 290to use a recent version of a distribution with a modern system compiler that 291meets these requirements. Note that it is tempting to to install a prior 292version of Clang and libc++ to be the host compiler, however libc++ was not 293well tested or set up to build on Linux until relatively recently. As 294a consequence, this guide suggests just using libstdc++ and a modern GCC as the 295initial host in a bootstrap, and then using Clang (and potentially libc++). 296 297The first step is to get a recent GCC toolchain installed. The most common 298distribution on which users have struggled with the version requirements is 299Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install 300the `toolchain testing PPA`_ and use it to install a modern GCC. There is 301a really nice discussions of this on the `ask ubuntu stack exchange`_. However, 302not all users can use PPAs and there are many other distributions, so it may be 303necessary (or just useful, if you're here you *are* doing compiler development 304after all) to build and install GCC from source. It is also quite easy to do 305these days. 306 307.. _toolchain testing PPA: 308 https://launchpad.net/~ubuntu-toolchain-r/+archive/test 309.. _ask ubuntu stack exchange: 310 http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal 311 312Easy steps for installing GCC 4.8.2: 313 314.. code-block:: console 315 316 % wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2 317 % tar -xvjf gcc-4.8.2.tar.bz2 318 % cd gcc-4.8.2 319 % ./contrib/download_prerequisites 320 % cd .. 321 % mkdir gcc-4.8.2-build 322 % cd gcc-4.8.2-build 323 % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++ 324 % make -j$(nproc) 325 % make install 326 327For more details, check out the excellent `GCC wiki entry`_, where I got most 328of this information from. 329 330.. _GCC wiki entry: 331 http://gcc.gnu.org/wiki/InstallingGCC 332 333Once you have a GCC toolchain, configure your build of LLVM to use the new 334toolchain for your host compiler and C++ standard library. Because the new 335version of libstdc++ is not on the system library search path, you need to pass 336extra linker flags so that it can be found at link time (``-L``) and at runtime 337(``-rpath``). If you are using CMake, this invocation should produce working 338binaries: 339 340.. code-block:: console 341 342 % mkdir build 343 % cd build 344 % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \ 345 cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64" 346 347If you fail to set rpath, most LLVM binaries will fail on startup with a message 348from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not 349found``. This means you need to tweak the -rpath linker flag. 350 351When you build Clang, you will need to give *it* access to modern C++11 352standard library in order to use it as your new host in part of a bootstrap. 353There are two easy ways to do this, either build (and install) libc++ along 354with Clang and then use it with the ``-stdlib=libc++`` compile and link flag, 355or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC. 356Clang will look within its own prefix for libstdc++ and use it if found. You 357can also add an explicit prefix for Clang to look in for a GCC toolchain with 358the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and 359link commands when using your just-built-Clang to bootstrap. 360 361.. _Getting Started with LLVM: 362 363Getting Started with LLVM 364========================= 365 366The remainder of this guide is meant to get you up and running with LLVM and to 367give you some basic information about the LLVM environment. 368 369The later sections of this guide describe the `general layout`_ of the LLVM 370source tree, a `simple example`_ using the LLVM tool chain, and `links`_ to find 371more information about LLVM or to get help via e-mail. 372 373Terminology and Notation 374------------------------ 375 376Throughout this manual, the following names are used to denote paths specific to 377the local system and working environment. *These are not environment variables 378you need to set but just strings used in the rest of this document below*. In 379any of the examples below, simply replace each of these names with the 380appropriate pathname on your local system. All these paths are absolute: 381 382``SRC_ROOT`` 383 384 This is the top level directory of the LLVM source tree. 385 386``OBJ_ROOT`` 387 388 This is the top level directory of the LLVM object tree (i.e. the tree where 389 object files and compiled programs will be placed. It can be the same as 390 SRC_ROOT). 391 392.. _Setting Up Your Environment: 393 394Setting Up Your Environment 395--------------------------- 396 397In order to compile and use LLVM, you may need to set some environment 398variables. 399 400``LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs`` 401 402 [Optional] This environment variable helps LLVM linking tools find the 403 locations of your bitcode libraries. It is provided only as a convenience 404 since you can specify the paths using the -L options of the tools and the 405 C/C++ front-end will automatically use the bitcode files installed in its 406 ``lib`` directory. 407 408Unpacking the LLVM Archives 409--------------------------- 410 411If you have the LLVM distribution, you will need to unpack it before you can 412begin to compile it. LLVM is distributed as a set of two files: the LLVM suite 413and the LLVM GCC front end compiled for your platform. There is an additional 414test suite that is optional. Each file is a TAR archive that is compressed with 415the gzip program. 416 417The files are as follows, with *x.y* marking the version number: 418 419``llvm-x.y.tar.gz`` 420 421 Source release for the LLVM libraries and tools. 422 423``llvm-test-x.y.tar.gz`` 424 425 Source release for the LLVM test-suite. 426 427.. _checkout: 428 429Checkout LLVM from Subversion 430----------------------------- 431 432If you have access to our Subversion repository, you can get a fresh copy of the 433entire source code. All you need to do is check it out from Subversion as 434follows: 435 436* ``cd where-you-want-llvm-to-live`` 437* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 438* Read-Write:``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` 439 440This will create an '``llvm``' directory in the current directory and fully 441populate it with the LLVM source code, Makefiles, test directories, and local 442copies of documentation files. 443 444If you want to get a specific release (as opposed to the most recent revision), 445you can checkout it from the '``tags``' directory (instead of '``trunk``'). The 446following releases are located in the following subdirectories of the '``tags``' 447directory: 448 449* Release 3.4: **RELEASE_34/final** 450* Release 3.3: **RELEASE_33/final** 451* Release 3.2: **RELEASE_32/final** 452* Release 3.1: **RELEASE_31/final** 453* Release 3.0: **RELEASE_30/final** 454* Release 2.9: **RELEASE_29/final** 455* Release 2.8: **RELEASE_28** 456* Release 2.7: **RELEASE_27** 457* Release 2.6: **RELEASE_26** 458* Release 2.5: **RELEASE_25** 459* Release 2.4: **RELEASE_24** 460* Release 2.3: **RELEASE_23** 461* Release 2.2: **RELEASE_22** 462* Release 2.1: **RELEASE_21** 463* Release 2.0: **RELEASE_20** 464* Release 1.9: **RELEASE_19** 465* Release 1.8: **RELEASE_18** 466* Release 1.7: **RELEASE_17** 467* Release 1.6: **RELEASE_16** 468* Release 1.5: **RELEASE_15** 469* Release 1.4: **RELEASE_14** 470* Release 1.3: **RELEASE_13** 471* Release 1.2: **RELEASE_12** 472* Release 1.1: **RELEASE_11** 473* Release 1.0: **RELEASE_1** 474 475If you would like to get the LLVM test suite (a separate package as of 1.4), you 476get it from the Subversion repository: 477 478.. code-block:: console 479 480 % cd llvm/projects 481 % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite 482 483By placing it in the ``llvm/projects``, it will be automatically configured by 484the LLVM configure script as well as automatically updated when you run ``svn 485update``. 486 487Git Mirror 488---------- 489 490Git mirrors are available for a number of LLVM subprojects. These mirrors sync 491automatically with each Subversion commit and contain all necessary git-svn 492marks (so, you can recreate git-svn metadata locally). Note that right now 493mirrors reflect only ``trunk`` for each project. You can do the read-only Git 494clone of LLVM via: 495 496.. code-block:: console 497 498 % git clone http://llvm.org/git/llvm.git 499 500If you want to check out clang too, run: 501 502.. code-block:: console 503 504 % cd llvm/tools 505 % git clone http://llvm.org/git/clang.git 506 507If you want to check out compiler-rt too, run: 508 509.. code-block:: console 510 511 % cd llvm/projects 512 % git clone http://llvm.org/git/compiler-rt.git 513 514If you want to check out the Test Suite Source Code (optional), run: 515 516.. code-block:: console 517 518 % cd llvm/projects 519 % git clone http://llvm.org/git/test-suite.git 520 521Since the upstream repository is in Subversion, you should use ``git 522pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history 523in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the 524master branch, run the following command: 525 526.. code-block:: console 527 528 % git config branch.master.rebase true 529 530Sending patches with Git 531^^^^^^^^^^^^^^^^^^^^^^^^ 532 533Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too. 534 535Assume ``master`` points the upstream and ``mybranch`` points your working 536branch, and ``mybranch`` is rebased onto ``master``. At first you may check 537sanity of whitespaces: 538 539.. code-block:: console 540 541 % git diff --check master..mybranch 542 543The easiest way to generate a patch is as below: 544 545.. code-block:: console 546 547 % git diff master..mybranch > /path/to/mybranch.diff 548 549It is a little different from svn-generated diff. git-diff-generated diff has 550prefixes like ``a/`` and ``b/``. Don't worry, most developers might know it 551could be accepted with ``patch -p1 -N``. 552 553But you may generate patchset with git-format-patch. It generates by-each-commit 554patchset. To generate patch files to attach to your article: 555 556.. code-block:: console 557 558 % git format-patch --no-attach master..mybranch -o /path/to/your/patchset 559 560If you would like to send patches directly, you may use git-send-email or 561git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. 562 563.. code-block:: console 564 565 % git format-patch --attach master..mybranch --stdout | git imap-send 566 567Then, your .git/config should have [imap] sections. 568 569.. code-block:: ini 570 571 [imap] 572 host = imaps://imap.gmail.com 573 user = your.gmail.account@gmail.com 574 pass = himitsu! 575 port = 993 576 sslverify = false 577 ; in English 578 folder = "[Gmail]/Drafts" 579 ; example for Japanese, "Modified UTF-7" encoded. 580 folder = "[Gmail]/&Tgtm+DBN-" 581 ; example for Traditional Chinese 582 folder = "[Gmail]/&g0l6Pw-" 583 584For developers to work with git-svn 585^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 586 587To set up clone from which you can submit code using ``git-svn``, run: 588 589.. code-block:: console 590 591 % git clone http://llvm.org/git/llvm.git 592 % cd llvm 593 % git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username> 594 % git config svn-remote.svn.fetch :refs/remotes/origin/master 595 % git svn rebase -l # -l avoids fetching ahead of the git mirror. 596 597 # If you have clang too: 598 % cd tools 599 % git clone http://llvm.org/git/clang.git 600 % cd clang 601 % git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username> 602 % git config svn-remote.svn.fetch :refs/remotes/origin/master 603 % git svn rebase -l 604 605Likewise for compiler-rt and test-suite. 606 607To update this clone without generating git-svn tags that conflict with the 608upstream Git repo, run: 609 610.. code-block:: console 611 612 % git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. 613 % git checkout master 614 % git svn rebase -l 615 % (cd tools/clang && 616 git checkout master && 617 git svn rebase -l) 618 619Likewise for compiler-rt and test-suite. 620 621This leaves your working directories on their master branches, so you'll need to 622``checkout`` each working branch individually and ``rebase`` it on top of its 623parent branch. 624 625For those who wish to be able to update an llvm repo/revert patches easily using 626git-svn, please look in the directory for the scripts ``git-svnup`` and 627``git-svnrevert``. 628 629To perform the aforementioned update steps go into your source directory and 630just type ``git-svnup`` or ``git svnup`` and everything will just work. 631 632If one wishes to revert a commit with git-svn, but do not want the git hash to 633escape into the commit message, one can use the script ``git-svnrevert`` or 634``git svnrevert`` which will take in the git hash for the commit you want to 635revert, look up the appropriate svn revision, and output a message where all 636references to the git hash have been replaced with the svn revision. 637 638To commit back changes via git-svn, use ``git svn dcommit``: 639 640.. code-block:: console 641 642 % git svn dcommit 643 644Note that git-svn will create one SVN commit for each Git commit you have pending, 645so squash and edit each commit before executing ``dcommit`` to make sure they all 646conform to the coding standards and the developers' policy. 647 648On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict, 649please make sure your current branch is up-to-date (via fetch/rebase) before 650proceeding. 651 652The git-svn metadata can get out of sync after you mess around with branches and 653``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining 654about files with uncommitted changes. The fix is to rebuild the metadata: 655 656.. code-block:: console 657 658 % rm -rf .git/svn 659 % git svn rebase -l 660 661Please, refer to the Git-SVN manual (``man git-svn``) for more information. 662 663Local LLVM Configuration 664------------------------ 665 666Once checked out from the Subversion repository, the LLVM suite source code must 667be configured via the ``configure`` script. This script sets variables in the 668various ``*.in`` files, most notably ``llvm/Makefile.config`` and 669``llvm/include/Config/config.h``. It also populates *OBJ_ROOT* with the 670Makefiles needed to begin building LLVM. 671 672The following environment variables are used by the ``configure`` script to 673configure the build system: 674 675+------------+-----------------------------------------------------------+ 676| Variable | Purpose | 677+============+===========================================================+ 678| CC | Tells ``configure`` which C compiler to use. By default, | 679| | ``configure`` will check ``PATH`` for ``clang`` and GCC C | 680| | compilers (in this order). Use this variable to override | 681| | ``configure``\'s default behavior. | 682+------------+-----------------------------------------------------------+ 683| CXX | Tells ``configure`` which C++ compiler to use. By | 684| | default, ``configure`` will check ``PATH`` for | 685| | ``clang++`` and GCC C++ compilers (in this order). Use | 686| | this variable to override ``configure``'s default | 687| | behavior. | 688+------------+-----------------------------------------------------------+ 689 690The following options can be used to set or enable LLVM specific options: 691 692``--enable-optimized`` 693 694 Enables optimized compilation (debugging symbols are removed and GCC 695 optimization flags are enabled). Note that this is the default setting if you 696 are using the LLVM distribution. The default behavior of a Subversion 697 checkout is to use an unoptimized build (also known as a debug build). 698 699``--enable-debug-runtime`` 700 701 Enables debug symbols in the runtime libraries. The default is to strip debug 702 symbols from the runtime libraries. 703 704``--enable-jit`` 705 706 Compile the Just In Time (JIT) compiler functionality. This is not available 707 on all platforms. The default is dependent on platform, so it is best to 708 explicitly enable it if you want it. 709 710``--enable-targets=target-option`` 711 712 Controls which targets will be built and linked into llc. The default value 713 for ``target_options`` is "all" which builds and links all available targets. 714 The "host" target is selected as the target of the build host. You can also 715 specify a comma separated list of target names that you want available in llc. 716 The target names use all lower case. The current set of targets is: 717 718 ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430, 719 powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``. 720 721``--enable-doxygen`` 722 723 Look for the doxygen program and enable construction of doxygen based 724 documentation from the source code. This is disabled by default because 725 generating the documentation can take a long time and producess 100s of 726 megabytes of output. 727 728To configure LLVM, follow these steps: 729 730#. Change directory into the object root directory: 731 732 .. code-block:: console 733 734 % cd OBJ_ROOT 735 736#. Run the ``configure`` script located in the LLVM source tree: 737 738 .. code-block:: console 739 740 % SRC_ROOT/configure --prefix=/install/path [other options] 741 742Compiling the LLVM Suite Source Code 743------------------------------------ 744 745Once you have configured LLVM, you can build it. There are three types of 746builds: 747 748Debug Builds 749 750 These builds are the default when one is using a Subversion checkout and 751 types ``gmake`` (unless the ``--enable-optimized`` option was used during 752 configuration). The build system will compile the tools and libraries with 753 debugging information. To get a Debug Build using the LLVM distribution the 754 ``--disable-optimized`` option must be passed to ``configure``. 755 756Release (Optimized) Builds 757 758 These builds are enabled with the ``--enable-optimized`` option to 759 ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command 760 line. For these builds, the build system will compile the tools and libraries 761 with GCC optimizations enabled and strip debugging information from the 762 libraries and executables it generates. Note that Release Builds are default 763 when using an LLVM distribution. 764 765Profile Builds 766 767 These builds are for use with profiling. They compile profiling information 768 into the code for use with programs like ``gprof``. Profile builds must be 769 started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line. 770 771Once you have LLVM configured, you can build it by entering the *OBJ_ROOT* 772directory and issuing the following command: 773 774.. code-block:: console 775 776 % gmake 777 778If the build fails, please `check here`_ to see if you are using a version of 779GCC that is known not to compile LLVM. 780 781If you have multiple processors in your machine, you may wish to use some of the 782parallel build options provided by GNU Make. For example, you could use the 783command: 784 785.. code-block:: console 786 787 % gmake -j2 788 789There are several special targets which are useful when working with the LLVM 790source code: 791 792``gmake clean`` 793 794 Removes all files generated by the build. This includes object files, 795 generated C/C++ files, libraries, and executables. 796 797``gmake dist-clean`` 798 799 Removes everything that ``gmake clean`` does, but also removes files generated 800 by ``configure``. It attempts to return the source tree to the original state 801 in which it was shipped. 802 803``gmake install`` 804 805 Installs LLVM header files, libraries, tools, and documentation in a hierarchy 806 under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, which 807 defaults to ``/usr/local``. 808 809``gmake -C runtime install-bytecode`` 810 811 Assuming you built LLVM into $OBJDIR, when this command is run, it will 812 install bitcode libraries into the GCC front end's bitcode library directory. 813 If you need to update your bitcode libraries, this is the target to use once 814 you've built them. 815 816Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on 817these ``make`` targets and descriptions of other targets available. 818 819It is also possible to override default values from ``configure`` by declaring 820variables on the command line. The following are some examples: 821 822``gmake ENABLE_OPTIMIZED=1`` 823 824 Perform a Release (Optimized) build. 825 826``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` 827 828 Perform a Release (Optimized) build without assertions enabled. 829 830``gmake ENABLE_OPTIMIZED=0`` 831 832 Perform a Debug build. 833 834``gmake ENABLE_PROFILING=1`` 835 836 Perform a Profiling build. 837 838``gmake VERBOSE=1`` 839 840 Print what ``gmake`` is doing on standard output. 841 842``gmake TOOL_VERBOSE=1`` 843 844 Ask each tool invoked by the makefiles to print out what it is doing on 845 the standard output. This also implies ``VERBOSE=1``. 846 847Every directory in the LLVM object tree includes a ``Makefile`` to build it and 848any subdirectories that it contains. Entering any directory inside the LLVM 849object tree and typing ``gmake`` should rebuild anything in or below that 850directory that is out of date. 851 852This does not apply to building the documentation. 853LLVM's (non-Doxygen) documentation is produced with the 854`Sphinx <http://sphinx-doc.org/>`_ documentation generation system. 855There are some HTML documents that have not yet been converted to the new 856system (which uses the easy-to-read and easy-to-write 857`reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup 858language). 859The generated documentation is built in the ``SRC_ROOT/docs`` directory using 860a special makefile. 861For instructions on how to install Sphinx, see 862`Sphinx Introduction for LLVM Developers 863<http://lld.llvm.org/sphinx_intro.html>`_. 864After following the instructions there for installing Sphinx, build the LLVM 865HTML documentation by doing the following: 866 867.. code-block:: console 868 869 $ cd SRC_ROOT/docs 870 $ make -f Makefile.sphinx 871 872This creates a ``_build/html`` sub-directory with all of the HTML files, not 873just the generated ones. 874This directory corresponds to ``llvm.org/docs``. 875For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to 876``llvm.org/docs/SphinxQuickstartTemplate.html``. 877The :doc:`SphinxQuickstartTemplate` is useful when creating a new document. 878 879Cross-Compiling LLVM 880-------------------- 881 882It is possible to cross-compile LLVM itself. That is, you can create LLVM 883executables and libraries to be hosted on a platform different from the platform 884where they are built (a Canadian Cross build). To configure a cross-compile, 885supply the configure script with ``--build`` and ``--host`` options that are 886different. The values of these options must be legal target triples that your 887GCC compiler supports. 888 889The result of such a build is executables that are not runnable on on the build 890host (--build option) but can be executed on the compile host (--host option). 891 892Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general 893<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information 894about cross-compiling. 895 896The Location of LLVM Object Files 897--------------------------------- 898 899The LLVM build system is capable of sharing a single LLVM source tree among 900several LLVM builds. Hence, it is possible to build LLVM for several different 901platforms or configurations using the same source tree. 902 903This is accomplished in the typical autoconf manner: 904 905* Change directory to where the LLVM object files should live: 906 907 .. code-block:: console 908 909 % cd OBJ_ROOT 910 911* Run the ``configure`` script found in the LLVM source directory: 912 913 .. code-block:: console 914 915 % SRC_ROOT/configure 916 917The LLVM build will place files underneath *OBJ_ROOT* in directories named after 918the build type: 919 920Debug Builds with assertions enabled (the default) 921 922 Tools 923 924 ``OBJ_ROOT/Debug+Asserts/bin`` 925 926 Libraries 927 928 ``OBJ_ROOT/Debug+Asserts/lib`` 929 930Release Builds 931 932 Tools 933 934 ``OBJ_ROOT/Release/bin`` 935 936 Libraries 937 938 ``OBJ_ROOT/Release/lib`` 939 940Profile Builds 941 942 Tools 943 944 ``OBJ_ROOT/Profile/bin`` 945 946 Libraries 947 948 ``OBJ_ROOT/Profile/lib`` 949 950Optional Configuration Items 951---------------------------- 952 953If you're running on a Linux system that supports the `binfmt_misc 954<http://en.wikipedia.org/wiki/binfmt_misc>`_ 955module, and you have root access on the system, you can set your system up to 956execute LLVM bitcode files directly. To do this, use commands like this (the 957first command may not be required if you are already using the module): 958 959.. code-block:: console 960 961 % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc 962 % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register 963 % chmod u+x hello.bc (if needed) 964 % ./hello.bc 965 966This allows you to execute LLVM bitcode files directly. On Debian, you can also 967use this command instead of the 'echo' command above: 968 969.. code-block:: console 970 971 % sudo update-binfmts --install llvm /path/to/lli --magic 'BC' 972 973.. _Program Layout: 974.. _general layout: 975 976Program Layout 977============== 978 979One useful source of information about the LLVM source base is the LLVM `doxygen 980<http://www.doxygen.org/>`_ documentation available at 981`<http://llvm.org/doxygen/>`_. The following is a brief introduction to code 982layout: 983 984``llvm/examples`` 985----------------- 986 987This directory contains some simple examples of how to use the LLVM IR and JIT. 988 989``llvm/include`` 990---------------- 991 992This directory contains public header files exported from the LLVM library. The 993three main subdirectories of this directory are: 994 995``llvm/include/llvm`` 996 997 This directory contains all of the LLVM specific header files. This directory 998 also has subdirectories for different portions of LLVM: ``Analysis``, 999 ``CodeGen``, ``Target``, ``Transforms``, etc... 1000 1001``llvm/include/llvm/Support`` 1002 1003 This directory contains generic support libraries that are provided with LLVM 1004 but not necessarily specific to LLVM. For example, some C++ STL utilities and 1005 a Command Line option processing library store their header files here. 1006 1007``llvm/include/llvm/Config`` 1008 1009 This directory contains header files configured by the ``configure`` script. 1010 They wrap "standard" UNIX and C header files. Source code can include these 1011 header files which automatically take care of the conditional #includes that 1012 the ``configure`` script generates. 1013 1014``llvm/lib`` 1015------------ 1016 1017This directory contains most of the source files of the LLVM system. In LLVM, 1018almost all code exists in libraries, making it very easy to share code among the 1019different `tools`_. 1020 1021``llvm/lib/IR/`` 1022 1023 This directory holds the core LLVM source files that implement core classes 1024 like Instruction and BasicBlock. 1025 1026``llvm/lib/AsmParser/`` 1027 1028 This directory holds the source code for the LLVM assembly language parser 1029 library. 1030 1031``llvm/lib/Bitcode/`` 1032 1033 This directory holds code for reading and write LLVM bitcode. 1034 1035``llvm/lib/Analysis/`` 1036 1037 This directory contains a variety of different program analyses, such as 1038 Dominator Information, Call Graphs, Induction Variables, Interval 1039 Identification, Natural Loop Identification, etc. 1040 1041``llvm/lib/Transforms/`` 1042 1043 This directory contains the source code for the LLVM to LLVM program 1044 transformations, such as Aggressive Dead Code Elimination, Sparse Conditional 1045 Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global 1046 Elimination, and many others. 1047 1048``llvm/lib/Target/`` 1049 1050 This directory contains files that describe various target architectures for 1051 code generation. For example, the ``llvm/lib/Target/X86`` directory holds the 1052 X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM 1053 backend. 1054 1055``llvm/lib/CodeGen/`` 1056 1057 This directory contains the major parts of the code generator: Instruction 1058 Selector, Instruction Scheduling, and Register Allocation. 1059 1060``llvm/lib/MC/`` 1061 1062 (FIXME: T.B.D.) 1063 1064``llvm/lib/Debugger/`` 1065 1066 This directory contains the source level debugger library that makes it 1067 possible to instrument LLVM programs so that a debugger could identify source 1068 code locations at which the program is executing. 1069 1070``llvm/lib/ExecutionEngine/`` 1071 1072 This directory contains libraries for executing LLVM bitcode directly at 1073 runtime in both interpreted and JIT compiled fashions. 1074 1075``llvm/lib/Support/`` 1076 1077 This directory contains the source code that corresponds to the header files 1078 located in ``llvm/include/ADT/`` and ``llvm/include/Support/``. 1079 1080``llvm/projects`` 1081----------------- 1082 1083This directory contains projects that are not strictly part of LLVM but are 1084shipped with LLVM. This is also the directory where you should create your own 1085LLVM-based projects. 1086 1087``llvm/runtime`` 1088---------------- 1089 1090This directory contains libraries which are compiled into LLVM bitcode and used 1091when linking programs with the Clang front end. Most of these libraries are 1092skeleton versions of real libraries; for example, libc is a stripped down 1093version of glibc. 1094 1095Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end 1096to compile. 1097 1098``llvm/test`` 1099------------- 1100 1101This directory contains feature and regression tests and other basic sanity 1102checks on the LLVM infrastructure. These are intended to run quickly and cover a 1103lot of territory without being exhaustive. 1104 1105``test-suite`` 1106-------------- 1107 1108This is not a directory in the normal llvm module; it is a separate Subversion 1109module that must be checked out (usually to ``projects/test-suite``). This 1110module contains a comprehensive correctness, performance, and benchmarking test 1111suite for LLVM. It is a separate Subversion module because not every LLVM user 1112is interested in downloading or building such a comprehensive test suite. For 1113further details on this test suite, please see the :doc:`Testing Guide 1114<TestingGuide>` document. 1115 1116.. _tools: 1117 1118``llvm/tools`` 1119-------------- 1120 1121The **tools** directory contains the executables built out of the libraries 1122above, which form the main part of the user interface. You can always get help 1123for a tool by typing ``tool_name -help``. The following is a brief introduction 1124to the most important tools. More detailed information is in 1125the `Command Guide <CommandGuide/index.html>`_. 1126 1127``bugpoint`` 1128 1129 ``bugpoint`` is used to debug optimization passes or code generation backends 1130 by narrowing down the given test case to the minimum number of passes and/or 1131 instructions that still cause a problem, whether it is a crash or 1132 miscompilation. See `<HowToSubmitABug.html>`_ for more information on using 1133 ``bugpoint``. 1134 1135``llvm-ar`` 1136 1137 The archiver produces an archive containing the given LLVM bitcode files, 1138 optionally with an index for faster lookup. 1139 1140``llvm-as`` 1141 1142 The assembler transforms the human readable LLVM assembly to LLVM bitcode. 1143 1144``llvm-dis`` 1145 1146 The disassembler transforms the LLVM bitcode to human readable LLVM assembly. 1147 1148``llvm-link`` 1149 1150 ``llvm-link``, not surprisingly, links multiple LLVM modules into a single 1151 program. 1152 1153``lli`` 1154 1155 ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode 1156 (although very slowly...). For architectures that support it (currently x86, 1157 Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time 1158 compiler (if the functionality was compiled in), and will execute the code 1159 *much* faster than the interpreter. 1160 1161``llc`` 1162 1163 ``llc`` is the LLVM backend compiler, which translates LLVM bitcode to a 1164 native code assembly file or to C code (with the ``-march=c`` option). 1165 1166``opt`` 1167 1168 ``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations 1169 (which are specified on the command line), and then outputs the resultant 1170 bitcode. The '``opt -help``' command is a good way to get a list of the 1171 program transformations available in LLVM. 1172 1173 ``opt`` can also be used to run a specific analysis on an input LLVM bitcode 1174 file and print out the results. It is primarily useful for debugging 1175 analyses, or familiarizing yourself with what an analysis does. 1176 1177``llvm/utils`` 1178-------------- 1179 1180This directory contains utilities for working with LLVM source code, and some of 1181the utilities are actually required as part of the build process because they 1182are code generators for parts of LLVM infrastructure. 1183 1184 1185``codegen-diff`` 1186 1187 ``codegen-diff`` is a script that finds differences between code that LLC 1188 generates and code that LLI generates. This is a useful tool if you are 1189 debugging one of them, assuming that the other generates correct output. For 1190 the full user manual, run ```perldoc codegen-diff'``. 1191 1192``emacs/`` 1193 1194 The ``emacs`` directory contains syntax-highlighting files which will work 1195 with Emacs and XEmacs editors, providing syntax highlighting support for LLVM 1196 assembly files and TableGen description files. For information on how to use 1197 the syntax files, consult the ``README`` file in that directory. 1198 1199``getsrcs.sh`` 1200 1201 The ``getsrcs.sh`` script finds and outputs all non-generated source files, 1202 which is useful if one wishes to do a lot of development across directories 1203 and does not want to individually find each file. One way to use it is to run, 1204 for example: ``xemacs `utils/getsources.sh``` from the top of your LLVM source 1205 tree. 1206 1207``llvmgrep`` 1208 1209 This little tool performs an ``egrep -H -n`` on each source file in LLVM and 1210 passes to it a regular expression provided on ``llvmgrep``'s command 1211 line. This is a very efficient way of searching the source base for a 1212 particular regular expression. 1213 1214``makellvm`` 1215 1216 The ``makellvm`` script compiles all files in the current directory and then 1217 compiles and links the tool that is the first argument. For example, assuming 1218 you are in the directory ``llvm/lib/Target/Sparc``, if ``makellvm`` is in your 1219 path, simply running ``makellvm llc`` will make a build of the current 1220 directory, switch to directory ``llvm/tools/llc`` and build it, causing a 1221 re-linking of LLC. 1222 1223``TableGen/`` 1224 1225 The ``TableGen`` directory contains the tool used to generate register 1226 descriptions, instruction set descriptions, and even assemblers from common 1227 TableGen description files. 1228 1229``vim/`` 1230 1231 The ``vim`` directory contains syntax-highlighting files which will work with 1232 the VIM editor, providing syntax highlighting support for LLVM assembly files 1233 and TableGen description files. For information on how to use the syntax 1234 files, consult the ``README`` file in that directory. 1235 1236.. _simple example: 1237 1238An Example Using the LLVM Tool Chain 1239==================================== 1240 1241This section gives an example of using LLVM with the Clang front end. 1242 1243Example with clang 1244------------------ 1245 1246#. First, create a simple C file, name it 'hello.c': 1247 1248 .. code-block:: c 1249 1250 #include <stdio.h> 1251 1252 int main() { 1253 printf("hello world\n"); 1254 return 0; 1255 } 1256 1257#. Next, compile the C file into a native executable: 1258 1259 .. code-block:: console 1260 1261 % clang hello.c -o hello 1262 1263 .. note:: 1264 1265 Clang works just like GCC by default. The standard -S and -c arguments 1266 work as usual (producing a native .s or .o file, respectively). 1267 1268#. Next, compile the C file into an LLVM bitcode file: 1269 1270 .. code-block:: console 1271 1272 % clang -O3 -emit-llvm hello.c -c -o hello.bc 1273 1274 The -emit-llvm option can be used with the -S or -c options to emit an LLVM 1275 ``.ll`` or ``.bc`` file (respectively) for the code. This allows you to use 1276 the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file. 1277 1278#. Run the program in both forms. To run the program, use: 1279 1280 .. code-block:: console 1281 1282 % ./hello 1283 1284 and 1285 1286 .. code-block:: console 1287 1288 % lli hello.bc 1289 1290 The second examples shows how to invoke the LLVM JIT, :doc:`lli 1291 <CommandGuide/lli>`. 1292 1293#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: 1294 1295 .. code-block:: console 1296 1297 % llvm-dis < hello.bc | less 1298 1299#. Compile the program to native assembly using the LLC code generator: 1300 1301 .. code-block:: console 1302 1303 % llc hello.bc -o hello.s 1304 1305#. Assemble the native assembly language file into a program: 1306 1307 .. code-block:: console 1308 1309 % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris 1310 1311 % gcc hello.s -o hello.native # On others 1312 1313#. Execute the native code program: 1314 1315 .. code-block:: console 1316 1317 % ./hello.native 1318 1319 Note that using clang to compile directly to native code (i.e. when the 1320 ``-emit-llvm`` option is not present) does steps 6/7/8 for you. 1321 1322Common Problems 1323=============== 1324 1325If you are having problems building or using LLVM, or if you have any other 1326general questions about LLVM, please consult the `Frequently Asked 1327Questions <FAQ.html>`_ page. 1328 1329.. _links: 1330 1331Links 1332===== 1333 1334This document is just an **introduction** on how to use LLVM to do some simple 1335things... there are many more interesting and complicated things that you can do 1336that aren't documented here (but we'll gladly accept a patch if you want to 1337write something up!). For more information about LLVM, check out: 1338 1339* `LLVM Homepage <http://llvm.org/>`_ 1340* `LLVM Doxygen Tree <http://llvm.org/doxygen/>`_ 1341* `Starting a Project that Uses LLVM <http://llvm.org/docs/Projects.html>`_ 1342