# Environment setup

 Please download the program package from the official website. There are two files in the package, one `bt` program and one `bt-app` program.

- `bt` is a BT language interpreter, used to compile and run BT language programs.
- `bt-app` is a BT desktop application engine (built-in BT language interpreter) for desktop software development.

 If you need to develop Web projects and API interfaces, you only need `bt`. If you need to develop desktop application projects, you only need `bt-app`.

You can keep the interpreter beside your project and run it directly, or install it for your user account as described below. A plain text editor is sufficient to write BT programs.

## Install the interpreter

Availability: the installation commands below are pending the next release and require a build containing this feature. Existing release downloads may not yet support them.

### Function

Explicitly install the currently running interpreter into a fixed user directory, configure the user `PATH`, and register `.bt` files for desktop execution. Installation is optional and does not require an administrator account. Opening the interpreter or running a script never installs or updates BT automatically.

### Syntax

In Windows PowerShell, run from the extracted directory:

```text
.\bt.exe install
```

On Linux or macOS, run from the extracted directory:

```text
./bt install
```

If necessary, first grant execution permission with `chmod +x bt`. At the `bt>` interactive prompt, enter `install` or `update` without the executable prefix. The former `--install` alias has been removed.

### Parameters

| Command | Arguments | Meaning |
|---|---|---|
| `bt install` | None | Install or update the currently running interpreter for this user. |
| `bt update` | None | Download and update an existing user installation to the latest stable release from the official website. |
| `bt update <name> [--project <dir>]` | An installed extension name is required; the project directory is optional. | Update an official extension without downgrading; see [extension updates](/en/docs/extensions/cli). |
| `bt install <name> [version] [--project <dir>]` | An extension name is required. Version and project directory are optional. | Install an official extension; see [extension installation](/en/docs/extensions/cli). |

Interpreter installation and updates accept no destination or version parameter. `install` copies the running interpreter and never downloads another version. `update` requires an existing installation and fetches the latest stable Windows x64, Linux x64, macOS ARM64, or macOS x64 ZIP directly from the official website, using the published size and SHA-256 digest. It checks the extracted interpreter version before replacement and never downgrades an equal or newer installation. It updates only the installed `bt`, not `bt-app` or the portable executable from which the command was invoked.

### Result

The command reports installation or retention of the existing interpreter and platform integration results. Failures are reported in the terminal. It is a command-line operation and does not return a BT language value.

| Platform | Installed interpreter | Desktop integration |
|---|---|---|
| Windows | `%USERPROFILE%\.bt\bin\bt.exe` | User registry entries for `PATH` and `.bt` file associations. |
| Linux | `~/.local/bin/bt` | User shell `PATH`; a terminal `.desktop` launcher and MIME association when a desktop session is available. Headless systems skip desktop integration. |
| macOS | `~/.bt/bin/bt` | User shell `PATH`; generated `~/Applications/BT.app` receives `.bt` files from Finder and opens Terminal. |

Open a new terminal after installation so it can load the updated `PATH`. The interpreter remains an independent binary. On macOS, `BT.app` is a generated desktop helper, not the `bt-app` desktop application runtime; the download ZIP does not need to contain this helper.

### Example

Save this as `demo.bt`:

```bt
// Output: hello BT
print 'hello BT'
```

After installation, open a new terminal and execute `bt demo.bt`. You can also select BT as the default application for `.bt` files and double-click `demo.bt`: a terminal displays the output and waits for Enter after the script finishes. See [usage](/en/docs/usage).

### Online update example

After installation, run `bt update`, or enter `update` at the `bt>` prompt. Success prints the old and new versions and installed path; an equal or newer installed version reports that it is up to date. A missing installation reports that `bt install` is required. Command-line failures return a nonzero exit status; interactive failures keep the session open.

### Notes

- A missing installed interpreter is copied from the running executable. A newer semantic version replaces the installed binary; the same or an older version preserves it. A downloaded older interpreter still runs its own version when opened directly. File associations use the fixed installed path.
- Online updates preserve the old interpreter if the network request, archive integrity check, extraction, or version verification fails. Downloads and extraction are bounded to 512 MiB; release metadata is bounded to 2 MiB. Metadata requests time out after 30 seconds and archive downloads after 10 minutes. Ordinary runs never contact the update server.
- Windows online updates can rename the running interpreter before publishing the new binary, retaining at most one `.bt-update-previous.exe` in the installation directory until it can be removed. Close an older retained session before another update if requested. Existing sessions continue on their original version; newly launched commands use the new version. No process is forcibly stopped.
- On Windows, an installed interpreter that is still in use may be locked. A failed replacement preserves it; close programs using the installed BT and retry installation from the downloaded interpreter. The installer does not forcibly terminate running programs.
- On Linux/macOS, a manually changed installer-managed `PATH` block is reported for repair rather than overwritten. File or profile permissions can leave installation only partly configured. Correct the reported problem and rerun `install` to complete integration.
- User `PATH` makes `bt` discoverable in a terminal; file associations separately enable double-click execution. Another executable earlier in the terminal's search path may still take precedence; use the full installed path when selecting an exact interpreter.
- The operating system may require you to choose BT as the default application once. Existing explicit user choices are respected. Linux double-click execution requires a desktop environment and a compatible terminal; macOS may require permission for the helper to control Terminal.
- Ordinary invocations perform no installation-directory, installed-version, or installation-related `PATH` checks and add no exit pause. Only explicit `install` or `update` starts installation or update work.
- Desktop execution waits for Enter after normal completion, errors, or `exit()`. It does not edit the source or append `pause()`; it does not pause a still-running service or protect against closing the terminal itself.

## Code editor:
`VS Code` + `bt-lang extension`: [open the bt-lang extension](vscode:extension/bt-lang.bt-lang) directly in VS Code.

### bt-lang extension support:

- Support BT language keywords, functions, strings, etc. highlighting
- Intelligent code completion and context-aware completion
- Display the parameter list and current parameter position when calling a function
 - Display complete description, parameter and return value information when the mouse hovers over a function
 - Support cross-file function jumps to quickly locate definition locations
 - Automatically scan and index functions in all BT files
 - Automatically identify and parse function definitions in include files
 - Display the function structure of the current file in the sidebar
 - Support system function prompts and automatic completion
 - Quickly execute the BT program in the current workspace

## Other editors:
- `HBuilderX` + `bt-lang extension`: [install it from the HBuilderX plugin marketplace](https://ext.dcloud.net.cn/plugin?id=20669).
- `Sublime Text` + `bt-lang extension`: [download it from GitHub](https://github.com/bt-lang/editor-extensions/tree/main/SublimeText) and place it under `[installation directory\Data\Packages]`.