Compiling your app

Summary#

Compiles the source on your disk into your app on the local platform (Running a local platform) — the inner-loop compile-and-apply. Additive changes (new entities, fields, functions) apply directly; changes that would remove or reshape existing data are held until you authorise them with a migration.

Signature#

osy compile [path] [--prune] [--generate-migration] [--migration <file>] [--json]

Description#

osy compile finds the local platform for your project, ensures your app exists there, and compiles the current source into it. It needs no account and no credentials — the local platform is yours. If no platform is running for the project, it starts one for you in the background and leaves it running, so you never have to start a server first — the compile is a single command. (See Running a local platform, and Stopping the local platform to shut it down.)

• --prune reconciles the app to the source, dropping metadata the source no longer declares. On a local (Development) app these apply; removing something in production requires a migration.
• --generate-migration writes migrations/<hash>.migration with a verb for each non-additive change — a drop, a rename or rebase it inferred, or a comment where it would not choose. Writing a verb is the acknowledgement, so review it before applying it with --migration; it does not apply anything.
• --migration <file> applies a migration you have reviewed and authorised.
• --json writes the compile result as JSON.

After a successful compile it says, in one line, when the access check is due: it has not been run on this project, it ran as an older version of the check, the source changed since, or it found mismatches. That line never stops the compile, and goes to standard error under --json (Checking access).

Compiling against a remote platform is the operator command osyrin app compile — the same compile, a different target.

Examples#

osy compile                       # starts the local platform if needed, then applies the current source
osy compile --generate-migration  # preview a migration for any non-additive changes
osy compile --new-version         # mint a new version instead of applying in place

A parked run stops the deploy#

An ordinary compile applies in place: the app's current version is rewritten and everything reads the new source immediately. That is what you want in the inner loop — until a workflow run is parked, waiting on an event, standing on the shape your edit is about to change. Applying in place would replace the model underneath it, and the run would resume into a body it never started under: a state it never entered, or a step it never took.

So the compile stops and tells you which runs are in the way:

$ osy compile
This deploy changes something a parked run is resolving through, and 1 run is parked on the current version.
  · osy compile --new-version   — mint a NEW version. Parked runs are drained onto it, and any that cannot be
                                  moved safely are reported so you can write a migration verb for them.
  · osy cancel-runs             — retire the parked runs, then deploy in place.
Nothing has been written; the app is exactly as it was.

Both answers are ordinary. --new-version is the one to reach for when the parked work matters; osy cancel-runs is right when the runs are leftovers from an earlier iteration and you do not care where they end up.

⚑ It only fires when both halves are true — a run is actually parked (not merely finished), and your edit reaches a workflow, a function a workflow calls, or an entity such code touches. Editing a page, or an entity no workflow touches, deploys in place with runs parked and says nothing.

See also#

Migrating runs that are still in flight — the verbs that move a parked run onto a new version when the shape changed under it.

Importing data — load the app's rows, the other half of "copy this app and it works".

Running a function — run one of the app's functions once it is compiled.

Running a local platform — the local platform your app compiles into.

Launching your app — open the app in a browser after compiling.

Running tests locally — run your app's tests (which compile the source too).