Split out option usage restriction from option category.
These are two different concepts. Do not remove category overload compatibility in this CL, to keep this change limited to converting the current uses of category.
With some flyby formatting fixes on affected OptionsBases.
RELNOTES: None.
PiperOrigin-RevId: 153390002
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 c2b40c0..1b0bb10 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
@@ -22,6 +22,7 @@
import com.google.devtools.common.options.Option;
import com.google.devtools.common.options.Options;
import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
import java.util.Map;
/**
@@ -44,153 +45,189 @@
public static final ExecutionOptions DEFAULTS = Options.getDefaults(ExecutionOptions.class);
- @Option(name = "verbose_failures",
- defaultValue = "false",
- category = "verbosity",
- help = "If a command fails, print out the full command line.")
+ @Option(
+ name = "verbose_failures",
+ defaultValue = "false",
+ category = "verbosity",
+ help = "If a command fails, print out the full command line."
+ )
public boolean verboseFailures;
- @Option(name = "subcommands",
- abbrev = 's',
- defaultValue = "false",
- category = "verbosity",
- help = "Display the subcommands executed during a build.")
+ @Option(
+ name = "subcommands",
+ abbrev = 's',
+ defaultValue = "false",
+ category = "verbosity",
+ help = "Display the subcommands executed during a build."
+ )
public boolean showSubcommands;
- @Option(name = "check_up_to_date",
- defaultValue = "false",
- category = "what",
- 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.")
+ @Option(
+ name = "check_up_to_date",
+ defaultValue = "false",
+ category = "what",
+ 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",
- category = "testing",
- implicitRequirements = { "--check_up_to_date" },
- 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."
- )
+ @Option(
+ name = "check_tests_up_to_date",
+ defaultValue = "false",
+ category = "testing",
+ implicitRequirements = {"--check_up_to_date"},
+ 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 = "",
- category = "testing",
- help = "Specifies which strategy to use when running tests.")
+ @Option(
+ name = "test_strategy",
+ defaultValue = "",
+ category = "testing",
+ help = "Specifies which strategy to use when running tests."
+ )
public String testStrategy;
- @Option(name = "test_keep_going",
- defaultValue = "true",
- category = "testing",
- 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.")
+ @Option(
+ name = "test_keep_going",
+ defaultValue = "true",
+ category = "testing",
+ 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(name = "runs_per_test_detects_flakes",
- defaultValue = "false",
- category = "testing",
- help = "If true, any shard in which at least one run/attempt passes and at least one "
- + "run/attempt fails gets a FLAKY status.")
+ @Option(
+ name = "runs_per_test_detects_flakes",
+ defaultValue = "false",
+ category = "testing",
+ help =
+ "If true, any shard in which at least one run/attempt passes and at least one "
+ + "run/attempt fails gets a FLAKY status."
+ )
public boolean runsPerTestDetectsFlakes;
- @Option(name = "flaky_test_attempts",
- defaultValue = "default",
- category = "testing",
- converter = TestStrategy.TestAttemptsConverter.class,
- 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 would be marked as "
- + "'FLAKY' in the test summary. If this option is set, it should specify an int N or the "
- + "string 'default'. If it's an int, then all tests will be run up to N times. If it is "
- + "not specified or its value is 'default', then only a single test attempt will be made "
- + "for regular tests and three for tests marked explicitly as flaky by their rule "
- + "(flaky=1 attribute).")
+ @Option(
+ name = "flaky_test_attempts",
+ defaultValue = "default",
+ category = "testing",
+ converter = TestStrategy.TestAttemptsConverter.class,
+ 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 would be marked as "
+ + "'FLAKY' in the test summary. If this option is set, it should specify an int N or "
+ + "the string 'default'. If it's an int, then all tests will be run up to N times. "
+ + "If it is not specified or its value is 'default', then only a single test attempt "
+ + "will be made for regular tests and three for tests marked explicitly as flaky by "
+ + "their rule (flaky=1 attribute)."
+ )
public int testAttempts;
- @Option(name = "test_tmpdir",
- defaultValue = "null",
- category = "testing",
- converter = OptionsUtils.PathFragmentConverter.class,
- help = "Specifies the base temporary directory for 'blaze test' to use.")
+ @Option(
+ name = "test_tmpdir",
+ defaultValue = "null",
+ category = "testing",
+ converter = OptionsUtils.PathFragmentConverter.class,
+ help = "Specifies the base temporary directory for 'blaze test' to use."
+ )
public PathFragment testTmpDir;
- @Option(name = "test_output",
- defaultValue = "summary",
- category = "testing",
- converter = TestStrategy.TestOutputFormat.Converter.class,
- 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 for all tests and 'streamed' "
- + "to output logs for all tests in real time (this will force tests "
- + "to be executed locally one at a time regardless of --test_strategy "
- + "value).")
+ @Option(
+ name = "test_output",
+ defaultValue = "summary",
+ category = "testing",
+ converter = TestStrategy.TestOutputFormat.Converter.class,
+ 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 "
+ + "for all tests and 'streamed' to output logs for all tests in real time "
+ + "(this will force tests to be executed locally one at a time regardless of "
+ + "--test_strategy value)."
+ )
public TestOutputFormat testOutput;
- @Option(name = "test_summary",
- defaultValue = "short",
- category = "testing",
- converter = TestStrategy.TestSummaryFormat.Converter.class,
- 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 unsuccessful tests,"
- + "'detailed' to print detailed information about failed test cases, "
- + "and 'none' to omit the summary.")
+ @Option(
+ name = "test_summary",
+ defaultValue = "short",
+ category = "testing",
+ converter = TestStrategy.TestSummaryFormat.Converter.class,
+ 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 "
+ + "unsuccessful tests, 'detailed' to print detailed information about failed "
+ + "test cases, and 'none' to omit the summary."
+ )
public TestSummaryFormat testSummary;
- @Option(name = "test_timeout",
- defaultValue = "-1",
- category = "testing",
- converter = TestTimeout.TestTimeoutConverter.class,
- help = "Override the default test timeout values for test timeouts (in secs). If a single "
- + "positive integer value is specified it will override all categories. If 4 comma-"
- + "separated integers are specified, they will override the timeouts for short, "
- + "moderate, long and eternal (in that order). In either form, a value of -1 tells blaze "
- + "to use its default timeouts for that category.")
+ @Option(
+ name = "test_timeout",
+ defaultValue = "-1",
+ category = "testing",
+ converter = TestTimeout.TestTimeoutConverter.class,
+ help =
+ "Override the default test timeout values for test timeouts (in secs). If a single "
+ + "positive integer value is specified it will override all categories. If 4 "
+ + "comma-separated integers are specified, they will override the timeouts for short, "
+ + "moderate, long and eternal (in that order). In either form, a value of -1 tells "
+ + "blaze to use its default timeouts for that category."
+ )
public Map<TestTimeout, Integer> testTimeout;
- @Option(name = "resource_autosense",
- defaultValue = "false",
- category = "strategy",
- help = "This flag has no effect, and is deprecated")
+ @Option(
+ name = "resource_autosense",
+ defaultValue = "false",
+ category = "strategy",
+ help = "This flag has no effect, and is deprecated"
+ )
public boolean useResourceAutoSense;
- @Option(name = "ram_utilization_factor",
- defaultValue = "67",
- category = "strategy",
- help = "Specify what percentage of the system's RAM Blaze should try to use for its "
- + "subprocesses. "
- + "This option affects how many processes Blaze will try to run in parallel. "
- + "If you run several Blaze builds in parallel, using a lower value for "
- + "this option may avoid thrashing and thus improve overall throughput. "
- + "Using a value higher than the default is NOT recommended. "
- + "Note that Blaze's estimates are very coarse, so the actual RAM usage may be much "
- + "higher or much lower than specified. "
- + "Note also that this option does not affect the amount of memory that the Blaze "
- + "server itself will use. "
- )
+ @Option(
+ name = "ram_utilization_factor",
+ defaultValue = "67",
+ category = "strategy",
+ help =
+ "Specify what percentage of the system's RAM Blaze should try to use for its subprocesses. "
+ + "This option affects how many processes Blaze will try to run in parallel. "
+ + "If you run several Blaze builds in parallel, using a lower value for "
+ + "this option may avoid thrashing and thus improve overall throughput. "
+ + "Using a value higher than the default is NOT recommended. "
+ + "Note that Blaze's estimates are very coarse, so the actual RAM usage may be much "
+ + "higher or much lower than specified. "
+ + "Note also that this option does not affect the amount of memory that the Blaze "
+ + "server itself will use. "
+ )
public int ramUtilizationPercentage;
- @Option(name = "local_resources",
- defaultValue = "null",
- category = "strategy",
- help = "Explicitly set amount of local resources available to Blaze. "
- + "By default, Blaze will query system configuration to estimate amount of RAM (in MB) "
- + "and number of CPU cores available for the locally executed build actions. It would also "
- + "assume default I/O capabilities of the local workstation (1.0). This options allows to "
- + "explicitly set all 3 values. Note, that if this option is used, Blaze will ignore "
- + "--ram_utilization_factor.",
- converter = ResourceSet.ResourceSetConverter.class
- )
+ @Option(
+ name = "local_resources",
+ defaultValue = "null",
+ category = "strategy",
+ help =
+ "Explicitly set amount of local resources available to Blaze. "
+ + "By default, Blaze will query system configuration to estimate amount of RAM (in MB) "
+ + "and number of CPU cores available for the locally executed build actions. It would "
+ + "also assume default I/O capabilities of the local workstation (1.0). This options "
+ + "allows to explicitly set all 3 values. Note, that if this option is used, Blaze "
+ + "will ignore --ram_utilization_factor.",
+ converter = ResourceSet.ResourceSetConverter.class
+ )
public ResourceSet availableResources;
- @Option(name = "local_test_jobs",
- defaultValue = "0",
- category = "testing",
- help = "The max number of local test jobs to run concurrently. "
- + "0 means local resources will limit the number of local test jobs to run "
- + "concurrently instead. Setting this greater than the value for --jobs is ineffectual."
+ @Option(
+ name = "local_test_jobs",
+ defaultValue = "0",
+ category = "testing",
+ help =
+ "The max number of local test jobs to run concurrently. "
+ + "0 means local resources will limit the number of local test jobs to run "
+ + "concurrently instead. Setting this greater than the value for --jobs is ineffectual."
)
public int localTestJobs;
@@ -201,7 +238,7 @@
@Option(
name = "debug_print_action_contexts",
defaultValue = "false",
- category = "undocumented",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
help = "Print the contents of the SpawnActionContext and ContextProviders maps."
)
public boolean debugPrintActionContexts;
@@ -209,7 +246,7 @@
@Option(
name = "cache_computed_file_digests",
defaultValue = "50000",
- category = "undocumented",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
help =
"If greater than 0, configures Blaze to cache file digests in memory based on their "
+ "metadata instead of recomputing the digests from disk every time they are needed. "
@@ -219,11 +256,10 @@
)
public long cacheSizeForComputedFileDigests;
-
@Option(
name = "experimental_enable_critical_path_profiling",
defaultValue = "true",
- category = "undocumented",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
help =
"If set (the default), critical path profiling is enabled for the execution phase. "
+ "This has a slight overhead in RAM and CPU, and may prevent Bazel from making certain"
