src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java

// Copyright 2018 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.lib.starlarkbuildapi;

import com.google.devtools.build.docgen.annot.DocCategory;
import com.google.devtools.build.lib.cmdline.Label;
import net.starlark.java.annot.Param;
import net.starlark.java.annot.ParamType;
import net.starlark.java.annot.StarlarkBuiltin;
import net.starlark.java.annot.StarlarkMethod;
import net.starlark.java.eval.EvalException;
import net.starlark.java.eval.NoneType;
import net.starlark.java.eval.Sequence;
import net.starlark.java.eval.StarlarkInt;
import net.starlark.java.eval.StarlarkThread;
import net.starlark.java.eval.StarlarkValue;

/** Interface for a module with native rule and package helper functions. */
@StarlarkBuiltin(
    name = "native",
    category = DocCategory.BUILTIN,
    doc =
        "A built-in module to support native rules and other package helper functions. "
            + "All native rules appear as functions in this module, e.g. "
            + "<code>native.cc_library</code>. "
            + "Note that the native module is only available in the loading phase "
            + "(i.e. for macros, not for rule implementations). Attributes will ignore "
            + "<code>None</code> values, and treat them as if the attribute was unset.<br>"
            + "The following functions are also available:")
public interface StarlarkNativeModuleApi extends StarlarkValue {

  @StarlarkMethod(
      name = "glob",
      doc =
          "Glob returns a new, mutable, sorted list of every file in the current package "
              + "that:<ul>\n"
              + "<li>Matches at least one pattern in <code>include</code>.</li>\n"
              + "<li>Does not match any of the patterns in <code>exclude</code> "
              + "(default <code>[]</code>).</li></ul>\n"
              + "If the <code>exclude_directories</code> argument is enabled "
              + "(set to <code>1</code>), files of type directory will be omitted from the "
              + "results (default <code>1</code>).",
      parameters = {
        @Param(
            name = "include",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            defaultValue = "[]",
            named = true,
            doc = "The list of glob patterns to include."),
        @Param(
            name = "exclude",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            defaultValue = "[]",
            named = true,
            doc = "The list of glob patterns to exclude."),
        // TODO(bazel-team): accept booleans as well as integers? (and eventually migrate?)
        @Param(
            name = "exclude_directories",
            defaultValue = "1", // keep consistent with glob prefetching logic in PackageFactory
            named = true,
            doc = "A flag whether to exclude directories or not."),
        @Param(
            name = "allow_empty",
            defaultValue = "unbound",
            named = true,
            doc =
                "Whether we allow glob patterns to match nothing. If `allow_empty` is False, each"
                    + " individual include pattern must match something and also the final"
                    + " result must be non-empty (after the matches of the `exclude` patterns are"
                    + " excluded).")
      },
      useStarlarkThread = true)
  Sequence<?> glob(
      Sequence<?> include,
      Sequence<?> exclude,
      StarlarkInt excludeDirectories,
      Object allowEmpty,
      StarlarkThread thread)
      throws EvalException, InterruptedException;

  @StarlarkMethod(
      name = "existing_rule",
      doc =
          "Returns an immutable dict-like object that describes the attributes of a rule"
              + " instantiated in this thread's package, or <code>None</code> if no rule instance"
              + " of that name exists." //
              + "<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object"
              + " <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in"
              + " x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>,"
              + " <code>x.keys()</code>, and <code>x.values()</code>." //
              + "<p>If the <code>--noincompatible_existing_rules_immutable_view</code> flag is set,"
              + " instead returns a new mutable dict with the same content." //
              + "<p>The result contains an entry for each attribute, with the exception of private"
              + " ones (whose names do not start with a letter) and a few unrepresentable legacy"
              + " attribute types. In addition, the dict contains entries for the rule instance's"
              + " <code>name</code> and <code>kind</code> (for example,"
              + " <code>'cc_binary'</code>)." //
              + "<p>The values of the result represent attribute values as follows:" //
              + "<ul><li>Attributes of type str, int, and bool are represented as is.</li>" //
              + "<li>Labels are converted to strings of the form <code>':foo'</code> for targets"
              + " in the same package or <code>'//pkg:name'</code> for targets in a different"
              + " package.</li>" //
              + "<li>Lists are represented as tuples, and dicts are converted to new, mutable"
              + " dicts. Their elements are recursively converted in the same fashion.</li>" //
              + "<li><code>select</code> values are returned with their contents transformed as " //
              + "described above.</li>" //
              + "<li>Attributes for which no value was specified during rule instantiation and"
              + " whose default value is computed are excluded from the result. (Computed defaults"
              + " cannot be computed until the analysis phase.).</li>" //
              + "</ul>" //
              + "<p>If possible, avoid using this function. It makes BUILD files brittle and"
              + " order-dependent. Also, beware that it differs subtly from the two"
              + " other conversions of rule attribute values from internal form to Starlark: one"
              + " used by computed defaults, the other used by <code>ctx.attr.foo</code>.",
      parameters = {@Param(name = "name", doc = "The name of the target.")},
      useStarlarkThread = true)
  Object existingRule(String name, StarlarkThread thread) throws EvalException;

  @StarlarkMethod(
      name = "existing_rules",
      doc =
          "Returns an immutable dict-like object describing the rules so far instantiated in this"
              + " thread's package. Each entry of the dict-like object maps the name of the rule"
              + " instance to the result that would be returned by"
              + " <code>existing_rule(name)</code>." //
              + "<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object"
              + " <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in"
              + " x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>,"
              + " <code>x.keys()</code>, and <code>x.values()</code>." //
              + "<p>If the <code>--noincompatible_existing_rules_immutable_view</code> flag is set,"
              + " instead returns a new mutable dict with the same content." //
              + "<p><em>Note: If possible, avoid using this function. It makes BUILD files brittle"
              + " and order-dependent. Furthermore, if the"
              + " </em><code>--noincompatible_existing_rules_immutable_view</code><em> flag is set,"
              + " this function may be very expensive, especially if called within a loop.</em>",
      useStarlarkThread = true)
  Object existingRules(StarlarkThread thread) throws EvalException;

  @StarlarkMethod(
      name = "package_group",
      doc =
          "This function defines a set of packages and assigns a label to the group. "
              + "The label can be referenced in <code>visibility</code> attributes.",
      parameters = {
        @Param(
            name = "name",
            named = true,
            positional = false,
            doc = "The unique name for this rule."),
        @Param(
            name = "packages",
            allowedTypes = {
              @ParamType(type = Sequence.class, generic1 = String.class),
            },
            defaultValue = "[]",
            named = true,
            positional = false,
            doc = "A complete enumeration of packages in this group."),
        @Param(
            name = "includes",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            defaultValue = "[]",
            named = true,
            positional = false,
            doc = "Other package groups that are included in this one.")
      },
      useStarlarkThread = true)
  NoneType packageGroup(
      String name, Sequence<?> packages, Sequence<?> includes, StarlarkThread thread)
      throws EvalException;

  @StarlarkMethod(
      name = "exports_files",
      doc =
          "Specifies a list of files belonging to this package that are exported to other "
              + "packages.",
      parameters = {
        @Param(
            name = "srcs",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            named = true,
            doc = "The list of files to export."),
        @Param(
            name = "visibility",
            allowedTypes = {
              @ParamType(type = Sequence.class),
              @ParamType(type = NoneType.class),
            },
            defaultValue = "None",
            named = true,
            doc =
                "A visibility declaration can to be specified. The files will be visible to the "
                    + "targets specified. If no visibility is specified, the files will be visible "
                    + "to every package."),
        @Param(
            name = "licenses",
            allowedTypes = {
              @ParamType(type = Sequence.class, generic1 = String.class),
              @ParamType(type = NoneType.class),
            },
            named = true,
            defaultValue = "None",
            doc = "Licenses to be specified.")
      },
      useStarlarkThread = true)
  NoneType exportsFiles(Sequence<?> srcs, Object visibility, Object licenses, StarlarkThread thread)
      throws EvalException;

  @StarlarkMethod(
      name = "package_name",
      doc =
          "The name of the package being evaluated. "
              + "For example, in the BUILD file <code>some/package/BUILD</code>, its value "
              + "will be <code>some/package</code>. "
              + "If the BUILD file calls a function defined in a .bzl file, "
              + "<code>package_name()</code> will match the caller BUILD file package. "
              + "This function is equivalent to the deprecated variable <code>PACKAGE_NAME</code>.",
      useStarlarkThread = true)
  String packageName(StarlarkThread thread) throws EvalException;

  @StarlarkMethod(
      name = "repository_name",
      doc =
          "The name of the repository the rule or build extension is called from. "
              + "For example, in packages that are called into existence by the WORKSPACE stanza "
              + "<code>local_repository(name='local', path=...)</code> it will be set to "
              + "<code>@local</code>. In packages in the main repository, it will be set to "
              + "<code>@</code>. This function is equivalent to the deprecated variable "
              + "<code>REPOSITORY_NAME</code>.",
      useStarlarkThread = true)
  String repositoryName(StarlarkThread thread) throws EvalException;

  @StarlarkMethod(
      name = "package_relative_label",
      doc =
          "Converts the input string into a <a href='Label'>Label</a> object, in the context of the"
              + " package currently being initialized (that is, the <code>BUILD</code> file for"
              + " which the current macro is executing). If the input is already a"
              + " <code>Label</code>, it is returned unchanged.<p>This function may only be called"
              + " while evaluating a BUILD file and the macros it directly or indirectly calls; it"
              + " may not be called in (for instance) a rule implementation function. <p>The result"
              + " of this function is the same <code>Label</code> value as would be produced by"
              + " passing the given string to a label-valued attribute of a target declared in the"
              + " BUILD file. <p><i>Usage note:</i> The difference between this function and <a"
              + " href='Label#Label'>Label()</a></code> is that <code>Label()</code> uses the"
              + " context of the package of the <code>.bzl</code> file that called it, not the"
              + " package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to"
              + " refer to a fixed target that is hardcoded into the macro, such as a compiler. Use"
              + " <code>package_relative_label()</code> when you need to normalize a label string"
              + " supplied by the BUILD file to a <code>Label</code> object. (There is no way to"
              + " convert a string to a <code>Label</code> in the context of a package other than"
              + " the BUILD file or the calling .bzl file. For that reason, outer macros should"
              + " always prefer to pass Label objects to inner macros rather than label strings.)",
      parameters = {
        @Param(
            name = "input",
            allowedTypes = {@ParamType(type = String.class), @ParamType(type = Label.class)},
            doc =
                "The input label string or Label object. If a Label object is passed, it's"
                    + " returned as is.")
      },
      useStarlarkThread = true)
  Label packageRelativeLabel(Object input, StarlarkThread thread) throws EvalException;

  @StarlarkMethod(
      name = "subpackages",
      doc =
          "Returns a new mutable list of every direct subpackage of the current package,"
              + " regardless of file-system directory depth. List returned is sorted and contains"
              + " the names of subpackages relative to the current package. It is advised to"
              + " prefer using the methods in bazel_skylib.subpackages module rather than calling"
              + " this function directly.",
      parameters = {
        @Param(
            name = "include",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            positional = false,
            named = true,
            doc = "The list of glob patterns to include in subpackages scan."),
        @Param(
            name = "exclude",
            allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
            defaultValue = "[]",
            positional = false,
            named = true,
            doc = "The list of glob patterns to exclude from subpackages scan."),
        @Param(
            name = "allow_empty",
            defaultValue = "False",
            positional = false,
            named = true,
            doc =
                "Whether we fail if the call returns an empty list. By default empty list indicates"
                    + " potential error in BUILD file where the call to subpackages() is"
                    + " superflous.  Setting to true allows this function to succeed in that case.")
      },
      useStarlarkThread = true)
  Sequence<?> subpackages(
      Sequence<?> include, Sequence<?> exclude, boolean allowEmpty, StarlarkThread thread)
      throws EvalException, InterruptedException;
}