asmdiff 0.1.1__tar.gz → 0.1.2__tar.gz

asmdiff-0.1.2/.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.2/.gitignore

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

asmdiff-0.1.2/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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asmdiff
-Version: 0.1.1
+Version: 0.1.2
 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]] [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -105,6 +105,7 @@ 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`, search `./`, `./build`, `../`, `../build`. See [below](#borrowing-includes-from-compile_commandsjson). |
 | `-- 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 +140,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 +169,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 +180,90 @@ 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` — 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.
+- **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 search `./`, `./build`, `../`, `../build` — first hit wins — which
+covers running from a project root or from one directory below it (a
+component dir), with the database where CMake/idf.py leaves it. 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

{asmdiff-0.1.1 → asmdiff-0.1.2}/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]] [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -87,6 +87,7 @@ 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`, search `./`, `./build`, `../`, `../build`. See [below](#borrowing-includes-from-compile_commandsjson). |
 | `-- 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 +122,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 +151,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 +162,90 @@ 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` — 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.
+- **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 search `./`, `./build`, `../`, `../build` — first hit wins — which
+covers running from a project root or from one directory below it (a
+component dir), with the database where CMake/idf.py leaves it. 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

asmdiff-0.1.2/asmdiff.example.toml

@@ -0,0 +1,50 @@
+# 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
+# ./, ./build, ../, ../build at run time (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

{asmdiff-0.1.1 → asmdiff-0.1.2}/asmdiff.py

@@ -12,6 +12,7 @@ Usage:
     tools/asmdiff/asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]...
                              [--across FUNC]... [--cc 'CC FLAGS']...
                              [--target NAME]... [--config PATH]
+                             [--compile-commands [PATH]]
                              [-- EXTRA_FLAGS...]
 
 Three modes:
@@ -28,10 +29,20 @@ Compilers come from --cc strings, from named targets in an asmdiff.toml
 config file (--target NAME), from the config's `default` entry, or —
 failing all of those — plain `gcc -O3` and `clang -O3`.
 Flags after a bare `--` are appended to every compiler invocation.
+
+A config target may name a compile_commands.json (compile_commands = PATH):
+the include/define flags recorded there for the source being compiled are
+added to that target's command, so a real project source resolves its
+headers the way its own build system does (e.g. an ESP-IDF component).
+compile_commands = true in a target — or a bare --compile-commands on the
+command line — instead searches ./, ./build, ../, ../build for the
+database; a source absent from a database found that way is compiled
+without borrowed flags (with a note) rather than being an error.
 """
 import argparse
 import glob
 import hashlib
+import json
 import os
 import re
 import shlex
@@ -51,6 +62,171 @@ DEFAULT_COMPILERS = ["gcc", "clang"]
 FALLBACK_FLAGS = "-O3"
 CONFIG_NAME = "asmdiff.toml"
 
+# Preprocessor flags lifted from a compile_commands.json entry so a project
+# source compiles the way its build system compiles it: header search paths,
+# forced includes, and defines.  Everything else the entry records (the
+# compiler, -O/-std/-W flags, -c, -o OUT, the source itself) is ignored —
+# asmdiff supplies the compiler and optimisation flags from the target.
+# Path-bearing flags may be glued (-Ipath) or split (-I path); defines too
+# (-DFOO / -D FOO).  None of the path flags is a prefix of another and -I is
+# case-distinct from -i*, so a single left-to-right scan is unambiguous.
+_CC_DB_PATH_FLAGS = ("-I", "-iquote", "-isystem", "-idirafter",
+                     "-include", "-imacros", "-isysroot")
+_CC_DB_PLAIN_FLAGS = ("-D", "-U")
+_DB_CACHE = {}
+_MISS_NOTED = set()
+
+
+class Target(str):
+    """A compiler-matrix entry: the ``CC FLAGS`` command string, plus an
+    optional compile_commands.json whose per-source include/define flags are
+    appended at compile time.  Subclassing str means it prints, compares, and
+    shlex-splits as the bare command everywhere the matrix is consumed, so
+    only compile_to_asm needs to know about the extra attributes.
+
+    ``db_discovered`` marks a database that was found by searching near the
+    CWD rather than named explicitly; a source absent from a discovered
+    database is tolerated (compiled without borrowed flags, with a note),
+    where an explicit database makes that an error."""
+
+    def __new__(cls, cmd, compile_commands=None, db_discovered=False):
+        self = super().__new__(cls, cmd)
+        self.compile_commands = compile_commands
+        self.db_discovered = db_discovered
+        return self
+
+
+def _abs_against(directory, value):
+    """Resolve a path recorded in a compile_commands entry against that
+    entry's ``directory``, so a relative -I still works from asmdiff's CWD."""
+    p = Path(value)
+    if directory and not p.is_absolute():
+        p = Path(directory) / p
+    return str(p)
+
+
+def include_flags(tokens, directory):
+    """Pick header-search, forced-include, and define flags out of one
+    recorded compile command; make relative paths absolute against
+    ``directory``.  Glued and split spellings are both recognised; path
+    flags are re-emitted in split form (-I path), which every driver accepts.
+    """
+    flags = []
+    i, n = 0, len(tokens)
+    while i < n:
+        tok, extra, matched = tokens[i], 0, False
+        for f in _CC_DB_PATH_FLAGS:
+            if tok == f and i + 1 < n:                    # -I path
+                flags += [f, _abs_against(directory, tokens[i + 1])]
+                extra, matched = 1, True
+                break
+            if tok.startswith(f) and len(tok) > len(f):   # -Ipath
+                flags += [f, _abs_against(directory, tok[len(f):])]
+                matched = True
+                break
+        if not matched:
+            for f in _CC_DB_PLAIN_FLAGS:
+                if tok == f and i + 1 < n:                # -D FOO
+                    flags.append(f + tokens[i + 1])
+                    extra = 1
+                    break
+                if tok.startswith(f) and len(tok) > len(f):  # -DFOO
+                    flags.append(tok)
+                    break
+        i += 1 + extra
+    return flags
+
+
+def find_compile_commands():
+    """Locate a compile_commands.json near the current directory.
+
+    Searched in order: ./, ./build, ../, ../build — first hit wins.  This
+    covers running asmdiff from a project root or from one directory below
+    it (a component dir), with the database where CMake/idf.py leaves it.
+    Returns None when nothing is found.
+    """
+    cwd = Path.cwd()
+    for d in (cwd, cwd / "build", cwd.parent, cwd.parent / "build"):
+        candidate = d / "compile_commands.json"
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def _discovered_db(who):
+    """find_compile_commands() for a caller that opted in (compile_commands
+    = true, or a bare --compile-commands): finding nothing is then an error,
+    not a silent no-op."""
+    found = find_compile_commands()
+    if found is None:
+        sys.exit(f"error: {who}: no compile_commands.json found in "
+                 "./, ./build, ../, or ../build")
+    return found
+
+
+def load_compile_commands(path):
+    """Parse a compile_commands.json into its list of entries (cached, since
+    one database is queried once per source per compiler in the matrix)."""
+    if path in _DB_CACHE:
+        return _DB_CACHE[path]
+    try:
+        data = json.loads(Path(path).read_text())
+    except FileNotFoundError:
+        sys.exit(f"error: compile_commands.json not found: {path}")
+    except (json.JSONDecodeError, OSError) as exc:
+        sys.exit(f"error: {path}: {exc}")
+    if not isinstance(data, list):
+        sys.exit(f"error: {path}: expected a JSON array of compile entries")
+    _DB_CACHE[path] = data
+    return data
+
+
+def compile_commands_flags(db_path, source, missing_ok=False):
+    """Header/define flags for ``source`` taken from a compile_commands.json.
+
+    The entry whose ``file`` resolves to the same path as ``source`` supplies
+    its include/define flags (relative paths made absolute against the entry's
+    ``directory``).  A ``command`` string is tokenised; an ``arguments`` array
+    is used as-is.  A source absent from the database is an error — compiling
+    it would otherwise fail on the very header this feature exists to supply —
+    and the message flags a same-name entry recorded under a different path.
+    With ``missing_ok`` (auto-discovered databases) an absent source instead
+    compiles without borrowed flags, after a one-time note per (db, source).
+    """
+    entries = load_compile_commands(db_path)
+    want = Path(source).resolve()
+    name_seen = False
+    for entry in entries:
+        f = entry.get("file")
+        if not f:
+            continue
+        directory = entry.get("directory", "")
+        fp = Path(f)
+        if not fp.is_absolute():
+            fp = Path(directory) / fp
+        try:
+            same = fp.resolve() == want
+        except OSError:
+            same = False
+        if same:
+            args = entry.get("arguments")
+            tokens = (list(args) if isinstance(args, list)
+                      else shlex.split(entry.get("command", "")))
+            return include_flags(tokens, directory)
+        if Path(f).name == want.name:
+            name_seen = True
+    if missing_ok:
+        key = (db_path, str(want))
+        if key not in _MISS_NOTED:
+            _MISS_NOTED.add(key)
+            print(f"note: {source} not in {db_path}; "
+                  "compiling without its include/define flags",
+                  file=sys.stderr)
+        return []
+    hint = (f"; an entry named {want.name} exists under a different path — "
+            "pass the source as it appears in the database") if name_seen else ""
+    sys.exit(f"error: {source} not found in {db_path}{hint}")
+
 # A label at column 0 that is not a local (.L*) label starts a function.
 FUNC_LABEL = re.compile(r"^([A-Za-z_][\w$.]*):")
 # Assembler directives that carry no information worth reading.
@@ -267,26 +443,52 @@ def target_command(config, name, config_path):
     if isinstance(flags, str) or not all(isinstance(f, str) for f in flags):
         sys.exit(f"error: target [{name}]: flags must be an array of strings")
     flags = [os.path.expandvars(f) for f in flags]
-    return shlex.join([resolve_cc(cc, name), *flags])
-
-
-def build_matrix(cc_args, target_args, config, config_path):
+    db = entry.get("compile_commands")
+    discovered = False
+    if db is True:                       # opt in to CWD-based discovery
+        db, discovered = _discovered_db(f"target [{name}]"), True
+    elif db is False:
+        db = None
+    elif db is not None:
+        if not isinstance(db, str):
+            sys.exit(f"error: target [{name}]: compile_commands must be a "
+                     "path to a compile_commands.json, or true to search "
+                     "./, ./build, ../, ../build")
+        db = os.path.expandvars(os.path.expanduser(db))
+    return Target(shlex.join([resolve_cc(cc, name), *flags]), db, discovered)
+
+
+def build_matrix(cc_args, target_args, config, config_path, db_arg=None):
     """Resolve the compiler matrix.
 
     --cc strings verbatim, then --target entries, in that order.  With
     neither, the config's `default` (a target name or list of names);
     with no config or no default, plain gcc/clang at -O3.
+
+    ``db_arg`` is the --compile-commands value: a PATH applies that
+    database to every entry, True discovers one near the CWD.  A target
+    whose config names its own compile_commands keeps it.
     """
     entries = list(cc_args)
     entries += [target_command(config, name, config_path)
                 for name in target_args]
-    if entries:
-        return entries
-    default = (config or {}).get("default")
-    if default:
-        names = [default] if isinstance(default, str) else list(default)
-        return [target_command(config, name, config_path) for name in names]
-    return [f"{cc} {FALLBACK_FLAGS}" for cc in DEFAULT_COMPILERS]
+    if not entries:
+        default = (config or {}).get("default")
+        if default:
+            names = [default] if isinstance(default, str) else list(default)
+            entries = [target_command(config, name, config_path)
+                       for name in names]
+        else:
+            entries = [f"{cc} {FALLBACK_FLAGS}" for cc in DEFAULT_COMPILERS]
+    if db_arg is not None:
+        if db_arg is True:
+            db, discovered = _discovered_db("--compile-commands"), True
+        else:
+            db = os.path.expandvars(os.path.expanduser(db_arg))
+            discovered = False
+        entries = [e if getattr(e, "compile_commands", None) is not None
+                   else Target(e, db, discovered) for e in entries]
+    return entries
 
 
 def asm_output_name(cc_cmd, harness):
@@ -305,7 +507,9 @@ def asm_output_name(cc_cmd, harness):
 def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
     """Run one compiler to -S; return the asm text.
 
-    Returns None (with a warning) if the compiler is not on PATH.
+    If the matrix entry names a compile_commands.json, this source's
+    include/define flags from that database are inserted before any bare-``--``
+    flags.  Returns None (with a warning) if the compiler is not on PATH.
     Exits with the compiler's stderr on a compile failure.
     """
     argv = shlex.split(cc_cmd)
@@ -313,8 +517,14 @@ def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
         print(f"warning: {argv[0]} not found on PATH, skipping",
               file=sys.stderr)
         return None
-    out_s = Path(out_dir) / asm_output_name(cc_cmd, harness)
-    cmd = argv + list(extra_flags) + ["-S", "-o", str(out_s), str(harness)]
+    db = getattr(cc_cmd, "compile_commands", None)
+    db_flags = (compile_commands_flags(
+                    db, harness,
+                    missing_ok=getattr(cc_cmd, "db_discovered", False))
+                if db else [])
+    out_s = Path(out_dir) / asm_output_name(shlex.join(argv + db_flags), harness)
+    cmd = (argv + db_flags + list(extra_flags)
+           + ["-S", "-o", str(out_s), str(harness)])
     proc = subprocess.run(cmd, capture_output=True, text=True)
     if proc.returncode != 0:
         sys.exit(f"error: compile failed: {' '.join(cmd)}\n{proc.stderr}")
@@ -549,6 +759,12 @@ def main(argv=None):
                         help="named [table] from the config file, resolved "
                              "to a --cc entry (repeatable; appended to the "
                              "matrix after --cc entries)")
+    parser.add_argument("--compile-commands", nargs="?", const=True,
+                        default=None, metavar="PATH",
+                        help="borrow each source's include/define flags from "
+                             "a compile_commands.json; with no PATH, search "
+                             "./, ./build, ../, ../build.  A target whose "
+                             "config names its own compile_commands keeps it")
     parser.add_argument("--config", metavar="PATH",
                         help=f"config file; default search: {CONFIG_NAME} "
                              "next to SOURCE.c, in the current directory, "
@@ -564,7 +780,8 @@ def main(argv=None):
                      "use --across FUNC for two files")
     config_path = find_config(args.config, args.sources)
     config = load_config(config_path) if config_path else None
-    matrix = build_matrix(args.cc, args.target, config, config_path)
+    matrix = build_matrix(args.cc, args.target, config, config_path,
+                          args.compile_commands)
     if args.across and len(args.sources) == 1 and len(matrix) < 2:
         parser.error("--across on one file needs at least two --cc entries")
     for spec in args.pair:

{asmdiff-0.1.1 → asmdiff-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asmdiff"
-version = "0.1.1"
+version = "0.1.2"
 description = "Compare per-function assembly between paired C implementations"
 readme = "README.md"
 license = "MIT"
@@ -15,7 +15,7 @@ authors = [
 ]
 keywords = [
     "assembly", "compiler", "gcc", "clang", "disassembly", "codegen",
-    "diff", "static-analysis", "embedded", "firmware", "dsp", 
+    "diff", "static-analysis", "embedded", "firmware", "dsp",
     "xtensa", "arm", "riscv", "cli", "devtools", "loop-analysis", "cfg"
 ]
 classifiers = [

{asmdiff-0.1.1 → asmdiff-0.1.2}/test_asmdiff.py

@@ -2,6 +2,7 @@
 """Unit tests for asmdiff.py.  Run: python3 tools/asmdiff/test_asmdiff.py -v"""
 import contextlib
 import io
+import json
 import os
 import tempfile
 import unittest
@@ -346,6 +347,242 @@ class TestBuildMatrix(unittest.TestCase):
             asmdiff.build_matrix([], ["bad"], cfg, "cfg.toml")
 
 
+class TestIncludeFlags(unittest.TestCase):
+    """Lifting include/define flags out of one recorded compile command."""
+
+    def test_glued_and_split_include_paths(self):
+        toks = ["cc", "-Iinc", "-I", "inc2", "-c", "a.c"]
+        self.assertEqual(asmdiff.include_flags(toks, "/build"),
+                         ["-I", "/build/inc", "-I", "/build/inc2"])
+
+    def test_absolute_paths_left_alone(self):
+        self.assertEqual(asmdiff.include_flags(["-I/abs/inc"], "/build"),
+                         ["-I", "/abs/inc"])
+
+    def test_defines_glued_and_split(self):
+        self.assertEqual(
+            asmdiff.include_flags(["-DFOO=1", "-D", "BAR", "-UNDEBUG"], "/b"),
+            ["-DFOO=1", "-DBAR", "-UNDEBUG"])
+
+    def test_system_and_forced_include_families(self):
+        toks = ["-isystem", "sys", "-iquote", "q", "-idirafter", "d",
+                "-include", "cfg.h", "-imacros", "m.h"]
+        self.assertEqual(
+            asmdiff.include_flags(toks, "/build"),
+            ["-isystem", "/build/sys", "-iquote", "/build/q",
+             "-idirafter", "/build/d", "-include", "/build/cfg.h",
+             "-imacros", "/build/m.h"])
+
+    def test_non_include_flags_and_source_dropped(self):
+        toks = ["gcc", "-O2", "-std=c11", "-Wall", "-g", "-c", "a.c",
+                "-o", "a.o", "-Iinc"]
+        self.assertEqual(asmdiff.include_flags(toks, "/b"), ["-I", "/b/inc"])
+
+    def test_dangling_flag_at_end_ignored(self):
+        self.assertEqual(asmdiff.include_flags(["-Iinc", "-I"], "/b"),
+                         ["-I", "/b/inc"])
+
+    def test_lowercase_isystem_not_split_as_capital_I(self):
+        # -isystem must not be read as -I + "system".
+        self.assertEqual(asmdiff.include_flags(["-isystem", "/s"], ""),
+                         ["-isystem", "/s"])
+
+
+class TestCompileCommandsFlags(unittest.TestCase):
+    def _db(self, tmp, entries):
+        path = Path(tmp) / "compile_commands.json"
+        path.write_text(json.dumps(entries))
+        asmdiff._DB_CACHE.clear()
+        return str(path)
+
+    def test_matches_by_resolved_path_command_string(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            src = Path(tmp) / "src" / "foo.c"
+            src.parent.mkdir()
+            src.touch()
+            db = self._db(tmp, [{
+                "directory": tmp, "file": str(src),
+                "command": f"cc -Iinc -DX=1 -c {src} -o foo.o"}])
+            self.assertEqual(asmdiff.compile_commands_flags(db, str(src)),
+                             ["-I", f"{tmp}/inc", "-DX=1"])
+
+    def test_matches_relative_file_and_arguments_array(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            src = Path(tmp) / "foo.c"
+            src.touch()
+            db = self._db(tmp, [{
+                "directory": tmp, "file": "foo.c",
+                "arguments": ["cc", "-Iinc", "-c", "foo.c"]}])
+            self.assertEqual(asmdiff.compile_commands_flags(db, str(src)),
+                             ["-I", f"{tmp}/inc"])
+
+    def test_missing_source_errors(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp, [{"directory": tmp, "file": f"{tmp}/a.c",
+                                 "command": "cc -c a.c"}])
+            with self.assertRaises(SystemExit) as ctx:
+                asmdiff.compile_commands_flags(db, f"{tmp}/b.c")
+            self.assertIn("not found", str(ctx.exception))
+
+    def test_same_name_different_path_hint(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp, [{"directory": tmp,
+                                 "file": f"{tmp}/other/foo.c",
+                                 "command": "cc -c foo.c"}])
+            with self.assertRaises(SystemExit) as ctx:
+                asmdiff.compile_commands_flags(db, f"{tmp}/foo.c")
+            self.assertIn("different path", str(ctx.exception))
+
+    def test_bad_json_shape_errors(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cc.json"
+            path.write_text('{"not": "a list"}')
+            asmdiff._DB_CACHE.clear()
+            with self.assertRaises(SystemExit):
+                asmdiff.compile_commands_flags(str(path), "x.c")
+
+
+class TestTargetCompileCommands(unittest.TestCase):
+    def test_target_carries_expanded_db_path(self):
+        os.environ["ASMDIFF_TEST_DB"] = "/proj/build"
+        try:
+            cfg = {"t": {"cc": "gcc", "flags": ["-O2"],
+                         "compile_commands": "$ASMDIFF_TEST_DB/cc.json"}}
+            matrix = asmdiff.build_matrix([], ["t"], cfg, "c")
+            self.assertEqual(matrix, ["gcc -O2"])          # str value unchanged
+            self.assertEqual(matrix[0].compile_commands,
+                             "/proj/build/cc.json")         # attribute carried
+        finally:
+            del os.environ["ASMDIFF_TEST_DB"]
+
+    def test_compile_commands_must_be_a_string(self):
+        cfg = {"t": {"cc": "gcc", "flags": [], "compile_commands": ["x"]}}
+        with self.assertRaises(SystemExit):
+            asmdiff.build_matrix([], ["t"], cfg, "c")
+
+    def test_cc_entries_have_no_db_attribute(self):
+        matrix = asmdiff.build_matrix(["gcc -O3"], [], None, None)
+        self.assertIsNone(getattr(matrix[0], "compile_commands", None))
+
+
+@contextlib.contextmanager
+def _inside(directory):
+    """Run a block with CWD set to ``directory`` (discovery is CWD-based)."""
+    prev = os.getcwd()
+    os.chdir(directory)
+    try:
+        yield
+    finally:
+        os.chdir(prev)
+
+
+class TestFindCompileCommands(unittest.TestCase):
+    """Auto-discovery of compile_commands.json near the current directory."""
+
+    def _touch_db(self, directory):
+        directory.mkdir(parents=True, exist_ok=True)
+        (directory / "compile_commands.json").write_text("[]")
+
+    def test_search_order_cwd_build_parent_parentbuild(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            cwd = root / "sub"
+            cwd.mkdir()
+            for where, expect in [(root / "build", root / "build"),
+                                  (root, root),
+                                  (cwd / "build", cwd / "build"),
+                                  (cwd, cwd)]:
+                self._touch_db(where)
+                with _inside(cwd):
+                    self.assertEqual(asmdiff.find_compile_commands(),
+                                     str(expect / "compile_commands.json"))
+
+    def test_nothing_found_returns_none(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cwd = Path(tmp) / "a" / "b"
+            cwd.mkdir(parents=True)
+            with _inside(cwd):
+                self.assertIsNone(asmdiff.find_compile_commands())
+
+
+class TestDiscoveredCompileCommands(unittest.TestCase):
+    """compile_commands = true in a target / bare --compile-commands."""
+
+    def test_target_true_discovers_and_is_soft(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = Path(tmp) / "build" / "compile_commands.json"
+            db.parent.mkdir()
+            db.write_text("[]")
+            cfg = {"t": {"cc": "gcc", "compile_commands": True}}
+            with _inside(tmp):
+                matrix = asmdiff.build_matrix([], ["t"], cfg, "c")
+            self.assertEqual(matrix[0].compile_commands, str(db))
+            self.assertTrue(matrix[0].db_discovered)
+
+    def test_target_true_with_no_db_anywhere_errors(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cwd = Path(tmp) / "a" / "b"
+            cwd.mkdir(parents=True)
+            cfg = {"t": {"cc": "gcc", "compile_commands": True}}
+            with _inside(cwd), self.assertRaises(SystemExit) as ctx:
+                asmdiff.build_matrix([], ["t"], cfg, "c")
+            self.assertIn("compile_commands.json", str(ctx.exception))
+
+    def test_target_false_means_off(self):
+        cfg = {"t": {"cc": "gcc", "compile_commands": False}}
+        matrix = asmdiff.build_matrix([], ["t"], cfg, "c")
+        self.assertIsNone(matrix[0].compile_commands)
+
+    def test_explicit_path_stays_hard(self):
+        cfg = {"t": {"cc": "gcc", "compile_commands": "/x/cc.json"}}
+        matrix = asmdiff.build_matrix([], ["t"], cfg, "c")
+        self.assertEqual(matrix[0].compile_commands, "/x/cc.json")
+        self.assertFalse(matrix[0].db_discovered)
+
+    def test_cli_bare_flag_fills_cc_and_default_entries(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = Path(tmp) / "compile_commands.json"
+            db.write_text("[]")
+            with _inside(tmp):
+                matrix = asmdiff.build_matrix(["gcc -O3"], [], None, None,
+                                              db_arg=True)
+                fallback = asmdiff.build_matrix([], [], None, None,
+                                                db_arg=True)
+        for entry in [matrix[0]] + list(fallback):
+            self.assertEqual(entry.compile_commands, str(db))
+            self.assertTrue(entry.db_discovered)
+
+    def test_cli_path_is_explicit_and_expanded(self):
+        os.environ["ASMDIFF_TEST_DB2"] = "/proj"
+        try:
+            matrix = asmdiff.build_matrix(["gcc -O3"], [], None, None,
+                                          db_arg="$ASMDIFF_TEST_DB2/cc.json")
+        finally:
+            del os.environ["ASMDIFF_TEST_DB2"]
+        self.assertEqual(matrix[0].compile_commands, "/proj/cc.json")
+        self.assertFalse(matrix[0].db_discovered)
+
+    def test_target_own_path_beats_cli(self):
+        cfg = {"t": {"cc": "gcc", "compile_commands": "/own/cc.json"}}
+        matrix = asmdiff.build_matrix([], ["t"], cfg, "c",
+                                      db_arg="/cli/cc.json")
+        self.assertEqual(matrix[0].compile_commands, "/own/cc.json")
+
+    def test_missing_source_soft_skips_with_note(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "compile_commands.json"
+            path.write_text(json.dumps([{"directory": tmp,
+                                         "file": f"{tmp}/a.c",
+                                         "command": "cc -Iinc -c a.c"}]))
+            asmdiff._DB_CACHE.clear()
+            err = io.StringIO()
+            with contextlib.redirect_stderr(err):
+                flags = asmdiff.compile_commands_flags(
+                    str(path), f"{tmp}/b.c", missing_ok=True)
+            self.assertEqual(flags, [])
+            self.assertIn("b.c", err.getvalue())
+
+
 class TestResolveCc(unittest.TestCase):
     def test_home_and_env_vars_expand(self):
         resolved = asmdiff.resolve_cc("~/bin/mycc", "t")

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

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(python3 test_asmdiff.py)"
-    ]
-  }
-}

asmdiff-0.1.1/asmdiff.example.toml

@@ -1,36 +0,0 @@
-# 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.  Compile at the flags your project ships with — that is
-# the whole point of the tool.
-
-default = "amy-host"
-
-[amy-host]
-cc = "gcc"
-flags = [
-  "-O3", "-Wall", "-Wno-strict-aliasing", "-Wextra",
-  "-Wno-unused-parameter", "-Wpointer-arith", "-Wno-float-conversion",
-  "-Wno-missing-declarations", "-DAMY_WAVETABLE",
-  # For harnesses that #include "amy.h", point at the AMY sources:
-  # "-I/path/to/amy/src",
-]
-
-# 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.
-[s3-amy]
-cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
-flags = [
-  "-O2", "-DAMY_USE_FIXEDPOINT", "-DNDEBUG",
-  "-Wno-strict-aliasing", "-Wno-float-conversion",
-  "-mlongcalls", "-Wpointer-arith",
-]