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