Grog Scripts

What are Grog Scripts?

Grog Scripts are a nicer way of defining binary script targets, that is, targets whose output you can run with grog run. In short; you add a comment header to your script that defines its dependencies and inputs, and Grog automatically builds them before running the script.

How to use Grog Scripts

In short:

1. Store scripts directly in your repository with names ending in .grog.sh or .grog.py.
2. Add a # @grog metadata block at the top of the file to describe dependencies, inputs, and outputs just like with annotated Makefile targets.
3. Run them anywhere in the workspace with grog run path/to/script.grog.sh (or the Python equivalent) while passing through arguments with --.

Let’s go through a brief example. Suppose you have a script scripts/format.sh that depends on some build target like //tools:install_prettier:

#!/usr/bin/env bash
# @grog
# name: format
# dependencies:
#   - //tools:install_prettier
set -euo pipefail

# Format JavaScript and TypeScript files
prettier --write "src/**/*.{js,ts}" "$@"

By adding this metadata block, Grog will treat this script as a Grog target and the actual script file as its binary output. Then, you can simply run the script anywhere in the workspace:

# Run the script using the file name
grog run scripts/format.grog.sh -- --check
# Run the script using the target label
grog run //scripts:format -- --check

Configuration

Grog scans your workspace for executable files that match the naming convention *.grog.sh or *.grog.py and treats each match as a runnable target.

Note

Files that do not follow the .grog.sh/.grog.py naming convention will not be discovered automatically, but can still be run with grog run path/to/script as long as they include a # @grog metadata block.

You can run a script from any directory with either a relative or absolute path using grog run. Grog will:

1. Build the script target including its dependencies.
2. Execute the file using sh (.py files need a shebang to specify the interpreter).

By default, Grog prepends set -eu before invoking your script to fail fast on unset variables and errors. Set the disable_default_shell_flags configuration option (or pass --disable-default-shell-flags) to opt out when needed.

Use -- to forward additional parameters to the script.

Comparison to binary output targets

Before this feature you would have to define a wrapper target that defines the existing script file as an executable target with a bin_output like so:

amends "package://grog.build/releases/v0.16.1/grog@0.16.1#/package.pkl"

targets {
  new {
    name = "your_script"
    bin_output = "script_file.sh"
    tags {
      "no-cache"
    }
  }
}

While this is less convenient and arguably a bit awkward, since there is no actual build step, it can still be useful in case you want to keep your build configuration separater from your scripts.