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