Extended development
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:
result = calc(1).add(2).value() // Output: 3 print result
Learning sequence
| Documentation | Description |
|---|---|
| Quick start | Create, package, install and call the first extension from scratch. |
| Running mechanism | Understand the .bts package, loading process, global entry, Runner and call distribution. |
| manifest.json | Describes the extension package identity, backend type, entry file, permissions and resource limit. |
| bindings.json | Describes which entries, objects and methods the script can call. |
| Pure BT extension | Use BT source code to write extensions, suitable for ordinary script capability encapsulation. |
| WASM extension | Write kind=wasm extension using Rust SDK. |
| SQLite shared example | Verify SQLite connection, transaction, and result limits with the shared WASM extension. |
| Permissions and paths | Describes file permissions, path parameters role and WASI path conversion. |
| Packaging and Installing | Description of bt ext tool chain commands and installation directory rules. |
| Official extension library | 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:
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:
project/ ├── main.bt └── extensions/ └── calc/ └── calc-1.0.0.bts
The extension development directory usually looks like this:
calc/ ├── manifest.json ├── bindings.json └── src/ └── lib.bt
WASM extension development directory usually looks like this:
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:
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:
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.
bt install <name> [version] to extensions/<name>/<name>-<version>.bts.
- The
.btspackage will verify the entry path, file size, manifest, bindings and backend entry. Any zip cannot be renamed and used directly as an extension.
- Extension objects that hold external resources long-term should provide close() or dispose() methods and declare lifecycle: "dispose" in bindings.json.