feat(parser): macro expansion, conditionals and include splicing with -I

Assisted-by: GLM 5.3 Flash
2026-09-20 14:25:47 +02:00
parent 0629f5e2df
commit ad82aac663
14 changed files with 1446 additions and 26 deletions
@@ -37,7 +37,7 @@ import (
 // construction and are excluded from the diff; the other architectures list
 // their conditional branches outright.
 func cmdAuditInstructions(args []string) error {
-	fs := newCommand("audit-instructions", "gasm audit-instructions [--corpus [dir]] [amd64|arm64|riscv64|loong64]", `
+	fs := newCommand("audit-instructions", "gasm audit-instructions [--corpus [dir]] [-I dir] [amd64|arm64|riscv64|loong64]", `
 Compare the gasm encoder for the given architecture (default amd64) against
 go tool asm and print the diff: superset encodings (gasm-only, shippable via
 gasm asm --format goobj) and known-but-unencodable names (the backlog).  The
@@ -57,11 +57,13 @@ per-architecture pass rates and the most common failure reasons, which drive
 the encodability backlog by frequency rather than by table order.
 `)
 	corpus := fs.Bool("corpus", false, "assemble a corpus of .s files and report pass rates and failure reasons")
+	var dirs includeDirs
+	fs.Var(&dirs, "I", "directory to search for #include files (may be repeated)")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
 	if *corpus {
-		return cmdAuditCorpus(fs.Args())
+		return cmdAuditCorpus(fs.Args(), dirs)
 	}
 	archName := "amd64"
 	switch n := len(fs.Args()); {
@@ -395,8 +397,11 @@ func (t *corpusTally) fail(path, reason string) {
 	}
 }

-// cmdAuditCorpus implements audit-instructions --corpus.
-func cmdAuditCorpus(args []string) error {
+// cmdAuditCorpus implements audit-instructions --corpus.  The include
+// directories carry #include resolution over a corpus whose files refer to
+// headers such as GOROOT/pkg/include, the same -I a toolchain comparison
+// needs.
+func cmdAuditCorpus(args []string, dirs includeDirs) error {
 	if len(args) > 1 {
 		return &usageError{fmt.Errorf("audit-instructions --corpus takes at most one directory argument")}
 	}
@@ -410,7 +415,25 @@ func cmdAuditCorpus(args []string) error {
 		}
 		root = filepath.Join(strings.TrimSpace(string(out)), "src")
 	}
-	stats, err := runCorpusAudit(root)
+	// The toolchain's shipped headers (funcdata.h and friends) define the
+	// macros GOROOT files include; a corpus audit measures those files, so
+	// the header directory joins the search path automatically.  go_asm.h
+	// is compiler-generated per package and stays unresolvable on purpose.
+	if out, err := exec.Command("go", "env", "GOROOT").Output(); err == nil {
+		pkgInclude := filepath.Join(strings.TrimSpace(string(out)), "pkg", "include")
+		if fi, err := os.Stat(pkgInclude); err == nil && fi.IsDir() {
+			seen := false
+			for _, d := range dirs {
+				if d == pkgInclude {
+					seen = true
+				}
+			}
+			if !seen {
+				dirs = append(dirs, pkgInclude)
+			}
+		}
+	}
+	stats, err := runCorpusAudit(root, dirs)
 	if err != nil {
 		return err
 	}
@@ -454,7 +477,7 @@ func otherPortFile(path string) bool {
 	return false
 }

-func runCorpusAudit(root string) (*corpusStats, error) {
+func runCorpusAudit(root string, dirs includeDirs) (*corpusStats, error) {
 	files, err := asmFiles(root)
 	if err != nil {
 		return nil, err
@@ -479,7 +502,7 @@ func runCorpusAudit(root string) (*corpusStats, error) {
 		if err != nil {
 			return nil, err
 		}
-		f, errs := parser.Parse(path, src)
+		f, errs := parser.ParseWithOptions(path, src, parser.Options{Expand: true, IncludeDirs: dirs})

 		var wanted []int // indexes into targets
 		if a := arch.FromFilename(path); a != arch.Unknown {
@@ -240,6 +240,16 @@ func readSource(path string) (string, error) {
 	return string(b), err
 }

+// includeDirs collects repeatable -I flags: the directories searched for
+// #include files during macro expansion and include splicing.
+type includeDirs []string
+
+func (d *includeDirs) String() string { return strings.Join(*d, ",") }
+func (d *includeDirs) Set(v string) error {
+	*d = append(*d, v)
+	return nil
+}
+
 func cmdTokens(args []string) int {
 	fs := newCommand("tokens", "gasm tokens <file>", `
 Print the lexical token stream of FILE: position, token kind and text, one
@@ -476,7 +486,7 @@ hover, document symbols, diagnostics and semantic-token highlighting.
 }

 func cmdAsm(args []string) int {
-	fs := newCommand("asm", "gasm asm [--format raw|elf|goobj] [-p pkg] [-GOARCH arch] [-o out] <file>", `
+	fs := newCommand("asm", "gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-o out] <file>", `
 	Assemble FILE without the Go toolchain: every TEXT function is encoded to
 	machine code and printed as a hex dump.  Supported architectures: amd64
 	(including VEX/AVX2 and EVEX/AVX-512), arm64 (AArch64 integer, FP,
@@ -498,9 +508,11 @@ and the format version from go version).
 	format := fs.String("format", "raw", "output format: raw (concatenated image), elf or goobj (Go object)")
 	pkg := fs.String("p", "", "package path for --format goobj (qualifies the exported symbols)")
 	archName := fs.String("GOARCH", "", "target architecture: amd64, arm64, riscv64 or loong64 (overrides the file-name suffix)")
+	var dirs includeDirs
+	fs.Var(&dirs, "I", "directory to search for #include files (may be repeated)")
 	fs.Parse(args)
 	if fs.NArg() != 1 {
-		fmt.Fprintln(os.Stderr, "usage: gasm asm [--format raw|elf|goobj] [-p pkg] [-GOARCH arch] [-o out] <file>")
+		fmt.Fprintln(os.Stderr, "usage: gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-o out] <file>")
 		return 2
 	}
 	// The format is validated before anything else, so a bogus value exits 2
@@ -526,7 +538,7 @@ and the format version from go version).
 		fmt.Fprintln(os.Stderr, "gasm:", err)
 		return 1
 	}
-	f, errs := parser.Parse(path, src)
+	f, errs := parser.ParseWithOptions(path, src, parser.Options{Expand: true, IncludeDirs: dirs})
 	for _, e := range errs {
 		fmt.Fprintf(os.Stderr, "%s: %v\n", path, e)
 	}
@@ -634,7 +646,7 @@ and the format version from go version).

 // cmdDiff compares the machine code of two assembly files.
 func cmdDiff(args []string) int {
-	set := newCommand("diff", "gasm diff [-GOARCH arch] <file1.s> <file2.s>", `
+	set := newCommand("diff", "gasm diff [-GOARCH arch] [-I dir] <file1.s> <file2.s>", `
 Compare the machine code produced by assembling two files.
 Shows which functions differ and the byte-level differences.
 Useful for verifying that two implementations produce identical code,
@@ -645,9 +657,11 @@ e.g. --map wideCopyAVX2=wideCopyAVX512 pairs the two regardless of suffix.
 `)
 	mapSpec := set.String("map", "", "comma-separated old=new pairs to match functions with different names")
 	archName := set.String("GOARCH", "", "target architecture for both files: amd64, arm64, riscv64 or loong64")
+	var dirs includeDirs
+	set.Var(&dirs, "I", "directory to search for #include files (may be repeated)")
 	set.Parse(args)
 	if set.NArg() != 2 {
-		fmt.Fprintln(os.Stderr, "usage: gasm diff [-GOARCH arch] <file1.s> <file2.s>")
+		fmt.Fprintln(os.Stderr, "usage: gasm diff [-GOARCH arch] [-I dir] <file1.s> <file2.s>")
 		return 2
 	}
 	path1, path2 := set.Arg(0), set.Arg(1)
@@ -675,12 +689,12 @@ e.g. --map wideCopyAVX2=wideCopyAVX512 pairs the two regardless of suffix.
 	}

 	// Assemble both files.
-	img1, err := assemblePath(path1, forced)
+	img1, err := assemblePath(path1, forced, dirs)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "gasm diff: %s: %v\n", path1, err)
 		return 1
 	}
-	img2, err := assemblePath(path2, forced)
+	img2, err := assemblePath(path2, forced, dirs)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "gasm diff: %s: %v\n", path2, err)
 		return 1
@@ -755,14 +769,15 @@ func assembleFile(targetArch arch.Arch, f *ast.File) (*asm.Image, error) {
 	}
 }

-// assemblePath reads, parses and assembles a file (used by cmdDiff).  A
-// non-Unknown forced architecture overrides the file-name suffix.
-func assemblePath(path string, forced arch.Arch) (*asm.Image, error) {
+// assemblePath reads, preprocesses, parses and assembles a file (used by
+// cmdDiff).  A non-Unknown forced architecture overrides the file-name
+// suffix.
+func assemblePath(path string, forced arch.Arch, dirs includeDirs) (*asm.Image, error) {
 	src, err := readSource(path)
 	if err != nil {
 		return nil, err
 	}
-	f, errs := parser.Parse(path, src)
+	f, errs := parser.ParseWithOptions(path, src, parser.Options{Expand: true, IncludeDirs: dirs})
 	for _, e := range errs {
 		fmt.Fprintf(os.Stderr, "%s: %v\n", path, e)
 	}
@@ -403,7 +403,7 @@ func TestRunCorpusAudit(t *testing.T) {
 	write("generic.s", "#include \"textflag.h\"\nTEXT ·g(SB), NOSPLIT, $0-0\n\tRET\n")
 	write("broken.s", "#include \"textflag.h\"\nTEXT ·b(SB), NOSPLIT, $0-0\n\tJMP nowhere\n\tRET\n")

-	stats, err := runCorpusAudit(dir)
+	stats, err := runCorpusAudit(dir, nil)
 	if err != nil {
 		t.Fatalf("runCorpusAudit: %v", err)
 	}
@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeTree writes a directory of files and returns its root.
+func writeTree(t *testing.T, files map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, content := range files {
+		path := filepath.Join(dir, name)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+// TestAsmMacroAndIncludeEndToEnd drives `gasm asm` over a source with an
+// in-file parameterised macro and an include resolved through -I, and checks
+// the assembled bytes came from the expansion (the loop body counts six
+// increments, two per expanded iteration).
+func TestAsmMacroAndIncludeEndToEnd(t *testing.T) {
+	if testing.Short() {
+		t.Skip("runs the assembler end to end")
+	}
+	dir := writeTree(t, map[string]string{
+		"inc/consts.h": "#define NITER 3\n",
+		"main_amd64.s": "#include \"textflag.h\"\n" +
+			"#include \"consts.h\"\n" +
+			"#define STEP(r) ADDQ $1, r; ADDQ $1, r\n" +
+			"TEXT ·f(SB), NOSPLIT, $0-8\n" +
+			"\tXORQ AX, AX\n" +
+			"\tMOVQ $NITER, CX\n" +
+			"loop:\n" +
+			"\tSTEP(AX)\n" +
+			"\tDECQ CX\n" +
+			"\tJNZ loop\n" +
+			"\tMOVQ AX, ret+0(FP)\n" +
+			"\tRET\n",
+	})
+	stdout, stderr, code := capture(func() int {
+		return cmdAsm([]string{"-I", filepath.Join(dir, "inc"), "-GOARCH", "amd64", filepath.Join(dir, "main_amd64.s")})
+	})
+	if code != 0 {
+		t.Fatalf("gasm asm exited %d: %s%s", code, stdout, stderr)
+	}
+	// The macro expanded to two ADDQ $1 encodings in the static body; the
+	// iteration count lives in the runtime loop.
+	if n := strings.Count(stdout, "83 c0 01"); n != 2 {
+		t.Errorf("found %d ADDQ $1 encodings in the image, want 2:\n%s", n, stdout)
+	}
+}
+
+// TestAsmIncludeResolutionOrder pins the -I search order end to end: the
+// including file's directory wins over the -I directories.
+func TestAsmIncludeResolutionOrder(t *testing.T) {
+	if testing.Short() {
+		t.Skip("runs the assembler end to end")
+	}
+	dir := writeTree(t, map[string]string{
+		"src/main_amd64.s": "#include \"textflag.h\"\n" +
+			"#include \"vals.h\"\n" +
+			"TEXT ·f(SB), NOSPLIT, $0\n" +
+			"\tMOVQ $VAL, AX\n" +
+			"\tRET\n",
+		"src/vals.h":   "#define VAL 1\n",
+		"late/vals.h":  "#define VAL 2\n",
+		"early/vals.h": "#define VAL 3\n",
+	})
+	stdout, stderr, code := capture(func() int {
+		return cmdAsm([]string{"-I", filepath.Join(dir, "early"), "-I", filepath.Join(dir, "late"),
+			"-GOARCH", "amd64", filepath.Join(dir, "src", "main_amd64.s")})
+	})
+	if code != 0 {
+		t.Fatalf("gasm asm exited %d: %s%s", code, stdout, stderr)
+	}
+	// VAL came from src/vals.h, not from either -I directory: the image
+	// loads the immediate 1.
+	if !strings.Contains(stdout, "b8 01 00 00 00") {
+		t.Errorf("expected the source-directory VAL (immediate 1) in:\n%s", stdout)
+	}
+}
+
+// TestAsmMissingIncludeIsAnError pins the diagnostic for an include that
+// resolves nowhere on the assembly path.
+func TestAsmMissingIncludeIsAnError(t *testing.T) {
+	if testing.Short() {
+		t.Skip("runs the assembler end to end")
+	}
+	path := writeTemp(t, "main_amd64.s", "#include \"textflag.h\"\n#include \"nothere.h\"\nTEXT ·f(SB), NOSPLIT, $0\n\tRET\n")
+	_, stderr, code := capture(func() int { return cmdAsm([]string{"-GOARCH", "amd64", path}) })
+	if code == 0 {
+		t.Fatal("gasm asm accepted a file whose include resolves nowhere")
+	}
+	if !strings.Contains(stderr, `#include "nothere.h"`) {
+		t.Errorf("stderr does not name the failing include: %s", stderr)
+	}
+}