README (3013B)
1 build-clang.py 2 ============== 3 4 A script to build clang from source. 5 6 ``` 7 usage: build-clang.py [-h] -c CONFIG [--clean] 8 9 optional arguments: 10 -h, --help show this help message and exit 11 -c CONFIG, --config CONFIG 12 Clang configuration file 13 --clean Clean the build directory 14 ``` 15 16 Pre-requisites 17 -------------- 18 * Working build toolchain. 19 * git 20 * CMake 21 * Ninja 22 * Python 2.7 and 3 23 24 Please use the latest available CMake for your platform to avoid surprises. 25 26 Config file format 27 ------------------ 28 29 build-clang.py accepts a JSON config format with the following fields: 30 31 * stages: Use 1, 2, 3 or 4 to select different compiler stages. The default is 2. 32 * cc: Path to the bootstraping C Compiler. 33 * cxx: Path to the bootstraping C++ Compiler. 34 * as: Path to the assembler tool. 35 * ar: Path to the library archiver tool. 36 * ranlib: Path to the ranlib tool (optional). 37 * ld: Path to the linker. 38 * patches: Optional list of patches to apply. 39 * build_type: The type of build to make. Supported types: Release, Debug, RelWithDebInfo or MinSizeRel. 40 * targets: The targets supported by the final stage LLVM/clang. 41 * build_clang_tidy: Whether to build clang-tidy with the Mozilla checks imported. The default is false. 42 * osx_cross_compile: Whether to invoke CMake for OS X cross compile builds. 43 * assertions: Whether to enable LLVM assertions. The default is false. 44 * pgo: Whether to build with PGO (requires stages == 4). The default is false. 45 46 The revisions are defined in taskcluster/kinds/fetch/toolchains.yml. They are usually commit sha1s corresponding to upstream tags. 47 48 Environment Variables 49 --------------------- 50 51 The following environment variables are used for cross-compile builds targeting OS X on Linux. 52 53 * OSX_SYSROOT: Path to the OS X SDK directory for cross compile builds. 54 55 Writing Patches 56 --------------- 57 58 Patches to Clang should be registered in ``clang-$n.json`` for patches to Clang ``$n.x``. They are applied in order. 59 60 When backporting patches from upstream, please use the output of ``git describe $rev`` to name the patch file, where ``$rev`` is the original revision upstream. 61 62 When reverting a commit from upstream, say ``$reverted_rev``, please name the patch ``revert-$(git describe $reverted_rev)``. 63 64 When adding a downstream patch, please suffix the patch with ``_clang_$n.patch``, where ``$n`` is the first version of Clang for which that patch needs to be applied. In the very common situation where the patch needs to be applied on the ``main`` branch, use the current development version number of Clang as ``$n``. 65 66 Patches in ``clang-$n.json`` are ordered following the following rules: 67 68 1. Patches that start with ``revert-llvmorg`` are in *reverse* `natural sort order <https://en.wikipedia.org/wiki/Natural_sort_order>`_. 69 2. Patches that start with ``llvmorg`` are in natural sort order. 70 3. Patches that correspond to an upstream *revert* come before the *cherry-picked* ones. 71 72 Other patches do not follow any specific ordering rule.