Contributing to Perfetto

Quickstart

NOTE: Perfetto can be built on Windows, Mac or Linux. However, setting up the environment on Windows is complicated so is not covered by this quickstart.

Prerequisites: git and python3.

Setup:

git clone https://android.googlesource.com/platform/external/perfetto/
cd perfetto
tools/install-build-deps
tools/setup_all_configs.py

Building

On Linux

For production:

tools/ninja -C out/linux_clang_release

For debug:

tools/ninja -C out/linux_clang_debug

On Mac

For production:

tools/ninja -C out/mac_release

For debug:

tools/ninja -C out/mac_debug

Contributing

Create an account at android.googlesource.com.
(if you are a Googler) Follow go/sync#get-credentials to allow uploading to Android Gerrit.
Download depot_tools, a collection of helper scripts which make uploading changes to Android Gerrit easier.cd perfetto git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
Add depot_tools to your PATH (you may want to add this to your .bashrc/.zshrc):depot_path="$(realpath depot_tools)" export PATH=$depot_path:$PATH
Create a branch with the change:git new-branch first-contribution
Make change in the repo.
Add, commit and upload the change:git add . git commit -m "My first contribution" git cl upload

Repository

This project uses Android AOSP Gerrit for code reviews, follows the Google C++ style, and targets -std=c++17.

Development happens in the AOSP repository: https://android.googlesource.com/platform/external/perfetto/

https://github.com/google/perfetto is an up-to-date and actively maintained read-only mirror of the above. Pull requests through GitHub are not accepted.

Code Reviews

All submissions, including submissions by project members, require review. We use Android AOSP Gerrit for this purpose.

git cl upload from Chromium depot tools is the preferred workflow to upload patches, as it takes care of runing presubmit tests, build-file generators and code formatting.

If you submit code directly through repo and your CL touches build files or .proto files, it's very likely that it will fail in the CI because the aforementioned generators are bypassed.

Continuous integration

There are two levels of CI / TryBots involved when submitting a Perfetto CL:

ci.perfetto.dev: it covers building and testing on most platforms and toolchains within ~15 mins. Anecdotally most build failures and bugs are detected at the Perfetto CI level.
The Android CI (also known as TreeHugger) builds a full system image and runs full integration tests within ~2-4 hours. This can shake a number of more rare integration bugs, often related with SELinux, initrc files or similar.

Both CIs are kicked in when the Presubmit-Ready: +1 is set and will publish a comment like this on the CL.

You need to wait for both CIs to go green before submitting. The only exceptions are UI-only, docs-only or GN-only changes, for which the Android CI can be bypassed, as those are not built as part of the Android tree.

You can also test a pending Perfetto CL against Chrome's TryBots.

Community

You can reach us on our Discord channel.

Mailing list: https://groups.google.com/forum/#!forum/perfetto-dev

This project follows Google's Open Source Community Guidelines.

Bugs

For bugs affecting Android or the tracing internals:

Googlers: use the internal bug tracker go/perfetto-bugs
Non-Googlers: use GitHub issues.

For bugs affecting Chrome Tracing:

Use http://crbug.com Component:Speed>Tracing label:Perfetto.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.