livery.toolroom.bench._provision¶
livery.toolroom.bench._provision ¶
Fetch the latest curated tools into a throwaway prefix — the engine behind
fm toolroom.provision.
The stubs are read from the installed binaries (fm toolroom.read), so
telling an editor what the newest release accepts means having the newest
release on PATH — across five ecosystems (PyPI, npm, bun, Go, C++), none of
which should be allowed to touch the machine's own environment.
One isolated prefix answers all of it. A tool comes from its own release
when it has one: a forge tier downloads the release asset for the host. PyPI
is the tier for programs that are Python, where the wheel is the release; a
wheel around a Rust or C++ binary is a wrapper with a platform gap wherever
the wheel is missing, so a tool that is not Python never sits on the uv
tier (a test pins the tier's members). What the forge tiers do not cover is
node (its own release index), the npm packages and their runtimes, and the
Python tools:
- uv —
uv tool install --upgrade <pkg>, tools and launchers under the prefix; nothing lands in~/.localor the system site-packages. Python programs only. - bun — bun's GitHub release, unpacked into the prefix: the runtime a node-tier package names instead of node.
- nodejs — node's build for this platform from nodejs.org, unpacked
whole into the prefix with npm beside it, and
nodelinked into the prefix'sbin. Provisioned before the node tier, which runs on it. - node — each npm package through its runtime:
npm install --globalon the provisioned node, orbun add --globalwithBUN_INSTALLpointed at the prefix where the driver names bun. - github / gitlab — the latest release asset for this platform, matched
from the release's own asset list (so
Darwin/x86_64vsdarwin/x64naming needn't be transcribed), unpacked whole, a launcher placed in the prefix. - system — git, docker, the uv running this: already on
PATH, left be. - deferred — parked, with a reason (tea, until it stops hanging on
--help).
Everything writes under one prefix and PATH="<prefix>/bin:$PATH" is all a
sync needs to read the newest binaries; deleting the prefix undoes it. This
is a maintainer tool: it shells out and downloads, and it is never on the
completion hot path.
Classes:
| Name | Description |
|---|---|
ProvisionError |
A tool could not be fetched — reported per tool, never fatal. |
Outcome |
What became of one tool: the line |
Functions:
| Name | Description |
|---|---|
bin_dir |
The one directory to put on |
exe |
name as this platform spells an executable. |
provision |
Materialise the latest of each curated tool under prefix. |
provisioned_node |
The node the nodejs tier unpacked under prefix, or None before it ran. |
provisioned_dotnet |
The dotnet the dotnet tier unpacked under prefix, or None before it ran. |
assets_for |
|
place_binary |
Unpack archive whole and put its |
write_launcher |
A launcher in into that runs target with args first; its path. |
Attributes:
| Name | Type | Description |
|---|---|---|
HOST_TOKENS |
Each store host key as an OS and a CPU, in the spellings the alias tables fold. |
HOST_TOKENS
module-attribute
¶
HOST_TOKENS = {host: (_SYSTEMS[host.split('-')[0]], _MACHINES[host.split('-')[1]]) for host in HOSTS}
Each store host key as an OS and a CPU, in the spellings the alias tables fold.
Outcome
dataclass
¶
bin_dir ¶
exe ¶
name as this platform spells an executable.
Windows resolves a command through PATHEXT, so an extensionless PE is
invisible to shutil.which and to every reader that follows it. Every
tier that names a binary needs the same suffix, and each one that grew
its own copy of the conditional was a separate Windows bug — the placed
file gained .exe while the tier still looked for the bare name.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
provision ¶
Materialise the latest of each curated tool under prefix.
Tiers run in the one order that matters: the runtimes before the npm packages that run on them. Each tool's failure is its own line, never the run's — a missing binary should read as one skipped hint, not a broken provision.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
provisioned_node ¶
The node the nodejs tier unpacked under prefix, or None before it ran.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
provisioned_dotnet ¶
The dotnet the dotnet tier unpacked under prefix, or None before it ran.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
assets_for ¶
[(asset name, download url)] for one release — latest when tag is
empty, and a specific tag when priming a tool's history.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
place_binary ¶
place_binary(archive: Path, tool: str, into: Path, *, windows: bool | None = None, launcher: bool = True) -> Path
Unpack archive whole and put its tool in into; the file placed there.
An archive is unpacked as it is, into a trees/<tool> directory
beside into, and the binary runs where it lies, so an app that
loads its runtime from beside itself (a PyInstaller directory app,
conan's release) finds it. What lands in into is a launcher that
runs the binary in its tree: a shell script, or a .cmd on Windows
where shutil.which finds it through PATHEXT. With launcher
off the binary itself is copied into into, for a place that must
hold the real file (a docker plugin directory). A downloaded bare
binary is placed as it is either way. The binary is the first file
member named tool or tool.exe, so a directory of the same name
(docker's docker/docker) never matches.
Raises:
| Type | Description |
|---|---|
ProvisionError
|
when the archive will not unpack or holds no such file. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_provision.py
write_launcher ¶
write_launcher(into: Path, name: str, target: Path, *args: str, windows: bool | None = None) -> Path
A launcher in into that runs target with args first; its path.
A shell script that execs the target, so the process is the target
itself and finds what sits beside it; on Windows a .cmd, which
cmd resolves through PATHEXT and forwards %* to whole.