Refactor snapshot updating/checking scripts

- Adds .session.mk generation for consistent
  makefile execution behavior.
- Refine document about snapshot test

Co-authored-by: Meng-Hung Chen <[email protected]>

.github/workflows/main.yml

@@ -8,6 +8,7 @@ jobs:
     strategy:
       matrix:
         compiler: [gcc-12, clang]
+        architecture: [arm, riscv]
     steps:
       - name: checkout code
         uses: actions/checkout@v4
@@ -19,11 +20,8 @@ jobs:
           sudo apt-get install -q -y graphviz jq
           sudo apt-get install -q -y qemu-user
           sudo apt-get install -q -y build-essential
-          make clean config
-          make check-snapshots || exit 1
-          make distclean config ARCH=arm
-          make check || exit 1
-          make distclean config ARCH=riscv
+          make distclean config ARCH=${{ matrix.architecture }}
+          make check-snapshot || exit 1
           make check || exit 1
 
   host-arm:

.gitignore

@@ -7,3 +7,4 @@ a.out
 *.dot
 config
 src/codegen.c
+.session.mk

Makefile

@@ -10,16 +10,20 @@ CFLAGS := -O -g \
 	-Wno-format \
 	-Wno-format-pedantic
 
+BUILD_SESSION := .session.mk
+
 include mk/common.mk
 include mk/arm.mk
 include mk/riscv.mk
+-include $(BUILD_SESSION)
 
 STAGE0 := shecc
 STAGE1 := shecc-stage1.elf
 STAGE2 := shecc-stage2.elf
 
 OUT ?= out
-ARCH ?= arm
+ARCHS = arm riscv
+ARCH ?= $(firstword $(ARCHS))
 SRCDIR := $(shell find src -type d)
 LIBDIR := $(shell find lib -type d)
 
@@ -28,11 +32,11 @@ OBJS := $(SRCS:%.c=$(OUT)/%.o)
 deps := $(OBJS:%.o=%.o.d)
 TESTS := $(wildcard tests/*.c)
 TESTBINS := $(TESTS:%.c=$(OUT)/%.elf)
-SNAPSHOTS := $(patsubst tests/%.c, tests/snapshots/%.json, $(TESTS))
+SNAPSHOTS := $(foreach SNAPSHOT_ARCH,$(ARCHS), $(patsubst tests/%.c, tests/snapshots/%-$(SNAPSHOT_ARCH).json, $(TESTS)))
 
 all: config bootstrap
 
-ifeq (,$(filter $(ARCH),arm riscv))
+ifeq (,$(filter $(ARCH),$(ARCHS)))
 $(error Support ARM and RISC-V only. Select the target with "ARCH=arm" or "ARCH=riscv")
 endif
 
@@ -45,6 +49,7 @@ config:
 	$(Q)ln -s $(PWD)/$(SRCDIR)/$(ARCH)-codegen.c $(SRCDIR)/codegen.c
 	$(call $(ARCH)-specific-defs) > $@
 	$(VECHO) "Target machine code switch to %s\n" $(ARCH)
+	$(Q)$(MAKE) $(BUILD_SESSION) --silent
 
 $(OUT)/tests/%.elf: tests/%.c $(OUT)/$(STAGE0)
 	$(VECHO) "  SHECC\t$@\n"
@@ -63,8 +68,24 @@ check-stage2: $(OUT)/$(STAGE2) $(TESTBINS) tests/driver.sh
 	tests/driver.sh 2
 
 check-snapshots: $(OUT)/$(STAGE0) $(SNAPSHOTS) tests/check-snapshots.sh
-	$(VECHO) "  TEST SNAPSHOTS\n"
-	tests/check-snapshots.sh
+	$(Q)$(foreach SNAPSHOT_ARCH, $(ARCHS), $(MAKE) distclean config check-snapshot ARCH=$(SNAPSHOT_ARCH) --silent;)
+	$(VECHO) "Switching backend back to %s\n" $(ARCH)
+	$(Q)$(MAKE) distclean config ARCH=$(ARCH) --silent
+
+check-snapshot: $(OUT)/$(STAGE0) tests/check-snapshots.sh
+	$(VECHO) "Checking snapshot for %s\n" $(ARCH)
+	tests/check-snapshots.sh $(ARCH)
+	$(VECHO) "  OK\n"
+
+update-snapshots: tests/update-snapshots.sh
+	$(Q)$(foreach SNAPSHOT_ARCH, $(ARCHS), $(MAKE) distclean config update-snapshot ARCH=$(SNAPSHOT_ARCH) --silent;)
+	$(VECHO) "Switching backend back to %s\n" $(ARCH)
+	$(Q)$(MAKE) distclean config ARCH=$(ARCH) --silent
+
+update-snapshot: $(OUT)/$(STAGE0) tests/update-snapshots.sh
+	$(VECHO) "Updating snapshot for %s\n" $(ARCH)
+	tests/update-snapshots.sh $(ARCH)
+	$(VECHO) "  OK\n"
 
 $(OUT)/%.o: %.c
 	$(VECHO) "  CC\t$@\n"
@@ -98,6 +119,9 @@ bootstrap: $(OUT)/$(STAGE2)
 	echo "Unable to bootstrap. Aborting"; false; \
 	fi
 
+$(BUILD_SESSION):
+	$(PRINTF) "ARCH=$(ARCH)" > $@
+
 .PHONY: clean
 clean:
 	-$(RM) $(OUT)/$(STAGE0) $(OUT)/$(STAGE1) $(OUT)/$(STAGE2)
@@ -107,6 +131,6 @@ clean:
 	-$(RM) $(OUT)/libc.inc
 
 distclean: clean
-	-$(RM) $(OUT)/inliner $(OUT)/target $(SRCDIR)/codegen.c config
+	-$(RM) $(OUT)/inliner $(OUT)/target $(SRCDIR)/codegen.c config $(BUILD_SESSION)
 
 -include $(deps)

README.md

@@ -107,12 +107,28 @@ $ chmod +x fib
 $ qemu-arm fib
 ```
 
-Verify that the emitted IRs are identical to the snapshots by specifying `check-snapshots` target when invoking `make`:
+### IR Regression Tests
+
+To ensure the consistency of frontend (lexer, parser) behavior when working on it, the snapshot test is introduced.
+The snapshot test dumps IRs from the executable and compares the structural identity with the provided snapshots.
+
+Verify the emitted IRs by specifying `check-snapshots` target when invoking `make`:
 ```shell
 $ make check-snapshots
 ```
 
-`shecc` comes with unit tests consist of stage 0, stage 2. To run these tests, give `check` as an argument:
+If the compiler frontend is updated, the emitted IRs might be changed.
+Thus, you can update snapshots by specifying `update-snapshots` target when invoking `make`:
+```shell
+$ make update-snapshots
+```
+
+Notice that the above 2 targets will update all backend snapshots at once, to update/check current backend's snapshot, 
+use `update-snapshot` / `check-snapshot` instead.
+
+### Unit Tests
+
+`shecc` comes with unit tests. To run the tests, give `check` as an argument:
 ```shell
 $ make check
 ```

tests/check-snapshots.sh

@@ -4,9 +4,16 @@ set -u
 
 readonly SHECC="$PWD/out/shecc"
 
+if [ "$#" != 1 ]; then
+    echo "Usage: $0 <architecture>"
+    exit 1
+fi
+
+readonly ARCH="$1"
+
 function check_snapshot() {
     local source="$1"
-    local ref="tests/snapshots/$(basename $source .c).json"
+    local ref="tests/snapshots/$(basename $source .c)-$ARCH.json"
     local temp_exe=$(mktemp)
     local temp_json=$(mktemp --suffix .json)
 

tests/update-snapshots.sh

@@ -4,9 +4,16 @@ set -u
 
 readonly SHECC="$PWD/out/shecc"
 
+if [ "$#" != 1 ]; then
+    echo "Usage: $0 <architecture>"
+    exit 1
+fi
+
+readonly ARCH="$1"
+
 function update_snapshot() {
     local source="$1"
-    local dest="tests/snapshots/$(basename $source .c).json"
+    local dest="tests/snapshots/$(basename $source .c)-$ARCH.json"
     local temp_exe=$(mktemp)
     local temp_json=$(mktemp --suffix .json)