--- name: solnix-porter description: > Port Linux software to Solnix and illumos, or package it as a Solnix recipe: configure/cmake/meson platform detection, undefined socket or getaddrinfo symbols (-lsocket -lnsl), the illumos link editor (RUNPATH, $ORIGIN, mapfiles, elfdump, elfedit, lari), epoll vs event ports, sendfile and /proc differences, GNU vs /usr/xpg4 tools in build scripts, wrong-endianness configure probes under gcc 14, leaks with libumem, crashes with mdb, LX zones vs a native port. Use when a build fails or a binary misbehaves on Solnix, or when writing a recipe. license: CC0-1.0 metadata: author: solnix version: "0.2.0" persona: porter --- # Solnix: porter and app developer Porting to Solnix is porting to illumos (its libc, its link editor, its kernel APIs), then packaging the result as a Nix derivation for `x86_64-solaris` (and `aarch64-solaris`). Most failures fall in a few classes; the rules below each name one, with the fix and the evidence. Read `steering/solnix-is-not-upstream-illumos.md` (repo root) first. ## Tools this uses - This server: `find_skill`, `search_manpages`, `translate_command`, `package_status`, `search_packages`, `package_dependencies`, `search_handbook`; and for what illumos itself does (a header, a libc function, why a flag exists): `illumos_search_code`, `illumos_commits`, `illumos_blame`, `illumos_issue`, `illumos_issues`. - On the machine: `nix build`, `elfdump`, `elfedit`, `ldd`, `lari`, `mdb`, `gcore`, `dtrace`, `uname`. ## Steps 1. **Classify the failure.** Find the first error in the build log or `config.log` (not the last), and match it to a row of the table below. Done when you have the error line quoted and one rule picked, or "none" (then `search_manpages` for the failing symbol, and `illumos_search_code {query: }` to see where illumos defines it). 2. **Read the rule.** Done when you know the Solnix fix and how the illumos way differs. 3. **Check what is already packaged.** `package_status {pname}` for the software and its dependencies: is a version served, built, queued? `package_dependencies` for what links it. Done when you know whether you are porting from scratch or fixing a served recipe. 4. **Fix in the source of the build, not the result.** A configure cache variable, a patch, a `-lsocket -lnsl`, a `-R` path. Edit a built binary (`elfedit`) only to diagnose, or in a build hook. Done when a clean `nix build` of the attribute succeeds. 5. **Prove it runs.** Run the rule's **Check** (`elfdump -d` shows the RUNPATH, `ldd` resolves every library, the test that exposed the bug passes). Done when you have pasted the output. 6. **Package it.** Follow `recipe-write-a-solnix-recipe.md`. Done when the recipe row or derivation and its test are ready for the build team. ## Failure classes (`../rules/`) | symptom | rule | |---|---| | configure picks the wrong OS branch; cmake/meson don't know the platform | `build-autotools-cmake-meson.md` | | `ld: fatal: symbol referencing errors` naming `socket`, `getaddrinfo` or `gethostbyname` | `link-lsocket-lnsl.md` | | `ld.so.1: ... fatal: libfoo.so.1: open failed`; binary works only with `LD_LIBRARY_PATH` | `link-runpath-origin.md` | | `--version-script` rejected; symbol visibility or versioning questions | `link-mapfiles-and-lari.md` | | epoll behaving oddly, `kqueue` missing, inotify file watching | `api-event-ports-vs-epoll.md` | | `sendfile` signature, `/proc/self/...` text files, pthread or glibc-only calls | `api-sendfile-proc-pthreads-libc.md` | | `sed --in-place`, `sed -i ''`, `grep -P`, `date -d` fail in a build script | `shell-xpg4-vs-gnu.md` | | "checking endianness... big" on x86/aarch64; numbers or hashes wrong at run time | `build-endianness-probe-trap.md` | | a configure test quietly fails after a compiler upgrade | `build-gcc14-implicit-declarations.md` | | the program can't be ported; only a Linux binary exists | `lx-vs-native.md`, `zones-lx.md` | | memory grows; heap corruption; double free | `debug-libumem-leaks.md` | | it crashed and left a core | `debug-mdb-postmortem.md` | | package it for Solnix | `recipe-write-a-solnix-recipe.md` | ## Facts that save time - The GNU triple is `x86_64-unknown-solaris2.11`; `uname -s` says `SunOS`; CMake calls it `SunOS`, Meson `sunos`. illumos is not Linux and not a BSD to configure. - The base tools (`sed`, `grep`, `ls`) are illumos, not GNU. Never assume GNU-only flags (`sed --in-place`, `grep -P`) in a build; `shell-xpg4-vs-gnu.md` says how to check. - Use `elfedit` and `elfdump`, not `patchelf`/`readelf` (the build team's steering says the GNU tools will not work; GNU `readelf` is only in `pkgs.solnix.binutils`). - Daemons ship as `smf.services` declarations, not systemd units. ## Reference - [handbook: how Solnix is built](https://solnix.io/docs/handbook/how-solnix-is-built), [handbook: debugging](https://solnix.io/docs/handbook/debugging). - [illumos Developer's Guide](https://illumos.org/books/dev/), [Modular Debugger Guide](https://illumos.org/books/mdb/) (PDL). - Man pages `ld(1)`, `ld.so.1(1)`, `elfdump(1)`, `port_create(3C)`, `umem_debug(3MALLOC)` at `https://solnix.io/docs/man/.
`.