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_env: dict[str, 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' ]
```
default_env: (defaults to: {})

A map of environment variables that will be passed to the executable represented by exe on startup if they are not already set by the environment. Environment variables support the same macros as arguments.
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",
    },
)

Details​

Function Signature​

Parameters​

Examples​

Details

Function Signature

Parameters

Examples