Logos / Docs

Building Binaries

Logos can compile your scripts into standalone executables. This allows you to distribute your applications without requiring users to have Logos installed.

The Build Command

Use lgs build to compile a Logos script into a binary:

lgs build script.lgs

This creates an executable named script (matching your script name without the .lgs extension) in the current directory.

How It Works

When you run lgs build, Logos:

  1. Parses and validates your Logos code
  2. Creates a temporary build directory
  3. Generates a Go main.go that embeds your script
  4. Copies the standard library into the build
  5. Resolves and includes any user modules your script imports
  6. Compiles everything using go build
  7. Produces a standalone executable

The resulting binary contains everything needed to run your script, including the Logos interpreter, your script source, the standard library, and any user modules.

User Modules

If your script imports custom modules using use "modulename", the build process automatically finds and bundles them. Modules should be in the same directory as your main script:

// myapp.lgs
use "utils"
use "helpers"

// Your code here
print(helperFunction())
// utils.lgs (in same directory)
let utilFunction = fn() {
    return "utility"
}

Standard library modules (array, log, math, path, string, testing, time, type) are always included automatically.

Requirements

Building requires Go to be installed on your system, since the build process uses go build under the hood.

# Check if Go is installed
go version

# If not, install Go first
# See: https://go.dev/doc/install

Example Workflow

Here's a typical workflow for building and distributing a Logos application:

# Write your script
print("Hello from Logos!")

# Save as myapp.lgs, then test it
lgs myapp.lgs

# Build to binary
lgs build myapp.lgs

# Run the binary
./myapp

Shebang Support

Logos scripts can include a shebang line for direct execution. The shebang is automatically stripped during both interpretation and building:

#!/usr/bin/env lgs

print("This script can be run directly!")
print("Or built into a binary.")
# Make executable and run directly
chmod +x myscript.lgs
./myscript.lgs

# Or build it
lgs build myscript.lgs
./myscript

Build Output

On a successful build, you'll see:

Built: myapp

The binary is created in your current working directory.

Troubleshooting

Build fails with parse errors

The build validates your script before compiling. Fix any syntax errors shown in the output:

lgs build broken.lgs
# Output shows: parse error: unexpected token...

Build fails with "module not found"

Ensure all imported modules exist in the same directory as your main script. The build process looks for modulename.lgs relative to the script location.

Build fails with Go errors

Make sure Go is properly installed and go build works:

# Verify Go installation
go version

# Check Go environment
go env GOROOT GOPATH

Cannot find std directory

The build process needs access to the Logos standard library. This is typically found relative to the lgs binary or in the current working directory.