Customization — the layered configuration model¶
Equinox OS is built to be edited while it runs. Almost every
behaviour that would be hard-coded in a conventional kernel is instead
expressed as text in a .ecf file, read on the invocation that needs
it — so a change takes effect on the next command, with no reboot and
no recompile.
This page documents that model end to end: the layers, the dispatch
mechanism, and the per-tool configuration files. The .ecf format
itself is specified in ECF.md; the system-wide file in
SYSTEM_ECF.md; the editing tools in
SET.md.
1. Why layers¶
A single flat config file scales badly. It conflates three different concerns — the machine's identity (which NIC driver, which package server), each tool's private defaults, and the behavioural wiring that decides what runs when. Mixing them means editing one tool's defaults risks disturbing another's, and every new tool adds keys to a file nobody fully owns.
Equinox separates them into layers, each with a single owner and a single job:
| Layer | Files | Owner | Contains |
|---|---|---|---|
| 1. System store | /equinox/conf/system.ecf (+ overlays) |
the kernel & wizard | machine identity: net.*, eggkg.*, dependencies.*, active-store pointer |
| 2. Per-tool config | /equinox/.config/<tool>.ecf |
that tool | the tool's private defaults: eggkg.ecf, mtcc.ecf |
| 3. Action registry | in-kernel (ecf_caller) |
each module that registers | the named actions a config may invoke |
| 4. Recipes | the step lists inside .ecf |
the user | the order and arguments of what actually runs |
Read downward: layer 1 says what the machine is, layer 2 says how a tool behaves by default, layer 3 says what can be invoked, and layer 4 says in what order, with which arguments. The lower layers are the ones you edit daily; the upper ones are the ones the system owns.
The analogy to an onion is deliberate: each layer is only reachable through the one outside it, and peeling one back reveals the next without the outer layers needing to know what is inside.
2. Layer 1 — the system store¶
/equinox/conf/system.ecf is the machine's identity file. It is
written by equinoxinstall during phase [3/4] and read at every
boot.
[net]
driver = e1000
[eggkg]
server = https://raw.githubusercontent.com/amnottdevv/Eggkg-l
local = /equinox/.local
[dependencies]
bash = true
At boot the kernel resolves the active store through
ecf_active_path(), parses it, and dispatches the keys it recognises
— net.driver brings up the NIC, dependencies.bash re-syncs
/equinox/.local into /bin before the shell starts, eggkg.*
configures the package manager.
This layer is documented in full in SYSTEM_ECF.md. It is the layer you touch when provisioning a machine, not the one you touch when tuning a tool.
Overlays and redirection¶
system.ecf may point the active store at another file:
active.conf = /equinox/conf/drivers.ecf
The overlay is merged on top of the base store (later keys win), so a volume can carry its own overrides without editing the canonical file. See ECF.md.
3. Layer 2 — per-tool configuration¶
Each configurable tool owns one file in .config/:
/equinox/.config/eggkg.ecf # package manager: the build/install recipe
/equinox/.config/mtcc.ecf # compiler: format, flags, set store, spawn
Two properties make this layer genuinely live rather than decorative:
Read per invocation, never cached at boot. Each tool re-reads its file when it runs. An edit is picked up by the next command. There is no cache to invalidate, no daemon to restart.
A single file per tool, edited as text. There is no drop-in directory, no fragments to merge, no generated cache. You edit one file, in the terminal, with any editor:
edit /equinox/.config/eggkg.ecf
Resolution — ecf_tool_path()¶
The kernel resolves a tool's config path through ecf_tool_path(tool,
for_write) in kernel/library/ecf.c. Its behaviour is asymmetric by
design:
- Reading (
for_write = 0) checks for the file's existence at/mnt/equinox/.config/<tool>.ecfand then/equinox/.config/<tool>.ecf, and returnsNULLif absent. It creates nothing — a read is never allowed to mutate the filesystem. - Writing (
for_write = 1) reuses an existing file's location if there is one; otherwise it creates the.configdirectory at the first candidate that works — the persistent/mnt/equinoxvolume if one is mounted, RAMFS otherwise.
The /mnt candidate comes first so that, on an installed system, a
tool's configuration lives on the durable volume rather than in the
session-scoped RAM filesystem.
Seeding¶
A tool that has never been configured does not fail — it seeds itself and then reads back what it wrote, so the config file remains the only execution path:
eggkg init # writes .config/eggkg.ecf (the default recipe)
config init mtcc # writes .config/mtcc.ecf (the default template)
eggkg init will not overwrite an existing recipe; config init mtcc
likewise leaves an existing file untouched. Both are idempotent
conveniences, not required steps — running the tool with no config
file produces the same seeded defaults.
4. Layer 3 — the action registry (ecf_caller)¶
This is the layer that turns configuration into behaviour.
kernel/library/ecf_caller.c is a string-keyed analogue of
syscall_table[]. Where the syscall table maps a number to a function
pointer, the registry maps a dotted action name to a handler:
mtcc.compile_ruf_eggkg pkg.install_bin pkg.db_record
pkg.read_list pkg.fetch_index set.key
set.path_local set.active
The contract¶
typedef int (*ecf_call_fn)(const struct ecf_call_ctx* ctx);
int ecf_call_register(const char* name, ecf_call_fn fn);
int ecf_call(const char* name, const struct ecf_call_ctx* ctx);
int ecf_call_exists(const char* name);
int ecf_call_count(void);
const char* ecf_call_name_at(int idx);
Every handler receives the same context:
struct ecf_call_ctx {
int argc; /* resolved argument count */
const char* argv[ECF_CALL_ARGC_MAX]; /* $var already substituted */
const char* caller; /* "eggkg", "shell", ... */
};
ecf_call performs an exact-match lookup and invokes the handler,
returning its result. An unknown name returns -1 and prints:
[ERROR] ecf_call: unknown action 'no.such.action' (try: config callers)
Design properties¶
The registry is open. Any module registers its own handlers during
initialisation. Adding a capability means writing a handler and
registering it — the dispatch core is never touched. config_cmd.cpp
registers the set.* family; eggkg.cpp registers the pkg.* and
mtcc.* families.
No heap. The registry is a fixed static array (48 slots), following
the same discipline as ecf.c. There is nothing to allocate and
nothing to free.
Ring-0 only. It is an in-kernel library. The interactive entry
point is the shell's call builtin.
Names are namespaced. <namespace>.<action>[_qualifier], where
each namespace owns its own name space — mtcc.compile_ruf_eggkg and
a hypothetical mtcc.compile_ruf_wizard are distinct actions, not
variants of one.
Introspection¶
config callers
lists every registered action. This is both a discovery tool and the mechanism the error message above points you toward — you never have to guess what a config file is allowed to invoke.
5. Layer 4 — recipes¶
The top layer is the one you edit most: a step list, held inside a tool's config file, that names actions in order and supplies their arguments.
The eggkg recipe¶
.config/eggkg.ecf holds two sections, each an ordered list:
[update]
1 = pkg.read_list $server
2 = pkg.fetch_index $repobase
[install]
1 = mtcc.compile_ruf_eggkg $rufpath
2 = pkg.install_bin $pkgdir
3 = pkg.db_record $name $version
Each line is <order> = <action> <args…>. Arguments beginning with
$ are variables resolved at the moment that step runs:
| Variable | Resolves to |
|---|---|
$server |
the package server (eggkg.server, or an explicit eggkg update <path> override) |
$repobase |
the repository base, derived during update |
$rufpath |
the build recipe for the package being installed |
$pkgdir |
the staging directory the sources were fetched into |
$name |
the package name |
$version |
the package version |
$local |
the local staging root (eggkg.local) |
Because $repobase is derived by step 1 of [update], step 2
resolves it correctly — variables are substituted per-step, not
pre-expanded.
Read fully, then run¶
A recipe is validated in full before anything executes. The entire step list is parsed, every action name is checked against the registry, and only then does execution begin. If any action is unknown, the whole recipe is rejected with a per-step error and nothing runs. Execution also stops at the first failing step — a partial install is never left behind.
This is what keeps configuration honest: a recipe is either entirely valid and runs in the order you wrote, or it is rejected whole. There is no half-applied state.
The recipe is the only execution path¶
eggkg install does not contain a hard-coded build-and-install
sequence that the config merely influences. The step list is the
execution path. On a first run with no config file, the defaults are
seeded and then read back from the file — so even the default
behaviour travels through the same config-driven interpreter.
Handlers wrap the existing, tested monolith logic rather than
reimplementing it. mtcc.compile_ruf_eggkg delegates to the same
function that spawns mtcc -make; pkg.install_bin wraps the same
.mrp-to-/bin move including its zero-copy relinking. The ordering
comes from the config; the work is the proven code.
What is honestly still monolithic¶
Two stages remain in the monolithic path, and this is stated in the recipe comments rather than hidden:
- Fetch. The source-download stage of
installmanages its buffer carefully — it is freed before themtccspawn to avoid heap fragmentation in the 256 MB kernel. Extracting it into a handler would risk that discipline, so it stays inline. index.idxverification. Hash verification duringupdatefollows the same reasoning.
Everything after fetch — build, install to /bin, database record —
runs from the recipe.
Inspecting without running¶
eggkg plan
prints the resolved [install] steps — after variable resolution, in
execution order — without executing any of them. It is the dry-run
counterpart to the validate-then-run guarantee: you can see exactly
what a recipe will do before it does it.
6. Triggering actions by hand¶
Any registered action can be invoked directly from the shell, outside any recipe:
call set.path_local /equinox/.local/tp
call set.key foo bar
call pkg.db_record mytool 1.0
call builds a context with caller = "shell", resolves no variables
(arguments are taken literally), and dispatches. It is the same
ecf_call the recipes use — a recipe is just a list of calls the
config supplies the order for.
This makes actions composable: a handler registered by one module can be driven by a recipe owned by another, or by a person at a prompt, with no glue code in between.
7. Live editing, end to end¶
The whole model converges on one property: a change is live on the next command.
# retarget the compiler's default output format
edit /equinox/.config/mtcc.ecf # [format] default = elf
mtcc -c prog.c # now emits ELF — no reboot
# reorder an install
edit /equinox/.config/eggkg.ecf # move db_record before install_bin
eggkg plan # confirm the new order
eggkg install mytool -y # runs it
# change what `set` writes to from a recipe
call set.active /equinox/conf/other.ecf
No step in that sequence requires a rebuild of the kernel, a restart of a service, or a reboot. The compiler, the package manager and the dispatch registry all re-read what they need at the point of use.
8. Tricks & recipes¶
Everything in this section is configuration only: no kernel rebuild, no recompile, no service restart. Each one is a text edit plus the command that proves it took effect.
Make ELF the default output¶
# /equinox/.config/mtcc.ecf
[format]
default = elf
mtcc -c prog.c now writes a static ELF32 by default, and mtcc -make
produces ELF products, so you can stop passing -format elf on every
build. A recipe's format directive and the CLI -format still
override it, so this is a site-wide default rather than a hard lock.
One caveat worth knowing: -format only applies to -c and -make.
In run mode (mtcc prog.c, which executes in memory and never writes a
file) the setting is ignored and mtcc prints
-o / -format only apply to -c (run mode never writes a file). Leave
format.default = mrp if run mode is the common case.
Build quietly by default¶
[flags]
default = -q
-q is read at process start, so it applies to every subsequent
compile, including the mtcc -make spawned by an eggkg install. Only
-q, -d/--debug and --lib are recognised here, and the flags are
additive: mtcc has no negative flags, so a command line can add to this
default but never subtract from it.
Inject flags into every spawned compile¶
[spawn]
args = -q --lib
The shell prepends spawn.args to the command line when it spawns the
compiler, deliberately before the arguments you typed, so config flags
are parsed first. It reaches every spawn path — the shell's mtcc,
equinoxinstall -build, and the mtcc -make that an eggkg install
performs, since all three funnel through the same spawn helper. Use it
for flags you never want to retype.
Swap the compiler binary¶
[spawn]
name = mtcc_dbg.mrp
Every mtcc and mtcc -make now looks for mtcc_dbg.mrp instead of
mtcc.mrp. The search order is the request's own directory, then
/equinox/tools, then the alternative directory — so dropping a second
binary alongside the first is enough to A/B two compiler builds without
renaming either.
Decide where a recipe's set writes¶
[set]
store = /equinox/conf/experiment.ecf
Recipe set key = value lines go to this file instead of the system
store. A recipe can override the same thing inline:
ecf /equinox/conf/experiment.ecf
set eggkg.local = $buildir
Both are inert until the recipe builds cleanly: set lines are queued
alongside copy/move and flushed only after every job succeeded,
so a broken build cannot half-update a config.
Default the build output folder¶
[buildir]
default = /equinox/.local/staging
Provides $buildir when a recipe does not set out. This is a
fallback, not an override — a recipe's own out <dir> always wins, and
so does an explicit out = line. (rufdir.default follows the same
rule for $rufdir, but the recipe's own folder is normally derived
automatically, so it is rarely reached.)
Reorder, trim, or extend an install¶
# /equinox/.config/eggkg.ecf
[install]
1 = mtcc.compile_ruf_eggkg $rufpath
2 = pkg.install_bin $pkgdir
3 = pkg.db_record $name $version
4 = set.key last.built $name
Lines run in file order — the leading number is decoration, so
reordering means moving lines, not renumbering them. You can delete a
step entirely (dropping pkg.db_record gives a build with no database
entry), duplicate one, or append a new action from any module that has
registered a handler. Then confirm before running it:
eggkg plan # resolved [install] steps, in order, nothing executed
Validation still applies to the edited file as a whole: one unknown action name rejects the section before a single step runs.
Run against an offline or local repository¶
eggkg update /equinox/repo # overrides $server for this run
call set.path_local /equinox/.local # or persist eggkg.local
eggkg update
$server resolves to the explicit argument when one is given, otherwise
to eggkg.server from the system store — so the same recipe works
against a network mirror, a local folder, or nothing at all, without a
single line changing in eggkg.ecf.
Drive one action at a time¶
config callers # what may be invoked
call set.key net.driver e1000
call set.path_local /equinox/.local/tp
call pkg.db_record mytool 1.0
A recipe is only a list of these calls with the order supplied by
configuration. Invoking one by hand is the same dispatch path with
caller = "shell", which makes a handler registered by one module
usable by another module's recipe — or by a person at a prompt.
Retarget the entire store¶
call set.active /equinox/conf/other.ecf # pivot now
set -d /equinox/conf/other.ecf # pivot and persist to boot
set -a /equinox/conf/other.ecf # merge it over the store
set -w /equinox/conf/other.ecf # save the result back
call set.active pivots the session immediately (it sets the
set -d target override and invalidates the store cache); set -d
writes the active.conf = <path> pointer into the active .ecf, so the
next boot sees it too. Because that pointer is also followed by
ecf_file_get, per-tool config files inherit the redirection when they
look up a key the main file does not carry.
Provision a session with a script¶
# /equinox/profile.es
[Eqshell]
Log=True
call set.key net.driver e1000
call set.path_local /equinox/.local
config init mtcc
eggkg plan
set -x profile.es
Every line runs through the ordinary shell dispatch, so a script is just
a recorded sequence of the same commands — and Log=True captures the
output to /eqshell.log. Note the honest limit: there is no boot
autostart; a .es file runs when you ask for it, not when the system
comes up.
A detail worth knowing when scripting: the shell's set KEY VAL edits
the in-memory store and is permanent only after set -w FILE,
whereas call set.key KEY VAL [-> FILE] writes the file immediately.
Pick the former when you want to stage several edits and save once,
the latter when a single call has to be durable on its own.
Discover what is possible¶
| Command | Answers |
|---|---|
config callers |
every action a config file may invoke |
config list |
the active store and which .config/*.ecf files exist |
config show <tool> |
the full text of one tool's config |
config get <tool> <key> |
one value from one tool's config |
eggkg plan |
what [install] will do, in order, before it does it |
set |
every key in the active system store |
Nothing in the configuration layer is undocumented-by-omission: the introspection commands are the discovery mechanism, and the error messages point at them.
9. The layers in one view¶
┌──────────────────────────────────────────────────────────┐
│ 1 system.ecf machine identity (net, eggkg) │
│ └─ overlays, active.conf redirection │
├──────────────────────────────────────────────────────────┤
│ 2 .config/<tool>.ecf per-tool defaults, live │
│ ├─ eggkg.ecf the build/install recipe │
│ └─ mtcc.ecf format, flags, set, spawn │
├──────────────────────────────────────────────────────────┤
│ 3 ecf_caller named actions (open registry) │
│ └─ pkg.* mtcc.* set.* register → dispatch │
├──────────────────────────────────────────────────────────┤
│ 4 recipes ordered steps + $variables │
│ └─ validate fully → run in order → stop on failure │
└──────────────────────────────────────────────────────────┘
▲ ▲ ▲
provisioning tuning a tool changing behaviour
Each layer is reached only through the one outside it, each has a single owner, and the innermost ones are the ones you edit while the system is running.
See also¶
- ECF.md — the
.ecfformat,ecf_tool_path, the registry API, action table - CONFIGURATION.md — the
setbuiltin and eqshell scripts - SYSTEM_ECF.md — every key in the system store
- SET.md — editing configuration, including through
ecf_caller - PACKAGES.md — the eggkg lifecycle this recipe drives
- MTCC_LANGUAGE.md — what
.config/mtcc.ecftunes