# Package and build

## Introduction
bt_app supports two desktop application products:

- `build` generates an independent exe containing bt_app runtime and application resources.
- `pack` generates a `.btr` software file containing only application configuration and resources, which is opened by the installed bt_app runtime.

`.btr` represents to users BT software that can be run directly, not a development package that requires manual decompression or installation of dependencies. A compressed resource container with version description is used internally. The root directory contains `app.json` and `btr.json` generated at runtime, but does not contain bt_app itself. So multiple gadgets can share a bt_app runtime file without having to copy the full exe for each tool.

## Build the independent exe
 and run it in the project directory:

```bash
./bt_app.exe build
```

 If there is no `app.json` in the current directory but `index.html` exists, the default `app.json` will be generated before building. The default configuration will include `app.json`, `index.html` and the common front-end build directory `assets/**`. Other root directory resources, image directories or custom static directories referenced by the page still need to be manually written to `resources`.

 Output location:

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

 When building, the BTR resource container will be generated first, and then a temporary exe will be generated in `dist`. The icon, meta information, BTR injection and readback verification will be completed before the final output is replaced. This way a failure will not leave a half-finished exe with no application resources. If `dist/{app.name}.exe` is running or occupied by other programs, the build will clearly fail and prompt you to close the target program and try again.

The desktop build only generates a single application exe and does not write an additional FFI license bypass file.

## Build BTR software

 and run it in the project directory:

```bash
./bt_app.exe pack
```

Output location:

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

 `pack` and `build` use the exact same `app.json`, resource collection rules, and readback verification; the only difference is that `pack` does not come with the bt_app runtime. BTR records the container format version, build-time BT version, and minimum runtime version. The runtime completes format, version, path, number of entries, single file size and expanded total size verification before loading the page or executing `app.main`.

 Run and check BTR:

```bash
./bt_app.exe info ./dist/HelloApp.btr
./bt_app.exe run ./dist/HelloApp.btr
./bt_app.exe ./dist/HelloApp.btr
```

`info` only reads metadata and does not execute `app.main`, `server.bt` or page scripts. Directly passing the `.btr` path as the first parameter is the abbreviation of `run`. Use `--` to separate business parameters to the software:

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

 page can read `document.md` through `window.bt.app.args()`, and will not see the bt_app command name, BTR path or `--`.

Under Windows, first add the bt_app in the final installation location to `PATH`, and then execute it again:

```powershell
bt_app.exe associate
```

After that, `.btr` can be opened by double-clicking it to the bt_app. Simply adding `PATH` does not automatically establish a Windows file association; Windows may still ask for confirmation in Open With if the user has previously selected a different default program. The association only writes to the current user registry, does not require administrator rights, and does not overwrite the system-protected `UserChoice`.

## Resource collection
`resources` supports ordinary files, directories and globs:

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

The necessary resources will be automatically added during the build phase, including `app.json`, `static` entry, main script, `server.bt` and icons. The final packaging collection is calculated according to `resources - exclude`. Both ordinary directories and `assets/**` will recursively collect all files in the directory. `dist/` always excludes wide resource rules from recursively typing the previous exe or BTR into new products.

## Icon and meta information
 After configuring `app.icon`, the build will verify the existence of the icon file and write the icon resource of the output exe on Windows:

```json
{
  "app": {
    "name": "IconDemo",
    "icon": "logo.ico",
    "description": " icon example ",
    "copyright": "Copyright 2026 BT"
  }
}
```

 Currently `app.icon` only supports `.ico`. `description` and `copyright` write Windows exe version resources.

File associations can declare independent document icons. The builder will embed each `file_associations[].icon` into an independent PE icon resource group of the exe; the associated file uses the document icon, and the resource manager right-click menu still uses the application main icon:

```json
{
  "app": {
    "icon": "icon.ico",
    "file_associations": [
      {
        "extensions": ["md", "markdown"],
        "icon": "markdown.ico",
        "description": " Markdown document ",
        "context_menu": " Open "
      }
    ]
  }
}
```

 The associated icon only supports the relative `.ico` path within the project, and there is no need to add additional `resources`. When `file_associations[].icon` is omitted, the file type continues to reuse `app.icon`; when no application icon is configured, the bt_app built-in icon is used.

## When the console
`dev.console` is `false`, the build will change the Windows exe subsystem to GUI, and the console will not pop up when double-clicking to run.

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

 It is recommended to use `dev.console:true` during the development stage to facilitate viewing startup summary, errors and `echo()` output.

## Other commands
```bash
./bt_app.exe run [directory or app.btr] [-- application arguments]
./bt_app.exe info <app.btr>
./bt_app.exe associate
./bt_app.exe bundle-check
```

- `run`: run the current directory project when no target is passed; run the specified development project when the directory is passed; run the specified BTR software when `.btr` is passed.
- `info`: Safely read BTR software information without executing software code.
- `associate`: Register the general bt_app as `.btr` to open the program under the current Windows user.
- `bundle-check`: Check whether the current exe contains application resources and print the resource file list; also compatible with older versions of Bundle.


## Platform description
 The current `build` logic outputs a single `.exe` file, which will process the GUI subsystem, exe icon and meta information under Windows; `pack` outputs the `.btr` resource software shared across products. The desktop runtime itself still needs to be built separately for the target operating system and architecture.