genrule()is used to generate files from a shell command. It must produce a single output file or folder.
The short name for this build target.
Either a list or a map of the source files which Buck makes available to the shell command at the path in the
SRCDIRenvironment 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.
The shell command to run to generate the output file. It is the fallback for
cmd_exearguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:
A string expansion of the
srcsargument delimited by the
environment_expansion_separatorargument where each element of
srcswill be translated into an absolute path.
The absolute path to a directory to which sources are copied prior to running the command.
The output file or directory for the
genrule(). This variable will have whatever value is specified by the
outargument. 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.
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.
A temporary directory which can be used for intermediate results and will not be bundled into the output.
String parameter macros
It is also possible to expand references to other rules within the
cmd, using builtin string parameter macros. All build rules expanded in the command are automatically considered to be dependencies of the
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_binaryrule and include the targets for these paths in the
resourcesargument of that
sh_binaryrule. These are the same targets that you pass to the string parameter macros.
Expands to the transitive classpath of the specified build rule, provided that the rule has a Java classpath. If the rule does not have (or contribute to) a classpath, then an exception is thrown and the build breaks.
Expands a build rule that results in an executable to the commands necessary to run that executable. For example, a
java_binary()might expand to a call to
java -jar path/to/target.jar. Files that are executable (perhaps generated by a
genrule()) are also expanded. If the build rule does not generate an executable output, then an exception is thrown and the build breaks.
Expands to the location of the output of the specified build rule. This means that you can refer to the output without needing to be aware of how Buck is storing data on the disk mid-build.
Expands to the Maven coordinates for the specified build rule. This allows you to access the Maven coordinates for Maven-aware build rules. The format of the expansion is:
A platform-specific version of the shell command parameter
cmd. It runs on Linux and UNIX systems—including OSX—on which
bashis installed. It has a higher priority than
bashargument is run with
/bin/bash -c. It has access to the same set of macros and variables as the
A platform-specific version of the shell command parameter
cmd. It runs on Windows and has a higher priority than
cmd_exeargument is run with
cmd.exe /c. It has access to the same set of macros and variables as the
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_genruledefined 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 "attrfilter( type, 'epilog', '//...' )"
The name of the output file or directory. The complete path to this argument is provided to the shell command through the
" ") #
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.
Whether this target should be executed in a sandbox or not.
Whether the output of the genrule is itself executable. Marking an output as executable makes
$(exe ...)macro expansion work with this target.
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.
List of build targets that identify tests that exercise this target.
List of build target patterns that identify the build rules that can include this rule as a dependency, for example, by listing it in their
exported_depsattributes. For more information, see visibility.
ExamplesThis genrule() uses a Python script to derive a new
AndroidManifest.xmlin the source tree. Note you don't need to prepend execution commands with
python: Buck knows how to execute different kinds of binaries using
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', )