Joseph Ferano
1d7f5e1c85
Decision 1. Odin's #load and #load_directory are the model, spelled as ordinary named calls — an s-expression language already has a head position and does not need Odin's `#`. (embed "p") is a [u8], (embed "p" string) is a string, and (embed-dir "d") is a [n EmbedFile] sorted by name. Two spellings rather than one that changes type with its context. Odin threads a type_hint everywhere and can afford it; with structural equality and no implicit widening, the same text meaning two types here would be a wart. The path is a literal and resolves relative to the file the form is written in, both of which are Odin's rules and for Odin's reasons: the bytes must be in hand before any value exists, and a package's assets must not depend on where flan was invoked from. The bytes reach the program as a [Str] node typed [u8], not as a [Bytes] prim over a string. [Bytes] is identity — emit.ml lowers String and Slice _ to the same %slice — and wrapping the literal in a prim would make the node non-constant, so an (embed-dir) bound with defconst could not be an LLVM constant. Both string emitters take the bytes and ignore the node's type, so it is the same constant either way and one a global can hold. emit.ml's escape is byte-exact, so a PNG survives the .ll. The directory lookup is a linear scan in the prelude over a slice of EmbedFile. A directory embed is tens of entries out of cache-warm .rodata, and a compile-time perfect hash would be a build-time map with its own failure modes that nothing has asked for. Sorted because readdir order is filesystem-dependent and an unsorted embed would make two builds of identical sources emit different .ll. The slice points into .rodata, so a store through it segfaults at -O0 and is deleted at -O2 — the same measured trap the prelude's ASCII-case note describes for (bytes "Hi"). Inherited, not widened; clone into a Vec for a mutable copy.
58 lines
2.7 KiB
Plaintext
58 lines
2.7 KiB
Plaintext
;;;; Assets baked in at compile time — NEXT.md decision 1.
|
|
;;;;
|
|
;;;; Odin's #load and #load_directory are the model, spelled as ordinary named
|
|
;;;; calls because an s-expression language already has a head position and
|
|
;;;; does not need Odin's `#`. The whole reason for preferring this to a build
|
|
;;;; flag is that it is a *compiler* feature: no linker arguments, no
|
|
;;;; per-target packaging, and identical on desktop and web. A single-file
|
|
;;;; program has no link channel at all — `Load` hands out lflags only to a
|
|
;;;; directory package — so the file that needs the asset is structurally the
|
|
;;;; one file that could not declare it. Embedding has no such hole.
|
|
;;;;
|
|
;;;; Nothing here costs anything at run time: every one of these is a
|
|
;;;; `private unnamed_addr constant` in the emitted module.
|
|
|
|
;; Bound once at top level, where it becomes an LLVM constant outright rather
|
|
;; than an array rebuilt on the stack per call (emit.ml's `const`).
|
|
(defconst assets [3 EmbedFile] (embed-dir "assets"))
|
|
|
|
(defn main [] i32
|
|
;; The default answer is a [u8]: bytes, because that is what an asset is.
|
|
(let [a (embed "assets/a.txt")]
|
|
(println (len a)) ; 13
|
|
(print (string a))) ; hello from a
|
|
|
|
;; `string` is the second spelling, not a different meaning for the same
|
|
;; text. With structural equality and no implicit widening, one form that
|
|
;; changes type with its context would be a wart.
|
|
(println (embed "assets/b.bin" string)) ; BBB
|
|
|
|
;; Byte-exact, including bytes no text encoding would survive: emit.ml's
|
|
;; escape hex-escapes everything outside printable ASCII, so a PNG makes the
|
|
;; round trip through the .ll unchanged.
|
|
(let [raw (embed "assets/raw.bin")]
|
|
(println (len raw)) ; 4
|
|
(println (at raw 0)) ; 0
|
|
(println (at raw 2)) ; 255
|
|
(println (at raw 3))) ; 254
|
|
|
|
;; A directory embed is a fixed array of EmbedFile, sorted by name — sorted
|
|
;; because readdir order is filesystem-dependent and an unsorted embed would
|
|
;; make two builds of identical sources emit different .ll.
|
|
(println (len assets)) ; 3
|
|
(println (.name (at assets 0))) ; a.txt
|
|
(println (.name (at assets 1))) ; b.bin
|
|
(println (.name (at assets 2))) ; raw.bin
|
|
|
|
;; The name-to-bytes lookup is a linear scan in the prelude. It takes a slice
|
|
;; rather than the array, because an array's length is part of its type and
|
|
;; there are no generics.
|
|
(let [all (slice assets 0 (len assets))]
|
|
(match (embed-find all "b.bin")
|
|
(Some b) (println (string b)) ; BBB
|
|
None (println "missing"))
|
|
(match (embed-find all "nope.txt")
|
|
(Some _) (println "found")
|
|
None (println "no nope.txt"))) ; no nope.txt
|
|
0)
|