Joseph Ferano
1504258afb
BUILT.md and the web page both make the point that the generated half agrees with the header by construction; headers said "425 declarations" and left a reader to infer that all 425 are independently verified. It is the file somebody reads when deciding whether to export the variable at all.
56 lines
3.0 KiB
Plaintext
56 lines
3.0 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 still optional. A build needs libraylib linkable and *not*
|
|
# raylib-devel installed, which is a property worth keeping; requiring a header
|
|
# would take it from everyone to give the check to whoever has one. Before the
|
|
# bindings were committed this marker also decided how many bindings a build
|
|
# got, which was the real cost of it being opt-in; it no longer decides that,
|
|
# and all it now withholds is a check that regeneration has already run once.
|
|
# Same shape as ${FLAN_RAYLIB_WEB} in `link`, and for the same reason.
|
|
#
|
|
# 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.
|
|
#
|
|
# export FLAN_RAYLIB_H=/path/to/raylib-5.5/src/raylib.h
|
|
#
|
|
# vendor/raylib/build-web.sh already clones that exact tag to build the browser
|
|
# archive, so a tree that has built for web has the matching header at
|
|
# vendor/raylib/web/raylib-5.5/src/raylib.h.
|
|
#
|
|
# 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.
|
|
#
|
|
?${FLAN_RAYLIB_H}
|