1===================== 2Building LLVM with GN 3===================== 4 5.. contents:: 6 :local: 7 8.. _Introduction: 9 10Introduction 11============ 12 13*Warning* The GN build is experimental and best-effort. It might not work, 14and if you use it you're expected to feel comfortable to unbreak it if 15necessary. LLVM's official build system is CMake, if in doubt use that. 16If you add files, you're expected to update the CMake build but you don't need 17to update GN build files. Reviewers should not ask authors to update GN build 18files. Keeping the GN build files up-to-date is on the people who use the GN 19build. 20 21`GN <https://gn.googlesource.com/gn/>`_ is a metabuild system. It always 22creates ninja files, but it can create some IDE projects (MSVC, Xcode, ...) 23which then shell out to ninja for the actual build. 24 25The main motivation behind the GN build is that some people find it more 26convenient for day-to-day hacking on LLVM than CMake. Distribution, building 27just parts of LLVM, and embedding the LLVM GN build from other builds are 28non-goals for the GN build. 29 30This is a `good overview of GN <https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12>`_. 31 32.. _Quick start: 33 34Quick start 35=========== 36 37#. ``git clone https://github.com/llvm/llvm-project.git; cd llvm-project`` if 38 you don't have a checkout yet. 39 40#. ``llvm/utils/gn/get.py`` to download a prebuilt gn binary if you're on a 41 64-bit X86 system running Linux, macOS, or Windows. `Build gn yourself 42 <https://gn.googlesource.com/gn/#getting-started>`_ if you're on a different 43 platform or don't want to trust prebuilt binaries. 44 45#. ``llvm/utils/gn/gn.py gen out/gn`` to run GN and create build files. 46 ``out/gn`` is the build directory, it can have any name, and you can have as 47 many as you want, each with different build settings. (The ``gn.py`` script 48 adds ``--dotfile=llvm/utils/gn/.gn --root=.`` and just runs regular ``gn``; 49 you can manually pass these parameters and not use the wrapper if you 50 prefer.) 51 52#. ``echo out >> .git/info/exclude`` to tell git to ignore files below ``out``. 53 54#. ``ninja -C out/gn check-lld`` to build all prerequisites for and run the LLD 55 tests. 56 57By default, you get a release build with assertions enabled that targets 58the host arch. You can set build options by editing ``out/gn/args.gn``, for 59example putting ``is_debug = true`` in there gives you a debug build. Run 60``llvm/utils/gn/gn.py args --list out/gn`` to see a list of all possible 61options. After touching ``out/gn/args.gn`` just run ninja: it will re-invoke gn 62before starting the build. 63 64GN has extensive built-in help; try e.g. ``llvm/utils/gn/gn.py help gen`` to see 65the help for the ``gen`` command. The full GN reference is also `available 66online <https://gn.googlesource.com/gn/+/master/docs/reference.md>`_. 67 68GN has an autoformatter: 69``git ls-files '*.gn' '*.gni' | xargs llvm/utils/gn/gn.py format`` 70after making GN build changes is your friend. 71 72To not put ``BUILD.gn`` files into the main tree, they are all below 73``utils/gn/secondary``. For example, the build file for ``llvm/lib/Support`` 74is in ``utils/gn/secondary/llvm/lib/Support``. 75 76.. _Syncing GN files from CMake files: 77 78Syncing GN files from CMake files 79================================= 80 81Sometimes after pulling in the latest changes, the GN build doesn't work. 82Most of the time this is due to someone adding a file to CMakeLists.txt file. 83Run ``llvm/utils/gn/build/sync_source_lists_from_cmake.py`` to print a report 84of which files need to be added to or removed from ``BUILD.gn`` files to 85match the corresponding ``CMakeLists.txt``. You have to manually read the output 86of the script and implement its suggestions. 87 88If new ``CMakeLists.txt`` files have been added, you have to manually create 89a new corresponding ``BUILD.gn`` file below ``llvm/utils/gn/secondary/``. 90 91If the dependencies in a ``CMakeLists.txt`` file have been changed, you have to 92manually analyze and fix. 93 94.. _Philosophy: 95 96Philosophy 97========== 98 99GN believes in using GN arguments to configure the build explicitly, instead 100of implicitly figuring out what to do based on what's available on the current 101system. 102 103configure is used for three classes of feature checks: 104 105- compiler checks. In GN, these could use exec_script to identify the host 106 compiler at GN time. For now the build has explicit toggles for compiler 107 features. (Maybe there could be a script that writes args.gn based on the 108 host compiler). It's possible we'll use exec_script() for this going forward, 109 but we'd have one exec_script call to identify compiler id and version, 110 and then base GN arg default values of compiler id and version instead of 111 doing one exec_script per feature check. 112 (In theory, the config approach means a new os / compiler just needs to tweak 113 the checks and not the code, but in practice a) new os's / compilers are rare 114 b) they will require code changes anyhow, so the configure tradeoff seems 115 not worth it.) 116 117- library checks. For e.g. like zlib, GN thinks it's better to say "we require 118 zlib, else we error at build time" than silently omitting features. People 119 who really don't want to install zlib can explicitly set the GN arg to turn 120 off zlib. 121 122- header checks (does system header X exist). These are generally not needed 123 (just keying this off the host OS works fine), but if they should become 124 necessary in the future, they should be done at build time and the few 125 targets that need to know if header X exists then depend on that build-time 126 check while everything else can build parallel with it. 127 128- LLVM-specific build toggles (assertions on/off, debug on/off, targets to 129 build, ...). These map cleanly to GN args (which then get copied into 130 config.h in a build step). 131 132For the last two points, it would be nice if LLVM didn't have a single 133``config.h`` header, but one header per toggle. That way, when e.g. 134``llvm_enable_terminfo`` is toggled, only the 3 files caring about that setting 135would need to be rebuilt, instead of everything including ``config.h``. 136 137GN doesn't believe in users setting arbitrary cflags from an environment 138variable, it wants the build to be controlled by .gn files. 139