Create doc on build arg best practices for Blimp.
Currently this information is either not captured in docs or widely spread.
This document provides the key guidelines and best practices for creating and using a new Chrome build arg.
BUG=593073
Review URL: https://codereview.chromium.org/1772213002
Cr-Original-Commit-Position: refs/heads/master@{#380702}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: 4a8943a3f2bcb06115d9c82fd5158ccba07186a2
diff --git a/tools/gn/docs/quick_start.md b/tools/gn/docs/quick_start.md
index d59abc8..8b064de 100644
--- a/tools/gn/docs/quick_start.md
+++ b/tools/gn/docs/quick_start.md
@@ -72,7 +72,6 @@
## Configuring goma
-
Run `gn args out/Default` (substituting your build directory as needed).
Add:
@@ -282,6 +281,24 @@
Hello, Bill and Joy.
```
+## Add a new build argument
+
+You declare which arguments you accept and specify default values via
+`declare_args`.
+
+```
+declare_args() {
+ enable_teleporter = true
+ enable_doom_melon = false
+}
+```
+
+See `gn help buildargs` for an overview of how this works.
+See `gn help declare_args` for specifics on declaring them.
+
+It is an error to declare a given argument more than once in a given scope, so
+care should be used in scoping and naming arguments.
+
## Don't know what's going on?
You can run GN in verbose mode to see lots of messages about what it's
diff --git a/tools/gn/docs/style_guide.md b/tools/gn/docs/style_guide.md
index 40c5286..de46564 100644
--- a/tools/gn/docs/style_guide.md
+++ b/tools/gn/docs/style_guide.md
@@ -182,3 +182,43 @@
to do otherwise. A static library is a standalone library which can be
slow to generate. A source set just links all the object files from that
target into the targets depending on it, which saves the "lib" step.
+
+## Build arguments
+
+### Scope
+
+Build arguments should be scoped to a unit of behavior, e.g. enabling a feature.
+Typically an argument would be declared in an imported file to share it with
+the subset of the build that could make use of it.
+
+### Type
+
+Arguments support all the [GN language types](language.md#Language).
+
+In the vast majority of cases `boolean` is the preferred type, since most
+arguments are enabling or disabling features or includes.
+
+`String`s are typically used for filepaths. They are also used for enumerated
+types, though `integer`s are sometimes used as well.
+
+### Naming conventions
+
+While there are no hard and fast rules around argument naming there are
+many common conventions. If you ever want to see the current list of argument
+names and default values for your current checkout use
+`gn args out/Debug --list --short`.
+
+`use_foo` - indicates dependencies or major codepaths to include (e.g.
+`use_open_ssl`, `use_ozone`, `use_cups`)
+
+`enable_foo` - indicates feature or tools to be enabled (e.g.
+`enable_google_now`, `enable_nacl`, `enable_remoting`, `enable_pdf`)
+
+`disable_foo` - _NOT_ recommended, use `enable_foo` instead with swapped default
+value
+
+`is_foo` - usually a global state descriptor (e.g. `is_chrome_branded`,
+`is_desktop_linux`); poor choice for non-globals
+
+`foo_use_bar` - prefixes can be used to indicate a limited scope for an argument
+(e.g. `rtc_use_h264`, `v8_use_snapshot`)
