Skip to content
⍼ Angzarr
Angzarr Blog

just Overlays

Platform-specific justfiles enable cross-platform development while keeping tasks consistent.

The Pattern

Section titled “The Pattern”

The root justfile imports platform-specific overlays:

# justfile (root)
import? 'justfile.linux'
import? 'justfile.darwin'
import? 'justfile.windows'
import? 'justfile.container'

The ? makes imports optional—missing files don’t cause errors.

Overlay Hierarchy

Section titled “Overlay Hierarchy”
project/
├── justfile              # Cross-platform recipes
├── justfile.linux        # Linux-specific overrides
├── justfile.darwin       # macOS-specific overrides
├── justfile.windows      # Windows-specific overrides
└── justfile.container    # Container environment overrides

How Overlays Work

Section titled “How Overlays Work”

Base Recipe

Section titled “Base Recipe”
# justfile
build:
    cargo build --release

Platform Override

Section titled “Platform Override”
justfile.linux
build:
    cargo build --release --target x86_64-unknown-linux-musl

When running on Linux, just build uses the overlay definition. On other platforms, it falls back to the base recipe.

Container Overlay

Section titled “Container Overlay”

For containerized builds where the same command should work on host and inside containers, see the Container Overlay Pattern. This technique mounts a container-specific build file over the host file, eliminating conditionals entirely.

Common Patterns

Section titled “Common Patterns”

Tool Availability

Section titled “Tool Availability”
justfile.darwin
brew-deps:
    brew install just skaffold helm kubectl


# justfile.linux
apt-deps:
    sudo apt-get install -y just
    # Manual install for others...

Path Differences

Section titled “Path Differences”
justfile.linux
socket := "/run/podman/podman.sock"


# justfile.darwin
socket := "~/.colima/default/docker.sock"

Binary Names

Section titled “Binary Names”
justfile.linux
container-runtime := "podman"


# justfile.darwin
container-runtime := "docker"

Example: Angzarr

Section titled “Example: Angzarr”

Angzarr uses overlays for devcontainer detection and cross-language formatting:

# justfile (base) - runs formatters in containers
_lang-container LANG +ARGS:
    #!/usr/bin/env bash
    if [ "${DEVCONTAINER:-}" = "true" ]; then
        {{ARGS}}
    else
        podman run --rm -v "{{TOP}}:/workspace:Z" -w /workspace \
            ghcr.io/angzarr-io/angzarr-{{LANG}}:latest {{ARGS}}
    fi


fmt-python:
    just _lang-container python black examples/python client/python


fmt-csharp:
    just _lang-container csharp csharpier format examples/csharp client/csharp

The DEVCONTAINER environment variable (set inside devcontainers) triggers direct execution, avoiding nested containers. On host, formatters run inside language-specific CI images with the workspace mounted.

See Container Overlay Pattern for the full technique.

Best Practices

Section titled “Best Practices”
  1. Keep base portable — Base justfile should work on most platforms
  2. Override only what differs — Don’t duplicate recipes unnecessarily
  3. Document requirements — Note platform-specific tool dependencies
  4. Test overlays — CI should test all supported platforms

Next Steps

Section titled “Next Steps”