[Revert] Force jumbo builds to fail.

Not just pointless to remove, but outright harmfull. We keep it as
it is trivial to maintain and provides huge benefits.

Change-Id: Ib7dd65996f9e985480f49fab2d1781a5d08bf6fd
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

7 files changed, 168 insertions, 18 deletions

diff --git a/chromium/build/config/jumbo.gni b/chromium/build/config/jumbo.gni
index 0c84b283bf8..9c168569120 100644
--- a/chromium/build/config/jumbo.gni
+++ b/chromium/build/config/jumbo.gni
@@ -6,18 +6,42 @@ import("//build/config/nacl/config.gni")  # To see if jumbo should be turned off
 import("//build/toolchain/goma.gni")
 
 declare_args() {
+  # If true, use a jumbo build (files compiled together) to speed up
+  # compilation.
   use_jumbo_build = false
+
+  # A list of build targets to exclude from jumbo builds, for optimal
+  # round trip time when frequently changing a set of cpp files. The
+  # targets can be just the short name (in which case it matches any
+  # target with that name), a directory prefixed with the root
+  # specifier //, or a full build target label.
+  #
+  # Example:
+  # These would all exclude the "browser" target in a file
+  # content/browser/BUILD.gn, and potentially more.
+  #
+  # jumbo_build_excluded = [ "browser" ]
+  # jumbo_build_excluded = [ "//content/browser" ]
+  # jumbo_build_excluded = [ "//content/browser:browser" ]
   jumbo_build_excluded = []
+
+  # How many files to group on average. Smaller numbers give more
+  # parallellism, higher numbers give less total CPU usage. Higher
+  # numbers also give longer single-file recompilation times.
+  #
+  # Recommendations:
+  # Higher numbers than 100 does not reduce wall clock compile times
+  # even for 4 cores or less so no reason to go higher than 100.
+  # Going from 50 to 100 with a 4 core CPU saves about 3% CPU time and
+  # 3% wall clock time in a tree with blink, v8 and content
+  # jumbofied. At the same time it increases the compile time for the
+  # largest jumbo chunks by 10-20% and reduces the chance to use all
+  # available CPU cores. So set the default to 50 to balance between
+  # high and low-core build performance. -1 means do the default which
+  # varies depending on whether goma is enabled.
   jumbo_file_merge_limit = -1
 }
 
-# TODO(crbug.com/994387): Remove all uses of the jumbo_* templates from the
-# BUILD.gn files, and then remove this whole file.
-assert(!use_jumbo_build,
-       "The jumbo build is no longer supported. Please remove any uses of " +
-           "'use_jumbo_build', 'jumbo_build_excluded', or " +
-           "'jumbo_file_merge_limit' from your args.gn file and re-run GN.")
-
 # Normal builds benefit from lots of jumbification
 jumbo_file_merge_default = 50
 
diff --git a/chromium/docs/clang_tidy.md b/chromium/docs/clang_tidy.md
index 72e3d5c329f..6a52fade04f 100644
--- a/chromium/docs/clang_tidy.md
+++ b/chromium/docs/clang_tidy.md
@@ -58,7 +58,8 @@ ninja clang-apply-replacements
 ## Running clang-tidy
 
 Running clang-tidy is (hopefully) simple.
-1.  Build chrome normally.
+1.  Build chrome normally.\* Note that [Jumbo builds](jumbo.md) are not
+    supported.
 ```
 ninja -C out/Release chrome
 ```
@@ -98,9 +99,9 @@ Copy-Paste Friendly (though you'll still need to stub in the variables):
     chrome/browser
 ```
 
-\*It's not clear which, if any, `gn` flags may cause issues for
-`clang-tidy`. I've had no problems building a component release build,
-both with and without goma. if you run into issues, let us know!
+\*It's not clear which, if any, `gn` flags outside of `use_jumbo_build` may
+cause issues for `clang-tidy`. I've had no problems building a component release
+build, both with and without goma. if you run into issues, let us know!
 
 ## Questions
 
diff --git a/chromium/docs/clang_tool_refactoring.md b/chromium/docs/clang_tool_refactoring.md
index d4e9f94748c..b8d31a64921 100644
--- a/chromium/docs/clang_tool_refactoring.md
+++ b/chromium/docs/clang_tool_refactoring.md
@@ -15,6 +15,8 @@ with a traditional find-and-replace regexp:
 
 ## Caveats
 
+* Clang tools do not work with jumbo builds.
+
 * Invocations of a clang tool runs on on only one build config at a time. For
 example, running the tool across a `target_os="win"` build won't update code
 that is guarded by `OS_POSIX`. Performing a global refactoring will often
diff --git a/chromium/docs/jumbo.md b/chromium/docs/jumbo.md
index 347f1dbc854..c2426e3d398 100644
--- a/chromium/docs/jumbo.md
+++ b/chromium/docs/jumbo.md
@@ -1,12 +1,116 @@
 # Jumbo / Unity builds
 
-[Jumbo / Unity builds are no longer supported in Chromium](crbug.com/994387).
+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.
 
-They were a mechanism for speeding up local builds by combining multiple
-files into a single compilation unit.
+## Build instructions
 
-We are still in the process of cleaning up the build files to remove
-references to the jumbo templates.
+If jumbo isn't already enabled, you enable it in `gn` by setting
+`use_jumbo_build = true` then compile as normal.
 
-**[TODO(crbug.com/994387)](crbug.com/994387)**: Remove this page itself
-when all references to jumbo have been removed from the build files.
+## Implementation
+
+Jumbo is currently implemented as a combined `gn` template and a
+python script. Eventually it may become a native `gn` feature. By
+(indirectly) using the template `internal_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 on average `50`, or `8` when using goma, files are merged at a
+time. The more files that are are merged, the less total CPU time is
+needed, but parallelism is reduced. This number can be changed by
+setting `jumbo_file_merge_limit`.
+
+## 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_static_library`. So far `source_set`, `component`,
+   `static_library` are supported.
+3. Recompile and test.
+
+### Example
+Change from:
+
+    source_set("foothing") {
+      sources = [
+        "foothing.cc"
+        "fooutil.cc"
+        "fooutil.h"
+      ]
+    }
+to:
+
+    import("//build/config/jumbo.gni")  # ADDED LINE
+    jumbo_source_set("foothing") {      # CHANGED 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).
diff --git a/chromium/docs/linux_build_instructions.md b/chromium/docs/linux_build_instructions.md
index c70a0c34548..d4324866883 100644
--- a/chromium/docs/linux_build_instructions.md
+++ b/chromium/docs/linux_build_instructions.md
@@ -153,6 +153,15 @@ use_goma=true
 goma_dir=/path/to/goma-client
 ```
 
+#### Jumbo/Unity builds
+
+Jumbo builds merge many translation units ("source files") and compile them
+together. Since a large portion of Chromium's code is in shared header files,
+this dramatically reduces the total amount of work needed. Check out the
+[Jumbo / Unity builds](jumbo.md) for more information.
+
+Enable jumbo builds by setting the GN arg `use_jumbo_build=true`.
+
 #### Disable NaCl
 
 By default, the build includes support for
diff --git a/chromium/docs/mac_build_instructions.md b/chromium/docs/mac_build_instructions.md
index 389a1fe8a5d..49c09f79a87 100644
--- a/chromium/docs/mac_build_instructions.md
+++ b/chromium/docs/mac_build_instructions.md
@@ -140,6 +140,15 @@ in your args.gn to disable debug symbols altogether.  This makes both full
 rebuilds and linking faster (at the cost of not getting symbolized backtraces
 in gdb).
 
+#### Jumbo/Unity builds
+
+Jumbo builds merge many translation units ("source files") and compile them
+together. Since a large portion of Chromium's code is in shared header files,
+this dramatically reduces the total amount of work needed. Check out the
+[Jumbo / Unity builds](jumbo.md) for more information.
+
+Enable jumbo builds by setting the GN arg `use_jumbo_build=true`.
+
 #### CCache
 
 You might also want to [install ccache](ccache_mac.md) to speed up the build.
diff --git a/chromium/docs/windows_build_instructions.md b/chromium/docs/windows_build_instructions.md
index dda0accd2a5..d2734befc51 100644
--- a/chromium/docs/windows_build_instructions.md
+++ b/chromium/docs/windows_build_instructions.md
@@ -239,6 +239,7 @@ in the editor that appears when you create your output directory
 (`gn args out/Default`) or on the gn gen command line
 (`gn gen out/Default --args="is_component_build = true is_debug = true"`).
 Some helpful settings to consider using include:
+* `use_jumbo_build = true` - [Jumbo/unity](jumbo.md) builds.
 * `is_component_build = true` - this uses more, smaller DLLs, and incremental
 linking.
 * `enable_nacl = false` - this disables Native Client which is usually not