cargo-binutils

To use cargo-binutils, you must install the crate itself and add the llvm-tools component via rustup to ensure the underlying LLVM tools are available in your toolchain.

$ cargo install cargo-binutils

$ rustup component add llvm-tools

When using cargo subcommands (e.g., cargo nm, cargo objdump, cargo size), you can use standard Cargo flags to specify which artifact to inspect. This avoids manually providing paths to the compiled files.

Supported flags for build and inspect mode:

• --bin NAME: Specify a specific binary.
• --example NAME: Specify a specific example.
• --lib: Specify a library.
• --target TARGET: Specify a target triple.
• --release: Build and inspect the release artifact.

When using cargo-binutils, some tools require the project to be built before they can be run, while others can operate on files directly.

Tools that require a prior cargo build:

• nm
• objcopy
• objdump
• readobj
• size
• strip

Tools that do NOT require a prior build:

• ar
• as
• cov
• lld
• profdata

The cargo-binutils package provides Cargo subcommands that act as proxies for the llvm-* tools (like nm, objcopy, objdump, etc.) shipped with the Rust toolchain.

When you run a command like cargo nm, the utility automatically handles finding the correct artifact produced by your Cargo project, setting up the appropriate execution context (like target triples), and passing your arguments through to the underlying LLVM tool.

To pass arguments directly to the underlying tool, use the -- separator. For example, to see the help documentation for the proxied tool, run:

cargo <tool> -- --help

The cargo-binutils toolset performs internal mapping between Rust target architectures and the architecture names expected by LLVM tools (like objdump or size). This mapping accounts for differences in naming conventions, specifically regarding endianness and specific architecture variants (e.g., x86_64 in Rust mapping to x86-64 in LLVM).

Key mapping logic includes:

• Endianness handling: For architectures like aarch64, arm, mips, and sparc, the tool appends suffixes like _be (big-endian) or el/le (little-endian) based on the target configuration.
• Thumb support: If a target name starts with thumb, it is mapped to thumbeb for big-endian or thumb for little-endian.
• Specific name translations:
  • s390x $\rightarrow$ systemz
  • sparc64 $\rightarrow$ sparcv9
  • powerpc $\rightarrow$ ppc32
  • x86_64 $\rightarrow$ x86-64

All arguments specified after the -- delimiter are passed directly to the underlying LLVM tool. This allows you to use any flags supported by the specific tool (e.g., objdump or nm) that are not explicitly handled by the cargo-binutils wrapper.

Example for objdump:

cargo objdump -- -h

cargo <tool> -- <args>

Use cargo objcopy to transform the output of Cargo (typically ELF) into other formats, such as a raw binary format.

Example: Transform a release build into a binary file named app.bin:

$ cargo objcopy --release -- -O binary app.bin

Use cargo size to print the size of sections in the binary in System V format.

$ cargo size --release -- -A -x

Use cargo objdump to disassemble a binary. For cargo-objdump, the architecture of the compilation target is automatically passed as -arch-name=$target to llvm-objdump.

$ cargo objdump --release -- --disassemble --no-show-raw-insn target/thumbv7m-none-eabi/debug/app

The rust-lld tool provides a link to lld. You can use it to change the linker or provide a workaround if -C linker-flavor is insufficient. This is typically configured in .cargo/config.

[target.wasm32-unknown-unknown]
linker = "rust-lld"

Use cargo-strip to strip all symbols from the build artifact to reduce its size.

$ cargo-strip --release -- --strip-all -o smaller-hello