fix: Keep uni_curl_shim.c buildable on Windows so downstream Native builds link (#640)

**Description**

uni 2026.1.17 broke every downstream Scala Native build on Windows:

```
uni_native0.5_3-2026.1.17-6/scala-native/uni_curl_shim.c:44:10:
fatal error: 'dlfcn.h' file not found
```

The `dlsym` rewrite that fixed #622 reached for `<dlfcn.h>` and
`<pthread.h>` unconditionally, and MSVC ships neither. Because Scala
Native compiles every `.c` under `resources/scala-native/` from every
jar on the classpath, this hits consumers that never touch curl —
[wvlet's Windows native
build](https://github.com/wvlet/wvlet/actions/runs/28837314411) is
failing on `main` for exactly this reason, and it only links `wvc-lib`.
Both Windows jobs there die on this one error and nothing else.

**The fix.** Split the two POSIX primitives per platform, preserving the
property #622 turned on — *the object file must reference no libcurl
symbol*, or downstream links without `-lcurl` fail:

| | POSIX | Windows |
|---|---|---|
| lookup | `dlsym(RTLD_DEFAULT, name)` | `GetProcAddress` over
`EnumProcessModules` |
| run-once | `pthread_once` | `InitOnceExecuteOnce` |

Windows has no all-modules handle, so the shim enumerates the process's
loaded modules and tries each — the process image first, matching
`dlsym`'s order. `#define PSAPI_VERSION 2` keeps `EnumProcessModules` in
`kernel32` (as `K32EnumProcessModules`) rather than `psapi.lib`, since a
jar-resource `.c` can't make downstream binaries add a linker flag. The
POSIX path is unchanged in behaviour.

One consequence worth flagging: runtime lookup only finds *exported*
symbols, so **libcurl must be linked as a DLL**, not a static `.lib`.
vcpkg's default `x64-windows` / `arm64-windows` triplets already do
that. This isn't new to Windows — a static `libcurl.a` is equally
invisible to `dlsym(RTLD_DEFAULT, ...)`. It's the price #622's fix
already paid; the ADR and the user docs now say so out loud.

**Why CI didn't catch it, and what now does.** Two distinct failure
modes, neither check subsuming the other:

1. **`curl shim C (Windows)`** — compiles the shim standalone with clang
on `windows-latest`. Nothing else here compiles the Windows half of the
`#if`.
2. **`check-curl-shim.sh`** — one step in the Linux Native job,
asserting via `nm -u` that the object names no `curl_easy_*` symbol.
*No* Scala Native job can catch that on any OS: [`build.sbt` passes
`-lcurl`
unconditionally](https://github.com/wvlet/uni/blob/main/build.sbt#L101-L103),
so uni's own binaries always resolve those symbols and link happily.
Only a consumer that doesn't link libcurl breaks — which is precisely
how #622 escaped this repo's CI. Inspecting the object stands in for
that consumer.

I checked (2) bites rather than rubber-stamps: against `v2026.1.16`'s
`extern`-based shim it reports `_curl_easy_setopt` /
`_curl_easy_getinfo` and exits 1, reproducing #622.

Both are gated on a new narrow `native` paths-filter (`**.c`,
`**/.native/**`, `project/**`, the workflow itself), so they run on
every push to `main` and only on PRs that can actually break them.
(`dorny/paths-filter` matches with `dot: true`, so `**/.native/**` does
reach the dot-prefixed source trees.) The `changes` filter never watched
`**.c` at all before, so an edit touching only this file skipped CI
outright.

> [!IMPORTANT]
> **A real `Scala Native (Windows)` job would be the better guard, and
uni cannot run one.** I built it — LLVM, vcpkg libcurl/zlib/OpenSSL,
aliasing every `foo.lib` that `-lfoo` asks for — and it compiles
everything, then fails at the final link:
>
> ```
> error LNK2019: unresolved external symbol scalanative_pollin
>   referenced in function ...wvlet.uni.http.NativeServerTest...
> fatal error LNK1120: 5 unresolved externals
> ```
>
> `NativeServer` uses POSIX `poll()`, and Scala Native's
[`posixlib/poll.c`](https://github.com/scala-native/scala-native/blob/v0.5.12/posixlib/src/main/resources/scala-native/poll.c)
is wrapped in `#if defined(__unix__) || (defined(__APPLE__) &&
defined(__MACH__))` — those symbols don't exist on Windows. Every native
HTTP test starts a server, so uni's native test binary is unlinkable
there, full stop. Giving `NativeServer` a `WSAPoll` path would unblock
it; this PR's history has the working toolchain setup to reuse. Worth
filing as a follow-up issue.
>
> That discarded run wasn't wasted: it linked everything *except*
`poll`, so none of the unresolved symbols were `curl_easy_*` — proving
the shim compiles **and links** clean under clang/MSVC, which is the
regression this PR is about.

**Docs.** The old text said only *"Scala Native requires libcurl to be
available at runtime."* Added [Linking libcurl on Scala
Native](https://github.com/wvlet/uni/blob/fix/curl-shim-windows/docs/http/client.md#linking-libcurl-on-scala-native)
covering the three things a Native user actually hits: you need libcurl
*only* if you use the HTTP client (DCE drops `@link("curl")` otherwise —
that's what #622 bought, and nobody would guess it); it must be a shared
library; and on Windows you alias `libcurl.lib` to the `curl.lib` Scala
Native asks for.

**Related Issue/Task**

Follow-up to #622 / the ADR added in #631. Unblocks wvlet's `Native`
workflow on `main`.

**Checklist**

- [x] This pull request focuses on a single task.
- [x] The change does not contain security credentials

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: xerial

.github/scripts/check-curl-shim.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Guards uni_curl_shim.c, which Scala Native compiles into every downstream binary on every platform
+# it supports. Two things can go wrong, and both have:
+#
+#   1. It fails to compile. v2026.1.17 included <dlfcn.h>, which the MSVC toolchain does not ship,
+#      breaking every downstream Windows Scala Native build.
+#   2. Its object references a libcurl symbol, which breaks the link of downstream projects that
+#      never pull in -lcurl (issue #622, adr/2026-07-06-curl-shim-weak-linking.md).
+#
+# No Scala Native job in this repo catches (2): build.sbt passes -lcurl unconditionally, so every uni
+# native binary resolves those symbols and links happily. Only a consumer without -lcurl breaks, and
+# inspecting the object directly is what stands in for that consumer.
+#
+# Nor can one catch (1) on Windows: uni's NativeServer uses POSIX poll(), which Scala Native's
+# posixlib only builds on unix/Apple, so uni's native test binary cannot link on Windows at all.
+# Compiling this one file standalone with clang is the coverage that is available there.
+set -euo pipefail
+
+shim="uni/.native/src/main/resources/scala-native/uni_curl_shim.c"
+obj="$(mktemp -d)/uni_curl_shim.o"
+
+echo "== Compiling ${shim} with $(clang --version | head -1)"
+clang -c "${shim}" -o "${obj}" -Wall -Wextra -Werror
+
+echo "== Undefined symbols"
+if [[ "${RUNNER_OS:-}" == "Windows" ]]; then
+  nm_undefined=(llvm-nm --undefined-only)
+else
+  nm_undefined=(nm -u)
+fi
+"${nm_undefined[@]}" "${obj}" | tee "${obj}.undefined"
+
+if grep -qi 'curl_easy' "${obj}.undefined"; then
+  echo
+  echo "ERROR: the shim object references libcurl symbols. Downstream Scala Native projects that do"
+  echo "not use CurlBindings never link -lcurl, so their build fails with 'undefined reference to"
+  echo "curl_easy_setopt'. Resolve the symbols at runtime instead — see issue #622 and"
+  echo "adr/2026-07-06-curl-shim-weak-linking.md."
+  exit 1
+fi
+
+echo
+echo "OK: compiles cleanly and references no libcurl symbol."

.github/workflows/test.yml

@@ -14,17 +14,28 @@ jobs:
       pull-requests: read
     outputs:
       src: ${{ steps.filter.outputs.src }}
+      native: ${{ steps.filter.outputs.native }}
     steps:
       - uses: actions/checkout@v7
       - uses: dorny/paths-filter@v4
         id: filter
         with:
           filters: |
+            # Building Scala Native on Windows costs ~15 minutes, mostly toolchain setup, so the
+            # Windows job sits behind this narrower filter: the C sources Scala Native compiles into
+            # every downstream binary, the Native-only Scala, and the Scala Native version itself.
+            native:
+              - '.github/workflows/test.yml'
+              - '**.c'
+              - '**/.native/**'
+              - 'project/**'
             src:
               - '.github/workflows/test.yml'
+              - '.github/scripts/**'
               - 'project/**'
               - '**.scala'
               - '**.sbt'
+              - '**.c'
               - '**.conf'
               - '**.json'
               - '**.js'
@@ -113,6 +124,11 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev
       - name: Scala Native test
         run: JVM_OPTS=-Xmx4g ./sbt "projectNative/test"
+      # This build passes -lcurl unconditionally, so no Scala Native job here — on any OS — can
+      # notice uni_curl_shim.c growing a reference to a libcurl symbol. Downstream projects that
+      # never link libcurl can, and their build breaks (issue #622). Check the object directly.
+      - name: Assert the curl shim references no libcurl symbol
+        run: .github/scripts/check-curl-shim.sh
       - name: Publish Test Report
         uses: mikepenz/action-junit-report@v6
         if: always() # always run even if the previous step fails
@@ -121,6 +137,25 @@ jobs:
           check_name: Test Report Scala Native
           annotate_only: true
           detailed_summary: true
+  curl_shim_c_windows:
+    # Scala Native compiles every .c under resources/scala-native/ from every jar on the classpath,
+    # so uni's uni_curl_shim.c lands in each downstream Windows binary — including ones that never
+    # call curl. Nothing else here compiles that file for Windows, which is how v2026.1.17 shipped a
+    # POSIX-only `#include <dlfcn.h>` and broke those consumers rather than this repo's CI.
+    #
+    # A full Windows Scala Native job would be the broader guard, but uni cannot run one: NativeServer
+    # uses POSIX poll(), and Scala Native's posixlib only builds poll.c on unix/Apple, so uni's native
+    # test binary fails to link on Windows with `unresolved external symbol scalanative_pollin`.
+    # Compiling this one file with the same clang/MSVC toolchain is the coverage available today.
+    name: curl shim C (Windows)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.native == 'true' }}
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compile the shim and check for libcurl symbol references
+        shell: bash
+        run: .github/scripts/check-curl-shim.sh
   package_src:
     name: Verify packageSrc
     needs: changes

adr/2026-07-06-curl-shim-weak-linking.md

@@ -33,24 +33,54 @@ either: Scala Native has no jar-level knob to conditionally include a resource
 
 ## Decision
 
-Resolve the libcurl symbols lazily via
-`dlsym(RTLD_DEFAULT, "curl_easy_setopt")` — not via C-level `extern` — inside a
-`pthread_once` initialiser that stores each pointer in a `static` cache. The
-shim's `.o` then has zero references to libcurl symbols; downstream projects
-that don't use CurlBindings link cleanly. Projects that do use CurlBindings
-still pull libcurl in via `@link("curl")` on `CurlBindings.Extern`, and
-`RTLD_DEFAULT` finds the symbols inside the already-loaded libcurl at runtime.
+Resolve the libcurl symbols lazily, at first call, from whatever is already
+loaded into the process — not via C-level `extern` — inside a run-once
+initialiser that stores each pointer in a `static` cache. The shim's `.o` then
+has zero references to libcurl symbols; downstream projects that don't use
+CurlBindings link cleanly. Projects that do use CurlBindings still pull libcurl
+in via `@link("curl")` on `CurlBindings.Extern`, and the lookup finds the
+symbols inside the already-loaded libcurl at runtime.
+
+The two primitives this needs — a lookup over all loaded modules, and a
+thread-safe run-once — are spelled differently per platform, so the file carries
+a `#if defined(_WIN32)` split:
+
+| | POSIX | Windows |
+|---|---|---|
+| lookup | `dlsym(RTLD_DEFAULT, name)` | `GetProcAddress` over `EnumProcessModules` |
+| run-once | `pthread_once` | `InitOnceExecuteOnce` |
+
+The Windows half exists because MSVC ships neither `<dlfcn.h>` nor
+`<pthread.h>`; the first version of this shim (v2026.1.17) included both
+unconditionally and broke every downstream Windows Scala Native build with
+`fatal error: 'dlfcn.h' file not found`.
 
 The function-pointer typedefs are declared variadic
 (`typedef int (*fn)(void *, int, ...)`) so the call at the shim's own call site
 still emits the correct variadic calling convention — that's what fixes the
 original CURLE_URL_MALFORMAT bug from #580, and it works exactly the same via a
 variadic function-pointer as via a variadic extern.
 
-If `dlsym` returns NULL (the shim is called from a build that somehow got the
+If the lookup returns NULL (the shim is called from a build that somehow got the
 wrappers linked in without libcurl present), the shim prints a pointer to #622
 on stderr and `abort()`s rather than jumping to NULL.
 
+Two CI additions guard this, because the file's two failure modes need two
+different checks:
+
+- **`curl_shim_c_windows`** ("curl shim C (Windows)") compiles the file standalone
+  with clang on `windows-latest`. Nothing else here compiles the Windows half of
+  the `#if`, which is how v2026.1.17's POSIX-only `#include <dlfcn.h>` shipped. It
+  runs on every push to `main` and on pull requests touching native code (the
+  `native` paths-filter): a `.c` file, anything under a `.native/` source tree, or
+  the Scala Native version in `project/`.
+- **`.github/scripts/check-curl-shim.sh`**, a step in the Linux Native job, which
+  compiles the shim standalone and asserts via `nm -u` that the object names no
+  `curl_easy_*` symbol. No Scala Native job can catch that regression on any OS:
+  `build.sbt` passes `-lcurl` unconditionally, so uni's own binaries always
+  resolve those symbols. Only a consumer that doesn't link libcurl breaks — the
+  object inspection stands in for that consumer.
+
 ## Non-obvious points a future reader would otherwise reverse-engineer
 
 ### `weak_import` / `__attribute__((weak))` on the extern is *not* a substitute
@@ -83,41 +113,101 @@ separate — but Scala Native's own `nativelib` already links both, so the shim
 inherits them. No extra linker option is required from consumers. Verified by
 inspecting Scala Native's link line (`[pthread, dl, m, crypto, curl, z]`).
 
+### A real "Scala Native on Windows" CI job would be better, and is not possible yet
+
+The obvious guard — build and run the native test suite on Windows, which would
+cover this break and any future one — was tried and abandoned. It gets the whole
+toolchain up (LLVM, vcpkg libcurl/zlib/OpenSSL, aliasing each `foo.lib` that
+`-lfoo` asks for), compiles every source *including this shim*, and then fails at
+the final link:
+
+    error LNK2019: unresolved external symbol scalanative_pollin
+      referenced in function ...wvlet.uni.http.NativeServerTest...
+    fatal error LNK1120: 5 unresolved externals
+
+`NativeServer` uses POSIX `poll()`, and Scala Native's `posixlib/poll.c` is wrapped
+in `#if defined(__unix__) || (defined(__APPLE__) && defined(__MACH__))` — the
+symbols do not exist on Windows. Every native HTTP test spins up a server, so uni's
+native test binary cannot link there at all. Giving `NativeServer` a Windows path
+(`WSAPoll`) would unblock it; until then, compiling the shim standalone is the
+Windows coverage available. Notably, that abandoned run *did* prove the shim
+compiles and links clean under clang/MSVC: none of the unresolved symbols were
+`curl_easy_*`.
+
+### Windows: why module enumeration, and why `PSAPI_VERSION 2`
+
+Windows has no `RTLD_DEFAULT`. `GetProcAddress` takes one `HMODULE` at a time,
+so the shim asks `EnumProcessModules` for every module loaded into the process
+and walks them in order — the process image comes first, matching `dlsym`'s
+search order. `GetModuleHandleA(NULL)` alone would only see the executable's own
+exports and would miss `libcurl.dll`.
+
+`#define PSAPI_VERSION 2` before `<psapi.h>` redirects `EnumProcessModules` to
+`K32EnumProcessModules`, which lives in `kernel32.dll` and so is always linked.
+Under the default (version 1) the symbol resolves out of `psapi.lib`, and a
+jar-resource `.c` file cannot make downstream binaries pass an extra linker
+flag — the exact constraint that kills the weak-symbol approach on macOS.
+`_WIN32_WINNT` is floored at `0x0600` for `InitOnceExecuteOnce` (Vista+), for
+MinGW header sets that leave it unset.
+
+`GetProcAddress` returns `FARPROC`; casting it straight to `void *` trips
+`-Wcast-function-type`, so the shim rounds it through `uintptr_t`.
+
+### Windows: libcurl must be a DLL, not a static `.lib`
+
+Runtime symbol lookup can only find *exported* symbols. A statically linked
+libcurl (vcpkg's `*-windows-static` triplets) exports nothing, so
+`GetProcAddress` returns NULL and the shim aborts with its diagnostic. Consumers
+must link libcurl dynamically — vcpkg's default `x64-windows` / `arm64-windows`
+triplets do exactly that, producing `libcurl.lib` as an import library for
+`libcurl.dll`.
+
+This is not a Windows quirk so much as the price of the whole approach: a static
+libcurl on Linux (`libcurl.a`, no `--export-dynamic`) is invisible to
+`dlsym(RTLD_DEFAULT, ...)` in precisely the same way. The old `extern`-based shim
+worked with static libcurl on both — that capability is what was traded away to
+fix #622.
+
 ### `_GNU_SOURCE` is required on glibc
 
 `RTLD_DEFAULT` is a GNU extension: glibc's `<dlfcn.h>` only defines it when
 `_GNU_SOURCE` is set. macOS libSystem exposes it unconditionally, so the macro
 is harmless there. The file defines `_GNU_SOURCE` at the top — dropping it
 would silently break Linux builds with `error: 'RTLD_DEFAULT' undeclared`.
 
-### Lazy init needs `pthread_once`, not "same value written twice"
+### Lazy init needs a run-once guard, not "same value written twice"
 
 An earlier draft argued no lock was needed because racing threads would race to
 write the same pointer value. That reasoning is wrong under C11: concurrent
 unsynchronised accesses to a non-atomic object where at least one is a write is
 a data race, i.e. undefined behaviour, regardless of the value written. The
 compiler is entitled to assume no such race exists and to re-order/eliminate
-the loads and stores accordingly. `pthread_once` gives a proper
-happens-before edge between the resolver's writes and every subsequent reader,
-at negligible cost after the first call (a plain "already done" flag check).
+the loads and stores accordingly. `pthread_once` (and `InitOnceExecuteOnce` on
+Windows) gives a proper happens-before edge between the resolver's writes and
+every subsequent reader, at negligible cost after the first call (a plain
+"already done" flag check).
 
 ### The variadic-typedef trick is the whole variadic story
 
 The C ABI's variadic calling convention is determined by the *type at the call
 site*, not by whatever the symbol on the other end was compiled as. That is why
 calling through `uni_curl_setopt_fn` (declared variadic) reproduces #580's fix
-even though the pointer was obtained from `dlsym` (which has no type
-information). Do not "simplify" the typedef to a fixed-arity signature — that
-reintroduces the CURLE_URL_MALFORMAT bug from #580.
+even though the pointer was obtained from `dlsym` / `GetProcAddress` (neither of
+which carries type information). Do not "simplify" the typedef to a fixed-arity
+signature — that reintroduces the CURLE_URL_MALFORMAT bug from #580.
 
 ## Consequences
 
 - Downstream Scala Native projects that don't use CurlBindings link cleanly
   again — #622 fixed.
-- Downstream projects that do use CurlBindings pay one `dlsym` per unique
-  wrapper on first call (three lookups total across the process's lifetime);
-  every subsequent call is a plain indirect function call.
+- Downstream projects that do use CurlBindings pay one symbol lookup per unique
+  wrapper on first call (two lookups total across the process's lifetime); every
+  subsequent call is a plain indirect function call. On Windows a lookup also
+  walks the loaded-module list, which is still a once-per-process cost.
 - CurlBindings' `@link("curl")` remains load-bearing — it's how libcurl actually
   gets into the process. Do not remove it.
-- Removing the shim `.c` file, or any `dlfcn`/`stdio` include, would regress
-  either the ABI fix or the link-error fix; keep both.
+- libcurl must be linked dynamically. Statically linked libcurl no longer works
+  on any platform, Windows included; see above.
+- Removing the shim `.c` file, or any of its includes, would regress either the
+  ABI fix, the link-error fix, or the Windows build; keep all three. The
+  "Scala Native (Windows)" job and `check-curl-shim.sh` are what notice.

adr/README.md

@@ -12,4 +12,4 @@ Read the relevant ADR before modifying the area it covers. Add a new entry here
 - [`2026-06-30-sbt-uni-crossproject.md`](2026-06-30-sbt-uni-crossproject.md) — the `sbt-uni-crossproject/` build: a minimal, uni-owned sbt 2.x re-implementation of `portable-scala/sbt-crossproject` (which isn't ported to sbt 2.x), supporting only the `CrossType.Pure` layout uni uses. Read before touching that build; covers the single-plugin-for-all-three-platforms choice, the Scala 3 val-name macro replicating sbt's `KeyMacro.definingValName`, why internal materialization needs `new CrossProject(...)`, and the `given Conversion[Builder, CrossProject]` build trigger.
 - [`2026-06-30-sbt2-main-build-migration.md`](2026-06-30-sbt2-main-build-migration.md) — migrating the **main build** to sbt 2.x: swaps the unported third-party plugins for the uni-owned ones (`sbt-uni-crossproject`, `uni-jsenv-playwright`, `sbt-uni` for `sbt-revolver`). Read before touching `build.sbt` / `project/plugin.sbt`; covers the output-dir name collision (root → `uni-root`), `%%%`→`%%` and the `scalajs-test-interface_2.13` single-`%` exception, `Def.uncached` for `jsEnv`, and the `implicitConversions` import.
 - [`2026-07-06-plugin-extension-points.md`](2026-07-06-plugin-extension-points.md) — `wvlet.uni.plugin` is built on typed `ExtensionPoint`s (identity-compared singletons; keyed points reject duplicate ids at activation), with `PluginContext` reduced to `contribute` + `onDeactivate`. Read before adding new contribution kinds: define a point next to the contributed type (`Command.point`, `RPCPlugin.routerPoint`) so dependency arrows point into `plugin`, never out of it.
-- [`2026-07-06-curl-shim-weak-linking.md`](2026-07-06-curl-shim-weak-linking.md) — `uni_curl_shim.c` resolves libcurl's variadic setopt/getinfo via `dlsym(RTLD_DEFAULT, ...)` inside a `pthread_once` init, not C-level `extern`s, so downstream Scala Native builds that don't use `CurlBindings` still link (issue #622). Read before touching the shim: covers why `__attribute__((weak))` on the extern fails on macOS, why `RTLD_DEFAULT` (not `dlopen`) is the right lookup, why the variadic-typedef ABI trick from #580 is still load-bearing, why `_GNU_SOURCE` is required on glibc, and why lazy init needs `pthread_once` not just "same value written twice".
+- [`2026-07-06-curl-shim-weak-linking.md`](2026-07-06-curl-shim-weak-linking.md) — `uni_curl_shim.c` resolves libcurl's variadic setopt/getinfo from the process's already-loaded modules (`dlsym(RTLD_DEFAULT, ...)` on POSIX, `GetProcAddress` over `EnumProcessModules` on Windows) inside a run-once init, not C-level `extern`s, so downstream Scala Native builds that don't use `CurlBindings` still link (issue #622). Read before touching the shim: covers why `__attribute__((weak))` on the extern fails on macOS, why `RTLD_DEFAULT` (not `dlopen`) is the right lookup, why MSVC needs the whole `#if defined(_WIN32)` half (no `<dlfcn.h>`/`<pthread.h>`) and `PSAPI_VERSION 2`, why libcurl must now be linked dynamically, why the variadic-typedef ABI trick from #580 is still load-bearing, why `_GNU_SOURCE` is required on glibc, why lazy init needs a run-once guard not just "same value written twice", why a real Scala Native Windows CI job is impossible today (`NativeServer` needs POSIX `poll`), and why guarding this takes a standalone clang compile plus a separate `nm` check (the build's unconditional `-lcurl` blinds every native job to the #622 regression).

docs/guide/installation.md

@@ -26,6 +26,13 @@ libraryDependencies += "org.wvlet.uni" %%% "uni" % "__UNI_VERSION__"
 libraryDependencies += "org.wvlet.uni" %%% "uni" % "__UNI_VERSION__"
 ```
 
+::: tip Scala Native and libcurl
+No system libraries are needed to build a Scala Native binary against uni. Only
+reaching for the HTTP client pulls in libcurl, which must then be present as a
+shared library — see
+[Linking libcurl on Scala Native](../http/client.md#linking-libcurl-on-scala-native).
+:::
+
 ## Imports
 
 Common imports for getting started: