Orkuncakilkaya
aca263642d
Getting started meant cloning the repository, bootstrapping a compiler and
learning a task runner called `x`. That is a contributor's workflow handed to
everyone who wants to try the language.
Installing is now one command:
curl -fsSL https://workshopsoft.pages.workshopsoft.io/ludic/install.sh | sh
install.sh puts a complete toolchain — compiler, CLI, engine runtime, bundled
ludic.* packages, formatter, language server — in ~/.ludic and adds it to PATH.
Prebuilt artifacts are checksum-verified; where a platform has none, or the
release predates this layout, it bootstraps from the compiler's own IR seed with
clang. The docs site publishes the script beside the pages that quote it, so the
page and the script can never come from different releases.
`x` becomes `ludic`, and the surface splits by audience. A user of the language
sees `new`, `run`, `build`, `test`, `add`, `fmt`, `lsp`, `doctor`, `upgrade`;
`ludic new` scaffolds a project that builds and plays as it stands. Everything
the toolchain repo needs moved under `ludic dev` — build, test, reseed,
bootstrap-cfree, docs-gen, release — unchanged apart from the namespace. Those
tasks read arguments one position further along, so dispatch_dev sets a shift
and commands use arg_n()/arg_total() rather than each knowing its own depth.
Release artifacts become complete install roots (bin/ beside runtime/, packages/
and VERSION) rather than bare binaries, which is what the installer unpacks.
`ludic dev test` asserts the whole shape: it stages an install, puts it on PATH
with no LUDIC_HOME, and runs new -> build -> test through it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
206 lines
9.7 KiB
Markdown
206 lines
9.7 KiB
Markdown
# Ludic packages
|
|
|
|
Ludic has a package manager built into the task runner (`bin/ludic`). It fetches,
|
|
resolves, stores and links third-party packages with no new infrastructure to
|
|
run — it drives plain `git` and rides on the Forgejo host and its release tags.
|
|
|
|
This is the v1 implementation of the direction decided in issue #63.
|
|
|
|
## The four decisions
|
|
|
|
| Axis | Ludic's choice |
|
|
| --- | --- |
|
|
| Where source comes from | **URL-as-identity, no registry.** The import path *is* the git location — `git.workshopsoft.io/user/pkg`. A `git tag vX.Y.Z` publishes a version. No account, no publish step, no index to run. |
|
|
| Version resolution | **Minimum Version Selection (MVS), Go-style.** A `require` is a *minimum*; the resolver picks, per module, the greatest of every required minimum, then keeps the reachable closure at those versions. Deterministic, no SAT solver. |
|
|
| Where dependencies live | **A content-addressed global store + per-project links (pnpm-style).** One immutable store keyed by a file-content hash (`~/.ludic/store/<sha256>`); each project gets a light linked view under `ludic_modules/` instead of a full copy. |
|
|
| Manifest / lock | **`package.ludic`** (declared deps + provided namespaces + kind + targets) and **`package.lock.ludic`** (resolved versions + content hashes). |
|
|
|
|
## Commands
|
|
|
|
```
|
|
ludic add <module>[@version] add a dependency to package.ludic, then resolve + fetch + link
|
|
ludic get resolve every dependency in package.ludic, link them, write the lock
|
|
ludic update [module] bump a dependency (or all) to its latest published version, then relock
|
|
ludic verify check every locked package against the store by content hash
|
|
ludic vendor copy the resolved packages into ./vendor for hermetic/offline builds
|
|
```
|
|
|
|
`ludic add` with no `@version` picks the latest published tag and records it as the
|
|
minimum. All the install commands print the resolved build list and write
|
|
`package.lock.ludic`.
|
|
|
|
## The manifest — `package.ludic`
|
|
|
|
A line-oriented manifest. `#` starts a comment; strings are double-quoted.
|
|
|
|
```
|
|
package "git.workshopsoft.io/orkun/greeter" # this package's import path
|
|
version "1.2.0" # the version this checkout publishes
|
|
kind source # source | prebuilt
|
|
provides "Greet" # the Foo.* namespace(s) it registers (repeatable)
|
|
|
|
require "git.workshopsoft.io/orkun/util" "1.0.0" # a dependency and its minimum version
|
|
|
|
# a prebuilt lib also declares the targets it ships:
|
|
# kind prebuilt
|
|
# targets "native-arm64" "wasm32"
|
|
```
|
|
|
|
A consumer project's manifest is the same file, usually with only `require`
|
|
lines (the `package`/`version` fields describe a *publishable* package and are
|
|
optional for a leaf application).
|
|
|
|
## The lockfile — `package.lock.ludic`
|
|
|
|
Generated by `ludic get`; do not edit by hand. One line per resolved module, pinning
|
|
its selected version, content hash, kind and provided namespaces:
|
|
|
|
```
|
|
# package.lock.ludic — generated by `ludic get`. Do not edit by hand.
|
|
lock 1
|
|
module "git.workshopsoft.io/orkun/greeter" version "1.2.0" hash "sha256:…" kind "source" provides "Greet"
|
|
module "git.workshopsoft.io/orkun/util" version "1.0.0" hash "sha256:…" kind "source" provides "Util"
|
|
```
|
|
|
|
`ludic verify` rehashes each store entry and confirms the project links to it, so a
|
|
tampered or missing dependency is caught before it reaches a build.
|
|
|
|
## The store and the project view
|
|
|
|
Fetched packages live once in a global, immutable, content-addressed store:
|
|
|
|
```
|
|
~/.ludic/store/<sha256>/… the package tree at a version (no .git)
|
|
~/.ludic/store/cache/<module>/ a git clone cache used during resolution
|
|
```
|
|
|
|
Each project gets a lightweight view — `ludic_modules/<import-path>` is a symlink
|
|
into the store — so many projects share one copy and nothing is duplicated
|
|
per-project. Override the store location with `$LUDIC_STORE`.
|
|
|
|
## Consuming a package — namespace registration
|
|
|
|
A **source package** ships plain Ludic. The consumer imports the package files by
|
|
their import path:
|
|
|
|
```
|
|
program App {
|
|
import "git.workshopsoft.io/orkun/greeter/greet.ludic"
|
|
entry { print(greet_hello()) }
|
|
}
|
|
```
|
|
|
|
The compiler resolves an import first relative to the importing file, then — for
|
|
a non-absolute path that is not found — under the package module root
|
|
(`$LUDIC_MODULES`, default `ludic_modules/`). So a fetched package's code is
|
|
spliced into the build and its namespace becomes available exactly the way the
|
|
built-in stdlib namespaces (Regex.\*, Grid.\*, …) are.
|
|
|
|
The **engine runtime is the exception** (issue #75): the compiler auto-splices
|
|
`runtime/native/*` for any ECS game, and that runtime ships with the *toolchain*,
|
|
not the project. A `runtime/...` import that is not found relative to the build is
|
|
resolved from the install root **`$LUDIC_HOME`** (default: the compiler binary's
|
|
directory — the same place the platform `.ll` files come from), *before* the
|
|
package module root. So an external game does not have to copy or symlink the
|
|
engine runtime into its `ludic_modules/`; that directory holds only third-party
|
|
packages. In-repo builds are unaffected — the runtime resolves locally there. Because Ludic compiles
|
|
ahead-of-time, a source package is compiled *into* the consumer's binary — no
|
|
ABI seam, and the whole-program guarantees (determinism, replay, `world_save`)
|
|
still hold.
|
|
|
|
Two packages may not register the same `Foo.*` namespace — a collision is a hard
|
|
error naming both modules.
|
|
|
|
## Package-declarable namespaces and engine systems (issue #62)
|
|
|
|
A package can register two things that used to be compiler-hardcoded — a `Foo.*`
|
|
namespace and an engine-owned system — with **no compiler edit**, via two
|
|
keyword-free annotations. This is what lets gameplay-controller libraries ship as
|
|
ordinary packages instead of living in the compiler's stdlib.
|
|
|
|
- `@Namespace(Name)` on a function opens a `Name.method(…)` namespace that
|
|
dispatches to the bare `name_method(…)` (the same generic path the built-in
|
|
namespaces use, applied only after them so it never shadows a core one):
|
|
|
|
```
|
|
@Namespace(Coach) function coach_bonus() -> int { return 99 }
|
|
# a consumer then writes Coach.bonus()
|
|
```
|
|
|
|
- `@EngineSystem(Component, Phase)` registers an engine-owned system: the frame
|
|
loop calls it every `Phase` (after the game's own handlers) whenever the named
|
|
`Component` is present — the package-declarable form of the built-in
|
|
`SpriteAnim`/`Motion`/`Light2D` systems. It reads and writes components by name
|
|
through the reflection ABI, so an unused registration is byte-identical:
|
|
|
|
```
|
|
@EngineSystem(Score, Update) function esys_score() -> void { … }
|
|
```
|
|
|
|
The core stdlib namespaces and engine systems keep their own optimized codegen;
|
|
packages flow through the generic registry alongside them. (For a *prebuilt*
|
|
binary module, the runtime counterpart of `@EngineSystem` is `@System(Phase)` —
|
|
see below.)
|
|
|
|
## Prebuilt binary packages (issue #64)
|
|
|
|
A `kind prebuilt` package ships a **compiled artifact** (a native dylib per
|
|
target it lists in `targets`) instead of source. A consumer uses its exported
|
|
**functions, systems and components** without ever seeing the source. This is
|
|
the escape hatch for closed-source or other-language code; source packages stay
|
|
the default because they keep cross-compilation (including wasm) and the
|
|
compile-time ECS first-class. Prebuilt packages are **native-only** and ride the
|
|
stable reflection C-ABI — second-class ECS (dynamic, by-name components; one
|
|
indirect call per registered system), not part of the deterministic/replay core.
|
|
|
|
**How a binary module works.** The module is compiled with `--emit-module`: no
|
|
`main`, no world table (the consumer owns the single world). It carries a
|
|
load-time constructor that, when the dylib loads, registers its pieces against
|
|
the host through the C-ABI:
|
|
|
|
- **Components** — `world_register_prop(name, nfields)` in a `module_init`
|
|
function; the host owns storage, the module reads/writes by name with
|
|
`world_get`/`world_set`/`world_has`/`world_attach_dyn`.
|
|
- **Systems** — a function marked `@System(Phase)` is registered with
|
|
`ludic_register_system`; the host's frame loop calls it every frame in that
|
|
phase, after its own handlers. Phases: `Input`, `FixedUpdate`, `Update`,
|
|
`LateUpdate`, `Render`, `Start`, `OnQuit`.
|
|
- **Functions** — plain functions become dylib symbols; a consumer binds them
|
|
with `extern function name(...) -> T = "fn_name"`.
|
|
|
|
A module registers its `ludic_*` calls as undefined and binds them back to the
|
|
host image at load (`-undefined dynamic_lookup`); the host exports its ABI
|
|
(`-export_dynamic`). Every Ludic game is a capable host — the reflection ABI is
|
|
always emitted (unused parts dead-strip).
|
|
|
|
**Publishing.** In the package repo:
|
|
|
|
```
|
|
ludic build-lib module.ludic # -> lib/<target>/lib<name>.dylib
|
|
# add `kind prebuilt` and `targets "<target>"` to package.ludic, commit lib/, git tag
|
|
```
|
|
|
|
**Consuming.** In the game project:
|
|
|
|
```
|
|
ludic add git.host/user/module # kind prebuilt is resolved + the dylib linked into the view
|
|
ludic get # links the artifact for the build target (hard error if the target is missing)
|
|
```
|
|
|
|
then link the module dylibs into the game build. `ludic link-flags` prints the exact
|
|
clang flags (the dylib, an rpath to the store, `-export_dynamic`) for any build
|
|
system to splice into its link step:
|
|
|
|
```
|
|
clang -O2 game.ll $(ludic link-flags) -o game
|
|
```
|
|
|
|
(`ludic build` links them automatically when building in-repo.) If the package does
|
|
not ship the build target, `ludic get` fails — build from source instead where the
|
|
package offers it.
|
|
|
|
## Offline / hermetic builds
|
|
|
|
`ludic vendor` copies the resolved packages out of the store into `./vendor`. Build
|
|
against the copy with `LUDIC_MODULES=vendor`, so the build needs neither the
|
|
network nor the global store.
|