1==================================== 2Getting Started with the LLVM System 3==================================== 4 5.. contents:: 6 :local: 7 8Overview 9======== 10 11Welcome to the LLVM project! 12 13The LLVM project has multiple components. The core of the project is 14itself called "LLVM". This contains all of the tools, libraries, and header 15files needed to process intermediate representations and converts it into 16object files. Tools include an assembler, disassembler, bitcode analyzer, and 17bitcode optimizer. It also contains basic regression tests. 18 19C-like languages use the `Clang <https://clang.llvm.org/>`_ front end. This 20component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode 21-- and from there into object files, using LLVM. 22 23Other components include: 24the `libc++ C++ standard library <https://libcxx.llvm.org>`_, 25the `LLD linker <https://lld.llvm.org>`_, and more. 26 27Getting the Source Code and Building LLVM 28========================================= 29 30The LLVM Getting Started documentation may be out of date. The `Clang 31Getting Started <https://clang.llvm.org/get_started.html>`_ page might have more 32accurate information. 33 34This is an example workflow and configuration to get and build the LLVM source: 35 36#. Checkout LLVM (including related subprojects like Clang): 37 38 * ``git clone https://github.com/llvm/llvm-project.git`` 39 * Or, on windows, ``git clone --config core.autocrlf=false 40 https://github.com/llvm/llvm-project.git`` 41 * To save storage and speed-up the checkout time, you may want to do a 42 `shallow clone <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt>`_. 43 For example, to get the latest revision of the LLVM project, use 44 ``git clone --depth 1 https://github.com/llvm/llvm-project.git`` 45 46#. Configure and build LLVM and Clang: 47 48 * ``cd llvm-project`` 49 * ``mkdir build`` 50 * ``cd build`` 51 * ``cmake -G <generator> -DCMAKE_BUILD_TYPE=<type> [options] ../llvm`` 52 53 Some common build system generators are: 54 55 * ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_ 56 build files. Most llvm developers use Ninja. 57 * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles. 58 * ``Visual Studio`` --- for generating Visual Studio projects and 59 solutions. 60 * ``Xcode`` --- for generating Xcode projects. 61 62 Some Common options: 63 64 * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM 65 subprojects you'd like to additionally build. Can include any of: clang, 66 clang-tools-extra, lldb, compiler-rt, lld, polly, or cross-project-tests. 67 68 For example, to build LLVM, Clang, libcxx, and libcxxabi, use 69 ``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``. 70 71 * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full 72 pathname of where you want the LLVM tools and libraries to be installed 73 (default ``/usr/local``). 74 75 * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug information 76 of the build. The default value is ``Debug`` which fits people who want 77 to work on LLVM or its libraries. ``Release`` is a better fit for most 78 users of LLVM and Clang. For more detailed information see 79 :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`. 80 81 * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled 82 (default is Yes for Debug builds, No for all other build types). 83 84 * ``cmake --build . [--target <target>]`` or the build system specified 85 above directly. 86 87 * The default target (i.e. ``cmake --build .`` or ``make``) will build all of 88 LLVM. 89 90 * The ``check-all`` target (i.e. ``ninja check-all``) will run the 91 regression tests to ensure everything is in working order. 92 93 * CMake will generate build targets for each tool and library, and most 94 LLVM sub-projects generate their own ``check-<project>`` target. 95 96 * Running a serial build will be **slow**. To improve speed, try running a 97 parallel build. That's done by default in Ninja; for ``make``, use the 98 option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the 99 number of available CPUs. 100 101 * For more information see `CMake <CMake.html>`__ 102 103 * If you get an "internal compiler error (ICE)" or test failures, see 104 `below`_. 105 106Consult the `Getting Started with LLVM`_ section for detailed information on 107configuring and compiling LLVM. Go to `Directory Layout`_ to learn about the 108layout of the source code tree. 109 110Requirements 111============ 112 113Before you begin to use the LLVM system, review the requirements given below. 114This may save you some trouble by knowing ahead of time what hardware and 115software you will need. 116 117Hardware 118-------- 119 120LLVM is known to work on the following host platforms: 121 122================== ===================== ============= 123OS Arch Compilers 124================== ===================== ============= 125Linux x86\ :sup:`1` GCC, Clang 126Linux amd64 GCC, Clang 127Linux ARM GCC, Clang 128Linux Mips GCC, Clang 129Linux PowerPC GCC, Clang 130Linux SystemZ GCC, Clang 131Solaris V9 (Ultrasparc) GCC 132DragonFlyBSD amd64 GCC, Clang 133FreeBSD x86\ :sup:`1` GCC, Clang 134FreeBSD amd64 GCC, Clang 135NetBSD x86\ :sup:`1` GCC, Clang 136NetBSD amd64 GCC, Clang 137OpenBSD x86\ :sup:`1` GCC, Clang 138OpenBSD amd64 GCC, Clang 139macOS\ :sup:`2` PowerPC GCC 140macOS x86 GCC, Clang 141Cygwin/Win32 x86\ :sup:`1, 3` GCC 142Windows x86\ :sup:`1` Visual Studio 143Windows x64 x86-64 Visual Studio 144================== ===================== ============= 145 146.. note:: 147 148 #. Code generation supported for Pentium processors and up 149 #. Code generation supported for 32-bit ABI only 150 #. To use LLVM modules on Win32-based system, you may configure LLVM 151 with ``-DBUILD_SHARED_LIBS=On``. 152 153Note that Debug builds require a lot of time and disk space. An LLVM-only build 154will need about 1-3 GB of space. A full build of LLVM and Clang will need around 15515-20 GB of disk space. The exact space requirements will vary by system. (It 156is so large because of all the debugging information and the fact that the 157libraries are statically linked into multiple tools). 158 159If you are space-constrained, you can build only selected tools or only 160selected targets. The Release build requires considerably less space. 161 162The LLVM suite *may* compile on other platforms, but it is not guaranteed to do 163so. If compilation is successful, the LLVM utilities should be able to 164assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation 165should work as well, although the generated native code may not work on your 166platform. 167 168Software 169-------- 170 171Compiling LLVM requires that you have several software packages installed. The 172table below lists those required packages. The Package column is the usual name 173for the software package that LLVM depends on. The Version column provides 174"known to work" versions of the package. The Notes column describes how LLVM 175uses the package and provides other details. 176 177=========================================================== ============ ========================================== 178Package Version Notes 179=========================================================== ============ ========================================== 180`CMake <http://cmake.org/>`__ >=3.13.4 Makefile/workspace generator 181`GCC <http://gcc.gnu.org/>`_ >=7.1.0 C/C++ compiler\ :sup:`1` 182`python <http://www.python.org/>`_ >=3.6 Automated test suite\ :sup:`2` 183`zlib <http://zlib.net>`_ >=1.2.3.4 Compression library\ :sup:`3` 184`GNU Make <http://savannah.gnu.org/projects/make>`_ 3.79, 3.79.1 Makefile/build processor\ :sup:`4` 185=========================================================== ============ ========================================== 186 187.. note:: 188 189 #. Only the C and C++ languages are needed so there's no need to build the 190 other languages for LLVM's purposes. See `below` for specific version 191 info. 192 #. Only needed if you want to run the automated test suite in the 193 ``llvm/test`` directory. 194 #. Optional, adds compression / uncompression capabilities to selected LLVM 195 tools. 196 #. Optional, you can use any other build tool supported by CMake. 197 198Additionally, your compilation host is expected to have the usual plethora of 199Unix utilities. Specifically: 200 201* **ar** --- archive library builder 202* **bzip2** --- bzip2 command for distribution generation 203* **bunzip2** --- bunzip2 command for distribution checking 204* **chmod** --- change permissions on a file 205* **cat** --- output concatenation utility 206* **cp** --- copy files 207* **date** --- print the current date/time 208* **echo** --- print to standard output 209* **egrep** --- extended regular expression search utility 210* **find** --- find files/dirs in a file system 211* **grep** --- regular expression search utility 212* **gzip** --- gzip command for distribution generation 213* **gunzip** --- gunzip command for distribution checking 214* **install** --- install directories/files 215* **mkdir** --- create a directory 216* **mv** --- move (rename) files 217* **ranlib** --- symbol table builder for archive libraries 218* **rm** --- remove (delete) files and directories 219* **sed** --- stream editor for transforming output 220* **sh** --- Bourne shell for make build scripts 221* **tar** --- tape archive for distribution generation 222* **test** --- test things in file system 223* **unzip** --- unzip command for distribution checking 224* **zip** --- zip command for distribution generation 225 226.. _below: 227.. _check here: 228 229Host C++ Toolchain, both Compiler and Standard Library 230------------------------------------------------------ 231 232LLVM is very demanding of the host C++ compiler, and as such tends to expose 233bugs in the compiler. We also attempt to follow improvements and developments in 234the C++ language and library reasonably closely. As such, we require a modern 235host C++ toolchain, both compiler and standard library, in order to build LLVM. 236 237LLVM is written using the subset of C++ documented in :doc:`coding 238standards<CodingStandards>`. To enforce this language version, we check the most 239popular host toolchains for specific minimum versions in our build systems: 240 241* Clang 5.0 242* Apple Clang 9.3 243* GCC 7.1 244* Visual Studio 2019 16.7 245 246Anything older than these toolchains *may* work, but will require forcing the 247build system with a special option and is not really a supported host platform. 248Also note that older versions of these compilers have often crashed or 249miscompiled LLVM. 250 251For less widely used host toolchains such as ICC or xlC, be aware that a very 252recent version may be required to support all of the C++ features used in LLVM. 253 254We track certain versions of software that are *known* to fail when used as 255part of the host toolchain. These even include linkers at times. 256 257**GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long 258warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was 259defined in a discarded section. You can safely ignore these messages as they are 260erroneous and the linkage is correct. These messages disappear using ld 2.17. 261 262**GNU binutils 2.17**: Binutils 2.17 contains `a bug 263<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link 264times (minutes instead of seconds) when building LLVM. We recommend upgrading 265to a newer version (2.17.50.0.4 or later). 266 267**GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug 268<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes 269intermittent failures when building LLVM with position independent code. The 270symptom is an error about cyclic dependencies. We recommend upgrading to a 271newer version of Gold. 272 273Getting a Modern Host C++ Toolchain 274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 275 276This section mostly applies to Linux and older BSDs. On macOS, you should 277have a sufficiently modern Xcode, or you will likely need to upgrade until you 278do. Windows does not have a "system compiler", so you must install either Visual 279Studio 2019 (or later), or a recent version of mingw64. FreeBSD 10.0 and newer 280have a modern Clang as the system compiler. 281 282However, some Linux distributions and some other or older BSDs sometimes have 283extremely old versions of GCC. These steps attempt to help you upgrade you 284compiler even on such a system. However, if at all possible, we encourage you 285to use a recent version of a distribution with a modern system compiler that 286meets these requirements. Note that it is tempting to install a prior 287version of Clang and libc++ to be the host compiler, however libc++ was not 288well tested or set up to build on Linux until relatively recently. As 289a consequence, this guide suggests just using libstdc++ and a modern GCC as the 290initial host in a bootstrap, and then using Clang (and potentially libc++). 291 292The first step is to get a recent GCC toolchain installed. The most common 293distribution on which users have struggled with the version requirements is 294Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install 295the `toolchain testing PPA`_ and use it to install a modern GCC. There is 296a really nice discussions of this on the `ask ubuntu stack exchange`_ and a 297`github gist`_ with updated commands. However, not all users can use PPAs and 298there are many other distributions, so it may be necessary (or just useful, if 299you're here you *are* doing compiler development after all) to build and install 300GCC from source. It is also quite easy to do these days. 301 302.. _toolchain testing PPA: 303 https://launchpad.net/~ubuntu-toolchain-r/+archive/test 304.. _ask ubuntu stack exchange: 305 https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149 306.. _github gist: 307 https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91 308 309Easy steps for installing GCC 7.1.0: 310 311.. code-block:: console 312 313 % gcc_version=7.1.0 314 % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2 315 % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig 316 % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg 317 % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig` 318 % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi 319 % tar -xvjf gcc-${gcc_version}.tar.bz2 320 % cd gcc-${gcc_version} 321 % ./contrib/download_prerequisites 322 % cd .. 323 % mkdir gcc-${gcc_version}-build 324 % cd gcc-${gcc_version}-build 325 % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++ 326 % make -j$(nproc) 327 % make install 328 329For more details, check out the excellent `GCC wiki entry`_, where I got most 330of this information from. 331 332.. _GCC wiki entry: 333 https://gcc.gnu.org/wiki/InstallingGCC 334 335Once you have a GCC toolchain, configure your build of LLVM to use the new 336toolchain for your host compiler and C++ standard library. Because the new 337version of libstdc++ is not on the system library search path, you need to pass 338extra linker flags so that it can be found at link time (``-L``) and at runtime 339(``-rpath``). If you are using CMake, this invocation should produce working 340binaries: 341 342.. code-block:: console 343 344 % mkdir build 345 % cd build 346 % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \ 347 cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64" 348 349If you fail to set rpath, most LLVM binaries will fail on startup with a message 350from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not 351found``. This means you need to tweak the -rpath linker flag. 352 353This method will add an absolute path to the rpath of all executables. That's 354fine for local development. If you want to distribute the binaries you build 355so that they can run on older systems, copy ``libstdc++.so.6`` into the 356``lib/`` directory. All of LLVM's shipping binaries have an rpath pointing at 357``$ORIGIN/../lib``, so they will find ``libstdc++.so.6`` there. Non-distributed 358binaries don't have an rpath set and won't find ``libstdc++.so.6``. Pass 359``-DLLVM_LOCAL_RPATH="$HOME/toolchains/lib64"`` to cmake to add an absolute 360path to ``libstdc++.so.6`` as above. Since these binaries are not distributed, 361having an absolute local path is fine for them. 362 363When you build Clang, you will need to give *it* access to modern C++ 364standard library in order to use it as your new host in part of a bootstrap. 365There are two easy ways to do this, either build (and install) libc++ along 366with Clang and then use it with the ``-stdlib=libc++`` compile and link flag, 367or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC. 368Clang will look within its own prefix for libstdc++ and use it if found. You 369can also add an explicit prefix for Clang to look in for a GCC toolchain with 370the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and 371link commands when using your just-built-Clang to bootstrap. 372 373.. _Getting Started with LLVM: 374 375Getting Started with LLVM 376========================= 377 378The remainder of this guide is meant to get you up and running with LLVM and to 379give you some basic information about the LLVM environment. 380 381The later sections of this guide describe the `general layout`_ of the LLVM 382source tree, a `simple example`_ using the LLVM tool chain, and `links`_ to find 383more information about LLVM or to get help via e-mail. 384 385Terminology and Notation 386------------------------ 387 388Throughout this manual, the following names are used to denote paths specific to 389the local system and working environment. *These are not environment variables 390you need to set but just strings used in the rest of this document below*. In 391any of the examples below, simply replace each of these names with the 392appropriate pathname on your local system. All these paths are absolute: 393 394``SRC_ROOT`` 395 396 This is the top level directory of the LLVM source tree. 397 398``OBJ_ROOT`` 399 400 This is the top level directory of the LLVM object tree (i.e. the tree where 401 object files and compiled programs will be placed. It can be the same as 402 SRC_ROOT). 403 404Unpacking the LLVM Archives 405--------------------------- 406 407If you have the LLVM distribution, you will need to unpack it before you can 408begin to compile it. LLVM is distributed as a number of different 409subprojects. Each one has its own download which is a TAR archive that is 410compressed with the gzip program. 411 412The files are as follows, with *x.y* marking the version number: 413 414``llvm-x.y.tar.gz`` 415 416 Source release for the LLVM libraries and tools. 417 418``cfe-x.y.tar.gz`` 419 420 Source release for the Clang frontend. 421 422.. _checkout: 423 424Checkout LLVM from Git 425---------------------- 426 427You can also checkout the source code for LLVM from Git. 428 429.. note:: 430 431 Passing ``--config core.autocrlf=false`` should not be required in 432 the future after we adjust the .gitattribute settings correctly, but 433 is required for Windows users at the time of this writing. 434 435Simply run: 436 437.. code-block:: console 438 439 % git clone https://github.com/llvm/llvm-project.git 440 441or on Windows, 442 443.. code-block:: console 444 445 % git clone --config core.autocrlf=false https://github.com/llvm/llvm-project.git 446 447This will create an '``llvm-project``' directory in the current directory and 448fully populate it with all of the source code, test directories, and local 449copies of documentation files for LLVM and all the related subprojects. Note 450that unlike the tarballs, which contain each subproject in a separate file, the 451git repository contains all of the projects together. 452 453If you want to get a specific release (as opposed to the most recent revision), 454you can check out a tag after cloning the repository. E.g., `git checkout 455llvmorg-6.0.1` inside the ``llvm-project`` directory created by the above 456command. Use `git tag -l` to list all of them. 457 458Sending patches 459^^^^^^^^^^^^^^^ 460 461See :ref:`Contributing <submit_patch>`. 462 463Bisecting commits 464^^^^^^^^^^^^^^^^^ 465 466See `Bisecting LLVM code <GitBisecting.html>`_ for how to use ``git bisect`` 467on LLVM. 468 469Reverting a change 470^^^^^^^^^^^^^^^^^^ 471 472When reverting changes using git, the default message will say "This reverts 473commit XYZ". Leave this at the end of the commit message, but add some details 474before it as to why the commit is being reverted. A brief explanation and/or 475links to bots that demonstrate the problem are sufficient. 476 477Local LLVM Configuration 478------------------------ 479 480Once checked out repository, the LLVM suite source code must be configured 481before being built. This process uses CMake. Unlinke the normal ``configure`` 482script, CMake generates the build files in whatever format you request as well 483as various ``*.inc`` files, and ``llvm/include/Config/config.h``. 484 485Variables are passed to ``cmake`` on the command line using the format 486``-D<variable name>=<value>``. The following variables are some common options 487used by people developing LLVM. 488 489+-------------------------+----------------------------------------------------+ 490| Variable | Purpose | 491+=========================+====================================================+ 492| CMAKE_C_COMPILER | Tells ``cmake`` which C compiler to use. By | 493| | default, this will be /usr/bin/cc. | 494+-------------------------+----------------------------------------------------+ 495| CMAKE_CXX_COMPILER | Tells ``cmake`` which C++ compiler to use. By | 496| | default, this will be /usr/bin/c++. | 497+-------------------------+----------------------------------------------------+ 498| CMAKE_BUILD_TYPE | Tells ``cmake`` what type of build you are trying | 499| | to generate files for. Valid options are Debug, | 500| | Release, RelWithDebInfo, and MinSizeRel. Default | 501| | is Debug. | 502+-------------------------+----------------------------------------------------+ 503| CMAKE_INSTALL_PREFIX | Specifies the install directory to target when | 504| | running the install action of the build files. | 505+-------------------------+----------------------------------------------------+ 506| PYTHON_EXECUTABLE | Forces CMake to use a specific Python version by | 507| | passing a path to a Python interpreter. By default | 508| | the Python version of the interpreter in your PATH | 509| | is used. | 510+-------------------------+----------------------------------------------------+ 511| LLVM_TARGETS_TO_BUILD | A semicolon delimited list controlling which | 512| | targets will be built and linked into llvm. | 513| | The default list is defined as | 514| | ``LLVM_ALL_TARGETS``, and can be set to include | 515| | out-of-tree targets. The default value includes: | 516| | ``AArch64, AMDGPU, ARM, AVR, BPF, Hexagon, Lanai, | 517| | Mips, MSP430, NVPTX, PowerPC, RISCV, Sparc, | 518| | SystemZ, WebAssembly, X86, XCore``. | 519| | | 520+-------------------------+----------------------------------------------------+ 521| LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source | 522| | code This is disabled by default because it is | 523| | slow and generates a lot of output. | 524+-------------------------+----------------------------------------------------+ 525| LLVM_ENABLE_PROJECTS | A semicolon-delimited list selecting which of the | 526| | other LLVM subprojects to additionally build. (Only| 527| | effective when using a side-by-side project layout | 528| | e.g. via git). The default list is empty. Can | 529| | include: clang, clang-tools-extra, | 530| | cross-project-tests, flang, libc, libclc, lld, | 531| | lldb, mlir, openmp, polly, or pstl. | 532+-------------------------+----------------------------------------------------+ 533| LLVM_ENABLE_RUNTIMES | A semicolon-delimited list selecting which of the | 534| | runtimes to build. (Only effective when using the | 535| | full monorepo layout). The default list is empty. | 536| | Can include: compiler-rt, libc, libcxx, libcxxabi, | 537| | libunwind, or openmp. | 538+-------------------------+----------------------------------------------------+ 539| LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source | 540| | code. This is disabled by default because it is | 541| | slow and generates a lot of output. Sphinx version | 542| | 1.5 or later recommended. | 543+-------------------------+----------------------------------------------------+ 544| LLVM_BUILD_LLVM_DYLIB | Generate libLLVM.so. This library contains a | 545| | default set of LLVM components that can be | 546| | overridden with ``LLVM_DYLIB_COMPONENTS``. The | 547| | default contains most of LLVM and is defined in | 548| | ``tools/llvm-shlib/CMakelists.txt``. This option is| 549| | not available on Windows. | 550+-------------------------+----------------------------------------------------+ 551| LLVM_OPTIMIZED_TABLEGEN | Builds a release tablegen that gets used during | 552| | the LLVM build. This can dramatically speed up | 553| | debug builds. | 554+-------------------------+----------------------------------------------------+ 555 556To configure LLVM, follow these steps: 557 558#. Change directory into the object root directory: 559 560 .. code-block:: console 561 562 % cd OBJ_ROOT 563 564#. Run the ``cmake``: 565 566 .. code-block:: console 567 568 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=<type> -DCMAKE_INSTALL_PREFIX=/install/path 569 [other options] SRC_ROOT 570 571Compiling the LLVM Suite Source Code 572------------------------------------ 573 574Unlike with autotools, with CMake your build type is defined at configuration. 575If you want to change your build type, you can re-run cmake with the following 576invocation: 577 578 .. code-block:: console 579 580 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=<type> -DCMAKE_BUILD_TYPE=type SRC_ROOT 581 582Between runs, CMake preserves the values set for all options. CMake has the 583following build types defined: 584 585Debug 586 587 These builds are the default. The build system will compile the tools and 588 libraries unoptimized, with debugging information, and asserts enabled. 589 590Release 591 592 For these builds, the build system will compile the tools and libraries 593 with optimizations enabled and not generate debug info. CMakes default 594 optimization level is -O3. This can be configured by setting the 595 ``CMAKE_CXX_FLAGS_RELEASE`` variable on the CMake command line. 596 597RelWithDebInfo 598 599 These builds are useful when debugging. They generate optimized binaries with 600 debug information. CMakes default optimization level is -O2. This can be 601 configured by setting the ``CMAKE_CXX_FLAGS_RELWITHDEBINFO`` variable on the 602 CMake command line. 603 604Once you have LLVM configured, you can build it by entering the *OBJ_ROOT* 605directory and issuing the following command: 606 607.. code-block:: console 608 609 % make 610 611If the build fails, please `check here`_ to see if you are using a version of 612GCC that is known not to compile LLVM. 613 614If you have multiple processors in your machine, you may wish to use some of the 615parallel build options provided by GNU Make. For example, you could use the 616command: 617 618.. code-block:: console 619 620 % make -j2 621 622There are several special targets which are useful when working with the LLVM 623source code: 624 625``make clean`` 626 627 Removes all files generated by the build. This includes object files, 628 generated C/C++ files, libraries, and executables. 629 630``make install`` 631 632 Installs LLVM header files, libraries, tools, and documentation in a hierarchy 633 under ``$PREFIX``, specified with ``CMAKE_INSTALL_PREFIX``, which 634 defaults to ``/usr/local``. 635 636``make docs-llvm-html`` 637 638 If configured with ``-DLLVM_ENABLE_SPHINX=On``, this will generate a directory 639 at ``OBJ_ROOT/docs/html`` which contains the HTML formatted documentation. 640 641Cross-Compiling LLVM 642-------------------- 643 644It is possible to cross-compile LLVM itself. That is, you can create LLVM 645executables and libraries to be hosted on a platform different from the platform 646where they are built (a Canadian Cross build). To generate build files for 647cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can 648define compiler flags and variables used during the CMake test operations. 649 650The result of such a build is executables that are not runnable on the build 651host but can be executed on the target. As an example the following CMake 652invocation can generate build files targeting iOS. This will work on macOS 653with the latest Xcode: 654 655.. code-block:: console 656 657 % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES="armv7;armv7s;arm64" 658 -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake 659 -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off 660 -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options] 661 <PATH_TO_LLVM> 662 663Note: There are some additional flags that need to be passed when building for 664iOS due to limitations in the iOS SDK. 665 666Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general 667<https://clang.llvm.org/docs/CrossCompilation.html>`_ for more information 668about cross-compiling. 669 670The Location of LLVM Object Files 671--------------------------------- 672 673The LLVM build system is capable of sharing a single LLVM source tree among 674several LLVM builds. Hence, it is possible to build LLVM for several different 675platforms or configurations using the same source tree. 676 677* Change directory to where the LLVM object files should live: 678 679 .. code-block:: console 680 681 % cd OBJ_ROOT 682 683* Run ``cmake``: 684 685 .. code-block:: console 686 687 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release SRC_ROOT 688 689The LLVM build will create a structure underneath *OBJ_ROOT* that matches the 690LLVM source tree. At each level where source files are present in the source 691tree there will be a corresponding ``CMakeFiles`` directory in the *OBJ_ROOT*. 692Underneath that directory there is another directory with a name ending in 693``.dir`` under which you'll find object files for each source. 694 695For example: 696 697 .. code-block:: console 698 699 % cd llvm_build_dir 700 % find lib/Support/ -name APFloat* 701 lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o 702 703Optional Configuration Items 704---------------------------- 705 706If you're running on a Linux system that supports the `binfmt_misc 707<http://en.wikipedia.org/wiki/binfmt_misc>`_ 708module, and you have root access on the system, you can set your system up to 709execute LLVM bitcode files directly. To do this, use commands like this (the 710first command may not be required if you are already using the module): 711 712.. code-block:: console 713 714 % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc 715 % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register 716 % chmod u+x hello.bc (if needed) 717 % ./hello.bc 718 719This allows you to execute LLVM bitcode files directly. On Debian, you can also 720use this command instead of the 'echo' command above: 721 722.. code-block:: console 723 724 % sudo update-binfmts --install llvm /path/to/lli --magic 'BC' 725 726.. _Program Layout: 727.. _general layout: 728 729Directory Layout 730================ 731 732One useful source of information about the LLVM source base is the LLVM `doxygen 733<http://www.doxygen.org/>`_ documentation available at 734`<https://llvm.org/doxygen/>`_. The following is a brief introduction to code 735layout: 736 737``llvm/cmake`` 738-------------- 739Generates system build files. 740 741``llvm/cmake/modules`` 742 Build configuration for llvm user defined options. Checks compiler version and 743 linker flags. 744 745``llvm/cmake/platforms`` 746 Toolchain configuration for Android NDK, iOS systems and non-Windows hosts to 747 target MSVC. 748 749``llvm/examples`` 750----------------- 751 752- Some simple examples showing how to use LLVM as a compiler for a custom 753 language - including lowering, optimization, and code generation. 754 755- Kaleidoscope Tutorial: Kaleidoscope language tutorial run through the 756 implementation of a nice little compiler for a non-trivial language 757 including a hand-written lexer, parser, AST, as well as code generation 758 support using LLVM- both static (ahead of time) and various approaches to 759 Just In Time (JIT) compilation. 760 `Kaleidoscope Tutorial for complete beginner 761 <https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html>`_. 762 763- BuildingAJIT: Examples of the `BuildingAJIT tutorial 764 <https://llvm.org/docs/tutorial/BuildingAJIT1.html>`_ that shows how LLVM’s 765 ORC JIT APIs interact with other parts of LLVM. It also, teaches how to 766 recombine them to build a custom JIT that is suited to your use-case. 767 768``llvm/include`` 769---------------- 770 771Public header files exported from the LLVM library. The three main subdirectories: 772 773``llvm/include/llvm`` 774 775 All LLVM-specific header files, and subdirectories for different portions of 776 LLVM: ``Analysis``, ``CodeGen``, ``Target``, ``Transforms``, etc... 777 778``llvm/include/llvm/Support`` 779 780 Generic support libraries provided with LLVM but not necessarily specific to 781 LLVM. For example, some C++ STL utilities and a Command Line option processing 782 library store header files here. 783 784``llvm/include/llvm/Config`` 785 786 Header files configured by ``cmake``. They wrap "standard" UNIX and 787 C header files. Source code can include these header files which 788 automatically take care of the conditional #includes that ``cmake`` 789 generates. 790 791``llvm/lib`` 792------------ 793 794Most source files are here. By putting code in libraries, LLVM makes it easy to 795share code among the `tools`_. 796 797``llvm/lib/IR/`` 798 799 Core LLVM source files that implement core classes like Instruction and 800 BasicBlock. 801 802``llvm/lib/AsmParser/`` 803 804 Source code for the LLVM assembly language parser library. 805 806``llvm/lib/Bitcode/`` 807 808 Code for reading and writing bitcode. 809 810``llvm/lib/Analysis/`` 811 812 A variety of program analyses, such as Call Graphs, Induction Variables, 813 Natural Loop Identification, etc. 814 815``llvm/lib/Transforms/`` 816 817 IR-to-IR program transformations, such as Aggressive Dead Code Elimination, 818 Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion, 819 Dead Global Elimination, and many others. 820 821``llvm/lib/Target/`` 822 823 Files describing target architectures for code generation. For example, 824 ``llvm/lib/Target/X86`` holds the X86 machine description. 825 826``llvm/lib/CodeGen/`` 827 828 The major parts of the code generator: Instruction Selector, Instruction 829 Scheduling, and Register Allocation. 830 831``llvm/lib/MC/`` 832 833 The libraries represent and process code at machine code level. Handles 834 assembly and object-file emission. 835 836``llvm/lib/ExecutionEngine/`` 837 838 Libraries for directly executing bitcode at runtime in interpreted and 839 JIT-compiled scenarios. 840 841``llvm/lib/Support/`` 842 843 Source code that corresponding to the header files in ``llvm/include/ADT/`` 844 and ``llvm/include/Support/``. 845 846``llvm/bindings`` 847---------------------- 848 849Contains bindings for the LLVM compiler infrastructure to allow 850programs written in languages other than C or C++ to take advantage of the LLVM 851infrastructure. 852LLVM project provides language bindings for Go, OCaml and Python. 853 854``llvm/projects`` 855----------------- 856 857Projects not strictly part of LLVM but shipped with LLVM. This is also the 858directory for creating your own LLVM-based projects which leverage the LLVM 859build system. 860 861``llvm/test`` 862------------- 863 864Feature and regression tests and other sanity checks on LLVM infrastructure. These 865are intended to run quickly and cover a lot of territory without being exhaustive. 866 867``test-suite`` 868-------------- 869 870A comprehensive correctness, performance, and benchmarking test suite 871for LLVM. This comes in a ``separate git repository 872<https://github.com/llvm/llvm-test-suite>``, because it contains a 873large amount of third-party code under a variety of licenses. For 874details see the :doc:`Testing Guide <TestingGuide>` document. 875 876.. _tools: 877 878``llvm/tools`` 879-------------- 880 881Executables built out of the libraries 882above, which form the main part of the user interface. You can always get help 883for a tool by typing ``tool_name -help``. The following is a brief introduction 884to the most important tools. More detailed information is in 885the `Command Guide <CommandGuide/index.html>`_. 886 887``bugpoint`` 888 889 ``bugpoint`` is used to debug optimization passes or code generation backends 890 by narrowing down the given test case to the minimum number of passes and/or 891 instructions that still cause a problem, whether it is a crash or 892 miscompilation. See `<HowToSubmitABug.html>`_ for more information on using 893 ``bugpoint``. 894 895``llvm-ar`` 896 897 The archiver produces an archive containing the given LLVM bitcode files, 898 optionally with an index for faster lookup. 899 900``llvm-as`` 901 902 The assembler transforms the human readable LLVM assembly to LLVM bitcode. 903 904``llvm-dis`` 905 906 The disassembler transforms the LLVM bitcode to human readable LLVM assembly. 907 908``llvm-link`` 909 910 ``llvm-link``, not surprisingly, links multiple LLVM modules into a single 911 program. 912 913``lli`` 914 915 ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode 916 (although very slowly...). For architectures that support it (currently x86, 917 Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time 918 compiler (if the functionality was compiled in), and will execute the code 919 *much* faster than the interpreter. 920 921``llc`` 922 923 ``llc`` is the LLVM backend compiler, which translates LLVM bitcode to a 924 native code assembly file. 925 926``opt`` 927 928 ``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations 929 (which are specified on the command line), and outputs the resultant 930 bitcode. '``opt -help``' is a good way to get a list of the 931 program transformations available in LLVM. 932 933 ``opt`` can also run a specific analysis on an input LLVM bitcode 934 file and print the results. Primarily useful for debugging 935 analyses, or familiarizing yourself with what an analysis does. 936 937``llvm/utils`` 938-------------- 939 940Utilities for working with LLVM source code; some are part of the build process 941because they are code generators for parts of the infrastructure. 942 943 944``codegen-diff`` 945 946 ``codegen-diff`` finds differences between code that LLC 947 generates and code that LLI generates. This is useful if you are 948 debugging one of them, assuming that the other generates correct output. For 949 the full user manual, run ```perldoc codegen-diff'``. 950 951``emacs/`` 952 953 Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGen 954 description files. See the ``README`` for information on using them. 955 956``getsrcs.sh`` 957 958 Finds and outputs all non-generated source files, 959 useful if one wishes to do a lot of development across directories 960 and does not want to find each file. One way to use it is to run, 961 for example: ``xemacs `utils/getsources.sh``` from the top of the LLVM source 962 tree. 963 964``llvmgrep`` 965 966 Performs an ``egrep -H -n`` on each source file in LLVM and 967 passes to it a regular expression provided on ``llvmgrep``'s command 968 line. This is an efficient way of searching the source base for a 969 particular regular expression. 970 971``TableGen/`` 972 973 Contains the tool used to generate register 974 descriptions, instruction set descriptions, and even assemblers from common 975 TableGen description files. 976 977``vim/`` 978 979 vim syntax-highlighting for LLVM assembly files 980 and TableGen description files. See the ``README`` for how to use them. 981 982.. _simple example: 983 984An Example Using the LLVM Tool Chain 985==================================== 986 987This section gives an example of using LLVM with the Clang front end. 988 989Example with clang 990------------------ 991 992#. First, create a simple C file, name it 'hello.c': 993 994 .. code-block:: c 995 996 #include <stdio.h> 997 998 int main() { 999 printf("hello world\n"); 1000 return 0; 1001 } 1002 1003#. Next, compile the C file into a native executable: 1004 1005 .. code-block:: console 1006 1007 % clang hello.c -o hello 1008 1009 .. note:: 1010 1011 Clang works just like GCC by default. The standard -S and -c arguments 1012 work as usual (producing a native .s or .o file, respectively). 1013 1014#. Next, compile the C file into an LLVM bitcode file: 1015 1016 .. code-block:: console 1017 1018 % clang -O3 -emit-llvm hello.c -c -o hello.bc 1019 1020 The -emit-llvm option can be used with the -S or -c options to emit an LLVM 1021 ``.ll`` or ``.bc`` file (respectively) for the code. This allows you to use 1022 the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file. 1023 1024#. Run the program in both forms. To run the program, use: 1025 1026 .. code-block:: console 1027 1028 % ./hello 1029 1030 and 1031 1032 .. code-block:: console 1033 1034 % lli hello.bc 1035 1036 The second examples shows how to invoke the LLVM JIT, :doc:`lli 1037 <CommandGuide/lli>`. 1038 1039#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: 1040 1041 .. code-block:: console 1042 1043 % llvm-dis < hello.bc | less 1044 1045#. Compile the program to native assembly using the LLC code generator: 1046 1047 .. code-block:: console 1048 1049 % llc hello.bc -o hello.s 1050 1051#. Assemble the native assembly language file into a program: 1052 1053 .. code-block:: console 1054 1055 % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris 1056 1057 % gcc hello.s -o hello.native # On others 1058 1059#. Execute the native code program: 1060 1061 .. code-block:: console 1062 1063 % ./hello.native 1064 1065 Note that using clang to compile directly to native code (i.e. when the 1066 ``-emit-llvm`` option is not present) does steps 6/7/8 for you. 1067 1068Common Problems 1069=============== 1070 1071If you are having problems building or using LLVM, or if you have any other 1072general questions about LLVM, please consult the `Frequently Asked 1073Questions <FAQ.html>`_ page. 1074 1075If you are having problems with limited memory and build time, please try 1076building with ninja instead of make. Please consider configuring the 1077following options with cmake: 1078 1079 * -G Ninja 1080 Setting this option will allow you to build with ninja instead of make. 1081 Building with ninja significantly improves your build time, especially with 1082 incremental builds, and improves your memory usage. 1083 1084 * -DLLVM_USE_LINKER 1085 Setting this option to lld will significantly reduce linking time for LLVM 1086 executables on ELF-based platforms, such as Linux. If you are building LLVM 1087 for the first time and lld is not available to you as a binary package, then 1088 you may want to use the gold linker as a faster alternative to GNU ld. 1089 1090 * -DCMAKE_BUILD_TYPE 1091 Controls optimization level and debug information of the build. This setting 1092 can affect RAM and disk usage, see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>` 1093 for more information. 1094 1095 * -DLLVM_ENABLE_ASSERTIONS 1096 This option defaults to ON for Debug builds and defaults to OFF for Release 1097 builds. As mentioned in the previous option, using the Release build type and 1098 enabling assertions may be a good alternative to using the Debug build type. 1099 1100 * -DLLVM_PARALLEL_LINK_JOBS 1101 Set this equal to number of jobs you wish to run simultaneously. This is 1102 similar to the -j option used with make, but only for link jobs. This option 1103 can only be used with ninja. You may wish to use a very low number of jobs, 1104 as this will greatly reduce the amount of memory used during the build 1105 process. If you have limited memory, you may wish to set this to 1. 1106 1107 * -DLLVM_TARGETS_TO_BUILD 1108 Set this equal to the target you wish to build. You may wish to set this to 1109 X86; however, you will find a full list of targets within the 1110 llvm-project/llvm/lib/Target directory. 1111 1112 * -DLLVM_OPTIMIZED_TABLEGEN 1113 Set this to ON to generate a fully optimized tablegen during your build. This 1114 will significantly improve your build time. This is only useful if you are 1115 using the Debug build type. 1116 1117 * -DLLVM_ENABLE_PROJECTS 1118 Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If 1119 compiling more than one project, separate the items with a semicolon. Should 1120 you run into issues with the semicolon, try surrounding it with single quotes. 1121 1122 * -DLLVM_ENABLE_RUNTIMES 1123 Set this equal to the runtimes you wish to compile (e.g. libcxx, libcxxabi, etc.) 1124 If compiling more than one runtime, separate the items with a semicolon. Should 1125 you run into issues with the semicolon, try surrounding it with single quotes. 1126 1127 * -DCLANG_ENABLE_STATIC_ANALYZER 1128 Set this option to OFF if you do not require the clang static analyzer. This 1129 should improve your build time slightly. 1130 1131 * -DLLVM_USE_SPLIT_DWARF 1132 Consider setting this to ON if you require a debug build, as this will ease 1133 memory pressure on the linker. This will make linking much faster, as the 1134 binaries will not contain any of the debug information; however, this will 1135 generate the debug information in the form of a DWARF object file (with the 1136 extension .dwo). This only applies to host platforms using ELF, such as Linux. 1137 1138.. _links: 1139 1140Links 1141===== 1142 1143This document is just an **introduction** on how to use LLVM to do some simple 1144things... there are many more interesting and complicated things that you can do 1145that aren't documented here (but we'll gladly accept a patch if you want to 1146write something up!). For more information about LLVM, check out: 1147 1148* `LLVM Homepage <https://llvm.org/>`_ 1149* `LLVM Doxygen Tree <https://llvm.org/doxygen/>`_ 1150* `Starting a Project that Uses LLVM <https://llvm.org/docs/Projects.html>`_ 1151