Add more README documentation. Adds benefits and disadvantages and talk about versioning. Change-Id: I1cbf3ab7112f1183f7670a451e63a77e15d860bf Reviewed-on: https://gn-review.googlesource.com/c/gn/+/11060 Reviewed-by: Nico Weber <thakis@chromium.org> Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/README.md b/README.md index 805760c..6fa5edd 100644 --- a/README.md +++ b/README.md
@@ -13,14 +13,81 @@ * 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 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 [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 @@ -103,3 +170,35 @@ 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 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 +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.