CROSSTOOL docs: fix formatting errors
Closes #6974.
Change-Id: Idd8ad88f3ef8d09ac7901256aa66edc41fa62e68
PiperOrigin-RevId: 226307355
diff --git a/site/docs/crosstool-reference.md b/site/docs/crosstool-reference.md
index 0fadb74..223565f 100644
--- a/site/docs/crosstool-reference.md
+++ b/site/docs/crosstool-reference.md
@@ -156,7 +156,10 @@
</td>
</tr>
<tr>
- <td><code>requires: ['feature1', 'feature2']</code>
+ <td><pre>requires {
+ feature: 'feature-name-1'
+ feature: 'feature-name-2'
+}</pre>
</td>
<td>Feature-level. The feature is supported only if the specified required
features are enabled. For example, when a feature is only supported in
@@ -168,30 +171,31 @@
<tr>
<td><code>implies: 'feature'</code>
</td>
- <td>Feature-level. This feature implies the specified feature. For example, a
+ <td><p>Feature-level. This feature implies the specified feature. For example, a
module compile implies the need for module maps, which can be implemented
by a repeated <code>implies</code> string in the feature where each of
the strings names a specific feature. Enabling a feature also implicitly
- enables all features implied by it (that is, it functions recursively).
- <p>
- Also provides the ability to factor common subsets of functionality out of
- a set of features, such as the common parts of sanitizers. Implied
- features cannot be disabled.
+ enables all features implied by it (that is, it functions recursively).</p>
+ <p>Also provides the ability to factor common subsets of functionality out of
+ a set of features, such as the common parts of sanitizers. Implied
+ features cannot be disabled.</p>
</td>
</tr>
<tr>
<td><code>provides: 'feature'</code>
</td>
- <td>Feature-level. Indicates that this feature is one of several mutually
+ <td><p>Feature-level. Indicates that this feature is one of several mutually
exclusive alternate features. For example, all of the sanitizers could
- specify <code>provides: "sanitizer"</code>.
- <p>
- This improves error handling by listing the alternatives if the user asks
- for two or more mutually exclusive features at once.
+ specify <code>provides: "sanitizer"</code>.</p>
+ <p>This improves error handling by listing the alternatives if the user asks
+ for two or more mutually exclusive features at once.</p>
</td>
</tr>
<tr>
- <td><code>with_feature: {feature: 'feature1', not_feature: 'feature2']</code>
+ <td><pre>with_feature {
+ feature: 'feature-name-1'
+ not_feature: 'feature-name-2'
+}</pre>
</td>
<td>Flag set-level. A feature can specify multiple flag sets with multiple
<code>with_feature</code> statements. When <code>with_feature</code> is
@@ -478,69 +482,68 @@
With Bazel, this process can instead be implemented as follows, with
`unbundle-debuginfo` being a Bazel action:
-```
-toolchain {
- action_config {
- config_name: "c++-link-executable"
- action_name: "c++-link-executable"
- tool {
- with_feature { feature: "generate-debug-symbols" }
- tool_path: "toolchain/mac/ld-with-dsym-packaging"
+
+ toolchain {
+ action_config {
+ config_name: "c++-link-executable"
+ action_name: "c++-link-executable"
+ tool {
+ with_feature { feature: "generate-debug-symbols" }
+ tool_path: "toolchain/mac/ld-with-dsym-packaging"
+ }
+ tool {
+ tool_path: "toolchain/mac/ld"
+ }
}
- tool {
- tool_path: "toolchain/mac/ld"
+
+ feature {
+ name: "generate-debug-symbols"
+ flag_set {
+ action: "c-compile"
+ action: "c++-compile"
+ flag_group {
+ flag: "-g"
+ }
+ }
+ implies: "unbundle-debuginfo"
}
}
- feature {
- name: "generate-debug-symbols"
- flag_set {
- action: "c-compile"
- action: "c++-compile"
- flag_group {
- flag: "-g"
- }
- }
- implies: { feature: "unbundle-debuginfo" }
- }
-}
-```
This same feature can be implemented entirely differently for Linux, which uses
`fission`, or for Windows, which produces `.pdb` files. For example, the
implementation for `fission`-based debug symbol generation might look as
follows:
-```
-toolchain {
- action_config {
- name: "c++-compile"
- tool {
- tool_path: "toolchain/bin/gcc"
+ toolchain {
+ action_config {
+ name: "c++-compile"
+ tool {
+ tool_path: "toolchain/bin/gcc"
+ }
+ }
+
+ feature {
+ name: "generate-debug-symbols"
+ requires { feature: "dbg" }
+ flag_set {
+ action: "c++-compile"
+ flag_group {
+ flag: "-gsplit-dwarf"
+ }
+ }
+ flag_set {
+ action: "c++-link-executable"
+ flag_group {
+ flag: "-Wl"
+ flag: "--gdb-index"
+ }
+ }
+ }
}
}
- feature {
- name: "generate-debug-symbols"
- requires { feature: "dbg" }
- flag_set {
- action: "c++-compile"
- flag_group {
- flag: "-gsplit-dwarf"
- }
- }
- flag_set {
- action: "c++-link-executable"
- flag_group {
- flag: "-Wl"
- flag: "--gdb-index"
- }
- }
- }
- }
-}
-```
### Flag groups
@@ -549,11 +552,10 @@
within the flag value, which the compiler expands when adding the flag to the
build command. For example:
-```
- flag_group {
- flag: "%{output_file_path}
- }
-```
+ flag_group {
+ flag: "%{output_file_path}"
+ }
+
In this case, the contents of the flag will be replaced by the output file path
of the action.
@@ -565,65 +567,54 @@
command, the flag group can iterate variables of type `list`. For example, the
variable `include_path` of type `list`:
-```
- flag_group {
- iterate_over: "include_paths"
- flag: "-I%{include_paths}"
- }
-```
+ flag_group {
+ iterate_over: "include_paths"
+ flag: "-I%{include_paths}"
+ }
expands to `-I<path>` for each path element in the `include_paths` list. All
flags (or `flag_group`s) in the body of a flag group declaration are expanded as
a unit. For example:
-```
- flag_group {
- iterate_over: "include_paths"
- flag: "-I"
- flag: "%{include_paths}"
- }
-```
+ flag_group {
+ iterate_over: "include_paths"
+ flag: "-I"
+ flag: "%{include_paths}"
+ }
expands to `-I <path>` for each path element in the `include_paths` list.
A variable can repeat multiple times. For example:
-```
- flag_group {
- iterate_over: "include_paths"
- flag: "-iprefix=%{include_paths}"
- flag: "-isystem=%{include_paths}"
- }
-```
+ flag_group {
+ iterate_over: "include_paths"
+ flag: "-iprefix=%{include_paths}"
+ flag: "-isystem=%{include_paths}"
+ }
expands to:
-```
- -iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>
-```
+ -iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>
Variables can correspond to structures accessible using dot-notation. For
example:
-```
- flag_group {
- flag: "-l%{libraries_to_link.name}"
- }
-```
+ flag_group {
+ flag: "-l%{libraries_to_link.name}"
+ }
Structures can be nested and may also contain sequences. To prevent name clashes
and to be explicit, you must specify the full path through the fields. For
example:
-```
- flag_group {
- iterate_over: "libraries_to_link"
flag_group {
- iterate_over: "libraries_to_link.shared_libraries"
- flag: "-l%{libraries_to_link.shared_libraries.name}"
+ iterate_over: "libraries_to_link"
+ flag_group {
+ iterate_over: "libraries_to_link.shared_libraries"
+ flag: "-l%{libraries_to_link.shared_libraries.name}"
+ }
}
- }
-```
+
### Conditional expansion
@@ -631,25 +622,24 @@
variable or its field using the `expand_if_all_available`, `expand_if_none_available`,
`expand_if_true`, `expand_if_false`, or `expand_if_equal` messages. For example:
-```
- flag_group {
- iterate_over: "libraries_to_link"
+
flag_group {
- iterate_over: "libraries_to_link.shared_libraries"
- flag_group {
- expand_if_all_available: "libraries_to_link.shared_libraries.is_whole_archive"
- flag: "--whole_archive"
- }
- flag_group {
- flag: "-l%{libraries_to_link.shared_libraries.name}"
- }
- flag_group {
- expand_if_all_available: "libraries_to_link.shared_libraries.is_whole_archive"
- flag: "--no_whole_archive"
- }
+ iterate_over: "libraries_to_link"
+ flag_group {
+ iterate_over: "libraries_to_link.shared_libraries"
+ flag_group {
+ expand_if_all_available: "libraries_to_link.shared_libraries.is_whole_archive"
+ flag: "--whole_archive"
+ }
+ flag_group {
+ flag: "-l%{libraries_to_link.shared_libraries.name}"
+ }
+ flag_group {
+ expand_if_all_available: "libraries_to_link.shared_libraries.is_whole_archive"
+ flag: "--no_whole_archive"
+ }
+ }
}
- }
-```
**Note:** The `--whole_archive` and `--no_whole_archive` options are added to
the build command only when a currently iterated library has an
@@ -664,39 +654,43 @@
The following is a reference of `CROSSTOOL` build variables.
-**Note:** `[action]` indicates the relevant action type.
+**Note:** The **Action** column indicates the relevant action type, if applicable.
<table>
- <col width="300">
- <col width="600">
<tr>
<td><strong>Variable</strong>
</td>
+ <td><strong>Action</strong>
+ </td>
<td><strong>Description</strong>
</td>
</tr>
<tr>
<td><strong><code>source_file</code></strong>
</td>
- <td><code>[compile]</code> Source file to compile.
+ <td>compile</td>
+ <td>Source file to compile.
</td>
</tr>
<tr>
<td><strong><code>input_file</code></strong>
</td>
- <td><code>[strip]</code> Artifact to strip.
+ <td>strip</td>
+ <td>Artifact to strip.
</td>
</tr>
<tr>
<td><strong><code>output_file</code></strong>
</td>
- <td><code>[compile]</code> Compilation output.
+ <td>compile</td>
+ <td>Compilation output.
</td>
</tr>
<tr>
<td><strong><code>output_assembly_file</code></strong>
</td>
- <td><code>[compile]</code> Emitted assembly file. Applies only when the
+ <td>compile</td>
+ <td>Emitted assembly file. Applies only when the
<code>compile</code> action emits assembly text, typically when using the
<code>--save_temps</code> flag. The contents are the same as for
<code>output_file</code>.
@@ -705,7 +699,8 @@
<tr>
<td><strong><code>output_preprocess_file</code></strong>
</td>
- <td><code>[compile]</code> Preprocessed output. Applies only to compile
+ <td>compile</td>
+ <td>Preprocessed output. Applies only to compile
actions that only preprocess the source files, typically when using the
<code>--save_temps</code> flag. The contents are the same as for
<code>output_file</code>.
@@ -714,22 +709,25 @@
<tr>
<td><strong><code>includes</code></strong>
</td>
- <td><code>[compile]</code> Sequence of files the compiler must
+ <td>compile</td>
+ <td>Sequence of files the compiler must
unconditionally include in the compiled source.
</td>
</tr>
<tr>
<td><strong><code>include_paths</code></strong>
</td>
- <td><code>[compile]</code> Sequence directories in which the compiler
+ <td>compile</td>
+ <td>Sequence directories in which the compiler
searches for headers included using <code>#include<foo.h></code>
and <code>#include "foo.h"</code>.
</td>
</tr>
<tr>
<td><strong><code>quote_include_paths</code></strong>
+ <td>compile</td>
</td>
- <td><code>[compile]</code> Sequence of <code>-iquote</code> includes -
+ <td>Sequence of <code>-iquote</code> includes -
directories in which the compiler searches for headers included using
<code>#include<foo.h></code>.
</td>
@@ -737,7 +735,8 @@
<tr>
<td><strong><code>system_include_paths</code></strong>
</td>
- <td><code>[compile]</code> Sequence of <code>-isystem</code> includes -
+ <td>compile</td>
+ <td>Sequence of <code>-isystem</code> includes -
directories in which the compiler searches for headers included using
<code>#include "foo.h"</code>.
</td>
@@ -745,55 +744,60 @@
<tr>
<td><strong><code>dependency_file</code></strong>
</td>
- <td><code>[compile]</code> The <code>.d</code> dependency file generated by
- the compiler.
+ <td>compile</td>
+ <td>The <code>.d</code> dependency file generated by the compiler.
</td>
</tr>
<tr>
<td><strong><code>preprocessor_defines</code></strong>
</td>
- <td><code>[compile]</code> Sequence of <code>defines</code>, such as
- <code>--DDEBUG</code>.
+ <td>compile</td>
+ <td>Sequence of <code>defines</code>, such as <code>--DDEBUG</code>.
</td>
</tr>
<tr>
<td><strong><code>pic</code></strong>
</td>
- <td><code>[compile]</code> Compiles the output as position-independent code.
+ <td>compile</td>
+ <td>Compiles the output as position-independent code.
</td>
</tr>
<tr>
<td><strong><code>gcov_gcno_file</code></strong>
</td>
- <td><code>[compile]</code> The <code>gcov</code> coverage file.
+ <td>compile</td>
+ <td>The <code>gcov</code> coverage file.
</td>
</tr>
<tr>
<td><strong><code>per_object_debug_info_file</code></strong>
</td>
- <td><code>[compile]</code> The per-object debug info (<code>.dwp</code>)
- file.
+ <td>compile</td>
+ <td>The per-object debug info (<code>.dwp</code>) file.
</td>
</tr>
<tr>
<td><strong><code>stripotps</code></strong>
</td>
- <td><code>[strip]</code> Sequence of <code>stripopts</code>.
+ <td>strip</td>
+ <td>Sequence of <code>stripopts</code>.
</td>
</tr>
<tr>
<td><strong><code>legacy_compile_flags</code></strong>
</td>
- <td><code>[compile]</code> Sequence of flags from legacy
- <code>CROSSTOOL</code> fields such as <code>compiler_flag</code>,
- <code>optional_compiler_flag</code>, <code>cxx_flag</code>, and
- <code>optional_cxx_flag</code>.
+ <td>compile</td>
+ <td>Sequence of flags from legacy
+ <code>CROSSTOOL</code> fields such as <code>compiler_flag</code>,
+ <code>optional_compiler_flag</code>, <code>cxx_flag</code>, and
+ <code>optional_cxx_flag</code>.
</td>
</tr>
<tr>
<td><strong><code>user_compile_flags</code></strong>
</td>
- <td><code>[compile]</code> Sequence of flags from either the
+ <td>compile</td>
+ <td>Sequence of flags from either the
<code>copt</code> rule attribute or the <code>--copt</code>,
<code>--cxxopt</code>, and <code>--conlyopt</code> flags.
</td>
@@ -801,136 +805,151 @@
<tr>
<td><strong><code>unfiltered_compile_flags</code></strong>
</td>
- <td><code>[compile]</code> Sequence of flags from the
+ <td>compile</td>
+ <td>Sequence of flags from the
<code>unfiltered_cxx_flag</code> legacy <code>CROSSTOOL</code> field or the
- <code>unfiltered _compile_flags</code> feature. These are not filtered by
+ <code>unfiltered_compile_flags</code> feature. These are not filtered by
the <code>nocopts</code> rule attribute.
</td>
</tr>
<tr>
<td><strong><code>sysroot</code></strong>
</td>
+ <td></td>
<td>The <code>sysroot</code>.
</td>
</tr>
<tr>
<td><strong><code>runtime_library_search_directories</code></strong>
</td>
- <td><code>[link]</code> Entries in the linker runtime search path (usually
+ <td>link</td>
+ <td>Entries in the linker runtime search path (usually
set with the <code>-rpath</code> flag).
</td>
</tr>
<tr>
<td><strong><code>library_search_directories</code></strong>
</td>
- <td><code>[link]</code> Entries in the linker search path (usually set with
+ <td>link</td>
+ <td>Entries in the linker search path (usually set with
the <code>-L</code> flag).
</td>
</tr>
<tr>
<td><strong><code>libraries_to_link</code></strong>
</td>
- <td><code>[link]</code> Flags providing files to link as inputs in the linker
- invocation.
+ <td>link</td>
+ <td>Flags providing files to link as inputs in the linker invocation.
</td>
</tr>
<tr>
<td><strong><code>def_file_path</code></strong>
</td>
- <td><code>[link]</code> Location of def file used on Windows with MSVC.
+ <td>link</td>
+ <td>Location of def file used on Windows with MSVC.
</td>
</tr>
<tr>
<td><strong><code>linker_param_file</code></strong>
</td>
- <td><code>[link]</code> Location of linker param file created by bazel to
+ <td>link</td>
+ <td>Location of linker param file created by bazel to
overcome command line length limit.
</td>
</tr>
<tr>
<td><strong><code>output_execpath</code></strong>
</td>
- <td><code>[link]</code> execpath of the output of the linker.
+ <td>link</td>
+ <td>Execpath of the output of the linker.
</td>
</tr>
<tr>
<td><strong><code>generate_interface_library</code></strong>
</td>
- <td><code>[link]</code> "yes"|"no" depending on whether interface library
- should be generated.
+ <td>link</td>
+ <td><code>"yes"</code> or <code>"no"</code> depending on whether interface library should
+ be generated.
</td>
</tr>
<tr>
<td><strong><code>interface_library_builder_path</code></strong>
</td>
- <td><code>[link]</code> Path to the interface library builder tool.
+ <td>link</td>
+ <td>Path to the interface library builder tool.
</td>
</tr>
<tr>
<td><strong><code>interface_library_input_path</code></strong>
</td>
- <td><code>[link]</code> Input for the interface library <code>ifso</code>
- builder tool.
+ <td>link</td>
+ <td>Input for the interface library <code>ifso</code> builder tool.
</td>
</tr>
<tr>
<td><strong><code>interface_library_output_path</code></strong>
</td>
- <td><code>[link]</code> Path where to generate interface library using the
- <code>ifso</code> builder tool.
+ <td>link</td>
+ <td>Path where to generate interface library using the <code>ifso</code> builder tool.
</td>
</tr>
<tr>
<td><strong><code>legacy_link_flags</code></strong>
</td>
- <td><code>[link]</code> Linker flags coming from the legacy
- <code>CROSSTOOL</code>.
+ <td>link</td>
+ <td>Linker flags coming from the legacy <code>CROSSTOOL</code>.
</td>
</tr>
<tr>
<td><strong><code>user_link_flags</code></strong>
</td>
- <td><code>[link]</code> Linker flags coming from the <code>--linkopt</code>
+ <td>link</td>
+ <td>Linker flags coming from the <code>--linkopt</code>
or <code>linkopts</code> attribute.
</td>
</tr>
<tr>
<td><strong><code>symbol_counts_output</code></strong>
</td>
- <td><code>[link]</code> Path to which to write symbol counts.
+ <td>link</td>
+ <td>Path to which to write symbol counts.
</td>
</tr>
<tr>
<td><strong><code>linkstamp_paths</code></strong>
</td>
- <td><code>[link]</code> A build variable giving linkstamp paths.
+ <td>link</td>
+ <td>A build variable giving linkstamp paths.
</td>
</tr>
<tr>
<td><strong><code>force_pic</code></strong>
</td>
- <td><code>[link]</code> Presence of this variable indicates that PIC code
- should be generated.
+ <td>link</td>
+ <td>Presence of this variable indicates that PIC code should be generated.
</td>
</tr>
<tr>
<td><strong><code>strip_debug_symbols</code></strong>
</td>
- <td><code>[link]</code> Presence of this variable indicates that the debug
+ <td>link</td>
+ <td>Presence of this variable indicates that the debug
symbols should be stripped.
</td>
</tr>
<tr>
<td><strong><code>is_cc_test</code></strong>
</td>
- <td><code>[link]</code> Truthy when current action is a <code>cc_test</code>
+ <td>link</td>
+ <td>Truthy when current action is a <code>cc_test</code>
linking action, false otherwise.
</td>
</tr>
<tr>
<td><strong><code>is_using_fission</code></strong>
</td>
- <td><code>[link]</code> Presence of this variable indicates that files were
+ <td>link</td>
+ <td>Presence of this variable indicates that files were
compiled with fission. Debug info is in <code>.dwo</code> files instead
of <code>.o</code> files and the linker needs to know this.
</td>
@@ -981,7 +1000,7 @@
<td><strong><code>per_object_debug_info</code></strong>
</td>
<td>Enabled if the <code>supports_fission</code> attribute is set in the
- `CROSSTOOL` file and the current compilation mode is specified in the
+ <code>CROSSTOOL</code> file and the current compilation mode is specified in the
<code>--fission</code> flag.
</td>
</tr>
