/* SPDX-License-Identifier: LicenseRef-Starship-1.0 * Copyright (c) 2023-2026 Robert A. James */ /* f18a.h -- build a train's engine, its F18 artifact, on the build machine (mkf18a). * * docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md section 2 and section 10. Every .f18 in the train's * directory is assembled by text.c, at 0, in name order, after the map; then: * - every : word with a fixed stack effect (effect.c) is an export, with the flags and the capabilities * written after its name; * - every `import TRAIN NAME` is an import of TRAIN's export NAME: TRAIN is given as an artifact, whose * capsule ID (the XXHash64 of its bytes, as mkcapsule gives it) names it, and whose export gives the * effects expected. TRAIN `nucleus` is the nucleus (plan section 12): hash 0, NAME looked up by its * dictionary name in the nucleus as the tool assembles it from its source, and its effect derived there; * a word in line there, or one with no fixed effect, is refused. It declares no capabilities; * - every address text.c records is a relocation; * - the provenance's four SHA-512 hashes, each over files framed as: the file's name, a NUL, its length * in 8 bytes low first, its bytes. The source: the train's .f18, in name order. The tool: its own * source (tools/mkf18a.c, tools/f18a.c, tools/f18a.h, src/artifact.c, src/asm.c, src/effect.c, * src/iword.c, src/text.c, then every .h of include/v4 in name order), named from the v4 directory. * The configuration: the text "V4_CELL_BITS=.. V4_NODE_WORDS=.. V4_DATA_RING=.. V4_RET_RING=.. * V4_ROM_WORDS=..", framed as "config", then the map. The ROM: the ROM's file as given. * It refuses what the ABI cannot carry: a header, a store or a start in the source; an export's name * over 31 characters; a port or a request it can see that the word does not declare, or one declared by * a word it calls; a word that runs on into the next export with no call or jump, since placement splits * the code at each export (plan section 12, 2a). */ #ifndef V4_TOOLS_F18A_H #define V4_TOOLS_F18A_H #include typedef struct { const char *name; /* as `import` names it */ const char *path; /* its .f18a */ } f18a_train; typedef struct { const char *map; /* the memory map's constants: map-.f18 */ const char *dir; /* the train's .f18 */ const char *rom; /* the ROM it is built against */ const f18a_train *trains; /* the trains it may import from */ unsigned ntrains; const char *tool_root; /* the v4 directory, for the tool's hash */ const char *nucleus; /* the nucleus's source directory, for `import nucleus NAME`, or NULL */ } f18a_args; /* 1 and the artifact in *out (malloc'd, *len bytes), or 0 and why in err. */ int f18a_build(const f18a_args *a, unsigned char **out, size_t *len, char *err, size_t errlen); #endif /* V4_TOOLS_F18A_H */