# 打包构建

## 介绍
bt-app 支持两种桌面应用产物：

- `build` 生成包含 bt-app 运行时和应用资源的独立 exe。
- `pack` 生成只包含应用配置与资源的 `.btr` 软件文件，由已安装的 bt-app 运行时打开。

`.btr` 对用户表示可直接运行的 BT 软件，不是需要手工解压或安装依赖的开发包。内部使用带版本描述的压缩资源容器，根目录包含 `app.json` 和运行时生成的 `btr.json`，不包含 bt-app 自身。因此多个小工具可以共用一个 bt-app 运行时文件，不必为每个工具复制完整 exe。

## 构建独立 exe
在项目目录运行：

```bash
./bt-app.exe build
```

如果当前目录没有 `app.json` 但存在 `index.html`，构建前会先生成默认 `app.json`。默认配置会包含 `app.json`、`index.html` 和常见前端构建目录 `assets/**`。页面引用的其他根目录资源、图片目录或自定义静态目录仍需要手动写入 `resources`。

输出位置：

```text
dist/{app.name}.exe
```

构建时会先生成 BTR 资源容器，再在 `dist` 中生成临时 exe，完成图标、元信息、BTR 注入和读回校验后才替换最终输出。这样中途失败不会留下一个没有应用资源的半成品 exe。若 `dist/{app.name}.exe` 正在运行或被其他程序占用，构建会明确失败并提示先关闭目标程序后重试。

桌面构建只生成单个应用 exe，不会额外写出 FFI 许可证旁路文件。

## 构建 BTR 软件

在项目目录运行：

```bash
./bt-app.exe pack
```

输出位置：

```text
dist/{app.name}.btr
```

`pack` 和 `build` 使用完全相同的 `app.json`、资源收集规则及回读校验；区别仅是 `pack` 不附带 bt-app 运行时。BTR 会记录容器格式版本、构建时 BT 版本和最低运行时版本。运行时在加载页面或执行 `app.main` 前完成格式、版本、路径、条目数量、单文件大小和展开总大小校验。

运行和检查 BTR：

```bash
./bt-app.exe info ./dist/HelloApp.btr
./bt-app.exe run ./dist/HelloApp.btr
./bt-app.exe ./dist/HelloApp.btr
```

`info` 只读取元数据，不执行 `app.main`、`server.bt` 或页面脚本。直接把 `.btr` 路径作为第一个参数是 `run` 的简写。需要向软件传递业务参数时使用 `--` 分隔：

```bash
./bt-app.exe run ./dist/HelloApp.btr -- document.md
```

页面可通过 `window.bt.app.args()` 读取 `document.md`，不会看到 bt-app 命令名、BTR 路径或 `--`。

Windows 下，先把最终安装位置的 bt-app 加入 `PATH`，再执行一次：

```powershell
bt-app.exe associate
```

之后 `.btr` 可通过双击交给该 bt-app 打开。仅加入 `PATH` 不会自动建立 Windows 文件关联；如果用户此前选择过其他默认程序，Windows 仍可能要求在“打开方式”中确认。关联只写当前用户注册表，不需要管理员权限，也不会覆盖系统保护的 `UserChoice`。

## 资源收集
`resources` 支持普通文件、目录和 glob：

```json
{
  "resources": [
    "index.html",
    "main.bt",
    "assets/**",
    "pages/*.html"
  ],
  "exclude": [
    "assets/test/**",
    "assets/*.bak"
  ]
}
```

构建阶段会自动加入必要资源，包括 `app.json`、`static` 入口、主脚本、`server.bt` 和图标。最终打包集合按 `resources - exclude` 计算，普通目录和 `assets/**` 都会递归收集目录下所有文件。`dist/` 始终排除，避免宽泛资源规则把上一轮 exe 或 BTR 递归打入新产物。

## 图标和元信息
配置 `app.icon` 后，构建会校验图标文件存在，并在 Windows 上写入输出 exe 的图标资源：

```json
{
  "app": {
    "name": "IconDemo",
    "icon": "logo.ico",
    "description": "图标示例",
    "copyright": "Copyright 2026 BT"
  }
}
```

当前 `app.icon` 只支持 `.ico`。`description` 和 `copyright` 会写入 Windows exe 版本资源。

文件关联可以声明独立的文档图标。构建器会把每个 `file_associations[].icon` 嵌入 exe 的独立 PE 图标资源组；关联文件使用文档图标，资源管理器右键菜单仍使用应用主图标：

```json
{
  "app": {
    "icon": "icon.ico",
    "file_associations": [
      {
        "extensions": ["md", "markdown"],
        "icon": "markdown.ico",
        "description": "Markdown 文档",
        "context_menu": "以 M++ 打开"
      }
    ]
  }
}
```

关联图标仅支持项目内相对 `.ico` 路径，不需要额外加入 `resources`。省略 `file_associations[].icon` 时，文件类型继续复用 `app.icon`；没有配置应用图标时则使用 bt-app 内置图标。

## 控制台
`dev.console` 为 `false` 时，构建会把 Windows exe 子系统改成 GUI，双击运行时不弹出控制台。

```json
{
  "dev": {
    "console": false
  }
}
```

开发阶段建议使用 `dev.console:true`，便于查看启动摘要、错误和 `echo()` 输出。

## 其他命令
```bash
./bt-app.exe run [目录或 app.btr] [-- 业务参数]
./bt-app.exe info <app.btr>
./bt-app.exe associate
./bt-app.exe bundle-check
```

- `run`：不传目标时运行当前目录项目；传目录时运行指定开发项目；传 `.btr` 时运行指定 BTR 软件。
- `info`：安全读取 BTR 软件信息，不执行软件代码。
- `associate`：Windows 当前用户下把通用 bt-app 注册为 `.btr` 打开程序。
- `bundle-check`：检查当前 exe 是否包含应用资源，并打印资源文件列表；同时兼容旧版 Bundle。


## 平台说明
当前 `build` 逻辑输出单个 `.exe` 文件，Windows 下会处理 GUI 子系统、exe 图标和元信息；`pack` 输出跨产物共用的 `.btr` 资源软件。桌面运行时本身仍需为目标操作系统和架构单独构建。