Joseph Ferano
2957804ebc
vendor/raylib/web/ is gitignored, so the header a build-web.sh tree happens
to have never appears in a git worktree. Every parallel lane that touched
bindings was checking against nothing and was not told. One went looking and
used a copy out of ~/.local/share/Trash, which happened to be byte-identical.
A check that silently does not run is worse than no check.
raylib.h is 128K and now sits beside the package it describes. The argument
for ?${FLAN_RAYLIB_H} was that requiring a header would make a build need
raylib-devel, and that dissolves when the header is committed here. There is
no variable to export any more; to check against a different header, edit
the line or replace the file.
Measured, because always-on has to be paid by every build: a warm build of
raylib-font.flan is 0.10-0.11s against a 0.10s baseline. The header read is
cached and keyed like the object cache, so this is under the noise. Verified
it fires by putting f64 where raylib says int and watching an ordinary build
refuse, naming the tracked header.
61 lines
3.4 KiB
Plaintext
61 lines
3.4 KiB
Plaintext
# C headers this package reads function signatures out of. One per line: a
|
|
# path, then any clang flags that header needs. A relative path is against
|
|
# this directory, ${NAME} expands from the environment, and a leading `?`
|
|
# means "if it is there" — an optional line with nothing behind it is simply
|
|
# not read.
|
|
#
|
|
# What this is for, now that the bindings are committed. generated.flan holds
|
|
# every declaration the importer produced, in the repository, so a build needs
|
|
# libraylib linkable and no header at all. This line is read by two things:
|
|
#
|
|
# 1. `flan generate-c vendor/raylib`, which is the only way generated.flan
|
|
# is written. It reads the header named here, compares the package
|
|
# against it, and refuses to write when they disagree — so it is not
|
|
# possible to regenerate the bindings without comparing them to the
|
|
# library they claim to bind.
|
|
#
|
|
# 2. an ordinary build, when the variable happens to be set. Every C symbol
|
|
# is bound already — by hand in raylib.flan or by generation in
|
|
# generated.flan — so the importer generates nothing and the header read
|
|
# is purely the check. It runs over all 425 declarations rather than the
|
|
# 172 hand-written ones, because the generated file is a package file like
|
|
# any other and is checked like one — though only the hand-written ones can
|
|
# actually disagree, since the generated half came out of this header and
|
|
# agrees with it by construction. That is also why the hand-written lines
|
|
# were kept rather than replaced by generated ones.
|
|
#
|
|
# Why it is no longer optional. It used to be `?${FLAN_RAYLIB_H}`, and the
|
|
# argument was that a build needs libraylib linkable and *not* raylib-devel
|
|
# installed, so requiring a header would take that property from everyone to
|
|
# give the check to whoever had one. **That argument dissolved when the header
|
|
# was committed here**: nobody needs raylib-devel to have it, because it ships
|
|
# with the repository.
|
|
#
|
|
# What being optional actually cost was found the hard way. `vendor/raylib/web/`
|
|
# is gitignored, so the header a `build-web.sh` tree happens to have never
|
|
# appears in a git worktree — and every parallel lane that touched bindings was
|
|
# therefore checking against nothing and not being told. One of them went
|
|
# looking and used a copy out of `~/.local/share/Trash`, which happened to be
|
|
# byte-identical. A check that silently does not run is worse than no check.
|
|
#
|
|
# The version must match the shared library `link` names — 5.5, libraylib.so.550.
|
|
# Reading one version's header while linking another's library is exactly the
|
|
# silent disagreement this exists to prevent, and it is caught rather than
|
|
# described: against a 5.1-dev header, regeneration reports ten differences
|
|
# that are all real and writes nothing.
|
|
#
|
|
# To check against a different header — a newer raylib, or a system one — edit
|
|
# this line or replace the file. There is no environment variable for it any
|
|
# more: the point of committing the header is that every tree checks against
|
|
# the same one without anybody exporting anything.
|
|
#
|
|
# To see what regeneration would produce without writing anything:
|
|
#
|
|
# flan import-c $FLAN_RAYLIB_H vendor/raylib/raylib.flan
|
|
#
|
|
# What shapes the generated half — which functions are skipped, and what they
|
|
# are called — is `bindings` beside this file. See its comments for why a
|
|
# committed generated file needs a config at all.
|
|
#
|
|
raylib-5.5.h
|