use-pigweed-toolchain-tools

name	Use Pigweed Toolchain Tools
description	Run toolchain binaries (objdump, nm, size, readelf, strip, etc) to disassemble code, list symbols, analyze binary size, and inspect ELF artifacts. MUST be used instead of system tools.

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.

# 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

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

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.