Home

Starting a gizmo

Two commands take you from an empty folder to a program that builds, installs and passes its tests. Everything the build needs is prebuilt executables, so a project folder never carries the machine's source tree.

The whole path

> llambda-local-connector new-gizmo llambda-tools.tar.gz C:\projects
established collection: C:\projects
  toolchain: tools.gizmo
  programs: garrage, gofur, wires, buttons, gizmo-runtime, codfish
  worktree: initialised (build paths anchor here)

> llambda-local-connector new-gadget C:\projects greeter
created gizmo: C:\projects\greeter.gizmo
  package: greeter, module Greeter
  routes: --hello, --help

> cd C:\projects\greeter.gizmo\greeter.wires
> onepush.bat
...
Test suite greeter-cog: PASS
1 of 1 test suites (1 of 1 test cases) passed.

> bin\greeter.exe --hello
hello, world

Nothing in between is edited by hand. The rest of this page is what each of those steps did.

1. Establish a collection

llambda-local-connector new-gizmo <archive> <path>

Download the archive from /install/llambda-tools.tar.gz. It is a .tar.gz or .zip that unpacks to tools.gizmo/ at its top level, and it holds executables and nothing else:

tools.gizmo/
  tools.gadgets
  tools.wires/
    bin/
      garrage.exe  gofur.exe  wires.exe
      buttons.exe  gizmo-runtime.exe  codfish.exe

The path you give is the collection root: the folder that will hold the toolchain and, beside it, whatever project gizmos you add. The directory name must end in .gizmos — that suffix is how a collection is recognised, and a patch sent to a directory without one is refused.

Establishing it does three things. It unpacks the toolchain; it marks the collection as a git worktree, because build paths anchor on the enclosing one and without a marker they are written beside the drive root where they are refused; and it creates a bare repository beside the collection, at <collection>.gizmos-origin.git, which is what patches land through.

git must be installed. It is the only prerequisite beyond the connector itself. Nothing is sent anywhere: the repository beside your collection is local, patches land into it from your own machine, and no account, remote host or credential is involved. You do not need a git identity configured either — the connector supplies one for the commit it makes.

2. Scaffold a gizmo

A collection holding only a toolchain has nothing to build. The second command writes a gizmo that compiles, installs and passes its tests as written, with no edits:

llambda-local-connector new-gadget <collection> <name>

Both commands are also available at the connector's own llambda> prompt, which is what you get by running the connector with no arguments or with repl.

An agent can ask for the same scaffold inside a patch — see the patch format's operations.

What the scaffold wrote

These are the files a person goes on to edit. Button manifests, the .cabal, the executable entry point and the test cog are not here: they are generated from the files below and regenerated on every onepush.

greeter.gizmo/
  greeter.gadgets                 authority: the gadget and its junction
  greeter.wires/
    greeter.wire                  name, projects folder, bin folder
    onepush.bat                   build, install, test
    projects/
      wire.project                which packages this gadget holds
      greeter/src/greeter/
        package.nut               dependencies, modules, go-is entry point
        package.garrage           the build-stage view of the same
        package.cog               the test suite
        package.bolt              what the executable links
        buttons.plan              the lifecycle phases
        lib/Greeter.hs            your code

The starting module is a real go-is entry point. The name in package.nut says which function the generated executable dispatches to, and its type is fixed:

go :: String -> [String] -> IO String

The route arrives as the first argument and the rest follow, so adding a command means adding one equation. Returning a string rather than printing is what lets the test cog call routes directly and check what they produce.