| // 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.docgen.annot.StarlarkConstructor; |
| import com.google.devtools.build.lib.collect.nestedset.Depset; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.ProviderApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.StructApi; |
| import javax.annotation.Nullable; |
| 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.StarlarkThread; |
| |
| /** A provider that gives general information about a target's direct and transitive files. */ |
| @StarlarkBuiltin( |
| name = "DefaultInfo", |
| category = DocCategory.PROVIDER, |
| doc = |
| "A provider that gives general information about a target's direct and transitive files." |
| + " Every rule type has this provider, even if it is not returned explicitly by the" |
| + " rule's implementation function. Each <code>DefaultInfo</code> instance has the" |
| + " following fields: <ul><li><code>files</code><li><code>files_to_run</code>" |
| + "<li><code>data_runfiles</code><li><code>default_runfiles</code></ul>See the <a" |
| + " href='https://bazel.build/extending/rules'>rules</a> page for extensive guides on" |
| + " how to use this provider.") |
| public interface DefaultInfoApi extends StructApi { |
| |
| static final String DEPRECATED_RUNFILES_PARAMETER_WARNING = |
| "<p><b>It is recommended that you avoid using this parameter (see " |
| + "<a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>" |
| + "\"runfiles features to avoid\"</a>)</b></p> "; |
| |
| @StarlarkMethod( |
| name = "files", |
| doc = |
| "A <a href='../builtins/depset.html'><code>depset</code></a> of <a" |
| + " href='../builtins/File.html'><code>File</code></a> objects representing the" |
| + " default outputs to build when this target is specified on the bazel command line." |
| + " By default it is all predeclared outputs.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| Depset getFiles(); |
| |
| @StarlarkMethod( |
| name = "files_to_run", |
| doc = |
| "A <a href='../providers/FilesToRunProvider.html'><code>FilesToRunProvider</code></a>" |
| + " object containing information about the executable and runfiles of the target.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| FilesToRunProviderApi<?> getFilesToRun(); |
| |
| @StarlarkMethod( |
| name = "data_runfiles", |
| doc = |
| "runfiles descriptor describing the files that this target needs when run in the " |
| + "condition that it is a <code>data</code> dependency attribute. Under most " |
| + "circumstances, use the <code>default_runfiles</code> parameter instead. " |
| + "See <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>" |
| + "\"runfiles features to avoid\"</a> for details. ", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| RunfilesApi getDataRunfiles(); |
| |
| @StarlarkMethod( |
| name = "default_runfiles", |
| doc = |
| "runfiles descriptor describing the files that this target needs when run " |
| + "(via the <code>run</code> command or as a tool dependency).", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| RunfilesApi getDefaultRunfiles(); |
| |
| /** Provider for {@link DefaultInfoApi}. */ |
| @StarlarkBuiltin(name = "Provider", documented = false, doc = "") |
| interface DefaultInfoApiProvider<RunfilesT extends RunfilesApi, FileT extends FileApi> |
| extends ProviderApi { |
| |
| @StarlarkMethod( |
| name = "DefaultInfo", |
| doc = "<p>The <code>DefaultInfo</code> constructor.", |
| parameters = { |
| @Param( |
| name = "files", |
| allowedTypes = { |
| @ParamType(type = Depset.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "A <a href='../builtins/depset.html'><code>depset</code></a> of <a" |
| + " href='../builtins/File.html'><code>File</code></a> objects representing" |
| + " the default outputs to build when this target is specified on the bazel" |
| + " command line. By default it is all predeclared outputs."), |
| @Param( |
| name = "runfiles", |
| allowedTypes = { |
| @ParamType(type = RunfilesApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "runfiles descriptor describing the files that this target needs when run " |
| + "(via the <code>run</code> command or as a tool dependency)."), |
| @Param( |
| name = "data_runfiles", |
| allowedTypes = { |
| @ParamType(type = RunfilesApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| DEPRECATED_RUNFILES_PARAMETER_WARNING |
| + "runfiles descriptor describing the runfiles this target needs to run " |
| + "when it is a dependency via the <code>data</code> attribute."), |
| @Param( |
| name = "default_runfiles", |
| allowedTypes = { |
| @ParamType(type = RunfilesApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| DEPRECATED_RUNFILES_PARAMETER_WARNING |
| + "runfiles descriptor describing the runfiles this target needs to run " |
| + "when it is a dependency via any attribute other than the " |
| + "<code>data</code> attribute."), |
| @Param( |
| name = "executable", |
| allowedTypes = { |
| @ParamType(type = FileApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "If this rule is marked <a" |
| + " href='../globals/bzl.html#rule.executable'><code>executable</code></a> or" |
| + " <a href='../globals/bzl.html#rule.test'><code>test</code></a>, this is a" |
| + " <a href='../builtins/File.html'><code>File</code></a> object representing" |
| + " the file that should be executed to run the target. By default it is the" |
| + " predeclared output <code>ctx.outputs.executable</code> but it is" |
| + " recommended to pass another file (either predeclared or not) explicitly.") |
| }, |
| selfCall = true, |
| useStarlarkThread = true) |
| @StarlarkConstructor |
| DefaultInfoApi constructor( |
| Object files, |
| Object runfiles, |
| Object dataRunfiles, |
| Object defaultRunfiles, |
| Object executable, |
| StarlarkThread thread) |
| throws EvalException; |
| } |
| } |
