Add more README documentation.

Adds benefits and disadvantages and talk about versioning.

Change-Id: I1cbf3ab7112f1183f7670a451e63a77e15d860bf
Reviewed-by: Nico Weber <>
Commit-Queue: Brett Wilson <>
diff --git a/ b/
index 805760c..6fa5edd 100644
--- a/
+++ b/
@@ -13,14 +13,81 @@
   * An introductory [presentation](
   * The [mailing list](!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 build 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 (Google does this for 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
 [macOS]( and
+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
     cd gn
@@ -103,3 +170,35 @@
 You may ask questions and follow along with GN's development on Chromium's
 Google Group.
+## Versioning and distribution
+Most projects are designed to use the developer's computer's current toolchain
+such as compiler, linker, and build tool. But the large 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
+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]( 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
+There have been discussions about adding a versioning scheme with some
+guarantees about backwards-compatibility, but nothing has yet been implemented.