Skip to main content

atmos plugin build

Compile a Go plugin for one or more platforms into the executable paths declared in plugin.yaml.
Experimental
atmos plugin build --help

Usage​

atmos plugin build [directory] [--platform <os/architecture[/variant]> | --all-platforms]

The command validates the manifest and extension metadata, then runs go build in the plugin's source directory. It uses the installed Go toolchain and its normal module and workspace configuration. The command explicitly sets the target operating system, architecture, and CPU variant, and disables CGO for portable binaries. Inherited GOOS, GOARCH, or architecture tuning settings do not change the selected target. For a fresh standalone module without go.sum, it first runs go mod tidy to prepare dependency metadata. Existing module metadata and Go workspaces use the normal build behavior. An interactive terminal shows compilation in the same four-line output viewport used by atmos build. Redirected output uses compiler diagnostics without terminal controls. For all-platform builds, diagnostics are buffered per target and displayed in platform order after compilation.

Everything build prints is UI output on stderr: the progress line, compiler diagnostics, and the final Plugin built successfully message with the executable path. Standard output stays empty, so the command never mixes into a pipeline. By default it builds for the platform of the running Atmos process, selecting the best compatible entry in spec.platforms. A manifest without platform declarations uses spec.runtime.executable; declared but incompatible platforms fail. Use --platform to select a declared target or --all-platforms to build every declared target with up to four compilers running concurrently. Returned paths stay in sorted order; no workflow matrix or parallel-step configuration is needed. Every target must have a distinct executable path. Paths cannot overlap or contain symlinks. Target syntax, declarations, and output paths are checked before compilation starts; the installed Go toolchain determines which OS/architecture pairs it can build.

Each successful build atomically replaces its executable and reports its path. A failure or cancellation preserves the previous binary for the affected target. Independent targets continue after a compiler failure, and the command reports failures after they finish. Cancellation stops running compilers and prevents queued targets from starting. Successful targets remain updated and are reported. Cross-compiled binaries are never executed.

Building requires Go on PATH. Consumers install precompiled OCI releases and do not need Go. The command does not install, publish, or run the plugin, and it runs no plugin code. For that reason build is not a plugin policy operation: on: plugin rules never evaluate it, so a policy that denies development plugins does not stop authors from compiling.

Examples​

atmos plugin create ./corporate-oidc --defaults
atmos plugin build ./corporate-oidc
atmos plugin test ./corporate-oidc

Inside the generated directory:

atmos plugin build

Build a specific declared architecture or ARM variant:

atmos plugin build ./corporate-oidc --platform linux/arm64
atmos plugin build ./corporate-oidc --platform linux/arm/v7

Build all platforms declared in spec.platforms, then pack the release into one OCI index:

atmos plugin build ./corporate-oidc --all-platforms
atmos plugin pack ./corporate-oidc --output ./corporate-oidc-release

Declare each target's output path in plugin.yaml, for example:

spec:
  runtime:
    type: native
    protocol: 1
    executable: bin/plugin.exe
  platforms:
    linux/amd64:
      executable: bin/linux-amd64/plugin
    linux/arm64:
      executable: bin/linux-arm64/plugin
    linux/arm/v7:
      executable: bin/linux-arm-v7/plugin
    windows/arm64:
      executable: bin/windows-arm64/plugin.exe

The common spec.runtime.executable is the installed path inside every platform payload. Use a .exe suffix when shipping Windows; the same filename works on Linux and macOS.

Supported CPU variants are amd64/v1 through v4, arm/v5 through v7, and arm64/v8, v8.0–v8.9, v9, and v9.0–v9.5. Unqualified targets use baseline amd64/v1, arm/v5, or arm64/v8.0. ARM builds use software floating point. Explicit variants set the corresponding Go compiler tuning; extra feature suffixes such as ,lse are not platform identifiers. A newer CPU can use compatible lower variants, but Atmos conservatively selects using its own recorded build requirements rather than probing for additional CPU features. See installation for selection and shared-lock behavior.

For plugins requiring CGO or a custom toolchain, use Go directly and write each platform's binary to its declared manifest path before packing.

Arguments​

directory
Go plugin source directory containing plugin.yaml and go.mod. Defaults to the current directory.

Flags​

--platform
Build one target declared in spec.platforms, using os/architecture or os/architecture/variant, such as linux/arm64 or linux/arm/v7. Defaults to the running Atmos process's platform. Cannot be combined with an enabled --all-platforms. Environment variable: ATMOS_PLUGIN_BUILD_PLATFORM.
--all-platforms
Build every target declared in spec.platforms. Requires at least one declared platform and cannot be combined with a nonempty --platform. Environment variable: ATMOS_PLUGIN_BUILD_ALL_PLATFORMS. An explicit --all-platforms=false overrides the environment setting.