Update GN documentation.
This CL updates the main GN page to reflect that the migration is
basically done, and also adds documentation for the magic
top-level "//:default" target (which we don't actually use in Chromium).
R=brettw@chromium.org, kjellander@chromium.org
Review-Url: https://codereview.chromium.org/2407523002
Cr-Original-Commit-Position: refs/heads/master@{#423973}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: e5e5a9dd1ca6b2d16db5ca08031ccade0654504f
diff --git a/tools/gn/README.md b/tools/gn/README.md
index 9d92d9c..ad731a6 100644
--- a/tools/gn/README.md
+++ b/tools/gn/README.md
@@ -2,13 +2,11 @@
GN is a meta-build system that generates
[NinjaBuild](https://chromium.googlesource.com/chromium/src/+/master/docs/ninja_build.md)
-files. It's meant to be faster and simpler than GYP. It outputs only Ninja build
-files.
+files so that you can build Chromium with Ninja.
-## Why bother with GN?
+## Why did you switch from GYP?
-1. We believe GN files are more readable and more maintainable
- than GYP files.
+1. We believe GN files are more readable and more maintainable than GYP files.
2. GN is fast:
* GN is 20x faster than GYP.
* GN supports automatically re-running itself as needed by Ninja
@@ -20,54 +18,19 @@
4. GN gives us tools for querying the build graph; you can ask
"what does X depend on" and "who depends on Y", for example.
-## What's the status?
+## What's the status of the GYP->GN migration?
-_as of March 2016:_
+_As of Oct 2016:_
- * Linux and Android: Complete but not quite all bots have been flipped.
- Developers should be using GN on these platforms for most work.
- * Windows and ChromeOS: Should be usable for almost all development. Some
- bots need to be flipped. cros_sdk builds don't work on ChromeOS yet.
- * Mac and iOS: Work is in progress, generally not usable for normal
- development.
-
-## When are you going to be done?
-
-_as of March 2016:_
-
-We expect most work to be finishing up between now and the end of Q2.
-
-## What does "done" mean?
-
-Ideally we're done when all of the GYP files have been deleted from
-Chromium and no one misses them.
-
-We will be "mostly" done when the following are true:
-
- * All of the bots maintained by the Chrome infra team for Chromium and
- downstream of Chromium have been switched to GN. (Upstream projects
- like Skia and V8 can choose to stay on GYP if they like).
- * Any developer configurations we care about that don't have bots also
- work (Generally speaking, we're aiming to not have any of these.
- * Configurations we care about should have bots to ensure they don't
- break). We have verified that all of the tests pass. We have
- verified that the command lines match in the above configurations as
- much as possible, and we accept any differences. We have reviewed
- any binary differences that result in the official builds and
- accepted them. The GN files are the "source of truth" for the
- build, and normal chromium developers normally do not need to touch
- GYP files to keep things working. We have replacements for the
- hybrid "msvs-ninja" and "xcode-ninja" configurations that GYP can
- currently build.
-
-The difference between "mostly done" and "done" exists to cover any
-issues we haven't yet identified :)
-
-## How can I help?
-
-We could especially use infrastructure/bot, Mac, and iOS help.
-
-Or, look at [the list of open bugs](https://code.google.com/p/chromium/issues/list?can=2&q=label:Proj-GN-Migration%20-type:Project&sort=pri&colspec=ID%20Pri%20Summary%20Type%20OS%20Owner%20Status%20Modified%20Blocking) related to the migration and see if there's anything that catches your fancy.
+ * All of the Chromium builds have been switched over.
+ * Nearly all of the GYP files have been deleted from the Chromium repos.
+ * You can no longer build with GYP as a result.
+ * There are still some GYP files in place for the "Closure Compilation"
+ builders that need to be converted over.
+ * Some related projects (e.g., V8, Skia) may still support GYP for their
+ own reasons.
+ * We're still cleaning up some odds and ends like making gclient not
+ still use GYP_DEFINES.
## I want more info on GN!
diff --git a/tools/gn/docs/faq.md b/tools/gn/docs/faq.md
index 5a4bb07..55d8aef 100644
--- a/tools/gn/docs/faq.md
+++ b/tools/gn/docs/faq.md
@@ -2,89 +2,22 @@
[TOC]
-## How will the build be converted?
-
-We intend to build a second independent build in parallel to the GYP
-build. Previous efforts to generate GYP as an intermediate stage proved
-difficult. There will be some smaller set of bots compiling this build,
-and we'll keep the GN build running on these configurations.
-
-## What is unsupported in GN?
-
-The main features not supported in GN yet are:
- * Mac/iOS bundles
-
## Where is the GN documentation?
-Rather than on a separate wiki, it is versioned with the tool. Run `gn
-help`. See also the [quick start](quick_start.md) guide and the
-[language and operation details](language.md).
+GN has extensive built-in help, so you can run `gn help`, but you can
+also see all of the help on [the reference page](reference.md). See
+also the [quick start](quick_start.md) guide and the [language and
+operation details](language.md).
-## What is likely to break?
+## Can I generate XCode or Visual Studio projects?
-Since common.gypi is not used for GN-generated GYP files, any rules
-there will no longer apply. There is a _lot_ of logic in there for many
-build configurations and various conditions where certain flags should
-or should not be used. Some of these build configurations aren't even
-supported any more. Some are run on other waterfalls or are used by
-individuals manually setting GYP\_DEFINES on their local system.
+You can generate skeleton (or wrapper) projects for Xcode, Visual Studio,
+QTCreator, and Eclipse that will list the files and targets in the
+build, but use Ninja to do the actual build. You cannot generate "real"
+projects that look like native ones like GYP could.
-## Will XCode/Visual Studio still be supported?
-
-Visual Studio is supported. Visual Studio can be used as an IDE for code
-browsing or debugging but Ninja is used for building.
Run `gn help gen` for more details.
-XCode is not supported yet. We need help!
-
-## I'm weird. Will my uncommon build mode be supported?
-
-One of the main benefits of the build changeover is that it will
-encourage us to refactor the build system. The project has generally not
-been as strict with build complexity and maintenance as we have with
-source code, and a lot of cruft has accumulated.
-
-In most cases, we will want to rethink how build flags are supported. We
-want to be more modular rather than throwing everything in the
-common.gypi equivalent. The bar for additions at this level will be very
-high, and we will need to figure out how to design certain build
-features. If you are interested in some weird configurations, this will
-likely make your life more difficult in the short term, but will
-hopefully bring long-term benefits for everybody.
-
-In some cases, we may decide that the overhead of supporting your build
-for BeOS running on a DEC Alpha is not in the interests of the project.
-There will likely be discussions about where to draw the line, and how
-to allow those who want to do weird things to do them cleanly without
-negatively affecting the rest of the Chromium community.
-
-## I'm only a little bit weird, will my development build flag be supported?
-
-Only if you do it yourself!
-
-Some features have build flags that turn on a debugging mode or switch
-between internal/external builds. This can be supported, but as with
-GYP, your team will have to add an maintain the support.
-
-## I use supplement.gypi, what's the GN equivalent?
-
-Some projects use files called `supplement.gypi` to set build flags. GYP
-looks in each directory under `src` and adds merges these files into the
-build. The model is that then adding something to your gclient to add
-something to your build (e.g `src-internal`) automatically sets flags.
-
-This behavior is fragile and mysterious. Some people get build flags and
-they don't know why. If you remove the entry from your `.gclient` and
-don't remove the directory you'll be stuck on an old version of the
-flags/code and not know why. You can't have builds in the same checkout
-with the corresponding flags on and off. Some people and projects were
-abusing this behavior.
-
-In GN, such things should be done with build arguments (`gn args`) and
-configured on your build directory when you set it up. For some people,
-this will be an extra step. But it is explicit and clear, and you can
-have multiple builds in the same checkout with different flags.
-
## How do I generate common build variants?
In GN, args go with a build directory rather than being global in the
@@ -111,3 +44,9 @@
multiple architectures in a single build.
See [GNCrossCompiles](cross_compiles.md) for more info.
+
+## Can I control what targets are built by default?
+
+Yes! If you create a group target called "default" in the top-level (root)
+build file, i.e., "//:default", GN will tell Ninja to build that by
+default, rather than building everything.
diff --git a/tools/gn/docs/language.md b/tools/gn/docs/language.md
index 6032329..e6e80d3 100644
--- a/tools/gn/docs/language.md
+++ b/tools/gn/docs/language.md
@@ -341,7 +341,10 @@
5. When a target's dependencies are resolved, write out the `.ninja`
file to disk.
6. When all targets are resolved, write out the root `build.ninja`
- file.
+ file. If the top-level build file defines a group called "default"
+ (i.e., `//:default`), GN will tell Ninja to use that for the
+ default build target, rather than building everything. (You can
+ still use `ninja all` to build everything).
### The build config file
