Package quick start

This section provides instructions on how to use the Toit package manager (henceforth TPM) for common operations. See Packages for the full documentation.

Installing a package

The following CLI commands search for a package, and then install it.

jag pkg search --verbose morse  # Search for a package "morse".
jag pkg install morse # Install package "morse".

Note that the example and test folder generally are considered to be separate projects as they might have different dependencies than the package itself. We recommend to open the example or test folder in separate instances of the IDE.

Unique names

The installation of "morse" only works if the name is unambiguous. If there are multiple "morse" packages, then one has to use the URL. It is possible to omit leading segments if that makes the package unique:

jag pkg install github.com/toitware/toit-morse
jag pkg install toitware/toit-morse  # Probably already unique.

Adding a registry

Toit supports multiple package registries. This can be useful if you want to use packages that are not part of the Toit registry, like private packages.

See which registries are installed:

jag pkg registry list

You should have one or more registries:

toit: github.com/toitware/registry (git)

If not, add a registry; for example the Toit registry:

jag pkg registry add toit github.com/toitware/registry

Creating a package

Create a new Git repository (for example github.com/toitware/toit-morse).

Add or move code into the src folder of the new repository.

Optionally (but strongly recommended) add a LICENSE file. We recommend a permissive free software license, such as MIT.

Optionally (but strongly recommended) add a README.md. The first paragraph should start as if prefixed with "This is a package containing". The first paragraph should have meaning on its own.

Optional (but strongly recommended): polish the package, with an eye on

toitdocs,
types,
examples, and
tests

Create a package.yaml in the root of the repository, with the following entries:

name: The name of the package.
description: A short description of the package.
license: The license of the package. Don't add this entry if there is a LICENSE file. The license file or entry should follow github conventions.
dependencies: a map of dependencies. This are automatically added by install commands, so you rarely have to add them by hand. Each entry should look as follows:
```
  prefix:
    url: <PKG_URL>
    version: <VERSION_CONSTRAINT, such as ^1.0.0>
```

Publishing

Commit everything and tag it with the version number of the package. If you think that the package should be used by other developers, consider giving it a v1.0.0 version number. (There is nothing gained by calling it v0.0.1).

Version numbers must be prefixed with v and follow semantic versioning.

Push your changes to the public repository (if not yet done), and inform a registry of its existence.

For the Toit package registry, publish your new package here. Your package will be validated by the Toit team, before it can be available for the rest of the Toit community. The validation is performed solely to avoid having packages that could be potentially harmful.