Add musl libc support (Alpine/OpenWrt) with Alpine E2E (#31)

Author: linghengqian

.github/workflows/e2e.yml

@@ -42,6 +42,21 @@ jobs:
           persist-credentials: false
       - run: docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 
+  e2e-linux-musl:
+    if: github.repository == 'version-fox/vfox-nodejs'
+    name: Linux musl container (${{ matrix.runs-on }})
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on: [ubuntu-latest, ubuntu-26.04-arm]
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - run: docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+
   e2e-windows:
     if: github.repository == 'version-fox/vfox-nodejs'
     name: Windows container (${{ matrix.runs-on }})

README.md

@@ -14,9 +14,23 @@ vfox add nodejs
 
 ```bash
 vfox add nodejs
-vfox install nodejs@26.10.0
+vfox install nodejs@26.11.1
 sudo apt install --assume-yes libatomic1
-vfox use --global nodejs@26.10.0
+vfox use --global nodejs@26.11.1
+```
+
+Note: the `libatomic1` step works around an upstream Node.js packaging bug
+([nodejs/node#60790](https://github.com/nodejs/node/issues/60790), still
+open): Node 25+ links `libatomic.so.1`, which stock Debian/Ubuntu images do
+not ship. System libraries are the user's responsibility; the plugin does
+not install them.
+
+### Example: Alpine / musl
+
+```bash
+vfox add nodejs
+vfox install nodejs@26.11.1
+vfox use --global nodejs@26.11.1
 ```
 
 You can verify this using the following command:
@@ -25,11 +39,23 @@ You can verify this using the following command:
 node -v
 ```
 
+musl details (OpenWrt, tarball matrix, mirror fallback): see [docs/musl.md](docs/musl.md).
+
 ## Mirror
 
 See [docs/mirror.md](docs/mirror.md) for details.
 
-## Testing
+## FAQ
+
+### Install from source
+
+See [docs/source-build.md](docs/source-build.md) for details.
+
+### LTS
+
+See [docs/lts.md](docs/lts.md) for details.
+
+### Testing
 
 See [docs/e2e.md](docs/e2e.md) for details.
 

docs/e2e.md

@@ -20,14 +20,16 @@ driven from Go through `docker exec`-style calls):
 3. A pinned Node.js release installs with checksum verification and runs
    (`node --version`, `npm --version`, `process.platform`, `process.arch`),
    so the `linux-x64` / `linux-arm64` / `win-x64` / `win-arm64` package
-   selection is checked for real.
+   selection is checked for real. The LTS release (`LTS_NODE_VERSION`)
+   installs as well, backing the codename probe below.
 4. `nodejs@latest` resolves through the plugin's `Available` list (the
    first, newest entry) and installs.
 5. The major and major.minor shorthands resolve through `PreUse` against the
    installed versions.
 6. `.nvmrc` and `.node-version` drive `vfox env` selection: the exact
-   version under the default `specified` strategy, and an LTS codename
-   (`lts/<codename>`) under `latest_installed`. Each legacy probe activates
+   pinned version under the default `specified` strategy, and an LTS
+   codename (`lts/<codename>`, see [lts](lts.md)) resolving to the LTS
+   release under `latest_installed`. Each legacy probe activates
    inside its own shell so the selection is recomputed rather than answered
    from the `vfox env` state cache of an earlier probe.
 7. `vfox search nodejs` lists the installed release with the same npm
@@ -49,9 +51,11 @@ pin `VFOX_VERSION` and `MIRROR` explicitly to widen or narrow the matrix.
 | ------------------- | ------------------ | ----------------------------------------------------------------------- |
 | `VFOX_VERSION`      | `latest main`      | Space-separated vfox channels (`latest`, `main`)                        |
 | `MIRROR`            | see matrix above   | Space-separated mirrors; `default` means `nodejs.org`                   |
-| `NODE_VERSION`      | `22.23.3`          | Pinned Node.js release installed by the suite                           |
+| `NODE_VERSION`      | `26.11.1`          | Pinned Node.js release installed by the suite                           |
+| `LTS_NODE_VERSION`  | `24.21.0`          | LTS release backing the `lts/<codename>` probe (see docs/lts.md)        |
 | `E2E_MAX_JOBS`      | `3` (Linux), `2` (Windows) | Parallel containers per host                                     |
 | `E2E_RETRY_ATTEMPTS`| `3`                | Attempts per network-touching exec (linear 10s backoff)                 |
+| `E2E_LINUX_BASE`    | `ubuntu`           | Linux userland: `ubuntu` (glibc) or `alpine` (musl, see docs/musl.md)   |
 
 ## Ubuntu
 
@@ -81,6 +85,22 @@ cd ./vfox-nodejs/
 DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock" docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 ```
 
+## Alpine (musl)
+
+Same host requirement. The Alpine suite builds
+`tests/e2e/linux/Dockerfile-alpine` (musl userland with `libstdc++`) and
+asserts the musl userland before running the standard flow, proving the
+plugin selects the `*-musl` tarballs
+([issue #29](https://github.com/version-fox/vfox-nodejs/issues/29)).
+See [docs/musl.md](musl.md) for the tarball matrix.
+
+```bash
+docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+```
+
+Scope it down locally the same way, e.g.
+`VFOX_VERSION=latest MIRROR=default E2E_MAX_JOBS=1` in front of the command.
+
 ## Windows 11 Pro
 
 Windows containers cannot be emulated across architectures, so the ARM64
@@ -99,13 +119,15 @@ combinations still run with an unspaced home.
 
 ### x64
 
-1. Execute in Windows PowerShell 5.1,
+All commands below run in PowerShell 7. If it is not installed yet, install
+it first (this single bootstrap command may run in the built-in Windows
+PowerShell):
 
 ```powershell
 winget install --id Microsoft.PowerShell --source winget --exact
 ```
 
-2. Execute in PowerShell 7,
+1. Execute in PowerShell 7,
 
 ```powershell
 winget install --id Git.Git --source winget --exact
@@ -116,13 +138,13 @@ curl.exe -fsSL `
     -o ./install-docker-ce.ps1
 ```
 
-3. Execute in PowerShell 7 with administrator privileges,
+2. Execute in PowerShell 7 with administrator privileges,
 
 ```powershell
 ./install-docker-ce.ps1
 ```
 
-4. Execute in PowerShell 7,
+3. Execute in PowerShell 7,
 
 ```powershell
 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\cli-plugins" | Out-Null
@@ -138,13 +160,15 @@ docker compose -f tests/e2e/windows/compose.amd64.yaml run --rm --build e2e
 
 ### arm64
 
-1. Execute in Windows PowerShell 5.1,
+All commands below run in PowerShell 7. If it is not installed yet, install
+it first (this single bootstrap command may run in the built-in Windows
+PowerShell):
 
 ```powershell
 winget install --id Microsoft.PowerShell --source winget --exact
 ```
 
-2. Execute in PowerShell 7,
+1. Execute in PowerShell 7,
 
 ```powershell
 winget install --id Git.Git --source winget --exact

docs/lts.md

@@ -0,0 +1,97 @@
+# LTS releases
+
+Node.js majors with even numbers become **LTS** (long-term support) lines:
+they keep receiving fixes long after odd releases go end-of-life, so most
+production setups pin an LTS line. Each LTS line has a codename
+(`argon` for 4, `boron` for 6, …, `krypton` for 24).
+
+## What this plugin understands
+
+Under the `latest_available` strategy the plugin discovers LTS codenames
+dynamically from the version index (`index.json` carries the codename in
+each release's `lts` field), so codenames that postdate this plugin keep
+working there. Everywhere else — and as the offline fallback — a hardcoded
+table in `hooks/parse_legacy_file.lua` is used, because `specified` and
+`latest_installed` must resolve without network access:
+
+| Codename | Major |
+| -------- | ----- |
+| argon | 4 |
+| boron | 6 |
+| carbon | 8 |
+| dubnium | 10 |
+| erbium | 12 |
+| fermium | 14 |
+| gallium | 16 |
+| hydrogen | 18 |
+| iron | 20 |
+| jod | 22 |
+| krypton | 24 |
+
+## Examples
+
+Given an `.nvmrc` (the same applies to `.node-version`) and
+`22.23.3` plus `24.21.0` installed:
+
+```sh
+# 1. LTS codename -> major, then strategy picks the release.
+$ cat .nvmrc
+lts/jod
+$ vfox config legacyVersionFile.strategy latest_installed
+$ cd <dir-with-.nvmrc> && eval "$(vfox activate bash)" && eval "$(vfox env -s bash)" && node --version
+v22.23.3
+```
+
+```sh
+# 2. Bare `lts` (or `lts/*`) means "the highest mapped major", currently 24.
+$ printf 'lts\n' > .nvmrc
+$ cd <dir-with-.nvmrc> && eval "$(vfox activate bash)" && eval "$(vfox env -s bash)" && node --version
+v24.21.0
+```
+
+```sh
+# 3. An exact version skips the codename table entirely.
+$ printf '22.23.3\n' > .nvmrc
+$ cd <dir-with-.nvmrc> && eval "$(vfox activate bash)" && eval "$(vfox env -s bash)" && node --version
+v22.23.3
+```
+
+```sh
+# 4. The current LTS line works the same way.
+$ printf 'lts/krypton\n' > .nvmrc
+$ cd <dir-with-.nvmrc> && eval "$(vfox activate bash)" && eval "$(vfox env -s bash)" && node --version
+v24.21.0
+```
+
+```sh
+# 5. Under latest_available the index is consulted, so even a codename
+# newer than the table above resolves (offline it falls back to the table).
+$ vfox config legacyVersionFile.strategy latest_available
+$ printf 'lts/<future-codename>\n' > .nvmrc
+$ cd <dir-with-.nvmrc> && eval "$(vfox activate bash)" && eval "$(vfox env -s bash)" && node --version
+v<newest release carrying that codename>
+$ vfox config legacyVersionFile.strategy specified
+```
+
+How example 1 resolves, step by step (`latest_installed`):
+
+```
+.nvmrc "lts/jod" --resolve_version--> "22" --prefix-match installed--> "22.23.3"
+```
+
+## E2E coverage
+
+The legacy-file suite needs an installed release whose major is inside the
+table, independently of the pinned release under test. `LTS_NODE_VERSION`
+(default `24.21.0`) provides it: the exact-version probes target
+`NODE_VERSION` while the `lts/<codename>` probe targets the LTS release.
+
+```sh
+# Narrow the matrix and watch the codename probe pick the LTS release:
+VFOX_VERSION=latest MIRROR=default E2E_MAX_JOBS=1 LTS_NODE_VERSION=24.21.0 \
+  docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+# PASS legacy files select 26.11.1 (.nvmrc, .node-version) and 24.21.0 (lts/krypton)
+```
+
+The E2E `LTSCodename` helper (`tests/e2e/common/common.go`) mirrors the
+plugin's table, so both sides stay in sync. See [e2e](e2e.md).

docs/mirror.md

@@ -6,10 +6,27 @@ are downloaded from `https://nodejs.org/dist` by default. Set
 
 ```bash
 export VFOX_NODEJS_MIRROR="https://npmmirror.com/mirrors/node"
-vfox install nodejs@22.23.3
+vfox install nodejs@26.11.1
 ```
 
 Point it at the root that mirrors `nodejs.org/dist`; the plugin appends its
 paths (`/index.json`, `/v<version>/...`) to that base URL. Trailing slashes
 are handled, so both `https://nodejs.org/dist` and `https://nodejs.org/dist/`
 work.
+
+## musl and unofficial builds
+
+`VFOX_NODEJS_MIRROR` only covers `nodejs.org/dist`. It does **not** apply to
+`https://unofficial-builds.nodejs.org/download/release`, which the plugin
+uses as a fallback on musl Linux (see [musl](musl.md)):
+
+- Linux musl x64 on a recent release (`26.8+`, `24.20+`, `22.23.3+`): the
+  official `*-musl` tarball is used, so the mirror applies normally (as long
+  as the mirror carries it).
+- Linux musl arm64 (all releases), or musl x64 on an older release: the
+  official index has no such file, so the plugin downloads from
+  `unofficial-builds.nodejs.org` directly, ignoring the mirror.
+
+A mirror that cannot even serve `SHASUMS256.txt` still fails the install
+instead of falling back (this is covered by the bogus-mirror negative probes
+in [e2e](e2e.md)); only a missing musl filename falls through to unofficial.

docs/musl.md

@@ -0,0 +1,55 @@
+# musl libc support (Alpine, OpenWrt/ImmortalWrt)
+
+Node.js official Linux tarballs link glibc (`ld-linux-*`). On musl systems
+there is no glibc loader, so the stock download fails with `not found` /
+`Error loading shared library ld-linux-aarch64.so.1`.
+See [issue #29](https://github.com/version-fox/vfox-nodejs/issues/29).
+
+This plugin detects musl and installs a musl tarball instead.
+
+## Requirements
+
+The musl builds link `libstdc++`, which musl distributions normally install
+automatically alongside the rest of the system toolchain, so there is
+usually nothing extra to do. If `node --version` ever fails with
+`Error relocating ... symbol not found`, the system is missing its
+`libstdc++` (`libstdcpp` on OpenWrt) runtime. The plugin's `PostInstall`
+hook detects this case and fails the install with a pointer at the README
+instead of leaving the cryptic relocation error.
+
+## Which tarball is installed
+
+| Host | Tarball | Source |
+| ---- | ------- | ------ |
+| Linux glibc, x64/arm64 | `node-v<V>-linux-x64.tar.gz` etc. | `nodejs.org/dist` |
+| Linux musl, x64 | `node-v<V>-linux-x64-musl.tar.gz` | official index when present, else unofficial |
+| Linux musl, arm64 | `node-v<V>-linux-arm64-musl.tar.gz` | `unofficial-builds.nodejs.org` (official never ships it) |
+
+Notes:
+
+- Official `nodejs.org/dist` only carries `linux-x64-musl` for recent
+  releases (roughly `26.8+`, `24.20+`, `22.23.3+`) and never carries
+  `linux-arm64-musl`. Older releases and all `arm64-musl` installs fall back
+  to `https://unofficial-builds.nodejs.org/download/release` automatically.
+- Mirror behavior on musl (when the mirror applies, when unofficial is
+  used): see [mirror](mirror.md).
+- musl builds exist only for `x64` and `arm64`. Other Linux architectures
+  (e.g. `x86`) error out with a pointer to the README.
+- After install the plugin returns a note pointing at the README so the
+  `libstdc++` requirement is visible in normal `vfox install` output.
+
+## Detection and override
+
+Detection order in `lib/util.lua`:
+
+1. `$VFOX_NODEJS_LIBC`: `musl` forces musl, `gnu`/`glibc` forces glibc.
+   Useful on exotic userlands and in tests.
+2. `RUNTIME.envType` when a future vfox core provides it (`musl`/`gnu`).
+3. File probes readable from Lua: `/etc/alpine-release`,
+   `/lib`/`/usr/lib`/`/lib64` `ld-musl-*.so.1`. musl wins when both linkers
+   exist (e.g. `gcompat` shims). Non-Linux is never musl.
+
+```sh
+# Force musl selection (debugging only)
+VFOX_NODEJS_LIBC=musl vfox install nodejs@26.11.1
+```