Merge branch 'master' into rename-to-electron

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)

docs/development/build-instructions-linux.md

@@ -9,7 +9,10 @@
 On Ubuntu you could install the libraries via:
 
 ```bash
-$ sudo apt-get install build-essential clang libdbus-1-dev libgtk2.0-dev libnotify-dev libgnome-keyring-dev libgconf2-dev gcc-multilib g++-multilib
+$ sudo apt-get install build-essential clang libdbus-1-dev libgtk2.0-dev \
+                       libnotify-dev libgnome-keyring-dev libgconf2-dev \
+                       libasound2-dev libcap-dev libcups2-dev libxtst-dev \
+                       gcc-multilib g++-multilib
 ```
 
 Latest Node.js could be installed via ppa:
@@ -52,10 +55,10 @@ $ ./script/build.py
 You can also only build the `Debug` target:
 
 ```bash
-$ ./script/build.py -c Debug
+$ ./script/build.py -c D
 ```
 
-After building is done, you can find `atom` under `out/Debug`.
+After building is done, you can find `atom` under `out/D`.
 
 ## Troubleshooting
 

docs/development/build-instructions-mac.md

@@ -39,10 +39,10 @@ $ ./script/build.py
 You can also only build the `Debug` target:
 
 ```bash
-$ ./script/build.py -c Debug
+$ ./script/build.py -c D
 ```
 
-After building is done, you can find `Atom.app` under `out/Debug`.
+After building is done, you can find `Atom.app` under `out/D`.
 
 ## 32bit support
 

docs/development/build-instructions-windows.md

@@ -49,10 +49,10 @@ python script\build.py
 You can also only build the Debug target:
 
 ```powershell
-python script\build.py -c Debug
+python script\build.py -c D
 ```
 
-After building is done, you can find `atom.exe` under `out\Debug`.
+After building is done, you can find `atom.exe` under `out\D`.
 
 ## 64bit support
 

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 quite a large project, the final linking stage would take
+quite a few minutes, making it hard for development. In order to solve this,
+Chromium introduced the "component build", which builds each component as a
+separate shared library, making linking very quick but sacrificing file size
+and performance.
+
+In Atom Shell we took a very similar approach: for `Debug` builds, the binary
+will be linked to shared library version of Chromium's components to achieve
+fast linking time; for `Release` builds, the binary will be linked to the static
+library versions, so we can have the best possible binary size and performance.
+
+## Minimal bootstrapping
+
+All of 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 should be between 800MB and 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/bootstrap.py --dev
+$ ./script/build.py -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.

docs/tutorial/using-native-node-modules.md

@@ -1,33 +1,8 @@
 # Using native Node modules
 
 The native Node modules are supported by atom-shell, but since atom-shell is
-using a different V8 version from official Node, you need to use `apm` instead
-of `npm` to install Node modules.
-
-The usage of [apm](https://github.com/atom/apm) is quite similar to `npm`, to
-install dependencies from `package.json` of current project, just do:
-
-```bash
-$ cd /path/to/atom-shell/project/
-$ apm install .
-```
-
-But you should notice that `apm install module` won't work because it will
-install a user package for [Atom Editor](https://github.com/atom/atom) instead.
-
-## Which version of apm to use
-
-Generally using the latest release of `apm` for latest atom-shell always works,
-but if you are uncertain of the which version of `apm` to use, you may manually
-instruct `apm` to use headers of a specified version of atom-shell by setting
-the `ATOM_NODE_VERSION` environment.
-
-For example force installing modules for atom-shell v0.16.0:
-
-```bash
-$ export ATOM_NODE_VERSION=0.16.0
-$ apm install .
-```
+using a different V8 version from official Node, you have to manually specify
+the location of atom-shell's headers when building native modules.
 
 ## Native Node module compatibility
 
@@ -41,10 +16,7 @@ To solve this, you should use modules that support Node v0.11.x,
 For old modules that only support Node v0.10.x, you should use the
 [nan](https://github.com/rvagg/nan) module to port it to v0.11.x.
 
-## Other ways of installing native modules
-
-Apart from `apm`, you can also use `node-gyp` and `npm` to manually build the
-native modules.
+## How to install native modules
 
 ### The node-gyp way
 
@@ -63,9 +35,12 @@ where to download the headers. The `--arch=ia32` says the module is built for
 
 ### The npm way
 
+You can also use `npm` to install modules, the steps are exactly the same with
+Node modules, except that you need to setup some environment variables:
+
 ```bash
 export npm_config_disturl=https://atom.io/download/atom-shell
-export npm_config_target=0.6.0
-export npm_config_arch=ia32
+export npm_config_target=0.23.0
+export npm_config_arch=x64
 HOME=~/.atom-shell-gyp npm install module-name
 ```