Some documentation for the jumbo feature.

docs/jumbo.md

Index: docs/jumbo.md
diff --git a/docs/jumbo.md b/docs/jumbo.md
new file mode 100644
index 0000000000000000000000000000000000000000..cce13df4ef61dfde36c90e90ab33f8b88aa178a5
--- /dev/null
+++ b/docs/jumbo.md
@@ -0,0 +1,115 @@
+# Jumbo / Unity builds
+
+To improve compilation times it is possible to use "unity builds",
+called Jumbo builds, in Chromium. The idea is to merge many
+translation units ("source files") and compile them together. Since a
+large portion of Chromium's code is in shared header files that
+dramatically reduces the total amount of work needed.
+
+## Build instructions
+
+If jumbo isn't already enabled, you enable it in `gn` by setting
+`use_jumbo_build = true` then compile as normal.
+
+## Implementation
+
+Jumbo is currently implemented as a combined `gn` template and a
+python script. Eventually it may become a native `gn` feature. By
+using the template `jumbo_target`, each target will split into one
+action to "merge" the files and one action to compile the merged files
+and any files left outside the merge.
+
+Template file: `//build/config/jumbo.gni`
+Merge script: `//build/config/merge_for_jumbo.py`
+
+### Merge The "merge" is currently done by creating wrapper files that
+`#include` the source files.
+
+## Jumbo Pros and Cons
+
+### Pros
+
+* Everything compiles significantly faster. When fully enabled
+* everywhere this can save hours for a full build (binaries and tests)
+* on a moderate computer.  Linking is faster because there is less
+* redundant data (debug information, inline functions) to merge.
+* Certain code bugs can be statically detected by the compiler when it
+* sees more/all the relevant source code.
+
+### Cons
+
+* By merging many files, symbols that have internal linkage in
+  different `cc` files can collide and cause compilation errors.
+* The smallest possible compilation unit grows which can add
+  10-20 seconds to some single file recompilations (though link
+  times often shrink).
+
+### Mixed blessing
+* Slightly different compiler warnings will be active.
+
+## Tuning
+
+By default at most `200` files are merged at a time. The more files
+are merged, the less total CPU time is needed, but parallelism is
+reduced. This can be changed by setting `jumbo_file_merge_limit` to
+something else than `200`.
+
+## Naming
+
+The term jumbo is used to avoid the confusion resulting from talking
+about unity builds since unity is also the name of a graphical
+environment, a 3D engine, a webaudio filter and part of the QUIC
+congestion control code. Jumbo has been used as name for a unity build
+system in another browser engine.
+
+## Want to make your favourite piece of code jumbo?
+
+1. Add `import("//build/config/jumbo.gni")` to `BUILD.gn`.
+2. Change your target, for instance `static_library`, to `jumbo_target`
+3. Add a local variable `target_type` with the name of the
+   final target/template. For instance `target_type = "static_library"`
+4. Recompile and test.
+
+### Example
+Change from:
+
+    static_library("foothing") {
+      sources = [
+        "foothing.cc"
+        "fooutil.cc"
+        "fooutil.h"
+      ]
+    }
+to:
+
+    import("//build/config/jumbo.gni")  # ADDED LINE
+    jumbo_target("foothing") {          # CHANGED LINE
+      target_type = "static_library"    # ADDED LINE
+      sources = [
+        "foothing.cc"
+        "fooutil.cc"
+        "fooutil.h"
+      ]
+    }
+
+
+If you see some compilation errors about colliding symbols, resolve
+those by renaming symbols or removing duplicate code.  If it's
+impractical to change the code, add a `jumbo_excluded_sources`
+variable to your target in `BUILD.gn`:
+
+`jumbo_excluded_sources = [ "problematic_file.cc" ]`
+
+## More information and pictures
+There are more information and pictures in a
+[Google Document](https://docs.google.com/document/d/19jGsZxh7DX8jkAKbL1nYBa5rcByUL2EeidnYsoXfsYQ)
+
+## Mailing List
+Public discussions happen on the generic blink-dev and chromium-dev
+mailing lists.
+
+https://groups.google.com/a/chromium.org/group/chromium-dev/topics
+
+## Bugs / feature requests
+Related bugs use the label `jumbo` in the bug database.
+See [the open bugs](http://code.google.com/p/chromium/issues/list?q=label:jumbo).