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