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