Skip to content

build.md

Latest commit

 

History

History
46 lines (32 loc) · 3.06 KB

build.md

File metadata and controls

46 lines (32 loc) · 3.06 KB

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. All additional build tools are managed automatically by go, and no manual tool installation is required.

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

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 Full build, test, and check 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 check all Run all quality checks Before committing
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.