How jonlundberg/loadwhat works
This is a single-binary Rust CLI tool for Windows x64 that diagnoses DLL loading failures by:
• Running a target EXE under Win32 debugging APIs (live diagnosis), optionally enabling loader-snaps to infer handled LoadLibrary* failures from debug strings.
• Parsing PE imports offline (static analysis) and doing a recursive missing-dependency walk (transitive missing detection).
File tree reading: map directories/files to architectural components
Top-level signals:
• src/ = core product code (Rust CLI).
• tests/fixtures/msvc/ = C++/MSVC-built executables/DLLs used to reproduce loader scenarios.
• tests/harness/ = custom Rust harness to run the CLI against fixtures and assert token output.
• xtask/ = dev tooling (build/test orchestration tasks).
• src/main.rs — entrypoint wiring
• src/cli.rs — argument parsing, subcommands (run, imports), flags (--trace, --loader-snaps, etc.)
• src/debug_run.rs — live “run under debugger” logic; phase/timeline tokens
• src/win.rs — Win32 API bindings/wrappers + OS/version/build detection utilities
• src/loader_snaps.rs — loader-snaps enabling + heuristics to infer dynamic load failures from debug strings
• src/pe.rs — PE parsing for imports (static analysis)
• src/search.rs — DLL search-order/path tracing and related tokens (SEARCH_ORDER, SEARCH_PATH)
• src/emit.rs — tokenized line emitter (TOKEN key=value ...) for summary/trace/verbose modes
README-derived architecture/behavior you must capture
From the README/spec:
• Two primary commands:
• loadwhat run <exe>: live run with debugging; emits summary or trace; Phase B does direct import diagnosis and a recursive missing walk (always on).
• loadwhat imports <exe_or_dll>: offline scan; includes recursive missing-dependency walk.
• Loader-snaps:
• Best-effort enabling via PEB->NtGlobalFlag with x64 offset chosen based on OS build detection.
• Heuristic selection rules when multiple candidates appear.
User/Inputs
• User invokes loadwhat with args
• Inputs: target EXE/DLL path, optional --cwd, --timeout-ms, flags (--trace, -v, --loader-snaps), target args after --
CLI/Orchestration Layer
• main.rs (entry)
• cli.rs (subcommand routing + option normalization, e.g., --verbose implies --trace)
Diagnosis Engines (core)
• Live Debug Runner (debug_run.rs)
• interacts with Win32 Debug APIs (win.rs)
• optionally uses Loader-snaps Inference (loader_snaps.rs)
• produces events: module load, debug strings, first break, exit status
• PE Import Scanner (pe.rs)
• reads PE structures/import tables from disk
• feeds into missing-dependency recursion
Search Analysis (search.rs) as a supporting component used by both engines to:
• “how the loader searched” (search order, expanded paths)
• enrich missing diagnosis with context
Output/Contract Layer
• Token Emitter (emit.rs)
• formats and prints TOKEN key=value ...
• supports modes: summary vs trace vs verbose
• emits families: STATIC_*, DYNAMIC_MISSING, SEARCH_*, RUN_*, SUMMARY, etc.
“Windows OS subsystems” explicitly as external dependencies
• Windows Loader (LoadLibrary behavior, search order)
• Win32 Debugging APIs (DebugActiveProcess / WaitForDebugEvent / output debug strings / module load notifications)
• PEB/NtGlobalFlag (for loader-snaps enabling)
• Filesystem (reading EXE/DLLs, current working directory)
This is a major accuracy driver: the “system” is essentially “loadwhat + Windows internals”.
cli.rs → debug_run.rs (RunConfig: exe path, cwd, timeout, mode flags)
3. debug_run.rs ↔ win.rs (debug session + OS build detection; process creation/attach; event loop)
4. (optional) debug_run.rs → loader_snaps.rs → win.rs (enable loader-snaps via PEB flag)
5. win.rs → debug_run.rs (events: module load, debug strings, exceptions/first break, exit)
6. debug_run.rs → pe.rs (Phase B: direct import diagnosis for main module and/or observed modules)
emit.rs → stdout (greppable lines)
• If --loader-snaps enabled: parse debug strings → infer candidates → apply selection rules → emit DYNAMIC_MISSING
• If mode is summary: emit one-line diagnosis (STATIC_MISSING/STATIC_BAD_IMAGE/DYNAMIC_MISSING/SUCCESS)
• If trace/verbose: emit expanded tokens (SEARCH_*, RUN_*, counters in SUMMARY)
pe.rs ↔ filesystem (read PE)
4. pe.rs → search.rs (resolve candidates, emit SEARCH_ORDER/PATH if in trace-like mode—if supported)
5. pe.rs → recursion walker (likely in pe.rs or a helper) → emits STATIC_MISSING with via=... depth=...
Architectural patterns to explicitly label
• Pipeline / staged diagnosis:
• Stage A: runtime debug event capture
• Stage B: static import + recursive missing walk (always on for run)
• Separation of concerns:
• OS bindings (win.rs)
• domain heuristics (loader_snaps.rs, search.rs)
• parsing (pe.rs)
• presentation/contract (emit.rs)
• Contract-first output: tokens are the interface; tests assert them.
Tech/framework/library callouts (only the significant ones)
• Rust CLI binary (Cargo)
• Windows x64 only
• Win32 Debug APIs + PEB/NtGlobalFlag manipulation
• PE (Portable Executable) parsing
Diagramming conventions to use (make it unambiguous)
Include:
• Clear labels: use module names (e.g., debug_run.rs) and responsibility (e.g., “Debug event loop”)
• Rectangles for internal modules