Skip to main content

genrule

name

def name(
*,
name: str,
default_target_platform: None | str = ...,
target_compatible_with: list[str] = ...,
compatible_with: list[str] = ...,
exec_compatible_with: list[str] = ...,
visibility: list[str] = ...,
within_view: list[str] = ...,
metadata: OpaqueMetadata = ...,
tests: list[str] = ...,
modifiers: OpaqueMetadata = ...,
_apple_platforms: dict[str, str] = ...,
_build_only_native_code: bool = ...,
_exec_os_type: str = ...,
_genrule_toolchain: str = ...,
always_print_stderr: bool = ...,
bash: None | str = ...,
cacheable: None | bool = ...,
cmd: None | str = ...,
cmd_exe: None | str = ...,
constraint_overrides: list[str] = ...,
contacts: list[str] = ...,
default_host_platform: None | str = ...,
default_outs: None | list[str] = ...,
enable_sandbox: None | bool = ...,
env: dict[str, str] = ...,
environment_expansion_separator: None | str = ...,
executable: None | bool = ...,
executable_outs: None | list[str] = ...,
labels: list[str] = ...,
licenses: list[str] = ...,
metadata_env_var: None | str = ...,
metadata_path: None | str = ...,
need_android_tools: bool = ...,
no_outputs_cleanup: bool = ...,
out: None | str = ...,
outs: None | dict[str, list[str]] = ...,
platform_override: None | str = ...,
remote: None | bool = ...,
remote_execution_dependencies: list[dict[str, str]] = ...,
srcs: list[str] | dict[str, str] = ...,
type: None | str = ...,
weight: None | int = ...,
) -> None

A genrule() is used to generate files from a shell command. It must produce a single output file or folder.

Parameters

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • bash: A platform-specific version of the shell command parameter cmd. It runs on Linux and UNIX systems—including OSX—on which bash is installed. It has a higher priority than cmd. The bash argument is run with /usr/bin/env bash -c. It has access to the same set of macros and variables as the cmd argument.

  • cmd: The shell command to run to generate the output file. It is the fallback for bash and cmd_exe arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:

    ${<variable>}

    Example:

    ${SRCS}

    ${SRCS}

    A string expansion of the srcs argument delimited by the environment_expansion_separator argument where each element of srcs will be translated into a relative path.

    ${SRCDIR}

    The relative path to a directory to which sources are copied prior to running the command.

    ${OUT}

    The output file or directory for the genrule(). This variable will have whatever value is specified by the out argument if not using named outputs. If using named outputs, this variable will be the output directory.

    The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.

    The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.

    ${TMP}

    A temporary directory which can be used for intermediate results and will not be bundled into the output.

  • cmd_exe: A platform-specific version of the shell command parameter cmd. It runs on Windows and has a higher priority than cmd. The cmd_exe argument is run with cmd.exe /v:off /c. It has access to the same set of macros and variables as the cmd argument.

  • default_outs: Default output which must be present if the outs arg is present. Otherwise does not apply.

    If a rule with outs is consumed without an output label, the default output is returned. The default output does not need to be present in any of the named outputs defined in outs.

    Note that a maximum of one value may be present in this list. For example:

    default_outs = [ "output_one", ]

    is valid, whereas

    default_outs = [ "output_one", "output_two", ]

    is not.

  • enable_sandbox: Whether this target should be executed in a sandbox or not.

  • env: A map of variables to be set in the environment where the shell command is run.

  • environment_expansion_separator: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.

  • executable: Whether the output of the genrule is itself executable. Marking an output as executable makes buck run and $(exe ...) macro expansion work with this target.

  • executable_outs: Only valid if the outs arg is present. Dictates which of those named outputs are marked as executable.

  • out: The name of the output file or directory. The complete path to this argument is provided to the shell command through the OUT environment variable. Only one of out or outs may be present.

  • outs: Mapping defining named outputs to output paths relative to the rule's output directory. Only one of out or outs may be present.

    Example:


    genrule(
    name = "named_outputs",
    outs = {
    "output1": [
    "out1.txt",
    ],
    "output2": [
    "out2.txt",
    ],
    },
    default_outs = [ "out1.txt" ],
    cmd = "echo something> $OUT/out1.txt && echo another> $OUT/out2.txt",
    )

    Note that a maximum of one value may be present in the list in this map. For example:


    outs = {
    "output1": [
    "out1.txt",
    ],
    },

    is valid, whereas


    outs = {
    "output1": [
    "out1.txt",
    "out2.txt",
    ],
    },

    is not.

  • remote: Opts this genrule in to remote execution. Note that it is only safe to execute a genrule remotely if it is completely hermetic and completely and correctly describes its dependencies. Defaults to false. This parameter is unstable. It is subject to removal, default reversal, and other arbitrary changes in the future.

  • srcs: Either a list or a map of the source files which Buck makes available to the shell command at the path in the SRCDIR environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.

  • type: Specifies the type of this genrule. This is used for logging and is particularly useful for grouping genrules that share an underlying logical "type".

    For example, if you have the following cxx_genrule defined in the root directory of your Buck project



    cxx_genrule(
    name = 'cxx_gen',
    type = 'epilog',
    cmd = 'touch finish.txt; cp finish.txt $OUT',
    out = 'finish.txt'
    )

    then the following buck query command



    buck query "attrfilter( type, 'epilog', '//...' )"

    returns



    //:cxx_gen

  • weight: How many local slots these genrule should take when executing locally.

Details

Examples:

This genrule() uses a Python script to derive a new AndroidManifest.xml from an AndroidManifest.xml in the source tree. Note you don't need to prepend execution commands with python: Buck knows how to execute different kinds of binaries using $(exe) command.


genrule(
name = 'generate_manifest',
srcs = [
'AndroidManifest.xml',
],
bash = '$(exe //python/android:basic_to_full) ' '$SRCDIR/AndroidManifest.xml > $OUT',
cmd_exe = '$(exe //python/android:basic_to_full) ' '%SRCDIR%\AndroidManifest.xml > %OUT%',
out = 'AndroidManifest.xml',
)


genrule(
name = 'generate_manifest_with_named_outputs',
srcs = [
'AndroidManifest.xml',
],
bash = '$(exe //python/android:basic_to_full) ' '$SRCDIR/AndroidManifest.xml > $OUT/AndroidManifest.xml',
cmd_exe = '$(exe //python/android:basic_to_full) ' '%SRCDIR%\AndroidManifest.xml > %OUT%\AndroidManifest.xml',
outs = {
"manifest": [ "AndroidManifest.xml" ],
},
default_outs = [ "AndroidManifest.xml" ],
)

For named outputs, build with any of the following:


buck build //:generate_manifest_with_named_outputs


buck build //:generate_manifest_with_named_outputs[manifest]

Consume in srcs with:


export_file(
name = "magic1",
src = ":generate_manifest_with_named_outputs",
out = "some_dir_to_copy_to/AndroidManifest.xml",
)


export_file(
name = "magic2",
src = ":generate_manifest_with_named_outputs[manifest]",
out = "some_dir_to_copy_to/AndroidManifest.xml",
)

Note that magic1 consumes generate_manifest_with_named_outputs's default output. magic2 consumes generate_manifest_with_named_outputs's named output "manifest," which happen to be pointing to the same output as the default output in this case, but they do not have to point to the same output.