Porting
This page is how to move this project to another operating system, and what a port has to keep true. The short version: rewrite one file.
The claim
To move this project to another platform, rewrite one file:
src/wire/net.c.
It is the only translation unit in the tree with a platform conditional in it, and the only one that makes a system call. Everything above it is a pure function from bytes to bytes and can be tested with no socket at all.
Check it yourself:
$ grep -rn '#ifdef\|#if defined' src/ --include='*.[ch]'
src/wire/arena.c:41:#if defined(__has_feature)
src/wire/arena.c:46:#if defined(__SANITIZE_ADDRESS__)
src/wire/net.c:1:/* net.c — THE ONE FILE WITH #ifdefs. Not protocol; see docs/PORTING.md.
src/wire/net.c:17:#if defined(__APPLE__)
src/wire/net.c:57:#if defined(MSG_NOSIGNAL)
src/wire/net.c:157:#if defined(SO_NOSIGPIPE)
src/wire/net.c:179:#if defined(SO_KEEPALIVE)
src/wire/arena.h:169:#if defined(NDEBUG)
Seven conditionals and one banner comment — net.c announcing itself, which is
the third line. Four of the seven are in net.c; a fifth, #if !defined (MSG_NOSIGNAL) && !defined(SO_NOSIGPIPE), is an #error the pattern above does
not match. The three outside net.c are not about an operating system at
all:
| Where | What it tests | Why it is not a port |
|---|---|---|
src/wire/net.c | __APPLE__, MSG_NOSIGNAL, SO_NOSIGPIPE, SO_KEEPALIVE, _POSIX_C_SOURCE | this is the port |
src/wire/arena.h | NDEBUG | whether the generation stamp is asserted |
src/wire/arena.c | __has_feature, __SANITIZE_ADDRESS__ | whether ASan poisoning is available |
Two of those three are about a build, not a target.
What you have to reimplement
src/wire/net.h is the whole surface: about twenty functions, no callbacks, no
hidden state beyond two small caller-owned structs. Grouped by what a port
actually has to find:
| Group | Functions | The platform thing behind it |
|---|---|---|
| listen / connect | oe_net_listen, oe_net_connect, oe_net_accept, oe_net_local_port | sockets, name resolution, non-blocking connect |
| move bytes | oe_net_read, oe_net_write, oe_net_read_some, oe_net_write_all | recv/send, EINTR, EAGAIN, and suppressing SIGPIPE per call |
| readiness | oe_net_poll, oe_net_poll_events, oe_net_poll_revents | poll or its local equivalent |
| the clock | oe_net_now_ms, oe_net_sleep_ms | a monotonic millisecond source |
| wakeup | oe_net_wake_*, oe_net_signal_wake, oe_net_signal_restore_all | a self-pipe (or eventfd), and signal disposition |
| fd pressure | oe_net_reserve_open, oe_net_reserve_close | a spare descriptor for the EMFILE path |
| randomness | oe_net_random | the kernel's entropy source |
Five facts a port has to keep true, and they are the reason this file exists
rather than a scattering of send() calls:
- Nothing blocks. Every descriptor handed out is non-blocking, so a peer that sends one byte and stalls cannot park a single-threaded server for the length of its patience.
- Sending to a departed peer returns an error and never raises
SIGPIPE. Suppressed per-call (MSG_NOSIGNAL) or per-socket (SO_NOSIGPIPE) — never with a process-widesignal()disposition. That one belongs to the embedder and we do not get to change it behind them. If your target has neither mechanism,net.chas an#errorwaiting for you rather than a silent process-kill. EINTRis retried at every call site, and retrying never resets a deadline the caller gave us.- A short move is normal, not an edge case. Every function reports how many bytes actually moved and expects the caller to come back.
- Randomness comes from the kernel, and when it cannot, that is a hard
failure.
oe_net_randomreads/dev/urandom(O_CLOEXEC) and returnsOE_EIOwith nothing usable written. ASec-WebSocket-Keyfrom a predictable source is not a nonce, and "just use the clock" is the bug that signature exists to make impossible.
Why no platform type appears in a header
src/wire/net.h deliberately contains no ssize_t, no struct pollfd and no
sigaction. A header here must compile standalone under a bare
-std=c99 -pedantic-errors with no feature-test macros defined, and every one
of those spellings fails that test.
So the header defines its own oe_pollfd and its own three readiness flags, and
net.c translates them. That buys a second thing worth knowing about. poll's
events field is a short, and POLLIN | POLLOUT promotes to int. So a
short field would be a narrowing assignment that -Wconversion is right to
complain about at every call site. Making the field an int moves that one
narrowing into one line of net.c, where a reader can watch it happen.
The same reasoning is why the public API says oe_server_fds(int *, short *, int)
rather than taking a struct pollfd *. In a prototype, an undeclared struct
type declares a new incomplete type at prototype scope and breaks every
caller.
Feature-test macros live in .c files
At the top, before the first #include, never in a header and never in
CFLAGS:
#ifndef _POSIX_C_SOURCE
#define _POSIX_C_SOURCE 200809L
#endif
#if defined(__APPLE__)
#define _DARWIN_C_SOURCE 1
#endif
Two different failures are being avoided:
- In
CFLAGSit works right up until somebody vendors this project into a build with its own flag set.make check-embedroute (b) is exactly that scenario: it compiles 33 of our.cfiles with-std=gnu17 -D_GNU_SOURCE -D_FORTIFY_SOURCE=2 -DNDEBUG -funsigned-char -Werrorand not one flag of ours, then runs the result and diffs protocol bytes. - In an installed header it applies to the consumer's translation unit and
silently changes what their
<string.h>declares.tools/check.shfails the build if a public header defines one.
make check-portability is what keeps the C99 claim honest: it compiles every
translation unit and every header with exactly four flags and no -D of ours.
$ make check-portability
check-portability: 72 sources, 35 headers, flags: -std=c99 -pedantic-errors -Wall -Wextra
check-portability: ok
One honest limitation. A consumer who pins _POSIX_C_SOURCE to a pre-2008
value on the command line cannot vendor src/wire/net.c. The #ifndef above
declines to raise it, and the declarations net.c needs are then not there. The
error output is pasted in PACKAGING.md.
What "tested" means for a port
Almost all of this project's tests do not touch your port at all, which is the useful consequence of the layering:
| Test | Needs a socket? |
|---|---|
t_replay — the whole 103-case reference corpus | no |
t_conn — all five connection states, capacity refusal, handshake deadline | no |
t_json_parse, t_json_write, t_ws, t_http, t_utf8, t_validate, … | no |
t_net | yes — this is the port's own test |
t_client part 6 | yes — forks our server and drives a real episode |
So the sequence for a new platform is: rewrite net.c, run t_net, then run
everything else and expect it to have been passing already.
The two supported targets today are Linux and macOS. Running make check
on the second machine is also what keeps tools/ honest: every script here is
POSIX sh with no grep -P, no sed -i, no readlink -f and no GNU-only
find/xargs. Nothing does that for you. This repository has no build service
and asks for none, so a port is proved by somebody running these targets.
See also
../src/wire/net.h↗ — the surface, and the five facts, at the declarations../src/wire/net.c↗ — the portPACKAGING.md— vendoring,pkg-config, the three embedded consumers, and the containerMEMORY.md— the other file with a platform story:arena.c, and why it is the only one that allocates