Add some docs on what rules and files are
--
MOS_MIGRATED_REVID=125449364
diff --git a/site/docs/skylark/index.md b/site/docs/skylark/index.md
index eadbc98..b72b218 100644
--- a/site/docs/skylark/index.md
+++ b/site/docs/skylark/index.md
@@ -4,10 +4,9 @@
---
# Custom rules
-Skylark is the name of the extension mechanism in Bazel. It lets you write
-[custom build rules](rules.md) as well as compose existing ones into
-[macros](macros.md).
-
+Skylark is the name of the extension mechanism in Bazel. It lets you add support
+for new languages and tools by writing [custom build rules](rules.md). You can
+also compose existing rules into [macros](macros.md).
## Getting started
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index 89caaf5..826c252 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -7,11 +7,31 @@
**Status: Experimental**. We may make breaking changes to the API, but we will
help you update your code.
+A rule defines a series of actions that Bazel should perform on inputs to get a
+set of outputs. For example, a C++ binary rule might take a set of .cpp
+files (the inputs), run `g++` on them (the action), and return an executable
+file (the output).
+
+Note that, from Bazel's perspective, `g++` and the standard C++ libraries are
+also inputs to this rule. As a rule writer, you must consider not only the
+user-provided inputs to a rule, but also all of the tools and libraries required
+to execute the actions (called _implicit inputs_).
+
## Rule creation
-In a Skylark extension, use the [rule](lib/globals.html#rule) function
-to create a new rule and store it in a global variable.
-[See example](cookbook.md#empty).
+In a Skylark extension (a .bzl file), use the [rule](lib/globals.html#rule)
+function to create a new rule and store it in a global variable:
+
+```python
+my_rule = rule(...)
+```
+
+See [the cookbook](cookbook.md#empty) for examples. The rule can then be
+loaded by BUILD files:
+
+```python
+load('//some/pkg:whatever.bzl', 'my_rule')
+```
A custom rule can be used just like a native rule. It has a mandatory `name`
attribute, you can refer to it with a label, and you can see it in
@@ -30,9 +50,9 @@
```python
sum = rule(
- implementation=impl,
- attrs={
- "number": attr.int(default=1),
+ implementation = impl,
+ attrs = {
+ "number": attr.int(default = 1),
"deps": attr.label_list(),
},
)
@@ -40,12 +60,16 @@
The following attributes are implicitly added to every rule: `deprecation`,
`features`, `name`, `tags`, `testonly`, `visibility`. Test rules also have the
-following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`.
+following attributes: `args`, `flaky`, `local`, `shard_count`, `size`,
+`timeout`.
-To access an attribute, use `ctx.attr.<attribute_name>`. The name and the
-package of a rule are available with `ctx.label.name` and `ctx.label.package`.
+Labels listed in `attr` will be inputs to the rule.
-[See example.](cookbook.md#attr)
+To access an attribute in a rule's implementation, use
+`ctx.attr.<attribute_name>`. The name and the package of a rule are available
+with `ctx.label.name` and `ctx.label.package`.
+
+See [an example](cookbook.md#attr) of using `attr` in a rule.
### <a name="private-attributes"></a> Private Attributes
@@ -152,7 +176,7 @@
output files come from the actual attribute values.
[See example](cookbook.md#outputs-custom)
-All output files must have exactly one generating action. See the
+Each output file must have exactly one generating action. See the
[library](lib/ctx.html#outputs) for more context.
## Default outputs
@@ -209,8 +233,9 @@
compilation fails.
**If an action generates an unknown number of outputs and you want to keep them
-all**, you may group them in a zip file. This way, you will be able to declare
-your output.
+all**, you must group them in a single file (e.g., a zip, tar, or other
+archive format). This way, you will be able to deterministically declare your
+outputs.
**If an action does not list a file it uses as an input**, the action execution
will most likely result in an error. The file is not guaranteed to be available
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 b3b8682..fe03f57 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
@@ -91,8 +91,14 @@
*/
@Immutable
@SkylarkModule(name = "File",
- doc = "This type represents a file used by the build system. It can be "
- + "either a source file or a derived file produced by a rule.")
+ doc = "<p>This type represents a file 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. If you have a Skylark rule that needs to create a new File, you might need to "
+ + "add the label to the attrs (if it's an input) or the outputs (if it's an output). Then "
+ + "you can access the File through the rule's <a href='ctx.html'>context</a>. You can "
+ + "also use <a href='ctx.html#new_file'>ctx.new_file</a> to create a new file in the rule "
+ + "implementation.</p>")
public class Artifact
implements FileType.HasFilename, ActionInput, SkylarkValue, Comparable<Object> {
