From fa231fe73a8e557fba92bd6d6ff9f8c9d29aa2df Mon Sep 17 00:00:00 2001 From: Florian Loitsch Date: Thu, 6 Aug 2026 00:37:38 +0200 Subject: [PATCH 1/2] Replace obsolete toit.pkg commands --- .github/workflows/ci.yml | 2 +- docs/language/imports.mdx | 6 +++--- docs/language/package/index.mdx | 14 +++++++------- docs/language/package/pkgconcepts.mdx | 16 ++++++++-------- docs/language/package/pkgguide.mdx | 12 ++++++------ 5 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index db973b6b..d05fd7dd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,7 +42,7 @@ jobs: run: | export TOIT_SDK=${{ steps.setup-toit.outputs.toit-install-dir }}/toit cd tools - $TOIT_SDK/bin/toit.pkg install + $TOIT_SDK/bin/toit pkg install ./run_all.sh ci: diff --git a/docs/language/imports.mdx b/docs/language/imports.mdx index 51371c3d..8d2bdc0c 100644 --- a/docs/language/imports.mdx +++ b/docs/language/imports.mdx @@ -118,15 +118,15 @@ name as the last segment instead. Say, we want to use the [morse package](https://github.com/toitware/toit-morse). When installing this package with `jag pkg install github.com/toitware/toit-morse`, -(or with `toit.pkg ...`) the package manager +(or with `toit pkg ...`) the package manager downloads the sources and adds a mapping from the package's name `morse` to the location it downloaded the sources. Specifically, the mapping points to the `src` folder of the package. If you are using Jaguar, you should use -`jag pkg` (with a space) to install packages. If you are using the -standalone open source Toit SDK, you should use `toit.pkg` (with a dot). +`jag pkg` to install packages. If you are using the standalone open source +Toit SDK, you should use `toit pkg`. Here is the file hierarchy of the `morse` package: diff --git a/docs/language/package/index.mdx b/docs/language/package/index.mdx index be17fe5f..5f8fede2 100644 --- a/docs/language/package/index.mdx +++ b/docs/language/package/index.mdx @@ -22,11 +22,11 @@ installs the package 'morse'. The Toit package manager (henceforth TPM) is integrated with the [Toit SDK](https://toitlang.org/). -All of its commands start with the `toit.pkg` command. +All of its commands start with the `toit pkg` command. For example: ```shell -toit.pkg install github.com/toitware/toit-morse +toit pkg install github.com/toitware/toit-morse ``` installs the package 'morse'. @@ -77,15 +77,15 @@ It's also possible to view the list of all available packages in the [package re The name of the package must be non-ambiguous, and thus might need a qualifier. Since TPM doesn't have a single namespace, many packages can have a similar short name. This is by design (as it allows decentralized and private packages), but it might sometimes require to be a little bit more specific when installing a package. For example, `jag pkg install utils` might not be specific enough to uniquely identify a package, and a more qualified name, such as `jag pkg install some_company/utils` could be necessary. -Toit programmers synchronize this repository, giving them access to all the descriptions in that registry. This is done through the `toit.pkg sync` command which simply pulls the latest changes. +Toit programmers synchronize this repository, giving them access to all the descriptions in that registry. This is done through the `toit pkg sync` command which simply pulls the latest changes. -With all the descriptions, Toit programmers can find the package they want. The `toit.pkg search ` command searches for relevant packages. +With all the descriptions, Toit programmers can find the package they want. The `toit pkg search ` command searches for relevant packages. Note that searching or browsing packages is done locally in the synchronized registries. -Developers can then install any of the packages by writing `toit.pkg install `. +Developers can then install any of the packages by writing `toit pkg install `. It's also possible to view the list of all available packages in the [package registry web-site](https://pkg.toit.io/packages) or search for a specific package by its name. -The name of the package must be non-ambiguous, and thus might need a qualifier. Since TPM doesn't have a single namespace, many packages can have a similar short name. This is by design (as it allows decentralized and private packages), but it might sometimes require to be a little bit more specific when installing a package. For example, `toit.pkg install utils` might not be specific enough to uniquely identify a package, and a more qualified name, such as `toit.pkg install some_company/utils` could be necessary. +The name of the package must be non-ambiguous, and thus might need a qualifier. Since TPM doesn't have a single namespace, many packages can have a similar short name. This is by design (as it allows decentralized and private packages), but it might sometimes require to be a little bit more specific when installing a package. For example, `toit pkg install utils` might not be specific enough to uniquely identify a package, and a more qualified name, such as `toit pkg install some_company/utils` could be necessary. @@ -110,7 +110,7 @@ package. However the `.packages` directory is local and should not be committed. For git, `.packages/` should be added to your `.gitignore` file. Before being able to use a program or package on a different computer one -has to run `jag pkg install` or `toit.pkg install` to +has to run `jag pkg install` or `toit pkg install` to download the packages that are specified in the lock file. ## Good practice diff --git a/docs/language/package/pkgconcepts.mdx b/docs/language/package/pkgconcepts.mdx index 00d7b8eb..a2f50443 100644 --- a/docs/language/package/pkgconcepts.mdx +++ b/docs/language/package/pkgconcepts.mdx @@ -8,9 +8,9 @@ Code that is not intended to be used by other projects is simply called a "progr When a program uses a package, that dependency is registered in the program's yaml file `package.yaml` and lock file `package.lock`. The latter is where the mapping from `prefix` to package is stored. Programs have concrete dependencies. All their dependent packages are resolved to a specific version, not a range of versions. These versions are written in the lock file. -When a developer calls `jag pkg install` or `toit.pkg install` they always get the same packages. A team of developers working on the same project will thus work with the exact same versions. +When a developer calls `jag pkg install` or `toit pkg install` they always get the same packages. A team of developers working on the same project will thus work with the exact same versions. -Both files must be located at the root of the project. Certain commands (like `pkg install`) automatically create these file if one doesn't exist yet. Be careful, as they are created in the current directory, which might not be the root directory. It is a good idea to initialize a new project with `jag pkg init` or `toit.pkg init` to create the files in the root directory. +Both files must be located at the root of the project. Certain commands (like `pkg install`) automatically create these file if one doesn't exist yet. Be careful, as they are created in the current directory, which might not be the root directory. It is a good idea to initialize a new project with `jag pkg init` or `toit pkg init` to create the files in the root directory. @@ -56,15 +56,15 @@ you could clone it from Github, then update your your `package.yaml` and `packag ```shell -jag pkg remove font_clock -jag pkg install --local --name=font_clock ../../toit-font-clock +jag pkg uninstall font_clock +jag pkg install --local --prefix=font_clock ../../toit-font-clock ``` ```shell -toit.pkg remove font_clock -toit.pkg install --local --name=font_clock ../../toit-font-clock +toit pkg uninstall font_clock +toit pkg install --local --prefix=font_clock ../../toit-font-clock ``` @@ -97,7 +97,7 @@ jag pkg install ```shell -toit.pkg install +toit pkg install ``` @@ -183,7 +183,7 @@ A registry collects descriptions of available packages. Conceptually it's a data Most of the time, developers only work with the public [github.com/toitware/registry](https://github.com/toitware/registry) registry. However, TPM supports multiple registries. Companies are free to create their own private registries and use them instead of, or in addition to, the public Toit registry. -Similar to packages, registries also exist in two variants: Git and local registries. Git registries are added to TPM with a Git-URL, and can be synchronized with `jag pkg sync` or `toit.pkg sync` (see the [quick start](../pkgguide) section for more). +Similar to packages, registries also exist in two variants: Git and local registries. Git registries are added to TPM with a Git-URL, and can be synchronized with `jag pkg sync` or `toit pkg sync` (see the [quick start](../pkgguide) section for more). Local registries are just pointers to a path that contains descriptions. diff --git a/docs/language/package/pkgguide.mdx b/docs/language/package/pkgguide.mdx index 4455a5cc..be1fbfda 100644 --- a/docs/language/package/pkgguide.mdx +++ b/docs/language/package/pkgguide.mdx @@ -33,8 +33,8 @@ jag pkg install toitware/toit-morse # Probably already unique. ```shell -toit.pkg search --verbose morse # Search for a package "morse". -toit.pkg install morse # Install package "morse". +toit pkg search --verbose morse # Search for a package "morse". +toit pkg install morse # Install package "morse". ``` Note that the example and test folder generally are considered to be @@ -47,8 +47,8 @@ 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: ```shell -toit.pkg install github.com/toitware/toit-morse -toit.pkg install toitware/toit-morse # Probably already unique. +toit pkg install github.com/toitware/toit-morse +toit pkg install toitware/toit-morse # Probably already unique. ``` @@ -85,7 +85,7 @@ jag pkg registry add toit github.com/toitware/registry See which registries are installed: ```shell -toit.pkg registry list +toit pkg registry list ``` You should have one or more registries: @@ -97,7 +97,7 @@ toit: github.com/toitware/registry (git) If not, add a registry; for example the Toit registry: ```shell -toit.pkg registry add toit github.com/toitware/registry +toit pkg registry add toit github.com/toitware/registry ``` From c572e110173f293251410f1824315a870edbfd6a Mon Sep 17 00:00:00 2001 From: Florian Loitsch Date: Thu, 6 Aug 2026 00:49:59 +0200 Subject: [PATCH 2/2] Clarify package manager prose --- docs/language/imports.mdx | 10 ++++------ docs/language/package/index.mdx | 8 ++++---- docs/language/package/pkgconcepts.mdx | 6 +++--- docs/language/package/pkgtutorial.mdx | 4 ++-- 4 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/language/imports.mdx b/docs/language/imports.mdx index 8d2bdc0c..c85b3001 100644 --- a/docs/language/imports.mdx +++ b/docs/language/imports.mdx @@ -116,12 +116,10 @@ of an import finds a folder, Toit tries to find a file with the same name as the last segment instead. Say, we want to use the [morse package](https://github.com/toitware/toit-morse). -When installing this package -with `jag pkg install github.com/toitware/toit-morse`, -(or with `toit pkg ...`) the package manager -downloads the sources and adds a mapping from the package's name `morse` to -the location it downloaded the sources. Specifically, the mapping points to -the `src` folder of the package. +When installing this package with the package manager—for example, with +`jag pkg install github.com/toitware/toit-morse`—it downloads the sources and +adds a mapping from the package's name `morse` to the location of the downloaded +sources. Specifically, the mapping points to the `src` folder of the package. If you are using Jaguar, you should use diff --git a/docs/language/package/index.mdx b/docs/language/package/index.mdx index 5f8fede2..0745b80a 100644 --- a/docs/language/package/index.mdx +++ b/docs/language/package/index.mdx @@ -22,7 +22,7 @@ installs the package 'morse'. The Toit package manager (henceforth TPM) is integrated with the [Toit SDK](https://toitlang.org/). -All of its commands start with the `toit pkg` command. +When invoked through the standalone SDK, its commands start with `toit pkg`. For example: ```shell @@ -109,9 +109,9 @@ shared with other developers who want to work with the same application or package. However the `.packages` directory is local and should not be committed. For git, `.packages/` should be added to your `.gitignore` file. -Before being able to use a program or package on a different computer one -has to run `jag pkg install` or `toit pkg install` to -download the packages that are specified in the lock file. +Before using a program or package on a different computer, run the package +manager's `install` command to download the packages specified in the lock +file. ## Good practice diff --git a/docs/language/package/pkgconcepts.mdx b/docs/language/package/pkgconcepts.mdx index a2f50443..670f17ad 100644 --- a/docs/language/package/pkgconcepts.mdx +++ b/docs/language/package/pkgconcepts.mdx @@ -8,9 +8,9 @@ Code that is not intended to be used by other projects is simply called a "progr When a program uses a package, that dependency is registered in the program's yaml file `package.yaml` and lock file `package.lock`. The latter is where the mapping from `prefix` to package is stored. Programs have concrete dependencies. All their dependent packages are resolved to a specific version, not a range of versions. These versions are written in the lock file. -When a developer calls `jag pkg install` or `toit pkg install` they always get the same packages. A team of developers working on the same project will thus work with the exact same versions. +Installing the dependencies recorded in the lock file always retrieves the same packages. A team of developers working on the same project will thus work with the exact same versions. -Both files must be located at the root of the project. Certain commands (like `pkg install`) automatically create these file if one doesn't exist yet. Be careful, as they are created in the current directory, which might not be the root directory. It is a good idea to initialize a new project with `jag pkg init` or `toit pkg init` to create the files in the root directory. +Both files must be located at the root of the project. Certain package-manager commands, such as `install`, automatically create these files if they don't exist yet. Be careful, as they are created in the current directory, which might not be the root directory. It is a good idea to use the package manager's `init` command to create the files in the project root. @@ -183,7 +183,7 @@ A registry collects descriptions of available packages. Conceptually it's a data Most of the time, developers only work with the public [github.com/toitware/registry](https://github.com/toitware/registry) registry. However, TPM supports multiple registries. Companies are free to create their own private registries and use them instead of, or in addition to, the public Toit registry. -Similar to packages, registries also exist in two variants: Git and local registries. Git registries are added to TPM with a Git-URL, and can be synchronized with `jag pkg sync` or `toit pkg sync` (see the [quick start](../pkgguide) section for more). +Similar to packages, registries also exist in two variants: Git and local registries. Git registries are added to TPM with a Git-URL and can be synchronized with the package manager's `sync` command (see the [quick start](../pkgguide) section for more). Local registries are just pointers to a path that contains descriptions. diff --git a/docs/language/package/pkgtutorial.mdx b/docs/language/package/pkgtutorial.mdx index de8ffabe..2d2dc06c 100644 --- a/docs/language/package/pkgtutorial.mdx +++ b/docs/language/package/pkgtutorial.mdx @@ -133,8 +133,8 @@ dependencies: version: ^1.0.0 ``` -You normally don't need to worry about them, as they are automatically added when -running `jag pkg install ` or `toit pkg install `. +You normally don't need to worry about them, as they are automatically added by +the package manager's `install` command. ## Polishing