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