Building a library yourself

When a generated build command is not enough, Flight runs yours and collects the files you name.

libify mode covers a library that looks like a library: C sources in a directory, headers, an export table. When it does not fit, custom mode hands the build back to you.

Reach for it when the repository has an unusual layout, a code generator that has to run first, its own hand-written assembly, or a build system that already produces the appvar.

The manifest#

.ceagle-flight

[program]
name = "Demo Library"
version = "1.0.0"
summary = "Two functions other programs can call."
categories = ["libs"]
author = "Ada Lovelace"

[library]
mode = "custom"
name = "DEMO"
appvar = "bin/DEMO.8xv"
stub = "bin/DEMO.lib"
headers = ["include/demo.h"]

[build]
command = "make lib"
submodules = false
timeout = "10m"

What changes from libify mode

commandRequired: Now required. A custom library with no build command fails with a custom library build needs a [build] command.
appvardefaults to bin/NAME.8xv: Where your build leaves the appvar. Now read, where in libify mode it is refused.
stubdefaults to bin/NAME.lib: Where your build leaves the linker stub.
src, include, exports, optimizeDeprecated: Not read. Those describe a generated command, and there is no generated command here.

Shipping no stub#

An explicit empty string says the build produces no stub:

[library]
mode = "custom"
name = "DEMO"
stub = ""

The library still loads on the calculator, and Swoop still installs it. Nothing else can link against it, which is occasionally what you want for a library that is only ever loaded by one program you also control.

Using ce-libify anyway#

Nothing stops a custom build from calling ce-libify. That is the usual reason to switch modes: you want the tool, but you want to run something before or after it.

makefile

lib: generated/tables.c
	ce-libify build --name DEMO --src src --headers include \
	  --exports exports.txt --bin bin --optimize -Oz

generated/tables.c: data/tables.csv tools/gen.py
	python3 tools/gen.py $< > $@

[library]
mode = "custom"
name = "DEMO"
headers = ["include/demo.h"]

[build]
command = "make lib"

What Flight checks afterwards#

The same checks as any other build, plus two specific to libraries.

Status	Code	Means
build	`the build produced no matching artifact`	The appvar path matched nothing.
build	`ce-libify produced no .lib stub next to the appvar`	The stub path matched nothing, and it was not set to the empty string.
build	`a header the manifest names is missing from the build`	One of the headers is not there. Paths are relative to the directory holding the manifest, and a header that your build generates has to exist by the time the command finishes.
build	`the release archive is larger than Roost accepts`	The staged archive exceeded its limit.

Reproducing what Flight publishes#

Run your own command, then check that the three sets of paths in the manifest exist:

make lib
ls -l bin/DEMO.8xv bin/DEMO.lib include/demo.h

If those three lines succeed, the collection step will too.