// Copyright 2014 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.exec;
import com.google.devtools.build.lib.actions.ResourceSet;
import com.google.devtools.build.lib.exec.TestStrategy.TestOutputFormat;
import com.google.devtools.build.lib.exec.TestStrategy.TestSummaryFormat;
import com.google.devtools.build.lib.packages.TestTimeout;
import com.google.devtools.build.lib.util.OptionsUtils;
import com.google.devtools.build.lib.vfs.PathFragment;
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;
/**
* Options affecting the execution phase of a build.
*
* These options are interpreted by the BuildTool to choose an Executor to
* be used for the build.
*
* Note: from the user's point of view, the characteristic function of this
* set of options is indistinguishable from that of the BuildRequestOptions:
* they are all per-request. The difference is only apparent in the
* implementation: these options are used only by the lib.exec machinery, which
* affects how C++ and Java compilation occur. (The BuildRequestOptions
* contain a mixture of "semantic" options affecting the choice of targets to
* build, and "non-semantic" options affecting the lib.actions machinery.)
* Ideally, the user would be unaware of the difference. For now, the usage
* strings are identical modulo "part 1", "part 2".
*/
public class ExecutionOptions extends OptionsBase {
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."
)
public boolean verboseFailures;
@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."
)
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."
)
public boolean testCheckUpToDate;
@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."
)
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."
)
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)."
)
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."
)
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)."
)
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."
)
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."
)
public Map<TestTimeout, Integer> testTimeout;
@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. "
)
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
)
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."
)
public int localTestJobs;
public boolean usingLocalTestJobs() {
return localTestJobs != 0;
}
@Option(
name = "debug_print_action_contexts",
defaultValue = "false",
optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
help = "Print the contents of the SpawnActionContext and ContextProviders maps."
)
public boolean debugPrintActionContexts;
@Option(
name = "cache_computed_file_digests",
defaultValue = "50000",
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. "
+ "Setting this to 0 ensures correctness because not all file changes can be noted "
+ "from file metadata. When not 0, the number indicates the size of the cache as the "
+ "number of file digests to be cached."
)
public long cacheSizeForComputedFileDigests;
@Option(
name = "experimental_enable_critical_path_profiling",
defaultValue = "true",
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"
+ " aggressive RAM optimizations in some cases."
)
public boolean enableCriticalPathProfiling;
}