cxx_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 = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _genrule_toolchain: str = ...,
    always_print_stderr: bool = ...,
    bash: None | str = ...,
    cacheable: None | bool = ...,
    cmd: None | str = ...,
    cmd_exe: None | 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 = ...,
    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]] = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: None | str = ...,
    weight: None | int = ...,
) -> None

A cxx_genrule() enables you to run shell commands as part of the Buck build process. A cxx_genrule() exposes - through a set of string parameter macros and variables - information about the tools and configuration options used by the Buck environment, specifically those related to the C/C++ toolchain.

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 of bash and cmd_exe. The shell command can access information about the buck build environment through a set of macros, parameterized macros, and variables.

Macros

The following macros are available to the shell command and are accessed using the following syntax.
```
$(<macro>)
```
Example:
```
$(cc)
```
$(cc) Path to the C compiler.

$(cxx) Path to the C++ compiler.

$(cflags) Flags passed to the C compiler.

$(cppflags) Flags passed to the C preprocessor.

$(cxxflags) Flags passed to the C++ compiler.

$(cxxppflags) Flags to pass to the C++ preprocessor.

$(ld) Path to the linker.

$(ldflags-pic) Flags passed to the linker for binaries that use position-independent code (PIC).

$(ldflags-pic-filter <pattern>) Flags passed to the linker for binaries that use position-independent code (PIC). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

$(ldflags-shared) Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs).

$(ldflags-shared-filter <pattern>) Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

$(ldflags-static) Flags passed to the linker for statically-linked libraries.

$(ldflags-static-filter <pattern>) Flags passed to the linker for statically-linked libraries. Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

$(platform-name) The platform flavor with which this cxx_genrule was specified.

Parameterized Macros

It is also possible to expand references to other rules within the shell command, using the following subset of the builtin string parameter macros . Note that all build rules expanded in the command are automatically considered to be dependencies of the genrule().

Note that the paths returned by these macros are absolute paths. You should convert these paths to be relative paths before embedding them in, for example, a shell script or batch file. Using relative paths ensures that your builds are hermetic, that is, they are reproducible across different machine environments.

Additionally, if you embed these paths in a shell script, you should execute that script using the sh_binary() rule and include the targets for these paths in the resources argument of that sh_binary rule. These are the same targets that you pass to the string parameter macros.

$(exe //path/to:target) Expands to the commands necessary to run the executable generated by the specified build rule. For a C++ executable, this will typically just be the name of the output executable itself, such as main. If the specified build rule does not generate an executable output, an exception will be thrown and the build will fail.

$(location //path/to:target) Expands to the path of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

Variables

Finally, Buck adds the following variables to the environment in which the shell command runs. They are accessed using the following syntax. Note the use of braces rather than parentheses.
```
${<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 an absolute path.

${SRCDIR} The absolute path to the to which sources are copied prior to running the command.

${OUT} The output file for the genrule(). The file 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.
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.
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.
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

The information exposed through these tools and configuration options is a reflection of: Buck's built-in settings, the settings in .buckconfig and .buckconfig.local, and the result of various command-line overrides specified through the common_parameters command-line option.

This information is available only to the shell commands specified in the cxx_genrule. The information is not available to other arguments of the rule.

A cxx_genrule() can be an input to another cxx_genrule().

Note that if you specify the cxx_genrule as a command-line target to buck build, you must include a platform flavor. For example:

buck build :cxx_gr_name#iphonesimulator-x86_64

You could also just specify the default platform flavor explicitly:

buck build :cxx_gr_name#default

name​

Parameters​

Macros​

Parameterized Macros​

Variables​

Details​

name

Parameters

Macros

Parameterized Macros

Variables

Details