compiler: implement go:cgo_import_dynamic and lower Darwin cgo import trampolines (#5604)

[neomantra]

As noted in #5604, this was worked through with LLM. It adds parsing of the go:cgo_import_dynamic directive and implementation for Darwin.

The other Tinygo-supported platform that could use this is OpenBSD, but is more important for Darwin. It targets loadASTComments generally because these directives are not necessarily attached to a function/module/etc; the comment there explains it.

The following description of the PR is LLM-generated from our journey; it is verbose but comprehensive. I have read it and I have reviewed all the submitted code, both humanually and with multiple LLMs. Thanks for the review.

---

Summary

Extend TinyGo's existing Darwin stdlib trampoline lowering to the variable-based pattern used by golang.org/x/sys/unix and internal/syscall/unix, and route all four variadic libc imports (open, openat, fcntl, ioctl) through fixed-signature wrappers on both trampoline paths.

Fixes #5604.
Fixes #5365.
Builds on #5401.
The companion _ioctl/___sincos_stret stubs (macos-minimal-sdk#5) are already in dev via the macos-minimal-sdk v0.1.0 submodule update.

Problem

Darwin syscall wrappers generated by x/sys declare globals such as libc_ioctl_trampoline_addr and associate them with dylib symbols using file-level //go:cgo_import_dynamic pragmas. TinyGo does not compile the assembly that initializes those globals, so the existing libc syscall engine receives address zero and crashes before main in Bubble Tea programs.

TinyGo already avoids the equivalent assembly trampoline for the standard library: createDarwinFuncPCABI0Call recognizes abi.FuncPCABI0(libc_*_trampoline) and substitutes the address of an external libc declaration. This change applies that same lowering to the x/sys global-load pattern.

That existing stdlib lowering also carries a silent bug of its own: among its variadic imports it routes only open through a fixed-signature wrapper, so stdlib fcntl, ioctl, and openat calls corrupt their variadic arguments on darwin/arm64. This PR fixes that too, since the new lowering needs the same wrapper set anyway.

Scope

This is a targeted implementation of the //go:cgo_import_dynamic pattern used by Darwin's generated syscall wrappers, not general cross-platform support for the directive. Although the file-level metadata is parsed during compilation, the libc_*_trampoline_addr symbol-address substitution is restricted to GOOS=darwin; non-Darwin targets retain their existing behavior.

Upstream Go also uses //go:cgo_import_dynamic on platforms such as OpenBSD, AIX, Solaris, and illumos. Supporting those platforms, the directive's library operand, other use patterns, and platform-specific linking or calling conventions remains out of scope.

Implementation

• Parse the local and remote symbol metadata from file-level //go:cgo_import_dynamic pragmas into a package-local map for Darwin trampoline lowering, accepting the same one-, two-, and three-operand forms as the gc compiler (local [remote ["library"]]); the remote symbol defaults to the local one and the library operand is ignored (the linker already resolves against libSystem).
• On Darwin, replace loads of matching uintptr-typed libc_*_trampoline_addr globals with ptrtoint of an external declaration for the pragma's remote symbol. Globals of any other type keep their normal load.
• Preserve remote names verbatim, including amd64 $INODE64 variants.
• Route the variadic imports through fixed-signature C wrappers via a shared darwinVariadicImports table. Of the symbols Darwin's generated syscall wrappers import (zsyscall_darwin_*.go in x/sys and the standard library), exactly open, openat, fcntl, and ioctl are variadic. The syscall engine calls imported addresses through fixed-signature function pointers (tinygo_syscallX and friends) that pass every argument in a register, while a variadic callee reads its variadic arguments from the stack on darwin/arm64, so direct calls silently receive garbage in the variadic slot (observed: EFAULT from ioctl; unix.Open creating files with mode 0 instead of the requested mode).
• In a separate commit, point the existing stdlib FuncPCABI0 trampoline lowering (createDarwinFuncPCABI0Call) at the same table, replacing its open-only special case. This fixes the pre-existing silent bug on the stdlib path: syscall.SetNonblock (fcntl F_SETFL with the new flags in the variadic slot) observably wrote garbage file flags on darwin/arm64, and the stdlib ioctl and openat trampolines were equally unsound.
• Extend the focused compiler IR test: pragma parsing including the short directive forms, exact remote-symbol preservation, load replacement, wrapper routing for all four variadic imports (with no direct declarations for them), and the non-uintptr-global guard.

The companion _ioctl and ___sincos_stret stub additions landed upstream in macos-minimal-sdk#5 and reached dev with the macos-minimal-sdk v0.1.0 submodule update, so this branch (rebased onto that dev) builds and links darwin x/sys programs out of the box with no SDK changes of its own. No new stubs are needed for open, openat, or fcntl — those symbols are already in the stock stub list, and their prototypes come from the SDK's sys/fcntl.h.

Verification

• go test -tags llvm22 ./compiler -count=1
• 11-line golang.org/x/sys/unix.IoctlGetTermios repro under a PTY: returned a populated termios value and <nil>.
• github.com/charmbracelet/x/term.IsTerminal under a PTY: true.
• term.MakeRaw and term.Restore under a PTY: both <nil>.
• Bubble Tea examples/spinner: initialized, rendered animated frames, and exited on q.
• Bubble Tea examples/list-default: initialized, rendered the list UI, and exited on q.
• Variadic-slot checks (x/sys path), asserting values that travel through the variadic parameter: unix.Open with mode 0o640 created the file with mode 640 exactly, unix.FcntlInt(F_DUPFD, 50) returned fd 50, and unix.Openat with mode 0o600 created mode 600 exactly. The pre-fix compiler produced mode 0, fd 49, and mode 41 on the same program — the silent-corruption failure mode.
• Variadic-slot check (stdlib FuncPCABI0 path): syscall.SetNonblock(fd, true) followed by an F_GETFL readback yields flags exactly 0o4 (O_NONBLOCK), and a read from the empty pipe returns EAGAIN immediately. Without the FuncPCABI0 change, the same program showed garbage flags (0o20000110), O_NONBLOCK unset, and the read blocked forever; the blocking read was also reproduced on stock dev at f71b630 with a stdlib-only variant.

No startup panic or os/signal/SIGWINCH failure surfaced in this ladder.

Context

This is the actual current Darwin-native root cause behind #5365. It is the "class 2" failure described by @mparrett in #4794 and is independent of the public syscall.Syscall* API discussed there.

An earlier attempt in #5403 made public syscall.Syscall* calls work by lowering syscall numbers directly to raw Darwin kernel instructions. That was a separate route which bypassed Darwin's libc-based dispatch and was never used by the x/sys/Bubble Tea call chain.

After #5401 made x/sys's private linknames resolve, the failing program reached TinyGo's existing syscall.syscalln/syscall.rawsyscalln libc dispatcher with the correct ioctl arguments but a zero function pointer. The dispatcher was not broken; the assembly-generated bridge that supplied its libc function pointer was missing. This change supplies that address and lets x/sys use TinyGo's existing libc path as intended.

This does not implement public syscall.Syscall*-by-number on Darwin, nor does it guarantee that every libc symbol is already present in the macOS minimal SDK.

[yohimik]

This also covers the stdlib fcntl fix in #5632. I will close that narrower duplicate and point the Darwin process work in #5634 here. The regression tests from #5632 remain available in src/os/fcntl_test.go at yohimik/tinygo@9161a8c. They cover integer F_SETFL and pointer F_GETLK arguments. Please reuse them if useful. I have read this implementation and its test record, but have not yet run those tests against this branch.

[yohimik]

Tested your head 08df152 in the combined hosted candidate e7d34c8, built by CI. The downloaded Darwin arm64 compiler builds unchanged Crier 7edaff9, and the earlier failure before main in x/sys/cpu.darwinSysctlEnabled is absent. Crier E2E passes 142 cases with no failures and one platform trust-store skip. The retained F_SETFL integer and F_GETLK pointer tests both pass, as do all process remapping tests. Full Linux and macOS candidate CI passed. This is combined-candidate evidence, not a claim that this PR alone supplies all Crier dependencies. Exact artifact IDs, hashes, logs, and limits are in https://github.com/yohimik/crier/blob/7c4ea43/docs/operations/tinygo-comparison-2026-09-05.md . Thank you for the broader stdlib and x/sys support.

[davecheney]

I verified this fix on osx/aarch64 with a project which previously panic'd using the x/term package and it worked. Thank you.

[deadprogram]

Thanks for this @neomantra, and for the very clear write-up. The approach looks correct, and the fix to the open-only special case in createDarwinFuncPCABI0Call is a good catch on its own.

The following findings are edited from an automated review.

1. Link failures for x/sys symbols that have no stub

compileopts/target.go:411 sets spec.Libc = "darwin-libSystem" for all darwin builds, native and cross, so every darwin link goes through the stub libSystem.dylib built from lib/macos-minimal-sdk. Of the 147 unique remote symbols imported by the generated darwin syscall wrappers in the standard library and x/sys/unix, 39 have no stub:

accept bind clonefile clonefileat connect fclonefileat fgetxattr flistxattr
fremovexattr fsetxattr fstatfs getfsstat getpeername getsockname getsockopt
getxattr listen listxattr mount poll ptrace recvfrom recvmsg removexattr
sendfile sendmsg sendto setprivexec setsockopt setxattr shmat shmctl shmdt
shmget shutdown socket socketpair statfs unmount

Before this change, a live call to unix.Socket or unix.Poll loaded zero and failed at run time. After it, the compiler emits a real external declaration, so a live reference becomes an undefined-symbol link error. The new failure is earlier and clearer, but it is a behavior change for code that used to build. The PR puts stub coverage out of scope, which is reasonable. It would help to name the socket and xattr families in the description and to open a follow-up issue in macos-minimal-sdk for them.

2. The ioctl declaration does not state its reason

In src/runtime/os_darwin.c, sys/ioctl.h is not present in the minimal SDK, so the hand-written declaration is necessary. Please add a source reference on this comment. One line is enough:

// <sys/ioctl.h> is not in lib/macos-minimal-sdk, so declare ioctl here.
extern int ioctl(int fd, unsigned long request, ...);

3. Comment length

Three new blocks are very long comments: darwinVariadicImports (17 lines), the pragma block in loadASTComments (14 lines), and the wrapper block in os_darwin.c (11 lines). The content is good, but most of it is rationale that reads better in the PR description. Each can go down to 2 lines plus the sys/fcntl.h reference.

4. Wrapper signature style

The three new wrappers take uintptr_t and cast inside, while the existing syscall_libc_open keeps typed parameters. Both work. Changing syscall_libc_open to match would keep the file uniform.

5. Test hygiene

TestDarwinCgoImportDynamic does not call t.Parallel() or llvm.VerifyModule, unlike the other tests in the file.

6. Pragma position is not checked

strings.Fields(comment.Text) accepts the directive in any comment, including a trailing comment on a code line. The gc compiler honors it only at column 1. This has no effect on the generated files that motivate the change.

[deadprogram]

@neomantra also please see merge conflict now, in addition to my last feedback. Thanks.