Buck: cxx_genrule()

cxx_genrule()

A cxx_genrule() is used to post-process a C or C++ executable or library. A cxx_genrule() exposes information about the tools and flags that were used during compilation and linking. 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

Arguments

  • name (required) #

    The name of the rule.

  • srcs (defaults to []) #

    A list of files to be used in the shell command.

  • cmd (defaults to None) #

    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 build 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.

    $(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 a subset of the builtin string parameter macros. Note that all build rules expanded in the command will be automatically considered to be dependencies of the genrule().

    $(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.

  • bash (defaults to None) #

    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 /bin/bash -c. It has access to the same set of macros and variables as the cmd argument.

  • cmd_exe (defaults to None) #

    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 /c. It has access to the same set of macros and variables as the cmd argument.

  • type (defaults to None) #

    The type of this genrule. This is used for logging and is particularly useful for grouping different genrules that share an underlying logical "type".

  • out (required) #

    The name of the output file or directory. Must be unique within the build file in which the genrule() is declared.

  • environment_expansion_separator (defaults to " ") #

    The delimiter between paths in environment variables that are populated by buck in genrules, like SRCS, that can contain multiple paths. This can be useful if paths contain spaces.

  • enable_sandbox (defaults to False) #

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

  • executable (defaults to False) #

    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.

  • tests (defaults to []) #

    List of build targets that identify the test rules that exercise this target.

  • visibility (defaults to []) #

    List of build target patterns that identify the build rules that can include this rule in its deps.

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

  • 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 attrfilter.