1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
# 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
(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).
|
