Fissuredocumentation v5.3.1
On this page

Fissure portability status

Fissure is Linux-first (src/fissure_platform.h). This document is the status of the native Windows port under MSYS2 (mingw64 / ucrt64), the only supported Windows target (no Cygwin). It is the single place the port state lives; docs/TODO.md tracks only the work that is still outstanding, and the completed slices are archived in docs/TODO_DONE.md.

Summary

The port is code-complete for everything that can be verified without a Windows toolchain-with-dependencies. A full-source cross-compile audit with the mingw-w64 cross compiler on Linux (x86_64-w64-mingw32-gcc, GCC 15, the same headers/CRT MSYS2 uses) gives:

Result Count (of 239 src/*.c, snapshot of the last make winsweep run)
Compile clean for the Windows target 107
Fail ONLY on a missing dependency HEADER (openssl/allegro/pcre2/libxml/xmlsec/yaml) 132
Real portability bugs 0

That table is a snapshot, not a standing guarantee: it is only true of the files that existed when the sweep was last run. Three real Windows errors reached a build afterwards, all in files added after it ran, all of the kinds this document already warns about: a bare two-argument mkdir in fissure_extstate.c, memmem without fissure_compat.h in fissure_rawedit.c, and FISSURE_PATH_MAX used from a Windows-only branch that included fissure_paths.h instead of fissure_constants.h in fissure_tls.c. The recipe below catches all three, and it caught a fourth on its next run: strcasestr in fissure_cspt.c without nilorea/n_str.h, which is where the portable declaration lives. <strings.h> has it on glibc and mingw does not, so the file built on Linux for several steps and would have failed on Windows. Re-run it whenever a src/*.c file is added, or the table silently ages into a false claim of a clean tree.

Read the gated count as a limit on the claim, not a footnote to it. A change can be "sweep clean" and still be entirely unchecked for Windows: of eight files one recent sequence touched, four were checked and four (fissure_js.c, fissure_checks.c, fissure_control.c, fissure_oast.c) were gated on openssl/err.h and never compiled for the target at all. The sweep says what it managed to check, and the honest reading of a clean result is "nothing was found in the half it can see".

The 132 dependency-gated files cannot be cross-compiled on a bare Linux box because those headers are MSYS2 pacman packages, not present in the cross toolchain. They are not portability bugs; they compile on a real MSYS2 install that has the packages.

That gating is now lifted for a full cross build. make windows (see "Cross-compiling on Linux" below) builds a dependency sysroot under external/mingw/ (prebuilt Allegro plus from-source openssl/pcre2/libyaml/libxml2/xmlsec1) and cross-links the whole program into fissure.exe on a plain Linux box. make windows-check cross-compiles every one of the 239 units against that sysroot, so the 132 formerly-gated files ARE compiled for the Windows target off-target now; what still needs a Windows desk is runtime behaviour, not compilation (see "What remains"). The syntax-only make winsweep is kept as the quick no-dependencies filter for a fast edit loop.

Nilorea itself is already portable (n_network wraps Winsock under __windows__, n_common defines WEXITSTATUS/WIFEXITED for Windows). All the port work is Fissure-owned code. This is internal plumbing, exempt from the control-API + MCP + skill parity rule (it exposes no new automatable capability), but each slice ships with a test and keeps the Linux build green.

Done

  • Subprocess model (src/fissure_proc.{h,c}). A Fissure-owned portable subprocess layer, POSIX and _WIN32 backends for every call-site shape: fissure_proc_run_wait (fork/exec/waitpid vs _spawnvp(_P_WAIT), optional null-stdio), fissure_proc_open_path (double-fork xdg-open vs ShellExecute, -lshell32), fissure_proc_spawn_detached + fissure_proc_kill_pid (setsid daemon + kill(-pid) vs CreateProcess(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP) + OpenProcess/TerminateProcess by pid, so no process handle needs threading back), fissure_proc_signal_pid, and fissure_proc_capture (the pipe-capture + timeout + process-group cancel path: POSIX pipe/fork vs Windows CreatePipe / CreateProcess / WaitForSingleObject). Every caller is migrated: fissure_plugin_run.c, fissure_gui_plugins.c, fissure_cdp.c, fissure_pdf.c, fissure_gui_main.c, and fissure_browser.c (its default_launch is #ifdef _WIN32-guarded, <sys/wait.h> is under #ifndef _WIN32). tests/test_proc covers exit codes, null-stdio, and a no-timeout capture cancelled by signalling its published pid. fissure_proc.c and fissure_browser.c cross-compile for the Windows target.

  • Sockets (src/fissure_net.h). The socket-compat header: portable SOCKET/closesocket/INVALID_SOCKET (Winsock on Windows, BSD on POSIX), SHUT_* mapped to SD_*, MSG_NOSIGNAL to 0, and a FISSURE_POLL name for poll/WSAPoll. All raw-socket files go through it: fissure_cancel, fissure_server, fissure_oast, fissure_cdp, fissure_wsrepeater, fissure_rawrelay, fissure_groupsend, fissure_engine, fissure_proxy. Socket fds are SOCKET (not int, which truncates a Win64 handle); each SO_RCVTIMEO/SO_SNDTIMEO is a _WIN32 DWORD of milliseconds vs a POSIX struct timeval, which fissure_socket_recv_timeout() in src/fissure_compat.h hides: call it rather than writing the #ifdef again, because passing a timeval to Winsock sets NO timeout at all and the mistake is silent. Nilorea starts Winsock inside netw_connect / netw_make_listening, so code that opens a raw socket instead calls fissure_sockets_init() first (a no-op on POSIX) or every socket() fails with WSANOTINITIALISED. Close one with fissure_socket_close(): on Windows a SOCKET is a handle from a different space than the CRT's file descriptors, so close() on one leaks it and can trip the CRT's invalid-parameter handler. Prerequisite Nilorea htonll/ntohll fix is on nilorea next.

  • DNS (src/fissure_dns.c). Dual-path: POSIX res_* and a _WIN32 DnsQuery path. The Makefile links PLATFORM_LIBS (-lresolv on Linux, -ldnsapi -lws2_32 -lshell32 on Windows).

  • libc gaps (src/fissure_compat.h, src/fissure_platform.h). fissure_compat.h supplies memmem, gmtime_r/localtime_r, getline, mkstemps, lstat, fchmod under _WIN32, plus a portable fissure_strndup (a new name on both platforms: the mingw-w64 CRT does not declare strndup under -std=c99, and whether it does varies by toolchain, so a same-name shim would clash on some). fissure_platform.h supplies FISSURE_MKDIR (1-arg _mkdir on Windows), FISSURE_PATH_SEP, and fissure_time_us (_ftime64 vs gettimeofday). Nilorea's n_str provides a portable strcasestr.

  • Packaging (make installer-windows). Bundles the MinGW/Allegro runtime DLLs (resolved with ldd) into packaging/dlls, generates the HTML docs, and compiles an NSIS setup.exe from packaging/installer.nsi. The decision was an NSIS installer (not a zip), mirroring the .deb/AppImage layout, minus the bundled Chromium (Windows uses a system-installed Chrome/Chromium if present). The Makefile handles the Windows target: PLATFORM_LIBS, -D_WIN32_WINNT=0x0600, the .exe suffix, windres for the icon and the version resource, and -mwindows (WIN_SUBSYSTEM) so no console window opens behind the GUI. The packaged files are stripped and signed; see "Signing the Windows build".

Building on Windows (MSYS2 mingw64 / ucrt64)

pacman -S mingw-w64-ucrt-x86_64-toolchain \
          mingw-w64-ucrt-x86_64-allegro \
          mingw-w64-ucrt-x86_64-openssl \
          mingw-w64-ucrt-x86_64-pcre2 \
          mingw-w64-ucrt-x86_64-zlib \
          mingw-w64-ucrt-x86_64-libyaml \
          mingw-w64-ucrt-x86_64-libxml2 \
          mingw-w64-ucrt-x86_64-xmlsec
# QuickJS is bundled in the tree; nothing to install for it.
make                    # builds fissure.exe
make installer-windows  # bundles DLLs + docs, produces dist/fissure-<ver>-setup.exe

The build needs the Nilorea sibling checkout at ../../nilorea-library (on the next branch, which carries the htonll/ntohll winsock fix and the connect-abort callback).

Known Windows gotchas (already handled)

  • shutdown() does not reliably wake a thread blocked in accept() or recvfrom() on Winsock, though it does on POSIX. Code that stops a worker by setting a flag and shutting its socket down therefore joins a thread that never returns, and the symptom is a hang with nothing to read: the test or the run is killed at its timeout. Two portable ways out, both used here: poke the listener with a throwaway connection so accept returns (the thread then sees the flag), or give the socket a short receive timeout so the blocking call comes back on its own and the loop re-reads the flag. The proxy's accept loop already worked around this; tests/test_rawrelay and tests/test_control do now too.

  • A path walk must step over the drive designator. C:/Users/x walked component by component from index 1 asks the CRT to create C:, which is not a directory to make but a reference to the current directory on that drive: _mkdir refuses it with EACCES, not EEXIST. fissure_paths_mkdirs therefore gave up on its first component and Fissure could not create its configuration directory at all, on every real run, since every %APPDATA%-derived path carries a drive letter. Worth remembering how it hid: the tests only exercised the location XDG_CONFIG_HOME redirects to, and MSYS2 hands a test a drive-less /tmp/... for that, so the branch a real run takes was never covered. A test that redirects a path should also test the platform's own default.

  • A filesystem path is not safe to paste into a JSON body. Windows paths hold backslashes, and "file":"D:\a\_temp\tmp" inside a JSON string is a run of escapes: \a and \_ are not valid ones and \t is a TAB. Escape the path (or build the JSON with a real encoder) or the request is rejected for a body you believe you built correctly.

  • The repository must check out with its bytes unchanged. Git on Windows defaults to core.autocrlf=true and rewrites every LF into CRLF in the working tree, which breaks anything byte-exact: the signed extension marketplace verifies an Ed25519 signature over the catalog and a sha256 per bundle, and the HTTP fuzz corpora under tests/fuzz/corpus are wire captures whose CRLFs are the protocol rather than the file format. It also broke a parser: test_control_routes reassembles the MCP tool signatures from the bridge and the skill catalog, and a stray CR made every argument on a wrapped line read as drift (42 phantom failures). A root .gitattributes with * -text pins the bytes on every platform; the parser drops a CR as well, so a working tree that already has CRLF still reads correctly.

  • rename() does not replace an existing file. The UCRT's rename fails with EEXIST where POSIX replaces atomically, so the write-a-temporary-then-rename idiom lands the first write of a fresh file and fails every rewrite after it. That is what every persisted store does, so settings, shortcuts, sessions, projects and the cookie jar could be created once and never updated. fissure_paths_write_atomic delegates to nilorea's n_file_write_atomic, which uses MoveFileEx with MOVEFILE_REPLACE_EXISTING there.

  • There are no POSIX permission bits. Windows synthesises st_mode from the read-only attribute, so a file written 0600 does not report 0600; what protects it is the ACL it inherits from its directory. Assert the mode on POSIX only.

  • The OSS-tool plugin subsystem is compiled out (FISSURE_HAS_PLUGINS is 0): plugins run external tools that a Unix-shell dependency manager installs. A test for it exits 77, which the suite runner reports as SKIPPED rather than counting as a pass.

  • The configuration directory must NOT come from $HOME. MSYS2 sets HOME to a path inside its own installation, so a $HOME/.config/fissure tree put the proxy CA, the projects, the scan history and the settings under C:/msys64/home/<user>/. That was survivable inside an MSYS2 shell and fatal outside one: launched from Explorer, the Start Menu or a plain cmd, HOME is not set at all, fissure_paths_config_dir returned -1, and the program came up as a fresh install with no CA and none of the operator's work, with nothing on screen to say why. fissure_paths_config_dir now resolves %APPDATA%/Fissure, then %USERPROFILE%/.config/fissure, then $HOME (in that order, after XDG_CONFIG_HOME, which still overrides everything on both platforms). Two details the first attempt would get wrong: the Windows variables hold BACKSLASH paths, which fissure_paths_mkdirs walks looking for FISSURE_PATH_SEP ('/' on both platforms) and would treat as a single component, so the value is normalized on the way in; and an existing MSYS2-shell tree is moved to the new location on the first run rather than orphaned, with fissure_paths_config_notice() reporting on screen what moved, or where the old tree still is when the move could not be made.

  • Browser CA trust is a different mechanism, not a missing one. Chromium on Linux reads user certificates from an NSS database, which the launcher seeds inside the throwaway profile with certutil; Chrome and Edge on Windows read the Windows certificate store and have no per-profile database at all. Running the NSS path there fails twice over: the find_certutil PATH walk splits on ':', which is a drive separator rather than a list separator on Windows, and the certutil.exe a Windows PATH does resolve is Microsoft's tool of the same name, which takes entirely different arguments, so a "not found" and a "found the wrong program" both end as a certificate warning on every intercepted page with a message telling the operator to apt install libnss3-tools. find_certutil and the NSS seeding are now #ifndef _WIN32, and fissure_trust.c writes the current user's Root store through the Win32 certificate API instead (-lcrypt32, no elevation, machine store never touched). The status the launch reports is a distinct one (FISSURE_BROWSER_CA_OK_SYSTEM) because the grant is genuinely wider than the Linux one: it is account-wide and outlives the browser profile, so the operator is told, and Settings carries a removal button.

  • Winsock listening-socket semantics: shutdown() on a LISTENING socket does NOT wake a blocked accept() (POSIX does; Windows needs closesocket()). The proxy/oast/rawrelay accept loops use netw_accept_nonblock_from(listen, FISSURE_ACCEPT_POLL_MS) so they poll running themselves rather than relying on shutdown to wake accept.

  • The same divergence on a CONNECTED socket, which this document previously got wrong. It used to say "shutdown() DOES break a CONNECTED socket's recv, so the request-cancel path is fine". That is POSIX behaviour; Winsock does not reliably wake a thread already blocked in recv when another thread calls shutdown() on its socket. It surfaced as a proxy that would not stop while a browser was open: a browser leaves several kept-alive connections idle, each parking a worker in a read, and fissure_proxy_stop spins until every worker drains. On POSIX the shutdown sweep releases them at once; on Windows they ran to the full 30 s FISSURE_PROXY_TIMEOUT_MS each, and with the browser re-connecting the stop never appeared to finish. Closing the browser fixed it because that closes the sockets for real. The fix is the same shape as the accept-loop one: do not depend on shutdown to wake a read. A per-connection client leg now reads in FISSURE_PROXY_READ_POLL_MS slices and checks the running flag between them (leg_set_interruptible), with the idle timeout enforced across slices by a deadline rather than by one long blocking read. The send timeout is deliberately left long, so a large upload is not cut off by the read slice. Verified on Linux by DISABLING the shutdown sweep to model Winsock: sweep off with the slicing takes milliseconds, sweep off without it takes 31294 ms. tests/test_proxy keeps the end-to-end assertion but says in a comment that it passes on POSIX for the shutdown reason, so a green run there is not evidence about Windows.

  • Winsock macro clash: <inaddr.h> #defines s_addr/s_host/s_net/s_lh/... The per-view layout static s_lh collided and was renamed s_lay_h across the GUI files.

  • _WIN32_WINNT: nilorea defaults it to XP (0x0501), but WSAPoll/inet_ntop need 0x0600; the Makefile Windows branch sets -D_WIN32_WINNT=0x0600.

  • Console window: fissure.exe is linked with -mwindows (the Makefile's WIN_SUBSYSTEM, applied to the app link only, never to the tests), mirroring Hook's Makefile.windows. Without it the loader opens a console window behind the GUI on every launch. Because a GUI-subsystem process starts with no console at all, main() calls fissure_proc_attach_console() first thing: it attaches to the launching terminal's console (AttachConsole(ATTACH_PARENT_PROCESS)) and rebinds only the CRT streams the shell did not already redirect, so fissure scan ..., fissure serve, -v and -h still print from cmd.exe/PowerShell and fissure ... > out.txt still writes the file. Started from Explorer, a shortcut or the installer there is no parent console, so nothing is attached and no window appears.

  • Blocking CLI: cmd.exe and PowerShell do not WAIT for a GUI-subsystem process, so a scripted fissure.exe scan ... would return the prompt immediately and a batch file could not read its exit code. The Windows build therefore also produces fissure-cli.exe (Makefile target WIN_CLI, source packaging/fissure_cli_launcher.c, installed next to fissure.exe): a console-subsystem launcher that starts the fissure.exe sitting beside it, waits for it and exits with the child's exit code. It forwards the RAW command line minus its own program name (fissure_cmdline_skip_arg0, tested by tests/test_cmdline) instead of re-quoting a parsed argv, so payload arguments carrying quotes, backslashes and spaces reach the child byte for byte. It holds no application logic: there is no second copy of Fissure to keep in sync and no second 19 MB binary in the installer. The child inherits the launcher's standard handles, so redirection works and Ctrl+C reaches both processes. Use fissure-cli in scripts and fissure for the GUI.

  • Console children: for the same reason, fissure_proc_run_wait uses CreateProcess with CREATE_NO_WINDOW (not _spawnvp), so the PDF generator and certutil do not flash up a console window of their own. fissure_proc_capture and fissure_proc_spawn_detached already used CREATE_NO_WINDOW / DETACHED_PROCESS.

  • _mkdir takes one argument (no mode) -> FISSURE_MKDIR.

  • readlink("/proc/self/exe") -> GetModuleFileNameA (then normalize \ to /); lstat -> stat (Fissure creates no directory symlinks).

  • strndup is not declared under -std=c99 on current mingw -> fissure_strndup.

  • fissure.exe needs the ucrt64 runtime directory on PATH. Started without it (from a plain cmd, or from CI outside the MSYS2 shell) it dies with STATUS_DLL_NOT_FOUND (0xC0000135, reported by cmd as exit -1073741515) before main runs. Worth knowing for two reasons: the failure produces an empty output file, which reads exactly like a redirection bug, and if errorlevel 1 in a batch file does NOT catch it, because that is a >= test and the status is negative. Test an exit code with if not "%errorlevel%"=="0".

  • A GUI-subsystem child does NOT inherit the parent's standard handles just because CreateProcess was called with bInheritHandles = TRUE. Windows ignores the STARTUPINFO handle fields for such a child unless STARTF_USESTDHANDLES is set, and a console child picking them up on its own is what makes the omission easy to miss. fissure-cli.exe therefore passes hStdInput/hStdOutput/hStdError explicitly. Without it fissure-cli.exe --version > out.txt exited 0, printed to the screen, and left out.txt empty: the child found no stdout, attached to the parent console and wrote there instead. Found by the Windows CI job the first time that check ever ran.

  • S_ISLNK does not exist in the UCRT headers, and lstat is a shim for stat, which FOLLOWS a symlink or a junction. A S_ISLNK(sb.st_mode) guard therefore compiles to a test that can never fire (and, before the shim, to an implicit-declaration error). The marketplace's three bundle walks (hash, copy, pack) test the file's FILE_ATTRIBUTE_REPARSE_POINT instead, via one entry_is_link predicate. This one is worth calling out because the POSIX side of it is redundant (an lstat'd link fails the S_ISDIR/S_ISREG tests anyway), so no POSIX test can tell a working version from a broken one: the Windows CI job is the only thing that checks it. It was found by that job's first successful run, on a file make winsweep had never reached.

  • sem_getvalue is unspecified while a thread is blocked in sem_wait, and the two platforms differ: glibc reports 0, winpthreads reports a negative waiter count. Any logic of the form "read the value, act only if it is 0" therefore works on Linux and fails on Windows. Nilorea's thread pool did exactly that to decide whether to post its idle token, which stranded wait_for_threaded_pool forever on Windows and made a Fissure scan finish its work and then hang unstoppably. Do not branch on sem_getvalue; consume-then-post is the portable way to clamp a token. Confirmed on a real MSYS2 build: with the fix the scan ends on its own, restarts, and stops on demand, where before it hung after finishing its work.

  • There is no /dev/urandom and no getrandom(2) on Windows, so Nilorea's n_random_bytes failed for EVERY caller until it grew a BCryptGenRandom branch (link -lbcrypt; n_windows.h must precede bcrypt.h, which uses LONG/ULONG without defining them). This was not cosmetic: the control-API token, the team tokens and every async job id come from it, and job creation ABORTS when the token is NULL, so POST /api/scans could not work on Windows at all. Found only because a real Windows run logged "cannot open /dev/urandom" - a reminder that a POSIX-only source file can compile perfectly for Windows and still be dead at runtime.

  • Plugins (external OSS tools installed by a Unix-shell dependency manager) are disabled on Windows (FISSURE_HAS_PLUGINS is 0); use Extensions (in-process JS) or the built-in checks instead. The GUI/control-API/MCP report this rather than failing silently.

  • The HTTP/3 MITM listener (fissure_h3proxy) is available on Windows. It used to be POSIX-only, because it gave each QUIC connection its own UDP socket bound to the shared listen port (SO_REUSEPORT + connect) and Winsock has no SO_REUSEPORT: a second bind to the same UDP port takes the port over instead of sharing it, which would have blackholed every client after the first. It now binds ONE socket and demultiplexes inbound datagrams to per-connection queues by the packet's destination connection id, sending on the same socket addressed to each packet's own path, which is the portable QUIC-server shape and asks the platform for nothing special. fissure_h3proxy_available() is therefore 1 wherever the ngtcp2/nghttp3 stack is present, and fissure_h3proxy_unavailable_reason() now has one reason left to report (a build without that stack). Two Windows-specific details in that path: the socket is made non-blocking with ioctlsocket(FIONBIO) rather than fcntl (fissure_net_set_nonblock), and errors are read with WSAGetLastError() rather than errno (FISSURE_SOCK_ERRNO and the FISSURE_SOCK_WOULDBLOCK / FISSURE_SOCK_EINTR_ERR predicates in fissure_net.h). SO_REUSEADDR is deliberately NOT set on Windows, where it would let an unrelated process bind over a port this listener already holds. Still to confirm on a real MSYS2 box: that the listener binds, handshakes and proxies there, the same way it does under tests/test_h3proxy on POSIX.

  • HTTP/3 is a conditional (HAVE_HTTP3) code path, so an audit that omits -DHAVE_HTTP3 never parses it. The sweep below defines it (that omission is how the fissure_h3proxy.c POSIX socket includes reached a Windows build unnoticed).

Signing the Windows build

A small unsigned mingw-built binary with no version resource and its DWARF sections left in is the shape several malware signatures describe, and a security product flagged a sibling project's DLL on exactly that. Three things make the Windows files say what they are. None of them changes the code.

  • Version resource. fissure.exe and fissure-cli.exe link a VERSIONINFO (packaging/windows/version.rc): company NiloreaStudio, product Fissure, the file's own name and description, and FISSURE_VERSION from src/fissure_version.h. The Makefile computes the four numbers of the binary version, and both resource objects depend on the version header, so a stamp rebuilds them. The installer and the uninstaller carry the same company and version through the VIAddVersionKey lines of installer.nsi, and the Add/Remove Programs entry names NiloreaStudio as the publisher. The bundled third-party DLLs are not given one, which would name us on files we did not write.
  • Strip. Every exe and DLL in a packaged folder is run through strip --strip-unneeded: dist/windows/ (make windows) and packaging/dlls/, the folder the installer packs (make installer-windows, make windows-installer). The build is -g, and the from-source and toolchain DLLs carry debug sections too. fissure.exe goes from 26.7 MB to 6.1 MB, the folder from 90 MB to 24 MB and the installer from 37 MB to 13 MB. The fissure.exe and fissure-cli.exe in the build tree are left as linked, with their symbols, for a debugger; the installer packs the stripped copies from packaging/dlls/.
  • Signature. After the strip (which rewrites the file), packaging/windows/windows-sign.sh signs every exe and DLL in the folder with osslsigncode, the third-party ones included, because one unsigned DLL is what a rule on the publisher stops at. The installer is signed once built, and the uninstaller stub is signed while makensis packs it (!uninstfinalize in installer.nsi).

The signature is Authenticode with a self-signed certificate named NiloreaStudio. No authority vouches for it, so Windows trusts it only where an administrator installed the certificate (README.md, "Windows: the signature"). What it gives without that is a publisher a security product can read and allow once, for every file and every later build, where an exception by hash dies with each build.

WIN_SIGN selects the mode, for make windows, make windows-installer and make installer-windows alike:

WIN_SIGN Behaviour
auto (default) sign when osslsigncode and the key are both on the machine; otherwise build unsigned and print NOTHING IS SIGNED
1 fail when either is missing
0 sign nothing (the GitHub workflow uses it; so does the server's CI without its secrets)

make release runs its Windows steps with WIN_SIGN=1 whatever the command line says, and its preflight checks the tool, the key and the fingerprint before the version is stamped, so a release cannot come out unsigned.

osslsigncode is apt install osslsigncode on Debian and pacman -S mingw-w64-ucrt-x86_64-osslsigncode on MSYS2 UCRT64, the environment this port is built in (mingw-w64-x86_64-osslsigncode under MINGW64); OSSLSIGNCODE=/path/to/it names another copy.

The key is not in the repository. key.pem and cert.pem live in ~/.config/nilorea/signing ($XDG_CONFIG_HOME/nilorea/signing, or WINSIGN_DIR), shared with the other NiloreaStudio projects so that they all sign as one publisher. Whoever holds key.pem can sign as NiloreaStudio: back it up, never commit it.

A build never creates the key. On a machine without one (an MSYS2 box, a CI runner) auto builds unsigned and says so, and 1 fails. To sign there as the same publisher, copy key.pem and cert.pem from the machine that has them into ~/.config/nilorea/signing (under MSYS2 that is the MSYS2 home, /home/<user>/.config/nilorea/signing), keeping the key readable by its owner only (chmod 600).

The CI on the project's own server (.forgejo/workflows/ci.yml, job cross) signs when the server holds two secrets, WINSIGN_KEY_PEM and WINSIGN_CERT_PEM, each the whole text of the file of that name. packaging/windows/ci-winsign.sh, read by the two steps that sign, writes them to a directory made for the step (owner only, removed when the step ends) and sets WIN_SIGN=1; the pinned fingerprint still applies, so a pair that is not the publisher's fails the job. Without the secrets the job builds unsigned. A pull request is given neither: what it builds is unsigned and the code it proposes never runs beside the key. The cost is that the key is on the server: whoever administers it or its runner, or can push a workflow to a repository that sees the secrets, can sign as NiloreaStudio.

The Makefile pins the publisher: WIN_SIGN_FINGERPRINT is the SHA-256 of the certificate, the one the README gives. A build that finds another key stops with both fingerprints rather than sign as a second NiloreaStudio, in every mode but 0. make ... WIN_SIGN_FINGERPRINT= (empty) accepts whatever key is there.

To become a new publisher on purpose, with no key in the directory:

sh packaging/windows/windows-sign.sh new-key

It writes a ten-year RSA 3072 certificate limited to code signing (CA:false), the key without a passphrase and readable by its owner only, prints the fingerprint, and refuses when the directory already holds a key. Then change WIN_SIGN_FINGERPRINT in the Makefile and the fingerprint in the README. WINSIGN_NAME changes the name in a new certificate. WINSIGN_TIMESTAMP names an RFC 3161 server; none is asked by default, so a signature stops verifying when the certificate expires.

The uninstaller is signed by makensis itself, which runs sh windows/windows-sign.sh from packaging/ on the stub. That step needs NSIS 3.08 or later and sh on the PATH when makensis runs (it is, in an MSYS2 shell and on Linux). If it fails on some machine, WIN_SIGN=0 is the way out: the step is not compiled in and nothing is signed.

A signed build writes the public certificate, DER encoded, as NiloreaStudio.cer beside the exe, and the installer installs it there (the uninstaller removes the whole folder). An unsigned build ships no certificate. To read the fingerprint of the one a build wrote:

sha256sum dist/windows/NiloreaStudio.cer

To check a signature from Linux:

osslsigncode verify -CAfile ~/.config/nilorea/signing/cert.pem -in dist/windows/fissure.exe

All of this was exercised on the Linux cross build. Not checked on a Windows machine: how Explorer and SmartScreen show the signature, the certutil commands of the README, and the strip, sign and !uninstfinalize steps under a native MSYS2 make installer-windows.

Cross-compiling on Linux (make windows)

The full Windows build is now reproducible on a plain Linux box, with no MSYS2 and no Windows machine, mirroring AfterAPro's model. Two steps:

make windows-deps      # once: build the dependency sysroot under external/mingw/
make windows           # cross-compile + link + stage fissure.exe and its DLLs

packaging/windows/fetch-windows-deps.sh populates external/mingw/ (gitignored): Allegro 5 and its dependency pack come PREBUILT from the Allegro project's own mingw release zip (SHA-pinned), and zlib, pcre2, libyaml, openssl, libxml2 and xmlsec1 (openssl backend) are cross-built FROM SOURCE in dependency order into external/mingw/sysroot. The Makefile's WINCROSS=1 switch then sets OS=Windows_NT so every existing native-Windows branch fires (.exe, -mwindows, the Winsock/dnsapi/bcrypt/crypt32 libs, the windres icon), points the compiler and linker at the sysroot, and names Allegro's import libraries explicitly (the prebuilt Allegro ships cmake config, not pkg-config). packaging/windows/stage-dlls.sh walks the PE import table with the cross objdump and copies every non-system DLL (Allegro, openssl, pcre2, yaml, libxml2, xmlsec, zlib, and the mingw runtime libgcc/libstdc++/libwinpthread) into dist/windows/ beside the exe.

make windows-check is the full cross compile of all 239 units against the sysroot with no link, which is the real check the syntax-only winsweep only approximates.

make windows-installer cross-builds the NSIS setup.exe as well. NSIS is the one packaging step that genuinely cross-compiles: makensis runs on Linux, so it reuses packaging/installer.nsi exactly as the native MSYS2 build does. It drives the existing installer-windows with WINCROSS=1, so collect-dlls (which is WINCROSS-aware: it stages with the objdump walk rather than the native ldd) fills packaging/dlls/ and the cross fissure.exe/fissure-cli.exe are what gets packaged into dist/fissure-<version>-setup.exe. Both are copied into packaging/dlls/ first, where they are stripped and signed with the DLLs.

The windows-cross.yml CI workflow (GitHub's runners) runs the compile, the link+stage and the installer on Linux and uploads both the loose build and the setup.exe as artifacts, unsigned (WIN_SIGN=0: those runners do not hold the publisher's key; the job on the project's own server does, see "Signing the Windows build"); it caches the sysroot keyed on the fetch script, so it is rebuilt only when a pinned version or sum changes.

HTTP/3 is built in. The sysroot includes nghttp3 and ngtcp2 with the ngtcp2_crypto_ossl (vanilla-OpenSSL) QUIC backend, which is why the cross OpenSSL is 3.5.x: that backend needs OpenSSL's QUIC-TLS API, absent in 3.3. The Makefile's pkg-config auto-detect finds all three through the sysroot and defines -DHAVE_HTTP3, so the cross build has the HTTP/3 fetch tool and h3proxy exactly as the native build does. The on-target native MSYS2 build (next section) remains the authority on runtime behaviour.

What remains

  1. On-target runtime verification. The cross build compiles and links every unit on Linux, so a POSIX-ism now surfaces at make windows-check rather than only on MSYS2. What the cross build cannot show is behaviour: the Debian cross toolchain can also under-report what the live MSYS2 CRT provides, so a native MSYS2 run stays the authority on anything that actually executes.
  2. A windows-latest CI job (msys2/setup-msys2, pacman -S the deps above, make + make tests) so the port does not rot. Written, at .github/workflows/windows.yml, and blocked only on CI having access to the private nilorea-library sibling checkout the build needs (a deploy key, submodule, or vendored copy); it stops at that step with a message saying so rather than failing later inside a compile. It carries one behavioural check beyond build+tests, run from cmd rather than the MSYS2 shell because the behaviour under test is what cmd does with a GUI-subsystem child: fissure-cli.exe waits, its output reaches a redirected handle (which is fissure_proc_attach_console working), and a bad subcommand comes back non-zero. Those are the three reasons the launcher exists, so a regression in any of them is worth catching automatically rather than on someone's desk.
  3. Minor: the fissure serve signal(SIGINT/SIGTERM) handlers compile on mingw but Windows signal-delivery semantics differ; revisit if the headless serve loop needs a cleaner Windows shutdown.
  4. Two checks that still want a person at a Windows desk, because neither has a headless form: that launching fissure.exe from Explorer opens NO console window while launching it from cmd still prints, and that Ctrl+C in a console stops a running fissure-cli scan. Both are about how a console session behaves, so wine is not a substitute: console and process semantics are exactly where it diverges most from Windows, and a wine result would be misleading rather than partial.

Verifying portability without MSYS2

The complete off-target check is now make windows-check (it needs the sysroot; make windows-deps builds it once). It cross-compiles every unit against the real Windows dependency headers, so nothing is gated out: it is the full version of what winsweep only samples. Use winsweep for a fast edit loop that needs no dependency sysroot.

Run:

make winsweep

It loops the cross compiler over src/, skipping ONLY the files whose first failure is a missing dependency header, reports every remaining error: line as a real portability issue, prints the three counts this document's table records, and exits non-zero if anything real turned up. It is a target rather than a copy-and-paste recipe precisely so the two details below cannot be lost by retyping it, which is how they were lost before. Needs gcc-mingw-w64-x86-64; override the compiler with make winsweep WINSWEEP_CC=....

To re-check only what a change touched, which is the rule below, narrow the file list:

make winsweep WINSWEEP_FILES="$(git diff --name-only HEAD -- 'src/*.c')"

Two things the sweep gets right, both learned the hard way:

  • Match error:, NOT fatal error:. A missing header is fatal and aborts the file, but a missing FUNCTION is an ordinary error that a fatal error filter silently drops: that is how strcasestr in fissure_surface.c (a GNU extension the Windows CRT lacks) survived a sweep that reported the tree clean. Nilorea declares a portable strcasestr in n_str.h under __windows__, so the fix is to include <nilorea/n_str.h> in any file that calls it.
  • Define -DHAVE_HTTP3 (see the gotcha list above), or the QUIC code is never parsed.
  • Run it on new files AND on changed ones. The first three misses were all files added after the last sweep: mkdir(dir, 0700) instead of FISSURE_MKDIR (the Windows CRT _mkdir takes no mode), memmem in a file that reaches neither fissure_compat.h nor fissure_constants.h (which includes it), and a constant used from a __windows__ branch whose include did not define it. That made "sweep the new files" look like the whole rule, and it is not: the fourth miss was strcasestr added to fissure_cspt.c, a file three sweeps had already seen and passed, because the CALL was new even though the file was not. A file's clean result expires when the file changes, so what needs re-sweeping is every file the change touched. A Windows-only #ifdef block is the easiest place to get this wrong, because the Linux build never compiles it.

The sweep is a filter, not a proof, and it is worth knowing how coarse a filter: 132 of the 239 files stop at their first missing dependency header, so it actually checks 107 of them, under half the tree. The gating is not random either. Every file that reaches fissure_net.h is gated, because that pulls in n_network.h, which includes openssl/err.h

  • so essentially all of the networking, proxy, scanner and check code is invisible to the sweep, and a clean make winsweep says nothing whatsoever about those files. Treat a skipped file as unchecked rather than as passing: what the sweep can prove is narrow, and anything behind an openssl/allegro include surfaces only on the MSYS2 build.

For a gated file, check the one hazard the sweep would have caught by hand: a GNU/BSD function the Windows CRT lacks. mingw-w64 declares neither strcasestr nor memmem, so a file calling either needs a portable declaration in scope - <nilorea/n_str.h> for strcasestr, fissure_compat.h (or fissure_constants.h, which includes it) for memmem. Compiling a two-line file that includes <string.h>, the header in question, and the call answers it in a second, without needing the file's dependencies.