Skip to content

Getting Started

Installation

There are two minimal ways to install Gloat:

One-Line Installer

make -f <(curl -sL gloathub.org/make) install

Clone and Setup

git clone https://github.com/gloathub/gloat
source gloat/.rc
gloat --help

For full installation instructions, options, and uninstall steps, see the Install page.

Basic Usage

Compile to Binary

By default, Gloat compiles to a native executable:

# Create ./app binary
gloat app.clj

# Specify output name
gloat app.clj -o myapp

# From YAMLScript source
gloat program.ys -o program

View Intermediate Formats

Output any stage of the compilation pipeline:

# View generated Clojure
gloat code.ys -t clj

# View generated Glojure
gloat code.ys -t glj

# View generated Go
gloat code.ys -t go

Save to Files

Use -o to save output to a file:

# File format inferred from extension
gloat app.ys -o app.clj    # Save as Clojure
gloat app.ys -o app.glj    # Save as Glojure
gloat app.ys -o app.go     # Save as Go

Or use the shorthand -t .ext syntax:

gloat app.ys -t .clj       # Creates app.clj
gloat app.ys -t .glj       # Creates app.glj
gloat app.ys -t .go        # Creates app.go

Output Formats

Gloat supports multiple output formats:

Format Flag Description
bin -t bin or no extension Native executable (default)
clj -t clj or .clj Clojure source
bb -t bb or .bb Babashka self-contained script
glj -t glj or .glj Glojure source
go -t go or .go Go source
dir -o path/ Portable Go project directory
lib .so or .dylib Shared library
wasm .wasm WebAssembly (WASI)
js -t js with .wasm WebAssembly (JavaScript, browser-ready with -Xhtml)

Directory Output

Create a self-contained Go project directory:

gloat app.ys -o build/

This generates:

build/
├── Makefile           # Makes-based build (auto-installs Go)
├── go.mod             # Go module definition
├── main.go            # Entry point
└── pkg/app/core/      # Glojure runtime code

Anyone can build it with just make - Go is automatically installed (within the build directory).

Cross-Compilation

Compile for different platforms using -p OS/ARCH:

# Linux targets
gloat app.ys -o app-linux --platform=linux/amd64
gloat app.ys -o app-arm --platform=linux/arm64

# macOS targets
gloat app.ys -o app-mac --platform=darwin/amd64
gloat app.ys -o app-mac-m1 --platform=darwin/arm64

# Windows targets
gloat app.ys -o app.exe --platform=windows/amd64

# WebAssembly
gloat app.ys -o app.wasm --platform=wasip1/wasm    # WASI
gloat app.ys -o app.wasm --platform=js/wasm        # JavaScript

Supported Platforms

OS Architectures
linux amd64, arm64, 386, arm
darwin amd64, arm64
windows amd64, arm64, 386
freebsd amd64, arm64, 386
openbsd amd64, arm64
netbsd amd64, arm64
wasip1 wasm
js wasm

Run gloat --platforms to see all supported targets.

Compile and Run

Use --run to compile to a temporary binary and execute it:

# Compile and run (no binary kept)
gloat --run app.ys

# Pass arguments to the program
gloat --run app.ys -- arg1 arg2

WebAssembly Output

Create Wasm modules for browser or WASI environments:

# WASI target (default for .wasm)
gloat app.ys -o app.wasm

# JavaScript target (for browsers)
gloat app.ys -o app.wasm -t js

# JavaScript target with HTML page for browser
gloat app.ys -o app.js -Xhtml
gloat app.ys -o app.js -Xhtml='arg1 arg2'

Adding -Xhtml generates app.html alongside the WASM file. The HTML page has the Go WASM runtime inlined and is ready to serve. Use python3 -m http.server (gloat will print the command) since fetch() requires HTTP, not file://.

Shared Libraries

Compile to shared libraries for FFI integration:

# Linux
gloat lib.clj -o libmylib.so

# macOS
gloat lib.clj -o libmylib.dylib

# Windows
gloat lib.clj -o mylib.dll

This generates both the library file and a .h header file for C bindings.

Check out the FFI bindings examples for over 20 languages.

These are all working code and bind to an example shared library written in YAMLScript and compiled with Gloat. You can run them all with make test-so-bindings. Every programming language that is needed is auto-installed by the Makes system.

The Gloat Shell

All Gloat dependencies are only accessible to Makefile rules, not your normal shell. To run commands like go, glj, ys, or bb directly:

gloat --shell

This starts a subshell with all tools in your PATH. Your prompt will change to indicate you're in the Gloat subshell. Press Ctrl-D or type exit to return to your normal shell.

Command-Line Options

-t, --to ...     Output format (inferred from -o; see --formats)
-o, --out ...    Output file or directory

--platform ...   Cross-compile (e.g., linux/amd64; see --platforms)
-X, --ext ...    Enable a processing extension (see --extensions)

--ns ...         Override namespace
--module ...     Go module name (e.g., github.com/user/project)

--formats        List available output formats
--extensions     List available processing extensions
--platforms      List available cross-compilation platforms
--complete ...   Generate shell completion script (bash, zsh, fish)
--shell          Start a sub-shell with gloat tools on PATH

-r, --run        Compile and run (pass program args after --)
-f, --force      Overwrite existing output files
-v, --verbose    Print timing for each compilation step
-q, --quiet      Suppress progress messages

-h, --help       Show this help
--version        Show version

Next Steps