1# Contributing to Perfetto 2 3## Quickstart 4 5NOTE: 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. 6 7Prerequisites: git and python3. 8 9Setup: 10```sh 11git clone https://android.googlesource.com/platform/external/perfetto/ 12cd perfetto 13tools/install-build-deps 14tools/setup_all_configs.py 15``` 16 17### Building 18 19#### On Linux 20 21For production: 22```sh 23tools/ninja -C out/linux_clang_release 24``` 25 26For debug: 27```sh 28tools/ninja -C out/linux_clang_debug 29``` 30 31#### On Mac 32 33For production: 34```sh 35tools/ninja -C out/mac_release 36``` 37 38For debug: 39```sh 40tools/ninja -C out/mac_debug 41``` 42 43### Contributing 44 451. Create an account at [android.googlesource.com](https://android.googlesource.com/). 462. Download `depot_tools`, a collection of helper scripts which make uploading changes to Android gerrit easier. 47```sh 48cd perfetto 49git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git 50``` 513. Add `depot_tools` to your path: 52```sh 53depot_path="$(realpath depot_tools)" 54export PATH=$depot_path:$PATH 55``` 564. Create a branch with the change: 57```sh 58git new-branch first-contribution 59``` 605. Make change in the repo. 615. Add and commit the change: 62```sh 63git add . 64git commit -m "My first contribution" 65git cl upload 66``` 67 68## Repository 69 70This project uses [Android AOSP Gerrit][perfetto-gerrit] for code reviews, 71follows the [Google C++ style][google-cpp-style], and targets `-std=c++17`. 72 73Development happens in the AOSP repository: 74https://android.googlesource.com/platform/external/perfetto/ 75 76https://github.com/google/perfetto is an up-to-date and actively maintained 77read-only mirror of the above. Pull requests through GitHub are not accepted. 78 79## Code Reviews 80 81All submissions, including submissions by project members, require review. 82We use [Android AOSP Gerrit][perfetto-gerrit] for this purpose. 83 84`git cl upload` from [Chromium depot tools][depot-tools] is the preferred 85workflow to upload patches, as it takes care of runing presubmit tests, 86build-file generators and code formatting. 87 88If you submit code directly through `repo` and your CL touches build files or 89.proto files, it's very likely that it will fail in the CI because the 90aforementioned generators are bypassed. 91 92## Continuous integration 93 94There are two levels of CI / TryBots involved when submitting a Perfetto CL: 95 96- [ci.perfetto.dev](https://ci.perfetto.dev): it covers building and testing 97 on most platforms and toolchains within ~15 mins. Anecdotally most build 98 failures and bugs are detected at the Perfetto CI level. 99 100- The [Android CI](https://ci.android.com) (also known as TreeHugger) builds a 101 full system image and runs full integration tests within ~2-4 hours. This can 102 shake a number of more rare integration bugs, often related with SELinux, 103 initrc files or similar. 104 105Both CIs are kicked in when the `Presubmit-Ready: +1` is set and will publish a 106comment like [this][ci-example] on the CL. 107 108You need to wait for both CIs to go green before submitting. The only 109exceptions are UI-only, docs-only or GN-only changes, for which the Android CI 110can be bypassed, as those are not built as part of the Android tree. 111 112You can also 113[test a pending Perfetto CL against Chrome's TryBots](testing.md#chromium). 114 115## Community 116 117You can reach us on our [Discord channel](https://discord.gg/35ShE3A). 118 119Mailing list: https://groups.google.com/forum/#!forum/perfetto-dev 120 121This project follows 122[Google's Open Source Community Guidelines](https://opensource.google/conduct/). 123 124### Bugs 125 126For bugs affecting Android or the tracing internals: 127 128* **Googlers**: use the internal bug tracker [go/perfetto-bugs](http://goto.google.com/perfetto-bugs) 129* **Non-Googlers**: use [GitHub issues](https://github.com/google/perfetto/issues). 130 131For bugs affecting Chrome Tracing: 132 133* Use http://crbug.com `Component:Speed>Tracing label:Perfetto`. 134 135## Contributor License Agreement 136 137Contributions to this project must be accompanied by a Contributor License 138Agreement. You (or your employer) retain the copyright to your contribution; 139this simply gives us permission to use and redistribute your contributions as 140part of the project. Head over to <https://cla.developers.google.com/> to see 141your current agreements on file or to sign a new one. 142 143You generally only need to submit a CLA once, so if you've already submitted one 144(even if it was for a different project), you probably don't need to do it 145again. 146 147[perfetto-gerrit]: https://android-review.googlesource.com/q/project:platform%252Fexternal%252Fperfetto+status:open 148[google-cpp-style]: https://google.github.io/styleguide/cppguide.html 149[depot-tools]: https://dev.chromium.org/developers/how-tos/depottools 150[ci-example]: https://android-review.googlesource.com/c/platform/external/perfetto/+/1108253/3#message-09fd27fb92ca8357abade3ec725919ac3445f3af 151