Migrate GN docs from the wiki to the repo.
Given that Google Code is shutting down, we need to figure out what to do with docs in the wiki. Gitiles (the tree browser for our Git repo) supports rendering markdown files that are checked in to the repo, so one obvious answer is to migrate the GN docs into the repo (and convert them to markdown); this would also make it easier to keep the docs versioned and in sync with the code.
This is a first pass at that. The content is unchanged from the wiki, just converted and manually reformatted to stay within 80 columns where possible (we can't do that for long URLs or wide tables).
[email protected], [email protected]
BUG=468851
Review URL: https://codereview.chromium.org/1052883002
Cr-Commit-Position: refs/heads/master@{#323923}
diff --git a/tools/gn/docs/quick_start.md b/tools/gn/docs/quick_start.md
new file mode 100644
index 0000000..49f16ae0
--- /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.
