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]
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
54**Android tree**:
55`$ mmma external/perfetto`
56or
57`$ m perfetto traced traced_probes`
58
59This will generate artifacts `out/target/product/XXX/system/`.
60Executables and shared libraries are stripped by default by the Android build
61system. The unstripped artifacts are kept into `out/target/product/XXX/symbols`.
62
63Build files
64-----------
65The source of truth of our build file is in the BUILD.gn files, which are based on [GN][gn-quickstart].
66The Android build file ([Android.bp](../Android.bp)) is autogenerated from the GN files
67through `tools/gen_android_bp`, which needs to be invoked whenever a change
68touches GN files or introduces new ones.
69A presubmit check checks that the Android.bp is consistent with GN files when
70submitting a CL through `git cl upload`.
71The generator has a whitelist of root targets that will be translated into the
72Android.bp file. If you are adding a new target, add a new entry to the
73`default_targets` variable inside [tools/gen_android_bp](../tools/gen_android_bp).
74
75
76Supported platforms
77-------------------
78**Linux desktop** (Debian Rodete):
79  - Hermetic clang + libcxx toolchain (both following chromium's revisions)
80  - GCC-7 and libstdc++ 6
81
82**Android**:
83  - Android's NDK r15c (using NDK's libcxx)
84  - AOSP's in-tree clang (using in-tree libcxx)
85
86**Mac**:
87 - XCode 9 / clang (currently maintained best-effort).
88
89
90
91Build configurations
92--------------------
93*** aside
94`tools/build_all_configs.py` can be used to generate out/XXX folders for most of
95the supported configurations.
96***
97
98The following [GN args][gn-quickstart] are supported:
99
100`target_os = "android" | "linux" | "mac"`:
101Defaults to the current host, set "android" to build for Android.
102
103`target_cpu = "arm" | "arm64" | "x86" | "x64"`:
104Defaults to `"arm"` when `target_os` == `"android"`, `"x64"` when targeting the
105host. 32-bit host builds are not supported.
106
107`is_debug = true | false`:
108Toggles Debug (default) / Release mode.
109
110`is_clang = true | false`:
111Use Clang (default: true) or GCC (false).
112On Linux, by default it uses the self-hosted clang (see `is_hermetic_clang`).
113On Android, by default it uses clang from the NDK (in `buildtools/ndk`).
114On Mac, by default it uses the system version of clang (requires Xcode).
115
116`is_hermetic_clang = true | false`:
117Use bundled toolchain from `buildtools/` rather than system-wide one.
118
119`cc = "gcc" / cxx = "g++"`:
120Uses a different compiler binary (default: autodetected depending on is_clang).
121
122`is_asan = true`:
123Enables [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)
124
125`is_lsan = true`:
126Enables [Leak Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer)
127(Linux/Mac only)
128
129`is_msan = true`:
130Enables [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer)
131(Linux only)
132
133`is_tsan = true`:
134Enables [Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual)
135(Linux/Mac only)
136
137`is_ubsan = true`:
138Enables [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
139
140
141[gn-quickstart]: https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/quick_start.md
142