README.md
1# GN
2
3GN is a meta-build system that generates build files for
4[Ninja](https://ninja-build.org).
5
6Related resources:
7
8 * Documentation in [docs/](https://gn.googlesource.com/gn/+/main/docs/). In
9 particular:
10 * [GN quick start guide](https://gn.googlesource.com/gn/+/main/docs/quick_start.md).
11 * [Frequently asked questions](https://gn.googlesource.com/gn/+/main/docs/faq.md)
12 * [Reference](https://gn.googlesource.com/gn/+/main/docs/reference.md)
13 (all builtin help converted to a single file).
14 * An introductory [presentation](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit?usp=sharing).
15 * The [mailing list](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev).
16 * The [bug database](https://bugs.chromium.org/p/gn/issues/list).
17
18## What GN is for
19
20GN is currently used as the build system for Chromium, Fuchsia, and related
21projects. Some strengths of GN are:
22
23 * It is designed for large projects and large teams. It scales efficiently to
24 many thousands of build files and tens of thousands of source files.
25
26 * It has a readable, clean syntax. Once a build is set-up, it is generally
27 easy for people with no backround in GN to make basic edits to the build.
28
29 * It is designed for multi-platform projects. It can cleanly express many
30 complicated build variants across different platforms. A single build
31 invocation can target multiple platforms.
32
33 * It supports multiple parallel output directories, each with their own
34 configuration. This allows a developer to maintain builds targeting debug,
35 release, or different platforms in parallel without forced rebuilds when
36 switching.
37
38 * It has a focus on correctness. GN checks for the correct dependencies,
39 inputs, and outputs to the extent possible, and has a number of tools to
40 allow developers to ensure the build evolves as desired (for example, `gn
41 check`, `testonly`, `assert_no_deps`).
42
43 * It has comprehensive build-in help available from the command-line.
44
45Although small projects successfully use GN, the focus on large projects has
46some disadvanages:
47
48 * GN has the goal of being minimally expressive. Although it can be quite
49 flexible, a design goal is to direct members of a large team (who may not
50 have much knowledge about the build) down an easy-to-understand, well-lit
51 path. This isn't necessarily the correct trade-off for smaller projects.
52
53 * The minimal build configuration is relatively heavyweight. There are several
54 files required and the exact way all compilers are linkers are run must be
55 specified in the configuration (see "Examples" below). There is no default
56 compiler configuration.
57
58 * It is not easily composable. GN is designed to compile a single large
59 project with relatively uniform settings and rules. Projects like Chromium
60 do bring together multiple repositories from multiple teams, but the
61 projects must agree on some conventions in the build files to allow this to
62 work.
63
64 * GN is designed with the expectation that the developers building a project
65 want to compile an identical configuration. So while builds can integrate
66 with the user's environment like the CXX and CFLAGS variables if they want,
67 this is not the default and most project's builds do not do this. The result
68 is that many GN projects do not integrate well with other systems like
69 ebuild.
70
71 * There is no simple release scheme (see "Versioning and distribution" below).
72 Projects are expected to manage the version of GN they require. Getting an
73 appropriate GN binary can be a hurdle for new contributors to a project.
74 Since GN is relatively uncommon, it can be more difficult to find
75 information and examples.
76
77GN can generate Ninja build files for C, C++, Rust, Objective C, and Swift
78source on most popular platforms. Other languages can be compiled using the
79general "action" rules which are executed by Python or another scripting
80language (Google does this to compile Java and Go). But because this is not as
81clean, generally GN is only used when the bulk of the build is in one of the
82main built-in languages.
83
84## Getting a binary
85
86You can download the latest version of GN binary for
87[Linux](https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest),
88[macOS](https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest) and
89[Windows](https://chrome-infra-packages.appspot.com/dl/gn/gn/windows-amd64/+/latest)
90from Google's build infrastructure (see "Versioning and distribution" below for
91how this is expected to work).
92
93Alternatively, you can build GN from source with a C++17 compiler:
94
95 git clone https://gn.googlesource.com/gn
96 cd gn
97 python build/gen.py
98 ninja -C out
99 # To run tests:
100 out/gn_unittests
101
102On Windows, it is expected that `cl.exe`, `link.exe`, and `lib.exe` can be found
103in `PATH`, so you'll want to run from a Visual Studio command prompt, or
104similar.
105
106On Linux, Mac and z/OS, the default compiler is `clang++`, a recent version is
107expected to be found in `PATH`. This can be overridden by setting `CC`, `CXX`,
108and `AR`.
109
110On z/OS, building GN requires [ZOSLIB](https://github.com/ibmruntimes/zoslib) to be
111installed, as described at that URL. When building with `build/gen.py`, use the option
112`--zoslib-dir` to specify the path to [ZOSLIB](https://github.com/ibmruntimes/zoslib):
113
114 cd gn
115 python build/gen.py --zoslib-dir /path/to/zoslib
116
117By default, if you don't specify `--zoslib-dir`, `gn/build/gen.py` expects to find
118`zoslib` directory under `gn/third_party/`.
119
120## Examples
121
122There is a simple example in [examples/simple_build](examples/simple_build)
123directory that is a good place to get started with the minimal configuration.
124
125To build and run the simple example with the default gcc compiler:
126
127 cd examples/simple_build
128 ../../out/gn gen -C out
129 ninja -C out
130 ./out/hello
131
132For a maximal configuration see the Chromium setup:
133 * [.gn](https://cs.chromium.org/chromium/src/.gn)
134 * [BUILDCONFIG.gn](https://cs.chromium.org/chromium/src/build/config/BUILDCONFIG.gn)
135 * [Toolchain setup](https://cs.chromium.org/chromium/src/build/toolchain/)
136 * [Compiler setup](https://cs.chromium.org/chromium/src/build/config/compiler/BUILD.gn)
137
138and the Fuchsia setup:
139 * [.gn](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/.gn)
140 * [BUILDCONFIG.gn](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/config/BUILDCONFIG.gn)
141 * [Toolchain setup](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/toolchain/)
142 * [Compiler setup](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/config/BUILD.gn)
143
144## Reporting bugs
145
146If you find a bug, you can see if it is known or report it in the [bug
147database](https://bugs.chromium.org/p/gn/issues/list).
148
149## Sending patches
150
151GN uses [Gerrit](https://www.gerritcodereview.com/) for code review hosted at
152[gn-review.googlesource.com](https://gn-review.googlesource.com/). The short
153version of how to patch is:
154
155 Register at https://gn-review.googlesource.com.
156
157 ... edit code ...
158 ninja -C out && out/gn_unittests
159
160Then, to upload a change for review:
161
162 git commit
163 git push origin HEAD:refs/for/main
164
165The first time you do this you'll get an error from the server about a missing
166change-ID. Follow the directions in the error message to install the change-ID
167hook and run `git commit --amend` to apply the hook to the current commit.
168
169When revising a change, use:
170
171 git commit --amend
172 git push origin HEAD:refs/for/main
173
174which will add the new changes to the existing code review, rather than creating
175a new one.
176
177We ask that all contributors
178[sign Google's Contributor License Agreement](https://cla.developers.google.com/)
179(either individual or corporate as appropriate, select 'any other Google
180project').
181
182## Community
183
184You may ask questions and follow along with GN's development on Chromium's
185[gn-dev@](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev)
186Google Group.
187
188## Versioning and distribution
189
190Most open-source projects are designed to use the developer's computer's current
191toolchain such as compiler, linker, and build tool. But the large
192centrally controlled projects that GN is designed for typically want a more
193hermetic environment. They will ensure that developers are using a specific
194compatible toolchain that is versioned with the code.
195
196As a result, GN expects that the project choose the appropriate version of GN
197that will work with each version of the project. There is no "current stable
198version" of GN that is expected to work for all projects.
199
200As a result, the GN developers do not maintain any packages in any of the
201various packaging systems (Debian, RedHat, HomeBrew, etc.). Some of these
202systems to have GN packages, but they are maintained by third parties and you
203should use them at your own risk. Instead, we recommend you refer your checkout
204tooling to download binaries for a specific hash from [Google's build
205infrastructure](https://chrome-infra-packages.appspot.com/p/gn/gn) or compile
206your own.
207
208GN does not guarantee the backwards-compatibility of new versions and has no
209branches or versioning scheme beyond the sequence of commits to the main git
210branch (which is expected to be stable).
211
212In practice, however, GN is very backwards-compatible. The core functionality
213has been stable for many years and there is enough GN code at Google alone to
214make non-backwards-compatible changes very difficult, even if they were
215desirable.
216
217There have been discussions about adding a versioning scheme with some
218guarantees about backwards-compatibility, but nothing has yet been implemented.
219