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