<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/6.1.0/_book.yaml">
</head>
<body>

<h1 class="page-title" id="modules.Args">Args</h1>

<!-- {% raw %} -->

An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line.<p>It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in <a href='depset.html'><code>depset</code></a>s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization.<p>For this reason, the action-constructing functions accept <code>Args</code> objects in addition to strings. Each <code>Args</code> object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. <code>Args</code> objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the <a href='https://bazel.build/versions/6.1.0/rules/performance'>Optimizing Performance</a> page for more information.<p><code>Args</code> are constructed by calling <a href='actions.html#args'><code>ctx.actions.args()</code></a>. They can be passed as the <code>arguments</code> parameter of <a href='actions.html#run'><code>ctx.actions.run()</code></a> or <a href='actions.html#run_shell'><code>ctx.actions.run_shell()</code></a>. Each mutation of an <code>Args</code> object appends values to the eventual command line.<p>The <code>map_each</code> feature allows you to customize how items are transformed into strings. If you do not provide a <code>map_each</code> function, the standard conversion is as follows: <ul><li>Values that are already strings are left as-is.<li><a href='File.html'><code>File</code></a> objects are turned into their     <code>File.path</code> values.<li>All other types are turned into strings in an <i>unspecified</i> manner. For     this reason, you should avoid passing values that are not of string or     <code>File</code> type to <code>add()</code>, and if you pass them to     <code>add_all()</code> or <code>add_joined()</code> then you should provide a     <code>map_each</code> function.</ul><p>When using string formatting (<code>format</code>, <code>format_each</code>, and <code>format_joined</code> params of the <code>add*()</code> methods), the format template is interpreted in the same way as <code>%</code>-substitution on strings, except that the template must have exactly one substitution placeholder and it must be <code>%s</code>. Literal percents may be escaped as <code>%%</code>. Formatting is applied after the value is converted to a string as per the above.<p>Each of the <code>add*()</code> methods have an alternate form that accepts an extra positional parameter, an "arg name" string to insert before the rest of the arguments. For <code>add_all</code> and <code>add_joined</code> the extra string will not be added if the sequence turns out to be empty. For instance, the same usage can add either <code>--foo val1 val2 val3 --bar</code> or just <code>--bar</code> to the command line, depending on whether the given sequence contains <code>val1..val3</code> or is empty.<p>If the size of the command line can grow longer than the maximum size allowed by the system, the arguments can be spilled over into parameter files. See <a href='#use_param_file'><code>use_param_file()</code></a> and <a href='#set_param_file_format'><code>set_param_file_format()</code></a>.<p>Example: Suppose we wanted to generate the command line: <pre>
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
</pre>We could use the following <code>Args</code> object: <pre class=language-python>
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)
</pre>

<h2>Members</h2>
<ul>
    <li>
    <a href="#add">add</a>
  </li>
      <li>
    <a href="#add_all">add_all</a>
  </li>
      <li>
    <a href="#add_joined">add_joined</a>
  </li>
      <li>
    <a href="#set_param_file_format">set_param_file_format</a>
  </li>
      <li>
    <a href="#use_param_file">use_param_file</a>
  </li>
  </ul>

      <h2 id="add">add</h2>
        <p><pre class="rule-signature"><a class="anchor" href="Args.html">Args</a> Args.add(arg_name_or_value, value=unbound, *, format=None)</pre></p>

    Appends an argument to this command line.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="add.arg_name_or_value">
              <code>arg_name_or_value</code>
            </td>
            <td>
                                     required<br/>
                          If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as <code>value</code> (see below).
            </td>
          </tr>
                  <tr>
            <td id="add.value">
              <code>value</code>
            </td>
            <td>
                                     default = unbound<br/>
                          The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no <code>map_each</code> parameter for this function, <code>value</code> should be either a string or a <code>File</code>. A list, tuple, depset, or directory <code>File</code> must be passed to <a href='#add_all'><code>add_all()</code> or <a href='#add_joined'><code>add_joined()</code></a> instead of this method.
            </td>
          </tr>
                  <tr>
            <td id="add.format">
              <code>format</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          A format string pattern, to be applied to the stringified version of <code>value</code>.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="add_all">add_all</h2>
        <p><pre class="rule-signature"><a class="anchor" href="Args.html">Args</a> Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)</pre></p>

    Appends multiple arguments to this command line. The items are processed lazily during the execution phase.<p>Most of the processing occurs over a list of arguments to be appended, as per the following steps:<ol><li>Each directory <code>File</code> item is replaced by all <code>File</code>s recursively contained in that directory.</li><li>If <code>map_each</code> is given, it is applied to each item, and the     resulting lists of strings are concatenated to form the initial argument     list. Otherwise, the initial argument list is the result of applying the     standard conversion to each item.<li>Each argument in the list is formatted with <code>format_each</code>, if     present.<li>If <code>uniquify</code> is true, duplicate arguments are removed. The first     occurrence is the one that remains.<li>If a <code>before_each</code> string is given, it is inserted as a new     argument before each existing argument in the list. This effectively doubles     the number of arguments to be appended by this point.<li>Except in the case that the list is empty and <code>omit_if_empty</code> is     true (the default), the arg name and <code>terminate_with</code> are     inserted as the first and last arguments, respectively, if they are given.</ol>Note that empty strings are valid arguments that are subject to all these processing steps.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="add_all.arg_name_or_values">
              <code>arg_name_or_values</code>
            </td>
            <td>
                                     required<br/>
                          If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the <code>values</code> without any processing. This arg name will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).
            </td>
          </tr>
                  <tr>
            <td id="add_all.values">
              <code>values</code>
            </td>
            <td>
                          <code><a class="anchor" href="list.html">sequence</a>; or <a class="anchor" href="depset.html">depset</a></code>;
                                     default = unbound<br/>
                          The list, tuple, or depset whose items will be appended.
            </td>
          </tr>
                  <tr>
            <td id="add_all.map_each">
              <code>map_each</code>
            </td>
            <td>
                          <code>callable; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used.<p>The function is passed either one or two positional arguments: the item to convert, followed by an optional <a href='DirectoryExpander.html'><code>DirectoryExpander</code></a>. The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter.<p>The return value's type depends on how many arguments are to be produced for the item:<ul><li>In the common case when each item turns into one string, the function     should return that string.<li>If the item is to be filtered out entirely, the function should return     <code>None</code>.<li>If the item turns into multiple strings, the function returns a list of     those strings.</ul>Returning a single string or <code>None</code> has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed.<p>Ordinarily, items that are directories are automatically expanded to their contents when <code>expand_directories=True</code> is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the <code>DirectoryExpander</code> argument can be applied to manually obtain the files of a given directory.<p>To avoid unintended retention of large analysis-phase data structures into the execution phase, the <code>map_each</code> function must be declared by a top-level <code>def</code> statement; it may not be a nested function closure by default.<p><i>Warning:</i> <a href='globals.html#print'><code>print()</code></a> statements that are executed during the call to <code>map_each</code> will not produce any visible output.
            </td>
          </tr>
                  <tr>
            <td id="add_all.format_each">
              <code>format_each</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          An optional format string pattern, applied to each string returned by the <code>map_each</code> function. The format string must have exactly one '%s' placeholder.
            </td>
          </tr>
                  <tr>
            <td id="add_all.before_each">
              <code>before_each</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          An optional string to append before each argument derived from <code>values</code> is appended.
            </td>
          </tr>
                  <tr>
            <td id="add_all.omit_if_empty">
              <code>omit_if_empty</code>
            </td>
            <td>
                                     default = True<br/>
                          If true, if there are no arguments derived from <code>values</code> to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and <code>terminate_with</code>, if provided, will still be appended regardless of whether or not there are other arguments.
            </td>
          </tr>
                  <tr>
            <td id="add_all.uniquify">
              <code>uniquify</code>
            </td>
            <td>
                                     default = False<br/>
                          If true, duplicate arguments that are derived from <code>values</code> will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items.
            </td>
          </tr>
                  <tr>
            <td id="add_all.expand_directories">
              <code>expand_directories</code>
            </td>
            <td>
                                     default = True<br/>
                          If true, any directories in <code>values</code> will be expanded to a flat list of files. This happens before <code>map_each</code> is applied.
            </td>
          </tr>
                  <tr>
            <td id="add_all.terminate_with">
              <code>terminate_with</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          An optional string to append after all other arguments. This string will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered).
            </td>
          </tr>
                  <tr>
            <td id="add_all.allow_closure">
              <code>allow_closure</code>
            </td>
            <td>
                                     default = False<br/>
                          If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="add_joined">add_joined</h2>
        <p><pre class="rule-signature"><a class="anchor" href="Args.html">Args</a> Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)</pre></p>

    Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase.<p>Processing is similar to <a href='#add_all'><code>add_all()</code></a>, but the list of arguments derived from <code>values</code> is combined into a single argument as if by <code>join_with.join(...)</code>, and then formatted using the given <code>format_joined</code> string template. Unlike <code>add_all()</code>, there is no <code>before_each</code> or <code>terminate_with</code> parameter since these are not generally useful when the items are combined into a single argument.<p>If after filtering there are no strings to join into an argument, and if <code>omit_if_empty</code> is true (the default), no processing is done. Otherwise if there are no strings to join but <code>omit_if_empty</code> is false, the joined string will be an empty string.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="add_joined.arg_name_or_values">
              <code>arg_name_or_values</code>
            </td>
            <td>
                                     required<br/>
                          If two positional parameters are passed this is interpreted as the arg name. The arg name is added before <code>values</code> without any processing. This arg will not be added if <code>omit_if_empty</code> is true (the default) and there are no strings derived from <code>values</code> to join together (which can happen if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).
            </td>
          </tr>
                  <tr>
            <td id="add_joined.values">
              <code>values</code>
            </td>
            <td>
                          <code><a class="anchor" href="list.html">sequence</a>; or <a class="anchor" href="depset.html">depset</a></code>;
                                     default = unbound<br/>
                          The list, tuple, or depset whose items will be joined.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.join_with">
              <code>join_with</code>
            </td>
            <td>
                                     required<br/>
                          A delimiter string used to join together the strings obtained from applying <code>map_each</code> and <code>format_each</code>, in the same manner as <a href='string.html#join'><code>string.join()</code></a>.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.map_each">
              <code>map_each</code>
            </td>
            <td>
                          <code>callable; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          Same as for <a href='#add_all.map_each'><code>add_all</code></a>.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.format_each">
              <code>format_each</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          Same as for <a href='#add_all.format_each'><code>add_all</code></a>.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.format_joined">
              <code>format_joined</code>
            </td>
            <td>
                          <code><a class="anchor" href="string.html">string</a>; or <a class="anchor" href="globals.html#None">None</a></code>;
                                     default = None<br/>
                          An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.omit_if_empty">
              <code>omit_if_empty</code>
            </td>
            <td>
                                     default = True<br/>
                          If true, if there are no strings to join together (either because <code>values</code> is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings).
            </td>
          </tr>
                  <tr>
            <td id="add_joined.uniquify">
              <code>uniquify</code>
            </td>
            <td>
                                     default = False<br/>
                          Same as for <a href='#add_all.uniquify'><code>add_all</code></a>.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.expand_directories">
              <code>expand_directories</code>
            </td>
            <td>
                                     default = True<br/>
                          Same as for <a href='#add_all.expand_directories'><code>add_all</code></a>.
            </td>
          </tr>
                  <tr>
            <td id="add_joined.allow_closure">
              <code>allow_closure</code>
            </td>
            <td>
                                     default = False<br/>
                          Same as for <a href='#add_all.allow_closure'><code>add_all</code></a>.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="set_param_file_format">set_param_file_format</h2>
        <p><pre class="rule-signature"><a class="anchor" href="Args.html">Args</a> Args.set_param_file_format(format)</pre></p>

    Sets the format of the param file, if one is used

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="set_param_file_format.format">
              <code>format</code>
            </td>
            <td>
                                     required<br/>
                          Must be one of:<ul><li>"multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it.</li><li>"shell": Same as "multiline", but the items are shell-quoted</li><li>"flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library.</li></ul><p>The format defaults to "shell" if not called.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="use_param_file">use_param_file</h2>
        <p><pre class="rule-signature"><a class="anchor" href="Args.html">Args</a> Args.use_param_file(param_file_arg, *, use_always=False)</pre></p>

    Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits.<p>Bazel may choose to elide writing the params file to the output tree during execution for efficiency. If you are debugging actions and want to inspect the param file, pass <code>--materialize_param_files</code> to your build.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="use_param_file.param_file_arg">
              <code>param_file_arg</code>
            </td>
            <td>
                                     required<br/>
                          A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file.<p>For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt".
            </td>
          </tr>
                  <tr>
            <td id="use_param_file.use_always">
              <code>use_always</code>
            </td>
            <td>
                                     default = False<br/>
                          Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length.
            </td>
          </tr>
                </tbody>
      </table>


</body>
</html>

<!-- {% endraw %} -->
