Dalec Package Builder

Expert guidance for working with Dalec, a Docker BuildKit frontend for building system packages (RPM, DEB) and containers from declarative YAML specifications. Supports multiple Linux distributions and Windows containers.

Core Principles

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Bootstrap and Basic Development

Dependency Management

Download Go dependencies: `go mod download` (takes ~5 seconds)

Testing and Validation

Run unit tests: `go test --test.short --timeout=10m ./...` (takes ~52 seconds)

- NEVER CANCEL this command

- Set timeout to 15+ minutes minimum

Generate source files: `go generate` (takes ~1 second)

Run custom linters: `go run ./cmd/lint ./...` (takes ~3 seconds)

Validate generated files are up to date: `git diff --exit-code` after running `go generate`

Building CLI Tools

Build frontend binary: `go build -o /tmp/frontend ./cmd/frontend` (takes ~1 second)

Build dalec-redirectio: `go build -o /tmp/dalec-redirectio ./cmd/dalec-redirectio` (takes ~1 second)

Generate JSON schema: `go run ./cmd/gen-jsonschema` (takes ~0.2 seconds)

All other CLI tools in `cmd/` can be built with `go build` or run with `go run`

Docker Frontend Build System

**CRITICAL**: Docker builds may fail in some environments due to TLS certificate issues with proxy.golang.org. This is an environmental limitation, not a code issue.

Build frontend image: `docker buildx bake frontend` (takes 2-5 minutes when working)

- NEVER CANCEL this command

- Set timeout to 15+ minutes minimum

**Alternative when Docker builds fail**: Use host-compiled binaries for development and testing

The frontend requires Docker BuildKit with buildx support

Integration Testing

Run specific distro tests: `go test -timeout=59m -v ./test -run=TestMariner2` (takes 30+ minutes)

- NEVER CANCEL this command

- Set timeout to 75+ minutes minimum

Run all integration tests: `go test -timeout=59m -v ./test` (takes 45+ minutes)

- NEVER CANCEL this command

- Set timeout to 75+ minutes minimum

Tests require Docker and BuildKit to be working properly

Tests cover multiple Linux distributions: Mariner2, Azlinux3, Jammy, Noble, Bullseye, Bookworm, etc.

Pre-Commit Validation

Always run these commands before committing:

1. `go test --test.short ./...` - validates unit tests pass

2. `go run ./cmd/lint ./...` - validates custom linting rules

3. `go generate && git diff --exit-code` - validates generated files are up to date

4. Consider running integration tests for your target distribution if making significant changes

Manual Validation Scenarios

CLI Tool Testing

Build and run: `go build -o /tmp/frontend ./cmd/frontend` then test with `--help` flag

Schema Generation

Run `go run ./cmd/gen-jsonschema` and verify JSON schema output is valid

Example Spec Validation

Use `docs/examples/go-md2man.yml` as a test case for spec validation

Docker Build Validation (When Working)

Build example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3/rpm --output=_output .`

Container example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3 .`

Repository Structure

```

├── cmd/ # CLI tools and binaries

│ ├── frontend/ # Main BuildKit frontend

│ ├── gen-jsonschema/ # JSON schema generator

│ ├── lint/ # Custom linters

│ └── ... # Other tools

├── docs/examples/ # Example Dalec specs

├── test/ # Integration tests

├── targets/ # Target-specific implementations

├── website/ # Documentation (Docusaurus)

├── docker-bake.hcl # Docker Buildx configuration

├── Dockerfile # Frontend container definition

└── go.mod # Go module definition

```

Key Files and Directories

Files to Monitor

Always regenerate files after modifying source variants: `go generate ./...`

Always run linting after changes: `go run ./cmd/lint ./...`

Check `docker-bake.hcl` for Docker build targets and configurations

Check `docs/examples/go-md2man.yml` for canonical example of Dalec spec format

Important Directories

`cmd/` - All CLI tools and main binaries

`test/` - Comprehensive integration test suite

`targets/` - Platform-specific build logic (Linux RPM/DEB, Windows)

`frontend/` - Core BuildKit frontend implementation

`website/docs/` - User documentation and examples

Development Environment Requirements

Required Tools

Go 1.25+ (check with `go version`)

Docker with BuildKit support (check with `docker buildx version`)

Standard Unix tools (git, make, etc.)

Optional but Recommended

Node.js 18+ for documentation site (`cd website && npm start`)

golangci-lint for additional linting (custom linter is used in addition to golangci-lint)

Environment Limitations

Docker builds require internet access

Integration tests require full Docker functionality

Host-based Go builds always work and are sufficient for most development

Time Expectations

Unit tests: ~1 minute

Custom linting: ~3 seconds

Code generation: ~1 second

Frontend binary build: ~1 second

Docker frontend build: 2-5 minutes (when working)

Integration test suite: 45+ minutes for full suite, 30+ minutes for single distro

Critical Reminders

**NEVER CANCEL long-running commands.** Build and test operations can legitimately take 30-60+ minutes. Always set appropriate timeouts:

Unit tests: 15+ minutes

Docker builds: 15+ minutes

Integration tests: 75+ minutes

Common Workflows

Making Code Changes

1. Make your changes to source files

2. Run `go generate` if you modified source variants

3. Run `go run ./cmd/lint ./...` to validate

4. Run `go test --test.short ./...` to test

5. Run `git diff --exit-code` to ensure generated files are up to date

6. Commit changes

Adding New Features

1. Update relevant code in `cmd/`, `frontend/`, or `targets/`

2. Add or update tests in `test/`

3. Update documentation in `website/docs/`

4. Run full validation suite before committing

5. Consider adding example specs in `docs/examples/`

Testing Distribution Support

1. Identify target distribution (e.g., Mariner2, Jammy, Bookworm)

2. Run specific integration test: `go test -timeout=59m -v ./test -run=Test<DistroName>`

3. Validate package builds correctly

4. Test container builds if applicable

Dalec Package Builder

Dalec Package Builder

Core Principles

Bootstrap and Basic Development

Dependency Management

Testing and Validation

Building CLI Tools

Docker Frontend Build System

Integration Testing

Pre-Commit Validation

Manual Validation Scenarios

CLI Tool Testing

Schema Generation

Example Spec Validation

Docker Build Validation (When Working)

Repository Structure

Key Files and Directories

Files to Monitor

Important Directories

Development Environment Requirements

Required Tools

Optional but Recommended

Environment Limitations

Time Expectations

Critical Reminders

Common Workflows

Making Code Changes

Adding New Features

Testing Distribution Support

Reviews (0)