# Package and build

## Introduction
bt-app supports two desktop application products:

- `build` generates a native executable containing the 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
Windows: dist/{app.name}.exe
Linux/macOS: dist/{app.name}
```

 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 embeds resources in the native executable and does not write an additional FFI license bypass file. Linux also writes `dist/{app.name}.png` and `dist/{app.name}.desktop`. The launcher uses absolute paths; rebuild after moving the output directory. Where GNOME file metadata is supported, the builder assigns the PNG to the local executable so the file manager can show its icon. Other file managers may show a generic executable icon; use the desktop launcher there. Files copied to another machine do not retain local GNOME metadata. Linux builds use `./bt-app build`; the output is ELF, not a Windows PE executable, and no backend is forced to X11.

## 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
 `build` outputs a native executable; Windows retains the `.exe` suffix and GUI subsystem, PE icon, and metadata processing; `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.