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_WIN32backends 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 vsShellExecute,-lshell32),fissure_proc_spawn_detached+fissure_proc_kill_pid(setsid daemon +kill(-pid)vsCreateProcess(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP)+OpenProcess/TerminateProcessby pid, so no process handle needs threading back),fissure_proc_signal_pid, andfissure_proc_capture(the pipe-capture + timeout + process-group cancel path: POSIX pipe/fork vs WindowsCreatePipe/CreateProcess/WaitForSingleObject). Every caller is migrated:fissure_plugin_run.c,fissure_gui_plugins.c,fissure_cdp.c,fissure_pdf.c,fissure_gui_main.c, andfissure_browser.c(itsdefault_launchis#ifdef _WIN32-guarded,<sys/wait.h>is under#ifndef _WIN32).tests/test_proccovers exit codes, null-stdio, and a no-timeout capture cancelled by signalling its published pid.fissure_proc.candfissure_browser.ccross-compile for the Windows target.Sockets (
src/fissure_net.h). The socket-compat header: portableSOCKET/closesocket/INVALID_SOCKET(Winsock on Windows, BSD on POSIX),SHUT_*mapped toSD_*,MSG_NOSIGNALto 0, and aFISSURE_POLLname forpoll/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 areSOCKET(notint, which truncates a Win64 handle); eachSO_RCVTIMEO/SO_SNDTIMEOis a_WIN32DWORD of milliseconds vs a POSIXstruct timeval, whichfissure_socket_recv_timeout()insrc/fissure_compat.hhides: call it rather than writing the#ifdefagain, because passing a timeval to Winsock sets NO timeout at all and the mistake is silent. Nilorea starts Winsock insidenetw_connect/netw_make_listening, so code that opens a raw socket instead callsfissure_sockets_init()first (a no-op on POSIX) or everysocket()fails with WSANOTINITIALISED. Close one withfissure_socket_close(): on Windows a SOCKET is a handle from a different space than the CRT's file descriptors, soclose()on one leaks it and can trip the CRT's invalid-parameter handler. Prerequisite Nilorea htonll/ntohll fix is on niloreanext.DNS (
src/fissure_dns.c). Dual-path: POSIXres_*and a_WIN32DnsQuerypath. The Makefile linksPLATFORM_LIBS(-lresolvon Linux,-ldnsapi -lws2_32 -lshell32on Windows).libc gaps (
src/fissure_compat.h,src/fissure_platform.h).fissure_compat.hsuppliesmemmem,gmtime_r/localtime_r,getline,mkstemps,lstat,fchmodunder_WIN32, plus a portablefissure_strndup(a new name on both platforms: the mingw-w64 CRT does not declarestrndupunder-std=c99, and whether it does varies by toolchain, so a same-name shim would clash on some).fissure_platform.hsuppliesFISSURE_MKDIR(1-arg_mkdiron Windows),FISSURE_PATH_SEP, andfissure_time_us(_ftime64vsgettimeofday). Nilorea's n_str provides a portablestrcasestr.Packaging (
make installer-windows). Bundles the MinGW/Allegro runtime DLLs (resolved withldd) intopackaging/dlls, generates the HTML docs, and compiles an NSISsetup.exefrompackaging/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.exesuffix,windresfor 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 inaccept()orrecvfrom()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 soacceptreturns (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_rawrelayandtests/test_controldo now too.A path walk must step over the drive designator.
C:/Users/xwalked component by component from index 1 asks the CRT to createC:, which is not a directory to make but a reference to the current directory on that drive:_mkdirrefuses it with EACCES, not EEXIST.fissure_paths_mkdirstherefore 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 locationXDG_CONFIG_HOMEredirects 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:\aand\_are not valid ones and\tis 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=trueand 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 undertests/fuzz/corpusare wire captures whose CRLFs are the protocol rather than the file format. It also broke a parser:test_control_routesreassembles 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.gitattributeswith* -textpins 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'srenamefails 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_atomicdelegates to nilorea'sn_file_write_atomic, which usesMoveFileExwithMOVEFILE_REPLACE_EXISTINGthere.There are no POSIX permission bits. Windows synthesises
st_modefrom 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_PLUGINSis 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 setsHOMEto a path inside its own installation, so a$HOME/.config/fissuretree put the proxy CA, the projects, the scan history and the settings underC:/msys64/home/<user>/. That was survivable inside an MSYS2 shell and fatal outside one: launched from Explorer, the Start Menu or a plaincmd,HOMEis not set at all,fissure_paths_config_dirreturned -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_dirnow resolves%APPDATA%/Fissure, then%USERPROFILE%/.config/fissure, then$HOME(in that order, afterXDG_CONFIG_HOME, which still overrides everything on both platforms). Two details the first attempt would get wrong: the Windows variables hold BACKSLASH paths, whichfissure_paths_mkdirswalks looking forFISSURE_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, withfissure_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: thefind_certutilPATH walk splits on ':', which is a drive separator rather than a list separator on Windows, and thecertutil.exea 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 toapt install libnss3-tools.find_certutiland the NSS seeding are now#ifndef _WIN32, andfissure_trust.cwrites 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 blockedaccept()(POSIX does; Windows needsclosesocket()). The proxy/oast/rawrelay accept loops usenetw_accept_nonblock_from(listen, FISSURE_ACCEPT_POLL_MS)so they pollrunningthemselves 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'srecv, so the request-cancel path is fine". That is POSIX behaviour; Winsock does not reliably wake a thread already blocked inrecvwhen another thread callsshutdown()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, andfissure_proxy_stopspins until every worker drains. On POSIX the shutdown sweep releases them at once; on Windows they ran to the full 30 sFISSURE_PROXY_TIMEOUT_MSeach, 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 inFISSURE_PROXY_READ_POLL_MSslices 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_proxykeeps 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>#definess_addr/s_host/s_net/s_lh/... The per-view layout statics_lhcollided and was renameds_lay_hacross the GUI files._WIN32_WINNT: nilorea defaults it to XP (0x0501), butWSAPoll/inet_ntopneed 0x0600; the Makefile Windows branch sets-D_WIN32_WINNT=0x0600.Console window:
fissure.exeis linked with-mwindows(the Makefile'sWIN_SUBSYSTEM, applied to the app link only, never to the tests), mirroring Hook'sMakefile.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()callsfissure_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, sofissure scan ...,fissure serve,-vand-hstill print from cmd.exe/PowerShell andfissure ... > out.txtstill 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 producesfissure-cli.exe(Makefile targetWIN_CLI, sourcepackaging/fissure_cli_launcher.c, installed next tofissure.exe): a console-subsystem launcher that starts thefissure.exesitting 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 bytests/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. Usefissure-cliin scripts andfissurefor the GUI.Console children: for the same reason,
fissure_proc_run_waitusesCreateProcesswithCREATE_NO_WINDOW(not_spawnvp), so the PDF generator andcertutildo not flash up a console window of their own.fissure_proc_captureandfissure_proc_spawn_detachedalready usedCREATE_NO_WINDOW/DETACHED_PROCESS._mkdirtakes one argument (no mode) ->FISSURE_MKDIR.readlink("/proc/self/exe")->GetModuleFileNameA(then normalize\to/);lstat->stat(Fissure creates no directory symlinks).strndupis not declared under-std=c99on current mingw ->fissure_strndup.fissure.exeneeds the ucrt64 runtime directory on PATH. Started without it (from a plaincmd, or from CI outside the MSYS2 shell) it dies withSTATUS_DLL_NOT_FOUND(0xC0000135, reported by cmd as exit-1073741515) beforemainruns. Worth knowing for two reasons: the failure produces an empty output file, which reads exactly like a redirection bug, andif errorlevel 1in a batch file does NOT catch it, because that is a>=test and the status is negative. Test an exit code withif not "%errorlevel%"=="0".A GUI-subsystem child does NOT inherit the parent's standard handles just because
CreateProcesswas called withbInheritHandles = TRUE. Windows ignores theSTARTUPINFOhandle fields for such a child unlessSTARTF_USESTDHANDLESis set, and a console child picking them up on its own is what makes the omission easy to miss.fissure-cli.exetherefore passeshStdInput/hStdOutput/hStdErrorexplicitly. Without itfissure-cli.exe --version > out.txtexited 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_ISLNKdoes not exist in the UCRT headers, andlstatis a shim forstat, which FOLLOWS a symlink or a junction. AS_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'sFILE_ATTRIBUTE_REPARSE_POINTinstead, via oneentry_is_linkpredicate. 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 filemake winsweephad never reached.sem_getvalueis unspecified while a thread is blocked insem_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 strandedwait_for_threaded_poolforever on Windows and made a Fissure scan finish its work and then hang unstoppably. Do not branch onsem_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/urandomand nogetrandom(2)on Windows, so Nilorea'sn_random_bytesfailed for EVERY caller until it grew aBCryptGenRandombranch (link-lbcrypt;n_windows.hmust precedebcrypt.h, which usesLONG/ULONGwithout 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, soPOST /api/scanscould 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_PLUGINSis 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 noSO_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, andfissure_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 withioctlsocket(FIONBIO)rather thanfcntl(fissure_net_set_nonblock), and errors are read withWSAGetLastError()rather thanerrno(FISSURE_SOCK_ERRNOand theFISSURE_SOCK_WOULDBLOCK/FISSURE_SOCK_EINTR_ERRpredicates infissure_net.h).SO_REUSEADDRis 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 undertests/test_h3proxyon POSIX.HTTP/3 is a conditional (
HAVE_HTTP3) code path, so an audit that omits-DHAVE_HTTP3never parses it. The sweep below defines it (that omission is how thefissure_h3proxy.cPOSIX 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.exeandfissure-cli.exelink aVERSIONINFO(packaging/windows/version.rc): company NiloreaStudio, product Fissure, the file's own name and description, andFISSURE_VERSIONfromsrc/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 theVIAddVersionKeylines ofinstaller.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) andpackaging/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.exegoes 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. Thefissure.exeandfissure-cli.exein the build tree are left as linked, with their symbols, for a debugger; the installer packs the stripped copies frompackaging/dlls/. - Signature. After the strip (which rewrites the file),
packaging/windows/windows-sign.shsigns every exe and DLL in the folder withosslsigncode, 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 whilemakensispacks it (!uninstfinalizeininstaller.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
- On-target runtime verification. The cross build compiles and links
every unit on Linux, so a POSIX-ism now surfaces at
make windows-checkrather 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. - A
windows-latestCI job (msys2/setup-msys2,pacman -Sthe 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 privatenilorea-librarysibling 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 fromcmdrather than the MSYS2 shell because the behaviour under test is what cmd does with a GUI-subsystem child:fissure-cli.exewaits, its output reaches a redirected handle (which isfissure_proc_attach_consoleworking), 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. - Minor: the
fissure servesignal(SIGINT/SIGTERM)handlers compile on mingw but Windows signal-delivery semantics differ; revisit if the headless serve loop needs a cleaner Windows shutdown. - Two checks that still want a person at a Windows desk, because
neither has a headless form: that launching
fissure.exefrom Explorer opens NO console window while launching it from cmd still prints, and that Ctrl+C in a console stops a runningfissure-cliscan. 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:, NOTfatal error:. A missing header is fatal and aborts the file, but a missing FUNCTION is an ordinary error that afatal errorfilter silently drops: that is howstrcasestrinfissure_surface.c(a GNU extension the Windows CRT lacks) survived a sweep that reported the tree clean. Nilorea declares a portablestrcasestrinn_str.hunder__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 ofFISSURE_MKDIR(the Windows CRT_mkdirtakes no mode),memmemin a file that reaches neitherfissure_compat.hnorfissure_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 wasstrcasestradded tofissure_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#ifdefblock 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 winsweepsays 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 anopenssl/allegroinclude 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.