# 环境搭建

请从官网下载程序包，包中有两个文件，一个`bt`程序，一个`bt-app`程序。

- `bt` 是BT语言解释器，用于编译和运行BT语言程序。
- `bt-app` 是BT桌面应用引擎（内置BT语言解释器），用于桌面软件开发。

如果你需要开发Web项目、API接口，只需要`bt`即可，如果需要开发桌面应用项目，只需要`bt-app`。

可以把解释器放在项目旁直接运行，也可以按下方说明安装到当前用户目录。编写 BT 程序只需要普通文本编辑器。

## 安装解释器

可用性：下列安装命令待下一版本发布，需要使用包含该功能的构建。现有正式版下载可能尚不支持。

### 功能

显式地把当前运行的解释器安装到固定用户目录，配置用户 `PATH`，并为 `.bt` 文件注册桌面执行方式。安装是可选操作，无须管理员账号。打开解释器或执行脚本不会自动安装或更新 BT。

### 语法

在 Windows PowerShell 中，从解压目录执行：

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

在 Linux 或 macOS 中，从解压目录执行：

```text
./bt install
```

如有必要，先执行 `chmod +x bt` 赋予执行权限。在 `bt>` 交互提示符中输入 `install` 或 `update`，不需要可执行文件前缀。原 `--install` 别名已移除。

### 参数

| 命令 | 参数 | 含义 |
|---|---|---|
| `bt install` | 无 | 为当前用户安装或更新当前运行的解释器。 |
| `bt update` | 无 | 从官网下载最新正式版，更新已有的用户安装。 |
| `bt update <name> [--project <dir>]` | 已安装扩展的名称必填，项目目录可选。 | 更新官方扩展，不降级，见[扩展更新](/zh-hans/docs/extensions/cli)。 |
| `bt install <name> [version] [--project <dir>]` | 扩展名称必填，版本和项目目录可选。 | 安装官方扩展，见[扩展安装](/zh-hans/docs/extensions/cli)。 |

解释器安装和更新不接受目标目录或版本参数。`install` 复制当前运行的解释器，不下载其他版本。`update` 要求已有安装，直接从官网下载 Windows x64、Linux x64、macOS ARM64 或 macOS x64 的最新正式版 ZIP，使用发布的大小和 SHA-256 校验，并在替换前检查解压后的解释器版本；同版或更高版本不会降级。它只更新已安装的 `bt`，不更新 `bt-app`，也不覆盖用于调用此命令的便携版可执行文件。

### 返回值

命令会报告解释器安装或保留已有版本的结果，以及平台集成结果。失败信息显示在终端中。这是命令行操作，不返回 BT 语言值。

| 平台 | 安装的解释器 | 桌面集成 |
|---|---|---|
| Windows | `%USERPROFILE%\.bt\bin\bt.exe` | 在用户注册表中配置 `PATH` 和 `.bt` 文件关联。 |
| Linux | `~/.local/bin/bt` | 配置用户 shell 的 `PATH`；有桌面会话时创建终端 `.desktop` 启动器和 MIME 关联。无桌面系统跳过桌面集成。 |
| macOS | `~/.bt/bin/bt` | 配置用户 shell 的 `PATH`；生成 `~/Applications/BT.app`，接收 Finder 打开的 `.bt` 文件并打开终端。 |

安装后请打开新终端，以加载更新后的 `PATH`。解释器仍然是独立二进制。macOS 的 `BT.app` 是安装时生成的桌面辅助入口，不是 `bt-app` 桌面应用运行时；下载 ZIP 无须包含这个辅助入口。

### 示例

保存以下代码为 `demo.bt`：

```bt
// 输出：hello BT
print 'hello BT'
```

安装后打开新终端，执行 `bt demo.bt`。也可以把 BT 选为 `.bt` 文件的默认应用，然后双击 `demo.bt`：终端会显示输出，并在脚本结束后等待按 Enter。详见[如何使用](/zh-hans/docs/usage)。

### 在线更新示例

安装后执行 `bt update`，或在 `bt>` 提示符中输入 `update`。成功时显示旧版本、新版本和安装路径；安装版相同或更新时提示已是最新版本。缺少安装时提示先执行 `bt install`。命令行失败返回非零退出码，交互模式失败后保留当前会话。

### 注意事项

- 安装目录中没有解释器时，复制当前可执行文件。语义版本较新时替换安装版，同版或旧版保留安装版。直接打开下载的旧版解释器时，仍然运行其自身版本。文件关联使用固定的安装路径。
- 在线更新在联网请求、压缩包完整性检查、解压或版本校验失败时保留原解释器。下载和解压均限制为 512 MiB，版本元数据限制为 2 MiB；元数据请求超时为 30 秒，压缩包下载超时为 10 分钟。普通运行不会访问更新服务器。
- Windows 在线更新可以先重命名正在运行的解释器，再发布新文件；安装目录中最多保留一个 `.bt-update-previous.exe`，直到可以删除。如果再次更新提示旧文件仍在使用，请先关闭保留的旧会话。已有会话继续运行原版本，新启动的命令使用新版本，不会强制结束进程。
- Windows 上正在使用的安装版解释器可能被锁定。替换失败时保留原文件；请关闭正在使用安装版 BT 的程序，再从下载的解释器重试安装。安装程序不会强制结束运行中的程序。
- Linux/macOS 上，如果安装程序维护的 `PATH` 配置块被手动修改，会报告需要修复，而不会覆盖。文件或 shell 配置文件的权限可能导致安装只完成部分配置；解决报告的问题后，重新执行 `install` 完成集成。
- 用户 `PATH` 让终端能够找到 `bt`，文件关联单独负责双击执行。终端搜索路径中优先级更高的其他可执行文件仍可能被选中；需要精确指定解释器时，使用安装文件的完整路径。
- 操作系统可能要求用户选择一次 BT 作为默认应用，并尊重已有的明确用户选择。Linux 双击执行要求有桌面环境和兼容的终端；macOS 可能要求允许辅助入口控制终端。
- 普通调用不检查安装目录、安装版本或与安装相关的 `PATH` 状态，也不增加退出暂停。只有显式 `install` 或 `update` 才执行安装或更新工作。
- 桌面执行在正常完成、报错或调用 `exit()` 后等待按 Enter，不修改源码，也不追加 `pause()`；它不会暂停仍在运行的服务，也不能阻止用户直接关闭终端。

## 代码编辑器：
`VS Code` + `扩展（bt-lang）` [在Vscode中直接打开bt-lang扩展](vscode:extension/bt-lang.bt-lang)

### bt-lang扩展支持：

- 支持 BT 语言关键字、函数、字符串等高亮显示
- 智能代码补全以及上下文感知补全
- 在调用函数时显示参数列表与当前参数位置
- 鼠标悬停函数时展示完整说明、参数与返回值信息
- 支持跨文件函数跳转，快速定位定义位置
- 自动扫描并索引所有 BT 文件中的函数
- 自动识别并解析 include 文件中的函数定义
- 在侧边栏展示当前文件的函数结构
- 支持系统函数提示与自动补全
- 快速执行当前工作区中的 BT 程序

## 其它编辑器：
- `HBuilderX` + `扩展（bt-lang）` [到HBuilderX插件市场进行安装](https://ext.dcloud.net.cn/plugin?id=20669)
- `Sublime Text` + `扩展（bt-lang）` [到GitHub中下载，放入【软件安装目录\Data\Packages】即可](https://github.com/bt-lang/editor-extensions/tree/main/SublimeText)