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