Lines Matching +full:check +full:- +full:docs +full:- +full:build
19 C-like languages use the `Clang <https://clang.llvm.org/>`_ front end. This
21 -- and from there into object files, using LLVM.
32 #. Check out LLVM (including subprojects like Clang):
34 * ``git clone https://github.com/llvm/llvm-project.git``
37 ``git clone --config core.autocrlf=false
38 https://github.com/llvm/llvm-project.git``
39 * To save storage and speed-up the checkout time, you may want to do a
40 `shallow clone <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt>`_.
43 ``git clone --depth 1 https://github.com/llvm/llvm-project.git``
46 stacked pull-requests and reverts), you can filter them from your
49 .. code-block:: console
51 git config --add remote.origin.fetch '^refs/heads/users/*'
52 git config --add remote.origin.fetch '^refs/heads/revert-*'
54 #. Configure and build LLVM and Clang:
56 * ``cd llvm-project``
57 * ``cmake -S llvm -B build -G <generator> [options]``
59 Some common build system generators are:
61 * ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_
62 build files. Most llvm developers use Ninja.
63 * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
64 * ``Visual Studio`` --- for generating Visual Studio projects and
66 * ``Xcode`` --- for generating Xcode projects.
68 * See the `CMake docs
69 <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_
74 * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
75 subprojects you'd like to additionally build. Can include any of: clang,
76 clang-tools-extra, lldb, lld, polly, or cross-project-tests.
78 For example, to build LLVM, Clang, and LLD, use
79 ``-DLLVM_ENABLE_PROJECTS="clang;lld"``.
81 * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
85 * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug
86 information of the build. Valid options for *type* are ``Debug``,
90 * ``-DLLVM_ENABLE_ASSERTIONS=ON`` --- Compile with assertion checks enabled
91 (default is ON for Debug builds, OFF for all other build types).
93 * ``-DLLVM_USE_LINKER=lld`` --- Link with the `lld linker`_, assuming it
97 * ``-DLLVM_PARALLEL_{COMPILE,LINK,TABLEGEN}_JOBS=N`` --- Limit the number of
103 * ``cmake --build build [--target <target>]`` or the build system specified
106 * The default target (i.e. ``cmake --build build`` or ``make -C build``)
107 will build all of LLVM.
109 * The ``check-all`` target (i.e. ``ninja check-all``) will run the
112 * CMake will generate build targets for each tool and library, and most
113 LLVM sub-projects generate their own ``check-<project>`` target.
115 * Running a serial build will be **slow**. To improve speed, try running a
116 parallel build. That's done by default in Ninja; for ``make``, use the
117 option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the
120 * A basic CMake and build/test invocation which only builds LLVM and no other
123 ``cmake -S llvm -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug``
125 ``ninja -C build check-llvm``
127 This will setup an LLVM build with debugging info, then compile LLVM and
132 * If you get build or test failures, see `below`_.
138 Stand-alone Builds
139 ------------------
141 Stand-alone builds allow you to build a sub-project against a pre-built
145 You can use the source code from a standard checkout of the llvm-project
146 (as described above) to do stand-alone builds, but you may also build
147 from a :ref:`sparse checkout<workflow-multicheckout-nocommit>` or from the
148 tarballs available on the `releases <https://github.com/llvm/llvm-project/releases/>`_
151 For stand-alone builds, you must have an llvm install that is configured
152 properly to be consumable by stand-alone builds of the other projects.
153 This could be a distro provided LLVM install, or you can build it yourself,
156 .. code-block:: console
158 cmake -G Ninja -S path/to/llvm-project/llvm -B $builddir \
159 -DLLVM_INSTALL_UTILS=ON \
160 -DCMAKE_INSTALL_PREFIX=/path/to/llvm/install/prefix \
163 ninja -C $builddir install
165 Once llvm is installed, to configure a project for a stand-alone build, invoke CMake like this:
167 .. code-block:: console
169 cmake -G Ninja -S path/to/llvm-project/$subproj \
170 -B $buildir_subproj \
171 -DLLVM_EXTERNAL_LIT=/path/to/lit \
172 -DLLVM_ROOT=/path/to/llvm/install/prefix
176 * The stand-alone build needs to happen in a folder that is not the
181 ``/usr/lib64``, then you should pass ``-DLLVM_ROOT=/usr/``.
183 required to do stand-alone builds for all sub-projects. Additional
184 required options for each sub-project can be found in the table
187 The ``check-$subproj`` and ``install`` build targets are supported for the
188 sub-projects listed in the table below.
191 Sub-Project Required Sub-Directories Required CMake Options
193 llvm llvm, cmake, third-party LLVM_INSTALL_UTILS=ON
194 clang clang, cmake CLANG_INCLUDE_TESTS=ON (Required for check-clang only)
198 Example for building stand-alone `clang`:
200 .. code-block:: console
204 build_llvm=`pwd`/build-llvm
205 build_clang=`pwd`/build-clang
207 llvm=`pwd`/llvm-project
208 mkdir -p $build_llvm
209 mkdir -p $installprefix
211 cmake -G Ninja -S $llvm/llvm -B $build_llvm \
212 -DLLVM_INSTALL_UTILS=ON \
213 -DCMAKE_INSTALL_PREFIX=$installprefix \
214 -DCMAKE_BUILD_TYPE=Release
216 ninja -C $build_llvm install
218 cmake -G Ninja -S $llvm/clang -B $build_clang \
219 -DLLVM_EXTERNAL_LIT=$build_llvm/utils/lit \
220 -DLLVM_ROOT=$installprefix
222 ninja -C $build_clang
232 --------
260 Windows x64 x86-64 Visual Studio, Clang\ :sup:`4`
267 #. Code generation supported for 32-bit ABI only
268 #. To use LLVM modules on Win32-based system, you may configure LLVM
269 with ``-DBUILD_SHARED_LIBS=On``.
273 Note that Debug builds require a lot of time and disk space. An LLVM-only build
274 will need about 1-3 GB of space. A full build of LLVM and Clang will need around
275 15-20 GB of disk space. The exact space requirements will vary by system. (It
279 If you are space-constrained, you can build only selected tools or only
280 selected targets. The Release build requires considerably less space.
289 --------
303 `GNU Make <http://savannah.gnu.org/projects/make>`_ 3.79, 3.79.1 Makefile/build processor\ :sup:`3`
314 #. Optional, you can use any other build tool supported by CMake.
320 * **ar** --- archive library builder
321 * **bzip2** --- bzip2 command for distribution generation
322 * **bunzip2** --- bunzip2 command for distribution checking
323 * **chmod** --- change permissions on a file
324 * **cat** --- output concatenation utility
325 * **cp** --- copy files
326 * **date** --- print the current date/time
327 * **echo** --- print to standard output
328 * **egrep** --- extended regular expression search utility
329 * **find** --- find files/dirs in a file system
330 * **grep** --- regular expression search utility
331 * **gzip** --- gzip command for distribution generation
332 * **gunzip** --- gunzip command for distribution checking
333 * **install** --- install directories/files
334 * **mkdir** --- create a directory
335 * **mv** --- move (rename) files
336 * **ranlib** --- symbol table builder for archive libraries
337 * **rm** --- remove (delete) files and directories
338 * **sed** --- stream editor for transforming output
339 * **sh** --- Bourne shell for make build scripts
340 * **tar** --- tape archive for distribution generation
341 * **test** --- test things in file system
342 * **unzip** --- unzip command for distribution checking
343 * **zip** --- zip command for distribution generation
351 ------------------------------------------------------
356 host C++ toolchain, both compiler and standard library, in order to build LLVM.
359 standards<CodingStandards>`. To enforce this language version, we check the most
360 popular host toolchains for specific minimum versions in our build systems:
368 build system with a special option and is not really a supported host platform.
409 well tested or set up to build on Linux until relatively recently. As
420 you're here you *are* doing compiler development after all) to build and install
424 https://launchpad.net/~ubuntu-toolchain-r/+archive/test
426 https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149
432 .. code-block:: console
435 % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2
436 % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig
437 % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
438 % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig`
440 % tar -xvjf gcc-${gcc_version}.tar.bz2
441 % cd gcc-${gcc_version}
444 % mkdir gcc-${gcc_version}-build
445 % cd gcc-${gcc_version}-build
446 % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++
447 % make -j$(nproc)
450 For more details, check out the excellent `GCC wiki entry`_, where I got most
456 Once you have a GCC toolchain, configure your build of LLVM to use the new
459 extra linker flags so that it can be found at link time (``-L``) and at runtime
460 (``-rpath``). If you are using CMake, this invocation should produce working
463 .. code-block:: console
465 % mkdir build
466 % cd build
468 cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"
472 found``. This means you need to tweak the -rpath linker flag.
475 fine for local development. If you want to distribute the binaries you build
478 ``$ORIGIN/../lib``, so they will find ``libstdc++.so.6`` there. Non-distributed
480 ``-DLLVM_LOCAL_RPATH="$HOME/toolchains/lib64"`` to cmake to add an absolute
484 When you build Clang, you will need to give *it* access to modern C++
486 There are two easy ways to do this, either build (and install) libc++ along
487 with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
491 the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and
492 link commands when using your just-built-Clang to bootstrap.
504 more information about LLVM or to get help via e-mail.
507 ------------------------
545 ------------------------
549 script, CMake generates the build files in whatever format you request as well
553 ``-D<variable name>=<value>``. The following variables are some common options
571 See :ref:`the list of frequently-used CMake variables <cmake_frequently_used_variables>`
578 .. code-block:: console
584 .. code-block:: console
586 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=<type> -DCMAKE_INSTALL_PREFIX=/install/path
590 ------------------------------------
592 Unlike with autotools, with CMake your build type is defined at configuration.
593 If you want to change your build type, you can re-run cmake with the following
596 .. code-block:: console
598 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=<type> SRC_ROOT
601 following build types defined:
605 These builds are the default. The build system will compile the tools and
610 For these builds, the build system will compile the tools and libraries
612 optimization level is -O3. This can be configured by setting the
618 debug information. CMakes default optimization level is -O2. This can be
622 Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
625 .. code-block:: console
629 If the build fails, please `check here`_ to see if you are using a version of
633 parallel build options provided by GNU Make. For example, you could use the
636 .. code-block:: console
638 % make -j2
645 Removes all files generated by the build. This includes object files,
654 ``make docs-llvm-html``
656 If configured with ``-DLLVM_ENABLE_SPHINX=On``, this will generate a directory
657 at ``OBJ_ROOT/docs/html`` which contains the HTML formatted documentation.
659 Cross-Compiling LLVM
660 --------------------
662 It is possible to cross-compile LLVM itself. That is, you can create LLVM
664 where they are built (a Canadian Cross build). To generate build files for
665 cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can
668 The result of such a build is executables that are not runnable on the build
670 invocation can generate build files targeting iOS. This will work on macOS
673 .. code-block:: console
675 % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES="armv7;armv7s;arm64"
676 -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
677 -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off
678 -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]
684 Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
685 <https://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
686 about cross-compiling.
689 ---------------------------------
691 The LLVM build system is capable of sharing a single LLVM source tree among
692 several LLVM builds. Hence, it is possible to build LLVM for several different
697 .. code-block:: console
703 .. code-block:: console
705 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release SRC_ROOT
707 The LLVM build will create a structure underneath *OBJ_ROOT* that matches the
715 .. code-block:: console
718 % find lib/Support/ -name APFloat*
722 ----------------------------
730 .. code-block:: console
732 % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
740 .. code-block:: console
742 % sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
756 --------------
757 Generates system build files.
760 Build configuration for llvm user defined options. Checks compiler version and
764 Toolchain configuration for Android NDK, iOS systems and non-Windows hosts to
768 -----------------
770 - Some simple examples showing how to use LLVM as a compiler for a custom
771 language - including lowering, optimization, and code generation.
773 - Kaleidoscope Tutorial: Kaleidoscope language tutorial run through the
774 implementation of a nice little compiler for a non-trivial language
775 including a hand-written lexer, parser, AST, as well as code generation
776 support using LLVM- both static (ahead of time) and various approaches to
779 <https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html>`_.
781 - BuildingAJIT: Examples of the `BuildingAJIT tutorial
782 <https://llvm.org/docs/tutorial/BuildingAJIT1.html>`_ that shows how LLVM’s
784 recombine them to build a custom JIT that is suited to your use-case.
787 ----------------
793 All LLVM-specific header files, and subdirectories for different portions of
810 ------------
835 IR-to-IR program transformations, such as Aggressive Dead Code Elimination,
852 assembly and object-file emission.
857 JIT-compiled scenarios.
865 ----------------------
873 -----------------
876 directory for creating your own LLVM-based projects which leverage the LLVM
877 build system.
880 -------------
885 ``test-suite``
886 --------------
890 <https://github.com/llvm/llvm-test-suite>``, because it contains a
891 large amount of third-party code under a variety of licenses. For
897 --------------
901 for a tool by typing ``tool_name -help``. The following is a brief introduction
913 ``llvm-ar``
918 ``llvm-as``
922 ``llvm-dis``
926 ``llvm-link``
928 ``llvm-link``, not surprisingly, links multiple LLVM modules into a single
935 Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time
948 bitcode. '``opt -help``' is a good way to get a list of the
956 --------------
958 Utilities for working with LLVM source code; some are part of the build process
962 ``codegen-diff``
964 ``codegen-diff`` finds differences between code that LLC
967 the full user manual, run ```perldoc codegen-diff'``.
976 Finds and outputs all non-generated source files,
984 Performs an ``egrep -H -n`` on each source file in LLVM and
997 vim syntax-highlighting for LLVM assembly files
1008 ------------------
1012 .. code-block:: c
1023 .. code-block:: console
1025 % clang hello.c -o hello
1029 Clang works just like GCC by default. The standard -S and -c arguments
1034 .. code-block:: console
1036 % clang -O3 -emit-llvm hello.c -c -o hello.bc
1038 The -emit-llvm option can be used with the -S or -c options to emit an LLVM
1044 .. code-block:: console
1050 .. code-block:: console
1057 #. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
1059 .. code-block:: console
1061 % llvm-dis < hello.bc | less
1065 .. code-block:: console
1067 % llc hello.bc -o hello.s
1071 .. code-block:: console
1073 % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris
1075 % gcc hello.s -o hello.native # On others
1079 .. code-block:: console
1084 ``-emit-llvm`` option is not present) does steps 6/7/8 for you.
1093 If you are having problems with limited memory and build time, please try
1097 * ``-G Ninja``
1099 Setting this option will allow you to build with ninja instead of make.
1100 Building with ninja significantly improves your build time, especially with
1103 * ``-DLLVM_USE_LINKER``
1110 * ``-DCMAKE_BUILD_TYPE``
1112 Controls optimization level and debug information of the build. This setting
1116 * ``-DLLVM_ENABLE_ASSERTIONS``
1119 builds. As mentioned in the previous option, using the Release build type and
1120 enabling assertions may be a good alternative to using the Debug build type.
1122 * ``-DLLVM_PARALLEL_LINK_JOBS``
1125 similar to the ``-j`` option used with ``make``, but only for link jobs. This option
1127 as this will greatly reduce the amount of memory used during the build
1130 * ``-DLLVM_TARGETS_TO_BUILD``
1132 Set this equal to the target you wish to build. You may wish to set this to
1135 `llvm-project/llvm/lib/Target <https://github.com/llvm/llvm-project/tree/main/llvm/lib/Target>`_
1138 * ``-DLLVM_OPTIMIZED_TABLEGEN``
1141 build, even if that build is a ``Debug`` build. This will significantly improve
1142 your build time. You should not enable this if your intention is to debug the
1145 * ``-DLLVM_ENABLE_PROJECTS``
1151 * ``-DLLVM_ENABLE_RUNTIMES``
1157 * ``-DCLANG_ENABLE_STATIC_ANALYZER``
1160 should improve your build time slightly.
1162 * ``-DLLVM_USE_SPLIT_DWARF``
1164 Consider setting this to ``ON`` if you require a debug build, as this will ease
1170 * ``-DBUILD_SHARED_LIBS``
1172 Setting this to ``ON`` will build shared libraries instead of static
1175 :ref:`BUILD_SHARED_LIBS <LLVM-related variables BUILD_SHARED_LIBS>`
1186 write something up!). For more information about LLVM, check out:
1190 * `Starting a Project that Uses LLVM <https://llvm.org/docs/Projects.html>`_