Buck: command_alias()

command_alias()

This is liable to change in the future.

This rule allows to wrap other build rules that create binaries and to pre-apply command line arguments and environment variables.

Examples include providing a command written in a scripting language, and running it with a specific interpreter, or transparently wrapping sub-commands of a binary.

A command_alias rule can be referenced in the cmd parameter of a genrule by using the exe macro:
$(exe//path/to:target)

Arguments

  • name (required) #

    The name of the rule.

  • exe (defaults to None) #

    A build target for a rule that outputs an executable, such as an sh_binary.

  • platform_exe (defaults to {}) #

    A mapping from platforms to build target. Allows to override exe per host platform.

    If present, exe will be used as a fallback on host platforms that are not specified in platform_exe.

    It is possible to omit exe when providing platform_exe. In that case, the build will fail if the command is invoked on a platform not specified in the mapping.

    Valid platforms are all values of the Platform enum:

    • FREEBSD
    • LINUX
    • MACOS
    • WINDOWS

  • args (defaults to None) #

    A string of args that will be passed to the executable represented by exe on startup. Arguments support string parameter macros (only $(location ...) is supported at the moment).

  • env (defaults to None) #

    A map of environment variables that will be passed to the executable represented by exe on startup. Environment variables support the same macros as arguments.

  • visibility (defaults to []) #

    List of build target patterns that identify the build rules that can include this rule in its deps.

  • licenses (defaults to []) #

    Set of license files for this library. To get the list of license files for a given build rule and all of its dependencies, you can use buck query.

  • labels (defaults to []) #

    Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query attrfilter.

Examples

# Combining an interpreter and a script

cxx_binary(
    name = "node-js",
    srcs = [
        # ...
    ],
    headers = [
        # ...
    ],
)

export_file(
    name = "scripts"
)

command_alias(
    name = "server",
    exe = ":node-js",
    args = [
        "$(location :scripts)/start-server.js",
    ],
)
# Exposing sub commands

export_file(
    name = "yarn",
    src = "yarn.sh",
)

command_alias(
    name = "add",
    exe = ":yarn",
    args = ["add"],
)

command_alias(
    name = "install",
    exe = ":yarn",
    args = ["install"],
)

command_alias(
    name = "run",
    exe = ":yarn",
    args = ["run"],
)
# Platform specific commands

export_file(
    name = "node-windows",
    src = "windows/node.exe",
)

export_file(
    name = "node-linux",
    src = "linux/node",
)

export_file(
    name = "node-macos",
    src = "macos/node",
)

command_alias(
    name = "node",
    platform_exe = {
        "windows": ":node-windows",
        "linux": ":node-linux",
        "macos": ":node-macos",
    },
)