145 lines
5.5 KiB
Markdown
145 lines
5.5 KiB
Markdown
# Export / Compile
|
|
|
|
Soleprint's source tree is not what runs. `build.py` compiles the framework plus
|
|
a room's configuration into a self-contained instance under `gen/<room>/`, and
|
|
that directory is what a container boots, what `deploy.sh` rsyncs, and what the
|
|
cluster manifests point at.
|
|
|
|
Everything below is a `make` target, and every target is one script in `ctrl/`.
|
|
The logic lives in the scripts, never in the Makefile.
|
|
|
|
```bash
|
|
make build # cfg/standalone -> gen/standalone
|
|
make build sample # cfg/sample -> gen/sample
|
|
make start # run it
|
|
```
|
|
|
|
## The targets
|
|
|
|
| Command | Runs | Does |
|
|
| --- | --- | --- |
|
|
| `make build [<room>\|all\|models]` | `ctrl/build.sh` | compile a room into `gen/` |
|
|
| `make dist [<room>]` | `ctrl/dist.sh` | compile just the plexus UIs to single files |
|
|
| `make docs [serve\|graphs]` | `ctrl/docs.sh` | serve the docs, or re-render the diagrams |
|
|
| `make start [<room>] [-d]` | `ctrl/start.sh` | run a built room's compose stack |
|
|
| `make stop [<room>]` | `ctrl/stop.sh` | stop it |
|
|
| `make cluster [up\|down\|status]` | `ctrl/cluster.sh` | the shared kind cluster |
|
|
| `make component [list\|publish\|sync\|watch\|diff]` | `ctrl/spr.py` | publish a distributable component |
|
|
| `make deploy` | `ctrl/deploy.sh` | rsync `gen/standalone` to the server and restart |
|
|
|
|
Bare words pass straight through, so `make build sample` becomes
|
|
`ctrl/build.sh sample`. Anything starting with a dash would be eaten by make
|
|
itself, so those go through `ARGS`:
|
|
|
|
```bash
|
|
make deploy ARGS="--build"
|
|
make component ARGS="publish soleprint-ui /tmp/out --dist"
|
|
```
|
|
|
|
## What a build does
|
|
|
|
`python build.py --cfg <room>` runs these in order:
|
|
|
|
1. **Clean** `gen/<room>/`. A build is not incremental — a stale file left
|
|
behind is worse than a slow build.
|
|
2. **Copy the framework.** `main.py`, `run.py`, `index.html`, `Dockerfile`,
|
|
`requirements.txt`, `dataloader/`, `common/`, and the three systems
|
|
(`artery/`, `atlas/`, `station/`).
|
|
3. **Merge the room** (`copy_cfg`). `cfg/<room>/config.json` lands in `cfg/`,
|
|
`data/*.json` in `data/`, and anything under `cfg/<room>/soleprint/artery|atlas|station/`
|
|
is merged *over* the framework copy — which is how a room adds its own vein,
|
|
shunt, tool or generator without forking the tree.
|
|
4. **Compose cabinets.** The dependency containers the room declared in
|
|
`data/cabinets.json` are merged into its `docker-compose.yml`. See
|
|
[Cabinets](#station-cabinets).
|
|
5. **Export plexuses.** Each plexus the room declared in `data/plexuses.json` is
|
|
compiled to a single self-contained `index.html` — theme, data and diagrams
|
|
inlined, so it opens with no server. See [Plexuses](#artery-plexuses).
|
|
6. **Generate models.** modelgen reads the room's `config.json` and writes
|
|
`models/pydantic/__init__.py`.
|
|
7. **Render k8s** (optional). When the room's config enables it,
|
|
`soleprint/ctrl/k8s/` writes manifests and lifecycle scripts.
|
|
|
|
## What comes out
|
|
|
|
A standalone room is a flat instance:
|
|
|
|
```
|
|
gen/standalone/
|
|
run.py main.py Dockerfile docker-compose.yml
|
|
artery/ atlas/ station/ common/
|
|
cfg/config.json
|
|
data/*.json
|
|
models/pydantic/
|
|
plexuses/<name>/index.html # one file each, opens with no server
|
|
```
|
|
|
|
A **managed** room — one that wraps an existing application — is three folders
|
|
instead, because soleprint sits beside the app rather than containing it:
|
|
|
|
```
|
|
gen/<room>/
|
|
<app>/ the application's repos, plus its ctrl scripts
|
|
link/ bridge code between the two
|
|
soleprint/ the instance, exactly as above
|
|
```
|
|
|
|
`build.py` picks between them on whether the room's `config.json` has a
|
|
`managed` block. `gen/` is gitignored in full: it is an artifact, and the way to
|
|
change it is to change `cfg/<room>/` and rebuild.
|
|
|
|
## Distributing components
|
|
|
|
Rooms are compiled; *components* are published. `registry.json` lists what can
|
|
be shipped out of this repo on its own:
|
|
|
|
```bash
|
|
make component # list
|
|
make component ARGS="publish soleprint-ui /tmp/out --dist"
|
|
make component ARGS="watch soleprint-ui ../unt/ui/framework"
|
|
```
|
|
|
|
`--dist` copies only the built bundle — `dist/**` plus `package.json`,
|
|
`README.md` and `LICENSE` — rather than the source. It refuses to publish an
|
|
empty `dist/`, because a component whose bundle was never built is the failure
|
|
that shows up later as a container that starts and renders nothing:
|
|
|
|
```
|
|
no build at soleprint/common/ui
|
|
build it first: cd soleprint/common/ui && pnpm build
|
|
```
|
|
|
|
Each publish leaves a `.spr` stamp in the destination recording name, version,
|
|
type, source and mode, so a copy can say where it came from.
|
|
|
|
## Deploying
|
|
|
|
```bash
|
|
make deploy ARGS="--build" # rebuild, sync, restart
|
|
make deploy ARGS="--sync-only" # sync, leave it running
|
|
```
|
|
|
|
`deploy.sh` rsyncs `gen/standalone/` and runs `docker compose up -d --build` on
|
|
the far side. `.env` is excluded, so server secrets stay on the server.
|
|
|
|
## Running without building
|
|
|
|
`python run.py` from `soleprint/` serves every subsystem on one port (12000 by
|
|
default) straight from the source tree. It is for developing the framework
|
|
itself; a room's `cfg/config.json` does not exist there, so the landing pages
|
|
fall back to their defaults. Rooms use docker.
|
|
|
|
## Diagrams
|
|
|
|
The `.dot` sources under `docs/graphs/` carry structure; the palette lives in
|
|
`docs/graphs/themes/*.gvpr` and is applied at render time, so one source renders
|
|
in every theme.
|
|
|
|
```bash
|
|
make docs graphs # every graph, every theme
|
|
make docs graphs lucid # one theme
|
|
```
|
|
|
|
`<name>.svg` is the dark default the docs link to; other themes write
|
|
`<name>.<theme>.svg`. See [Themes](#themes).
|