Extension packaging and installation

Function

bt ext is a BT extension toolchain, used to create extension projects, build .bts packages, install to projects, view package information and perform load checks. The official extension library is installed remotely using the top-level command bt install.

Command

Interpreter installation is separate: in builds containing the pending next-release feature, bt install without an extension name installs the interpreter for the current user. bt install <name> keeps the extension behavior documented here. See environment setup.

Parameters

Command	Description
`new <dir>`	Create an extension development directory and generate `kind=bt` scaffolding by default.
`new <dir> --kind wasm`	Create WASM extension development directory and generate Rust SDK scaffolding.
`build [dir]`	Package `.bts` from the extension development directory, and output `<manifest.name>.bts` by default.
`build [dir] -o <file>`	Specify the output package path, the `.bts` suffix must be used.
`install <file> [dir]`	Verify the local package and copy it to the target project `extensions/<name>/<name>-<version>.bts`.
`info <file>`	View the manifest, entries, objects, methods, and runtime limits.
`check [dir\|file]`	Verify that the development directory or `.bts` package can be loaded by the current BT build.
`bt install <name>`	Install the latest compatible version from the official website extension library.
`bt install <name> <version>`	Install the specified three-stage version from the official website extension library.
`--project <dir>`	Specify the remote installation target project directory, the default is the current directory.

Return Value

bt ext is a command line tool and does not return a value to the BT script. When the command is successful, the execution progress and results are output; when the command fails, a Chinese error is output and a failure status is returned.

Packaging rules

bt ext build will collect ordinary files in the development directory and skip:

When packaging, the number of .bts package entries, single file size, total decompression size and path within the package will be limited. After writing the zip, the tool will read back .bts and initialize the corresponding Runner to ensure that the package can be loaded at runtime.

Installation rules

installation command:

will copy the extension to:

The target directory and file name come from manifest.name and manifest.version in the package, not the file name passed in from the command line. Before installing a new version with the same name, the old <name>-*.bts under extensions/<name>/ will be deleted to prevent the same project from loading two extension versions with the same name at the same time. The runtime is still compatible with the old extensions/*.bts top-level package.

Remote installation command:

You can first open /en/ext to view the reviewed open-source extensions, versions, package hashes, and source repositories currently distributed by the official website.

The remote installation will first read the official website metadata, then download the .bts temporary file, verify SHA-256, file size, manifest.name, manifest.version, kind and abi in the package and then write it to the project extension directory. When downloading fails, verification fails, or package backend loading fails, half of the .bts file will not be left that can be loaded at runtime.

The remote installation output is divided into three steps: download, verification and installation:

Code Examples

Complete pure BT expansion process:

Post-installation project script call:

Notes

bt ext new will not overwrite non-empty directories.
If the output path of bt ext build is located in the development directory, the tool will avoid typing the output package into the package again.
Both bt ext install and bt install will keep only one version of the extension with the same name in the project.
Local installation does not contact or require the official registry. Installing an extension means trusting its code; private and closed-source packages are supported but are outside the official catalog's review.
The first stage of bt install only supports the three-stage version of major.minor.patch, and does not support range versions and transitive dependencies.

- The extended CLI command will output the build, installation or check results to the terminal when successful; when it fails, it will output a Chinese error and will not generate a partially loadable .bts package.

- The default build has the extensions feature enabled and can use bt ext directly; bt ext and project extension loading are not available only when building the lightweight version with --no-default-features.

Update an installed extension

Availability: pending the next release. bt update <name> [--project <dir>] updates an existing official extension to the registry's latest version. With no extension name, bt update updates the interpreter instead. The interactive prompt accepts the same commands.

Syntax

Parameters

Parameter	Type	Required	Default	Valid values and meaning
`name`	String	Yes for extension updates	None	Installed official extension name; lowercase letters, digits and underscores, beginning with a lowercase letter.
`--project <dir>`	Path string	No	Current working directory	An existing project directory containing `extensions/<name>/`.

A version argument is not accepted. To explicitly install a chosen version, use bt install <name> <version>.

Result and notes

This command prints update progress or an up-to-date message, without returning a BT language value. Command-line failures return a nonzero exit status; the interactive prompt stays open after failures. The extension must already contain exactly one valid installed package. The current version is read from its manifest; equal or newer installed versions are preserved. The latest official version must not be withdrawn and must support the running BT version. An incompatible version produces an error; update BT first and retry. Download size, SHA-256, manifest identity, and backend compatibility are checked before replacement. If publishing the new package or validating the project's extensions fails, the old package is restored. Other extensions are unchanged. Restart scripts or applications that already loaded the extension to use the new version.