Setup

A program folder should never need its own copy of machines/. When your program says Include "seq.shoddy" — a bare filename, no path — the mill looks in three places, in order:

1. beside the including file, so a program’s own pieces always win;
2. the directory named by SHODDYLIB, if you have set one. SHODDYLIB is an environment variable — a named setting your operating system hands to every program it starts;
3. the machine library shipped with the mill that is running — machines/ beside the executable, then one level up beside its bin/.

That third rule is why nothing needs configuring. The mill inside the extension finds the machines staged beside it. A mill you build yourself finds the repo’s machines/ from bin/. Both work from any folder on disk, with no environment variables set at all.

You normally never set SHODDYLIB. Set it only if you keep several checkouts — separate copies of the repository — and want a program pinned to one of them. It is no longer part of installing Shoddy. If you do set one, the editor steps aside and lets it win.

The mill is a .NET program, so it needs the .NET runtime — the support package that lets .NET programs run. It needs the runtime, not the much larger SDK, which is the full developer kit. Check first with dotnet --list-runtimes. If nothing at version 10 appears, install from dotnet.microsoft.com, or:

winget install Microsoft.DotNet.Runtime.10

brew install --cask dotnet-runtime

Download the latest .vsix from the latest release, then in VS Code: Extensions view → the ··· menu → Install from VSIX… → pick the file you downloaded. Reload when prompted.

The release page also carries sparky — the calculator packaged as an MCP server, a plug-in that lets an AI assistant use the calculator. It is a separate, self-contained download. It needs neither this extension nor the runtime. The sparky page has the per-client registration shapes — the snippet each assistant client needs.

Use a scratch folder anywhere on disk — any throwaway folder will do. That is the real test, because it proves a program folder needs nothing of its own:

1. Create check.shoddy:

   Include "stats.shoddy"
   
   Def Main()
       Print(Sum({ 1, 2, 3 }))

2. Open the folder in VS Code and press the ▶ Run button (or ctrl+r) — expect 6.
3. Press F5 on the same file: the perch — Shoddy’s debugger — stops on the first line. That proves the debugger half of the chain too. The VS Code page is the tour.

If step 2 reports unknown word: Sum or cannot open the include, see Troubleshooting below.

Check with dotnet --version. If it’s missing or older than 10, install from dotnet.microsoft.com/download, or:

winget install Microsoft.DotNet.SDK.10

brew install dotnet-sdk

The mill is not committed to the repository, so you build it yourself from the repo root. The verify run should print HELLO FROM SHODDY and a run of worked examples. (What the wrapper actually runs, and why it’s a folder publish, is on the Toolchain page.)

git clone https://github.com/shoddymills/shoddy
cd shoddy
.\build.ps1 build
bin\mill.exe run tst\examples.shoddy

git clone https://github.com/shoddymills/shoddy
cd shoddy
./build.sh build
bin/mill run tst/examples.shoddy

That is the whole setup. bin/mill finds the repo’s machines/ one level up on its own, so bare includes work immediately with nothing set. ./build.ps1 machines (./build.sh machines) compiles the library to machine DLLs up front. You can skip that: a machine is always used compiled, so the mill builds any machine you use that is missing one anyway.

This step only lets you type mill instead of the full path to bin/mill. PATH is the list of folders your terminal searches when you type a command.

echo 'export PATH="$HOME/github/shoddy/bin:$PATH"' >> ~/.zshrc

Machine-level symptoms — the ones that come from installs and paths, not from your program. Editor-side symptoms (F5 fails but ▶ works, millPath) are in the VS Code page’s table.