Squish

Combine multiple Lua files into a single compact, executable script

Overview

Squish is a powerful build tool that packages multiple Lua scripts, modules, and resources into a single executable file. Perfect for distributing Lua applications and libraries without dependency hassles.

Features

Module Bundling — Combine multiple Lua modules into one file
Minification — Strip whitespace, comments, and optimize code
Uglification — Obfuscate identifiers and compress keywords
Resource Embedding — Pack any file type into your script
Debug Support — Preserve line numbers and filenames in tracebacks
Gzip Compression — DEFLATE algorithm for maximum size reduction
Bytecode Compilation — Compile to Lua bytecode (experimental)

Quick Start

Requirements

Lua 5.2 or later (including Lua 5.3, 5.4, and LuaJIT)
CMake 3.10+ (for building)
Make (optional, for Unix-style builds)

Installation

Using CMake (Recommended for Windows)

# Clone the repository
git clone https://github.com/NathanTBeene/squish.git
cd squish

# Build
cmake -B build
cmake --build build

# Optional: Install system-wide
cmake --install build --prefix /usr/local

Using Make (Linux/macOS)

make
sudo make install  # Optional: Install to /usr/local/bin

Basic Usage

# Create a squishy file (see below)
lua squish

# Build with minification
lua squish --minify

# Build with uglification
lua squish --uglify

# Build with both
lua squish --minify --uglify

Squishy Files

A squishy file defines how to build your project. Create a file named squishy in your project directory.

Example Squishy

-- Define output file
Output "myapp.lua"

-- Add modules (will be available via require())
Module "mylib" "src/mylib.lua"
Module "utils" "src/utils.lua"

-- Add main script (executed after modules are loaded)
Main "src/main.lua"

-- Add resources (accessible via require_resource())
Resource "config" "config.json"

-- Set build options
Option "minify"
Option "uglify"

Squishy Commands

`Module "name" "path"`

Adds a Lua module to the output. Modules are loaded before scripts run.

Module "mymodule" "src/mymodule.lua"

`Main "script.lua"`

Adds a script to execute. Scripts run in order after all modules load.

Main "src/main.lua"

`Output "filename.lua"`

Sets the output filename. Default is squished.out.lua.

Output "myapp.lua"

`Option "name" [value]`

Enables an option. Value is optional (defaults to true).

Option "minify"
Option "minify-level" "full"
Option "uglify"

`Resource "name" "path"`

Embeds a file as a resource. Access with require_resource("name").

Resource "config" "config.json"
Resource "template" "template.html"

`AutoFetchURL "url"`

Experimental: Auto-fetch missing modules via HTTP. ? is replaced with the module path.

AutoFetchURL "https://raw.githubusercontent.com/user/repo/main/?.lua"

Options

Minification

Removes whitespace, comments, and optimizes code structure.

Option "minify"
Option "minify-level" "full"  -- none, basic, default, full, debug

Level	Description
`none`	No minification
`basic`	Remove comments and excess whitespace
`default`	Basic + optimize whitespace
`full`	Default + optimize locals and strings
`debug`	All optimizations except those that change line numbers

Uglification

Compresses keywords and optionally obfuscates identifiers.

Option "uglify"
Option "uglify-level" "full"  -- basic, full

Level	Description
`basic`	Compress Lua keywords only
`full`	Compress keywords + frequently used identifiers/strings

Gzip Compression

Compresses output using DEFLATE algorithm. Adds ~4KB decompression code.

Option "gzip"

Bytecode Compilation

Compiles output to Lua bytecode (experimental).

Option "compile"

Debug Mode

Preserves filenames and line numbers in error messages.

Option "debug"

Note: Use Option "minify-level" "debug" with debug mode to avoid line number mismatches.

Virtual I/O

Makes embedded resources accessible through standard Lua I/O functions (io.open, dofile, loadfile).

Option "virtual-io"

Command Line Options

lua squish [directory] [options]

Options:
  --minify              Enable minification (opt-in)
  --minify-level=LEVEL  Set minification level
  --uglify              Enable uglification (opt-in)
  --uglify-level=LEVEL  Set uglification level
  --gzip                Enable gzip compression
  --compile             Compile to bytecode
  --debug               Enable debug mode
  --virtual-io          Enable virtual I/O

Examples

Simple Application

-- squishy
Module "math_utils" "lib/math_utils.lua"
Main "app.lua"
Output "myapp.lua"

Optimized Distribution

-- squishy
Module "core" "src/core.lua"
Module "ui" "src/ui.lua"
Main "main.lua"
Output "dist/app.lua"

Option "minify-level" "full"
Option "uglify-level" "full"

Library with Resources

-- squishy
Module "mylib" "src/mylib.lua"
Resource "schema" "schema.json"
Resource "template" "template.html"
Output "mylib_bundle.lua"

Option "minify"
Option "virtual-io"

Utility: make_squishy

Automatically generates a squishy file by scanning for require() calls:

lua make_squishy src/*.lua > squishy.new

Edit squishy.new as needed, then rename to squishy.

Building Squish Modules

Squish includes pre-configured builds for its own modules:

# Build gzip decompressor
lua squish gzip  # Creates gunzip.lua

# Build debug module
lua squish debug  # Creates squish.debug

Upgrading from 0.2.x

Breaking Changes

Lua 5.2+ Required — Lua 5.1 is no longer supported
Opt-in Features — Minify and uglify are now disabled by default
- Add Option "minify" or Option "uglify" to your squishy file
- Or use --minify / --uglify command line flags

Migration Guide

Update Lua to 5.2 or later
Add explicit Option "minify" and/or Option "uglify" to your squishy files
Rebuild your projects

License

Squish is licensed under the MIT License. See COPYRIGHT for details.

Component Licenses

Building Releases

For Maintainers: Automated scripts for building distribution packages

Squish includes build scripts in the release/ folder that automatically create distribution packages from dist.info.

Build Scripts

PowerShell (Windows):

cd release
.\build_release.ps1          # Build all variants
.\build_release.ps1 -Clean   # Clean and rebuild

Bash (Linux/macOS):

cd release
./build_release.sh           # Build all variants
./build_release.sh --clean   # Clean and rebuild

What Gets Built

The scripts automatically read version information from dist.info and create:

Lua Scripts:

squish-basic-vX.X.X.lua — Basic squish without features
squish-full-vX.X.X.lua — All features included
squish-minify-vX.X.X.lua — Minify support only
squish-uglify-vX.X.X.lua — Uglify support only
gunzip-vX.X.X.lua — Standalone gzip decompressor
squish-debug-vX.X.X.lua — Debug support module

Archives:

squish-lua-vX.X.X.zip/tar.gz — All Lua scripts
squish-complete-vX.X.X.zip/tar.gz — Scripts + documentation
SHA256SUMS.txt — Checksums for verification

All files are created in release/dist/ and are ready for GitHub release.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes following the guidelines
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Changelog

See CHANGES for version history.

Credits

Original Author: Matthew Wild
Maintainers: Peter Drahoš, aten.dev
Lua 5.2+ Port: aten.dev (2026)

Links

Made with ❤️ for the Lua community

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
cmake		cmake
compile		compile
debug		debug
gzip		gzip
minify		minify
release		release
test_project		test_project
uglify		uglify
vio		vio
.gitignore		.gitignore
CHANGES		CHANGES
CMakeLists.txt		CMakeLists.txt
COPYRIGHT		COPYRIGHT
Makefile		Makefile
README.md		README.md
README_OLD.md		README_OLD.md
dist.info		dist.info
make_squishy		make_squishy
squish.lua		squish.lua
squishy		squishy

NathanTBeene/squish

Folders and files

Latest commit

History

Repository files navigation