Page MenuHomePhabricator
Differential D56375 Diff 180667 llvm/trunk/utils/gn/README.rst

Changeset View

Standalone View

View Options

llvm/trunk/utils/gn/README.rst

Show All 12 Lines
*Warning* The GN build is experimental and best-effort. It might not work, *Warning* The GN build is experimental and best-effort. It might not work,
and if you use it you're expected to feel comfortable to unbreak it if and if you use it you're expected to feel comfortable to unbreak it if
necessary. LLVM's official build system is CMake, if in doubt use that. necessary. LLVM's official build system is CMake, if in doubt use that.
If you add files, you're expected to update the CMake build but you don't need If you add files, you're expected to update the CMake build but you don't need
to update GN build files. Reviewers should not ask authors to update GN build to update GN build files. Reviewers should not ask authors to update GN build
files. Keeping the GN build files up-to-date is on the people who use the GN files. Keeping the GN build files up-to-date is on the people who use the GN
build. build.
*Another Warning* Right now, we're in the process of getting the GN build `GN <https://gn.googlesource.com/gn/>`_ is a metabuild system. It always
checked in. As of this writing, it's not yet functional at all. Check back
in a few weeks!
`GN <https://gn.googlesource.com/gn/>`_ is another metabuild system. It always
creates ninja files, but it can create some IDE projects (MSVC, Xcode, ...) creates ninja files, but it can create some IDE projects (MSVC, Xcode, ...)
which then shell out to ninja for the actual build. which then shell out to ninja for the actual build.
Its main features are that GN is very fast (it currently produces ninja files Its main features are that GN is very fast (it currently produces ninja files
for LLVM's build in 35ms on the author's laptop, compared to 66s for CMake) -- for LLVM's build in 35ms on the author's laptop, compared to 66s for CMake) --
a 2000x difference), and since it's so fast it doesn't aggressively cache, a 2000x difference), and since it's so fast it doesn't aggressively cache,
making it possible to switch e.g. between release and debug builds in one build making it possible to switch e.g. between release and debug builds in one build
directory. directory.
It is arguable easier to configure than the CMake build, and has native support
for building with multiple toolchains in one build directory. The build
description is declarative-ish, allowing GN to print it in a json format that
can fairly easily be converted to other metabuild system inputs.
The main motivation behind the GN build is that some people find it more The main motivation behind the GN build is that some people find it more
convenient for day-to-day hacking on LLVM than CMake. Distribution, building convenient for day-to-day hacking on LLVM than CMake. Distribution, building
just parts of LLVM, and embedding the LLVM GN build from other builds are a just parts of LLVM, and embedding the LLVM GN build from other builds are a
non-goal for the GN build. non-goal for the GN build.
This is a `good overview of GN <https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12>`_. This is a `good overview of GN <https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12>`_.
.. _Quick start: .. _Quick start:
Quick start Quick start
=========== ===========
*Warning* Right now, we're in the process of getting the GN build checked in.
As of this writing, it's not yet functional at all.
GN only works in the monorepo layout. GN only works in the monorepo layout.
#. Obtain a `gn binary <https://gn.googlesource.com/gn/#getting-started>`_. #. Obtain a `gn binary <https://gn.googlesource.com/gn/#getting-started>`_.
#. In the root of the monorepo, run #. In the root of the monorepo, run
`gn gen --dotfile=$PWD/llvm/utils/gn/.gn --root=. out/gn` (`out/gn` is the `gn gen --dotfile=$PWD/llvm/utils/gn/.gn --root=. out/gn` (`out/gn` is the
build directory, it can have any name, and you can have as many as you want, build directory, it can have any name, and you can have as many as you want,
each with different build settings). each with different build settings).
#. Run e.g. `ninja -C out/gn llvm-undname` to build all prerequisites for and #. Run e.g. `ninja -C out/gn check-lld` to build all prerequisites for and
including the Microsoft symbol name pretty printing tool llvm-undname. run the LLD tests.
By default, you get a release build with assertions enabled that targets By default, you get a release build with assertions enabled that targets
the host arch. You can set various build options by editing `out/gn/args.gn`, the host arch. You can set various build options by editing `out/gn/args.gn`,
for example putting `is_debug = true` in there gives you a debug build. Run for example putting `is_debug = true` in there gives you a debug build. Run
`gn args --list out/gn` to see a list of all possible options. After touching `gn args --list out/gn` to see a list of all possible options. After touching
`out/gn/args.gn`, just run ninja, it will re-invoke gn before starting the `out/gn/args.gn`, just run ninja, it will re-invoke gn before starting the
build. build.
▲ Show 20 Lines • Show All 74 Lines • Show Last 20 Lines