1# Perfetto build instructions
2
3The source of truth for the Perfetto codebase currently lives in AOSP:
4https://android.googlesource.com/platform/external/perfetto/
5
6Perfetto can be built both from the Android tree (AOSP) and standalone.
7Standalone builds are meant only for local testing and are not shipped.
8Due to the reduced dependencies they are faster to iterate on and the
9suggested way to work on Perfetto.
10
11Get the code
12------------
13**Standalone checkout**:
14```
15$ git clone https://android.googlesource.com/platform/external/perfetto/
16```
17
18**Android tree**:
19Perfetto lives in `external/perfetto` in the AOSP tree.
20
21
22Prerequisites
23-------------
24**Standalone checkout**:
25All dependent libraries are self-hosted and pulled through:
26```
27$ tools/install-build-deps [--no-android] [--ui]
28```
29
30**Android tree**:
31See https://source.android.com/setup
32
33
34Building
35--------
36**Standalone checkout**:
37If you are a chromium developer and have depot_tools installed you can avoid
38the `tools/` prefix below and just use gn/ninja from depot_tools.
39
40`$ tools/gn args out/android` to generate build files and enter in the editor:
41
42```
43target_os = "android"                 # Only when building for Android
44target_cpu = "arm" / "arm64" / "x64"  # Only when building for Android
45is_debug = true / false
46```
47
48(See the [Build Configurations](#build-configurations) section below for more)
49
50```
51$ tools/ninja -C out/android
52```
53
54To build the UI (remember to run `tools/install-build-deps --ui` first):
55
56```
57$ tools/ninja -C out/android ui
58```
59
60**Android tree**:
61`$ mmma external/perfetto`
62or
63`$ m perfetto traced traced_probes`
64
65This will generate artifacts `out/target/product/XXX/system/`.
66Executables and shared libraries are stripped by default by the Android build
67system. The unstripped artifacts are kept into `out/target/product/XXX/symbols`.
68
69Build files
70-----------
71The source of truth of our build file is in the BUILD.gn files, which are based on [GN][gn-quickstart].
72The Android build file ([Android.bp](../Android.bp)) is autogenerated from the GN files
73through `tools/gen_android_bp`, which needs to be invoked whenever a change
74touches GN files or introduces new ones.
75A presubmit check checks that the Android.bp is consistent with GN files when
76submitting a CL through `git cl upload`.
77The generator has a whitelist of root targets that will be translated into the
78Android.bp file. If you are adding a new target, add a new entry to the
79`default_targets` variable inside [tools/gen_android_bp](../tools/gen_android_bp).
80
81
82Supported platforms
83-------------------
84**Linux desktop** (Debian Rodete):
85  - Hermetic clang + libcxx toolchain (both following chromium's revisions)
86  - GCC-7 and libstdc++ 6
87
88**Android**:
89  - Android's NDK r15c (using NDK's libcxx)
90  - AOSP's in-tree clang (using in-tree libcxx)
91
92**Mac**:
93 - XCode 9 / clang (currently maintained best-effort).
94
95
96
97Build configurations
98--------------------
99*** aside
100`tools/build_all_configs.py` can be used to generate out/XXX folders for most of
101the supported configurations.
102***
103
104The following [GN args][gn-quickstart] are supported:
105
106`target_os = "android" | "linux" | "mac"`:
107Defaults to the current host, set "android" to build for Android.
108
109`target_cpu = "arm" | "arm64" | "x86" | "x64"`:
110Defaults to `"arm"` when `target_os` == `"android"`, `"x64"` when targeting the
111host. 32-bit host builds are not supported.
112
113`is_debug = true | false`:
114Toggles Debug (default) / Release mode.
115
116`is_clang = true | false`:
117Use Clang (default: true) or GCC (false).
118On Linux, by default it uses the self-hosted clang (see `is_hermetic_clang`).
119On Android, by default it uses clang from the NDK (in `buildtools/ndk`).
120On Mac, by default it uses the system version of clang (requires Xcode).
121
122`is_hermetic_clang = true | false`:
123Use bundled toolchain from `buildtools/` rather than system-wide one.
124
125`cc = "gcc" / cxx = "g++"`:
126Uses a different compiler binary (default: autodetected depending on is_clang).
127
128`is_asan = true`:
129Enables [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)
130
131`is_lsan = true`:
132Enables [Leak Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer)
133(Linux/Mac only)
134
135`is_msan = true`:
136Enables [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer)
137(Linux only)
138
139`is_tsan = true`:
140Enables [Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual)
141(Linux/Mac only)
142
143`is_ubsan = true`:
144Enables [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
145
146
147[gn-quickstart]: https://gn.googlesource.com/gn/+/master/docs/quick_start.md
148