Skip to content

Latest commit

 

History

History
198 lines (139 loc) · 7.02 KB

AGENTS.md

File metadata and controls

198 lines (139 loc) · 7.02 KB

Perfetto Project Development Guidelines

This document provides essential instructions and best practices for developing in the Perfetto codebase. Adhere to these guidelines to ensure consistency and quality.

1. Building the Project

Use the following commands to build the project for different configurations. All commands should be run from the root of the repository.

The output folder where code is built lives in out/xxx. Different people use different output folders. Pick the output folder as follows

  • The $OUT env var should contain the path of the output folder. If it exists respect that.
  • If $OUT is empty/unset, set it by looking at the most recent out/ subdir, i.e. OUT=out/$(ls -t1 out | head -n1)

Building C++ code

Our C++ sources use tools/gn and tools/ninja to build.

  • If you touch a .gn or .gni file, rerun tools/gn gen --check $OUT
  • Afterwards, you can build code running `tools/ninja -C $OUT TARGET_NAME"
  • TARGET_NAME is:
    • perfetto_unittests: for any file in src/**/*_unittest.cc
    • perfetto_integrationtests: for any file in src/**/*_integrationtest.cc (and most code under test/)
    • perfetto_benchmarks: for any file in src/**/*_benchmark.cc (and most code under test/)
    • Other target names are usually: traced, traced_probes, perfetto, trace_processor_shell. You can discover them following the root /BUILD.gn file

When adding/removing source files, keep BUILD.gn files updated. Usually there is a BUILD.gn file in each directory. If not, look at closer parent dirs for precedent.

Never bother manually updating Android.bp files or bazel BUILD files. Those are autogenerated later when uploading the pull request via tools/gen_all $OUT, but humans will take care of that.

To build one or more targets:

tools/ninja -C $OUT -k 10000 trace_processor_shell perfetto_unittests

2. Running C++ Tests

Perfetto uses the Google Test framework. You will see c++ sources like

TEST(ProtozeroToJsonTest, Foo) {
...
}

ProtozeroToJsonTest is the test suite name, Foo the test name.

You can run all the tests in a test suite by doing:

$OUT/perfetto_unittests --gtest_brief=1 --gtest_filter="ProtozeroToJsonTest.*"

Or if you touch a specific test, you can run only that one doing

$OUT/perfetto_unittests --gtest_brief=1 --gtest_filter="ProtozeroToJsonTest.Foo"

Same goes for perfetto_integrationtests.

For perfetto_benchmarks you need instead to run

$OUT/perfetto_benchmarks --benchmark_filter='.*BM_RtMutex_NoContention.*'

Note that unlike Google Test, where the filter is a glob, in Google Benchmarks the filter is a regex.

Trace Processor Diff Tests

Trace Processor Diff Tests (or diff tests for short) are executed by running the following command:

tools/diff_test_trace_processor.py $OUT$/trace_processor_shell --keep-input --quiet --name-filter="<regex of test names>"

Note: These tests can also be run with ASan or MSan builds by changing the path from out/linux_clang_release/ to out/linux_asan/ or out/linux_msan/ respectively. Note: The --name-filter argument is optional. Note: When using the --name-filter flag, do not include test_ in the filter. The test runner automatically drops this prefix. For example, to run test_my_cool_test, use the filter MyTestSuite.my_cool_test.

Test Guidelines

  • Prefer test suites over individual tests. When using the --gtest_filter flag, specify a whole test suite (e.g., "MyTestSuite.*") instead of a single test case (e.g., "MyTestSuite.MySpecificTest"). This ensures broader test coverage.
  • Do not test unstable IDs. When writing diff tests, do not include columns that contain unstable IDs (e.g. upid, utid, id, etc) in the output. These IDs can change between different runs of the same test, which will cause the test to fail.
  • Remove test_ prefix for diff tests. When using the --name-filter flag for diff tests, do not include test_ in the filter. The test runner automatically drops this prefix. For example, to run test_my_cool_test, use the filter MyTestSuite.my_cool_test.

3. Core Software Engineering Principles

Follow these principles when writing and modifying code.

Principle 1: Don't Repeat Yourself (DRY)

  • Avoid code duplication. Before writing a new function, search the codebase for existing functions that provide similar functionality.
  • Reuse and refactor. If a suitable function exists, reuse it. If it's close but not an exact match, consider refactoring the existing function to accommodate the new use case instead of creating a copy.
  • Consult if unsure. If you are considering duplicating a function or a significant block of code, consult with the user first.

4. Getting Diffs

When asked to "get a diff" or "read the current diff", run the following command:

git diff $(git config branch.$(git rev-parse --abbrev-ref HEAD).parent)

5. Fixing GN Dependencies

When asked to fix GN dependencies, run the following command and fix any errors that are reported:

tools/gn check $OUT

Note: When fixing include errors, do not add dependencies to public_deps unless explicitly instructed to by the user. Instead, add a direct dependency to the target that requires it.

6. Other Configurations

ASan (AddressSanitizer) Build

To build with ASan for memory error detection:

tools/ninja -C out/linux_asan -k 10000 trace_processor_shell perfetto_unittests

MSan (MemorySanitizer) Build

To build with MSan for uninitialized read detection:

tools/ninja -C out/linux_msan -k 10000 trace_processor_shell perfetto_unittests

ASan (AddressSanitizer) Tests

Note: Ensure the ASAN_SYMBOLIZER_PATH is set correctly.

ASAN_SYMBOLIZER_PATH="$(pwd)/buildtools/linux64/clang/bin/llvm-symbolizer" \
out/linux_asan/perfetto_unittests --gtest_brief=1 --gtest_filter="<TestSuiteName.*>"

MSan (MemorySanitizer) Tests

Note: Ensure the MSAN_SYMBOLIZER_PATH is set correctly.

MSAN_SYMBOLIZER_PATH="$(pwd)/buildtools/linux64/clang/bin/llvm-symbolizer" \
out/linux_msan/perfetto_unittests --gtest_brief=1 --gtest_filter="<TestSuiteName.*>"

## 7. Creating Pull Requests

When creating a pull request, follow these steps:

1.  **Create a new branch:**
    Use the command `git new-branch dev/lalitm/<name-of-branch>` to create a new branch for your pull request.

2.  **Create a stacked/dependent pull request:**
    To create a pull request that depends on another, use the command `git new-branch --parent <name-of-parent-branch> dev/lalitm/<name-of-branch>`.

**Note:** The `git new-branch` command only creates and switches to a new
branch. The normal `git add` and `git commit` workflow should be used to add
changes to the branch.

## 8. Commit Messages

When writing commit messages, follow these guidelines:

- **Prefix your commits.** Prefix changes to Trace Processor code with `tp:`,
  UI code with `ui:`, and general Perfetto changes with `perfetto:`.
- **Keep it concise.** A short one-line summary followed by a paragraph
  describing the change is the best commit message.