docs: Add "Build system overview" chapter

diff --git a/docs/README.md b/docs/README.md
index e9ceda7..3468884 100644 (file)
--- a/docs/README.md
+++ b/docs/README.md
@@ -59,6 +59,7 @@ Modules for both processes:
 * [Coding style](development/coding-style.md)
 * [Source code directory structure](development/source-code-directory-structure.md)
 * [Technical differences to NW.js (formerly node-webkit)](development/atom-shell-vs-node-webkit.md)
+* [Build system overview](development/build-system-overview.md)
 * [Build instructions (Mac)](development/build-instructions-mac.md)
 * [Build instructions (Windows)](development/build-instructions-windows.md)
 * [Build instructions (Linux)](development/build-instructions-linux.md)

diff --git a/docs/development/build-system-overview.md b/docs/development/build-system-overview.md
new file mode 100644 (file)
index 0000000..b159500
--- /dev/null
+++ b/docs/development/build-system-overview.md
@@ -0,0 +1,64 @@
+# Build system overview
+
+Atom Shell uses `gyp` for project generation, and `ninja` for building, project
+configurations can be found in `.gyp` and `.gypi` files.
+
+## Gyp files
+
+Following `gyp` files contain the main rules of building Atom Shell:
+
+* `atom.gyp` defines how Atom Shell itself is built.
+* `common.gypi` adjusts the build configurations of Node to make it build
+  together with Chromium.
+* `vendor/brightray/brightray.gyp` defines how `brightray` is built, and
+  includes the default configurations of linking with Chromium.
+* `vendor/brightray/brightray.gypi` includes general build configurations about
+  building.
+
+## Component build
+
+Since Chromium is a quite large project, the final linking stage would take
+quite a few minutes, making it hard for development. In order to solve this,
+Chromium introduces the "component build", which builds each component as a
+separate shared library, so linking can be very quick, in sacrifice of file size
+and performance.
+
+In Atom Shell we took a very similar approach: for `Debug` build, the binary
+will be linked to shared library version of Chromium's components to achieve
+fast linking time; for `Release` build, the binary will be linked to the static
+library versions, so we can have best binary size and performance.
+
+## Minimal bootstrapping
+
+All the Chromium's prebuilt binaries are downloaded when running the bootstrap
+script, by default both static libraries and shared libraries will be
+downloaded, and the final size is between 800MB to 2GB according to the
+platform.
+
+If you only want to build Atom Shell quickly for testing or development, you
+can only download the shared library versions by passing the `--dev` parameter:
+
+```bash
+$ ./script/boostrap.by --dev
+$ ./script/build.by -c D
+```
+
+## Two-phrase project generation
+
+Atom Shell links with different sets of libraries in `Release` and `Debug`
+builds, however `gyp` doesn't support configuring different link settings for
+different configurations.
+
+To work around this Atom Shell uses a `gyp` variable
+`libchromiumcontent_component` to control which link settings to use, and only
+generates one target when running `gyp`.
+
+## Target names
+
+Unlike most projects that use `Release` and `Debug` as target names, Atom Shell
+uses `R` and `D` instead. This is because `gyp` randomly crashes if there is
+only one `Release` or `Debug` build configuration is defined, and Atom Shell has
+to only generate one target for one time as stated above.
+
+This only affects developers, if you are only building Atom Shell for rebranding
+you are not affected.

diff --git a/vendor/brightray b/vendor/brightray
index 14b4dc7..9b4018b 160000 (submodule)
--- a/vendor/brightray
+++ b/vendor/brightray
@@ -1 +1 @@
-Subproject commit 14b4dc7151ded676d7133f0da17033149a4954df
+Subproject commit 9b4018b24a1812fb2a073ff297f103f0df319db1