1# Perfetto build instructions 2 3The source of truth for the Perfetto codebase 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 11## Get 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## Prerequisites 22 23**Standalone checkout**: 24All dependent libraries are self-hosted and pulled through: 25``` 26$ tools/install-build-deps [--android] [--ui] 27``` 28 29**Android tree**: 30See https://source.android.com/setup 31 32 33## Building 34 35**Standalone checkout**: 36If you are a chromium developer and have depot_tools installed you can avoid 37the `tools/` prefix below and just use gn/ninja from depot_tools. 38 39`$ tools/gn args out/android` to generate build files and enter in the editor: 40 41``` 42target_os = "android" # Only when building for Android 43target_cpu = "arm" / "arm64" / "x64" # Only when building for Android 44is_debug = true / false 45cc_wrapper = "ccache" # Optionally speed repeated builds with ccache 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 63## UI development 64 65To build the UI (remember to run `tools/install-build-deps --ui` first): 66 67``` 68$ tools/ninja -C out/android ui 69 70``` 71Test your changes on a local server using: 72 73``` 74$ ui/run-dev-server out/android 75``` 76Navigate to `localhost:10000` to see the changes. 77 78## IDE setup 79 80Use a following command in the checkout directory in order to generate the 81compilation database file: 82 83``` 84$ tools/ninja -C out/android -t compdb cc cxx > compile_commands.json 85``` 86 87After generating, it can be used in CLion (File -> Open -> Open As Project), 88Visual Studio Code with C/C++ extension and any other tool and editor that 89supports the compilation database format. 90 91## Build files 92 93The source of truth of our build file is in the BUILD.gn files, which are based on [GN][gn-quickstart]. 94The Android build file ([Android.bp](/Android.bp)) is autogenerated from the GN files 95through `tools/gen_android_bp`, which needs to be invoked whenever a change 96touches GN files or introduces new ones. 97A presubmit check checks that the Android.bp is consistent with GN files when 98submitting a CL through `git cl upload`. 99The generator has a whitelist of root targets that will be translated into the 100Android.bp file. If you are adding a new target, add a new entry to the 101`default_targets` variable inside [tools/gen\_android\_bp](/tools/gen_android_bp). 102 103## Supported platforms 104 105**Linux desktop** (Debian Rodete): 106 - Hermetic clang + libcxx toolchain (both following chromium's revisions) 107 - GCC-7 and libstdc++ 6 108 109**Android**: 110 - Android's NDK r15c (using NDK's libcxx) 111 - AOSP's in-tree clang (using in-tree libcxx) 112 113**Mac**: 114 - XCode 9 / clang (currently maintained best-effort). 115 116## Build configurations 117 118TIP: `tools/build_all_configs.py` can be used to generate out/XXX folders for most of 119the supported configurations. 120 121The following [GN args][gn-quickstart] are supported: 122 123`target_os = "android" | "linux" | "mac"`: 124Defaults to the current host, set "android" to build for Android. 125 126`target_cpu = "arm" | "arm64" | "x86" | "x64"`: 127Defaults to `"arm"` when `target_os` == `"android"`, `"x64"` when targeting the 128host. 32-bit host builds are not supported. 129 130`is_debug = true | false`: 131Toggles Debug (default) / Release mode. 132 133`is_clang = true | false`: 134Use Clang (default: true) or GCC (false). 135On Linux, by default it uses the self-hosted clang (see `is_hermetic_clang`). 136On Android, by default it uses clang from the NDK (in `buildtools/ndk`). 137On Mac, by default it uses the system version of clang (requires Xcode). 138 139`is_hermetic_clang = true | false`: 140Use bundled toolchain from `buildtools/` rather than system-wide one. 141 142`cc = "gcc" / cxx = "g++"`: 143Uses a different compiler binary (default: autodetected depending on is_clang). 144 145`cc_wrapper = "tool"`: 146Prepends all build commands with a wrapper command. Using `"ccache"` here 147enables the [ccache](https://github.com/ccache/ccache) caching compiler, 148which can considerably speed up repeat builds. 149 150`is_asan = true`: 151Enables [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) 152 153`is_lsan = true`: 154Enables [Leak Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer) 155(Linux/Mac only) 156 157`is_msan = true`: 158Enables [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer) 159(Linux only) 160 161`is_tsan = true`: 162Enables [Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual) 163(Linux/Mac only) 164 165`is_ubsan = true`: 166Enables [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) 167 168 169[gn-quickstart]: https://gn.googlesource.com/gn/+/master/docs/quick_start.md 170