path: root/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm

#if (!$singlePage)
---
layout: documentation
title: Functions
---
#end
#if (!$singlePage)
#parse("com/google/devtools/build/docgen/templates/be/header.vm")
#end

<h1>Functions</h1>

#if (!$singlePage)
<div class="toc">
  <h1>Contents</h1>
  <ul>
    <li><a href="#load">load</a></li>
    <li><a href="#package">package</a></li>
    <li><a href="#package_group">package_group</a></li>
    <li><a href="#licenses">licenses</a></li>
    <li><a href="#exports_files">exports_files</a></li>
    <li><a href="#glob">glob</a></li>
    <li><a href="#select">select</a></li>
    <li><a href="#workspace">workspace</a></li>
  </ul>
</div>
#end
<!-- =================================================================
                              load()
     =================================================================
-->

<h2 id="load">load</h2>

<pre>load(label, symbols...)</pre>

<p><code>load()</code> is a statement that imports definitions from a
  Skylark module (<code>.bzl</code> file). For example:
</p>

<pre class="code">
load("//tools/build_rules:build_test.bzl", "build_test")

build_test(name = ...)
</pre>

<p>This will execute the
  <a href="{{ page.version_prefix }}/docs/skylark/index.html">Skylark</a>
  module <code>tools/build_rules/build_test.bzl</code> and import the symbol
  <code>build_test</code> in the local environment. This is useful for
  using macros or for sharing values between multiple BUILD files. By
  using more arguments, you can load more symbols at once.</p>

<pre class="code">
load("//tools/build_rules:build_defs.bzl", "COMPILER_FLAGS", "LINKER_FLAGS")
</pre>

<p>
  In <code>load()</code> statement, keyword arguments have special meaning.
  They can be used to import a value from a <code>.bzl</code> file under a new
  name. For example:
</p>

<pre class="code">
load("//tools/build_rules:build_defs.bzl", BUILD_DEF_COMPILER_FLAGS="COMPILER_FLAGS", "LINKER_FLAGS")
</pre>
<p>
This will make <code>COMPILER_FLAGS</code> exported from
<code>build_defs.bzl</code> available under the name
<code>BUILD_DEF_COMPILER_FLAGS</code> in the current file.
</p>

<p>
  The label must refer to an existing package. For example, for the above
  statement to work, <code>tools/build_rules/BUILD</code> must exist (an empty
  file is sufficient) The name of the file must have the suffix
  <code>.bzl</code>. If the specified label is in the relative label syntax
  (<code>:a/b.bzl</code>), it will be resolved relative to the package of the
  file the <code>load</code> statement is in. <code>load</code> statements
  don't respect visibility: there is no need to use <code>exports_files</code>
  to make the <code>.bzl</code> file visible.
</p>

<p>
  Note: The <code>load</code> statement still supports the legacy syntax that refers
  to Skylark modules by their paths and not by their labels. This statement is
  equivalent to the first example:
</p>

<pre class="code">
load("/tools/build_rules/build_test", "build_test")
</pre>

<p>
  However, this syntax is deprecated and will be removed soon.
</p>

<!-- =================================================================
                              package()
     =================================================================
-->

<h2 id="package">package</h2>

<pre>
package(default_deprecation, default_testonly, default_visibility, features)
</pre>
<p>This function declares metadata that applies to every subsequent rule in the
package. It is used at most once within a package (BUILD file).</p>

<p>The package() function should be called right after all the load() statements at the top of the
file, before any rule.</p>

<h3 id="package_args">Arguments</h3>

<table class="table table-condensed table-bordered table-params">
  <colgroup>
    <col class="col-param" />
    <col class="param-description" />
  </colgroup>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td id="package.default_visibility"><code>default_visibility</code></td>
      <td>
        <p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
        <p>The default visibility of the rules in this package.</p>
        <p>Every rule in this package has the visibility specified in this
        attribute, unless otherwise specified in the <code>visibility</code>
        attribute of the rule. For detailed information about the syntax of this
        attribute, see the documentation of the
        <a href="common-definitions.html#common.visibility">visibility</a>
        attribute. The package default visibility does not apply to
        <a href="general.html#exports_files">exports_files</a>, which is
        public by default.</p>
      </td>
    </tr>
    <tr>
      <td id="package.default_deprecation"><code>default_deprecation</code></td>
      <td>
        <p><code>String; optional</code></p>
        <p>Sets the default <a href="common-definitions.html#common.deprecation">
        <code>deprecation</code></a> message for all rules in this package.</p>
      </td>
    </tr>
    <tr>
      <td id="package.default_testonly"><code>default_testonly</code></td>
      <td>
        <p><code>Boolean; optional; default is 0 except as noted</code></p>
        <p>Sets the default <a href="common-definitions.html#common.testonly">
        <code>testonly</code></a> property for all rules in this package.</p>
        <p>In packages under <code>javatests</code> the default value is 1.</p>
      </td>
    </tr>
    <tr>
      <td id="package.features"><code>features</code></td>
      <td>
        <p><code>List strings; optional</code></p>
        <p>Sets various flags that affect the semantics of this BUILD file.</p>
        <p>This feature is mainly used by the people working on the build system to
        tag packages that need some kind of special handling. Do not use this unless
        explicitly requested by someone working on the build system.</p>

      </td>
    </tr>

  </tbody>
</table>

<h3 id="package_example">Examples</h3>

The declaration below declares that the rules in this package are
visible only to members of package
group <code>//foo:target</code>. Individual visibility declarations
on a rule, if present, override this specification.

<pre class="code">
package(default_visibility = ["//foo:target"])
</pre>

<!-- =================================================================
                              package_group()
     =================================================================
-->

<h2 id="package_group">package_group</h2>

<pre>package_group(name, packages, includes)</pre>

<p>This function defines a set of packages and assigns a label to the
group. The label can be referenced in <code>visibility</code> attributes.</p>

<p>Package groups are used for visibility control.  You can grant access to a rule
to one or more package groups, every rule in the entire source tree, or only to rules declared
in the same package. For more detailed description of the visibility system, see
the <a href="common-definitions.html#common.visibility">visibility</a> attribute.

<h3 id="package_group_args">Arguments</h3>

<table class="table table-condensed table-bordered table-params">
  <colgroup>
    <col class="col-param" />
    <col class="param-description" />
  </colgroup>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td id="package_group.name"><code>name</code></td>
      <td>
        <p><code><a href="../build-ref.html#name">Name</a>; required</code></p>
        <p>A unique name for this rule.</p>
      </td>
    </tr>
    <tr>
      <td id="package_group.packages"><code>packages</code></td>
      <td>
        <p><code>List of <a href="../build-ref.html#packages">Package</a>; optional</code></p>
        <p>A complete enumeration of packages in this group.</p>

        <p>Packages should be referred to using their full names,
        starting with a double slash. For
        example, <code>//foo/bar/main</code> is a valid element
        of this list.</p>

        <p>You can also specify wildcards: the specification
        <code>//foo/...</code> specifies every package under
        <code>//foo</code>, including <code>//foo</code> itself.</p>

        <p>Package specifications can be prefixed with <code>-</code> to
        indicate negation: the specification <code>-//foo/bar/...</code>
        excludes all packages under <code>//foo/bar</code> that would
        otherwise have been matched by the package patterns in the
        current <code>package_group</code>. When used together with
        <code>includes</code>, the set of packages for each package group
        is computed and then the results are unioned: negative patterns
        in one package group do not affect the result of included package
        groups.

        <p>If this attribute is missing, the package group itself will contain
        no packages (but it can still include other package groups).</p>
      </td>
    </tr>
    <tr>
      <td id="package_group.includes"><code>includes</code></td>
      <td>
        <p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
        <p>Other package groups that are included in this one.</p>

        <p>The labels in this attribute must refer to other package
        groups. Packages in referenced package groups are taken to be part
        of this package group. This is transitive, that is, if package
        group <code>a</code> contains package group <code>b</code>,
        and <code>b</code> contains package group <code>c</code>, every
        package in <code>c</code> will also be a member of <code>a</code>.</p>
      </td>
    </tr>
  </tbody>
</table>

<h3 id="package_group_example">Examples</h3>

<p>The following <code>package_group</code> declaration specifies a
package group called "tropical" that contains tropical fruits.</p>

<pre class="code">
package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)
</pre>

<p>The following declarations specify the package groups of a fictional
application:</p>

<pre class="code">
package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)
</pre>

<!-- =================================================================
                              licenses()
     =================================================================
-->

<h2 id="licenses">licenses</h2>

<pre>licenses(license_types)</pre>

<p><code>licenses()</code> specifies the default license type (or types)
   of the build rules in a <code>BUILD</code> file.

   The <code>licenses()</code> directive should appear close to the
   beginning of the <code>BUILD</code> file, before any build rules, as it
   sets the <code>BUILD</code>-file scope default for build rule license
   types.</p>

<h3 id="licenses_args">Arguments</h3>

<p>The argument, <code id="licenses.licence_types">license_types</code>,
   is a list of license-type strings.
   <!-- TODO(bazel-team): specify some examples -->

</p>

<p>Valid license types include:</p>
<dl>
  <dt><code>restricted</code></dt><dd>Requires mandatory source
    distribution.</dd>
  <dt><code>reciprocal</code></dt><dd>Allows usage of software freely in
    <b>unmodified</b> form. Any modifications must be made freely
    available.</dd>
  <dt><code>notice</code></dt><dd>Original or modified third-party software may
    be shipped without danger nor encumbering other sources. All of the
    licenses in this category do, however, have an "original Copyright notice"
    or "advertising clause", wherein any external distributions must include
    the notice or clause specified in the license.</dd>
  <dt><code>permissive</code></dt><dd>Code that is under a license but does not
    require a notice.</dd>
  <dt><code>unencumbered</code></dt><dd>Public domain, free for any use.</dd>
</dl>
licenses(["notice"])  # MIT license

exports_files(["jquery-2.1.1.js"])
</pre>

<!-- =================================================================
                        exports_files([label, ...])
     =================================================================
  -->

<h2 id="exports_files">exports_files</h2>

<pre>exports_files([<i>label</i>, ...], visibility, licenses)</pre>

<p>
  <code>exports_files()</code> specifies a list of files belonging to
  this package that are exported to other packages but not otherwise
  mentioned in the BUILD file.
</p>

<p>
  The BUILD file for a package may only refer to files belonging to another
  package if they are mentioned somewhere in the other packages's BUILD file,
  whether as an input to a rule or an explicit or implicit output from a rule.
  The remaining files are not associated with a specific rule but are just "data",
  and for these, <code>exports_files</code> ensures that they may be referenced by
  other packages.  (One kind of data for which this is particularly useful are
  shell scripts.)
</p>

<h3 id="exports_files_args">Arguments</h3>

<p>
  The argument is a list of names of files within the current package. A
  visibility declaration can also be specified; in this case, the files will be
  visible to the targets specified. If no visibility is specified, the files
  will be visible to every package, even if a package default visibility was
  specified in the <code><a href="functions.html#package">package</a></code>
  function. The <a href="common-definitions.html#common.licenses">licenses</a>
  can also be specified.
</p>

<h3 id="exports_files_example">Example</h3>

<p>
  The following example exports <code>golden.txt</code>, a
  text file from the <code>test_data</code> package, so that other
  packages may use it, for example, in the <code>data</code> attribute
  of tests.
</p>

<pre class="code">
# from //test_data/BUILD

exports_files(["golden.txt"])
</pre>

<!-- =================================================================
                               glob()
     =================================================================
  -->

<h2 id="glob">glob</h2>

<pre>glob(include, exclude=[], exclude_directories=1)</pre>

<p>
Glob is a helper function that can be used anywhere a list of filenames
is expected.  It takes one or two lists of filename patterns containing
the <code>*</code> wildcard: as per the Unix shell, this wildcard
matches any string excluding the directory separator <code>/</code>.
In addition filename patterns can contain the recursive <code>**</code>
wildcard. This wildcard will match zero or more complete
path segments separated by the directory separator <code>/</code>.
This wildcard can only be used as a complete path segment. For example,
<code>"x/**/*.java"</code> is valid, but <code>"test**/testdata.xml"</code>
and <code>"**.java"</code> are both invalid. No other wildcards are supported.
</p>
<p>
Glob returns a sorted list of every file in the current package that:
</p>
<ul>
  <li>Matches at least one pattern in <code>include</code>. </li>
  <li>Does not match any of the patterns in <code>exclude</code> (default []).</li>
</ul>
<p>
If the <code>exclude_directories</code> argument is enabled (set to 1), files of
type directory will be omitted from the results (default 1).
</p>
<p>
There are several important limitations and caveats:
</p>

<ol>
  <li>
    Since <code>glob()</code> runs during BUILD file evaluation,
    <code>glob()</code> matches files only in your source tree, never
    generated files.  If you are building a target that requires both
    source and generated files, create a list of generated
    files. This list can be specified by using the labels for the generated
    files or using the label
    for the target that produces the generated files.
    Use <code>+</code> to add the list of
    generated files to the result of the <code>glob()</code> call as shown in
    the <a href="#glob_example">example</a>
    below with the target <code>:gen_java_srcs</code>.
  </li>

  <li>
    Globs may match files in subdirectories.  And subdirectory names
    may be wildcarded.  However...
  </li>

  <li>
    Labels are not allowed to cross the package boundary and glob does
    not match files in subpackages.

    For example, the glob expression <code>**/*.cc</code> in package
    <code>x</code> does not include <code>x/y/z.cc</code> if
    <code>x/y</code> exists as a package (either as
    <code>x/y/BUILD</code>, or somewhere else on the package-path). This
    means that the result of the glob expression actually depends on the
    existence of BUILD files &mdash; that is, the same glob expression would
    include <code>x/y/z.cc</code> if there was no package called
    <code>x/y</code> or it was marked as deleted using the
    <a href="../user-manual.html#flag--deleted_packages">--deleted_packages</a>
    flag.

  </li>

  <li>
    The restriction above applies to all glob expressions,
    no matter which wildcards they use.
  </li>
  <li>
    A hidden file with filename starting with <code>.</code> is matched by
    both the <code>**</code> and the <code>*</code> wildcards.
  </li>
  <li>
    If a rule and a source file with the same name both exist in the package, the glob will
    return the outputs of the rule instead of the source file.
  </li>

  <li>
    The "**" wildcard has one corner case: the pattern
    <code>"**"</code> doesn't match the package's directory path. That is to
    say, <code>glob(["**"], exclude_directories = 0)</code> matches all files
    and directories transitively strictly under the current package's directory
    (but of course not going into directories of subpackages - see the previous
    note about that).
  </li>
</ol>

<p>
In general, you should <b>try to provide an appropriate extension (e.g. *.html)
instead of using a bare '*'</b> for a glob pattern. The more explicit name
is both self documenting and ensures that you don't accidentally match backup
files, or emacs/vi/... auto-save files.
</p>

<p>
When writing build rules you can enumerate the elements of the glob. This
enables generating individual rules for every input, for example. See the
<a href="#expanded_glob_example">expanded glob example</a> section below.
</p>

<h3 id="glob_example">Glob Examples</h3>

<p> Create a Java library built from all java files in this directory,
and all files generated by the <code>:gen_java_srcs</code> rule.</p>
<pre class="code">
java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)
</pre>

<p>Include all txt files in directory testdata except experimental.txt.
Note that files in subdirectories of testdata will not be included. If
you want those files to be included, use a recursive glob (**).</p>
<pre class="code">
sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)
</pre>

<h3 id="recursive_glob_example">Recursive Glob Examples</h3>

<p>Create a library built from all java files in this directory and all
subdirectories except those whose path includes a directory named testing.
Subdirectories containing a BUILD file are ignored.
<b>This pattern should be avoided if possible, as it can reduce build
incrementality and therefore increase build times.</b>
</p>
<pre class="code">
java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)
</pre>

<p>Make the test depend on all txt files in the testdata directory,
   its subdirectories</p>
<pre class="code">
sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)
</pre>

<h3 id="expanded_glob_example">Expanded Glob Examples</h3>

<p>
Create an individual genrule for *_test.cc in the current directory
that counts the number of lines in the file.
</p>

<pre class="code">
# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $&lt; &gt;$@",
 ) for f in glob(["*_test.cc"])]
</pre>

<p>
If the BUILD file above is in package //foo and the package contains three
matching files, a_test.cc, b_test.cc and c_test.cc then running
<code>bazel query '//foo:all'</code> will list all rules that were generated:

<pre>
$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test
</pre>

<!-- =================================================================
                              select()
     =================================================================
-->

<h2 id="select">select</h2>

<pre>
select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)
</pre>

<p><code>select()</code> is the helper function that makes a rule attribute
  <a href="common-definitions.html#configurable-attributes">configurable</a>.
  It can replace the right-hand side of

  <i>almost</i>
  any attribute assignment so its value depends on command-line Bazel flags.
  This can be used, for example, to define platform-specific dependencies or to
  embed different resources depending on whether a rule is built in "developer"
  vs. "release" mode.
</p>

<p>Basic usage is as follows:</p>

<pre class="code">
sh_binary(
    name = "myrule",
    srcs = select({
        ":conditionA": ["myrule_a.sh"],
        ":conditionB": ["myrule_b.sh"],
        "//conditions:default": ["myrule_default.sh"]
    })
)
</pre>

<p>This makes the <code>srcs</code> attribute of
  a <code>sh_binary</code> configurable by replacing its normal label
  list assignment with a <code>select</code> call that maps
  configuration conditions to matching values. Each condition is a label
  reference to
  a <code><a href="general.html#config_setting">config_setting</a></code> instance,
  which "matches" if the rule's configuration matches an expected set of
  values. The value of <code>myrule#srcs</code> then becomes whichever
  label list matches the current invocation.
</p>

<p>Further notes:</p>

<ul>
  <li>Exactly one condition is selected on any invocation.
  </li>
  <li>If multiple conditions match and one is a specialization of the others
    (i.e. it matches on the same flags as any of the others plus additional
    ones), the specialization takes precedence.
  </li>
  <li>If multiple conditions match and one is not a specialization of all the
    others, Bazel fails with an error.
  </li>
  <li>The special pseudo-label <code>//conditions:default</code> is
    considered to match if no other condition matches. If this condition
    is left out, some other rule must match to avoid an error.
  </li>
  <li><code>select</code> can be embedded <i>inside</i> a larger
    attribute assignment. So <code>srcs = ["common.sh"]
    + select({ ":conditionA": ["myrule_a.sh"], ...})</code> and <code>
    srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB":
    ["b.sh"]})</code> are valid expressions.
  </li>
  <li><code>select</code> works with most, but not all, attributes. Incompatible
  attributes are marked <code>nonconfigurable</code> in their documentation.

  </li>
</ul>

By default, Bazel produces the following error when no conditions match:
<pre class="code">
Configurable attribute "foo" doesn't match this configuration (would a default
condition help?).
Conditions checked:
 //pkg:conditionA.
 //pkg:conditionB.
</pre>

<code>no_match_error</code> can be used to signal more precise errors.

<h3 id="select_example">Examples</h3>

<pre class="code">
config_setting(
    name = "windows",
    values = {
        "crosstool_top": "//crosstools/windows",
    },
)

cc_binary(
    name = "multiplatform_app",
    ...
    linkopts = select({
        ":windows": [
            "-Wl,windows_support1.lib",
            "-Wl,windows_support2.lib",
        ],
        "//conditions:default": [],
    ...
)
</pre>

<p>In the above example, <code>multiplatform_app</code> links with additional
  options when invoked with <code>bazel build //pkg:multiplatform_app
  --crosstool_top=//crosstools/windows </code>.

<p>

<!-- =================================================================
                              workspace()
     =================================================================
-->

<h2 id="workspace">workspace</h2>

<pre>workspace(name = "com_example_project")</pre>

<p>This can only be used in a WORKSPACE file.</p>

<p>Each repository's WORKSPACE file should have a workspace(name = "...") line,
  which sets a global name for the repository.</p>

<p>This name is used for the directory that the repository's runfiles are stored
  in. For example, if there is a runfile <code>foo/bar</code> in the local
  repository and the WORKSPACE file contains
  <code>workspace(name = "baz")</code>, then the runfile will be available under
  <code>mytarget.runfiles/baz/foo/bar</code>.  If no workspace name is
  specified, then the runfile will be symlinked to
  <code>bar.runfiles/foo/bar</code>.
</p>

<p>A workspace name must start with a letter and can contain letters, numbers,
  and underscores (this is to maximize the number of languages for which this
  string can be a valid package/module name). It should describe the project in
  reverse-DNS form, with elements separated by underscores. For example, if a
  project is hosted at example.com/some-project, you might use
  com_example_some_project as the workspace name.
</p>

<p><a href="workspace.html">Remote repository</a> rule names must be
  valid workspace names. For example, you could have
  <code>maven_jar(name = "foo")</code>, but not
  <code>maven_jar(name = "foo.bar")</code>, as Bazel would attempt to write a
  WORKSPACE file for the <code>maven_jar</code> containing
  <code>workspace(name = "foo.bar")</code>.
</p>

#if (!$singlePage)
#parse("com/google/devtools/build/docgen/templates/be/footer.vm")
#end