Bundle Command

The bundle command is used to bundle scripts and files into a standalone executable with zune.

zune.toml settings are also applied into the bundled build, allowing custom formatting settings, color settings, etc. (none of the source data of zune.toml is stored in the bundled build, only the configured settings).

The command bundles all scripts and files with path names in the final build. All final paths in the executable are always relative to the current working directory.

If you build outside of the home directory, there is a chance unwanted path names would be embedded in the final build (this can be disabled). zune would also print a warning but won’t error.

zune would only embed the home path relative to the current working directory. This is to allow you to use ~ in .luaurc.

Requires should also work with bundled builds if you bundle with all your necessary scripts.

Usage

zune bundle [...flags or files]

• [...flags or files] - flags & files to use for the bundle command.

The first source obtained by exact path or glob pattern would be the entry file that zune would execute, it is recommended to define the entry file first.

The last flags would take priority.

Example

zune bundle src/main.luau src/**/*.luau -f **/*.png **/*.html --out=build/myproject

• zune.toml
• build
  • myproject
• src
  • assets
    • icon.png
    • page.html
  • modules
    • a.luau
    • b.luau
  • main.luau
  • utils.luau

Flags

Read

This flag is the only one that must be explicitly first and the path to the bundled app provided after.

This would read the bundled app, and output information about the app, but only showing size, bundle format information, main entry file name, etc.

In cases if an invalid bundled app is provided, --read flag would display if whether the bundle does not exist or is corrupted.

Useful for validating the bundle, inspecting size/usage and entry script.

zune bundle --read <executable>

All luau flags, like optimization level, debug level, native code generation, etc. are supported, this would be reflected on the final bundled build.

Optimization Level

zune bundle -O=0|1|2 ...

Debug Level

zune bundle -g=0|1|2 ...

Native

Enables native code generation by default. This is the default behavior.

zune bundle --native ...

No-native

Stops zune from using native code generation by default. This does not remove the native code generation, checkout no-jit flag.

zune bundle --no-native ...

No-jit

Disables native code generation entirely.

zune bundle --no-jit ...

Limbo

Disables all of builtin libraries.

zune bundle --limbo ...

No-fmt

Disables print formatting

zune bundle --no-fmt ...

Out

When provided, zune would make recursively make directories (if needed) and override existing file (if it exists) to the specified path.

If not provided, the default name would be the entry script name (if the default file exists, an error would be displayed).

zune bundle --out=<path> ...

Exe

zune would bundle the scripts and files with the provided path.

zune bundle --exe=<path> ...

Release

zune would embed pre-compiled luau bytecode instead of luau source code of all scripts.

zune bundle --release ...

Debug

zune would embed luau source code of all scripts.

Useful for making debug builds and using detailed error features.

zune bundle --debug ...

No_home

Disables embedding the home path in the final build.

zune bundle --no_home ...

Home

Sets a custom home path to embed in the final build.

zune bundle --home=<path> ...

Compression

Uses the specified compression algorithm to compress each file in the final build. This can reduce the size of embedded files, and would be decompressed at runtime, whenever the file is used.

At times it is better to use this command when working with pretty medium or large files.

zune bundle --compression=<zlib|lz4|zstd|gzip|flate> ...

Sources

Scripts

When you pass --scripts or -s to the command, all file arguments after this flag would be stored as scripts in the bundled app.

Example

zune bundle main.luau a.luau -s b.luau c.luau --scripts d.luau **/*.luau

Files

When you pass --files or -f to the command, all file arguments after this flag would be stored as files in the bundled app.

Example

zune bundle main.luau -f a.txt b.png --files c.luau **/*.md

Scripts & Files Example

zune bundle -f a.txt -s main.luau b.luau --files c --scripts d.luau