BASELINE: Update GN

Change-Id: I70780976cc316da912f784e722f3505b2050c3a6
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

1 files changed, 120 insertions, 5 deletions

diff --git a/gn/README.md b/gn/README.md
index a8d9fa3724f..d6c91184c78 100644
--- a/gn/README.md
+++ b/gn/README.md
@@ -5,18 +5,90 @@ GN is a meta-build system that generates build files for
 
 Related resources:
 
-  * Documentation in [docs/](https://gn.googlesource.com/gn/+/master/docs/).
+  * Documentation in [docs/](https://gn.googlesource.com/gn/+/master/docs/). In
+    particular [GN Quick Start
+    guide](https://gn.googlesource.com/gn/+/master/docs/quick_start.md)
+    and the [reference](https://gn.googlesource.com/gn/+/master/docs/reference.md)
+    (the latter is all builtin help converted to a single file).
   * An introductory [presentation](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit?usp=sharing).
   * The [mailing list](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev).
 
+## What GN is for
+
+GN is currently used as the build system for Chromium, Fuchsia, and related
+projects. Some strengths of GN are:
+
+  * It is designed for large projects and large teams. It scales efficiently to
+    many thousands of build files and tens of thousands of source files.
+
+  * It has a readable, clean syntax. Once a build is set-up, it is generally
+    easy for people with no backround in GN to make basic edits to the build.
+
+  * It is designed for multi-platform projects. It can cleanly express many
+    complicated build variants across different platforms. A single build
+    invocation can target multiple platforms.
+
+  * It supports multiple parallel output directories, each with their own
+    configuration. This allows a developer to maintain builds targeting debug,
+    release, or different platforms in parallel without forced rebuilds when
+    switching.
+
+  * It has a focus on correctness. GN checks for the correct dependencies,
+    inputs, and outputs to the extent possible, and has a number of tools to
+    allow developers to ensure the build evolves as desired (for example, `gn
+    check`, `testonly`, `assert_no_deps`).
+
+  * It has comprehensive build-in help available from the command-line.
+
+Although small projects successfully use GN, the focus on large projects has
+some disadvanages:
+
+  * GN has the goal of being minimally expressive. Although it can be quite
+    flexible, a design goal is to direct members of a large team (who may not
+    have much knowledge about the build) down an easy-to-understand, well-lit
+    path. This isn't necessarily the correct trade-off for smaller projects.
+
+  * The minimal build configuration is relatively heavyweight. There are several
+    files required and the exact way all compilers are linkers are run must be
+    specified in the configuration (see "Examples" below). There is no default
+    compiler configuration.
+
+  * It is not easily composable. GN is designed to compile a single large
+    project with relatively uniform settings and rules. Projects like Chromium
+    do bring together multiple repositories from multiple teams, but the
+    projects must agree on some conventions in the build files to allow this to
+    work.
+
+  * GN is designed with the expectation that the developers building a project
+    want to compile an identical configuration. So while builds can integrate
+    with the user's environment like the CXX and CFLAGS variables if they want,
+    this is not the default and most project's builds do not do this. The result
+    is that many GN projects do not integrate well with other systems like
+    ebuild.
+
+  * There is no simple release scheme (see "Versioning and distribution" below).
+    Projects are expected to manage the version of GN they require. Getting an
+    appropriate GN binary can be a hurdle for new contributors to a project.
+    Since it is relatively uncommon, it can be more difficult to find
+    information and examples.
+
+GN can generate Ninja build files for C, C++, Rust, Objective C, and Swift
+source on most popular platforms. Other languages can be compiled using the
+general "action" rules which are executed by Python or another scripting
+language (Google does this to compile Java and Go). But because this is not as
+clean, generally GN is only used when the bulk of the build is in one of the
+main built-in languages.
+
 ## Getting a binary
 
 You can download the latest version of GN binary for
 [Linux](https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest),
 [macOS](https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest) and
-[Windows](https://chrome-infra-packages.appspot.com/dl/gn/gn/windows-amd64/+/latest).
+[Windows](https://chrome-infra-packages.appspot.com/dl/gn/gn/windows-amd64/+/latest)
+from Google's build infrastructure (see "Versioning and distribution" below for
+how this is expected to work).
 
-Alternatively, you can build GN from source:
+Alternatively, you can build GN from source with a C++17 compiler:
 
     git clone https://gn.googlesource.com/gn
     cd gn
@@ -38,6 +110,13 @@ and `AR`.
 There is a simple example in [examples/simple_build](examples/simple_build)
 directory that is a good place to get started with the minimal configuration.
 
+To build and run the simple example with the default gcc compiler:
+
+    cd examples/simple_build
+    ../../out/gn gen -C out
+    ninja -C out
+    ./out/hello
+
 For a maximal configuration see the Chromium setup:
   * [.gn](https://cs.chromium.org/chromium/src/.gn)
   * [BUILDCONFIG.gn](https://cs.chromium.org/chromium/src/build/config/BUILDCONFIG.gn)
@@ -68,12 +147,16 @@ version of how to patch is:
 Then, to upload a change for review:
 
     git commit
-    git cl upload --gerrit
+    git push origin HEAD:refs/for/master
+
+The first time you do this you'll get an error from the server about a missing
+change-ID. Follow the directions in the error message to install the change-ID
+hook and run `git commit --amend` to apply the hook to the current commit.
 
 When revising a change, use:
 
     git commit --amend
-    git cl upload --gerrit
+    git push origin HEAD:refs/for/master
 
 which will add the new changes to the existing code review, rather than creating
 a new one.
@@ -88,3 +171,35 @@ project').
 You may ask questions and follow along with GN's development on Chromium's
 [gn-dev@](https://groups.google.com/a/chromium.org/forum/#!forum/gn-dev)
 Google Group.
+
+## Versioning and distribution
+
+Most open-source projects are designed to use the developer's computer's current
+toolchain such as compiler, linker, and build tool. But the large
+centrally controlled projects that GN is designed for typically want a more
+hermetic environment. They will ensure that developers are using a specific
+compatible toolchain that is versioned with the code
+
+As a result, GN expects that the project choose the appropriate version of GN
+that will work with each version of the project. There is no "current stable
+version" of GN that is expected to work for all projects.
+
+As a result, the GN developers to not maintain any packages in any of the
+various packaging systems (Debian, RedHat, HomeBrew, etc.). Some of these
+systems to have GN packages, but they are maintained by third parties and you
+should use at your own risk. Instead, we recommend you refer your checkout
+tooling to download binaries for a specific hash from [Google's build
+infrastructure](https://chrome-infra-packages.appspot.com/p/gn/gn) or compile
+your own.
+
+GN does not guarantee the backwards-compatibility of new versions and has no
+branches or versioning scheme beyond the sequence of commits to the master git
+branch (which is expected to be stable).
+
+In practice, however, GN is very backwards-compatible. The core functionality
+has been stable for many years and there is enough GN code at Google alone to
+make non-backwards-compatible changes very difficult, even if they were
+desirable.
+
+There have been discussions about adding a versioning scheme with some
+guarantees about backwards-compatibility, but nothing has yet been implemented.