Tools
Last updated
Last updated
Tool definitions
Each tool definition shares a set of attributes:
Field | |
---|---|
Note: If the tool has a
runtime
attribute, the runtime's environment is merged in to its environment (discussed in the examples below).
Broadly speaking, there are 3 kinds of tools - download, package, and runtime-based tools. We'll look at each one in turn:
Download-based tools are straightforward: They reference a named download configuration in the global downloads
section. Here is an example:
Note that for the downloaded archive, the binary named gh
is inside the bin
directory, so we use the environment to point the $PATH
there.
strip_components
: This number of leading directory components to remove from all files in an archive when extracting.
rename_single_file
: If an archive contains a single file, this will cause that file to be renamed to the name of the tool. This is most useful for downloads of gzip'd binaries with the platform name in the binary.
Package-based tools depend on specified package
and runtime
attributes. Here is an example of configuring mypy
as a tool:
extra_packages
behaves equivalently to a package file like requirements.txt
for Python or package.json
for Node. They can be optionally pinned at versions.
The version of the primary package (in this case, mypy
) is specified in the tools.enabled
. So to enable the mypy
tool at 1.4.0
, list it as - mypy@1.4.0
.
If you don't want to include additional packages in the tool definition, you can instead make them explicit in the enabled section of your .trunk/trunk.yaml
as you would for linters, for example:
Runtime-based tools are a special case that are not explicitly defined. Rather, each runtime object exposes a set of shims
(just like tool
definitions).
If the runtime is enabled and listed in tools.runtimes
, then shims exposed by that runtime are automatically installed in the .trunk/tools
directory alongside those of other tools (trunk tools enable <runtime_tool>
does that for you). Thus you can run python
, pip
, etc as trunk
-managed tools.
Example:
If this is disruptive to your workflow, simply remove the runtime's name (go, node, python,...)
from tools.runtimes
section or run trunk tools disable <runtime_name>
which will handle it for you. Runtimes cannot be enabled or versioned via the tools.enabled
section, however, and runtimes must be enabled in the runtimes
section to be available to have their shims installed.
name
The name of the tool. Must be unique.
known_good_version
The default version to initialize the tool at (required).
shims
A list of binaries exposed by the tool. Each of these will correspond to one identically named executable installed in .trunk/tools.
In the most common case, there is exactly one shim matching the name of the tool. We'll discuss other cases below.
environment
You can specify an environment for the tool. We provide the ${tool}
template argument that resolves to the installation directory of the tool. By default, we prepend this to $PATH
within the shim script, so this is used to locate the binary. For legacy reasons, ${linter}
also resolves to this directory.