enhance esp-idf-size

[Jason2866]

Description:

Enhance use of esp-idf-size

Example for using in platformio.ini

[env:esp32dev]
board = esp32dev
framework = arduino

; Standard-parameters for esp-idf-size (optional)
custom_esp_idf_size_args = --format=text

; Verbose-mode for Debug-Output (optional)
custom_esp_idf_size_verbose = true

; Example for different Output formats:
; custom_esp_idf_size_args = --format=csv --output-file=size_report.csv
; custom_esp_idf_size_args = --format=json --archives
; custom_esp_idf_size_args = --format=text --files

Terminal (CLI)

# Build and show metrics
pio run -t metrics

# Only metrics without build
pio run -t metrics-only

With Command Line Parameters

# CSV format output
pio run -t metrics -- --format=csv

# JSON format with archive details
pio run -t metrics -- --format=json --archives

# Output to file
pio run -t metrics -- --format=csv --output-file=firmware_size.csv

# Detailed file analysis
pio run -t metrics -- --format=text --files --archives

# Compare with another map file
pio run -t metrics -- --diff=previous_build.map

# Combined parameters
pio run -t metrics -- --format=json --archives --output-file=detailed_report.json

Advanced Usage

# With environment-specific parameters
pio run -e esp32dev -t metrics -- --format=csv

# Multiple environments
pio run -e esp32dev -e esp32s3 -t metrics

# Verbose mode for debugging
pio run -t metrics -- --format=text --archives

# Memory analysis with specific sections
pio run -t metrics -- --format=text --archives --files

# Generate size comparison report
pio run -t metrics -- --format=csv --output-file=size_comparison.csv --archives

# Quick size overview
pio run -t metrics-only -- --format=text

# Detailed JSON report for CI/CD
pio run -t metrics -- --format=json --output-file=build_metrics.json --archives --files

Practical workflow examples

# Development workflow: build and analyze
pio run && pio run -t metrics-only -- --format=text --archives

# CI/CD pipeline: generate reports
pio run -t metrics -- --format=json --output-file=metrics.json

# Size optimization: compare builds
pio run -t metrics -- --format=csv --output-file=before_optimization.csv
# ... make changes ...
pio run -t metrics -- --diff=before_optimization.map --format=text

# Release preparation: comprehensive analysis
pio run -t metrics -- --format=text --archives --files --output-file=release_metrics.txt

Checklist:

• The pull request is done against the latest develop branch
• Only relevant files were touched
• Only one feature/fix was added per PR, more changes are allowed when changing boards.json
• I accept the CLA

Summary by CodeRabbit

• New Features

  • Introduced two new build targets, "metrics" and "metrics-only", for flexible firmware size analysis after building or on existing builds.
  • Enhanced firmware size reporting to support custom command line arguments and improved verbose output.

• Bug Fixes

  • Improved error handling with clearer messages for missing files or tools during firmware size analysis.

[coderabbitai]

Walkthrough

The changes remove the conditional check for "SHOW_METRICS" in the ESP-IDF build process, making map file generation unconditional. The firmware size metrics functionality is enhanced to support custom arguments, improved error handling, and verbose output. Two new build targets, metrics and metrics-only, are introduced for flexible firmware size analysis.

Changes

File(s)	Change Summary
builder/frameworks/espidf.py	Removed conditional check for "SHOW_METRICS"; linker flag for map file is now always appended.
builder/main.py	Enhanced firmware_metrics to accept custom args, improved error handling, added verbose output.
builder/main.py	Added new custom build targets: metrics (with build dependency) and metrics-only (no dependency).

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant BuildSystem
    participant firmware_metrics
    participant esp-idf-size

    User->>BuildSystem: Invoke 'metrics' or 'metrics-only' target
    BuildSystem->>firmware_metrics: Call with target, source, env
    firmware_metrics->>firmware_metrics: Parse custom args and options
    firmware_metrics->>esp-idf-size: Run with map file and custom args
    esp-idf-size-->>firmware_metrics: Return size analysis output
    firmware_metrics-->>BuildSystem: Print/report results

Loading

Possibly related PRs

• Add espressif esp-idf-size to the build engine to show firmware metrics #178: Extends esp-idf-size integration by removing conditional map file generation and enhancing size reporting, directly building on the earlier esp-idf-size support.

Poem

A bunny hopped into the build tonight,
Unconditional maps now in sight!
Metrics with options, verbose and neat,
Two new targets make the workflow complete.
With every byte and every line,
Firmware size is now easy to define!
🐇✨

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7d84d32 and 2d9ff88.

📒 Files selected for processing (2)

• builder/frameworks/espidf.py (1 hunks)
• builder/main.py (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (15)

• GitHub Check: build (macos-15, examples/espidf-blink)
• GitHub Check: build (windows-latest, examples/espidf-peripherals-usb)
• GitHub Check: build (windows-latest, examples/espidf-ulp-riscv)
• GitHub Check: build (windows-latest, examples/arduino-zigbee-switch)
• GitHub Check: build (windows-latest, examples/arduino-wifiscan)
• GitHub Check: build (ubuntu-24.04, examples/espidf-peripherals-usb)
• GitHub Check: build (ubuntu-24.04, examples/espidf-storage-sdcard)
• GitHub Check: build (ubuntu-24.04, examples/espidf-exceptions)
• GitHub Check: build (ubuntu-24.04, examples/espidf-arduino-matter-light)
• GitHub Check: build (ubuntu-24.04, examples/espidf-blink)
• GitHub Check: build (ubuntu-24.04, examples/espidf-hello-world)
• GitHub Check: build (ubuntu-24.04, examples/tasmota)
• GitHub Check: build (ubuntu-24.04, examples/espidf-arduino-littlefs)
• GitHub Check: build (ubuntu-24.04, examples/arduino-NimBLE-ext_client)
• GitHub Check: build (ubuntu-24.04, examples/arduino-wifiscan)

🔇 Additional comments (4)

builder/frameworks/espidf.py (1)

1802-1805: LGTM! Unconditional map file generation supports enhanced metrics functionality.

This change ensures that map files are always generated, which is essential for the new metrics and metrics-only build targets added in builder/main.py. The implementation correctly uses f-string formatting and proper path construction.

builder/main.py (3)

363-366: Well-documented function enhancement.

The updated docstring clearly explains the new functionality and provides a helpful usage example for passing command-line arguments.

---

376-422: Excellent error handling and argument parsing implementation.

The enhanced function demonstrates several best practices:

• Comprehensive error handling: Covers missing map file, Python executable, and esp-idf-size module scenarios with actionable error messages
• Proper argument parsing: Uses shlex.split() for platformio.ini arguments and correctly handles command-line arguments after --
• Appropriate subprocess usage: Uses subprocess.run() with check=False and capture_output=False for proper output handling
• Conditional debug output: Helpful for troubleshooting when verbose mode is enabled

---

659-682: Well-designed build targets for flexible firmware analysis.

The two new build targets provide excellent flexibility:

• metrics: Depends on the ELF file, enabling a build-then-analyze workflow
• metrics-only: No build dependencies, allowing analysis of existing builds
• Both targets appropriately use always_build=True for analysis operations
• Clear, descriptive titles and descriptions enhance user experience

This design pattern allows users to choose the appropriate workflow for their needs.

✨ Finishing Touches

• 📝 Generate Docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[Jason2866]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.