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