One binary for glibc and musl distros

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: CI
 # Testing Strategy:
 # - Tests run on Linux and Windows (AMD64 only - macOS planned for v0.5.0)
 # - goffi uses platform-specific assembly (System V vs Win64 ABI)
-# - Go 1.25+ required (matches go.mod requirement)
+# - Go 1.26+ required (matches go.mod requirement)
 # - Race detector critical for low-level FFI code
 #
 # Branch Strategy (Git Flow):
@@ -41,7 +41,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
           cache: true
 
       - name: Download dependencies
@@ -69,7 +69,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
           cache: true
 
       - name: Check formatting
@@ -97,7 +97,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
           cache: true
 
       - name: Cross-compile all platforms
@@ -168,14 +168,60 @@ jobs:
   # Keep both supported Go patch lines: runtime/cgo startup and TLS details
   # are part of this platform contract, so a single floating toolchain is not
   # sufficient evidence.
+  # Static builds - the goffi_static tag must strip every
+  # //go:cgo_import_dynamic directive, otherwise the linker keeps emitting an
+  # ELF interpreter and the artifact will not run on Alpine or scratch.
+  # See docs/STATIC_BUILDS.md and unxed/f4#693.
+  static-build:
+    name: Static Build (goffi_static)
+    runs-on: ubuntu-latest
+    needs: [lint, formatting]
+    env:
+      CGO_ENABLED: 0
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+          cache: true
+
+      - name: Check static build mode
+        run: scripts/check-static.sh
+
+  # musl builds - the goffi_musl tag must swap the glibc SONAMEs and the
+  # ELF interpreter for their musl equivalents, otherwise the binary cannot
+  # start on Alpine. Link-time checks run for amd64 and arm64; the runtime
+  # probe executes inside a real Alpine userland. See docs/MUSL.md.
+  musl-build:
+    name: musl Build (goffi_musl)
+    runs-on: ubuntu-latest
+    needs: [lint, formatting]
+    env:
+      CGO_ENABLED: 0
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+          cache: true
+
+      - name: Check musl build mode
+        run: scripts/check-musl.sh
+
   android-cross:
     name: Android arm64 (Go ${{ matrix.go }})
     runs-on: ubuntu-latest
     needs: [lint, formatting]
     strategy:
       fail-fast: false
       matrix:
-        go: ['1.25.12', '1.26.5']
+        go: ['1.25.12', '1.26.5', '1.26.x']
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -229,7 +275,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
           cache: true
           cache-dependency-path: go.sum
 
@@ -298,7 +344,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
           cache: true
 
       - name: Download dependencies
@@ -340,7 +386,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26.x'
 
       - name: Download coverage reports
         uses: actions/download-artifact@v4
@@ -408,7 +454,7 @@ jobs:
           echo "✅ Lint: PASSED"
           echo "✅ Formatting: PASSED"
           echo "✅ Cross-Compile: PASSED (8 desktop targets)"
-          echo "✅ Android arm64: PASSED (API 29+, Go 1.25/1.26, cgo=0/1)"
+          echo "✅ Android arm64: PASSED (API 29+, Go 1.26, cgo=0/1)"
           echo "✅ Tests: PASSED (CGO_ENABLED=0 and CGO_ENABLED=1)"
           echo "   - Linux AMD64 (ubuntu-latest)"
           echo "   - Windows AMD64 (windows-latest)"

.github/workflows/universal.yml

@@ -0,0 +1,117 @@
+name: universal
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build + Profile U contract
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          # Pinned to match .github/workflows/ci.yml: the goffi_musl build below
+          # depends on the toolchain's cgo_import_dynamic restrictions, which
+          # the -gcflags=...=-std workaround is calibrated against.
+          go-version: '1.26.x'
+      - name: Build every mode, vet and unit tests
+        run: |
+          set -euo pipefail
+          CGO_ENABLED=0 go build ./...
+          CGO_ENABLED=0 go build -tags goffi_universal ./...
+          CGO_ENABLED=0 go build -tags goffi_static ./...
+          CGO_ENABLED=0 go build -tags goffi_musl -gcflags=github.com/go-webgpu/goffi/internal/dl=-std ./...
+          # -unsafeptr=false: goffi reconstructs pointers from native call
+          # registers and stack slots by design (see ffi/callback_pointer.go's
+          # //go:nocheckptr contract). ci.yml runs vet through golangci-lint,
+          # which excludes govet on exactly those paths (.golangci.yml); this
+          # flag is the bare-vet equivalent of that exclusion.
+          CGO_ENABLED=0 go vet -unsafeptr=false ./...
+          CGO_ENABLED=0 go test ./...
+          CGO_ENABLED=0 go test -tags goffi_universal ./internal/...
+      - name: Build the universal probe and check the ELF contract
+        run: |
+          set -euo pipefail
+          bash scripts/build-universal.sh -o universal-probe ./cmd/universal-probe
+          go run ./cmd/goffi-audit universal-probe
+      - name: Upload universal probe
+        uses: actions/upload-artifact@v4
+        with:
+          name: universal-probe
+          path: universal-probe
+
+  run-glibc:
+    name: run on glibc (${{ matrix.image }})
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        image: [ "debian:stable-slim", "ubuntu:24.04" ]
+    container:
+      image: ${{ matrix.image }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: universal-probe
+      - name: Run the same universal binary on glibc
+        run: |
+          set -eu
+          chmod +x universal-probe
+          ./universal-probe | tee out.txt
+          grep -q UNIVERSAL-PROBE-OK out.txt
+
+  run-musl:
+    name: run on musl (alpine)
+    needs: build
+    runs-on: ubuntu-latest
+    container:
+      image: alpine:latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: universal-probe
+      - name: Run the same universal binary on musl
+        shell: sh
+        run: |
+          set -eu
+          chmod +x universal-probe
+          ./universal-probe | tee out.txt
+          grep -q UNIVERSAL-PROBE-OK out.txt
+
+  purego-coexistence:
+    name: purego coexistence (CGO-free, -tags nofakecgo)
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: goffi
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+      - name: Build and run a program importing goffi and purego together
+        run: |
+          set -euo pipefail
+          mkdir coexist && cd coexist
+          printf '%s\n' \
+            'package main' \
+            '' \
+            'import (' \
+            '	_ "github.com/ebitengine/purego"' \
+            '	"github.com/go-webgpu/goffi/ffi"' \
+            ')' \
+            '' \
+            'func main() { println("coexist ffi.Available =", ffi.Available()) }' \
+            > main.go
+          go mod init coexist
+          go mod edit -replace github.com/go-webgpu/goffi=../goffi
+          GOFLAGS=-mod=mod go get github.com/go-webgpu/goffi/ffi
+          GOFLAGS=-mod=mod go get github.com/ebitengine/purego
+          CGO_ENABLED=0 go build -tags nofakecgo -o coexist .
+          ./coexist

.gitignore

@@ -68,3 +68,5 @@ RESEARCH*.md
 # Go modules (don't ignore go.mod and go.sum)
 !go.mod
 !go.sum
+/goffi-audit
+/def_probe

CONTRIBUTING.md

@@ -225,7 +225,7 @@ experiment: prototype macOS Apple Silicon support
 
 ### Prerequisites
 
-- **Go 1.25 or later** (required for latest runtime.cgocall features)
+- **Go 1.26 or later** (required for latest runtime.cgocall features)
 - **golangci-lint** (code quality)
 - **GCC or Clang** (for race detector, optional but recommended)
 - **Platform access**:
@@ -241,7 +241,7 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
 
 # Verify installation
 golangci-lint --version
-go version  # Should be 1.25+
+go version  # Should be 1.26+
 ```
 
 ### Running Tests

NOTICE

@@ -11,3 +11,13 @@ under the Apache License, Version 2.0. Original copyright:
 
 The Apache-2.0 licensed files retain their original SPDX headers
 with dual copyright attribution.
+
+--------------------------------------------------------------------------------
+Profile U (universal glibc/musl) build
+--------------------------------------------------------------------------------
+goffi's universal build ports the "Profile U" concept from
+unxed/static-everywhere (https://github.com/unxed/static-everywhere): a single
+CGO-free binary with no PT_INTERP and no DT_NEEDED that reaches the host libc
+through the host's own dynamic loader. The full in-process foreign-libc loader
+pg83/solo (https://github.com/pg83/solo) is referenced but not vendored. See
+docs/PROFILE_U.md.

README.md

@@ -376,6 +376,47 @@ if err != nil {
 
 ---
 
+## Static Builds
+
+Binaries that import goffi are dynamically linked by default: the
+`//go:cgo_import_dynamic` directives behind `dlopen`/`dlsym` make the Go linker
+emit an ELF interpreter and `DT_NEEDED` entries even under `CGO_ENABLED=0`, and
+`-extldflags '-static'` cannot change that because no external linker runs.
+
+Build with `-tags goffi_static` to drop those directives:
+
+```bash
+CGO_ENABLED=0 go build -tags goffi_static ./...
+```
+
+The result is a genuinely static binary that runs on Alpine and in `scratch`
+containers. The trade is unavoidable — `dlopen` is a service of the dynamic
+loader, which a static executable does not have — so in that mode `LoadLibrary`,
+`GetSymbol` and `CallFunction` return an error wrapping `ffi.ErrStaticBuild`.
+
+The API is identical in both modes, so one source tree can produce both
+artifacts. Branch on `ffi.Available()`, a compile-time constant, to keep the
+pure-Go path and let the linker drop the rest:
+
+```go
+if ffi.Available() {
+    backend = newAcceleratedBackend()
+} else {
+    backend = newPureGoBackend()
+}
+```
+
+The tag is a no-op on Windows and Android, which are dynamically linked by
+construction; `Available()` stays `true` there, so a cross-platform build matrix
+can pass the tag everywhere. See [docs/STATIC_BUILDS.md](docs/STATIC_BUILDS.md).
+
+For Alpine and other musl-based distros there is a third flavor: the default
+build hardcodes glibc SONAMEs and the glibc loader path, so it cannot start
+under musl at all. Build with `-tags goffi_musl` (plus one `-gcflags` line) to
+target musl with **full FFI** — see [docs/MUSL.md](docs/MUSL.md).
+
+---
+
 ## Platform Support
 
 | Platform | Arch | ABI | Since | CI |
@@ -483,3 +524,9 @@ MIT — see [LICENSE](LICENSE).
 ---
 
 *goffi v0.4.1 | [GitHub](https://github.com/go-webgpu/goffi) | [pkg.go.dev](https://pkg.go.dev/github.com/go-webgpu/goffi) | [Dev.to](https://dev.to/kolkov/goffi-zero-cgo-foreign-function-interface-for-go-how-we-call-c-libraries-without-a-c-compiler-ca5)*
+
+## Universal build (glibc + musl)
+
+One CGO-free binary can do FFI on both glibc and musl systems — see
+[docs/PROFILE_U.md](docs/PROFILE_U.md). Attribution for the Profile U concept
+(unxed/static-everywhere, pg83/solo) is in [NOTICE](NOTICE).