miniopenenv

tests/embed/README.md → html

tests/embed — can a stranger consume this?

Three third-party consumers, three routes that share no code path, each one actually compiled and actually run by make check-embed. The whole directory exists because every claim it tests is the kind that is easy to believe and easy to have broken six months ago without noticing.

$ make check-embed
RouteThe claim under test
(a)pkg-config, against a real make install into a throwaway DESTDIRthe install path works, and openenv.pc records PREFIX rather than DESTDIR
(b)the sources vendored into a consumer's own Makefile, compiled with a hostile flag setour feature-test macros are in the .c files, not in CFLAGS
(c)<openenv/embed.h> alonea program that speaks the whole protocol contains no system call

Two files do the work. consumer.c is cases (a) and (b) — one program, two build routes. pure.c is case (c).


§ 1 · (a) pkg-config

(a) pkg-config

tools/embed.sh runs make install DESTDIR=build/embed/stage PREFIX=/usr/local, then compiles consumer.c from a temporary directory that is not this repository, with a copy of the source, so that no relative include path can rescue a broken install.

The assertion that is easy to miss is not "it compiled". It is this:

PREFIX is where the files will BE. DESTDIR is where they are being PUT.

Only the first belongs inside openenv.pc. A .pc that recorded the staging directory would send every consumer of the resulting package to a path that existed on the build machine for four seconds. That is the single most common packaging defect there is. So the test greps the staged file and fails if DESTDIR appears in it.

Pointing pkg-config at a staging tree anyway is then solved from outside the file, which is also exactly what a cross-compile does with a sysroot:

PKG_CONFIG_PATH=<stage>/usr/local/lib/pkgconfig \
pkg-config --define-variable=prefix=<stage>/usr/local --cflags openenv

That works only because openenv.pc.in writes libdir=${prefix}/lib rather than expanding it, and the Makefile rewrites $(LIBDIR) back into terms of ${prefix} on its way into the file. PC_LIBDIR in the Makefile is those two sentences as code.

Finally make uninstall runs and the staging tree must contain no file at all afterwards — checkable precisely because nothing else ever wrote there.

§ 2 · (b) Vendored, with hostile flags

(b) Vendored, with hostile flags

tests/embed/Makefile is what a consumer's Makefile looks like after they add this repository as a submodule: one include ../../openenv.mk, one rule, and their own flags on the compile line. Their flags are:

-std=gnu17 -O2 -Wall -Wextra -Werror -D_GNU_SOURCE -D_FORTIFY_SOURCE=2
-DNDEBUG -funsigned-char -fvisibility=hidden -fno-common

Not one of those is ours, and -std=c99 is deliberately absent. Every entry is there because it could plausibly break somebody who put their feature-test macros in the wrong place, or who assumed char was signed, or whose struct layout depended on assert. -Werror makes a warning from our sources under their flags a test failure instead of scrollback. And the resulting binary is run, and it diffs protocol bytes — because -funsigned-char changing a UTF-8 decision is a behaviour bug and not a compile error.

The honest limitation, stated rather than discovered. A consumer who pins _POSIX_C_SOURCE to an old value on the command line — -D_POSIX_C_SOURCE=199506L — breaks the vendored build of src/wire/net.c, because our #ifndef guard can lower nothing:

../../src/wire/net.c:213:22: error: storage size of 'hints' isn't known
../../src/wire/net.c:229:25: error: 'AI_PASSIVE' undeclared
../../src/wire/net.c:230:9: error: implicit declaration of function 'getaddrinfo'

That is real output. There are two fixes and both are the consumer's: raise the value (200809L or later), or take route (a) instead and link the archive, which compiles net.c with our flags and hands you a header that needs none. _GNU_SOURCE, _XOPEN_SOURCE=700 and no macro at all are all fine, which covers essentially every project that is not deliberately pinning to POSIX.1-1996.

§ 3 · (c) embed.h alone, and no socket in the binary

(c) embed.h alone, and no socket in the binary

pure.c includes exactly one header of ours and drives oe_session_frame through a reset, a step and an error frame.

It links the whole libopenenv.a — the archive that contains the accept loop, the client, and src/wire/net.c, the one file in the project with an #ifdef in it. A static archive is a bag of translation units, and the linker takes only what something references. So if the protocol layer needed a socket, socket would appear in the finished program's undefined-symbol list.

The test asserts a positive control first: nm finds socket in the archive, so there is something to exclude. Then it checks the program's undefined symbols against thirty-one forbidden names — sockets, polling, signals, clocks, fork, open — and then prints what is there:

abort  calloc  fflush  fprintf  free  getenv  malloc  memcmp  memcpy
memset  printf  puts  snprintf  strlen  strtod

printf and puts are pure.c's own output — gcc rewrites a printf of a literal into puts. Seven of the rest are src/wire/arena.c: the allocator, the OE_ARENA_DEBUG_MALLOC switch behind getenv, and the message it prints before aborting on a pointer that outlived its reset. strtod and snprintf are JSON numbers. That list is the entire operating-system dependency of the OpenEnv protocol.


§ 4 · Why these files live in a directory make check also lints

Why these files live in a directory make check also lints

tools/check.sh applies the project's banned-function and no-goto rules to everything under tests/, this directory included — so consumer.c obeys conventions a genuine stranger would not have heard of. That is a deliberate trade: the alternative is a lint exemption, and an exemption is a hole that grows. What matters for the claim is the flags and the include paths, and those really are a stranger's.

make check-embed is not part of make check, for the same reason make interop is not: it writes files, shells out to pkg-config, and takes seconds rather than milliseconds. Each case skips loudly, with the reason printed, when a tool it needs is absent — never silently, and never as a pass.

See docs/PACKAGING.md for the full transcript and for the container half of the same story.