diff options
| -rw-r--r-- | site/_layouts/documentation.html | 13 | ||||
| -rw-r--r-- | site/docs/skylark/tutorial-sharing-variables.md | 87 |
2 files changed, 99 insertions, 1 deletions
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html index 16cbbe67bc..671baa61a7 100644 --- a/site/_layouts/documentation.html +++ b/site/_layouts/documentation.html @@ -106,6 +106,18 @@ nav: docs <li> <a class="sidebar-nav-heading" data-toggle="collapse" + href="#extensions-tutorials" aria-expanded="false" + aria-controls="extensions-tutorials"> + 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/cookbook.html">Examples</a></li> + </ul> + </li> + + <li> + <a class="sidebar-nav-heading" data-toggle="collapse" href="#extensions-concepts" aria-expanded="false" aria-controls="extensions-concepts"> Concepts <span class="caret"></span> @@ -126,7 +138,6 @@ nav: docs <li><a href="/versions/{{ site.version }}/skylark/build-style.html">Style guide for BUILD files</a></li> <li><a href="/versions/{{ site.version }}/skylark/bzl-style.html">Style guide for bzl files</a></li> - <li><a href="/versions/{{ site.version }}/skylark/cookbook.html">Examples</a></li> <li><a href="/versions/{{ site.version }}/skylark/lib/skylark-overview.html">Reference</a></li> <li><a href="/versions/{{ site.version }}/skylark/language.html">Language</a></li> </ul> diff --git a/site/docs/skylark/tutorial-sharing-variables.md b/site/docs/skylark/tutorial-sharing-variables.md new file mode 100644 index 0000000000..72f7304b99 --- /dev/null +++ b/site/docs/skylark/tutorial-sharing-variables.md @@ -0,0 +1,87 @@ +--- +layout: documentation +title: Sharing variables +--- + +# Sharing variables + +`BUILD` files are intended to be simple and declarative. They will typically +consist of a series of a target declarations. As your code base and your `BUILD` +files are getting larger, you will probably notice some duplication, e.g. + +``` python +cc_library( + name = "foo", + copts = ["-DVERSION=5"], + srcs = ["foo.cc"], +) + +cc_library( + name = "bar", + copts = ["-DVERSION=5"], + srcs = ["bar.cc"], + deps = [":foo"], +) +``` + +Code duplication in `BUILD` files is usually fine. This can make the file more +readable: each declaration can be read and understood without any context. This +is important, not only for humans, but also for external tools. For example, a +tool might be able to read and update `BUILD` files to add missing dependencies. +Code refactoring and code reuse might prevent this kind of automated +modification. + +With that in mind, it is possible to share values, if you still believe it would +be useful (e.g. values must be kept in sync). We can update the previous example +and introduce a variable: + +``` python +COPTS = ["-DVERSION=5"] + +cc_library( + name = "foo", + copts = [COPTS], + srcs = ["foo.cc"], +) + +cc_library( + name = "bar", + copts = [COPTS], + srcs = ["bar.cc"], + deps = [":foo"], +) +``` + +The value `COPTS` is now used by multiple declarations. By convention, we use +uppercase letters to name global constants. + +## Sharing variables across multiple BUILD files + +If you need to share a value across multiple `BUILD` files, you have to put it +in a `.bzl` file. `.bzl` files contain definitions (variables and functions) +that can be used in `BUILD` files. + +In `path/to/variables.bzl`, write: + +``` python +COPTS = ["-DVERSION=5"] +``` + +Then, you can update your `BUILD` files to access the variable: + +``` python +load("//path/to:variables.bzl", "COPTS") + +cc_library( + name = "foo", + copts = [COPTS], + srcs = ["foo.cc"], +) + +cc_library( + name = "bar", + copts = [COPTS], + srcs = ["bar.cc"], + deps = [":foo"], +) +``` |