Skip to content

Remove the vendored elftools tree and the unreachable GDB source-archive path - #249

Merged
danielrmerskine merged 1 commit into
mainfrom
de/drop-vendored-elftools
Aug 13, 2026
Merged

Remove the vendored elftools tree and the unreachable GDB source-archive path#249
danielrmerskine merged 1 commit into
mainfrom
de/drop-vendored-elftools

Conversation

@danielrmerskine

@danielrmerskine danielrmerskine commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Closes #240.

What was wrong

cli/elftools/ was vendored in without its construct/lib/ subpackage. The directory is
absent from the repo itself, so all 30 modules raised ModuleNotFoundError in every
environment — pip installs and dev checkouts alike, not just the wheel:

cli/elftools/elf/elffile.py:27 -> cli/elftools/common/utils.py:12
  -> cli/elftools/construct/__init__.py:33 -> cli/elftools/construct/core.py:3
ModuleNotFoundError: No module named 'cli.elftools.construct.lib'

Four separate things kept it invisible: the tree was excluded from ruff, omitted from
coverage, had no tests, and compileall checks syntax without resolving imports. The
packaging gate's import walk was the first thing to actually try importing it.

Why deletion rather than repair

The issue offered three options. Investigating pushed the answer to its third one, harder than
expected:

  • The only consumer is unreachable. cli/commands/development/debug/gdb.py is the sole
    importer, and gdb appears in neither list_commands nor get_command of the debug group
    (cli/commands/development/debug/commands.py:474-482). There is no lager debug gdb
    command and there has not been one. The only reference anywhere is a lazy re-export in
    debug/__init__.py.
  • Repair would restore something already broken by modern toolchains. The vendored copy is
    pyelftools 0.27 with no local modifications (grep -rni lager cli/elftools/ is empty), and
    it has no DWARF5 line-program support — dwarf/structs.py still defines the DWARF≤4 file
    entry form. gdb.py compounded it by hard-coding 1-indexed file/dir entries, which DWARF5
    made 0-indexed. GCC 11+ and clang 14+ emit DWARF5 by default.
  • Nothing else needs it. pyelftools is not a declared dependency anywhere, and the box
    side deliberately hand-rolls a minimal ELF32 reader specifically to avoid pulling it in
    (box/lager/debug/da1469x_loader.py:242).

So this removes 48 files and 13,241 lines that could not run, under a command that could not
be invoked. If ELF/DWARF parsing is wanted later, the right move is pyelftools from PyPI —
recorded in cli/vendor/__init__.py so the next person doesn't re-vendor it.

Also removed

The ruff --exclude and the coverage OMIT entry for */elftools/*. Both existed only to
hide this tree from static analysis; leaving them would let a future vendored tree inherit the
same blind spot silently.

Verified

  • Reproduced the import failure directly before deleting anything.
  • Full packaging pipeline green on this branch: python -m buildtwine check (both
    artifacts PASSED) → wheel installed into a fresh venv → lager --version → import walk.
  • The import walk is the proof this is fixed: 135 modules walked, 2 failures, both covered
    by the baseline and both belonging to cli.impl.box_config and cli.impl.power.enable_disable import lager.* from the box tree #241. It was 34 failures before. The two cli.elftools.*
    and cli.commands.development.debug.gdb baseline entries are deleted here, and the baseline
    is two-sided, so a stale entry would have failed the gate.
  • Wheel contains 0 elftools entries and no gdb.py (147 entries total).
  • unit (cli): 1179 passed, 2 xfailed — matches this branch's test/COVERAGE.md exactly, so
    the deletion changed no test count. tools/check_coverage_counts.py agrees on every suite
    except unit (box), which reports 1556 (+7 skipped) here purely because 7 box tests are
    gated on /proc and flock(1) and this is macOS. Those tests are untouched by this change
    and run on Linux CI; the darwin-awareness that reports them as n/a landed in v0.36.2 and is
    not on this branch yet.
  • ruff check --select E9,F63,F7,F82 --exclude cli/vendor cli/ box/ test/ tools/ — all checks
    passed with the narrowed exclusion.

Left alone deliberately

.github/workflows/packaging.yml's header comment still lists the vendored tree among the
defects the gate's first run found. That is a statement about that run, and it stays accurate.

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.

Vendored elftools tree is missing construct/lib -- the ELF parsing path cannot import

1 participant