This section provides instructions on how to use the Toit package manager (henceforth TPM) for common operations. See Packages for the full documentation.
Some Toit installations use the program
toit.pkg instead of
toit pkg. If you
have one of these installations you will need to substitute the correct command in
the examples below.
You might need to add a registry as the first thing, before you can proceed with installing a package (see below).
The following CLI commands update the local registry, search for a package, and then install it.
toit pkg sync # Synchronize the installed registries. toit pkg search morse # Search for a package "morse". toit pkg install morse # Install package "morse".
It is important to execute these commands in the correct folder. Ideally, they should be run in the root of the project that needs the package.
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.
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:
Before being able to install any package, one must have a registry installed. Newer versions of the
toit CLI do this automatically, but it never hurts to check:
See which registries are installed:
You should have one or more registries:
If not, add a registry; for example the Toit registry:
Create a new Git repository (for example
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 title should be the package-name. The first paragraph should start as if prefixed with "This is a package containing". The first paragraph should have meaning on its own.
Optionally (but recommended) add a CHANGELOG.md.
Optional (but strongly recommended): polish the package, with an eye on
- examples, and
package.yaml in the root of the repository, with the following entries:
name: The name of the package. Don't add this entry if the README's title is the package-name.
description: A short description of the package. Don't add this entry if the README's first paragraph is a good description.
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. Each entry should look as follows:
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
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.