dymokomi/luce-base
Source of release 0.43.0
0.43.0 / src / support / manifest.lucb
#==============================================================================================
#
# manifest - The package manifest, `package.prisma`
#
# DESCRIPTION:
# A package has a `package.prisma` at its root (base.md §16.4). This reads the little of it
# the compiler needs: `[package] name`, the identity of the package's error codes
# (§11.3); `symbol_prefix`, what every exported symbol starts with (§17.6); and the
# `[native]` inputs the build hands the C compiler and the linker (§17.4); and, for the
# module resolver, the source root, the dependencies, the exports, and the compiled
# modules' package identities (§16.4). The file is found upward from the entry file's
# directory; a program without one is the package `app` with no inputs. `settings`
# is the one line reader: every `key = value` line under its `[section]`, with either
# TOML quoting, a trailing comment dropped, and any other line refused.
#
#==============================================================================================
import luce_std.paths
import c
import os
import platform
import support.cache as cache
import support.in_arena
import memory
import strings
# mark: Settings ==============================================================================
## A manifest line or value is malformed.
pub let malformed: ErrorCode = ErrorCode.package(17)
## One `key = value` line of a manifest, under its section, the value unquoted.
pub struct Setting:
## The `[section]` header the setting falls under.
pub var section: str
## The setting's key, trimmed.
pub var key: str
## The setting's value, unquoted and trimmed.
pub var value: str
## Every setting of a `package.prisma` `text`, as section/key/value records in order, so the
## rest of the compiler reads one shape:
##
## def package "n" { [package] name = n (n as an identifier)
## [package] written name = n (as spelled)
## str k = "v" [package] k = v
## def dependency "n" { str path = "p" } [dependencies] n = p, or .luc/deps/n without a path
## str[] public = ["m", "n.o"] [package] public = ["m", "n.o"]
## def native "x" { str[] k = ["a", "b"] } [native] k = ["a", "b"]
##
## A package name may be spelled `luce-ui`; the compiler's identifier for it is `luce_ui`.
## Other elements (tasks, the desktop bundle) and properties are luc's and are skipped, but
## a key set twice in one element is refused, luc's or not (§16.4). A malformed line is
## refused at `path:line:column`, `path` naming the file `text` was read from.
pub func settings(text: str, path: str) -> Setting[]!:
var out = try new Setting[count_lines(text) + 2] ---
var count: usize = 0
var keys = try Keys.create(count_lines(text) + 1)
var kind: str = ""
var element: str = ""
var saw_path = false
var line_number: usize = 0
var rest = text
while rest.length > 0:
let cut = strings.find(rest, "\n") else rest.length
let raw_line = (str)rest.bytes[..<cut]
let line = trim(raw_line)
let at = Place(path = path, line = line_number + 1, indent = raw_line.length - trim_start(raw_line).length)
line_number += 1
rest = (str)rest.bytes[cut + 1..] if cut < rest.length else ""
if line.length == 0 or line.bytes[0] == '#':
continue
if line == "}":
if keys.depth == 2 and kind == "dependency" and not saw_path:
out[count] = Setting(section = "[dependencies]", key = element, value = try deps_path(element))
count += 1
if keys.depth == 0:
try at.refuse(0, "package.prisma closes an element it never opened")
keys.close_element()
continue
if line.length > 4 and (str)line.bytes[..<4] == "def ":
let after = trim((str)line.bytes[4..])
let space = strings.find(after, " ") else after.length
let word = (str)after.bytes[..<space]
let named = trim((str)after.bytes[space..])
if named.length < 3 or named.bytes[named.length - 1] != '{':
try at.refuse(0, "an element is `def kind \"name\" {`")
let name = unquote(trim((str)named.bytes[..<named.length - 1]))
try keys.open_element()
if keys.depth == 1:
if word != "package":
try at.refuse(0, "package.prisma starts with `def package`")
out[count] = Setting(section = "[package]", key = "name", value = try identifier_of(name))
out[count + 1] = Setting(section = "[package]", key = "written name", value = name)
count += 2
elif keys.depth == 2:
kind = word
element = try identifier_of(name) if word == "dependency" else name
saw_path = false
continue
let eq = strings.find(line, "=") else line.length
if eq >= line.length:
try at.refuse(0, "a property is `type key = value`")
let left = trim((str)line.bytes[..<eq])
let type_end = strings.find(left, " ") else left.length
if type_end >= left.length:
try at.refuse(0, "a property is `type key = value`")
let key = trim((str)left.bytes[type_end..])
let column = left.length - trim_start((str)left.bytes[type_end..]).length
if let first = try keys.set(key, at.line):
var room = try new u8[key.length + 64] ---
try at.refuse(column, try strings.format(room, f"`{key}` is set twice in one element; it was set on line {first}"))
let raw = trim((str)line.bytes[eq + 1..])
if keys.depth == 1:
out[count] = Setting(section = "[package]", key = key, value = unquote(raw))
count += 1
elif keys.depth == 2:
if kind == "dependency" and key == "path":
out[count] = Setting(section = "[dependencies]", key = element, value = unquote(raw))
count += 1
saw_path = true
elif kind == "export":
try at.refuse(0, "a package names its public modules in `str[] public = [...]`, under `src/` (§16.4); `def export` is gone")
elif kind == "native":
# The element's name says where it applies; parse keeps the ones for the target.
var room = try new u8[element.length + key.length + 1] ---
let scoped = try strings.format(room, f"{element}/{key}")
out[count] = Setting(section = "[native]", key = scoped, value = raw)
count += 1
return out[..<count]
## Where in a manifest a line starts: its file, its line, and the blanks before its text.
struct Place:
var path: str
var line: usize
var indent: usize
## Refuse the line as malformed, `what` naming why, at `column` past its indent.
func refuse(column: usize, what: str) -> never!:
var room = try new u8[self.path.length + what.length + 48] ---
error(malformed, try strings.format(room, f"{self.path}:{self.line}:{self.indent + column + 1}: {what}"))
## The keys set in each open element, so one set twice in an element is found; elements
## are numbered as they open, and each key remembers the element and the line it is in.
struct Keys:
var names: str[]
var elements: usize[]
var lines: usize[]
var count: usize
## The open elements' numbers, outermost first, and how many are open.
var open: usize[16]
var depth: usize
var opened: usize
static func create(capacity: usize) -> Keys!:
return Keys(names = try new str[capacity] ---, elements = try new usize[capacity] ---, lines = try new usize[capacity] ---)
func open_element() -> !:
if self.depth >= self.open.length:
error(malformed, "package.prisma nests elements too deeply")
self.open[self.depth] = self.opened
self.opened += 1
self.depth += 1
func close_element():
self.depth -= 1
## Note `key` set on `line` in the innermost open element; the line of the setting
## already there, if the element has one.
func set(key: str, line: usize) -> usize?!:
let current = self.open[self.depth - 1] if self.depth > 0 else self.opened
for i in 0..<self.count:
if self.elements[i] == current and self.names[i] == key:
return self.lines[i]
self.names[self.count] = key
self.elements[self.count] = current
self.lines[self.count] = line
self.count += 1
return none
## `luce-ui` as the identifier `luce_ui`.
pub func identifier_of(name: str) -> str!:
var copy = try new u8[name.length] ---
var i: usize = 0
for b in name.bytes:
copy[i] = '_' if b == '-' else b
i += 1
return (str)copy
## Where luc unpacks a registry dependency that declares no checkout path.
func deps_path(name: str) -> str!:
let prefix = ".luc/deps/"
var copy = try new u8[prefix.length + name.length] ---
var i: usize = 0
for b in prefix.bytes:
copy[i] = b
i += 1
for b in name.bytes:
copy[i] = b
i += 1
return (str)copy
func count_lines(text: str) -> usize:
var n: usize = 0
for b in text.bytes:
if b == '\n':
n += 1
return n
# mark: Manifests =============================================================================
## What the manifest says; the lists hold NUL-terminated text, ready for a tool's arguments.
pub struct Manifest:
## The package's name, as an identifier.
pub var name: str
## The package's name as `def package` spells it (`luce-ui`), empty without a
## manifest; the program a build makes carries it (`platform.program`).
pub var written_name: str
## The manifest's `version`, empty when it gives none (`platform.program_version`).
pub var version: str
## The directory holding `package.prisma`, with its trailing slash; empty when none was found.
pub var root: str
## The prefix put before exported C symbols, or empty.
pub var symbol_prefix: str
## The C source files to compile alongside the program, NUL-terminated.
pub var sources: c.str[]
## The libraries to link, NUL-terminated.
pub var libraries: c.str[]
## The directories to search for libraries, NUL-terminated.
pub var link_search: c.str[]
## The macOS frameworks to link, NUL-terminated.
pub var frameworks: c.str[]
## The pkg-config packages whose flags to add, NUL-terminated.
pub var pkg_config: c.str[]
## The manifest of the package holding `entry_path`, or the default one.
pub func load(entry_path: str) -> Manifest!:
var dir = directory_of(entry_path)
while true:
var buffer = try new u8[dir.length + 16] ---
let candidate = try strings.format(buffer, f"{dir}package.prisma")
if let text = read_if_present((c.str)candidate):
return try parse((str)text, dir)
if dir.length == 0:
return try parse("", "")
dir = parent_of(dir)
## The bytes of the file at `path`, or `none` when there is no such file.
func read_if_present(path: c.str) -> u8[]?:
let data = in_arena.read(path) catch:
cache.note_absent((str)path)
return none
cache.note_input((str)path, data)
return data
## The manifest `text` describes, for the package rooted at `root`.
pub func parse(text: str, root: str) -> Manifest!:
var m = Manifest(name = "app", written_name = "", version = "", root = root, symbol_prefix = "", sources = try no_items(), libraries = try no_items(),
link_search = try no_items(), frameworks = try no_items(), pkg_config = try no_items())
var room = try new u8[root.length + 16] ---
for setting in try settings(text, try strings.format(room, f"{root}package.prisma")):
let section = setting.section
let key = setting.key
let value = setting.value
if section == "[package]":
if key == "name":
m.name = value
elif key == "written name":
m.written_name = value
elif key == "version":
m.version = value
elif key == "symbol_prefix":
m.symbol_prefix = value
elif section == "[native]":
let slash = strings.find(key, "/") else key.length
if slash >= key.length or not applies((str)key.bytes[..<slash]):
continue
let field = (str)key.bytes[slash + 1..]
let items = try items_of(value)
if field == "sources":
m.sources = try joined(m.sources, items)
elif field == "libraries":
m.libraries = try joined(m.libraries, items)
elif field == "link_search":
m.link_search = try joined(m.link_search, try searched(items))
elif field == "frameworks":
m.frameworks = try joined(m.frameworks, items)
elif field == "pkg_config":
m.pkg_config = try joined(m.pkg_config, items)
return m
# mark: Targets ===============================================================================
## The target native elements are chosen for: the host's unless the build names another.
var target_name: str = ""
## Choose the target `def native` elements are selected for (`arm64-macos`, …).
pub func set_target(name: str):
target_name = name
## Whether a `def native "NAME"` element applies to the target: `inputs` (or `all`)
## everywhere, an operating system (`macos`, `linux`, `windows`) on each of its
## architectures, or one exact target (`x86_64-windows`).
pub func applies(name: str) -> bool:
if name == "inputs" or name == "all":
return true
let target = target_name if target_name.length > 0 else platform.name
if name == target:
return true
return target.length > name.length + 1 and target.bytes[target.length - name.length - 1] == '-' and (str)target.bytes[target.length - name.length..] == name
## Search directories with a leading `$NAME` taken from the environment: `$VULKAN_SDK/Lib`
## is the SDK's library directory where the variable is set, and nothing where it is not.
func searched(items: c.str[]) -> c.str[]!:
var out = try new c.str[items.length] ---
var count: usize = 0
for item in items:
let text = (str)item
if text.length == 0 or text.bytes[0] != '$':
out[count] = item
count += 1
continue
let slash = strings.find(text, "/") else text.length
let name = try new u8[slash] ---
memory.copy(name, text.bytes[1..<slash], slash - 1)
name[slash - 1] = 0
let value = os.env((c.str)name.data) else continue
let rest = (str)text.bytes[slash..] if slash < text.length else ""
let room = try new u8[value.length + rest.length + 1] ---
let joined_text = try strings.format(room, f"{value}{rest}")
room[joined_text.length] = 0
out[count] = (c.str)room.data
count += 1
return out[..<count]
## Two item lists as one, in order.
func joined(first: c.str[], second: c.str[]) -> c.str[]!:
if first.length == 0:
return second
if second.length == 0:
return first
var out = try new c.str[first.length + second.length] ---
for index in 0..<first.length:
out[index] = first[index]
for index in 0..<second.length:
out[first.length + index] = second[index]
return out
## `["a", "b"]` as its strings, each copied with a NUL after it; a bare string is one item.
func items_of(value: str) -> c.str[]!:
var body = value
if body.length >= 2 and body.bytes[0] == '[' and body.bytes[body.length - 1] == ']':
body = (str)body.bytes[1..<body.length - 1]
var out = try new c.str[body.length + 1] ---
var count: usize = 0
var at: usize = 0
while at < body.length:
while at < body.length and (body.bytes[at] == ' ' or body.bytes[at] == '\t'):
at += 1
if at == body.length or body.bytes[at] == '#':
break
let quote = body.bytes[at]
if quote != '"' and quote != '\'':
error(malformed, "a list holds quoted strings")
at += 1
let text = try new u8[body.length + 1] ---
var used: usize = 0
var ended = false
while at < body.length:
var byte = body.bytes[at]
at += 1
if byte == quote:
ended = true
break
if byte == '\\' and quote == '"':
if at == body.length:
error(malformed, "a list string ends inside an escape")
byte = body.bytes[at]
at += 1
if byte == 'n':
byte = '\n'
elif byte == 'r':
byte = '\r'
elif byte == 't':
byte = '\t'
elif byte != '"' and byte != '\\':
error(malformed, "a list string has an escape other than \\n, \\r, \\t, \\\" and \\\\")
if byte == 0:
error(malformed, "a list string cannot hold NUL")
text[used] = byte
used += 1
if not ended or used == 0:
error(malformed, "a list string is nonempty and closed")
text[used] = 0
out[count] = (c.str)text.data
count += 1
while at < body.length and (body.bytes[at] == ' ' or body.bytes[at] == '\t'):
at += 1
if at < body.length:
if body.bytes[at] != ',':
error(malformed, "list strings are separated by commas")
at += 1
return out[..<count]
## The strings of a manifest list, `["ui", "widgets.button"]`, in order.
pub func strings_of(value: str) -> str[]!:
let items = try items_of(value)
var out = try new str[items.length] ---
for k in 0..<items.length:
out[k] = try strings.copy((str)items[k])
return out
# mark: Text and paths ========================================================================
## A TOML string's text: `"basic"` or `'literal'`, with a trailing `# comment` dropped; a
## bare value stays as written.
pub func unquote(value: str) -> str:
let b = value.bytes
if b.length >= 2 and (b[0] == '"' or b[0] == '\''):
var end: usize = 1
while end < b.length and b[end] != b[0]:
end += 1
if end < b.length:
return (str)b[1..<end]
return value
## `text` without the blanks at its start.
func trim_start(text: str) -> str:
var start: usize = 0
while start < text.length and (text.bytes[start] == ' ' or text.bytes[start] == '\t'):
start += 1
return (str)text.bytes[start..]
## `text` without the blanks at either end.
func trim(text: str) -> str:
let b = text.bytes
var start: usize = 0
var end = b.length
while start < end and (b[start] == ' ' or b[start] == '\t' or b[start] == '\r'):
start += 1
while end > start and (b[end - 1] == ' ' or b[end - 1] == '\t' or b[end - 1] == '\r'):
end -= 1
return (str)b[start..<end]
func no_items() -> c.str[]!:
var none_at_all = try new c.str[1] ---
return none_at_all[..<0]
## The directory part of a path, with its trailing slash; empty for a bare name.
pub func directory_of(path: str) -> str:
let b = path.bytes
var end: usize = 0
var i: usize = 0
while i < b.length:
if paths.separator(b[i]):
end = i + 1
i += 1
return (str)b[..<end]
## The directory above `dir`, with its trailing slash; empty at the top.
pub func parent_of(dir: str) -> str:
if paths.root(dir).length == dir.length:
return ""
let b = dir.bytes
if b.length == 0:
return ""
var end: usize = 0
var i: usize = 0
while i + 1 < b.length:
if paths.separator(b[i]):
end = i + 1
i += 1
return (str)b[..<end]
test "a manifest names the package, the prefix, and the native inputs":
var backing: u8[8192]
var arena = memory.FixedBuffer.over(backing)
with arena:
let m = try parse("#prisma 4.0\ndef package \"wid-gets\" {\n str version = \"1.2.3\"\n str symbol_prefix = \"wg_\"\n def native \"inputs\" {\n str[] sources = [\"vendor/a.c\", \"shims.c\"]\n str[] libraries = [\"m\"]\n str[] frameworks = [\"Metal\"]\n }\n}\n", "pkg/")
assert(m.name == "wid_gets")
assert(m.written_name == "wid-gets" and m.version == "1.2.3")
assert(m.symbol_prefix == "wg_")
assert(m.root == "pkg/")
assert(m.sources.length == 2)
assert((str)m.sources[1] == "shims.c")
assert(m.libraries.length == 1)
assert(m.frameworks.length == 1)
assert(m.pkg_config.length == 0)
let none_at_all = try parse("", "")
assert(none_at_all.name == "app")
assert(none_at_all.written_name == "" and none_at_all.version == "")
assert(none_at_all.sources.length == 0)
test "every element becomes settings under its section; luc's own elements are skipped":
var backing: u8[8192]
var arena = memory.FixedBuffer.over(backing)
with arena:
let found = try settings("#prisma 4.0\ndef package \"w\" {\n str kind = \"package\"\n str source = 'lib'\n str[] public = [\"ui\", \"widgets.button\"]\n def dependency \"luce-ui\" {\n str owner = \"dymokomi\"\n str path = \"../luce-ui\"\n }\n def dependency \"luce-json\" {\n str version = \"^0.2.0\"\n }\n def task \"ci\" {\n str cmd = \"luc test\"\n }\n}\n", "w/package.prisma")
assert(found.length == 7)
assert(found[0].section == "[package]" and found[0].key == "name" and found[0].value == "w")
assert(found[1].key == "written name" and found[1].value == "w")
assert(found[2].key == "kind" and found[2].value == "package")
assert(found[3].key == "source" and found[3].value == "lib")
assert(found[4].key == "public")
let public = try strings_of(found[4].value)
assert(public.length == 2 and public[0] == "ui" and public[1] == "widgets.button")
assert(found[5].section == "[dependencies]" and found[5].key == "luce_ui" and found[5].value == "../luce-ui")
assert(found[6].section == "[dependencies]" and found[6].key == "luce_json" and found[6].value == ".luc/deps/luce_json")
let exported = settings("def package \"w\" {\n def export \"ui\" {\n str module = \"ui\"\n }\n}\n", "w/package.prisma") catch failure:
recover found[..<0]
assert(exported.length == 0)
let bad = settings("def widget \"x\" {\n}\n", "w/package.prisma") catch failure:
assert(failure.message == "w/package.prisma:1:1: package.prisma starts with `def package`")
recover found[..<0]
assert(bad.length == 0)
test "a key set twice in one element is refused where it is set again":
var backing: u8[8192]
var arena = memory.FixedBuffer.over(backing)
with arena:
let empty = try new Setting[1] ---
var refused = false
_ = settings("#prisma 4.0\ndef package \"w\" {\n str[] public = [\"a\"]\n str[] public = [\"a\"]\n}\n", "w/package.prisma") catch failure:
assert(failure.code == malformed)
assert(failure.message == "w/package.prisma:4:11: `public` is set twice in one element; it was set on line 3")
refused = true
recover empty[..<0]
assert(refused)
refused = false
_ = settings("def package \"w\" {\n def task \"ci\" {\n str cmd = \"a\"\n str cmd = \"b\"\n }\n}\n", "p") catch failure:
assert(failure.message == "p:4:13: `cmd` is set twice in one element; it was set on line 3")
refused = true
recover empty[..<0]
assert(refused)
# the same key in different elements, and in the package around them, is no repeat
let fine = try settings("def package \"w\" {\n str version = \"1\"\n def dependency \"a\" {\n str version = \"^1.0.0\"\n }\n def dependency \"b\" {\n str version = \"^1.0.0\"\n }\n str owner = \"o\"\n}\n", "p")
assert(fine.length == 6)
test "native elements apply by operating system or exact target":
set_target("arm64-macos")
assert(applies("inputs") and applies("all") and applies("macos") and applies("arm64-macos"))
assert(not applies("windows") and not applies("linux") and not applies("x86_64-linux"))
set_target("x86_64-windows")
assert(applies("windows") and not applies("macos"))
let m = try parse("def package \"p\" {\n def native \"inputs\" {\n list libraries = [\"m\"]\n }\n def native \"windows\" {\n list libraries = [\"user32\"]\n }\n def native \"macos\" {\n list frameworks = [\"AppKit\"]\n }\n}\n", "")
assert(m.libraries.length == 2 and (str)m.libraries[0] == "m" and (str)m.libraries[1] == "user32" and m.frameworks.length == 0)
set_target("")
test "a search directory may start from an environment variable, and goes where it is unset":
let m = try parse("def package \"p\" {\n def native \"inputs\" {\n list link_search = [\"$HOME/lib\", \"$LUCE_UNSET_FOR_TEST/Lib\", \"vendor\"]\n }\n}\n", "")
let home = os.env("HOME") else return
assert(m.link_search.length == 2 and (str)m.link_search[1] == "vendor")
var expected: u8[1024]
assert((str)m.link_search[0] == try strings.format(expected, f"{home}/lib"))