Class Genrule

  • All Implemented Interfaces:
    BuildEngineAction, HasOutputName, AllowsNonAnnotatedFields, HasMultipleOutputs, SupportsInputBasedRuleKey, BuildRule, HasNameAndType, Comparable<BuildRule>
    Direct Known Subclasses:
    GenruleBinary

    public class Genrule
    extends BaseGenrule<GenruleBuildable>
    implements HasOutputName, HasMultipleOutputs
    Build rule for generating a file via a shell command. For example, to generate the katana AndroidManifest.xml from the wakizashi AndroidManifest.xml, such a rule could be defined as:
     genrule(
       name = 'katana_manifest',
       srcs = [
         'wakizashi_to_katana_manifest.py',
         'AndroidManifest.xml',
       ],
       cmd = 'python wakizashi_to_katana_manifest.py ${SRCDIR}/AndroidManfiest.xml > $OUT',
       out = 'AndroidManifest.xml',
     )
     

    The output of this rule would likely be used as follows:

     android_binary(
       name = 'katana',
       manifest = ':katana_manifest',
       deps = [
         # Additional dependent android_library rules would be listed here, as well.
       ],
     )
     

    Named outputs are availabe in genrules by using `outs` instead of `out`. Only one of 'out' or 'outs' may be present in a genrule. For example, the aforementioned rule can be defined as:

     genrule(
       name = 'katana_manifest',
       srcs = [
         'wakizashi_to_katana_manifest.py',
         'AndroidManifest.xml',
       ],
       cmd = 'python wakizashi_to_katana_manifest.py ${SRCDIR}/AndroidManfiest.xml > $OUT',
       outs = {
        'manifest': [ 'AndroidManifest.xml'] ,
       },
     )
     

    The key-value pairs in 'outs' define the named output groups provided by this genrule. The keys are OutputLabel instances, while the values are outputs relative to this genrule's output directory. Genrule outputs with 'outs' can be consumed using the BuildTargetWithOutputs syntax. For example:

     android_binary(
       name = 'katana',
       manifest = ':katana_manifest[manifest]',
       deps = [
         # Additional dependent android_library rules would be listed here, as well.
       ],
     )
     

    If a rule with 'outs' is consumed without an output label, the default output group is returned. Currently, the default output group is an empty set. In the future, it would be the set of all named outputs.

    A genrule is evaluated by running the shell command specified by cmd with the following environment variable substitutions:

    • SRCS will be a space-delimited string expansion of the srcs attribute where each element of srcs will be translated into an absolute path.
    • SRCDIR will be a directory containing all files mentioned in the srcs.
    • TMP will be a temporary directory which can be used for intermediate results
    • OUT is the output file for the genrule() if 'out' is used. If using `outs`, it is the output directory. 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.
    In the above example, if the katana_manifest rule were defined in the src/com/facebook/wakizashi directory, then the command that would be executed would be:
     python convert_to_katana.py src/com/facebook/wakizashi/AndroidManifest.xml > \
         buck-out/gen/src/com/facebook/wakizashi/AndroidManifest.xml
     
    Note that cmd could be run on either Mac or Linux, so it should contain logic that works on either platform. If this becomes an issue in the future (or we want to support building on different platforms), then we could introduce a new attribute that is a map of target platforms to the appropriate build command for that platform.

    Note that the SRCDIR is populated by symlinking the sources.