GEMINI.md

## Overview

Pigweed is a collection of embedded libraries, called "modules," that work
together to enable faster and more robust development of embedded systems. It
provides a comprehensive development environment, including a build system,
testing frameworks, and tools for debugging and analysis.

## Local guidelines for AI agents

This document provides guidelines for AI agents making changes to the Pigweed
codebase.

Some subdirectories, such as `pw_ide`, contain their own `GEMINI.md` file with
more specific instructions for that area of the codebase. When working in those
areas, please refer to the local `GEMINI.md` for more detailed guidance.

## C++ Development Guidance

This section provides specific guidance for writing C++ code and tests in
Pigweed.

### Testing

Pigweed places a strong emphasis on testing. Here are some key points to
remember:

- **Framework:** Tests are written using the `pw_unit_test` framework, which
  provides a GoogleTest-like API. You should be familiar with the `TEST` and
  `TEST_F` macros for defining test cases, and the `EXPECT_*` and `ASSERT_*`
  macros for assertions.
- **File Location:** Test files should be located in the same module as the code
  they are testing and have a `_test.cc` suffix.
- **Status and Result:** Use `PW_TEST_EXPECT_OK` and `PW_TEST_ASSERT_OK` to test
  functions that return `pw::Status` or `pw::Result`.
- **Negative Compilation Tests:** Pigweed uses negative compilation tests
  (`PW_NC_TEST`) to verify that code fails to compile under specific conditions.
  This is particularly useful for testing static assertions and template
  metaprogramming.
- **Test Naming:** Test suites and test cases should be named clearly and
  descriptively. The test suite name often corresponds to the class or module
  being tested, and the test case name describes the specific behavior being
  tested.

### C++ Style Guide (Condensed)

This is a condensed version of the Pigweed C++ style guide. For more details,
refer to the full style guide.

- **C++ Standard:** All C++ code must compile with `-std=c++17`. C++20 features
  can be used if the code remains C++17 compatible.
- **Formatting:** Code is automatically formatted with `clang-format`.
- **C and C++ Standard Libraries:**
  - Use C++-style headers (e.g., `<cstdlib>` instead of `<stdlib.h>`).
  - A limited subset of the C++ Standard Library is permitted. Dynamic memory
    allocation, streams, and exceptions are disallowed in core Pigweed modules.
  - Use Pigweed's own libraries (e.g., `pw::string`, `pw::sync`, `pw::function`)
    instead of their `std` counterparts.
- **Comments:**
  - Prefer C++-style comments (`//`).
  - Code in comments should be indented with two additional spaces.
- **Control Statements:**
  - Always use braces for loops and conditionals.
  - Prefer early exits with `return` and `continue`.
  - Do not use `else` after a `return` or `continue`.
- **Error Handling:**
  - Use `pw::Status` and `pw::Result` for recoverable errors.
  - Use `PW_ASSERT` and `PW_CHECK` for fatal errors.
- **Include Guards:** Use `#pragma once`.
- **Logging:**
  - Use the `pw_log` module for logging.
  - Log errors as soon as they are unambiguously determined to be errors.
  - Log at the appropriate level (`PW_LOG_DEBUG`, `PW_LOG_INFO`, `PW_LOG_WARN`,
    `PW_LOG_ERROR`, `PW_LOG_CRITICAL`).
- **Memory Allocation:** No dynamic memory allocation in core Pigweed code.
- **Naming:**
  - All C++ code must be in the `pw` namespace.
  - C symbols must be prefixed with the module name (e.g., `pw_tokenizer_*`).
  - Public macros must be prefixed with `PW_MY_MODULE_*`.
- **Pointers and References:**
  - Place the `*` or `&` next to the type (e.g., `int* number`).
  - Prefer references over pointers when possible.
- **Preprocessor Macros:**
  - Use macros only when they significantly improve the code.
  - Standalone statement macros must require a semicolon.
- **Unsigned Integers:** Permitted, but be careful when mixing with signed
  integers.
- **Unused Variables:** The `PW_MAYBE_UNUSED` macro is deprecated and has been
  removed. For handling unused variables, the standard C++ attribute
  `[[maybe_unused]]` should be used instead.

## Python Development Guidance

### Python Style Guide (Condensed)

- **Style:** Pigweed follows PEP 8. Code should pass `pw format`, which uses
  `black`.
- **Python Versions:** Upstream Pigweed code must support the officially
  supported Python versions.
- **Generated Files:** Python packages with generated files should extend their
  import path in `__init__.py`.

## Project Conventions

### Build System Interaction

Pigweed uses `gn` and `bazel` as its primary build systems. Here are some common
commands:

- **`gn` (Meta-build system):**

  - **Generate build files:** `gn gen out`
  - **Build all targets and run tests:** `ninja -C out --quiet`
  - **Clean the build:** `gn clean out`

- **`bazel` (Build system):**
  - **Note:** Always use `bazelisk` and not `bazel` to ensure the correct
    `bazel` version is in use. **Note:** Use `--noshow_progress`
    `--noshow_loading_progress` to reduce the amount of output produced and
    avoid polluting the context window.
  - **Build a target:**
    `bazelisk build --noshow_progress --noshow_loading_progress //path/to/module:target`
  - **Run a test:**
    `bazelisk test --noshow_progress --noshow_loading_progress //path/to/module:target`
  - **Run all tests in a module:**
    `bazelisk test --noshow_progress --noshow_loading_progress //path/to/module/...`

### Commit Message Conventions

Pigweed follows a specific commit message format. A good commit message should
be concise and descriptive.

- **Subject Line:**

  - Start with the module name affected by the change, followed by a colon.
  - Use the imperative mood (e.g., "Add feature" not "Added feature").
  - Keep it under 72 characters.
  - Example: `pw_foo: Add support for bar feature`

- **Body:**

  - Explain the "what" and "why" of the change, not the "how".
  - Reference any relevant issue trackers.
  - If you are tempted to write a long commit message, consider if the content
    is better written in the docs and referred to from the commit.
  - Use a `Bug:` or `Fixed:` line for bug fixes.
  - Example:

    ``` This change adds support for the bar feature to the `pw_foo` module.
    This is necessary because...

    Bug: b/123456789 ```

## Fetching Change List (CL) diffs

Fuchsia development happens on Gerrit When the user asks for you to read a CL
for them, do the following:

1. Parse the change id from the CL URL. If the URL is `pwrev/1234`, then the id
   is 1234. If the URL is
   `https://pigweed-review.googlesource.com/c/pigweed/+/1299104`, then the ID is
   `1299104`.
2. If the user asked for a CL hosted at
   `https://pigweed-review.googlesource.com`, run this shell command to get the
   diff from the changelist:
   `curl -L https://pigweed-review.googlesource.com/changes/<ID>/revisions/current/patch?raw`.
3. Use this diff to answer further questions about the changelist

## Code review response workflow

Pigweed development happens on Gerrit, and you can help users get changes
through the review process by automating parts of the review flow. When the user
asks for reading review comments, do this:

1. Get change ID from the last couple git commits or ask user for it
2. Run this shell command to get open comments on the change:
   `curl https://pigweed-review.googlesource.com/changes/<ID>/comments`
3. Read the unresolved comments: i.e. have `unresolved=true`, and are for latest
   `patch_set` only
4. Read the relevant file and get the surrounding context in the file mentioned
5. List down comments (and address them if user asked to) along with exact ONE
   line in code where it belongs