src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java - bazel - Git at Google

 // Copyright 2014 Google Inc. 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.packages.TestTimeout;
 import com.google.devtools.build.lib.rules.test.TestStrategy;
 import com.google.devtools.build.lib.rules.test.TestStrategy.TestOutputFormat;
 import com.google.devtools.build.lib.rules.test.TestStrategy.TestSummaryFormat;
 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 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;
   }
 }
	// Copyright 2014 Google Inc. 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.packages.TestTimeout;
	import com.google.devtools.build.lib.rules.test.TestStrategy;
	import com.google.devtools.build.lib.rules.test.TestStrategy.TestOutputFormat;
	import com.google.devtools.build.lib.rules.test.TestStrategy.TestSummaryFormat;
	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 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;
	}
	}