README.md

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