migrate GN docs from the wiki to the repo.

tools/gn/docs/quick_start.md

Index: tools/gn/docs/quick_start.md
diff --git a/tools/gn/docs/quick_start.md b/tools/gn/docs/quick_start.md
new file mode 100644
index 0000000000000000000000000000000000000000..49f16ae08be33b2a32e749ad653eb33590518e20
--- /dev/null
+++ b/tools/gn/docs/quick_start.md
@@ -0,0 +1,329 @@
+# GN Quick Start guide
+
+[TOC]
+
+## Running GN
+
+You just run `gn` from the command line. There is a script in
+depot\_tools (which is presumably on your path) with this name. The
+script will find the binary in the source tree containing the current
+directory and run it.
+
+## Setting up a build
+
+In GYP, the system would generate `Debug` and `Release` build
+directories for you and configure them accordingly. GN doesn't do this.
+Instead, you set up whatever build directory you want with whatever
+configuration you want. The Ninja files will be automatically
+regenerated if they're out of date when you build in that directory.
+
+To make a build directory:
+
+```
+gn gen out/my_build
+```
+
+## Passing build arguments
+
+Set build arguments on your build directory by running:
+
+```
+gn args out/my_build
+```
+
+This will bring up an editor. Type build args into that file like this:
+
+```
+is_component_build = true
+is_debug = false
+```
+
+You can see the list of available arguments and their default values by
+typing
+
+```
+gn args --list out/my_build
+```
+
+on the command line. See "Taking build arguments" below for information
+on how to use these in your code. (Note that you have to specify the
+build directory for this command because the available arguments can
+change according to what's set.
+
+## Configuring goma
+
+
+Run `gn args out/Default` (substituting your build directory as needed).
+Add:
+
+```
+use_goma = true
+goma_dir = "~/foo/bar/goma" 
+```
+
+If your goma is in the default location (`~/goma`) then you can omit the
+`goma_dir` line.
+
+## Configuring component mode
+
+This is a build arg like the goma flags. run `gn args out/Default` and add:
+
+```
+is_component_build = true
+```
+
+## Step-by-step
+
+### Adding a build file
+
+Create a `tools/gn/tutorial/BUILD.gn` file and enter the following:
+
+```
+executable("hello_world") {
+  sources = [
+    "hello_world.cc",
+  ]
+}
+```
+
+There should already be a `hello_world.cc` file in that directory,
+containing what you expect. That's it! Now we just need to tell the
+build about this file. Open the `BUILD.gn` file in the root directory
+and add the label of this target to the dependencies of the root group
+(a "group" target is a meta-target that is just a collection of other
+targets):
+
+```
+group("root") {
+  deps = [
+    ...
+    "//url",
+    "//tools/gn/tutorial:hello_world",
+  ]
+}
+```
+
+You can see the label of your target is "//" (indicating the source
+root), followed by the directory name, a colon, and the target name.
+
+### Testing your addition
+
+From the command line in the source root directory:
+
+```
+gn gen out/Default
+ninja -C out/Default hello_world
+out/Default/hello_world
+```
+
+GN encourages target names for static libraries that aren't globally
+unique. To build one of these, you can pass the label with no leading
+"//" to ninja:
+
+```
+ninja -C out/Default tools/gn/tutorial:hello_world
+```
+
+### Declaring dependencies
+
+Let's make a static library that has a function to say hello to random
+people. There is a source file `hello.cc` in that directory which has a
+function to do this. Open the `tools/gn/tutorial/BUILD.gn` file and add
+the static library to the bottom of the existing file:
+
+```
+static_library("hello") {
+  sources = [
+    "hello.cc",
+  ]
+}
+```
+
+Now let's add an executable that depends on this library:
+
+```
+executable("say_hello") {
+  sources = [
+    "say_hello.cc",
+  ]
+  deps = [
+    ":hello",
+  ]
+}
+```
+
+This executable includes one source file,and depends on the previous
+static library. The static library is referenced by its label in the
+`deps`. You could have used the full label `//tools/gn/tutorial:hello`
+but if you're referencing a target in the same build file, you can use
+the shortcut `:hello`.
+
+### Test the static library version
+
+From the command line in the source root directory:
+
+```
+ninja -C out/Default say_hello
+out/Default/say_hello
+```
+
+Note that you **didn't** need to re-run GN.GN will automatically rebuild
+the ninja files when any build file has changed. You know this happens
+when ninja prints `[1/1] Regenerating ninja files` at the beginning of
+execution.
+
+### Compiler settings
+
+Our hello library has a new feature, the ability to say hello to two
+people at once. This feature is controlled by defining `TWO_PEOPLE`. We
+can add defines like so:
+
+```
+static_library("hello") {
+  sources = [
+    "hello.cc",
+  ]
+  defines = [
+    "TWO_PEOPLE",
+  ]
+}
+```
+
+### Putting settings in a config
+
+However, users of the library also need to know about this define, and
+putting it in the static library target defines it only for the files
+there. If somebody else includes `hello.h`, they won't see the new
+definition. To see the new definition, everybody will have to define
+`TWO_PEOPLE`.
+
+GN has a concept called a "config" which encapsulates settings. Let's
+create one that defines our preprocessor define:
+
+```
+config("hello_config") {
+  defines = [
+    "TWO_PEOPLE",
+  ]
+}
+```
+
+To apply these settings to your target, you only need to add the
+config's label to the list of configs in the target:
+
+```
+static_library("hello") {
+  ...
+  configs += [
+    ":hello_config",
+  ]
+}
+```
+
+Note that you need "+=" here instead of "=" since the build
+configuration has a default set of configs applied to each target that
+set up the default build stuff. You want to add to this list rather than
+overwrite it. To see the default configs, you can use the `print`
+function in the build file or the `desc` command-line subcommand (see
+below for examples of both).
+
+### Dependent configs
+
+This nicely encapsulates our settings, but still requires everybody that
+uses our library to set the config on themselves. It would be nice if
+everybody that depends on our `hello` library can get this
+automatically. Change your library definition to:
+
+```
+static_library("hello") {
+  sources = [
+    "hello.cc",
+  ]
+  all_dependent_configs = [
+    ":hello_config"
+  ]
+}
+```
+
+This applies the `hello_config` to the `hello` target itself, plus all
+targets that depend on transitively depend on the current one. Now
+everybody that depends on us will get our settings. You can also set
+`direct_dependent_configs` which applies only to targets that directly
+depend on your target (not transitively).
+
+Now if you compile and run, you'll see the new version with two people:
+
+```
+> ninja -C out/Default say_hello
+ninja: Entering directory 'out/Default'
+[1/1] Regenerating ninja files
+[4/4] LINK say_hello
+> out/Default/say_hello
+Hello, Bill and Ted.
+```
+
+## Don't know what's going on?
+
+You can run GN in verbose mode to see lots of messages about what it's
+doing. Use `-v` for this.
+
+### Print debugging
+
+There is a `print` command which just writes to stdout:
+
+```
+static_library("hello") {
+  ...
+  print(configs)
+}
+```
+
+This will print all of the configs applying to your target (including
+the default ones).
+
+### The "desc" command
+
+You can run `gn desc <build_dir> <targetname>` to get information about
+a given target:
+
+```
+gn desc out/Default //tools/gn/tutorial:say_hello
+```
+
+will print out lots of exciting information. You can also print just one
+section. Lets say you wanted to know where your `TWO_PEOPLE` define
+came from on the `say_hello` target:
+
+```
+> gn desc out/Default //tools/gn/tutorial:say_hello defines --blame
+...lots of other stuff omitted...
+  From //tools/gn/tutorial:hello_config
+       (Added by //tools/gn/tutorial/BUILD.gn:12)
+    TWO_PEOPLE
+```
+
+You can see that `TWO_PEOPLE` was defined by a config, and you can also
+see the which like caused that config to be applied to your target (in
+this case, the `all_dependent_configs` line).
+
+Another particularly interesting variation:
+
+```
+gn desc out/Default //base:base_i18n deps --tree
+```
+
+See `gn help desc` for more.
+
+### Performance
+
+You can see what took a long time by running it with the --time command
+line flag. This will output a summary of timings for various things.
+
+You can also make a trace of how the build files were executed:
+
+```
+gn --tracelog=mylog.trace
+```
+
+and you can load the resulting file in Chrome's `about:tracing` page to
+look at everything.