command_alias()

This is liable to change in the future.

The command_alias rule enables you to wrap build rules that create binaries and to pre-apply command-line arguments and environment variables.

Example uses include running a command written in a scripting language with a specific interpreter, and transparently wrapping sub-commands of a binary.

You can reference a command_alias target in the cmd parameter of a genrule by using the exe macro:

$(exe //path/to:target)

Arguments

• name (required) #

  The short name for this build target.

• 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. enables you 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 arguments that is passed to the executable specified by exe at startup. These arguments support a subset of Buck's string parameter macros. Only the $(location ...) and $(exe ...) macros are supported currently.

• 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 as a dependency, for example, by listing it in their deps or exported_deps attributes. For more information, see visibility.

• 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",
    },
)