diff options
author | 2018-02-26 07:20:00 -0800 | |
---|---|---|
committer | 2018-02-26 07:22:00 -0800 | |
commit | 4d1425910e757334d5f6c6ed9eb71916dc97fd6e (patch) | |
tree | 3c0b56783cde9c2d34ffb429767ec5a8b24cb531 /src/main/java/com/google/devtools | |
parent | af24688e4e0c8c359a2ec7af3fffaa1c825ef7ed (diff) |
Revamp rules.md documentation for files
Unified "Files" and "Output files" sections. Renamed "declared files" to "predeclared files" to avoid confusion with "declare_file()"/"declare_directory()".
RELNOTES: None
PiperOrigin-RevId: 187017607
Diffstat (limited to 'src/main/java/com/google/devtools')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/actions/Artifact.java | 18 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java | 19 |
2 files changed, 19 insertions, 18 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java index 85873b27a0..918c6b998c 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java +++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java @@ -101,16 +101,14 @@ import javax.annotation.Nullable; */ @Immutable @SkylarkModule( - name = "File", - category = SkylarkModuleCategory.BUILTIN, - doc = - "<p>This type represents a file or directory used by the build system. It can be " - + "either a source file or a derived file produced by a rule.</p>" - + "<p>The File constructor is private, so you cannot call it directly to create new " - + "Files. You typically get a File object from a " - + "<a href='Target.html'>Target</a>, or using " - + "<a href='actions.html#declare_file'>ctx.actions.declare_file</a>, " - + "or <a href='actions.html#declare_directory'>ctx.actions.declare_directory</a>." + name = "File", + category = SkylarkModuleCategory.BUILTIN, + doc = "This object is created during the analysis phase to represent a file or directory that " + + "will be read or written during the execution phase. It is not an open file handle, and " + + "cannot be used to directly read or write file contents. Rather, you use it to construct " + + "the action graph in a rule implementation function by passing it to action-creating " + + "functions. See the <a href='../rules.$DOC_EXT#files'>Rules page</a> for more " + + "information." ) @AutoCodec public class Artifact diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java index d991f493f4..e14bfc0046 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java @@ -103,14 +103,17 @@ public class SkylarkActionFactory implements SkylarkValue { @SkylarkCallable( name = "declare_file", doc = - "Declares that rule or aspect creates a file with the given filename. " - + "If <code>sibling</code> is not specified, file name is relative to " - + "package directory, otherwise the file is in the same directory as " - + "<code>sibling</code>. " - + "You must create an action that generates the file. <br>" - + "Files cannot be created outside of the current package. " - + "Files that are specified in rule's outputs do not need to be declared and are " - + "available through <a href=\"ctx.html#outputs\"><code>ctx.outputs</code></a>. " + "Declares that the rule or aspect creates a file with the given filename. " + + "If <code>sibling</code> is not specified, the file name is relative to the package" + + "directory, otherwise the file is in the same directory as <code>sibling</code>." + + "Files cannot be created outside of the current package." + + "<p>Remember that in addition to declaring a file, you must separately create an " + + "action that emits the file. Creating that action will require passing the returned " + + "<code>File</code> object to the action's construction function." + + "<p>Note that <a href='../rules.$DOC_EXT#files'>predeclared output files</a> do not " + + "need to be (and cannot be) declared using this function. You can obtain their " + + "<code>File</code> objects from <a href=\"ctx.html#outputs\"><code>ctx.outputs</code>" + + "</a> instead. " + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/" + "computed_dependencies/hash.bzl\">See example of use</a>", parameters = { |