ThicketScript

Using packages ​

A package is ThicketScript source from somewhere else: another folder, a git repository or a zip. You list it under packages in thicket.json and import it by name. Packages are source only: nothing runs when one is fetched, and no package contains native code.

json5
{
    entry: "app.tks",
    packages: {
        willowui: "../willowui-tks",                              // a folder next to this project
        shared: "https://github.com/example/shared-tks#v1.2.0",   // a git repo at a tag
        icons: "https://example.com/icons.zip",                   // a zip
        mathx: "mathx",                                           // thicket_packages/mathx/
        oldlib: false,                                            // switched off
    },
}
ts
import { Button } from "willowui/src/core/button";
import { lerp } from "mathx/easing";

The key is the import name. "name" loads the package's entry file. "name/sub/path" loads another file inside it.

One string per package ​

The shape of the string says where the package comes from:

You writeIt is
./, ../, /, ~/ or a drive letterA folder, used in place.
https://, http://, ssh:// or git@host:A git repository. Add #tag, #branch or #commit to pin it.
Anything ending in .zipA zip archive, local or downloaded.
A plain nameA folder called thicket_packages/<name>/.
false, null, "", "no", "false" or "none"Switched off.

Where a plain name is found ​

The first folder that exists wins:

  1. thicket_packages/<name>/ next to your thicket.json.
  2. thicket_packages/<name>/ in each parent folder, up to the drive root. Handy for a workspace of projects that share packages.
  3. Your per-user folder: ~/.local/share/thicket/thicket_packages/ on Linux, ~/Library/Application Support/thicket/thicket_packages/ on macOS, %APPDATA%\thicket\thicket_packages\ on Windows.

There is no install command yet. To use a plain name, copy or link the folder into thicket_packages/ yourself.

One flat folder ​

Every package, including the packages your packages use, is resolved once, by name, for the whole program.

  • Git and zip packages are fetched into your project's thicket_packages/, side by side, never nested.
  • Two different sources for the same name anywhere in the program is an error that names both.
  • Packages that list each other are fine.

Git and zip packages ​

  • Fetched once and reused. After the first fetch, runs and checks work offline.
  • Fetched again only when the string changes, or when you delete the package's entry in thicket.lock.
  • Git uses the git on your PATH with your own credentials.
  • Zips are checked for unsafe entries before anything is written.
  • thicket check fetches what is missing. The editor never fetches.

thicket.lock ​

thicket.lock sits next to thicket.json and records what each string resolved to: the git commit, the zip's hash, or a folder and its content hash. Commit it, and gitignore thicket_packages/. The .gitignore that thicket new writes already does.

When something no longer matches the lock, the error names the package and the fix: delete that entry in thicket.lock to accept the change.

You import only what you list ​

If a package you use depends on dep, you cannot import dep yourself until you add it to your own packages.

You grant what packages need ​

A package's permissions and systems say what it needs. Only the project you run grants anything. If willowui needs fs, your project turns on fs. If it lists willow, your project lists willow too, or leaves systems out entirely. Every unmet need is reported at once:

text
willowui needs fs; add it to permissions

Names you cannot use ​

Package keys cannot be the name of a system or core module (willow, fs, http and so on), or system, engine, thicket, thicketscript, tks or heartwood. They cannot be empty, start with ., or contain /, \, : or spaces.

Next: writing a package.