Skip to content

build.md

Latest commit

 

History

History
52 lines (36 loc) · 3.71 KB

build.md

File metadata and controls

52 lines (36 loc) · 3.71 KB
Raw

Build Reference

All code in this repo is written in golang. The golang package is required to build and run the tools.

The build system uses mage, which can be installed with go install github.com/magefile/mage@latest. Alternatively, a zero-install approach is available through go run magefile.go or ./magefile.go, which automatically downloads the required dependencies without manual installation. Go build tools are managed automatically by go.

All core tooling dependencies are handled by go tool, which will automatically get the required tools when using mage. See the tools section for more information.

Optional Python lint tools are pinned in requirements-lint.txt. Before using a Mage target that runs Python checks, follow the virtual environment setup in Getting Started so that ruff and pyright are on your PATH.

This repo contains configs for the golangci-lint linter. It is installed as part of the VSCode go extension. It's also optionally available as a binary release.

Mage Commands

Command Description When to Use
mage -l List all available targets To see all options
mage all Build, test, default checks, and scenario pipeline Before submitting PR
mage build Build Go binaries After code changes
mage install Build Go binaries and install Outer-loop testing
mage unit Run unit tests After writing tests
mage scenario Run scenario tests (SLOW) For major changes
mage scenarioUpdate Update test snapshots When test expectations change
mage mutation <path> Run mutation testing on a package; writes out/mutation-report.json To assess test quality of a package
mage mutationDiff <ref> Run mutation testing on lines changed vs a git ref To check test quality of a branch's changes
mage check default Run default Go checks (lint, static analysis, license) Before committing
mage check all Run all quality checks, including Python Before committing or after Python changes
mage fix all Auto-fix code issues When linting fails
mage generate Run go generate ./... (mockgen, stringer, etc.) Seldom needed directly; runs automatically with build/test
mage docs Build binary + regenerate CLI docs and JSON schema After changing config structs or CLI commands

Note: Dependencies run automatically in correct order (i.e. mage build and mage unit automatically run code generation as needed).

Code Generation

The project uses automatic code generation including:

  • go:generate directives
  • Stringer for enums
  • Schema generation
  • Mocks generated by mockgen

There are two generation stages:

  1. mage generate — runs go generate ./... for all packages (mockgen, stringer, etc.). This is a prerequisite for building and runs automatically with mage build and mage unit.
  2. mage docs — builds the binary, then regenerates CLI docs (docs/user/reference/cli/) and JSON schema (schemas/azldev.schema.json). Run this after changing config structs (schema) or Cobra command descriptions (CLI docs).

You typically don't need to run mage generate manually; mage build runs it automatically. Run mage docs explicitly when you want to update the schema or CLI docs without running the full scenario test suite.

See tools documentation for more details on how to use tools with go tool in go:generate directives.