Lines Matching +full:docs +full:- +full:clang +full:- +full:tools +full:- +full:html
14 itself called "LLVM". This contains all of the tools, libraries, and header
16 object files. Tools include an assembler, disassembler, bitcode analyzer, and
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]``
61 * ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_
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
82 pathname of where you want the LLVM tools and libraries to be installed
85 * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug
90 * ``-DLLVM_ENABLE_ASSERTIONS=ON`` --- Compile with assertion checks enabled
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``)
109 * The ``check-all`` target (i.e. ``ninja check-all``) will run the
113 LLVM sub-projects generate their own ``check-<project>`` target.
117 option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the
123 ``cmake -S llvm -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug``
125 ``ninja -C build check-llvm``
130 * For more detailed information on CMake options, see `CMake <CMake.html>`__
138 Stand-alone Builds
139 ------------------
141 Stand-alone builds allow you to build a sub-project against a pre-built
142 version of the clang or llvm libraries that is already present on your
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.
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 --------
239 Linux x86\ :sup:`1` GCC, Clang
240 Linux amd64 GCC, Clang
241 Linux ARM GCC, Clang
242 Linux AArch64 GCC, Clang
243 Linux Mips GCC, Clang
244 Linux PowerPC GCC, Clang
245 Linux SystemZ GCC, Clang
247 DragonFlyBSD amd64 GCC, Clang
248 FreeBSD x86\ :sup:`1` GCC, Clang
249 FreeBSD amd64 GCC, Clang
250 FreeBSD AArch64 GCC, Clang
251 NetBSD x86\ :sup:`1` GCC, Clang
252 NetBSD amd64 GCC, Clang
253 OpenBSD x86\ :sup:`1` GCC, Clang
254 OpenBSD amd64 GCC, Clang
256 macOS x86 GCC, Clang
257 macOS arm64 Clang
260 Windows x64 x86-64 Visual Studio, Clang\ :sup:`4`
261 Windows on Arm ARM64 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``.
270 #. Visual Studio alone can compile LLVM. When using Clang, you
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
277 libraries are statically linked into multiple tools).
279 If you are space-constrained, you can build only selected tools or only
289 --------
313 tools.
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 ------------------------------------------------------
362 * Clang 5.0
363 * Apple Clang 10.0
401 have a modern Clang as the system compiler.
408 version of Clang and libc++ to be the host compiler, however libc++ was not
411 initial host in a bootstrap, and then using Clang (and potentially libc++).
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)
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
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.
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++
487 with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
488 or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC.
489 Clang will look within its own prefix for libstdc++ and use it if found. You
490 can also add an explicit prefix for Clang to look in for a GCC toolchain with
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 ------------------------
533 See `Bisecting LLVM code <GitBisecting.html>`_ for how to use ``git bisect``
545 ------------------------
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 ------------------------------------
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
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
625 .. code-block:: console
636 .. code-block:: console
638 % make -j2
650 Installs LLVM header files, libraries, tools, and documentation in a hierarchy
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
665 cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can
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 ---------------------------------
697 .. code-block:: console
703 .. code-block:: console
705 % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release SRC_ROOT
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 --------------
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 ------------
813 share code among the `tools`_.
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
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
896 ``llvm/tools``
897 --------------
901 for a tool by typing ``tool_name -help``. The following is a brief introduction
902 to the most important tools. More detailed information is in
903 the `Command Guide <CommandGuide/index.html>`_.
910 miscompilation. See `<HowToSubmitABug.html>`_ for more information on using
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 --------------
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
1005 This section gives an example of using LLVM with the Clang front end.
1007 Example with clang
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
1040 the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file.
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
1083 Note that using clang to compile directly to native code (i.e. when the
1084 ``-emit-llvm`` option is not present) does steps 6/7/8 for you.
1091 Questions <FAQ.html>`_ page.
1097 * ``-G Ninja``
1103 * ``-DLLVM_USE_LINKER``
1110 * ``-DCMAKE_BUILD_TYPE``
1116 * ``-DLLVM_ENABLE_ASSERTIONS``
1122 * ``-DLLVM_PARALLEL_LINK_JOBS``
1125 similar to the ``-j`` option used with ``make``, but only for link jobs. This option
1130 * ``-DLLVM_TARGETS_TO_BUILD``
1135 `llvm-project/llvm/lib/Target <https://github.com/llvm/llvm-project/tree/main/llvm/lib/Target>`_
1138 * ``-DLLVM_OPTIMIZED_TABLEGEN``
1145 * ``-DLLVM_ENABLE_PROJECTS``
1147 Set this equal to the projects you wish to compile (e.g. ``clang``, ``lld``, etc.) If
1151 * ``-DLLVM_ENABLE_RUNTIMES``
1157 * ``-DCLANG_ENABLE_STATIC_ANALYZER``
1159 Set this option to ``OFF`` if you do not require the clang static analyzer. This
1162 * ``-DLLVM_USE_SPLIT_DWARF``
1170 * ``-DBUILD_SHARED_LIBS``
1175 :ref:`BUILD_SHARED_LIBS <LLVM-related variables BUILD_SHARED_LIBS>`
1190 * `Starting a Project that Uses LLVM <https://llvm.org/docs/Projects.html>`_