command_alias

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

Details

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)

Function Signature

def command_alias(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _apple_platforms: dict[str, str] = {},
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _target_os_type: str = "prelude//os_lookup/targets:os_lookup",
    args: list[str] = [],
    contacts: list[str] = [],
    default_host_platform: None | str = None,
    env: dict[str, str] = {},
    exe: None | str = None,
    executable_name: None | str = None,
    labels: list[str] = [],
    licenses: list[str] = [],
    platform_exe: dict[str, str] = {},
    resources: list[str] = [],
    run_using_single_arg: bool = False,
) -> None

Parameters

• name: (required)

  name of the target

• default_target_platform: (defaults to: None)

  specifies the default target platform, used when no platforms are specified on the command line

• target_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• exec_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

• visibility: (defaults to: [])

  a list of visibility patterns restricting what targets can depend on this one

• within_view: (defaults to: ["PUBLIC"])

  a list of visibility patterns restricting what this target can depend on

• metadata: (defaults to: {})

  a key-value map of metadata associated with this target

• tests: (defaults to: [])

  a list of targets that provide tests for this one

• modifiers: (defaults to: [])

  an array of modifiers associated with this target

• args: (defaults to: [])

  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.

• contacts: (defaults to: [])

  A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

  contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

• env: (defaults to: {})

  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.

• exe: (defaults to: None)

  A build target for a rule that outputs an executable, such as an sh_binary(), or an executable source file.

• executable_name: (defaults to: None)

  If provided, use this name for the trampoline script (with an extension added if required by the platform).

• 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().

• 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

• 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

• run_using_single_arg: (defaults to: False)

  Ensure that the command alias can be run as a single argument (instead of $(exe) or RunInfo potentially expanding to multiple arguments).

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