Categorize and apply effect tags on test and strategy flags.
Fixes https://github.com/bazelbuild/bazel/issues/5149
RELNOTES:
PiperOrigin-RevId: 308320450
diff --git a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
index 33161d1..5d98641 100644
--- a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
@@ -63,8 +63,8 @@
name = "spawn_strategy",
defaultValue = "",
converter = CommaSeparatedNonEmptyOptionListConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"Specify how spawn actions are executed by default. Accepts a comma-separated list of"
+ " strategies from highest to lowest priority. For each action Bazel picks the"
@@ -77,8 +77,8 @@
name = "genrule_strategy",
defaultValue = "",
converter = CommaSeparatedNonEmptyOptionListConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"Specify how to execute genrules. This flag will be phased out. Instead, use "
+ "--spawn_strategy=<value> to control all actions or --strategy=Genrule=<value> "
@@ -90,8 +90,8 @@
allowMultiple = true,
converter = Converters.StringToStringListConverter.class,
defaultValue = "null",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"Specify how to distribute compilation of other spawn actions. Accepts a comma-separated"
+ " list of strategies from highest to lowest priority. For each action Bazel picks"
@@ -104,8 +104,8 @@
name = "strategy_regexp",
allowMultiple = true,
converter = RegexFilterAssignmentConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+ effectTags = {OptionEffectTag.EXECUTION},
defaultValue = "null",
help =
"Override which spawn strategy should be used to execute spawn actions that have "
@@ -123,8 +123,8 @@
@Option(
name = "materialize_param_files",
defaultValue = "false",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"Writes intermediate parameter files to output tree even when using "
+ "remote action execution. Useful when debugging actions. "
@@ -134,8 +134,8 @@
@Option(
name = "experimental_materialize_param_files_directly",
defaultValue = "false",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {OptionEffectTag.EXECUTION},
help = "If materializing param files, do so with direct writes to disk.")
public boolean materializeParamFilesDirectly;
@@ -147,69 +147,63 @@
}
@Option(
- name = "verbose_failures",
- defaultValue = "false",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help = "If a command fails, print out the full command line."
- )
+ name = "verbose_failures",
+ defaultValue = "false",
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {OptionEffectTag.TERMINAL_OUTPUT},
+ help = "If a command fails, print out the full command line.")
public boolean verboseFailures;
@Option(
- name = "subcommands",
- abbrev = 's',
- defaultValue = "false",
- converter = ShowSubcommandsConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help = "Display the subcommands executed during a build."
- )
+ name = "subcommands",
+ abbrev = 's',
+ defaultValue = "false",
+ converter = ShowSubcommandsConverter.class,
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {OptionEffectTag.TERMINAL_OUTPUT},
+ help = "Display the subcommands executed during a build.")
public ShowSubcommands showSubcommands;
@Option(
- name = "check_up_to_date",
- defaultValue = "false",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help =
- "Don't perform the build, just check if it is up-to-date. If all targets are "
- + "up-to-date, the build completes successfully. If any step needs to be executed "
- + "an error is reported and the build fails."
- )
+ name = "check_up_to_date",
+ defaultValue = "false",
+ documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+ effectTags = {OptionEffectTag.EXECUTION},
+ help =
+ "Don't perform the build, just check if it is up-to-date. If all targets are "
+ + "up-to-date, the build completes successfully. If any step needs to be executed "
+ + "an error is reported and the build fails.")
public boolean checkUpToDate;
@Option(
- name = "check_tests_up_to_date",
- defaultValue = "false",
- implicitRequirements = {"--check_up_to_date"},
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help =
- "Don't run tests, just check if they are up-to-date. If all tests results are "
- + "up-to-date, the testing completes successfully. If any test needs to be built or "
- + "executed, an error is reported and the testing fails. This option implies "
- + "--check_up_to_date behavior."
- )
+ name = "check_tests_up_to_date",
+ defaultValue = "false",
+ implicitRequirements = {"--check_up_to_date"},
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.EXECUTION},
+ help =
+ "Don't run tests, just check if they are up-to-date. If all tests results are "
+ + "up-to-date, the testing completes successfully. If any test needs to be built or "
+ + "executed, an error is reported and the testing fails. This option implies "
+ + "--check_up_to_date behavior.")
public boolean testCheckUpToDate;
@Option(
- name = "test_strategy",
- defaultValue = "",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help = "Specifies which strategy to use when running tests."
- )
+ name = "test_strategy",
+ defaultValue = "",
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.EXECUTION},
+ help = "Specifies which strategy to use when running tests.")
public String testStrategy;
@Option(
- name = "test_keep_going",
- defaultValue = "true",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help =
- "When disabled, any non-passing test will cause the entire build to stop. By default "
- + "all tests are run, even if some do not pass."
- )
+ name = "test_keep_going",
+ defaultValue = "true",
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.EXECUTION},
+ help =
+ "When disabled, any non-passing test will cause the entire build to stop. By default "
+ + "all tests are run, even if some do not pass.")
public boolean testKeepGoing;
@Option(
@@ -217,8 +211,8 @@
allowMultiple = true,
defaultValue = "default",
converter = TestAttemptsConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"Each test will be retried up to the specified number of times in case of any test"
+ " failure. Tests that required more than one attempt to pass are marked as 'FLAKY'"
@@ -239,7 +233,7 @@
name = "test_tmpdir",
defaultValue = "null",
converter = OptionsUtils.PathFragmentConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+ documentationCategory = OptionDocumentationCategory.TESTING,
effectTags = {OptionEffectTag.UNKNOWN},
help = "Specifies the base temporary directory for 'bazel test' to use.")
public PathFragment testTmpDir;
@@ -248,8 +242,12 @@
name = "test_output",
defaultValue = "summary",
converter = TestOutputFormat.Converter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {
+ OptionEffectTag.TEST_RUNNER,
+ OptionEffectTag.TERMINAL_OUTPUT,
+ OptionEffectTag.EXECUTION
+ },
help =
"Specifies desired output mode. Valid values are 'summary' to output only test status "
+ "summary, 'errors' to also print test logs for failed tests, 'all' to print logs "
@@ -262,8 +260,8 @@
name = "test_summary",
defaultValue = "short",
converter = TestSummaryFormat.Converter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.LOGGING,
+ effectTags = {OptionEffectTag.TERMINAL_OUTPUT},
help =
"Specifies the desired format ot the test summary. Valid values are 'short' to print "
+ "information only about tests executed, 'terse', to print information only about "
@@ -272,12 +270,11 @@
public TestSummaryFormat testSummary;
@Option(
- name = "resource_autosense",
- defaultValue = "false",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help = "This flag has no effect, and is deprecated"
- )
+ name = "resource_autosense",
+ defaultValue = "false",
+ documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
+ effectTags = {OptionEffectTag.UNKNOWN},
+ help = "This flag has no effect, and is deprecated")
public boolean useResourceAutoSense;
@Option(
@@ -357,8 +354,8 @@
@Option(
name = "local_test_jobs",
defaultValue = "auto",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.EXECUTION},
help =
"The max number of local test jobs to run concurrently. "
+ "Takes "
