Create doc on build arg best practices for Blimp.

blimp/docs/args.md

Index: blimp/docs/args.md
diff --git a/blimp/docs/args.md b/blimp/docs/args.md
new file mode 100644
index 0000000000000000000000000000000000000000..3ab76c0facd511fd0bbe275c5b3c791712033763
--- /dev/null
+++ b/blimp/docs/args.md
@@ -0,0 +1,77 @@
+# Build Arguments

[nyquist, 2016/03/08 22:42:35]

Should this page be linked to from somewhere?

[Jess, 2016/03/09 00:39:32]

Done.

+
+[Build arguments](../../tools/gn/docs/language.md#Build-arguments)
+can be passed via the command line or an args.gn file to control the build.

[nyquist, 2016/03/08 22:42:35]

Nit: could you do `args.gn`?

[Jess, 2016/03/09 00:39:32]

Done.

+
+This document addresses the creation of new build arguments for Blimp. See
+[building](build.md) for developer GN args setup.
+
+## Best Practices
+
+### Scope
+
+Build arguments should be scoped to a unit of behavior, e.g. enabling a feature.
+There are historic examples in core code that do not conform (e.g. target_os),
+but the build team recommends this convention for all new arguments.
+
+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](../../tools/gn/docs/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 are typically used for filepaths. They are also used for enumerated

[nyquist, 2016/03/08 22:42:35]

Nit: Could you add ` around String to make it clear it's the data type String?

Nit: "`String` is' or "`String`s are"?

[Jess, 2016/03/09 00:39:32]

Done.

+options though integers and even sets of booleans are often used instead.
+
+### 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`)
+
+## Declaring Build Args
+
+You declare which arguments you accept and specify default values via
+`declare_args`. 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.
+
+## Build Args for Behavior
+
+While build args directly affect build behavior and values they can not be
+directly referenced in code. This can be handled with an entry in the
+[defines](../../tools/gn/docs/reference.md#defines_C-preprocessor-defines)
+set that can then be used in code.
+
+## Updating Args Templates
+
+Blimp has default argument templates for the
+[build/args/blimp_client.gn](../../build/args/blimp_client.gn) and

[nyquist, 2016/03/08 22:42:35]

Could you make these paths surrounded by quotes?
Like: [`build/args/...`](../../build/args/...)

[Jess, 2016/03/09 00:39:32]

Done.

+[build/args/blimp_engine.gn](../../build/args/blimp_engine.gn).

[nyquist, 2016/03/08 22:42:35]

Should we also describe here how to import them in args.gn, or maybe refer to
build.md as a reference_

[Jess, 2016/03/09 00:39:32]

Done.

+
+If you create a new argument where the default behavior for the rest of chrome
+does not match the default behavior of typical blimp build,
+you should update the respective blimp argument template(s).