genrule_common.bzl

# Copyright (c) Meta Platforms, Inc. and affiliates.
#
# This source code is licensed under both the MIT license found in the
# LICENSE-MIT file in the root directory of this source tree and the Apache
# License, Version 2.0 found in the LICENSE-APACHE file in the root directory
# of this source tree.

# TODO(cjhopman): This was generated by scripts/hacks/rules_shim_with_docs.py,
# but should be manually edited going forward. There may be some errors in
# the generated docs, and so those should be verified to be accurate and
# well-formatted (and then delete this TODO)

def _srcs_arg():
    return {
        "srcs": attrs.named_set(attrs.source(allow_directory = True), sorted = False, default = [], doc = """
    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.
"""),
    }

def _cmd_arg():
    return {
        "cmd": attrs.option(attrs.arg(), default = None, doc = """
    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.

"""),
    }

def _bash_arg():
    return {
        "bash": attrs.option(attrs.arg(), default = None, doc = """
    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.
"""),
    }

def _cmd_exe_arg():
    return {
        "cmd_exe": attrs.option(attrs.arg(), default = None, doc = """
    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.
"""),
    }

def _weight_arg():
    return {
        "weight": attrs.option(attrs.int(), default = None, doc = """
    How many local slots these genrule should take when executing locally.
"""),
    }

def _out_arg():
    return {
        "out": attrs.option(attrs.string(), default = None, doc = """
    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.
"""),
    }

def _type_arg():
    return {
        "type": attrs.option(attrs.string(), default = None, doc = """
    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

    ```
"""),
    }

def _environment_expansion_separator():
    return {
        "environment_expansion_separator": attrs.option(attrs.string(), default = None, doc = """
    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.
"""),
    }

def _env_arg():
    return {
        "env": attrs.dict(key = attrs.string(), value = attrs.arg(), sorted = False, default = {}, doc = """
        A map of variables to be set in the environment where the shell command is run.
"""),
    }

genrule_common = struct(
    srcs_arg = _srcs_arg,
    cmd_arg = _cmd_arg,
    bash_arg = _bash_arg,
    cmd_exe_arg = _cmd_exe_arg,
    out_arg = _out_arg,
    type_arg = _type_arg,
    weight_arg = _weight_arg,
    environment_expansion_separator = _environment_expansion_separator,
    env_arg = _env_arg,
)