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 | target_name_glob] = [],
    within_view: list[str | target_name_glob] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _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] = [],
    env: dict[str, str] = {},
    exe: None | str = None,
    executable_name: None | str = None,
    labels: list[str] = [],
    licenses: list[str] = [],
    platform_exe: dict[str, str | 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 OS names (linux, macos, windows) to executable dependencies or arch maps, for example: {"linux": {"x86_64": ":tool-x86", "arm64": ":tool-arm"}, "macos": ":universal"}.

  Arch maps support x86_64 and arm64. Thin configurations select the target arch. Fat linux configurations require both Linux branches and dispatch at runtime using uname -m (aarch64 is treated as arm64).

  Fat mac/linux configurations dispatch only the OS at runtime. Arch maps for both OSes select the same configured target arch, which must be x86_64 or arm64. For hosts with different architectures, use flat entries supplying a suitable portable executable for each OS.

  Each mapped target must already build or supply an executable for the named architecture. Adding an arm64 key does not make Buck compile that target for ARM. Buck may configure mapped dependencies even when they are not selected. All arch maps must be nonempty and use supported keys, including maps for unselected OSes.

  exe is an optional fallback for omitted OS entries, not missing arch entries. Without it, an omitted OS is an error if any entry is an arch map. With only flat entries, args supplies the command for an omitted OS.

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