docs/build_instructions.md

# Perfetto - Build instructions

Perfetto can be built both from the Android tree and standalone.  
Standalone builds are meant only for local testing and are not shipped.  
Due to the reduced dependencies they are faster to iterate on and the
suggested way to work on Perfetto.

# Prerequisites
All dependent libraries are self-hosted and pulled by the
`tools/install-build-deps` script.  
The only requirements on the host are
python and git:  

```
$ sudo apt-get update && sudo apt-get install git python
```


# Standalone checkout

Get the code
------------
```
$ git clone https://android.googlesource.com/platform/external/perfetto.git
```

Build
-----
If you are a chromium developer and have depot_tools installed you can avoid
the `tools/` prefix below and just use gn/ninja from depot_tools.

`$ tools/install-build-deps` to install third-party build deps (NDK etc)

`$ tools/gn args out/android` to generate build files and enter in the editor:

```
target_os = "android"          # Leave empty for local testing
target_cpu = "arm" or "arm64"  # Only when building for Android
```

(See the [Build Configurations](#build-configurations) section below for more)

```
$ tools/ninja -C out/android all
```

This will generate artifacts under `out/android`.


# Inside the Android tree

Get the code
------------
See https://source.android.com/setup/building.
Perfetto lives in `external/perfetto` in the Android tree.

Build
-----
`$ mmma external/perfetto`
or
`$ m perfetto traced traced_probes  # put other target names here`

This will generate artifacts `out/target/product/XXX/system/`.
Executables and shared libraries are stripped by default by the Android build
system. The unstripped versions are kept into `out/target/product/XXX/symbols`.

# GN -> Android.bp generator
The source of truth of our build file is in the BUILD.gn files, which are based on [GN][gn-quickstart].
The Android build file ([Android.bp](../Android.bp)) is autogenerated from the GN files
through `tools/gen_android_bp`, which needs to be invoked whenever a change
touches GN files or introduces new ones.
A presubmit check checks that the Android.bp is consistent with GN files when
submitting a CL through `git cl upload`.
The generator has a whitelist of root targets that will be translated into the
Android.bp file. If you are adding a new target, add a new entry to the
`default_targets` variable inside [tools/gen_android_bp](../tools/gen_android_bp).


# Build configurations
The following [GN args][gn-quickstart] are supported:

`target_os = "android" | "linux" | "mac"`:  
Defaults to the current host, set "android" to build for Android.

`target_cpu = "arm" | "arm64" | "x86" | "x64"`:  
Defaults to `"arm"` when `target_os` == `"android"`, `"x64"` when targeting the
host. 32-bit host builds are not supported.

`is_debug = true | false`:  
Toggles Debug (default) / Release mode.

`is_clang = true | false`:  
Use Clang (default) / GCC. It requires clang 3.5+ to be installed on the host.
Clang is the default compiler on Mac (% having installed Xcode).
On Linux: `sudo apt-get update && sudo apt-get install clang`

`is_hermetic_clang = true | false`:  
Use bundled toolchain from `buildtools/` rather than system-wide one.

`cc = "gcc" / cxx = "g++"`:  
Uses a different compiler binary (default: autodetected depending on is_clang).

`is_asan = true`:  
Enables [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)

`is_lsan = true`:  
Enables [Leak Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer)
(Linux/Mac only)

`is_msan = true`:  
Enables [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer)
(Linux only)

`is_tsan = true`:  
Enables [Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual)
(Linux/Mac only)

`is_ubsan = true`:  
Enables [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)


[gn-quickstart]: https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/quick_start.md