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..c7a245a5e8b19fc77c2425edab64a2ca8881fbbf
--- /dev/null
+++ b/docs/jumbo.md
@@ -0,0 +1,86 @@
+# 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 compilation units 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.

[brucedawson, 2017/07/05 21:50:41]

compilation units-> translation units.

[Daniel Bratell, 2017/07/06 09:48:11]

Done.

+
+## 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 at 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.

[brucedawson, 2017/07/05 21:50:40]

'at native' -> 'a native'

[Daniel Bratell, 2017/07/06 09:48:12]

Done.

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

[brucedawson, 2017/07/05 21:50:41]

"include" or "#include" - there's a big difference.

[Daniel Bratell, 2017/07/06 09:48:12]

Done. #include for now.

We used concatenated files for jumbo for Presto and in sumo (another build
accelerator related to ninja) which has higher overhead and more complicated
dependency tracking but fewer surprises.

+
+## Jumbo Pros and Cons
+
+### Pros
+
+* Everything compiles faster. When fully enabled everywhere this can **save hours** for a single full compile on a moderate computer.

[brucedawson, 2017/07/05 21:50:41]

-< for a single full compile on a moderate computer.
-> for a full build on a moderate computer.

It doesn't make sense to call it a full 'compile' because it's much more than
just compiling.

BTW, my new four-core *laptop* built Chrome in 2:04:30. Jumbo builds would have
helped, I'm sure, but I'm curious as to what computers take long enough to build
Chrome that jumbo builds could possibly save hours.

[Daniel Bratell, 2017/07/06 08:28:29]

I think the answer is "tests". Browser tests and unit tests take a long time to
compile and link. When I've test build jumbo recently I've included the target
blink_tests so I got at least some tests built.

Looked at the hardware for the slowest recent Windows build. It was on a build
slave using a Intel(R) Xeon(R) CPU E3-1241 v3 @ 3.50GHz. Probably quite similar
to a normal desktop i7 CPU.

[Daniel Bratell, 2017/07/06 09:48:12]

Done.

+* Linking is faster because there is less debug data to merge.

[brucedawson, 2017/07/05 21:50:41]

-< less debug data to merge.
-> less redundant data (debug information, inline functions) to merge.

Many inline functions, especially those that are exported, are generated in
every translation unit and this also needs to be deduped by the linker.

[Daniel Bratell, 2017/07/06 09:48:12]

Done.

+* 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 in different `cc` files can collide and cause compilation errors.

[brucedawson, 2017/07/05 21:50:41]

-< symbols in different `cc` files can collide and cause compilation errors.
-> symbols that have internal linkage in different `cc` files can collide and
cause compilation errors.

[Daniel Bratell, 2017/07/06 09:48:12]

Done.

+* 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).