# 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

```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 summary of manifest, permissions, entries, objects and methods. |
| `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 the English extension library page `/en/ext` to view the currently installable extensions, versions, permissions and source code addresses.

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