# 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](/en/docs/build).

```text
bt ext new <dir> [--kind bt|wasm]
bt ext build [dir] [-o <file.bts>]
bt ext install <file.bts> [project_dir]
bt ext info <file.bts>
bt ext check [dir|file.bts]
bt install <name> [version] [--project <dir>]
```

## 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:

```text
target/
.git/
.hg/
.svn/
node_modules/
```

 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:

```text
bt ext install calc.bts project
```

 will copy the extension to:

```text
project/extensions/calc/calc-1.0.0.bts
```

 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:

```text
bt install sqlite
bt install sqlite 1.0.0
bt install sqlite --project examples/app
```

 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:

```text
Installing sqlite 1.0.0...

[1/3] Downloading
[████████████████████████████████████████] 720.3KB / 720.3KB  100%  1.2MB/s

[2/3] Verifying checksum
✔ sha256 OK

[3/3] Installing
✔ completed

Done.
```

## Code Examples

Complete pure BT expansion process:

```text
bt ext new calc
bt ext build calc -o calc.bts
bt ext check calc.bts
bt ext info calc.bts
bt ext install calc.bts project
bt install sqlite 1.0.0 --project project
```

Post-installation project script call:

```bt
result = calc(1).add(2).value()

// Output: 3
print result
```

## 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

```text
bt update sqlite
bt update sqlite --project examples/app
```

### 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.