feat(pkg): phase 15 - a package can carry a native library

native "<target>" "<path>" in a package's package.ludic; the compiler records the libraries of
every package a program imports and writes them into the IR (; ludic-native:), so ludicc -o,
ludic build, ludic test and ludic bundle all link one list. macOS: an rpath to the package and to
Contents/Frameworks, where ludic bundle copies and signs each library and drops the build
machine's rpath. Windows: the import library, the .dll copied beside the exe (--natives-out for
the bundle). tools/native/lib.sh builds from a pinned, checksummed source with clang on both
machines; ludic.nativeecho is the worked example; the shim rules are in packages/README.md.
Linked at build time rather than dlopen (docs/PACKAGES.md says why). Reseeded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tools/ludic-cli/build.ludic

@@ -27,6 +27,8 @@ function ensure_ludicc() -> void {
 # rendered to build/out.ppm from piped input — deterministic output for tests).
 # Returns true on success. `ludic build`, `ludic run` and the contributor tool all
 # go through here.
+# the native libraries (phase 15) the last compile_app linked, for `ludic bundle` to place
+var g_built_natives: []pointer = new []pointer
 function compile_app(src: pointer, out: pointer, mode: int, save: bool) -> bool {
   ensure_ludicc()                          # in a checkout: assemble the seed if bin/ludicc is missing or stale
   let home = ludic_home()
@@ -52,7 +54,8 @@ function compile_app(src: pointer, out: pointer, mode: int, save: bool) -> bool
 
   if mode == 2 {
     if not shq(`{ludicc()} --headless{title_flag()}{unsafe_flag()} {src} --emit-llvm -o {ll}`) { return false }
-    if not shq(`{cc()} -O2 {ll}{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{pbf} -o {out}`) { return false }
+    if not shq(`{cc()} -O2 {ll}{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{native_link_flags(ll)}{pbf} -o {out}`) { return false }
+    g_built_natives = native_libs_of(ll)
     if not save { shell(`rm -f {ll}`) }
     return true
   }
@@ -62,7 +65,8 @@ function compile_app(src: pointer, out: pointer, mode: int, save: bool) -> bool
   # canonical `ludicc -o` path links it only when Audio.* is used.
   let cocoa = `{home}runtime/native/cocoa.ll`
   let audio = `{home}runtime/native/audio.ll`
-  if not shq(`{cc()} -O2 {ll} {cocoa} {audio} -framework Cocoa -Wl,-needed_framework,GameController -Wl,-needed_framework,AVFoundation -Wl,-rpath,@loader_path{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{pbf} -o {out}`) { return false }
+  if not shq(`{cc()} -O2 {ll} {cocoa} {audio} -framework Cocoa -Wl,-needed_framework,GameController -Wl,-needed_framework,AVFoundation -Wl,-rpath,@loader_path{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{native_link_flags(ll)}{pbf} -o {out}`) { return false }
+  g_built_natives = native_libs_of(ll)
   if not save { shell(`rm -f {ll}`) }
   return true
 }
@@ -105,6 +109,30 @@ function vk_link_flags(ll: pointer) -> pointer {
   return ` {home}runtime/native/vk_thunks.ll {home}runtime/native/vk_mac.ll`
 }
 
+# A package that carries a native library (phase 15) is written into the IR by the compiler as
+# `; ludic-native: <path>` lines: link each, with an rpath to its directory for a run from the
+# build and one to Contents/Frameworks, where `ludic bundle` puts it.
+function native_libs_of(ll: pointer) -> []pointer {
+  let out = new []pointer
+  let lines = split_lines(capture(`grep "^; ludic-native: " {ll} 2>/dev/null`))
+  var i = 0
+  while i < len(lines) {
+    if s_starts(lines[i], "; ludic-native: ") { push(out, sslice(lines[i], 16, slen(lines[i]))) }
+    i += 1
+  }
+  return out
+}
+function native_link_flags(ll: pointer) -> pointer {
+  let libs = native_libs_of(ll)
+  var f = ""
+  var i = 0
+  while i < len(libs) {
+    f = f + ` "{libs[i]}" -Wl,-rpath,{dir_of_path(libs[i])} -Wl,-rpath,@executable_path/../Frameworks`
+    i += 1
+  }
+  return f
+}
+
 # A program that uses Http.* calls the @hs_* transport; link http.ll and Foundation only
 # then, in both modes, as `ludicc -o` does (selfhost/main.ludic). Without it a Http.*
 # program built through `ludic build` failed to link on every hs_* symbol.

tools/ludic-cli/bundle.ludic

@@ -272,6 +272,35 @@ function windows_icon_res(icon: pointer) -> pointer {
   return res
 }
 
+# copy what the last build linked into Contents/Frameworks
+# and drop the rpath to where each was built: a shipped binary names no path on this machine
+function bundle_natives_mac(contents: pointer, exe: pointer) -> bool {
+  if len(g_built_natives) == 0 { return true }
+  shell(`mkdir -p "{contents}/Frameworks"`)
+  for i in 0 .. len(g_built_natives) {
+    shq(`install_name_tool -delete_rpath "{dir_of_path(g_built_natives[i])}" "{exe}" 2>/dev/null`)
+    if not shq(`cp "{g_built_natives[i]}" "{contents}/Frameworks/"`) {
+      err(`ludic bundle: could not place {g_built_natives[i]}\n`)
+      return false
+    }
+  }
+  return true
+}
+
+# copy the .dll files ludicc wrote into <exe>.natives beside the executable
+function bundle_natives_win(list: pointer, root: pointer) -> bool {
+  let txt = read_file(list)
+  if txt == null { return true }
+  let libs = split_lines(txt)
+  for i in 0 .. len(libs) {
+    if libs[i] != "" and not shq(`cp "{libs[i]}" "{root}/"`) {
+      err(`ludic bundle: could not place {libs[i]}\n`)
+      return false
+    }
+  }
+  return true
+}
+
 function cmd_bundle_windows() -> int {
   let entry = parse_build_args(2)
   if g_argerr { return 1 }
@@ -288,11 +317,12 @@ function cmd_bundle_windows() -> int {
   let staged = tmp_path("bundle_exe")
   var flags = "--windowed --gui"
   if res != "" { flags = flags + ` --link "{res}"` }
-  if not shq(`{ludicc()} {flags}{title_flag()} {entry} -o {staged}`) { return 1 }
+  if not shq(`{ludicc()} {flags}{title_flag()} {entry} --natives-out {staged}.natives -o {staged}`) { return 1 }
   if not shq(`cp "{staged}.exe" "{root}/{name}.exe"`) {
     err("ludic bundle: could not place the executable\n")
     return 1
   }
+  if not bundle_natives_win(`{staged}.natives`, root) { return 1 }
 
   # 2. the assets, exactly as the .app packs them
   let roots = pack_roots(m, 999)
@@ -376,6 +406,11 @@ function cmd_bundle() -> int {
     return 1
   }
 
+  # 1b. a package's native libraries (phase 15) go in Contents/Frameworks, where the binary's
+  #     @executable_path/../Frameworks rpath finds them - never in MacOS, which must hold mach-o
+  #     executables only (a Velopack update strips anything else's detached signature)
+  if not bundle_natives_mac(contents, exe) { return 1 }
+
   # 2. the assets
   let roots = pack_roots(m, 999)                 # manifest/convention only, no argv
   var packed = false
@@ -430,6 +465,13 @@ function cmd_bundle() -> int {
   #    ID and notarisation - but it does make it run here.
   var ident = manifest_app(m, "sign")
   if ident == "" { ident = "-" }
+  # nested code is signed before what contains it
+  for i in 0 .. len(g_built_natives) {
+    let fw = `{contents}/Frameworks/{file_of_path(g_built_natives[i])}`
+    if not shq(`codesign --force --timestamp=none --sign "{ident}" "{fw}" 2>/dev/null`) {
+      err(`ludic bundle: warning: codesign failed on {fw}\n`)
+    }
+  }
   if not shq(`codesign --force --timestamp=none --sign "{ident}" "{root}" 2>/dev/null`) {
     err(`ludic bundle: warning: codesign failed; the app may not launch\n`)
   }

tools/ludic-cli/selfhost.ludic

@@ -21,6 +21,7 @@ function selfhost_frags() -> []pointer {
   push(f, "selfhost/frontend/generics.ludic")
   push(f, "selfhost/frontend/aliases.ludic")
   push(f, "selfhost/frontend/modules.ludic")
+  push(f, "selfhost/frontend/natives.ludic")
   push(f, "selfhost/frontend/ports.ludic")
   push(f, "selfhost/frontend/privates.ludic")
   push(f, "selfhost/frontend/privates_types.ludic")

tools/ludic-cli/testpar.ludic

@@ -36,7 +36,7 @@ function test_parallel(files: []pointer, only: pointer, verbose: bool) -> int {
     let bin = bins[i]
     let ll = `{bin}.ll`
     if test_rc(`{bin}.rc1`) == 0 {
-      let flags = `{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{pbf}`
+      let flags = `{gl_link_flags(ll)}{vk_link_flags(ll)}{http_link_flags(ll)}{udp_link_flags(ll)}{process_link_flags(ll)}{threads_link_flags(ll)}{native_link_flags(ll)}{pbf}`
       write_file(`{jd}/l{string(i)}.sh`, `{cc()} -O2 {ll}{flags} -o {bin} >> {bin}.log 2>&1; echo $? > {bin}.rc2\n`)
     }
   }