blob: f96d895244bc85f4fdd76d642e6afe319104ff1d [file] [log] [blame] [view]
Petr Hosek567ac712018-05-30 15:55:16 -07001# GN
2
Scott Grahamab123de2018-06-08 15:53:07 -07003GN is a meta-build system that generates build files for
Brett Wilsonfc2f07a2019-09-03 12:06:18 -07004[Ninja](https://ninja-build.org).
5
6Related resources:
7
Shezan Baige0c476f2021-06-08 05:08:15 -04008 * Documentation in [docs/](https://gn.googlesource.com/gn/+/main/docs/). In
Brett Wilsonf847b572021-10-29 12:58:28 -07009 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).
Brett Wilsonfc2f07a2019-09-03 12:06:18 -070014 * 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).
Brett Wilsonf847b572021-10-29 12:58:28 -070016 * The [bug database](https://bugs.chromium.org/p/gn/issues/list).
Scott Grahamab123de2018-06-08 15:53:07 -070017
Brett Wilson5f30bbf2021-01-25 16:07:26 -080018## 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
Brett Wilson03ce92d2022-07-04 13:31:55 -070054 files required and the exact way all compilers and linkers are run must be
Brett Wilson5f30bbf2021-01-25 16:07:26 -080055 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
Brett Wilsond7cf6232021-02-02 17:09:07 -080064 * GN is designed with the expectation that the developers building a project
65 want to compile an identical configuration. So while builds can integrate
Brett Wilson5f30bbf2021-01-25 16:07:26 -080066 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.
Brett Wilson89266962021-10-29 14:00:30 -070074 Since GN is relatively uncommon, it can be more difficult to find
Brett Wilson5f30bbf2021-01-25 16:07:26 -080075 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
Brett Wilsond7cf6232021-02-02 17:09:07 -080079general "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.
Brett Wilson5f30bbf2021-01-25 16:07:26 -080083
Brett Wilson4c0c60e2019-07-08 15:18:40 -070084## Getting a binary
Scott Grahamab123de2018-06-08 15:53:07 -070085
Petr Hosek1beb0502018-10-24 18:58:39 -070086You 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
Brett Wilson5f30bbf2021-01-25 16:07:26 -080089[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).
Petr Hosek1beb0502018-10-24 18:58:39 -070092
Brett Wilson5f30bbf2021-01-25 16:07:26 -080093Alternatively, you can build GN from source with a C++17 compiler:
Petr Hosek1beb0502018-10-24 18:58:39 -070094
Scott Graham4a2a0682018-06-11 09:28:19 -070095 git clone https://gn.googlesource.com/gn
96 cd gn
Takuto Ikuta578a7fe2022-05-11 15:41:48 +090097 python build/gen.py # --allow-warning if you want to build with warnings.
Scott Graham4a2a0682018-06-11 09:28:19 -070098 ninja -C out
Andrew Grieve77d64a32018-09-06 23:19:01 -040099 # To run tests:
100 out/gn_unittests
Scott Graham0c5d9362018-06-26 21:12:17 -0700101
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
Gaby Baghdadi45aa8422021-05-12 12:37:08 -0400106On Linux, Mac and z/OS, the default compiler is `clang++`, a recent version is
Brett Wilson03ce92d2022-07-04 13:31:55 -0700107expected to be found in `PATH`. This can be overridden by setting the `CC`, `CXX`,
108and `AR` environment variables.
Scott Graham0c5d9362018-06-26 21:12:17 -0700109
anlex N70844c82024-04-24 18:49:31 +0800110On MSYS and MinGW, the default compiler is `g++`, a recent version is
111expected to be found in `PATH`. This can be overridden by setting the `CC`, `CXX`,
112`LD` and `AR` environment variables.
113
Gaby Baghdadi45aa8422021-05-12 12:37:08 -0400114On z/OS, building GN requires [ZOSLIB](https://github.com/ibmruntimes/zoslib) to be
115installed, as described at that URL. When building with `build/gen.py`, use the option
116`--zoslib-dir` to specify the path to [ZOSLIB](https://github.com/ibmruntimes/zoslib):
117
118 cd gn
119 python build/gen.py --zoslib-dir /path/to/zoslib
120
121By default, if you don't specify `--zoslib-dir`, `gn/build/gen.py` expects to find
122`zoslib` directory under `gn/third_party/`.
123
Brett Wilson4c0c60e2019-07-08 15:18:40 -0700124## Examples
125
126There is a simple example in [examples/simple_build](examples/simple_build)
127directory that is a good place to get started with the minimal configuration.
128
Wayne Piekarskib0e61462019-11-08 15:55:17 -0800129To build and run the simple example with the default gcc compiler:
130
131 cd examples/simple_build
132 ../../out/gn gen -C out
133 ninja -C out
134 ./out/hello
135
Brett Wilson4c0c60e2019-07-08 15:18:40 -0700136For a maximal configuration see the Chromium setup:
137 * [.gn](https://cs.chromium.org/chromium/src/.gn)
138 * [BUILDCONFIG.gn](https://cs.chromium.org/chromium/src/build/config/BUILDCONFIG.gn)
139 * [Toolchain setup](https://cs.chromium.org/chromium/src/build/toolchain/)
140 * [Compiler setup](https://cs.chromium.org/chromium/src/build/config/compiler/BUILD.gn)
141
142and the Fuchsia setup:
Shezan Baige0c476f2021-06-08 05:08:15 -0400143 * [.gn](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/.gn)
144 * [BUILDCONFIG.gn](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/config/BUILDCONFIG.gn)
145 * [Toolchain setup](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/toolchain/)
146 * [Compiler setup](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/build/config/BUILD.gn)
Brett Wilson4c0c60e2019-07-08 15:18:40 -0700147
Daniel Bratellf73698e2018-10-19 16:00:05 +0200148## Reporting bugs
149
150If you find a bug, you can see if it is known or report it in the [bug
151database](https://bugs.chromium.org/p/gn/issues/list).
152
Scott Graham0c5d9362018-06-26 21:12:17 -0700153## Sending patches
154
Brett Wilson89266962021-10-29 14:00:30 -0700155GN uses [Gerrit](https://www.gerritcodereview.com/) for code review hosted at
156[gn-review.googlesource.com](https://gn-review.googlesource.com/). The short
Scott Graham0c5d9362018-06-26 21:12:17 -0700157version of how to patch is:
158
Erik Chenc4b86552018-08-22 16:30:36 -0700159 Register at https://gn-review.googlesource.com.
160
Scott Graham0c5d9362018-06-26 21:12:17 -0700161 ... edit code ...
162 ninja -C out && out/gn_unittests
163
164Then, to upload a change for review:
165
166 git commit
Shezan Baige0c476f2021-06-08 05:08:15 -0400167 git push origin HEAD:refs/for/main
Scott Graham0c5d9362018-06-26 21:12:17 -0700168
Brett Wilsone67b81b2020-01-03 07:56:19 -0800169The first time you do this you'll get an error from the server about a missing
170change-ID. Follow the directions in the error message to install the change-ID
171hook and run `git commit --amend` to apply the hook to the current commit.
172
Scott Graham0c5d9362018-06-26 21:12:17 -0700173When revising a change, use:
174
175 git commit --amend
Shezan Baige0c476f2021-06-08 05:08:15 -0400176 git push origin HEAD:refs/for/main
Scott Graham0c5d9362018-06-26 21:12:17 -0700177
178which will add the new changes to the existing code review, rather than creating
179a new one.
180
Dirk Prankecad6b532018-07-23 14:02:13 -0700181We ask that all contributors
182[sign Google's Contributor License Agreement](https://cla.developers.google.com/)
183(either individual or corporate as appropriate, select 'any other Google
184project').
185
186## Community
187
Brett Wilson4c0c60e2019-07-08 15:18:40 -0700188You may ask questions and follow along with GN's development on Chromium's
Dirk Prankecad6b532018-07-23 14:02:13 -0700189[gn-dev@](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev)
190Google Group.
Brett Wilson5f30bbf2021-01-25 16:07:26 -0800191
192## Versioning and distribution
193
Brett Wilsond7cf6232021-02-02 17:09:07 -0800194Most open-source projects are designed to use the developer's computer's current
195toolchain such as compiler, linker, and build tool. But the large
196centrally controlled projects that GN is designed for typically want a more
197hermetic environment. They will ensure that developers are using a specific
Ted Pudlik07e2e1b2021-09-10 13:18:14 -0700198compatible toolchain that is versioned with the code.
Brett Wilson5f30bbf2021-01-25 16:07:26 -0800199
200As a result, GN expects that the project choose the appropriate version of GN
201that will work with each version of the project. There is no "current stable
202version" of GN that is expected to work for all projects.
203
Ted Pudlik07e2e1b2021-09-10 13:18:14 -0700204As a result, the GN developers do not maintain any packages in any of the
Brett Wilson5f30bbf2021-01-25 16:07:26 -0800205various packaging systems (Debian, RedHat, HomeBrew, etc.). Some of these
206systems to have GN packages, but they are maintained by third parties and you
Ted Pudlik07e2e1b2021-09-10 13:18:14 -0700207should use them at your own risk. Instead, we recommend you refer your checkout
Brett Wilson5f30bbf2021-01-25 16:07:26 -0800208tooling to download binaries for a specific hash from [Google's build
209infrastructure](https://chrome-infra-packages.appspot.com/p/gn/gn) or compile
210your own.
211
212GN does not guarantee the backwards-compatibility of new versions and has no
Shezan Baige0c476f2021-06-08 05:08:15 -0400213branches or versioning scheme beyond the sequence of commits to the main git
Brett Wilson5f30bbf2021-01-25 16:07:26 -0800214branch (which is expected to be stable).
215
216In practice, however, GN is very backwards-compatible. The core functionality
217has been stable for many years and there is enough GN code at Google alone to
218make non-backwards-compatible changes very difficult, even if they were
219desirable.
220
221There have been discussions about adding a versioning scheme with some
222guarantees about backwards-compatibility, but nothing has yet been implemented.