workshopsoft/ludic
2
0
Fork 0
Code Issues Pull requests Projects Releases 26 Packages Wiki Activity Actions

feat(cli): install in one command, and call the CLI ludic

Browse source 
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>
This commit is contained in:
Orkun ÇAKILKAYA 2026-09-05 22:01:52 +03:00
parent 005cc39394
commit aca263642d
54 changed files with 1802 additions and 670 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/PACKAGES.md
View file

@ -1,6 +1,6 @@
# Ludic packages
Ludic has a package manager built into the task runner (`bin/x`). It fetches,
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.
@ -18,14 +18,14 @@ This is the v1 implementation of the direction decided in issue #63.
## Commands
```
x add <module>[@version] add a dependency to package.ludic, then resolve + fetch + link
x get resolve every dependency in package.ludic, link them, write the lock
x update [module] bump a dependency (or all) to its latest published version, then relock
x verify check every locked package against the store by content hash
x vendor copy the resolved packages into ./vendor for hermetic/offline builds
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
```
`x add` with no `@version` picks the latest published tag and records it as the
`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`.
@ -52,17 +52,17 @@ optional for a leaf application).
## The lockfile — `package.lock.ludic`
Generated by `x get`; do not edit by hand. One line per resolved module, pinning
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 `x get`. Do not edit by hand.
# 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"
```
`x verify` rehashes each store entry and confirms the project links to it, so a
`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
@ -176,31 +176,31 @@ always emitted (unused parts dead-strip).
**Publishing.** In the package repo:
```
x build-lib module.ludic # -> lib/<target>/lib<name>.dylib
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:
```
x add git.host/user/module # kind prebuilt is resolved + the dylib linked into the view
x get # links the artifact for the build target (hard error if the target is missing)
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. `x link-flags` prints the exact
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 $(x link-flags) -o game
clang -O2 game.ll $(ludic link-flags) -o game
```
(`x app` links them automatically when building in-repo.) If the package does
not ship the build target, `x get` fails — build from source instead where the
(`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
`x vendor` copies the resolved packages out of the store into `./vendor`. Build
`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.