---
name: pigweed-project/Use Pigweed Toolchain Tools
source: https://app.decimal.ai/s/pigweed-project-use-pigweed-toolchain-tools@1/SKILL.md
source_sha256: f802038868ac
---

# Use Pigweed Toolchain Tools

When you need to inspect build artifacts using standard tools like `objdump`, `nm`, `size`, `readelf`, or `strip`, **DO NOT** use your local system binaries or search for toolchain paths in the filesystem.

Local system tools often lack support for the target architecture (e.g., a host `nm` cannot read an ARM ELF), and Pigweed's hermetic toolchain binaries are stored in internal Bazel directories that are difficult to access manually.

Instead, use the runnable targets in `//pw_toolchain/cc/current_toolchain`. These targets **dynamically resolve** the correct tool from the active toolchain's action mapping, ensuring you use the exact same binary and configuration as the build itself.

## Usage

Run the tools via `bazelisk run` with the appropriate `--config` (e.g., `rp2350` or `host`).

### Supported Tools

| Tool | Target (under `//pw_toolchain/cc/current_toolchain:`) |
| :--- | :--- |
| **objdump** | `:objdump` |
| **nm** | `:nm` |
| **size** | `:size` |
| **readelf** | `:readelf` |
| **strip** | `:strip` |
| **ar** | `:ar` |
| **ld** | `:ld` |
| **cc / c++** | `:cc` / `:c++` |
| **cov** | `:cov` |
| **gcov** | `:gcov` |

> [!IMPORTANT]
> **Interactive use only**: These targets must only be used with `bazelisk run`. **Do NOT** use them as dependencies (`srcs`, `deps`) in other rules, as Bazel's configuration transitions will likely select the wrong tool for the context.

> [!NOTE]
> Tool availability depends on the suite (LLVM, GCC, or Zephyr variants). These targets
> work seamlessly across all supported toolchains—for example, when targeting
> an ARM MCU, `:nm` will correctly resolve to `arm-none-eabi-nm` or the
> Zephyr equivalent based on your configuration.

## Examples

### Disassemble a binary
The target must be built first so the binary exists. When passing file paths to `bazelisk run`, use absolute paths (e.g., `$PWD/...`) because the tool runs from the execution root, not the current working directory.

```bash
# 1. Build the target
bazelisk build --config=rp2350 //pw_status:status_test

# 2. Run objdump with the absolute path to the binary
bazelisk run --config=rp2350 //pw_toolchain/cc/current_toolchain:objdump -- -d "$PWD/bazel-bin/pw_status/status_test"
```

### Check binary size
```bash
bazelisk build --config=rp2350 //pw_status:status_test
bazelisk run --config=rp2350 //pw_toolchain/cc/current_toolchain:size -- "$PWD/bazel-bin/pw_status/status_test"
```

### List symbols
```bash
bazelisk build --config=rp2350 //pw_status:status_test
bazelisk run --config=rp2350 //pw_toolchain/cc/current_toolchain:nm -- "$PWD/bazel-bin/pw_status/status_test"
```

## When to use this skill
Use this skill whenever you need to inspect binary artifacts generated by the build. This ensures compatibility across different host OSes and toolchain versions.