Petr Hosek | 567ac71 | 2018-05-30 15:55:16 -0700 | [diff] [blame] | 1 | # GN |
| 2 | |
Scott Graham | ab123de | 2018-06-08 15:53:07 -0700 | [diff] [blame] | 3 | GN is a meta-build system that generates build files for |
Brett Wilson | fc2f07a | 2019-09-03 12:06:18 -0700 | [diff] [blame] | 4 | [Ninja](https://ninja-build.org). |
| 5 | |
| 6 | Related resources: |
| 7 | |
Shezan Baig | e0c476f | 2021-06-08 05:08:15 -0400 | [diff] [blame] | 8 | * Documentation in [docs/](https://gn.googlesource.com/gn/+/main/docs/). In |
Brett Wilson | f847b57 | 2021-10-29 12:58:28 -0700 | [diff] [blame] | 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). |
Brett Wilson | fc2f07a | 2019-09-03 12:06:18 -0700 | [diff] [blame] | 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). |
Brett Wilson | f847b57 | 2021-10-29 12:58:28 -0700 | [diff] [blame] | 16 | * The [bug database](https://bugs.chromium.org/p/gn/issues/list). |
Scott Graham | ab123de | 2018-06-08 15:53:07 -0700 | [diff] [blame] | 17 | |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 18 | ## What GN is for |
| 19 | |
| 20 | GN is currently used as the build system for Chromium, Fuchsia, and related |
| 21 | projects. 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 | |
| 45 | Although small projects successfully use GN, the focus on large projects has |
| 46 | some 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 Wilson | 03ce92d | 2022-07-04 13:31:55 -0700 | [diff] [blame] | 54 | files required and the exact way all compilers and linkers are run must be |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 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 | |
Brett Wilson | d7cf623 | 2021-02-02 17:09:07 -0800 | [diff] [blame] | 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 |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 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. |
Brett Wilson | 8926696 | 2021-10-29 14:00:30 -0700 | [diff] [blame] | 74 | Since GN is relatively uncommon, it can be more difficult to find |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 75 | information and examples. |
| 76 | |
| 77 | GN can generate Ninja build files for C, C++, Rust, Objective C, and Swift |
| 78 | source on most popular platforms. Other languages can be compiled using the |
Brett Wilson | d7cf623 | 2021-02-02 17:09:07 -0800 | [diff] [blame] | 79 | general "action" rules which are executed by Python or another scripting |
| 80 | language (Google does this to compile Java and Go). But because this is not as |
| 81 | clean, generally GN is only used when the bulk of the build is in one of the |
| 82 | main built-in languages. |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 83 | |
Brett Wilson | 4c0c60e | 2019-07-08 15:18:40 -0700 | [diff] [blame] | 84 | ## Getting a binary |
Scott Graham | ab123de | 2018-06-08 15:53:07 -0700 | [diff] [blame] | 85 | |
Petr Hosek | 1beb050 | 2018-10-24 18:58:39 -0700 | [diff] [blame] | 86 | You 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 Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 89 | [Windows](https://chrome-infra-packages.appspot.com/dl/gn/gn/windows-amd64/+/latest) |
| 90 | from Google's build infrastructure (see "Versioning and distribution" below for |
| 91 | how this is expected to work). |
Petr Hosek | 1beb050 | 2018-10-24 18:58:39 -0700 | [diff] [blame] | 92 | |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 93 | Alternatively, you can build GN from source with a C++17 compiler: |
Petr Hosek | 1beb050 | 2018-10-24 18:58:39 -0700 | [diff] [blame] | 94 | |
Scott Graham | 4a2a068 | 2018-06-11 09:28:19 -0700 | [diff] [blame] | 95 | git clone https://gn.googlesource.com/gn |
| 96 | cd gn |
Takuto Ikuta | 578a7fe | 2022-05-11 15:41:48 +0900 | [diff] [blame] | 97 | python build/gen.py # --allow-warning if you want to build with warnings. |
Scott Graham | 4a2a068 | 2018-06-11 09:28:19 -0700 | [diff] [blame] | 98 | ninja -C out |
Andrew Grieve | 77d64a3 | 2018-09-06 23:19:01 -0400 | [diff] [blame] | 99 | # To run tests: |
| 100 | out/gn_unittests |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 101 | |
| 102 | On Windows, it is expected that `cl.exe`, `link.exe`, and `lib.exe` can be found |
| 103 | in `PATH`, so you'll want to run from a Visual Studio command prompt, or |
| 104 | similar. |
| 105 | |
Gaby Baghdadi | 45aa842 | 2021-05-12 12:37:08 -0400 | [diff] [blame] | 106 | On Linux, Mac and z/OS, the default compiler is `clang++`, a recent version is |
Brett Wilson | 03ce92d | 2022-07-04 13:31:55 -0700 | [diff] [blame] | 107 | expected to be found in `PATH`. This can be overridden by setting the `CC`, `CXX`, |
| 108 | and `AR` environment variables. |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 109 | |
anlex N | 70844c8 | 2024-04-24 18:49:31 +0800 | [diff] [blame] | 110 | On MSYS and MinGW, the default compiler is `g++`, a recent version is |
| 111 | expected to be found in `PATH`. This can be overridden by setting the `CC`, `CXX`, |
| 112 | `LD` and `AR` environment variables. |
| 113 | |
Gaby Baghdadi | 45aa842 | 2021-05-12 12:37:08 -0400 | [diff] [blame] | 114 | On z/OS, building GN requires [ZOSLIB](https://github.com/ibmruntimes/zoslib) to be |
| 115 | installed, 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 | |
| 121 | By default, if you don't specify `--zoslib-dir`, `gn/build/gen.py` expects to find |
| 122 | `zoslib` directory under `gn/third_party/`. |
| 123 | |
Brett Wilson | 4c0c60e | 2019-07-08 15:18:40 -0700 | [diff] [blame] | 124 | ## Examples |
| 125 | |
| 126 | There is a simple example in [examples/simple_build](examples/simple_build) |
| 127 | directory that is a good place to get started with the minimal configuration. |
| 128 | |
Wayne Piekarski | b0e6146 | 2019-11-08 15:55:17 -0800 | [diff] [blame] | 129 | To 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 Wilson | 4c0c60e | 2019-07-08 15:18:40 -0700 | [diff] [blame] | 136 | For 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 | |
| 142 | and the Fuchsia setup: |
Shezan Baig | e0c476f | 2021-06-08 05:08:15 -0400 | [diff] [blame] | 143 | * [.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 Wilson | 4c0c60e | 2019-07-08 15:18:40 -0700 | [diff] [blame] | 147 | |
Daniel Bratell | f73698e | 2018-10-19 16:00:05 +0200 | [diff] [blame] | 148 | ## Reporting bugs |
| 149 | |
| 150 | If you find a bug, you can see if it is known or report it in the [bug |
| 151 | database](https://bugs.chromium.org/p/gn/issues/list). |
| 152 | |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 153 | ## Sending patches |
| 154 | |
Brett Wilson | 8926696 | 2021-10-29 14:00:30 -0700 | [diff] [blame] | 155 | GN uses [Gerrit](https://www.gerritcodereview.com/) for code review hosted at |
| 156 | [gn-review.googlesource.com](https://gn-review.googlesource.com/). The short |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 157 | version of how to patch is: |
| 158 | |
Erik Chen | c4b8655 | 2018-08-22 16:30:36 -0700 | [diff] [blame] | 159 | Register at https://gn-review.googlesource.com. |
| 160 | |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 161 | ... edit code ... |
| 162 | ninja -C out && out/gn_unittests |
| 163 | |
| 164 | Then, to upload a change for review: |
| 165 | |
| 166 | git commit |
Shezan Baig | e0c476f | 2021-06-08 05:08:15 -0400 | [diff] [blame] | 167 | git push origin HEAD:refs/for/main |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 168 | |
Brett Wilson | e67b81b | 2020-01-03 07:56:19 -0800 | [diff] [blame] | 169 | The first time you do this you'll get an error from the server about a missing |
| 170 | change-ID. Follow the directions in the error message to install the change-ID |
| 171 | hook and run `git commit --amend` to apply the hook to the current commit. |
| 172 | |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 173 | When revising a change, use: |
| 174 | |
| 175 | git commit --amend |
Shezan Baig | e0c476f | 2021-06-08 05:08:15 -0400 | [diff] [blame] | 176 | git push origin HEAD:refs/for/main |
Scott Graham | 0c5d936 | 2018-06-26 21:12:17 -0700 | [diff] [blame] | 177 | |
| 178 | which will add the new changes to the existing code review, rather than creating |
| 179 | a new one. |
| 180 | |
Dirk Pranke | cad6b53 | 2018-07-23 14:02:13 -0700 | [diff] [blame] | 181 | We 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 |
| 184 | project'). |
| 185 | |
| 186 | ## Community |
| 187 | |
Brett Wilson | 4c0c60e | 2019-07-08 15:18:40 -0700 | [diff] [blame] | 188 | You may ask questions and follow along with GN's development on Chromium's |
Dirk Pranke | cad6b53 | 2018-07-23 14:02:13 -0700 | [diff] [blame] | 189 | [gn-dev@](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev) |
| 190 | Google Group. |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 191 | |
| 192 | ## Versioning and distribution |
| 193 | |
Brett Wilson | d7cf623 | 2021-02-02 17:09:07 -0800 | [diff] [blame] | 194 | Most open-source projects are designed to use the developer's computer's current |
| 195 | toolchain such as compiler, linker, and build tool. But the large |
| 196 | centrally controlled projects that GN is designed for typically want a more |
| 197 | hermetic environment. They will ensure that developers are using a specific |
Ted Pudlik | 07e2e1b | 2021-09-10 13:18:14 -0700 | [diff] [blame] | 198 | compatible toolchain that is versioned with the code. |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 199 | |
| 200 | As a result, GN expects that the project choose the appropriate version of GN |
| 201 | that will work with each version of the project. There is no "current stable |
| 202 | version" of GN that is expected to work for all projects. |
| 203 | |
Ted Pudlik | 07e2e1b | 2021-09-10 13:18:14 -0700 | [diff] [blame] | 204 | As a result, the GN developers do not maintain any packages in any of the |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 205 | various packaging systems (Debian, RedHat, HomeBrew, etc.). Some of these |
| 206 | systems to have GN packages, but they are maintained by third parties and you |
Ted Pudlik | 07e2e1b | 2021-09-10 13:18:14 -0700 | [diff] [blame] | 207 | should use them at your own risk. Instead, we recommend you refer your checkout |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 208 | tooling to download binaries for a specific hash from [Google's build |
| 209 | infrastructure](https://chrome-infra-packages.appspot.com/p/gn/gn) or compile |
| 210 | your own. |
| 211 | |
| 212 | GN does not guarantee the backwards-compatibility of new versions and has no |
Shezan Baig | e0c476f | 2021-06-08 05:08:15 -0400 | [diff] [blame] | 213 | branches or versioning scheme beyond the sequence of commits to the main git |
Brett Wilson | 5f30bbf | 2021-01-25 16:07:26 -0800 | [diff] [blame] | 214 | branch (which is expected to be stable). |
| 215 | |
| 216 | In practice, however, GN is very backwards-compatible. The core functionality |
| 217 | has been stable for many years and there is enough GN code at Google alone to |
| 218 | make non-backwards-compatible changes very difficult, even if they were |
| 219 | desirable. |
| 220 | |
| 221 | There have been discussions about adding a versioning scheme with some |
| 222 | guarantees about backwards-compatibility, but nothing has yet been implemented. |