GALA Dependency Management

GALA provides a dependency management system similar to Go modules, using gala.mod and gala.sum files to track dependencies and their checksums. The key difference from Go is that GALA projects only need gala.mod - no go.mod is required in your project folder.

Quick Start
File Formats
- gala.mod
- gala.sum
CLI Commands
Build System
- Without Bazel
- With Bazel
Cache Structure
Go Dependencies
GALA Library Dependencies
Bazel Integration
- MODULE.bazel (Bzlmod)
- BUILD Files
Version Constraints

1. Quick Start

Non-Bazel Projects (Recommended for simple projects)

Initialize and build a GALA project:

# Create a new project
mkdir myproject && cd myproject

# Initialize gala.mod
gala mod init github.com/user/myproject

# Add dependencies
gala mod add github.com/example/gala-utils@v1.2.3
gala mod add github.com/google/uuid@v1.6.0 --go

# Create your GALA source file
cat > main.gala <<'EOF'
package main

import "github.com/google/uuid"

func main() {
    Println("Hello from GALA!")
    Println(s"UUID: ${uuid.New().String()}")
}
EOF

# Build and run
gala build
./myproject

Your project structure (no go.mod needed!):

myproject/
  gala.mod          # Module manifest
  gala.sum          # Dependency checksums
  main.gala         # Your GALA code
  myproject.exe     # Built binary (after gala build)

Bazel Projects

For Bazel projects, gala mod tidy generates the necessary go.mod and go.sum files:

# Initialize
gala mod init github.com/user/myproject

# Add dependencies
gala mod add github.com/example/gala-utils@v1.2.3
gala mod add github.com/google/uuid@v1.6.0 --go

# Sync dependencies (generates go.mod and go.sum for Bazel)
gala mod tidy

# Build with Bazel
bazel build //:myapp

2. File Formats

gala.mod

The gala.mod file declares your module’s path, GALA version, and dependencies.

module github.com/user/myproject

gala 1.0

require (
    github.com/example/utils v1.2.3
    github.com/example/math  v2.0.0
    github.com/google/uuid   v1.6.0 // go
)

require (
    github.com/example/indirect v1.0.0 // indirect
)

replace github.com/example/utils => ../local-utils

exclude github.com/example/deprecated v0.9.0

Directives

Directive	Description
`module`	Declares the module path
`gala`	Minimum GALA version required
`require`	Declares a dependency
`replace`	Substitutes a module with another (local or remote)
`exclude`	Prevents a specific version from being used

Comments

Comment	Meaning
`// indirect`	Transitive dependency (not directly imported)
`// go`	Go package (not GALA) - will not be transpiled

gala.sum

The gala.sum file contains cryptographic checksums for each dependency to ensure integrity.

github.com/example/utils v1.2.3 h1:abc123def456...
github.com/example/utils v1.2.3/gala.mod h1:xyz789...
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=

Each line contains:

Module path
Version
Optional file suffix (e.g., /gala.mod)
Hash prefix (h1:) and SHA-256 hash

3. CLI Commands

gala build

Build a GALA project to a binary.

# Build with default output name (project directory name)
gala build

# Build with custom output name
gala build -o myapp

# Build with verbose output
gala build -v

What happens:

Transpiles .gala files to Go in a workspace at ~/.gala/build/<hash>/
Downloads Go dependencies to ~/.gala/go/pkg/mod/
Runs go build to produce the binary in your project directory

Auto-fetch: gala build automatically downloads GALA dependencies listed in gala.mod that are not yet cached locally. No manual gala mod download step is needed.

gala run

Build and run a GALA project.

# Build and run
gala run

# Pass arguments to the program
gala run -- arg1 arg2

# Verbose mode
gala run -v

gala clean

Clean build artifacts.

# Clean the workspace for this project
gala clean

# Clean all GALA caches
gala clean --all

# Clean stale workspaces (projects that no longer exist)
gala clean --stale

gala mod init

Initialize a new gala.mod file.

# Auto-detect module path from go.mod or directory name
gala mod init

# Explicit module path
gala mod init github.com/user/project

Creates:

gala.mod with module declaration
Empty gala.sum file

gala mod add

Add a dependency to your module.

# Add latest version
gala mod add github.com/example/utils

# Add specific version
gala mod add github.com/example/utils@v1.2.3

# Add compatible version (caret constraint)
gala mod add github.com/example/utils@^1.0.0

# Add Go dependency (not GALA)
gala mod add github.com/google/uuid@v1.6.0 --go

The command will:

Fetch the module from Git
Cache it locally
Update gala.mod with the dependency
Update gala.sum with checksums

gala mod remove

Remove a dependency from your module.

gala mod remove github.com/example/utils

gala mod update

Update dependencies to their latest versions.

# Update all dependencies
gala mod update

# Update specific dependency
gala mod update github.com/example/utils

# Update to specific version
gala mod update github.com/example/utils@v2.0.0

gala mod tidy

Synchronize gala.mod with your source code imports.

gala mod tidy

This command:

Adds missing dependencies found in imports
Removes unused dependencies
Marks indirect dependencies appropriately
For Bazel projects: Generates go.mod and go.sum with Go dependencies

gala mod tidy handles both single-line and multi-line import blocks, and recognizes known GALA dependencies (like std, collection_immutable, etc.) automatically.

gala mod graph

Print the dependency tree.

gala mod graph

Output:

github.com/user/myproject
├── github.com/example/utils@v1.2.3
│   └── github.com/example/common@v1.0.0
└── github.com/example/math@v2.0.0

gala mod verify

Verify that dependencies match their checksums in gala.sum.

gala mod verify

4. Build System

GALA supports two build modes: standalone (without Bazel) and Bazel-based.

Without Bazel

When you run gala build, GALA:

Creates a build workspace at ~/.gala/build/<hash>/ (hash is derived from your project path)
Extracts the stdlib to ~/.gala/stdlib/v<version>/
Transpiles GALA dependencies — any GALA library in gala.mod (not marked // go) is transpiled from .gala source in the module cache to .gen.go files in ~/.gala/build/<hash>/deps/
Transpiles your .gala files to .gen.go files in ~/.gala/build/<hash>/gen/
Generates a go.mod in the workspace with absolute paths to dependencies
Downloads Go dependencies to ~/.gala/go/pkg/mod/
Runs go build to create the binary

Key benefits:

Your project folder stays clean (no go.mod, no _gala folder, no .gen.go files)
Dependencies are cached globally
GALA library dependencies are automatically transpiled — no pre-compiled .go files needed in the module cache
No symlinks used (works on all platforms including Windows)

With Bazel

For Bazel projects:

Run gala mod tidy to generate go.mod and go.sum (Go dependencies only)
GALA dependencies are handled by the bzlmod extension
Build with bazel build //:target

5. Cache Structure

All GALA caches are stored in ~/.gala/:

~/.gala/
  build/                              # Build workspaces (per-project)
    <hash>/                           # Workspace for a specific project
      gen/                            # Transpiled .gen.go files from your project
      deps/                           # Transpiled GALA library dependencies
        github.com/user/lib@v1.0.0/   # Each dep gets its own directory
          math.gen.go                 # Transpiled Go output
          go.mod                      # Generated go.mod for the dep
      go.mod                          # Generated go.mod with absolute paths
      go.sum                          # Generated go.sum

  stdlib/                             # Stdlib versions
    vdev/                             # Development version
      std/                            # Standard library packages
      go_interop/
      collection_immutable/
      collection_mutable/
      concurrent/

  pkg/mod/                            # GALA package cache (source)
    github.com/example/utils@v1.2.3/  # Cached GALA modules (.gala source)

  go/pkg/mod/                         # Go package cache (GOMODCACHE)
    github.com/google/uuid@v1.6.0/    # Cached Go modules

Directory	Purpose
`build/<hash>/gen/`	Transpiled `.gen.go` files from your project
`build/<hash>/deps/`	Transpiled GALA library dependencies
`stdlib/v<version>/`	GALA standard library
`pkg/mod/`	GALA module cache (`.gala` source files)
`go/pkg/mod/`	Go module cache

6. Go Dependencies

GALA can depend on Go packages. Mark Go dependencies with // go or use the --go flag:

gala mod add github.com/google/uuid@v1.6.0 --go

In gala.mod:

require (
    github.com/google/uuid v1.6.0 // go
)

How it works:

Go dependencies are tracked in gala.mod but not transpiled
The transpiler generates correct Go imports for Go packages
For non-Bazel builds: gala build downloads them via go mod tidy
For Bazel builds: Gazelle’s go_deps extension fetches them

Usage in GALA code:

package main

import "github.com/google/uuid"

func GenerateID() string = uuid.New().String()

7. GALA Library Dependencies

GALA projects can depend on other GALA libraries — packages written in GALA and published as .gala source files.

How It Works

When you add a GALA dependency (without the --go flag), the source .gala files are fetched to ~/.gala/pkg/mod/. At build time, gala build automatically transpiles these dependencies to Go before compiling:

The builder scans gala.mod for GALA dependencies (entries without // go)
For each dep that contains .gala files, the transpiler pipeline runs (parse -> analyze -> transform -> generate)
Transpiled .gen.go files and a go.mod are written to ~/.gala/build/<hash>/deps/<module>@<version>/
The project’s go.mod uses replace directives pointing to the transpiled output
Transitive GALA dependencies are collected recursively and transpiled as well

Multi-File Packages

GALA library packages with multiple .gala files are fully supported. The transpiler uses NewGalaAnalyzerWithPackageFiles to enable cross-file type resolution within the dependency.

Transitive Dependencies

Dependencies of dependencies are handled automatically:

your-project
├── github.com/user/lib-a@v1.0.0       (GALA — transpiled)
│   └── github.com/user/lib-b@v2.0.0   (GALA — transpiled)
│       └── github.com/google/uuid      (Go — downloaded by go mod tidy)
└── github.com/other/lib@v1.0.0        (Go — downloaded by go mod tidy)

GALA deps at any depth are transpiled and their go.mod files are generated with correct replace directives
Go deps at any depth are collected and added to the project’s go.mod
Pure Go packages in gala.mod (no .gala files in cache) are skipped — they don’t need transpilation

Example

# Add a GALA library dependency
gala mod add github.com/martianoff/gala_demo_pkg@v0.2.3

# Build — the dep is transpiled automatically
gala build -v

Verbose output:

Found 1 GALA dependencies to transpile
  Transpiling dependency: github.com/martianoff/gala_demo_pkg@v0.2.3 (2 files)
    math.gala -> math.gen.go
    utils.gala -> utils.gen.go
Transpiling GALA files...
  main.gala -> main.gen.go

8. Bazel Integration

GALA provides Bazel rules for dependency management. Dependencies are declared in gala.mod and automatically loaded into Bazel.

MODULE.bazel (Bzlmod)

module(
    name = "myproject",
    version = "0.0.1",
)

# GALA toolchain
bazel_dep(name = "gala", version = "1.0.0")

# Go rules (required for Go dependencies)
bazel_dep(name = "rules_go", version = "0.50.1")
bazel_dep(name = "gazelle", version = "0.39.1")

# Go dependencies (auto-generated by 'gala mod tidy')
go_deps = use_extension("@gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//:go.mod")
use_repo(go_deps, "com_github_google_uuid")

# GALA dependencies
gala = use_extension("@gala//:extensions.bzl", "gala")
gala.from_file(gala_mod = "//:gala.mod")
use_repo(gala, "com_github_example_utils")

Important: Run gala mod tidy to generate go.mod and go.sum files that Bazel needs for Go dependencies.

BUILD Files

Reference dependencies in the standard deps attribute:

load("//:gala.bzl", "gala_library", "gala_binary")

gala_library(
    name = "mylib",
    src = "mylib.gala",
    importpath = "github.com/user/project/mylib",
    deps = ["@com_github_example_utils//:utils"],
)

gala_binary(
    name = "myapp",
    src = "main.gala",
    deps = ["@com_github_example_utils//:utils"],
)

Repository Naming Convention

Module paths are converted to Bazel repository names:

Module Path	Repository Name
`github.com/example/utils`	`@com_github_example_utils`
`gitlab.com/user/lib`	`@com_gitlab_user_lib`

9. Version Constraints

GALA supports several version constraint syntaxes:

Syntax	Meaning	Example
`v1.2.3`	Exact version	Exactly v1.2.3
`^1.2.3`	Compatible	>=1.2.3, <2.0.0
`~1.2.3`	Approximate	>=1.2.3, <1.3.0
`>=1.2.3`	Minimum	At least v1.2.3
`latest`	Latest stable	Most recent tagged version

Minimal Version Selection (MVS):

Like Go modules, GALA uses MVS for dependency resolution:

When multiple versions are required, the highest minimum is selected
This ensures reproducible builds

Best Practices

Commit both files: Always commit gala.mod and gala.sum to version control
Run verify in CI: Add gala mod verify to your CI pipeline
Use tidy regularly: Run gala mod tidy after changing imports
Pin versions: Use exact versions in production, constraints in libraries
Separate Go deps: Mark Go dependencies with // go for clarity
For Bazel: Also commit go.mod and go.sum (they’re auto-generated but needed by Bazel)

Example Projects

For complete working examples of GALA dependency management, see:

gala_demo_pkg_import - Non-Bazel project using gala build
gala_demo_pkg_import_bazel - Bazel project with bzlmod integration