utils/gn/README.rst

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