Skip to content

feature: Install espressif Gdb Python debug module#427

Merged
Jason2866 merged 9 commits into
developfrom
gdb_debug
Mar 12, 2026
Merged

feature: Install espressif Gdb Python debug module#427
Jason2866 merged 9 commits into
developfrom
gdb_debug

Conversation

@Jason2866
Copy link
Copy Markdown

@Jason2866 Jason2866 commented Mar 12, 2026

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

  • Chores
    • Automatic installation of the freertos-gdb extension into embedded Python environments for installed GDB tools to improve debugging.
    • Installation respects network availability and will skip gracefully when offline.
    • GDB command snippets simplified for more reliable extension loading.
    • GDB tool selection made dynamic to support multiple tool variants.

Added function to install freertos-gdb into GDB tool packages if not already present.
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 12, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cf5ab302-8552-44bc-b7ad-2ffa68d246b5

📥 Commits

Reviewing files that changed from the base of the PR and between 312b566 and f85fe60.

📒 Files selected for processing (3)
  • builder/main.py
  • builder/penv_setup.py
  • platform.py

📝 Walkthrough

Walkthrough

Adds GDB_TOOL_PACKAGES and an install_freertos_gdb(platform, uv_executable, penv_executable, uv_cache_dir=None) function to install freertos-gdb into GDB tool embedded Python sites; wires the installer into platform/penv setup and replaces hardcoded GDB package names. Note: the installer is defined twice in the same module (duplicate definition).

Changes

Cohort / File(s) Summary
Penv setup
builder/penv_setup.py
Added GDB_TOOL_PACKAGES constant, introduced has_network (derived from has_internet_connection() or github_actions), and added install_freertos_gdb(...) to pip-install freertos-gdb into each GDB tool's embedded Python site (share/gdb/python/). The function is duplicated (two identical definitions). Minor whitespace tweak in has_internet_connection().
Platform wiring & GDB cmds
platform.py
Imports/wires penv_setup as penv_setup_module, exports install_freertos_gdb, replaces hardcoded GDB package names with entries from GDB_TOOL_PACKAGES, invokes install_freertos_gdb(...) after toolchain setup, and simplifies _get_freertos_gdb_cmds() to emit a single-line try/except.
Main runtime selection
builder/main.py
Replaces hardcoded GDB tool package names with GDB_TOOL_PACKAGES indices when selecting GDB tool directories for xtensa vs riscv targets; path construction otherwise unchanged.

Sequence Diagram(s)

sequenceDiagram
    participant Platform as Platform
    participant Penv as penv_setup.install_freertos_gdb
    participant UV as uv (pip)
    participant Tools as GDB tool packages
    participant FS as Filesystem/Logger

    rect rgba(200,230,255,0.5)
    Platform->>Penv: call install_freertos_gdb(platform, uv_exe, penv_exe, cache_dir)
    end

    rect rgba(220,255,200,0.5)
    Penv->>Tools: enumerate installed GDB tool packages (GDB_TOOL_PACKAGES)
    Penv->>UV: run "uv --pip install --target=... freertos-gdb" (use UV_CACHE_DIR if set)
    UV->>Tools: install files into share/gdb/python/
    UV-->>Penv: return success/failure
    Penv->>FS: log install result or warning
    end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • Use new GDB 16.2 #154: Related changes to GDB tool packaging and wiring that affect which packages the installer targets.
  • always install gdb tool #422: Modifies representation/selection of GDB tool packages; relevant to replacing hardcoded package names with GDB_TOOL_PACKAGES.
  • tl installer / new OpenOCD  #149: Updates GDB tool installation/handling logic that may interact with when/where freertos-gdb should be installed.

Poem

🐰 I hopped through build scripts at first light,
Pushed freertos-gdb into toolchain night,
Pip vined through folders, tidy and spry,
Shared python paths now ready to try,
Debugging carrots gleam — hop, pip, delight! 🥕

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the main objective of the pull request: installing a GDB debug module for Espressif platforms.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch gdb_debug
📝 Coding Plan
  • Generate coding plan for human review comments

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

Comment @coderabbitai help to get the list of available commands and usage tips.

@Jason2866
Copy link
Copy Markdown
Author

@coderabbitai full review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 12, 2026

✅ Actions performed

Full review triggered.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
builder/penv_setup.py (1)

682-685: Derive the GDB package list from shared platform metadata.

This hardcoded list duplicates the GDB discovery logic already used in platform.py. It works today, but any new *-gdb tool added there will load the Python hook without ever getting freertos-gdb installed here. Reusing a shared helper or filtering known platform packages would keep these paths in sync.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@builder/penv_setup.py` around lines 682 - 685, Replace the hardcoded
gdb_tool_packages list with the shared platform package discovery used in
platform.py so new "*-gdb" tools are picked up automatically; import and call
the existing helper in platform.py that returns platform tool/package metadata
(the same function used for GDB discovery) and filter that result for packages
that end with "-gdb" (or otherwise match the platform's GDB tool predicate),
then use that derived list where gdb_tool_packages is referenced and ensure
"freertos-gdb" is still included if required by the existing installation logic.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@builder/penv_setup.py`:
- Around line 523-524: The call to install_freertos_gdb(...) is executed too
early and should be moved so it runs after the MCU toolchain GDB packages exist;
specifically, relocate the install_freertos_gdb(platform, uv_executable,
penv_python, uv_cache_dir) invocation to run after _configure_mcu_toolchains()
completes or invoke it from the code path in platform.py that installs
tool-xtensa-esp-elf-gdb / tool-riscv32-esp-elf-gdb so the GDB packages are
present when install_freertos_gdb runs (search for the platform.py GDB-install
function or _configure_mcu_toolchains to find the correct insertion point).

---

Nitpick comments:
In `@builder/penv_setup.py`:
- Around line 682-685: Replace the hardcoded gdb_tool_packages list with the
shared platform package discovery used in platform.py so new "*-gdb" tools are
picked up automatically; import and call the existing helper in platform.py that
returns platform tool/package metadata (the same function used for GDB
discovery) and filter that result for packages that end with "-gdb" (or
otherwise match the platform's GDB tool predicate), then use that derived list
where gdb_tool_packages is referenced and ensure "freertos-gdb" is still
included if required by the existing installation logic.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14120923-f28b-430d-bff2-d224f51aa13a

📥 Commits

Reviewing files that changed from the base of the PR and between 312b566 and 6360229.

📒 Files selected for processing (2)
  • builder/penv_setup.py
  • platform.py

Comment thread builder/penv_setup.py Outdated
@Jason2866
Copy link
Copy Markdown
Author

@coderabbitai full review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 12, 2026

✅ Actions performed

Full review triggered.

@Jason2866
Copy link
Copy Markdown
Author

@coderabbitai full review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 12, 2026

✅ Actions performed

Full review triggered.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
builder/penv_setup.py (2)

700-710: Fix inconsistent indentation in subprocess.check_call arguments.

The list elements have misaligned indentation which hurts readability:

🔧 Proposed fix for consistent indentation
         try:
             subprocess.check_call([
-            uv_executable, "pip", "install", "--quiet",
-                 f"--python={penv_executable}",
-                 "--target", target_dir,
-                "freertos-gdb"],
+                uv_executable, "pip", "install", "--quiet",
+                f"--python={penv_executable}",
+                "--target", str(target_dir),
+                "freertos-gdb"
+            ],
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.STDOUT,
                 timeout=60,
                 env=uv_env,
             )
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@builder/penv_setup.py` around lines 700 - 710, The subprocess.check_call
invocation has inconsistent indentation for its argument list; fix it by
reformatting the list elements so they align consistently (e.g., each list item
on its own line indented one level inside the call), and align the keyword
arguments (stdout, stderr, timeout, env) at the same indentation level as the
list closing bracket; update the call to subprocess.check_call so uv_executable,
"pip", "install", "--quiet", f"--python={penv_executable}", "--target",
target_dir, "freertos-gdb" and the kwargs stdout=subprocess.DEVNULL,
stderr=subprocess.STDOUT, timeout=60, env=uv_env are consistently indented for
readability.

683-686: Consider centralizing GDB tool package names.

These package names are duplicated in platform.py (MCU_TOOLCHAIN_CONFIG), builder/main.py, and now here. While they currently match, a future rename would require coordinated updates across all locations.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@builder/penv_setup.py` around lines 683 - 686, gdb_tool_packages is
duplicated; replace the local list with a single shared constant and import it
where needed: create a module-level constant (e.g., GDB_TOOL_PACKAGES) in the
existing central config (where MCU_TOOLCHAIN_CONFIG is defined) and export it,
then update this file to use that constant instead of the inline
gdb_tool_packages list and update other locations (they currently reference
MCU_TOOLCHAIN_CONFIG) to import the new constant as needed; ensure the symbol
name matches across modules and remove the duplicated literal lists.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@builder/penv_setup.py`:
- Line 39: The module-level assignment has_network = has_internet_connection()
or github_actions runs before has_internet_connection is defined, causing a
NameError; move that assignment to after the has_internet_connection function
definition (i.e., place it below the has_internet_connection(...) function) so
the function exists when called, and keep the same variable name has_network and
reference to github_actions to avoid breaking callers.

---

Nitpick comments:
In `@builder/penv_setup.py`:
- Around line 700-710: The subprocess.check_call invocation has inconsistent
indentation for its argument list; fix it by reformatting the list elements so
they align consistently (e.g., each list item on its own line indented one level
inside the call), and align the keyword arguments (stdout, stderr, timeout, env)
at the same indentation level as the list closing bracket; update the call to
subprocess.check_call so uv_executable, "pip", "install", "--quiet",
f"--python={penv_executable}", "--target", target_dir, "freertos-gdb" and the
kwargs stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT, timeout=60,
env=uv_env are consistently indented for readability.
- Around line 683-686: gdb_tool_packages is duplicated; replace the local list
with a single shared constant and import it where needed: create a module-level
constant (e.g., GDB_TOOL_PACKAGES) in the existing central config (where
MCU_TOOLCHAIN_CONFIG is defined) and export it, then update this file to use
that constant instead of the inline gdb_tool_packages list and update other
locations (they currently reference MCU_TOOLCHAIN_CONFIG) to import the new
constant as needed; ensure the symbol name matches across modules and remove the
duplicated literal lists.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fd051284-5caa-4c87-9b54-e86129a8f9d8

📥 Commits

Reviewing files that changed from the base of the PR and between 312b566 and df5d198.

📒 Files selected for processing (2)
  • builder/penv_setup.py
  • platform.py

Comment thread builder/penv_setup.py Outdated
@Jason2866
Copy link
Copy Markdown
Author

@coderabbitai full review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 12, 2026

✅ Actions performed

Full review triggered.

@Jason2866 Jason2866 merged commit bd50f20 into develop Mar 12, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant