Skip to content

Latest commit

 

History

History
204 lines (144 loc) · 10.1 KB

README.md

File metadata and controls

204 lines (144 loc) · 10.1 KB

These rules provide a simple interface for running multiple commands, optionally in parallel, with a single bazel run invocation. This is especially useful for running multiple linters or formatters with a single command.

command

command(name, data, arguments, command, description, environment)

A command is a wrapper rule for some other target that can be run like a command line tool. You can customize the command to run with specific arguments or environment variables you would like to be passed. Then you can compose multiple commands into a multirun rule to run them in a single bazel invocation, and in parallel if desired.

load("@rules_multirun//:defs.bzl", "multirun", "command")

sh_binary(
    name = "some_linter",
    ...
)

py_binary(
    name = "some_other_linter",
    ...
)

command(
    name = "lint-something",
    command = ":some_linter",
    arguments = ["check"], # Optional arguments passed directly to the tool
)

command(
    name = "lint-something-else",
    command = ":some_other_linter",
    environment = {"CHECK": "true"}, # Optional environment variables set when invoking the command
    data = ["..."] # Optional runtime data dependencies
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
data The list of files needed by this command at runtime. See general comments about data at https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes List of labels optional []
arguments List of command line arguments. Subject to $(location) expansion. See https://docs.bazel.build/versions/master/skylark/lib/ctx.html#expand_location List of strings optional []
command Target to run Label required
description A string describing the command printed during multiruns String optional ""
environment Dictionary of environment variables. Subject to $(location) expansion. See https://docs.bazel.build/versions/master/skylark/lib/ctx.html#expand_location Dictionary: String -> String optional {}

command_force_opt

command_force_opt(name, data, arguments, command, description, environment)

A command that forces the compilation mode of the dependent targets to opt. This can be useful if your tools have improved performance if built with optimizations. See the documentation for command for more examples. If you'd like to always use this variation you can import this directly and rename it for convenience like:

load("@rules_multirun//:defs.bzl", "multirun", command = "command_force_opt")

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
data The list of files needed by this command at runtime. See general comments about data at https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes List of labels optional []
arguments List of command line arguments. Subject to $(location) expansion. See https://docs.bazel.build/versions/master/skylark/lib/ctx.html#expand_location List of strings optional []
command Target to run Label required
description A string describing the command printed during multiruns String optional ""
environment Dictionary of environment variables. Subject to $(location) expansion. See https://docs.bazel.build/versions/master/skylark/lib/ctx.html#expand_location Dictionary: String -> String optional {}

multirun

multirun(name, data, buffer_output, commands, jobs, keep_going, print_command)

A multirun composes multiple command rules in order to run them in a single bazel invocation, optionally in parallel. This can have a major performance improvement both in build time and run time depending on your tools.

load("@rules_multirun//:defs.bzl", "command", "multirun")
load("@rules_python//python:defs.bzl", "py_binary")

sh_binary(
    name = "some_linter",
    ...
)

py_binary(
    name = "some_other_linter",
    ...
)

command(
    name = "lint-something",
    command = ":some_linter",
    arguments = ["check"], # Optional arguments passed directly to the tool
)

command(
    name = "lint-something-else",
    command = ":some_other_linter",
    environment = {"CHECK": "true"}, # Optional environment variables set when invoking the command
    data = ["..."] # Optional runtime data dependencies
)

multirun(
    name = "lint",
    commands = [
        "lint-something",
        "lint-something-else",
    ],
    jobs = 0, # Set to 0 to run in parallel, defaults to sequential
)

With this configuration you can bazel run :lint and it will run both both linters in parallel. If you would like to run them serially you can omit the jobs attribute.

NOTE: If your commands change files in the workspace you might want to prefer sequential execution to avoid race conditions when changing the same file from multiple tools.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
data The list of files needed by the commands at runtime. See general comments about data at https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes List of labels optional []
buffer_output Buffer the output of the commands and print it after each command has finished. Only for parallel execution. Boolean optional False
commands Targets to run List of labels optional []
jobs The expected concurrency of targets to be executed. Default is set to 1 which means sequential execution. Setting to 0 means that there is no limit concurrency. Integer optional 1
keep_going Keep going after a command fails. Only for sequential execution. Boolean optional False
print_command Print what command is being run before running it. Boolean optional True

command_with_transition

command_with_transition(cfg, allowlist, doc)

Create a command rule with a transition to the given configuration.

This is useful if you have a project-specific configuration that you want to apply to all of your commands. See also multirun_with_transition.

PARAMETERS

Name Description Default Value
cfg The transition to force on the dependent targets. none
allowlist The transition allowlist to use for the given cfg. Not necessary in newer bazel versions. None
doc The documentation to use for the rule. Only necessary if you're generating documentation with stardoc for your custom rules. None

multirun_with_transition

multirun_with_transition(cfg, allowlist)

Creates a multirun rule which transitions all commands to the given configuration.

This is useful if you have a project-specific configuration that you want to apply to all of your commands. See also command_with_transition.

PARAMETERS

Name Description Default Value
cfg The transition to force on the dependent commands. none
allowlist The transition allowlist to use for the given cfg. Not necessary in newer bazel versions. None