diff --git a/docs/concepts/build-files.mdx b/docs/concepts/build-files.mdx index c3476684fcd670..33087dc4557d0f 100644 --- a/docs/concepts/build-files.mdx +++ b/docs/concepts/build-files.mdx @@ -2,6 +2,8 @@ title: 'BUILD files' --- + + The previous sections described packages, targets and labels, and the build dependency graph abstractly. This section describes the concrete syntax used to define a package. @@ -48,7 +50,7 @@ team. `BUILD` file authors should comment liberally to document the role of each build target, whether or not it is intended for public use, and to document the role of the package itself. -## Loading an extension {:#load} +## Loading an extension Bazel extensions are files ending in `.bzl`. Use the `load` statement to import a symbol from an extension. @@ -90,7 +92,7 @@ loaded from another file. You can use [load visibility](/concepts/visibility#load-visibility) to restrict who may load a `.bzl` file. -## Types of build rules {:#types-of-build-rules} +## Types of build rules The majority of build rules come in families, grouped together by language. For example, `cc_binary`, `cc_library` diff --git a/docs/concepts/dependencies.mdx b/docs/concepts/dependencies.mdx index 148a63adfb58fd..d3fcb71e6bb9eb 100644 --- a/docs/concepts/dependencies.mdx +++ b/docs/concepts/dependencies.mdx @@ -2,9 +2,11 @@ title: 'Dependencies' --- + + A target `A` _depends upon_ a target `B` if `B` is needed by `A` at build or execution time. The _depends upon_ relation induces a -[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph){: .external} +[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) over targets, and it is called a _dependency graph_. A target's _direct_ dependencies are those other targets reachable by a path @@ -16,7 +18,7 @@ of _actual dependencies_ and the graph of _declared dependencies_. Most of the time, the two graphs are so similar that this distinction need not be made, but it is useful for the discussion below. -## Actual and declared dependencies {:#actual-and-declared-dependencies} +## Actual and declared dependencies A target `X` is _actually dependent_ on target `Y` if `Y` must be present, built, and up-to-date in order for `X` to be built correctly. _Built_ could @@ -57,7 +59,7 @@ dependencies don't appear in the `BUILD` file. Because the rule doesn't directly depend on the provider, there is no way to track changes, as shown in the following example timeline: -### 1. Declared dependencies match actual dependencies {:#this-is-fine} +### 1. Declared dependencies match actual dependencies At first, everything works. The code in package `a` uses code in package `b`. The code in package `b` uses code in package `c`, and thus `a` transitively @@ -127,7 +129,7 @@ function foo() { The declared dependencies overapproximate the actual dependencies. All is well. -### 2. Adding an undeclared dependency {:#undeclared-dependency} +### 2. Adding an undeclared dependency A latent hazard is introduced when someone adds code to `a` that creates a direct _actual_ dependency on `c`, but forgets to declare it in the build file @@ -173,7 +175,7 @@ The declared dependencies no longer overapproximate the actual dependencies. This may build ok, because the transitive closures of the two graphs are equal, but masks a problem: `a` has an actual but undeclared dependency on `c`. -### 3. Divergence between declared and actual dependency graphs {:#divergence} +### 3. Divergence between declared and actual dependency graphs The hazard is revealed when someone refactors `b` so that it no longer depends on `c`, inadvertently breaking `a` through no @@ -236,7 +238,7 @@ dependencies, even when transitively closed; the build is likely to fail. The problem could have been averted by ensuring that the actual dependency from `a` to `c` introduced in Step 2 was properly declared in the `BUILD` file. -## Types of dependencies {:#types-of-dependencies} +## Types of dependencies Most build rules have three attributes for specifying different kinds of generic dependencies: `srcs`, `deps` and `data`. These are explained below. For @@ -247,16 +249,16 @@ Many rules also have additional attributes for rule-specific kinds of dependencies, for example, `compiler` or `resources`. These are detailed in the [Build Encyclopedia](/reference/be/). -### `srcs` dependencies {:#srcs-dependencies} +### `srcs` dependencies Files consumed directly by the rule or rules that output source files. -### `deps` dependencies {:#deps-dependencies} +### `deps` dependencies Rule pointing to separately-compiled modules providing header files, symbols, libraries, data, etc. -### `data` dependencies {:#data-dependencies} +### `data` dependencies A build target might need some data files to run correctly. These data files aren't source code: they don't affect how the target is built. For example, a @@ -293,7 +295,7 @@ you can refer to these files by joining the paths of the test's source directory and the workspace-relative path, for example, `${TEST_SRCDIR}/workspace/path/to/data/file`. -## Using labels to reference directories {:#using-labels-reference-directories} +## Using labels to reference directories As you look over our `BUILD` files, you might notice that some `data` labels refer to directories. These labels end with `/.` or `/` like these examples, diff --git a/docs/concepts/labels.mdx b/docs/concepts/labels.mdx index 24f782b30f6165..caf82faf79fc9b 100644 --- a/docs/concepts/labels.mdx +++ b/docs/concepts/labels.mdx @@ -2,6 +2,8 @@ title: 'Labels' --- + + A **label** is an identifier for a target. A typical label in its full canonical form looks like: @@ -115,7 +117,7 @@ used from external repositories. For information about the different ways you can refer to targets, see [target patterns](/run/build#specifying-build-targets). -### Lexical specification of a label {:#labels-lexical-specification} +### Lexical specification of a label Label syntax discourages use of metacharacters that have special meaning to the shell. This helps to avoid inadvertent quoting problems, and makes it easier to @@ -124,7 +126,7 @@ construct tools and scripts that manipulate labels, such as the The precise details of allowed target names are below. -### Target names — `{{ "" }}package-name{{ "" }}:target-name` {:#target-names} +### Target names — `{{ "" }}package-name{{ "" }}:target-name` `target-name` is the name of the target within the package. The name of a rule is the value of the `name` attribute in the rule's declaration in a `BUILD` @@ -155,7 +157,7 @@ However, there are some situations where use of a slash is convenient, or sometimes even necessary. For example, the name of certain rules must match their principal source file, which may reside in a subdirectory of the package. -### Package names — `//package-name:{{ "" }}target-name{{ "" }}` {:#package-names} +### Package names — `//package-name:{{ "" }}target-name{{ "" }}` The name of a package is the name of the directory containing its `BUILD` file, relative to the top-level directory of the containing repository. @@ -186,7 +188,7 @@ On a practical level: `//:foo`), it's best to leave that package empty so all meaningful packages have descriptive names. -## Rules {:#rules} +## Rules A rule specifies the relationship between inputs and outputs, and the steps to build the outputs. Rules can be of one of many different diff --git a/docs/contribute/docs-style-guide.mdx b/docs/contribute/docs-style-guide.mdx index c7dfb766d41c12..f50c9eb67bf6e6 100644 --- a/docs/contribute/docs-style-guide.mdx +++ b/docs/contribute/docs-style-guide.mdx @@ -2,12 +2,14 @@ title: 'Bazel docs style guide' --- + + Thank you for contributing to Bazel's documentation. This serves as a quick documentation style guide to get you started. For any style questions not answered by this guide, follow the -[Google developer documentation style guide](https://developers.google.com/style){: .external}. +[Google developer documentation style guide](https://developers.google.com/style). -## Defining principles {:#principles} +## Defining principles Bazel docs should uphold these principles: @@ -19,11 +21,11 @@ Bazel docs should uphold these principles: - **Correct.** Write in a way where the content stays correct for as long as possible by avoiding time-based information and promises for the future. -## Writing {:#writing-tips} +## Writing This section contains basic writing tips. -### Headings {:#headings} +### Headings - Page-level headings start at H2. (H1 headings are used as page titles.) - Make headers as short as is sensible. This way, they fit in the TOC @@ -43,7 +45,7 @@ This section contains basic writing tips. - Yes: Preserving graph order - No: On the preservation of graph order -### Names {:#names} +### Names - Capitalize proper nouns, such as Bazel and Starlark. @@ -57,7 +59,7 @@ This section contains basic writing tips. - For example, if you're writing about issuing commands on a terminal, don't use both terminal and command line on the page. -### Page scope {:#page-scope} +### Page scope - Each page should have one purpose and that should be defined at the beginning. This helps readers find what they need quicker. @@ -69,7 +71,7 @@ This section contains basic writing tips. there is no clear action, you can include links to similar concepts, examples, or other avenues for exploration. -### Subject {:#subject} +### Subject In Bazel documentation, the audience should primarily be users—the people using Bazel to build their software. @@ -92,7 +94,7 @@ Bazel to build their software. - No: Bazel is evolving, and we will make changes to Bazel that at times will be incompatible and require some changes from Bazel users. -### Temporal {:#temporal} +### Temporal Where possible, avoid terms that orient things in time, such as referencing specific dates (Q2 2022) or saying "now", "currently", or "soon." These go @@ -105,7 +107,7 @@ specify a version level instead, such as "Bazel X.x and higher supports - No: Bazel will soon support remote caching, likely in October 2017. -### Tense {:#tense} +### Tense - Use present tense. Avoid past or future tense unless absolutely necessary for clarity. @@ -123,7 +125,7 @@ specify a version level instead, such as "Bazel X.x and higher supports - No: X is initiated by Bazel and then afterward Y will be built with the output. -### Tone {:#tone} +### Tone Write with a business friendly tone. @@ -135,18 +137,18 @@ Write with a business friendly tone. - Avoid overly formal language. Write as though you're explaining the concept to someone who is curious about tech, but doesn't know the details. -## Formatting {:#format} +## Formatting -### File type {:#file-type} +### File type For readability, wrap lines at 80 characters. Long links or code snippets may be longer, but should start on a new line. For example: Note: Where possible, use Markdown instead of HTML in your files. Follow the -[GitHub Markdown Syntax Guide](https://guides.github.com/features/mastering-markdown/#syntax){: .external} +[GitHub Markdown Syntax Guide](https://guides.github.com/features/mastering-markdown/#syntax) for recommended Markdown style. -### Links {:#links} +### Links - Use descriptive link text instead of "here" or "below". This practice makes it easier to scan a doc and is better for screen readers. @@ -157,7 +159,7 @@ for recommended Markdown style. - Yes: For more details, see [link]. - No: See [link] for more information. -### Lists {:#lists} +### Lists - Use an ordered list to describe how to accomplish a task with steps - Use an unordered list to list things that aren't task based. (There should @@ -167,7 +169,7 @@ for recommended Markdown style. 1. Start with verbs that are the same tense. 1. Use an ordered list if there are steps to follow. -### Placeholders {:#placeholders} +### Placeholders - Use angle brackets to denote a variable that users should change. In Markdown, escape the angle brackets with a back slash: `\`. @@ -179,11 +181,11 @@ for recommended Markdown style. - Especially for complicated code samples, use placeholders that make sense in context. -### Table of contents {:#toc} +### Table of contents Use the auto-generated TOC supported by the site. Don't add a manual TOC. -## Code {:#code} +## Code Code samples are developers' best friends. You probably know how to write these already, but here are a few tips. @@ -192,7 +194,7 @@ If you're referencing a small snippet of code, you can embed it in a sentence. If you want the reader to use the code, such as copying a command, use a code block. -### Code blocks {:#code-blocks} +### Code blocks - Keep it short. Eliminate all redundant or unnecessary text from a code sample. @@ -205,7 +207,7 @@ block. - Separate commands and output into different code blocks. -### Inline code formatting {:#code-format} +### Inline code formatting - Use code style for filenames, directories, paths, and small bits of code. - Use inline code styling instead of _italics_, "quotes," or **bolding**.