asmdiff 0.1.1__tar.gz → 0.1.3__tar.gz

asmdiff-0.1.3/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 test_asmdiff.py)",
+      "Bash(git -C /home/fatta/esp-idf/tools/asmdiff log --oneline -5)",
+      "Bash(git -C /home/fatta/esp-idf/tools/asmdiff diff main...HEAD --stat)"
+    ]
+  }
+}

asmdiff-0.1.3/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.py[cod]

asmdiff-0.1.3/CLAUDE.md

@@ -0,0 +1,28 @@
+# asmdiff
+
+Single-file, stdlib-only Python CLI that compares per-function assembly
+between paired C implementations across a compiler matrix. Published to
+PyPI as `asmdiff` (hatchling build, see pyproject.toml).
+
+## Toolchain
+
+- Runtime: Python >= 3.8; config files (asmdiff.toml) need >= 3.11 (tomllib).
+- No third-party dependencies, in source or tests. Keep it that way.
+- Compilers invoked at runtime: whatever the user's matrix names
+  (host gcc/clang, xtensa/riscv ESP toolchains via glob patterns).
+
+## Commands
+
+- Run tests: `python3 test_asmdiff.py` (unittest; add `-v` for detail).
+- Run the tool: `python3 asmdiff.py asmdiff_example.c`.
+- Everything is safe/reversible: the tool only compiles to `-S` in a
+  temp dir and prints. No flashing, no shared infra.
+
+## Layout
+
+- `asmdiff.py` — the entire tool.
+- `test_asmdiff.py` — unit tests, one class per feature area.
+- `asmdiff.example.toml` — documented starter config; keep it generic
+  (portable gcc/clang defaults, ESP targets as commented examples).
+- README.md documents every user-visible behavior; changes to flags or
+  config keys update README, example toml, and the module docstring.

{asmdiff-0.1.1 → asmdiff-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asmdiff
-Version: 0.1.1
+Version: 0.1.3
 Summary: Compare per-function assembly between paired C implementations
 Project-URL: Homepage, https://github.com/rt-rtos/asmdiff
 Project-URL: Repository, https://github.com/rt-rtos/asmdiff
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Debuggers
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 
-# asmdiff 
+# [asmdiff](https://pypi.org/project/asmdiff/) 
 ## per-function assembly comparison for paired C implementations
 
 > asmdiff is a stdlib only command-line tool for comparing the generated assembly of individual C functions across implementations, compiler flags, compiler versions, and source revisions. It is intended for investigating compiler code generation rather than benchmarking runtime performance.
@@ -94,7 +94,7 @@ $ asmdiff.py asmdiff_example.c
 ```
 asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
            [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
-           [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [-v] [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -105,6 +105,8 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--cc 'CC FLAGS'` | One compiler invocation, command and flags in a single quoted string. Repeatable to build a matrix. |
 | `--target NAME` | A named target from the config file, resolved to a `--cc` entry. Repeatable; appended to the matrix after `--cc` entries. |
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
+| `--compile-commands [PATH]` | Borrow each source's include/define flags from a `compile_commands.json`; with no `PATH`, walk up from the CWD checking each directory and its `build/` until the repository root. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `-v`, `--verbose` | On compile failure, print the full compiler command and complete error output. Default shows only the compiler, the source, and the first error lines. |
 | `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
 
 With no `--cc` and no `--target`, the config file's top-level
@@ -139,19 +141,19 @@ each compiler+flags combination once:
 
 ```toml
 # asmdiff.toml — next to your harnesses, in CWD, or in ~/.config/
-default = "s3-amy"          # target(s) used when no --cc/--target is given
+default = "esp32s3"         # target(s) used when no --cc/--target is given
 
-[s3-amy]                     # production-like ESP32-S3 codegen
+[esp32s3]                    # production-like ESP32-S3 codegen
 cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
 flags = [
-  "-O2", "-DAMY_USE_FIXEDPOINT", "-DNDEBUG",
+  "-O2", "-DMY_FEATURE", "-DNDEBUG",
   "-Wno-strict-aliasing", "-mlongcalls",
-  "-I$HOME/project/components/amy/src",
+  "-I$HOME/project/components/dsp/include",
 ]
 
-[host-fixed]                 # same defines on host gcc
+[host]                       # same defines on host gcc
 cc = "gcc"
-flags = ["-O2", "-DAMY_USE_FIXEDPOINT", "-I$HOME/amy/src"]
+flags = ["-O2", "-DMY_FEATURE", "-I$HOME/project/components/dsp/include"]
 ```
 
 `cc` values expand `~` and `$VARS` and may be glob patterns, so a config
@@ -168,8 +170,8 @@ shapes:
 
 ```bash
 asmdiff.py h.c                                  # config default target(s)
-asmdiff.py h.c --target s3-amy --target host-fixed   # two-target matrix
-asmdiff.py h.c --across f --target s3-amy --cc 'gcc -O2'  # mix freely
+asmdiff.py h.c --target esp32s3 --target host      # two-target matrix
+asmdiff.py h.c --across f --target esp32s3 --cc 'gcc -O2'  # mix freely
 ```
 
 A config placed next to your harness files travels with them: any invocation
@@ -179,6 +181,100 @@ included `asmdiff.example.toml` is a starting point. If a flag or include
 path must vary per machine, that's what per-machine config files are for —
 nothing lives in the tool.
 
+### Borrowing includes from `compile_commands.json`
+
+A real project source rarely compiles with a handful of `-I` flags. An
+ESP-IDF component pulls in `freertos/FreeRTOS.h`, `esp_*` headers, and a
+*generated* `sdkconfig.h`, reachable only through the dozens of `-I`/`-D`
+flags the build system computes — none of which live in the source file.
+That is why `asmdiff.py component.c` fails with `freertos/FreeRTOS.h: No
+such file or directory`: not a wrong compiler (the xtensa toolchain ships
+no FreeRTOS either), just missing include paths. Transcribing them by hand
+is miserable.
+
+So don't. Any build that uses CMake or Ninja can emit a
+[`compile_commands.json`](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
+recording the exact flags for every source it builds (ESP-IDF writes one to
+`build/compile_commands.json` on every `idf.py build`). Point a target at it:
+
+```toml
+[esp32s3-idf]
+cc = "xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls"]
+compile_commands = "$HOME/myproject/build/compile_commands.json"
+
+```
+
+Now `asmdiff.py $HOME/myproject/components/dsp/biquad.c --target esp32s3-idf`
+finds that file's entry in the database and adds the include/define flags
+it recorded — `-I`, `-isystem`, `-iquote`, `-idirafter`, `-include`,
+`-imacros`, `-D`, `-U`, plus the header-environment driver flags `-specs`
+and `--sysroot` — to this target's command. Everything else the
+database records (its own compiler, `-O`/`-std`/`-W` flags, `-c`, `-o`, the
+source) is ignored: **you** own the compiler and optimisation flags via
+`cc`/`flags`; only the header environment is borrowed. That split is the
+point — you can now sweep *your* `-O`/`-m` variations over a source that
+only ever compiled one way under the build system.
+
+Details that make it robust:
+
+- **Paths are made absolute** against each entry's `directory`, so a
+  database full of build-relative `-I../include` flags still resolves when
+  asmdiff runs from anywhere.
+- **`@file` response files are expanded.** Build systems park flags in
+  them — ESP-IDF v6 hides `-specs=picolibc.specs` in
+  `build/toolchain/cflags`, and without it every libc header breaks —
+  so the flag scan reads them (nested ones too) instead of skipping the
+  token. A bare specs name is left for the compiler's own search
+  directories; a specs path resolves like any other recorded path.
+- **Per source file.** The lookup keys on the source you pass (matched by
+  resolved absolute path), so two files in an `--across`/summary run each
+  get their own recorded flags.
+- **Absent source is an error**, not a silent empty flag set — otherwise
+  you'd just hit the missing-header failure this feature exists to prevent.
+  The message flags a same-basename entry recorded under a different path.
+- **`compile_commands` expands `~` and `$VARS`.** The `==` header always
+  prints the resolved compiler command; run with `-- -v` if you want to see
+  every include path the compiler actually received.
+
+### Auto-discovering the database
+
+When you run asmdiff from inside the project anyway, the path is
+redundant. Two opt-ins skip it:
+
+```toml
+[esp32s3-idf]
+cc = "xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls"]
+compile_commands = true      # search instead of naming a path
+```
+
+```bash
+asmdiff.py biquad.c --compile-commands            # same, for any matrix
+asmdiff.py biquad.c --compile-commands path/to/compile_commands.json
+```
+
+Both walk up from the current directory, checking each level for
+`compile_commands.json` and then `build/compile_commands.json` (where
+CMake and idf.py leave it) — first hit wins. The walk stops at the
+repository root (the first directory with a `.git`), so running from any
+depth of component directory finds the project database, but an unrelated
+one further up the filesystem is never picked up. Finding nothing is an
+error: discovery is opt-in, so if you asked for it, silence would be a
+lie. It is never on by default — a target without `compile_commands` and
+no `--compile-commands` flag borrows nothing.
+
+The precedence is what you'd hope: a target that names its own
+`compile_commands` path always keeps it; `--compile-commands` (with or
+without a path) fills in every other matrix entry, including `--cc`
+strings and the built-in gcc/clang fallback.
+
+One behavioral difference: with a *discovered* database, a source that has
+no entry is compiled without borrowed flags after a one-line stderr note,
+instead of being an error. That keeps standalone harness files working
+when a `build/` directory happens to sit nearby; an explicitly named
+database still treats an absent source as the error it is.
+
 ## Whole-file summary
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to
@@ -207,6 +303,12 @@ weight, did a call appear that shouldn't have? It sums parsed function
 bodies only (no literal pools, data, or alignment), so it is not a size
 measurement, and per-function rows are where the real information is.
 
+Only labels the assembler types as functions are listed — global data
+(string constants, state structs, lookup tables) gets column-0 labels too
+but is not code. A `calls` list longer than 8 symbols is truncated to
+`..., +N more`; real firmware dispatch functions call dozens of distinct
+symbols and would otherwise make rows thousands of characters wide.
+
 ## Comparing the same function across two builds (`--across`)
 
 `--pair` needs both variants to coexist in one compilation. Real changes

{asmdiff-0.1.1 → asmdiff-0.1.3}/README.md

@@ -1,4 +1,4 @@
-# asmdiff 
+# [asmdiff](https://pypi.org/project/asmdiff/) 
 ## per-function assembly comparison for paired C implementations
 
 > asmdiff is a stdlib only command-line tool for comparing the generated assembly of individual C functions across implementations, compiler flags, compiler versions, and source revisions. It is intended for investigating compiler code generation rather than benchmarking runtime performance.
@@ -76,7 +76,7 @@ $ asmdiff.py asmdiff_example.c
 ```
 asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
            [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
-           [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [-v] [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -87,6 +87,8 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--cc 'CC FLAGS'` | One compiler invocation, command and flags in a single quoted string. Repeatable to build a matrix. |
 | `--target NAME` | A named target from the config file, resolved to a `--cc` entry. Repeatable; appended to the matrix after `--cc` entries. |
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
+| `--compile-commands [PATH]` | Borrow each source's include/define flags from a `compile_commands.json`; with no `PATH`, walk up from the CWD checking each directory and its `build/` until the repository root. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `-v`, `--verbose` | On compile failure, print the full compiler command and complete error output. Default shows only the compiler, the source, and the first error lines. |
 | `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
 
 With no `--cc` and no `--target`, the config file's top-level
@@ -121,19 +123,19 @@ each compiler+flags combination once:
 
 ```toml
 # asmdiff.toml — next to your harnesses, in CWD, or in ~/.config/
-default = "s3-amy"          # target(s) used when no --cc/--target is given
+default = "esp32s3"         # target(s) used when no --cc/--target is given
 
-[s3-amy]                     # production-like ESP32-S3 codegen
+[esp32s3]                    # production-like ESP32-S3 codegen
 cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
 flags = [
-  "-O2", "-DAMY_USE_FIXEDPOINT", "-DNDEBUG",
+  "-O2", "-DMY_FEATURE", "-DNDEBUG",
   "-Wno-strict-aliasing", "-mlongcalls",
-  "-I$HOME/project/components/amy/src",
+  "-I$HOME/project/components/dsp/include",
 ]
 
-[host-fixed]                 # same defines on host gcc
+[host]                       # same defines on host gcc
 cc = "gcc"
-flags = ["-O2", "-DAMY_USE_FIXEDPOINT", "-I$HOME/amy/src"]
+flags = ["-O2", "-DMY_FEATURE", "-I$HOME/project/components/dsp/include"]
 ```
 
 `cc` values expand `~` and `$VARS` and may be glob patterns, so a config
@@ -150,8 +152,8 @@ shapes:
 
 ```bash
 asmdiff.py h.c                                  # config default target(s)
-asmdiff.py h.c --target s3-amy --target host-fixed   # two-target matrix
-asmdiff.py h.c --across f --target s3-amy --cc 'gcc -O2'  # mix freely
+asmdiff.py h.c --target esp32s3 --target host      # two-target matrix
+asmdiff.py h.c --across f --target esp32s3 --cc 'gcc -O2'  # mix freely
 ```
 
 A config placed next to your harness files travels with them: any invocation
@@ -161,6 +163,100 @@ included `asmdiff.example.toml` is a starting point. If a flag or include
 path must vary per machine, that's what per-machine config files are for —
 nothing lives in the tool.
 
+### Borrowing includes from `compile_commands.json`
+
+A real project source rarely compiles with a handful of `-I` flags. An
+ESP-IDF component pulls in `freertos/FreeRTOS.h`, `esp_*` headers, and a
+*generated* `sdkconfig.h`, reachable only through the dozens of `-I`/`-D`
+flags the build system computes — none of which live in the source file.
+That is why `asmdiff.py component.c` fails with `freertos/FreeRTOS.h: No
+such file or directory`: not a wrong compiler (the xtensa toolchain ships
+no FreeRTOS either), just missing include paths. Transcribing them by hand
+is miserable.
+
+So don't. Any build that uses CMake or Ninja can emit a
+[`compile_commands.json`](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
+recording the exact flags for every source it builds (ESP-IDF writes one to
+`build/compile_commands.json` on every `idf.py build`). Point a target at it:
+
+```toml
+[esp32s3-idf]
+cc = "xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls"]
+compile_commands = "$HOME/myproject/build/compile_commands.json"
+
+```
+
+Now `asmdiff.py $HOME/myproject/components/dsp/biquad.c --target esp32s3-idf`
+finds that file's entry in the database and adds the include/define flags
+it recorded — `-I`, `-isystem`, `-iquote`, `-idirafter`, `-include`,
+`-imacros`, `-D`, `-U`, plus the header-environment driver flags `-specs`
+and `--sysroot` — to this target's command. Everything else the
+database records (its own compiler, `-O`/`-std`/`-W` flags, `-c`, `-o`, the
+source) is ignored: **you** own the compiler and optimisation flags via
+`cc`/`flags`; only the header environment is borrowed. That split is the
+point — you can now sweep *your* `-O`/`-m` variations over a source that
+only ever compiled one way under the build system.
+
+Details that make it robust:
+
+- **Paths are made absolute** against each entry's `directory`, so a
+  database full of build-relative `-I../include` flags still resolves when
+  asmdiff runs from anywhere.
+- **`@file` response files are expanded.** Build systems park flags in
+  them — ESP-IDF v6 hides `-specs=picolibc.specs` in
+  `build/toolchain/cflags`, and without it every libc header breaks —
+  so the flag scan reads them (nested ones too) instead of skipping the
+  token. A bare specs name is left for the compiler's own search
+  directories; a specs path resolves like any other recorded path.
+- **Per source file.** The lookup keys on the source you pass (matched by
+  resolved absolute path), so two files in an `--across`/summary run each
+  get their own recorded flags.
+- **Absent source is an error**, not a silent empty flag set — otherwise
+  you'd just hit the missing-header failure this feature exists to prevent.
+  The message flags a same-basename entry recorded under a different path.
+- **`compile_commands` expands `~` and `$VARS`.** The `==` header always
+  prints the resolved compiler command; run with `-- -v` if you want to see
+  every include path the compiler actually received.
+
+### Auto-discovering the database
+
+When you run asmdiff from inside the project anyway, the path is
+redundant. Two opt-ins skip it:
+
+```toml
+[esp32s3-idf]
+cc = "xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls"]
+compile_commands = true      # search instead of naming a path
+```
+
+```bash
+asmdiff.py biquad.c --compile-commands            # same, for any matrix
+asmdiff.py biquad.c --compile-commands path/to/compile_commands.json
+```
+
+Both walk up from the current directory, checking each level for
+`compile_commands.json` and then `build/compile_commands.json` (where
+CMake and idf.py leave it) — first hit wins. The walk stops at the
+repository root (the first directory with a `.git`), so running from any
+depth of component directory finds the project database, but an unrelated
+one further up the filesystem is never picked up. Finding nothing is an
+error: discovery is opt-in, so if you asked for it, silence would be a
+lie. It is never on by default — a target without `compile_commands` and
+no `--compile-commands` flag borrows nothing.
+
+The precedence is what you'd hope: a target that names its own
+`compile_commands` path always keeps it; `--compile-commands` (with or
+without a path) fills in every other matrix entry, including `--cc`
+strings and the built-in gcc/clang fallback.
+
+One behavioral difference: with a *discovered* database, a source that has
+no entry is compiled without borrowed flags after a one-line stderr note,
+instead of being an error. That keeps standalone harness files working
+when a `build/` directory happens to sit nearby; an explicitly named
+database still treats an absent source as the error it is.
+
 ## Whole-file summary
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to
@@ -189,6 +285,12 @@ weight, did a call appear that shouldn't have? It sums parsed function
 bodies only (no literal pools, data, or alignment), so it is not a size
 measurement, and per-function rows are where the real information is.
 
+Only labels the assembler types as functions are listed — global data
+(string constants, state structs, lookup tables) gets column-0 labels too
+but is not code. A `calls` list longer than 8 symbols is truncated to
+`..., +N more`; real firmware dispatch functions call dozens of distinct
+symbols and would otherwise make rows thousands of characters wide.
+
 ## Comparing the same function across two builds (`--across`)
 
 `--pair` needs both variants to coexist in one compilation. Real changes

asmdiff-0.1.3/asmdiff.example.toml

@@ -0,0 +1,51 @@
+# asmdiff config — named compiler+flags targets.
+#
+# Copy to one of the locations asmdiff searches (first hit wins):
+#   1. the path given with --config
+#   2. asmdiff.toml next to the SOURCE.c being compiled
+#   3. asmdiff.toml in the current directory
+#   4. ~/.config/asmdiff.toml
+#
+# Each [table] is a target usable as `--target NAME`; the optional
+# top-level `default` names the target(s) used when no --cc/--target
+# is given (a list runs several: default = ["gcc", "clang"]).
+# Compile at the flags your project ships with — that is the whole
+# point of the tool.
+
+default = "gcc"
+
+[gcc]
+cc = "gcc"
+flags = [
+  "-O3", "-Wall", "-Wextra",
+  # Project-specific include paths and defines go here:
+  # "-I/path/to/project/src", "-DMY_FEATURE",
+]
+
+[clang]
+cc = "clang"
+flags = ["-O3", "-Wall", "-Wextra"]
+
+# cc values may use ~, $VARS, and glob patterns.  A glob that matches
+# several installed toolchains resolves to the highest version-sorted
+# one (announced on stderr); pin the exact esp-NN directory instead if
+# reproducibility across sessions matters more than convenience.
+[esp32s3]
+cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls", "-DNDEBUG"]
+
+# A project source that pulls in framework headers (ESP-IDF's freertos/*,
+# esp_*, a generated sdkconfig.h, ...) needs the dozens of -I/-D flags its
+# build system passes.  Point `compile_commands` at the database that build
+# emits (idf.py leaves build/compile_commands.json), and asmdiff copies the
+# include/define flags recorded there for the file being compiled — so you
+# never transcribe include paths by hand.  The compiler and -O/-m flags
+# still come from cc/flags; only the header environment is borrowed.
+# A path expands ~ and $VARS; `compile_commands = true` instead searches
+# at run time: each directory from the CWD up to the repository root,
+# and its build/ subdirectory (a source missing from a database found
+# that way is compiled without borrowed flags, with a note).
+[esp32s3-idf]
+cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
+flags = ["-O2", "-mlongcalls"]
+compile_commands = true