Home

Starting a gizmo

A collection needs a toolchain before anything in it can build. The connector establishes one from a packaged tools gizmo, so a project folder gets the tools without carrying the machine's source tree.

Establishing a collection

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

The archive is a .tar.gz or .zip that unpacks to tools.gizmo/ at its top level. The path is the collection root: the folder that will hold the toolchain and, beside it, whatever project gizmos are added. It is created if it does not exist.

Download the current archive from /install/llambda-tools.tar.gz.

What the archive holds

tools.gizmo/
  tools.gadgets
  tools.wires/
    bin/
      garrage.exe  gofur.exe  wires.exe
      buttons.exe  gizmo-runtime.exe  codfish.exe
    projects/
      read-write-and-type/

Why binaries and one library

The tools gizmo declares its executables with expose-bin, which names a program and the folder holding it. It is an authority declaration rather than a build rule: nothing requires the gizmo to have compiled what it exposes, which is what lets it carry prebuilt binaries and no source.

Libraries are different. A libs= grant is supplied to the build as a source path, so any library a project needs must exist somewhere the collection can point at. Exactly one is unavoidable: read-write-and-type, because every generated executable entry point imports it. The archive therefore carries that library's source, and that is why it is a packaged gizmo rather than a folder of executables.

Starting a gizmo

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

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.

Start to running binary

> 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 scaffold writes the files a person would go on to edit — the authority, the wire descriptors, package.nut, the button plan and one library module — and then runs the generators that produce the rest. Button manifests, the .cabal, the executable entry point and the test cog are all generated from those files and regenerated on every onepush.

What the scaffold writes

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.

The junction, if you write one by hand

A gizmo reaches the toolchain through its authority file. The scaffold writes this; it is here because it is the part worth understanding:

use-gizmo tools path=../tools.gizmo/tools.gadgets

junction <gadget> tools:tools libs=read-write-and-type \
  bins=garrage,gofur,wires,buttons,gizmo-runtime,codfish

Two details cost time when a gizmo is assembled by hand. The cabal= field must name the projects-level cabal.project, not the one inside the package: the test phase runs cabal from projects/, so a deeper file is invisible to it and the failure appears much later as an unresolvable dependency. And the collection root has to be a worktree — build paths anchor beside the enclosing one, and without it they are written beside the drive root, where they are refused. new-gizmo marks it for you.