# Extended development

## Function

The BT extension is used to package reusable capabilities into `.bts` files and install them into the `extensions/` directory in the project root directory. When the project starts, BT will scan the `extensions/*.bts` and `extensions/<name>/*.bts` expansion packages, verify the `manifest.json` and `bindings.json` in the package, and then inject the public entry into the script global environment.

 The extension is suitable for encapsulating general business capabilities, computing modules, file processing capabilities, protocol adaptation layers, or components within projects that need to be released independently. The chaining style of BT is still maintained when the script calls the extension, for example:

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

// Output: 3
print result
```

## Learning sequence

| Documentation | Description |
| ------ | ------ |
| [Quick start ](/en/docs/extensions/quick-start) | Create, package, install and call the first extension from scratch. |
| [Running mechanism ](/en/docs/extensions/mechanism) | Understand the `.bts` package, loading process, global entry, Runner and call distribution. |
| [manifest.json](/en/docs/extensions/manifest) | Describes the extension package identity, backend type, entry file, permissions and resource limit. |
| [bindings.json](/en/docs/extensions/bindings) | Describes which entries, objects and methods the script can call. |
| [Pure BT extension ](/en/docs/extensions/bt) | Use BT source code to write extensions, suitable for ordinary script capability encapsulation. |
| [WASM extension ](/en/docs/extensions/wasm) | Write `kind=wasm` extension using Rust SDK. |
| [SQLite shared example ](/en/docs/extensions/sqlite) | Verify SQLite connection, transaction, and result limits with the shared WASM extension. |
| [Permissions and paths ](/en/docs/extensions/permissions) | Describes file permissions, path parameters role and WASI path conversion. |
| [Packaging and Installing ](/en/docs/extensions/cli) | Description of `bt ext` tool chain commands and installation directory rules. |
| [Official extension library ](/en/ext) | Check the official website for installable extensions, versions, permissions and installation commands. |

## Syntax

A `.bts` extension package is essentially a verified zip package, containing at least three files:

```text
manifest.json
bindings.json
Back-end entry file
```

`manifest.json` describes who this extension is, what kind of backend it uses to run, where the entry file is, and what permissions are required. `bindings.json` describes which functions, objects and methods this extension exposes to BT scripts. The backend entry file is the source code or WASM module that actually executes the business logic.

`manifest.kind` represents the extended backend type, and `manifest.abi` represents the calling protocol version used between the backend and the BT host. The two must match:

| kind | abi | entry file | suitable for scenarios |
| ------ | ------ | ------ | ------ |
| `bt` | `bts-bt-1` | BT source code, such as `src/lib.bt` | pure BT logic, business rules, simple reusable modules. |
| `wasm` | `bts-wasi-1` | WASM modules, such as `module.wasm` | High-performance logic written in Rust and other languages, modules that require independent object state. |

`kind=bt` means that the extension entry is provided by BT source code, and the host will compile it with pure BT Runner and call the functions or class methods in it. `bts-bt-1` is the ABI name of this backend, which means that the entries and object methods in bindings will be mapped to the BT `fn` and `pub` methods with the same name.

`kind=wasm` means that the extension entry is provided by the WASM/WASI module, and the host will use WASM Runner to call the `bts_call` distribution function exported by the module. `bts-wasi-1` is the ABI name of this backend and indicates that parameters and return values are passed between the host and WASM linear memory via the BtValueBinary binary format.

A normal BT project after installing an extension usually looks like this:

```text
project/
├── main.bt
└── extensions/
    └── calc/
        └── calc-1.0.0.bts
```

 The extension development directory usually looks like this:

```text
calc/
├── manifest.json
├── bindings.json
└── src/
    └── lib.bt
```

 WASM extension development directory usually looks like this:

```text
calc_sdk/
├── manifest.json
├── bindings.json
├── Cargo.toml
├── module.wasm
└── src/
    └── lib.rs
```

## Parameters

 The parameters of the extension entry and object methods are declared by `bindings.json`. When calling the script, you do not need to care whether the extended backend is pure BT or WASM. You only need to call it in the order of the entry name, method name and parameters exposed by the bindings.

## Return Value

 The extension entry can return ordinary BT values or extension objects. Methods extending the object continue to be called through the dot chain; if the object holds long-term state, a release method should be provided.

## Code Examples

 project script only cares about the entry names exposed by bindings. After the extension package is installed as `project/extensions/calc/calc-1.0.0.bts`, you can directly call:

```bt
value = calc(10).add(5).value()

// Output: 15
print value
```

 The extension entry is injected into the user's global environment, but it is not a system function:

```bt
result = [has_env('calc'), has_envs('calc')]

// Output: [true, false]
print result
```

## Notes

 - The extension entry name must avoid conflicts with system functions, system constants and other extension entries.
- The English extension library page is located at `/en/ext`, where you can view installable extensions, source code addresses, versions, permissions and installation commands.
 - The official extension library can be installed via `bt install <name> [version]` to `extensions/<name>/<name>-<version>.bts`.
- The `.bts` package will verify the entry path, file size, manifest, bindings and backend entry. Any zip cannot be renamed and used directly as an extension.
 - The pure BT extension is suitable for zero-dependency script logic; the WASM extension is suitable for scenarios that require Rust ecology, object state tables, or stronger isolation boundaries.
 - Extension objects that hold external resources long-term should provide `close()` or `dispose()` methods and declare `lifecycle: "dispose"` in `bindings.json`.