Target Configuration

Overview

A target is the fundamental unit of work in Grog. It defines:

• What command to run (command)
• Which files to track for changes (inputs)
• What artifacts it produces (outputs)
• Which other targets it depends on (dependencies)
• Optional metadata like platform constraints and tags

Grog uses this information to ensure incremental, cached, and parallel builds.

Fields Reference

Field	Type	Description
name	string	Unique identifier for the target within its package
command	string	Shell command or script to execute in the target’s package directory
inputs	string[]	File paths or glob patterns that, when changed, will trigger a rebuild
exclude_inputs	string[]	File paths or glob patterns to exclude from inputs
outputs	string[]	Files or directories produced by the target
dependencies	label[]	Labels of other targets that must be built before this one
platform	PlatformConfig	OS and architecture constraints for where this target can run
tags	string[]	Metadata tags that affect target behavior (e.g., “no-cache”)
bin_output	Output	Specifically identifies a binary output from the target

Note

Targets with names ending in test are automatically treated as test targets. They will be executed with grog test but not with grog build unless explicitly requested.

Field Details

name

A unique identifier for the target within its package. This forms part of the target’s label.

command

The shell command or script to execute. This can be a single line or a multi-line script using YAML’s | syntax or equivalent in other formats. The command is optional which can be useful, for instance, when defining executable scripts (read more).

Grog also injects the following environment variables into the target’s environment:

Variable Name	Description
GROG_TARGET	The full label of the target. E.g. //path/to/package:target_name)
GROG_OS	The grog binary’s target operating system. E.g. linux.
GROG_ARCH	The grog binary’s target architecture. E.g. amd64.
GROG_PLATFORM	The grog binary’s target platform. E.g. linux/amd64.
GROG_PACKAGE	The path to the package directory. E.g. path/to/package.
GROG_GIT_HASH	The output of git rev-parse HEAD. Useful for tagging artifacts.

inputs

A list of files or glob patterns that Grog monitors for changes. When any input file changes, the target will be rebuilt.

Common glob patterns:

• src/**/*.js - All JavaScript files in the src directory and its subdirectories
• *.{png,jpg} - All PNG and JPG files in the current directory
• go.mod - A specific file

Caution

If your input glob matches some of your output files, Grog will always re-build the target. Therefore, it is important to declare all outputs (Grog will warn if there is an overlap) and to avoid using globs that match your output files.

exclude_inputs

A list of files or glob patterns to exclude from the resolved inputs. This is useful when you want to include a broad pattern in inputs but exclude specific files or subdirectories.

Examples:

• If inputs includes src/**/*.js but you want to exclude test files, you can add src/**/*.test.js to exclude_inputs
• If inputs includes all files in a directory but you want to exclude specific files, you can list them in exclude_inputs

Note

The exclusion happens after all input patterns are resolved, so you can exclude specific files that were matched by glob patterns.

outputs

Files or directories produced by the target. For directories, use the dir:: prefix. For Docker images, use the docker:: prefix.

Examples:

• dist/bundle.js - A file output
• dir::dist/assets/ - A directory output
• docker::myregistry.com/myimage:tag - A Docker image

dependencies

Other targets that must be built before this one, specified as labels. Labels can reference:

• Targets in the same package: :target_name
• Targets in other packages: //path/to/package:target_name

platform

A platform configuration that restricts where this target can be executed. This is particularly useful for multi-platform builds (see docs).

The platform field has two sub-fields:

• os: List of operating systems where this target can run (e.g., “linux”, “darwin”)
• arch: List of CPU architectures where this target can run (e.g., “amd64”, “arm64”)

When a target has platform constraints defined:

1. Grog checks the current host’s OS and architecture
2. Targets that don’t match the current platform are skipped

tags

Tags is a list of unique strings that can be used to group and query targets. There are a few reserved tags that alter the way grog treats a target:

Tag Name	Effect
no-cache	Outputs will neither be stored in nor loaded from the cache backend.
multiplatform-cache	By default grog separates target caches by the host platform. Adding this tag causes grog to store the outputs at the same cache key across platforms