Add GCC15 notes, varargs tests, and ternary condition ABI selftest

Author: t81dev

.github/workflows/ci.yml

@@ -11,8 +11,15 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest]
-        gcc-version: [9, 11]
+        include:
+          - os: ubuntu-latest
+            gcc-version: 9
+          - os: ubuntu-latest
+            gcc-version: 11
+          - os: macos-latest
+            gcc-version: 14
+          - os: macos-latest
+            gcc-version: 15
 
     steps:
     - uses: actions/checkout@v2
@@ -32,33 +39,6 @@ jobs:
         echo "CC=gcc-${{ matrix.gcc-version }}" >> $GITHUB_ENV
         echo "CXX=g++-${{ matrix.gcc-version }}" >> $GITHUB_ENV
 
-    - name: Build Plugin
-      run: make
-
-    - name: Build Runtime
-      run: |
-        gcc -Iinclude -c runtime/ternary_runtime.c -o ternary_runtime.o
-
     - name: Run Tests
       run: |
-        cd tests
-        chmod +x run_tests.sh
-        ./run_tests.sh
-        # Compile ABI test
-        gcc -I../include -c test_abi.c -o test_abi.o
-        gcc test_abi.o ../runtime/ternary_runtime.o -o test_abi
-        ./test_abi
-        # Compile promotion test
-        gcc -fplugin=../ternary_plugin.so -fplugin-arg-ternary_plugin-types -I../include -c test_promotion.c -o test_promotion.o
-        gcc test_promotion.o -o test_promotion
-        ./test_promotion
-        # Sanity check
-        gcc -c test_no_ternary.c -o test_no_ternary.o
-        # Run benchmark
-        gcc -I../include -c benchmark.c -o benchmark.o
-        gcc benchmark.o ../runtime/ternary_runtime.o -o benchmark
-        ./benchmark
-        # Edge cases
-        gcc -I../include -c test_edge_cases.c -o test_edge_cases.o
-        gcc test_edge_cases.o ../runtime/ternary_runtime.o -o test_edge_cases
-        ./test_edge_cases
+        make test

README.md

@@ -90,6 +90,12 @@ To build the plugin, you need GCC with plugin support enabled.
 make
 ```
 
+On macOS, prefer Homebrew GCC and set the toolchain explicitly:
+
+```bash
+make CXX=g++-15 CC=gcc-15
+```
+
 Alternatively, with CMake (requires GMP and other deps):
 
 ```bash
@@ -110,6 +116,10 @@ Optional arguments:
 
 - `-fplugin-arg-ternary_plugin-warn` emits a warning for each ternary operator.
 - `-fplugin-arg-ternary_plugin-stats` prints a summary at the end of compilation.
+- `-fplugin-arg-ternary_plugin-version` prints the plugin version and GCC version.
+- `-fplugin-arg-ternary_plugin-selftest` prints a brief self-test summary of enabled features.
+- `-fplugin-arg-ternary_plugin-trace` logs lowering decisions for matching statements.
+- `-fplugin-arg-ternary_plugin-dump-gimple` dumps matching GIMPLE statements before rewriting.
 - `-fplugin-arg-ternary_plugin-lower` replaces ternary operators with calls to
   `__ternary_select_[i|u]<bits>` for integral result types (e.g., `__ternary_select_i32`)
   and `__ternary_select_f32` or `__ternary_select_f64` for floating-point types.
@@ -128,6 +138,14 @@ Optional arguments:
 - `-fplugin-arg-ternary_plugin-prefix=<name>` sets the function name prefix used by `-lower`
   (default: `__ternary_select`).
 
+Example with trace/dumps enabled:
+
+```bash
+gcc -fplugin=./ternary_plugin.so -fplugin-arg-ternary_plugin-lower \
+  -fplugin-arg-ternary_plugin-trace -fplugin-arg-ternary_plugin-dump-gimple \
+  -Iinclude -c source.c
+```
+
 ## Implementing the Helpers
 
 When using `-lower`, the plugin emits calls to external functions like `__ternary_select_i32`.
@@ -136,12 +154,15 @@ You need to provide implementations for these functions, tailored to your ternar
 Include `include/ternary_helpers.h` in your code, which provides example implementations using
 placeholder ternary ISA instructions (for example, `tsel`, `tadd`, `tmul`, `tnot`). Adjust the
 assembly to match your ISA. `TERNARY_COND_T` defines the condition type used by select helpers
-and must match the source condition type (defaults to `bool`).
+and is fixed to `ternary_cond_t` (default: `int64_t`). The plugin lowers conditions to
+`ternary_cond_t` before helper calls.
 
 For testing without the plugin, the header provides C implementations of all ternary operations.
 Packed ternary types use a 2-bit encoding per trit (00 = -1, 01 = 0, 10 = +1).
 Define `TERNARY_USE_BUILTIN_TYPES` before including the header when compiling with
 `-fplugin-arg-ternary_plugin-types` to avoid typedef conflicts.
+Helper/runtime support is currently provided for t6/t12/t24 only; t48/t96/t192 require
+custom runtime implementations.
 
 For example:
 
@@ -165,7 +186,7 @@ gcc -fplugin=./ternary_plugin.so -fplugin-arg-ternary_plugin-lower -Iinclude -c
 For a minimal out-of-line runtime, use the reference implementation in `runtime/ternary_runtime.c`
 with the public header `include/ternary_runtime.h`. It implements the same packed 2-bit-trit
 semantics as the helpers (t6/t12/t24) and is intended as a starting point for a real ISA-backed
-library.
+library. Packed helpers for t48/t96/t192 are not provided in this reference runtime.
 
 Example build:
 
@@ -184,6 +205,12 @@ gcc -fplugin=./ternary_plugin.so -fplugin-arg-ternary_plugin-lower \
   -fplugin-arg-ternary_plugin-conv -Iinclude -c test_ternary.c
 ```
 
+On macOS, run:
+
+```bash
+make test CXX=g++-15 CC=gcc-15
+```
+
 ## Description
 
 This plugin analyzes ternary conditional expressions in the code and can optionally

ROADMAP.md

@@ -1,13 +1,14 @@
 # Ternary GCC Plugin Roadmap
 
 This roadmap focuses on getting a usable, testable ternary toolchain surfaced
-through a GCC plugin, with a stable ABI and runtime.
+through a GCC plugin, with a stable ABI and runtime on binary substrates.
 
 ## Phase 0: Baseline and Scope Lock
 
 - Define supported GCC versions and host platforms.
 - Freeze the ternary ABI surface (type sizes, packing, calling convention).
 - Decide on ternary XOR semantics and rounding rules for conversions.
+- Confirm the software-first contract (helpers as reference semantics).
 
 Deliverables:
 - ABI section in `SPECIFICATION.md` finalized.
@@ -18,6 +19,7 @@ Deliverables:
 - Implement `__ternary_*` functions referenced by the plugin.
 - Provide a portable reference implementation in C/C++.
 - Define headers for builtins and public API.
+- Add container helpers for t6/t12/t24 and a plan for larger widths.
 
 Deliverables:
 - `lib/` or `runtime/` with source and headers.
@@ -28,6 +30,7 @@ Deliverables:
 - Add user-facing types/macros and builtins in `include/ternary_plugin.h`.
 - Define how ternary literals and casts are written in C/C++.
 - Validate type promotion and conversion rules.
+- Lock down exact condition type handling in helper signatures.
 
 Deliverables:
 - Updated header APIs and example usage in `README.md`.
@@ -83,7 +86,17 @@ Deliverables:
 - Compatibility matrix in `README.md`.
 - ABI validation step in CI.
 
-## Phase 8: Extensions (Optional)
+## Phase 8: Optional Hardware Backend
+
+- Define an ISA encoding that preserves the helper ABI semantics.
+- Add a codegen path that targets the hardware mnemonics.
+- Provide a fallback mechanism to the helper runtime when unavailable.
+
+Deliverables:
+- Hardware backend design note and prototype.
+- Compatibility tests against the helper ABI.
+
+## Phase 9: Extensions (Optional)
 
 - Vector/packed ternary operations.
 - Ternary-aware optimizations (strength reduction, peepholes).