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:

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:

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:

Output location:

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:

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:

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:

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:

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:

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:

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.

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

Other commands

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.