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..18f217872deb0037e88ffcb718953613c075ce72
--- /dev/null
+++ b/blimp/docs/args.md
@@ -0,0 +1,79 @@
+# Build Arguments
+
+[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.
+
+This document addresses the creation of new build arguments for Blimp. See

[Dirk Pranke, 2016/03/09 01:28:45]

Honestly, I'm not sure that you should really have a document for creating new
build arguments for Blimp specifically; people shouldn't really be doing this
...

However, talking about when and how to define args is generically useful; you
might want to move some of this text to either //tools/gn/docs/quick_start.md or
.../style_guide.md , and link to those sections from here if possible.

[Jess, 2016/03/09 19:14:27]

Done. Please let me know your thoughts on the restructing.

+[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.

[Dirk Pranke, 2016/03/09 01:28:45]

I would probably drop lines 14 and 15. target_os isn't a good example of a
historic feature, but I'm not sure what would be. I think most users (devs)
don't need to worry about non-feature flags.

[Jess, 2016/03/09 19:14:27]

Done.

+
+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`s are typically used for filepaths. They are also used for enumerated
+options though integers and even sets of `boolean`s are often used instead.

[Dirk Pranke, 2016/03/09 01:28:45]

sets of booleans?

[Jess, 2016/03/09 19:14:27]

Ugh. Bad writing on my part. There was a segment of code that used a string
build argument as a switch statement for a series boolean defines.

Is there a recommended build arg type for enumerations? That is actually what
I'd like to capture.

+
+### 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`)

[Dirk Pranke, 2016/03/09 01:28:45]

These three sections (Scope, Type, Naming conventions) might be good additions
to the style guide (//tools/gn/docs/style_guide.md).

[Jess, 2016/03/09 19:14:27]

Done.

+
+## 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
+[`build/args/blimp_engine.gn`](../../build/args/blimp_engine.gn).
+
+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).
+
+See [building](build.md) for using these in a developer GN args setup.

[Dirk Pranke, 2016/03/09 01:28:45]

If you were to get rid of this file, I would keep this last section and merge it
into build.md.

[Jess, 2016/03/09 19:14:27]

Done.