Tutorial about macro creation

RELNOTES: None.
PiperOrigin-RevId: 162736242

2 files changed, 83 insertions, 1 deletions

diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 671baa61a7..02478a7b29 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -111,7 +111,8 @@ nav: docs
                   Tutorials <span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="extensions-tutorials">
-                  <li><a href="/versions/{{ site.version }}/skylark/tutorial-sharing-variables.html">Sharing Variables</a></li>
+                  <li><a href="/versions/{{ site.version }}/skylark/tutorial-sharing-variables.html">Sharing variables</a></li>
+                  <li><a href="/versions/{{ site.version }}/skylark/tutorial-creating-a-macro.html">Creating a macro</a></li>
                   <li><a href="/versions/{{ site.version }}/skylark/cookbook.html">Examples</a></li>
                 </ul>
               </li>
diff --git a/site/docs/skylark/tutorial-creating-a-macro.md b/site/docs/skylark/tutorial-creating-a-macro.md
new file mode 100644
index 0000000000..44359907dd
--- /dev/null
+++ b/site/docs/skylark/tutorial-creating-a-macro.md
@@ -0,0 +1,81 @@
+---
+layout: documentation
+title: Creating a macro
+---
+
+# Creating a macro
+
+Let's suppose you need to run a tool as part of your build. For example, you
+may want to generate or preprocess a source file, or compress a binary. In this
+tutorial, we are going to resize an image.
+
+The easiest way is to use a `genrule`:
+
+``` python
+genrule(
+    name = "logo_miniature",
+    srcs = ["logo.png"],
+    outs = ["small_logo.png"],
+    cmd = "convert $< -resize 100x100 $@",
+)
+
+cc_binary(
+    name = "my_app",
+    srcs = ["my_app.cc"],
+    data = [":logo_miniature"],
+)
+```
+
+If you need to resize more images, you may want to reuse the code. To do that,
+we are going to define a function in a separate `.bzl` file. Let's call the file
+`miniature.bzl`:
+
+``` python
+def miniature(name, src, size="100x100", **kwargs):
+  """Create a miniature of the src image.
+
+  The generated file is prefixed with 'small_'.
+  """
+  native.genrule(
+    name = name,
+    srcs = [src],
+    outs = ["small_" + src],
+    cmd = "convert $< -resize 100x100 $@",
+    **kwargs
+  )
+```
+
+A few remarks:
+
+* By convention, macros have a `name` argument, just like rules.
+
+* We document the behavior of a macro by using a
+  [docstring](https://www.python.org/dev/peps/pep-0257/) like in Python.
+
+* To call a `genrule`, or any other native rule, use `native.`.
+
+* `**kwargs` is used to forward the extra arguments to the underlying `genrule`
+  (it works just like in [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)).
+  This is useful, so that a user can use standard attributes like `visibility`,
+  or `tags`.
+
+Now, you can use the macro from the `BUILD` file:
+
+``` python
+load("//path/to:miniature.bzl", "miniature")
+
+miniature(
+    name = "logo_miniature",
+    src = "image.png",
+)
+
+cc_binary(
+    name = "my_app",
+    srcs = ["my_app.cc"],
+    data = [":logo_miniature"],
+)
+```
+
+Macros are suitable for simple tasks. If you want to do anything more
+complicated, for example add support for a new programming language, consider
+creating a [rule](rules.md). Rules will give you more control and flexibility.