diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib')
23 files changed, 2222 insertions, 1635 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java b/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java index 036e7473b1..5d56cf31d4 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java @@ -95,6 +95,7 @@ import com.google.devtools.build.skyframe.WalkableGraph; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import java.util.ArrayList; import java.util.Collection; @@ -156,9 +157,9 @@ import javax.annotation.Nullable; public class BuildView { /** - * Options that affect the <i>mechanism</i> of analysis. These are distinct from {@link - * com.google.devtools.build.lib.analysis.config.BuildOptions}, which affect the <i>value</i> - * of a BuildConfiguration. + * Options that affect the <i>mechanism</i> of analysis. These are distinct from {@link + * com.google.devtools.build.lib.analysis.config.BuildOptions}, which affect the <i>value</i> of a + * BuildConfiguration. */ public static class Options extends OptionsBase { @Option( @@ -170,42 +171,54 @@ public class BuildView { ) public int loadingPhaseThreads; - @Option(name = "keep_going", - abbrev = 'k', - defaultValue = "false", - category = "strategy", - help = "Continue as much as possible after an error. While the" - + " target that failed, and those that depend on it, cannot be" - + " analyzed (or built), the other prerequisites of these" - + " targets can be analyzed (or built) all the same.") + @Option( + name = "keep_going", + abbrev = 'k', + defaultValue = "false", + category = "strategy", + help = + "Continue as much as possible after an error. While the target that failed, and those " + + "that depend on it, cannot be analyzed (or built), the other prerequisites of " + + "these targets can be analyzed (or built) all the same." + ) public boolean keepGoing; - @Option(name = "analysis_warnings_as_errors", - deprecationWarning = "analysis_warnings_as_errors is now a no-op and will be removed in" - + " an upcoming Blaze release", - defaultValue = "false", - category = "strategy", - help = "Treat visible analysis warnings as errors.") + @Option( + name = "analysis_warnings_as_errors", + deprecationWarning = + "analysis_warnings_as_errors is now a no-op and will be removed in" + + " an upcoming Blaze release", + defaultValue = "false", + category = "strategy", + help = "Treat visible analysis warnings as errors." + ) public boolean analysisWarningsAsErrors; - @Option(name = "discard_analysis_cache", - defaultValue = "false", - category = "strategy", - help = "Discard the analysis cache immediately after the analysis phase completes." - + " Reduces memory usage by ~10%, but makes further incremental builds slower.") + @Option( + name = "discard_analysis_cache", + defaultValue = "false", + category = "strategy", + help = + "Discard the analysis cache immediately after the analysis phase completes." + + " Reduces memory usage by ~10%, but makes further incremental builds slower." + ) public boolean discardAnalysisCache; - @Option(name = "experimental_extra_action_filter", - defaultValue = "", - category = "experimental", - converter = RegexFilter.RegexFilterConverter.class, - help = "Filters set of targets to schedule extra_actions for.") + @Option( + name = "experimental_extra_action_filter", + defaultValue = "", + category = "experimental", + converter = RegexFilter.RegexFilterConverter.class, + help = "Filters set of targets to schedule extra_actions for." + ) public RegexFilter extraActionFilter; - @Option(name = "experimental_extra_action_top_level_only", - defaultValue = "false", - category = "experimental", - help = "Only schedules extra_actions for top level targets.") + @Option( + name = "experimental_extra_action_top_level_only", + defaultValue = "false", + category = "experimental", + help = "Only schedules extra_actions for top level targets." + ) public boolean extraActionTopLevelOnly; @Option( @@ -220,12 +233,15 @@ public class BuildView { ) public boolean extraActionTopLevelOnlyWithAspects; - @Option(name = "version_window_for_dirty_node_gc", - defaultValue = "0", - category = "undocumented", - help = "Nodes that have been dirty for more than this many versions will be deleted" - + " from the graph upon the next update. Values must be non-negative long integers," - + " or -1 indicating the maximum possible window.") + @Option( + name = "version_window_for_dirty_node_gc", + defaultValue = "0", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Nodes that have been dirty for more than this many versions will be deleted" + + " from the graph upon the next update. Values must be non-negative long integers," + + " or -1 indicating the maximum possible window." + ) public long versionWindowForDirtyNodeGc; @Deprecated diff --git a/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java b/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java index 21d3d38730..b02bf3b4af 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java @@ -29,6 +29,7 @@ import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.build.lib.vfs.PathFragment; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.io.IOException; import java.util.HashMap; import java.util.List; @@ -55,29 +56,34 @@ public abstract class WorkspaceStatusAction extends AbstractAction { * Options controlling the workspace status command. */ public static class Options extends OptionsBase { - @Option(name = "embed_label", - defaultValue = "", - category = "misc", - valueHelp = "<string>", - help = "Embed source control revision or release label in binary") + @Option( + name = "embed_label", + defaultValue = "", + category = "misc", + valueHelp = "<string>", + help = "Embed source control revision or release label in binary" + ) public String embedLabel; @Option( name = "experimental_embed_timestamp_epoch", defaultValue = "-1", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Alternative timestamp to be used in stamping the binary" ) public long embedTimestampEpoch; - @Option(name = "workspace_status_command", - defaultValue = "", - category = "misc", - converter = OptionsUtils.PathFragmentConverter.class, - valueHelp = "<path>", - help = "A command invoked at the beginning of the build to provide status " - + "information about the workspace in the form of key/value pairs. " - + "See the User's Manual for the full specification.") + @Option( + name = "workspace_status_command", + defaultValue = "", + category = "misc", + converter = OptionsUtils.PathFragmentConverter.class, + valueHelp = "<path>", + help = + "A command invoked at the beginning of the build to provide status " + + "information about the workspace in the form of key/value pairs. " + + "See the User's Manual for the full specification." + ) public PathFragment workspaceStatusCommand; } diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java index c38cfc2e5e..8c733c5db1 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java @@ -75,6 +75,7 @@ import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import com.google.devtools.common.options.TriState; import java.util.ArrayList; @@ -479,123 +480,153 @@ public final class BuildConfiguration { */ public static class Options extends FragmentOptions implements Cloneable { @Option( - name = "define", - converter = Converters.AssignmentConverter.class, - defaultValue = "", - category = "semantics", - allowMultiple = true, - help = "Each --define option specifies an assignment for a build variable." + name = "define", + converter = Converters.AssignmentConverter.class, + defaultValue = "", + category = "semantics", + allowMultiple = true, + help = "Each --define option specifies an assignment for a build variable." ) public List<Map.Entry<String, String>> commandLineBuildVariables; - @Option(name = "cpu", - defaultValue = "", - category = "semantics", - converter = AutoCpuConverter.class, - help = "The target CPU.") + @Option( + name = "cpu", + defaultValue = "", + category = "semantics", + converter = AutoCpuConverter.class, + help = "The target CPU." + ) public String cpu; /** * Allows a configuration to record if --experimental_multi_cpu was used to set a cpu value. - * This is necessary to ensure that a configuration transition that sets cpu does not erase - * the difference between a pair of configurations created by --experimental_multi_cpu, leading - * to a crash when the configurations are treated as the same. + * This is necessary to ensure that a configuration transition that sets cpu does not erase the + * difference between a pair of configurations created by --experimental_multi_cpu, leading to a + * crash when the configurations are treated as the same. * * <p>TODO(b/33780512): Remove once dynamic configurations are used. */ - @Option(name = "experimental multi cpu distinguisher", - defaultValue = "", - category = "internal") + @Option( + name = "experimental multi cpu distinguisher", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL + ) public String experimentalMultiCpuDistinguisher; - @Option(name = "min_param_file_size", - defaultValue = "32768", - category = "undocumented", - help = "Minimum command line length before creating a parameter file.") + @Option( + name = "min_param_file_size", + defaultValue = "32768", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Minimum command line length before creating a parameter file." + ) public int minParamFileSize; - @Option(name = "experimental_extended_sanity_checks", - defaultValue = "false", - category = "undocumented", - help = "Enables internal validation checks to make sure that configured target " - + "implementations only access things they should. Causes a performance hit.") + @Option( + name = "experimental_extended_sanity_checks", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Enables internal validation checks to make sure that configured target " + + "implementations only access things they should. Causes a performance hit." + ) public boolean extendedSanityChecks; - @Option(name = "experimental_allow_runtime_deps_on_neverlink", - defaultValue = "true", - category = "undocumented", - help = "Flag to help transition from allowing to disallowing runtime_deps on neverlink" - + " Java archives. The depot needs to be cleaned up to roll this out by default.") + @Option( + name = "experimental_allow_runtime_deps_on_neverlink", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Flag to help transition from allowing to disallowing runtime_deps on neverlink" + + " Java archives. The depot needs to be cleaned up to roll this out by default." + ) public boolean allowRuntimeDepsOnNeverLink; - @Option(name = "strict_filesets", - defaultValue = "false", - category = "semantics", - help = "If this option is enabled, filesets crossing package boundaries are reported " - + "as errors. It does not work when check_fileset_dependencies_recursively is " - + "disabled.") + @Option( + name = "strict_filesets", + defaultValue = "false", + category = "semantics", + help = + "If this option is enabled, filesets crossing package boundaries are reported " + + "as errors. It does not work when check_fileset_dependencies_recursively is " + + "disabled." + ) public boolean strictFilesets; // Plugins are build using the host config. To avoid cycles we just don't propagate // this option to the host config. If one day we decide to use plugins when building // host tools, we can improve this by (for example) creating a compiler configuration that is // used only for building plugins. - @Option(name = "plugin", - converter = LabelConverter.class, - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Plugins to use in the build. Currently works with java_plugin.") + @Option( + name = "plugin", + converter = LabelConverter.class, + allowMultiple = true, + defaultValue = "", + category = "flags", + help = "Plugins to use in the build. Currently works with java_plugin." + ) public List<Label> pluginList; - @Option(name = "plugin_copt", - converter = PluginOptionConverter.class, - allowMultiple = true, - category = "flags", - defaultValue = ":", - help = "Plugin options") + @Option( + name = "plugin_copt", + converter = PluginOptionConverter.class, + allowMultiple = true, + category = "flags", + defaultValue = ":", + help = "Plugin options" + ) public List<Map.Entry<String, String>> pluginCoptList; - @Option(name = "stamp", - defaultValue = "false", - category = "semantics", - help = "Stamp binaries with the date, username, hostname, workspace information, etc.") + @Option( + name = "stamp", + defaultValue = "false", + category = "semantics", + help = "Stamp binaries with the date, username, hostname, workspace information, etc." + ) public boolean stampBinaries; // This default value is always overwritten in the case of "bazel coverage" by // CoverageCommand.setDefaultInstrumentationFilter(). - @Option(name = "instrumentation_filter", - converter = RegexFilter.RegexFilterConverter.class, - defaultValue = "-/javatests[/:]", - category = "semantics", - help = "When coverage is enabled, only rules with names included by the " - + "specified regex-based filter will be instrumented. Rules prefixed " - + "with '-' are excluded instead. Note that only non-test rules are " - + "instrumented unless --instrument_test_targets is enabled.") + @Option( + name = "instrumentation_filter", + converter = RegexFilter.RegexFilterConverter.class, + defaultValue = "-/javatests[/:]", + category = "semantics", + help = + "When coverage is enabled, only rules with names included by the " + + "specified regex-based filter will be instrumented. Rules prefixed " + + "with '-' are excluded instead. Note that only non-test rules are " + + "instrumented unless --instrument_test_targets is enabled." + ) public RegexFilter instrumentationFilter; - @Option(name = "instrument_test_targets", - defaultValue = "false", - category = "semantics", - help = "When coverage is enabled, specifies whether to consider instrumenting test rules. " - + "When set, test rules included by --instrumentation_filter are instrumented. " - + "Otherwise, test rules are always excluded from coverage instrumentation.") + @Option( + name = "instrument_test_targets", + defaultValue = "false", + category = "semantics", + help = + "When coverage is enabled, specifies whether to consider instrumenting test rules. " + + "When set, test rules included by --instrumentation_filter are instrumented. " + + "Otherwise, test rules are always excluded from coverage instrumentation." + ) public boolean instrumentTestTargets; - @Option(name = "host_cpu", - defaultValue = "", - category = "semantics", - converter = AutoCpuConverter.class, - help = "The host CPU.") + @Option( + name = "host_cpu", + defaultValue = "", + category = "semantics", + converter = AutoCpuConverter.class, + help = "The host CPU." + ) public String hostCpu; - @Option(name = "compilation_mode", - abbrev = 'c', - converter = CompilationMode.Converter.class, - defaultValue = "fastbuild", - category = "semantics", // Should this be "flags"? - help = "Specify the mode the binary will be built in. " - + "Values: 'fastbuild', 'dbg', 'opt'.") + @Option( + name = "compilation_mode", + abbrev = 'c', + converter = CompilationMode.Converter.class, + defaultValue = "fastbuild", + category = "semantics", // Should this be "flags"? + help = "Specify the mode the binary will be built in. " + "Values: 'fastbuild', 'dbg', 'opt'." + ) public CompilationMode compilationMode; /** @@ -603,31 +634,37 @@ public final class BuildConfiguration { * to a constant, so that the output files for the host are completely independent of those for * the target, no matter what options are in force (k8/piii, opt/dbg, etc). */ - @Option(name = "output directory name", - defaultValue = "null", - category = "internal") + @Option( + name = "output directory name", + defaultValue = "null", + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL + ) public String outputDirectoryName; - @Option(name = "platform_suffix", - defaultValue = "null", - category = "misc", - help = "Specifies a suffix to be added to the configuration directory.") + @Option( + name = "platform_suffix", + defaultValue = "null", + category = "misc", + help = "Specifies a suffix to be added to the configuration directory." + ) public String platformSuffix; // TODO(bazel-team): The test environment is actually computed in BlazeRuntime and this option // is not read anywhere else. Thus, it should be in a different options class, preferably one // specific to the "test" command or maybe in its own configuration fragment. // BlazeRuntime, though. - @Option(name = "test_env", - converter = Converters.OptionalAssignmentConverter.class, - allowMultiple = true, - defaultValue = "", - category = "testing", - help = "Specifies additional environment variables to be injected into the test runner " - + "environment. Variables can be either specified by name, in which case its value " - + "will be read from the Bazel client environment, or by the name=value pair. " - + "This option can be used multiple times to specify several variables. " - + "Used only by the 'bazel test' command." + @Option( + name = "test_env", + converter = Converters.OptionalAssignmentConverter.class, + allowMultiple = true, + defaultValue = "", + category = "testing", + help = + "Specifies additional environment variables to be injected into the test runner " + + "environment. Variables can be either specified by name, in which case its value " + + "will be read from the Bazel client environment, or by the name=value pair. " + + "This option can be used multiple times to specify several variables. " + + "Used only by the 'bazel test' command." ) public List<Map.Entry<String, String>> testEnvironment; @@ -650,226 +687,273 @@ public final class BuildConfiguration { ) public List<Map.Entry<String, String>> actionEnvironment; - @Option(name = "collect_code_coverage", - defaultValue = "false", - category = "testing", - help = "If specified, Bazel will instrument code (using offline instrumentation where " - + "possible) and will collect coverage information during tests. Only targets that " - + " match --instrumentation_filter will be affected. Usually this option should " - + " not be specified directly - 'bazel coverage' command should be used instead." + @Option( + name = "collect_code_coverage", + defaultValue = "false", + category = "testing", + help = + "If specified, Bazel will instrument code (using offline instrumentation where " + + "possible) and will collect coverage information during tests. Only targets that " + + " match --instrumentation_filter will be affected. Usually this option should " + + " not be specified directly - 'bazel coverage' command should be used instead." ) public boolean collectCodeCoverage; - @Option(name = "microcoverage", - defaultValue = "false", - category = "testing", - help = "If specified with coverage, Blaze will collect microcoverage (per test method " - + "coverage) information during tests. Only targets that match " - + "--instrumentation_filter will be affected. Usually this option should not be " - + "specified directly - 'blaze coverage --microcoverage' command should be used " - + "instead." + @Option( + name = "microcoverage", + defaultValue = "false", + category = "testing", + help = + "If specified with coverage, Blaze will collect microcoverage (per test method " + + "coverage) information during tests. Only targets that match " + + "--instrumentation_filter will be affected. Usually this option should not be " + + "specified directly - 'blaze coverage --microcoverage' command should be used " + + "instead." ) public boolean collectMicroCoverage; - @Option(name = "coverage_support", - converter = LabelConverter.class, - defaultValue = "@bazel_tools//tools/test:coverage_support", - category = "testing", - help = "Location of support files that are required on the inputs of every test action " - + "that collects code coverage. Defaults to '//tools/test:coverage_support'.") + @Option( + name = "coverage_support", + converter = LabelConverter.class, + defaultValue = "@bazel_tools//tools/test:coverage_support", + category = "testing", + help = + "Location of support files that are required on the inputs of every test action " + + "that collects code coverage. Defaults to '//tools/test:coverage_support'." + ) public Label coverageSupport; - @Option(name = "coverage_report_generator", - converter = LabelConverter.class, - defaultValue = "@bazel_tools//tools/test:coverage_report_generator", - category = "testing", - help = "Location of the binary that is used to generate coverage reports. This must " - + "currently be a filegroup that contains a single file, the binary. Defaults to " - + "'//tools/test:coverage_report_generator'.") + @Option( + name = "coverage_report_generator", + converter = LabelConverter.class, + defaultValue = "@bazel_tools//tools/test:coverage_report_generator", + category = "testing", + help = + "Location of the binary that is used to generate coverage reports. This must " + + "currently be a filegroup that contains a single file, the binary. Defaults to " + + "'//tools/test:coverage_report_generator'." + ) public Label coverageReportGenerator; - @Option(name = "experimental_use_llvm_covmap", - defaultValue = "false", - category = "experimental", - help = "If specified, Bazel will generate llvm-cov coverage map information rather than " - + "gcov when collect_code_coverage is enabled." + @Option( + name = "experimental_use_llvm_covmap", + defaultValue = "false", + category = "experimental", + help = + "If specified, Bazel will generate llvm-cov coverage map information rather than " + + "gcov when collect_code_coverage is enabled." ) public boolean useLLVMCoverageMapFormat; - @Option(name = "cache_test_results", - defaultValue = "auto", - category = "testing", - abbrev = 't', // it's useful to toggle this on/off quickly - help = "If 'auto', Bazel will only rerun a test if any of the following conditions apply: " - + "(1) Bazel detects changes in the test or its dependencies " - + "(2) the test is marked as external " - + "(3) multiple test runs were requested with --runs_per_test " - + "(4) the test failed " - + "If 'yes', the caching behavior will be the same as 'auto' except that " - + "it may cache test failures and test runs with --runs_per_test. " - + "If 'no', all tests will be always executed.") + @Option( + name = "cache_test_results", + defaultValue = "auto", + category = "testing", + abbrev = 't', // it's useful to toggle this on/off quickly + help = + "If 'auto', Bazel will only rerun a test if any of the following conditions apply: " + + "(1) Bazel detects changes in the test or its dependencies " + + "(2) the test is marked as external " + + "(3) multiple test runs were requested with --runs_per_test " + + "(4) the test failed " + + "If 'yes', the caching behavior will be the same as 'auto' except that " + + "it may cache test failures and test runs with --runs_per_test. " + + "If 'no', all tests will be always executed." + ) public TriState cacheTestResults; @Deprecated - @Option(name = "test_result_expiration", - defaultValue = "-1", // No expiration by defualt. - category = "testing", - help = "This option is deprecated and has no effect.") + @Option( + name = "test_result_expiration", + defaultValue = "-1", // No expiration by defualt. + category = "testing", + help = "This option is deprecated and has no effect." + ) public int testResultExpiration; - @Option(name = "test_sharding_strategy", - defaultValue = "explicit", - category = "testing", - converter = TestActionBuilder.ShardingStrategyConverter.class, - help = "Specify strategy for test sharding: " - + "'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. " - + "'disabled' to never use test sharding. " - + "'experimental_heuristic' to enable sharding on remotely executed tests without an " - + "explicit 'shard_count' attribute which link in a supported framework. Considered " - + "experimental.") + @Option( + name = "test_sharding_strategy", + defaultValue = "explicit", + category = "testing", + converter = TestActionBuilder.ShardingStrategyConverter.class, + help = + "Specify strategy for test sharding: " + + "'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. " + + "'disabled' to never use test sharding. " + + "'experimental_heuristic' to enable sharding on remotely executed tests without an " + + "explicit 'shard_count' attribute which link in a supported framework. Considered " + + "experimental." + ) public TestActionBuilder.TestShardingStrategy testShardingStrategy; - @Option(name = "runs_per_test", - allowMultiple = true, - defaultValue = "1", - category = "testing", - converter = RunsPerTestConverter.class, - help = "Specifies number of times to run each test. If any of those attempts " - + "fail for any reason, the whole test would be considered failed. " - + "Normally the value specified is just an integer. Example: --runs_per_test=3 " - + "will run all tests 3 times. " - + "Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for " - + "an integer value and regex_filter stands " - + "for a list of include and exclude regular expression patterns (Also see " - + "--instrumentation_filter). Example: " - + "--runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ " - + "except those under foo/bar three times. " - + "This option can be passed multiple times. ") + @Option( + name = "runs_per_test", + allowMultiple = true, + defaultValue = "1", + category = "testing", + converter = RunsPerTestConverter.class, + help = + "Specifies number of times to run each test. If any of those attempts " + + "fail for any reason, the whole test would be considered failed. " + + "Normally the value specified is just an integer. Example: --runs_per_test=3 " + + "will run all tests 3 times. " + + "Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for " + + "an integer value and regex_filter stands " + + "for a list of include and exclude regular expression patterns (Also see " + + "--instrumentation_filter). Example: " + + "--runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ " + + "except those under foo/bar three times. " + + "This option can be passed multiple times. " + ) public List<PerLabelOptions> runsPerTest; - @Option(name = "build_runfile_links", - defaultValue = "true", - category = "strategy", - help = "If true, build runfiles symlink forests for all targets. " - + "If false, write only manifests when possible.") + @Option( + name = "build_runfile_links", + defaultValue = "true", + category = "strategy", + help = + "If true, build runfiles symlink forests for all targets. " + + "If false, write only manifests when possible." + ) public boolean buildRunfiles; - @Option(name = "legacy_external_runfiles", - defaultValue = "true", - category = "strategy", - help = "If true, build runfiles symlink forests for external repositories under " - + ".runfiles/wsname/external/repo (in addition to .runfiles/repo).") + @Option( + name = "legacy_external_runfiles", + defaultValue = "true", + category = "strategy", + help = + "If true, build runfiles symlink forests for external repositories under " + + ".runfiles/wsname/external/repo (in addition to .runfiles/repo)." + ) public boolean legacyExternalRunfiles; - @Option(name = "test_arg", - allowMultiple = true, - defaultValue = "", - category = "testing", - help = "Specifies additional options and arguments that should be passed to the test " - + "executable. Can be used multiple times to specify several arguments. " - + "If multiple tests are executed, each of them will receive identical arguments. " - + "Used only by the 'bazel test' command." + @Option( + name = "test_arg", + allowMultiple = true, + defaultValue = "", + category = "testing", + help = + "Specifies additional options and arguments that should be passed to the test " + + "executable. Can be used multiple times to specify several arguments. " + + "If multiple tests are executed, each of them will receive identical arguments. " + + "Used only by the 'bazel test' command." ) public List<String> testArguments; - @Option(name = "test_filter", - allowMultiple = false, - defaultValue = "null", - category = "testing", - help = "Specifies a filter to forward to the test framework. Used to limit " - + "the tests run. Note that this does not affect which targets are built.") + @Option( + name = "test_filter", + allowMultiple = false, + defaultValue = "null", + category = "testing", + help = + "Specifies a filter to forward to the test framework. Used to limit " + + "the tests run. Note that this does not affect which targets are built." + ) public String testFilter; - @Option(name = "check_fileset_dependencies_recursively", - defaultValue = "true", - category = "semantics", - help = "If false, fileset targets will, whenever possible, create " - + "symlinks to directories instead of creating one symlink for each " - + "file inside the directory. Disabling this will significantly " - + "speed up fileset builds, but targets that depend on filesets will " - + "not be rebuilt if files are added, removed or modified in a " - + "subdirectory which has not been traversed.") + @Option( + name = "check_fileset_dependencies_recursively", + defaultValue = "true", + category = "semantics", + help = + "If false, fileset targets will, whenever possible, create " + + "symlinks to directories instead of creating one symlink for each " + + "file inside the directory. Disabling this will significantly " + + "speed up fileset builds, but targets that depend on filesets will " + + "not be rebuilt if files are added, removed or modified in a " + + "subdirectory which has not been traversed." + ) public boolean checkFilesetDependenciesRecursively; @Option( - name = "experimental_skyframe_native_filesets", - defaultValue = "false", - category = "experimental", - help = - "If true, Blaze will use the skyframe-native implementation of the Fileset rule." - + " This offers improved performance in incremental builds of Filesets as well as" - + " correct incremental behavior, but is not yet stable. The default is false," - + " meaning Blaze uses the legacy impelementation of Fileset." + name = "experimental_skyframe_native_filesets", + defaultValue = "false", + category = "experimental", + help = + "If true, Blaze will use the skyframe-native implementation of the Fileset rule." + + " This offers improved performance in incremental builds of Filesets as well as" + + " correct incremental behavior, but is not yet stable. The default is false," + + " meaning Blaze uses the legacy impelementation of Fileset." ) public boolean skyframeNativeFileset; @Option( - name = "run_under", - category = "run", - defaultValue = "null", - converter = RunUnderConverter.class, - help = - "Prefix to insert in front of command before running. " - + "Examples:\n" - + "\t--run_under=valgrind\n" - + "\t--run_under=strace\n" - + "\t--run_under='strace -c'\n" - + "\t--run_under='valgrind --quiet --num-callers=20'\n" - + "\t--run_under=//package:target\n" - + "\t--run_under='//package:target --options'\n" + name = "run_under", + category = "run", + defaultValue = "null", + converter = RunUnderConverter.class, + help = + "Prefix to insert in front of command before running. " + + "Examples:\n" + + "\t--run_under=valgrind\n" + + "\t--run_under=strace\n" + + "\t--run_under='strace -c'\n" + + "\t--run_under='valgrind --quiet --num-callers=20'\n" + + "\t--run_under=//package:target\n" + + "\t--run_under='//package:target --options'\n" ) public RunUnder runUnder; - @Option(name = "distinct_host_configuration", - defaultValue = "true", - category = "strategy", - help = "Build all the tools used during the build for a distinct configuration from " - + "that used for the target program. When this is disabled, the same configuration " - + "is used for host and target programs. This may cause undesirable rebuilds of tools " - + "such as the protocol compiler (and then everything downstream) whenever a minor " - + "change is made to the target configuration, such as setting the linker options. " - + "When this enabled (the default), a distinct configuration will be used to build the " - + "tools, preventing undesired rebuilds. However, certain libraries will then " - + "need to be compiled twice, once for each configuration, which may cause some " - + "builds to be slower. As a rule of thumb, this option is likely to benefit " - + "users that make frequent changes in configuration (e.g. opt/dbg). " - + "Please read the user manual for the full explanation.") + @Option( + name = "distinct_host_configuration", + defaultValue = "true", + category = "strategy", + help = + "Build all the tools used during the build for a distinct configuration from that used " + + "for the target program. When this is disabled, the same configuration is used for " + + "host and target programs. This may cause undesirable rebuilds of tools such as " + + "the protocol compiler (and then everything downstream) whenever a minor change " + + "is made to the target configuration, such as setting the linker options. When " + + "this is enabled (the default), a distinct configuration will be used to build the " + + "tools, preventing undesired rebuilds. However, certain libraries will then need " + + "to be compiled twice, once for each configuration, which may cause some builds " + + "to be slower. As a rule of thumb, this option is likely to benefit users that " + + "make frequent changes in configuration (e.g. opt/dbg). " + + "Please read the user manual for the full explanation." + ) public boolean useDistinctHostConfiguration; - @Option(name = "check_visibility", - defaultValue = "true", - category = "checking", - help = "If disabled, visibility errors are demoted to warnings.") + @Option( + name = "check_visibility", + defaultValue = "true", + category = "checking", + help = "If disabled, visibility errors are demoted to warnings." + ) public boolean checkVisibility; // Moved from viewOptions to here because license information is very expensive to serialize. // Having it here allows us to skip computation of transitive license information completely // when the setting is disabled. - @Option(name = "check_licenses", - defaultValue = "false", - category = "checking", - help = "Check that licensing constraints imposed by dependent packages " - + "do not conflict with distribution modes of the targets being built. " - + "By default, licenses are not checked.") + @Option( + name = "check_licenses", + defaultValue = "false", + category = "checking", + help = + "Check that licensing constraints imposed by dependent packages " + + "do not conflict with distribution modes of the targets being built. " + + "By default, licenses are not checked." + ) public boolean checkLicenses; @Option( - name = "enforce_constraints", - defaultValue = "true", - category = "undocumented", - help = - "Checks the environments each target is compatible with and reports errors if any " - + "target has dependencies that don't support the same environments", - oldName = "experimental_enforce_constraints" + name = "enforce_constraints", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Checks the environments each target is compatible with and reports errors if any " + + "target has dependencies that don't support the same environments", + oldName = "experimental_enforce_constraints" ) public boolean enforceConstraints; - @Option(name = "experimental_action_listener", - allowMultiple = true, - defaultValue = "", - category = "experimental", - converter = LabelConverter.class, - help = "Use action_listener to attach an extra_action to existing build actions.") + @Option( + name = "experimental_action_listener", + allowMultiple = true, + defaultValue = "", + category = "experimental", + converter = LabelConverter.class, + help = "Use action_listener to attach an extra_action to existing build actions." + ) public List<Label> actionListeners; // TODO(bazel-team): Either remove this flag once transparent compression is shown to not @@ -878,38 +962,45 @@ public final class BuildConfiguration { @Option( name = "experimental_transparent_compression", defaultValue = "true", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Enables gzip compression for the contents of FileWriteActions, which reduces " + "memory usage in the analysis phase at the expense of additional time overhead." ) public boolean transparentCompression; - @Option(name = "is host configuration", - defaultValue = "false", - category = "internal", - help = "Shows whether these options are set for host configuration.") + @Option( + name = "is host configuration", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, + help = "Shows whether these options are set for host configuration." + ) public boolean isHost; - @Option(name = "features", - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "The given features will be enabled or disabled by default for all packages. " - + "Specifying -<feature> will disable the feature globally. " - + "Negative features always override positive ones. " - + "This flag is used to enable rolling out default feature changes without a " - + "Blaze release.") + @Option( + name = "features", + allowMultiple = true, + defaultValue = "", + category = "flags", + help = + "The given features will be enabled or disabled by default for all packages. " + + "Specifying -<feature> will disable the feature globally. " + + "Negative features always override positive ones. " + + "This flag is used to enable rolling out default feature changes without a " + + "Blaze release." + ) public List<String> defaultFeatures; - @Option(name = "target_environment", - converter = LabelConverter.class, - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Declares this build's target environment. Must be a label reference to an " - + "\"environment\" rule. If specified, all top-level targets must be " - + "compatible with this environment." + @Option( + name = "target_environment", + converter = LabelConverter.class, + allowMultiple = true, + defaultValue = "", + category = "flags", + help = + "Declares this build's target environment. Must be a label reference to an " + + "\"environment\" rule. If specified, all top-level targets must be " + + "compatible with this environment." ) public List<Label> targetEnvironments; @@ -941,27 +1032,30 @@ public final class BuildConfiguration { } } - @Option(name = "experimental_dynamic_configs", - defaultValue = "notrim_partial", - category = "undocumented", - converter = DynamicConfigsConverter.class, - help = "Dynamically instantiates build configurations instead of using the default " - + "static globally defined ones") + @Option( + name = "experimental_dynamic_configs", + defaultValue = "notrim_partial", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = DynamicConfigsConverter.class, + help = + "Dynamically instantiates build configurations instead of using the default " + + "static globally defined ones" + ) public DynamicConfigsMode useDynamicConfigurations; @Option( - name = "experimental_enable_runfiles", - defaultValue = "auto", - category = "undocumented", - help = "Enable runfiles; off on Windows, on on other platforms" + name = "experimental_enable_runfiles", + defaultValue = "auto", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Enable runfiles; off on Windows, on on other platforms" ) public TriState enableRunfiles; @Option( - name = "build_python_zip", - defaultValue = "auto", - category = "undocumented", - help = "Build python executable zip; on on Windows, off on other platforms" + name = "build_python_zip", + defaultValue = "auto", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Build python executable zip; on on Windows, off on other platforms" ) public TriState buildPythonZip; diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java index 84b1fa251e..3fdf939f4c 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java @@ -18,18 +18,22 @@ 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.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; /** * Command-line options for repositories. */ public class RepositoryOptions extends OptionsBase { - @Option(name = "experimental_repository_cache", - defaultValue = "null", - category = "hidden", - converter = OptionsUtils.PathFragmentConverter.class, - help = "Specifies the cache location of the downloaded values obtained " - + "during the fetching of external repositories.") + @Option( + name = "experimental_repository_cache", + defaultValue = "null", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = OptionsUtils.PathFragmentConverter.class, + help = + "Specifies the cache location of the downloaded values obtained " + + "during the fetching of external repositories." + ) public PathFragment experimentalRepositoryCache; }
\ No newline at end of file diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java index 6c1a124d88..37298bf810 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java @@ -26,6 +26,7 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.util.OS; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import javax.annotation.Nullable; /** @@ -71,10 +72,12 @@ public class BazelPythonConfiguration extends BuildConfiguration.Fragment { ) public String python3Path; - @Option(name = "experimental_python_import_all_repositories", + @Option( + name = "experimental_python_import_all_repositories", defaultValue = "true", - category = "undocumented", - help = "Do not use.") + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Do not use." + ) public boolean experimentalPythonImportAllRepositories; } diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java index 67618a3fbb..da3805e22a 100644 --- a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java +++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java @@ -16,6 +16,7 @@ package com.google.devtools.build.lib.buildeventstream.transports; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; /** Options used to configure BuildEventStreamer and its BuildEventTransports. */ public class BuildEventStreamOptions extends OptionsBase { @@ -23,7 +24,7 @@ public class BuildEventStreamOptions extends OptionsBase { @Option( name = "experimental_build_event_text_file", defaultValue = "", - category = "hidden", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "If non-empty, write a textual representation of the build event protocol to that file" ) public String buildEventTextFile; @@ -31,7 +32,7 @@ public class BuildEventStreamOptions extends OptionsBase { @Option( name = "experimental_build_event_binary_file", defaultValue = "", - category = "hidden", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "If non-empty, write a varint delimited binary representation of representation of the" + " build event protocol to that file." @@ -41,20 +42,22 @@ public class BuildEventStreamOptions extends OptionsBase { @Option( name = "experimental_build_event_text_file_path_conversion", defaultValue = "true", - category = "hidden", - help = "Convert paths in the text file representation of the build event protocol to more" - + " globally valid URIs whenever possible; if disabled, the file:// uri scheme will always" - + " be used" + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "Convert paths in the text file representation of the build event protocol to more " + + "globally valid URIs whenever possible; if disabled, the file:// uri scheme will " + + "always be used" ) public boolean buildEventTextFilePathConversion; @Option( name = "experimental_build_event_binary_file_path_conversion", defaultValue = "true", - category = "hidden", - help = "Convert paths in the binary file representation of the build event protocol to more" - + " globally valid URIs whenever possible; if disabled, the file:// uri scheme will always" - + " be used" + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "Convert paths in the binary file representation of the build event protocol to more " + + "globally valid URIs whenever possible; if disabled, the file:// uri scheme will " + + "always be used" ) public boolean buildEventBinaryFilePathConversion; diff --git a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java index 577be35c8a..0f93ccc424 100644 --- a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java +++ b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java @@ -38,6 +38,7 @@ import com.google.devtools.common.options.Converters.RangeConverter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsClassProvider; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import com.google.devtools.common.options.OptionsProvider; import java.util.ArrayList; @@ -83,193 +84,234 @@ public class BuildRequest implements OptionsClassProvider { ) public int jobs; - @Option(name = "progress_report_interval", - defaultValue = "0", - category = "verbosity", - converter = ProgressReportIntervalConverter.class, - help = "The number of seconds to wait between two reports on" - + " still running jobs. The default value 0 means to use" - + " the default 10:30:60 incremental algorithm.") + @Option( + name = "progress_report_interval", + defaultValue = "0", + category = "verbosity", + converter = ProgressReportIntervalConverter.class, + help = + "The number of seconds to wait between two reports on still running jobs. The " + + "default value 0 means to use the default 10:30:60 incremental algorithm." + ) public int progressReportInterval; - @Option(name = "explain", - defaultValue = "null", - category = "verbosity", - converter = OptionsUtils.PathFragmentConverter.class, - help = "Causes the build system to explain each executed step of the " - + "build. The explanation is written to the specified log file.") + @Option( + name = "explain", + defaultValue = "null", + category = "verbosity", + converter = OptionsUtils.PathFragmentConverter.class, + help = + "Causes the build system to explain each executed step of the " + + "build. The explanation is written to the specified log file." + ) public PathFragment explanationPath; - @Option(name = "verbose_explanations", - defaultValue = "false", - category = "verbosity", - help = "Increases the verbosity of the explanations issued if --explain is enabled. " - + "Has no effect if --explain is not enabled.") + @Option( + name = "verbose_explanations", + defaultValue = "false", + category = "verbosity", + help = + "Increases the verbosity of the explanations issued if --explain is enabled. " + + "Has no effect if --explain is not enabled." + ) public boolean verboseExplanations; - @Option(name = "output_filter", - converter = Converters.RegexPatternConverter.class, - defaultValue = "null", - category = "flags", - help = "Only shows warnings for rules with a name matching the provided regular " - + "expression.") + @Option( + name = "output_filter", + converter = Converters.RegexPatternConverter.class, + defaultValue = "null", + category = "flags", + help = "Only shows warnings for rules with a name matching the provided regular expression." + ) public Pattern outputFilter; @Deprecated - @Option(name = "dump_makefile", - defaultValue = "false", - category = "undocumented", - help = "this flag has no effect.") + @Option( + name = "dump_makefile", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "this flag has no effect." + ) public boolean dumpMakefile; @Deprecated - @Option(name = "dump_action_graph", - defaultValue = "false", - category = "undocumented", - help = "this flag has no effect.") - + @Option( + name = "dump_action_graph", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "this flag has no effect." + ) public boolean dumpActionGraph; @Deprecated - @Option(name = "dump_action_graph_for_package", - allowMultiple = true, - defaultValue = "", - category = "undocumented", - help = "this flag has no effect.") + @Option( + name = "dump_action_graph_for_package", + allowMultiple = true, + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "this flag has no effect." + ) public List<String> dumpActionGraphForPackage = new ArrayList<>(); @Deprecated - @Option(name = "dump_action_graph_with_middlemen", - defaultValue = "true", - category = "undocumented", - help = "this flag has no effect.") + @Option( + name = "dump_action_graph_with_middlemen", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "this flag has no effect." + ) public boolean dumpActionGraphWithMiddlemen; @Deprecated - @Option(name = "dump_providers", - defaultValue = "false", - category = "undocumented", - help = "This is a no-op.") + @Option( + name = "dump_providers", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "This is a no-op." + ) public boolean dumpProviders; @Deprecated - @Option(name = "dump_targets", - defaultValue = "null", - category = "undocumented", - help = "this flag has no effect.") + @Option( + name = "dump_targets", + defaultValue = "null", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "this flag has no effect." + ) public String dumpTargets; @Deprecated - @Option(name = "dump_host_deps", - defaultValue = "true", - category = "undocumented", - help = "Deprecated") + @Option( + name = "dump_host_deps", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Deprecated" + ) public boolean dumpHostDeps; @Deprecated - @Option(name = "dump_to_stdout", - defaultValue = "false", - category = "undocumented", - help = "Deprecated") + @Option( + name = "dump_to_stdout", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Deprecated" + ) public boolean dumpToStdout; - @Option(name = "analyze", - defaultValue = "true", - category = "undocumented", - help = "Execute the analysis phase; this is the usual behaviour. " - + "Specifying --noanalyze causes the build to stop before starting the " - + "analysis phase, returning zero iff the package loading completed " - + "successfully; this mode is useful for testing.") + @Option( + name = "analyze", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Execute the analysis phase; this is the usual behaviour. Specifying --noanalyze causes " + + "the build to stop before starting the analysis phase, returning zero iff the " + + "package loading completed successfully; this mode is useful for testing." + ) public boolean performAnalysisPhase; - @Option(name = "build", - defaultValue = "true", - category = "what", - help = "Execute the build; this is the usual behaviour. " - + "Specifying --nobuild causes the build to stop before executing the " - + "build actions, returning zero iff the package loading and analysis " - + "phases completed successfully; this mode is useful for testing " - + "those phases.") + @Option( + name = "build", + defaultValue = "true", + category = "what", + help = + "Execute the build; this is the usual behaviour. " + + "Specifying --nobuild causes the build to stop before executing the build " + + "actions, returning zero iff the package loading and analysis phases completed " + + "successfully; this mode is useful for testing those phases." + ) public boolean performExecutionPhase; - @Option(name = "output_groups", - converter = Converters.CommaSeparatedOptionListConverter.class, - allowMultiple = true, - defaultValue = "", - category = "undocumented", - help = "Specifies which output groups of the top-level targets to build. " - + "If omitted, a default set of output groups are built." - + "When specified the default set is overridden." - + "However you may use --output_groups=+<output_group> " - + "or --output_groups=-<output_group> " - + "to instead modify the set of output groups.") + @Option( + name = "output_groups", + converter = Converters.CommaSeparatedOptionListConverter.class, + allowMultiple = true, + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Specifies which output groups of the top-level targets to build. If omitted, a default " + + "set of output groups are built. When specified the default set is overridden." + + "However you may use --output_groups=+<output_group> or " + + "--output_groups=-<output_group> to instead modify the set of output groups." + ) public List<String> outputGroups; - @Option(name = "show_result", - defaultValue = "1", - category = "verbosity", - help = "Show the results of the build. For each " - + "target, state whether or not it was brought up-to-date, and if " - + "so, a list of output files that were built. The printed files " - + "are convenient strings for copy+pasting to the shell, to " - + "execute them.\n" - + "This option requires an integer argument, which " - + "is the threshold number of targets above which result " - + "information is not printed. " - + "Thus zero causes suppression of the message and MAX_INT " - + "causes printing of the result to occur always. The default is one.") + @Option( + name = "show_result", + defaultValue = "1", + category = "verbosity", + help = + "Show the results of the build. For each target, state whether or not it was brought " + + "up-to-date, and if so, a list of output files that were built. The printed files " + + "are convenient strings for copy+pasting to the shell, to execute them.\n" + + "This option requires an integer argument, which is the threshold number of " + + "targets above which result information is not printed. Thus zero causes " + + "suppression of the message and MAX_INT causes printing of the result to occur " + + "always. The default is one." + ) public int maxResultTargets; - @Option(name = "experimental_show_artifacts", - defaultValue = "false", - category = "undocumented", - help = "Output a list of all top level artifacts produced by this build." - + "Use output format suitable for tool consumption. " - + "This flag is temporary and intended to facilitate Android Studio integration. " - + "This output format will likely change in the future or disappear completely." + @Option( + name = "experimental_show_artifacts", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Output a list of all top level artifacts produced by this build." + + "Use output format suitable for tool consumption. " + + "This flag is temporary and intended to facilitate Android Studio integration. " + + "This output format will likely change in the future or disappear completely." ) public boolean showArtifacts; - @Option(name = "announce", - defaultValue = "false", - category = "verbosity", - help = "Deprecated. No-op.", - deprecationWarning = "This option is now deprecated and is a no-op") + @Option( + name = "announce", + defaultValue = "false", + category = "verbosity", + help = "Deprecated. No-op.", + deprecationWarning = "This option is now deprecated and is a no-op" + ) public boolean announce; - @Option(name = "symlink_prefix", - defaultValue = "null", - category = "misc", - help = "The prefix that is prepended to any of the convenience symlinks that are created " - + "after a build. If '/' is passed, then no symlinks are created and no warning is " - + "emitted. If omitted, the default value is the name of the build tool." - ) + @Option( + name = "symlink_prefix", + defaultValue = "null", + category = "misc", + help = + "The prefix that is prepended to any of the convenience symlinks that are created " + + "after a build. If '/' is passed, then no symlinks are created and no warning is " + + "emitted. If omitted, the default value is the name of the build tool." + ) public String symlinkPrefix; - @Option(name = "experimental_multi_cpu", - converter = Converters.CommaSeparatedOptionListConverter.class, - allowMultiple = true, - defaultValue = "", - category = "semantics", - help = "This flag allows specifying multiple target CPUs. If this is specified, " - + "the --cpu option is ignored.") + @Option( + name = "experimental_multi_cpu", + converter = Converters.CommaSeparatedOptionListConverter.class, + allowMultiple = true, + defaultValue = "", + category = "semantics", + help = + "This flag allows specifying multiple target CPUs. If this is specified, " + + "the --cpu option is ignored." + ) public List<String> multiCpus; - @Option(name = "output_tree_tracking", - oldName = "experimental_output_tree_tracking", - defaultValue = "true", - category = "undocumented", - help = "If set, tell the output service (if any) to track when files in the output " - + "tree have been modified externally (not by the build system). " - + "This should improve incremental build speed when an appropriate output service " - + "is enabled.") + @Option( + name = "output_tree_tracking", + oldName = "experimental_output_tree_tracking", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "If set, tell the output service (if any) to track when files in the output " + + "tree have been modified externally (not by the build system). " + + "This should improve incremental build speed when an appropriate output service " + + "is enabled." + ) public boolean finalizeActions; @Option( name = "aspects", converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "", - category = "undocumented", // for now + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, // for now help = "List of top-level aspects" ) public List<String> aspects; @@ -281,7 +323,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "use_action_cache", defaultValue = "true", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Whether to use the action cache" ) public boolean useActionCache; 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 c2b40c0859..1b0bb10c5e 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.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; /** @@ -44,153 +45,189 @@ 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.") + @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 @@ public class ExecutionOptions extends OptionsBase { @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 @@ public class ExecutionOptions extends OptionsBase { @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 class ExecutionOptions extends OptionsBase { ) 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" diff --git a/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java index e36136b0d9..14fe8b1fdc 100644 --- a/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java +++ b/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java @@ -16,6 +16,7 @@ package com.google.devtools.build.lib.exec.local; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.regex.Pattern; /** @@ -23,19 +24,25 @@ import java.util.regex.Pattern; */ public class LocalExecutionOptions extends OptionsBase { - @Option(name = "local_termination_grace_seconds", - oldName = "local_sigkill_grace_seconds", - category = "remote execution", - defaultValue = "15", - help = "Time to wait between terminating a local process due to timeout and forcefully " - + "shutting it down.") + @Option( + name = "local_termination_grace_seconds", + oldName = "local_sigkill_grace_seconds", + category = "remote execution", + defaultValue = "15", + help = + "Time to wait between terminating a local process due to timeout and forcefully " + + "shutting it down." + ) public double localSigkillGraceSeconds; - @Option(name = "allowed_local_actions_regex", - category = "undocumented", - converter = Converters.RegexPatternConverter.class, - defaultValue = "null", - help = "A regex whitelist for action types which may be run locally. If unset, " - + "all actions are allowed to execute locally") + @Option( + name = "allowed_local_actions_regex", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = Converters.RegexPatternConverter.class, + defaultValue = "null", + help = + "A regex whitelist for action types which may be run locally. If unset, " + + "all actions are allowed to execute locally" + ) public Pattern allowedLocalAction; } diff --git a/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java b/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java index b67eceea1e..4906aec484 100644 --- a/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java +++ b/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java @@ -18,6 +18,7 @@ import com.google.devtools.build.lib.packages.TestTimeout; import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.List; import java.util.Set; @@ -25,92 +26,107 @@ import java.util.Set; * Options that affect how command-line target patterns are resolved to individual targets. */ public class LoadingOptions extends OptionsBase { - @Option(name = "build_tests_only", - defaultValue = "false", - category = "what", - help = "If specified, only *_test and test_suite rules will be built " - + "and other targets specified on the command line will be ignored. " - + "By default everything that was requested will be built.") + @Option( + name = "build_tests_only", + defaultValue = "false", + category = "what", + help = + "If specified, only *_test and test_suite rules will be built and other targets specified " + + "on the command line will be ignored. By default everything that was requested " + + "will be built." + ) public boolean buildTestsOnly; - @Option(name = "compile_one_dependency", - defaultValue = "false", - category = "what", - help = "Compile a single dependency of the argument files. " - + "This is useful for syntax checking source files in IDEs, " - + "for example, by rebuilding a single target that depends on " - + "the source file to detect errors as early as possible in the " - + "edit/build/test cycle. This argument affects the way all " - + "non-flag arguments are interpreted; instead of being targets " - + "to build they are source filenames. For each source filename " - + "an arbitrary target that depends on it will be built.") + @Option( + name = "compile_one_dependency", + defaultValue = "false", + category = "what", + help = + "Compile a single dependency of the argument files. This is useful for syntax checking " + + "source files in IDEs, for example, by rebuilding a single target that depends on " + + "the source file to detect errors as early as possible in the edit/build/test cycle. " + + "This argument affects the way all non-flag arguments are interpreted; instead of " + + "being targets to build they are source filenames. For each source filename " + + "an arbitrary target that depends on it will be built." + ) public boolean compileOneDependency; - @Option(name = "build_tag_filters", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = "", - category = "what", - help = "Specifies a comma-separated list of tags. Each tag can be optionally " - + "preceded with '-' to specify excluded tags. Only those targets will be built that " - + "contain at least one included tag and do not contain any excluded tags. This option " - + "does not affect the set of tests executed with the 'test' command; those are be " - + "governed by the test filtering options, for example '--test_tag_filters'" - ) + @Option( + name = "build_tag_filters", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = "", + category = "what", + help = + "Specifies a comma-separated list of tags. Each tag can be optionally " + + "preceded with '-' to specify excluded tags. Only those targets will be built that " + + "contain at least one included tag and do not contain any excluded tags. This option " + + "does not affect the set of tests executed with the 'test' command; those are be " + + "governed by the test filtering options, for example '--test_tag_filters'" + ) public List<String> buildTagFilterList; - @Option(name = "test_tag_filters", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = "", - category = "what", - help = "Specifies a comma-separated list of test tags. Each tag can be optionally " + - "preceded with '-' to specify excluded tags. Only those test targets will be " + - "found that contain at least one included tag and do not contain any excluded " + - "tags. This option affects --build_tests_only behavior and the test command." - ) + @Option( + name = "test_tag_filters", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = "", + category = "what", + help = + "Specifies a comma-separated list of test tags. Each tag can be optionally " + + "preceded with '-' to specify excluded tags. Only those test targets will be " + + "found that contain at least one included tag and do not contain any excluded " + + "tags. This option affects --build_tests_only behavior and the test command." + ) public List<String> testTagFilterList; - @Option(name = "test_size_filters", - converter = TestSize.TestSizeFilterConverter.class, - defaultValue = "", - category = "what", - help = "Specifies a comma-separated list of test sizes. Each size can be optionally " + - "preceded with '-' to specify excluded sizes. Only those test targets will be " + - "found that contain at least one included size and do not contain any excluded " + - "sizes. This option affects --build_tests_only behavior and the test command." - ) + @Option( + name = "test_size_filters", + converter = TestSize.TestSizeFilterConverter.class, + defaultValue = "", + category = "what", + help = + "Specifies a comma-separated list of test sizes. Each size can be optionally " + + "preceded with '-' to specify excluded sizes. Only those test targets will be " + + "found that contain at least one included size and do not contain any excluded " + + "sizes. This option affects --build_tests_only behavior and the test command." + ) public Set<TestSize> testSizeFilterSet; - @Option(name = "test_timeout_filters", - converter = TestTimeout.TestTimeoutFilterConverter.class, - defaultValue = "", - category = "what", - help = "Specifies a comma-separated list of test timeouts. Each timeout can be " + - "optionally preceded with '-' to specify excluded timeouts. Only those test " + - "targets will be found that contain at least one included timeout and do not " + - "contain any excluded timeouts. This option affects --build_tests_only behavior " + - "and the test command." - ) + @Option( + name = "test_timeout_filters", + converter = TestTimeout.TestTimeoutFilterConverter.class, + defaultValue = "", + category = "what", + help = + "Specifies a comma-separated list of test timeouts. Each timeout can be " + + "optionally preceded with '-' to specify excluded timeouts. Only those test " + + "targets will be found that contain at least one included timeout and do not " + + "contain any excluded timeouts. This option affects --build_tests_only behavior " + + "and the test command." + ) public Set<TestTimeout> testTimeoutFilterSet; - @Option(name = "test_lang_filters", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = "", - category = "what", - help = "Specifies a comma-separated list of test languages. Each language can be " + - "optionally preceded with '-' to specify excluded languages. Only those " + - "test targets will be found that are written in the specified languages. " + - "The name used for each language should be the same as the language prefix in the " + - "*_test rule, e.g. one of 'cc', 'java', 'py', etc." + - "This option affects --build_tests_only behavior and the test command." - ) + @Option( + name = "test_lang_filters", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = "", + category = "what", + help = + "Specifies a comma-separated list of test languages. Each language can be " + + "optionally preceded with '-' to specify excluded languages. Only those " + + "test targets will be found that are written in the specified languages. " + + "The name used for each language should be the same as the language prefix in the " + + "*_test rule, e.g. one of 'cc', 'java', 'py', etc." + + "This option affects --build_tests_only behavior and the test command." + ) public List<String> testLangFilterList; - @Option(name = "build_manual_tests", - defaultValue = "false", - category = "what", - help = "Forces test targets tagged 'manual' to be built. " - + "'manual' tests are excluded from processing. This option forces " - + "them to be built (but not executed)." + @Option( + name = "build_manual_tests", + defaultValue = "false", + category = "what", + help = + "Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from " + + "processing. This option forces them to be built (but not executed)." ) public boolean buildManualTests; @@ -119,10 +135,13 @@ public class LoadingOptions extends OptionsBase { // the loading phase at all, and therefore can't currently support the other flag. If we roll this // out soonish, then we're never going to implement the legacy code path in the new // implementation, making it a moot point. - @Option(name = "experimental_skyframe_target_pattern_evaluator", - defaultValue = "false", - category = "hidden", - help = "Use the Skyframe-based target pattern evaluator; implies " - + "--experimental_interleave_loading_and_analysis.") + @Option( + name = "experimental_skyframe_target_pattern_evaluator", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "Use the Skyframe-based target pattern evaluator; implies " + + "--experimental_interleave_loading_and_analysis." + ) public boolean useSkyframeTargetPatternEvaluator; } diff --git a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java index 8237e8408f..626d76faa3 100644 --- a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java +++ b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java @@ -26,6 +26,7 @@ import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import java.util.List; @@ -56,64 +57,78 @@ public class PackageCacheOptions extends OptionsBase { } } - @Option(name = "package_path", - defaultValue = "%workspace%", - category = "package loading", - converter = Converters.ColonSeparatedOptionListConverter.class, - help = "A colon-separated list of where to look for packages. " - + "Elements beginning with '%workspace%' are relative to the enclosing " - + "workspace. If omitted or empty, the default is the output of " - + "'blaze info default-package-path'.") + @Option( + name = "package_path", + defaultValue = "%workspace%", + category = "package loading", + converter = Converters.ColonSeparatedOptionListConverter.class, + help = + "A colon-separated list of where to look for packages. " + + "Elements beginning with '%workspace%' are relative to the enclosing " + + "workspace. If omitted or empty, the default is the output of " + + "'blaze info default-package-path'." + ) public List<String> packagePath; - @Option(name = "show_package_location", - defaultValue = "false", - category = "verbosity", - deprecationWarning = "This flag is no longer supported and will go away soon.", - help = "If enabled, causes Blaze to print the location on the --package_path " - + "from which each package was loaded.") + @Option( + name = "show_package_location", + defaultValue = "false", + category = "verbosity", + deprecationWarning = "This flag is no longer supported and will go away soon.", + help = + "If enabled, causes Blaze to print the location on the --package_path " + + "from which each package was loaded." + ) public boolean showPackageLocation; - @Option(name = "show_loading_progress", - defaultValue = "true", - category = "verbosity", - help = "If enabled, causes Blaze to print \"Loading package:\" messages.") + @Option( + name = "show_loading_progress", + defaultValue = "true", + category = "verbosity", + help = "If enabled, causes Blaze to print \"Loading package:\" messages." + ) public boolean showLoadingProgress; - @Option(name = "deleted_packages", - defaultValue = "", - category = "package loading", - converter = CommaSeparatedPackageNameListConverter.class, - help = "A comma-separated list of names of packages which the " - + "build system will consider non-existent, even if they are " - + "visible somewhere on the package path." - + "\n" - + "Use this option when deleting a subpackage 'x/y' of an " - + "existing package 'x'. For example, after deleting x/y/BUILD " - + "in your client, the build system may complain if it " - + "encounters a label '//x:y/z' if that is still provided by another " - + "package_path entry. Specifying --deleted_packages x/y avoids this " - + "problem.") + @Option( + name = "deleted_packages", + defaultValue = "", + category = "package loading", + converter = CommaSeparatedPackageNameListConverter.class, + help = + "A comma-separated list of names of packages which the " + + "build system will consider non-existent, even if they are " + + "visible somewhere on the package path.\n" + + "Use this option when deleting a subpackage 'x/y' of an " + + "existing package 'x'. For example, after deleting x/y/BUILD " + + "in your client, the build system may complain if it " + + "encounters a label '//x:y/z' if that is still provided by another " + + "package_path entry. Specifying --deleted_packages x/y avoids this " + + "problem." + ) public List<PackageIdentifier> deletedPackages; - @Option(name = "default_visibility", - defaultValue = "private", - category = "undocumented", - converter = DefaultVisibilityConverter.class, - help = "Default visibility for packages that don't set it explicitly ('public' or " - + "'private').") + @Option( + name = "default_visibility", + defaultValue = "private", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = DefaultVisibilityConverter.class, + help = + "Default visibility for packages that don't set it explicitly ('public' or " + "'private')." + ) public RuleVisibility defaultVisibility; - @Option(name = "legacy_globbing_threads", - defaultValue = "100", - category = "undocumented", - help = "Number of threads to use for glob evaluation.") + @Option( + name = "legacy_globbing_threads", + defaultValue = "100", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Number of threads to use for glob evaluation." + ) public int globbingThreads; @Option( name = "experimental_max_directories_to_eagerly_visit_in_globbing", defaultValue = "-1", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If non-negative, the first time a glob is evaluated in a package, the subdirectories of " + "the package will be traversed in order to warm filesystem caches and compensate for " @@ -121,17 +136,22 @@ public class PackageCacheOptions extends OptionsBase { ) public int maxDirectoriesToEagerlyVisitInGlobbing; - @Option(name = "fetch", - defaultValue = "true", - category = "undocumented", - help = "Allows the command to fetch external dependencies") + @Option( + name = "fetch", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Allows the command to fetch external dependencies" + ) public boolean fetch; - @Option(name = "experimental_check_output_files", - defaultValue = "true", - category = "undocumented", - help = "Check for modifications made to the output files of a build. Consider setting " - + "this flag to false to see the effect on incremental build times.") + @Option( + name = "experimental_check_output_files", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Check for modifications made to the output files of a build. Consider setting " + + "this flag to false to see the effect on incremental build times." + ) public boolean checkOutputFiles; /** diff --git a/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java b/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java index e17fa48a90..34ba0d40f9 100644 --- a/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java +++ b/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java @@ -18,6 +18,7 @@ import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.EnumSet; import java.util.List; import java.util.Set; @@ -40,12 +41,14 @@ public class QueryOptions extends OptionsBase { } } - @Option(name = "output", - defaultValue = "label", - category = "query", - help = "The format in which the query results should be printed." - + " Allowed values are: label, label_kind, minrank, maxrank, package, location, graph," - + " xml, proto, record.") + @Option( + name = "output", + defaultValue = "label", + category = "query", + help = + "The format in which the query results should be printed. Allowed values are: " + + "label, label_kind, minrank, maxrank, package, location, graph, xml, proto, record." + ) public String outputFormat; @Option( @@ -114,121 +117,154 @@ public class QueryOptions extends OptionsBase { ) public OrderOutput orderOutput; - @Option(name = "keep_going", - abbrev = 'k', - defaultValue = "false", - category = "strategy", - help = "Continue as much as possible after an error. While the " - + "target that failed, and those that depend on it, cannot be " - + "analyzed, other prerequisites of these " - + "targets can be.") + @Option( + name = "keep_going", + abbrev = 'k', + defaultValue = "false", + category = "strategy", + help = + "Continue as much as possible after an error. While the target that failed, and those " + + "that depend on it, cannot be analyzed, other prerequisites of these targets can be." + ) public boolean keepGoing; - @Option(name = "loading_phase_threads", - defaultValue = "200", - category = "undocumented", - help = "Number of parallel threads to use for the loading phase.") + @Option( + name = "loading_phase_threads", + defaultValue = "200", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Number of parallel threads to use for the loading phase." + ) public int loadingPhaseThreads; - @Option(name = "host_deps", - defaultValue = "true", - category = "query", - help = "If enabled, dependencies on 'host configuration' targets will be included in " - + "the dependency graph over which the query operates. A 'host configuration' " - + "dependency edge, such as the one from any 'proto_library' rule to the Protocol " - + "Compiler, usually points to a tool executed during the build (on the host machine) " - + "rather than a part of the same 'target' program. Queries whose purpose is to " - + "discover the set of things needed during a build will typically enable this option; " - + "queries aimed at revealing the structure of a single program will typically disable " - + "this option.") + @Option( + name = "host_deps", + defaultValue = "true", + category = "query", + help = + "If enabled, dependencies on 'host configuration' targets will be included in the " + + "dependency graph over which the query operates. A 'host configuration' dependency " + + "edge, such as the one from any 'proto_library' rule to the Protocol Compiler, " + + "usually points to a tool executed during the build (on the host machine) rather " + + "than a part of the same 'target' program. Queries whose purpose is to discover " + + "the set of things needed during a build will typically enable this option; queries " + + "aimed at revealing the structure of a single program will typically disable this " + + "option." + ) public boolean includeHostDeps; - @Option(name = "implicit_deps", - defaultValue = "true", - category = "query", - help = "If enabled, implicit dependencies will be included in the dependency graph over " - + "which the query operates. An implicit dependency is one that is not explicitly " - + "specified in the BUILD file but added by blaze.") + @Option( + name = "implicit_deps", + defaultValue = "true", + category = "query", + help = + "If enabled, implicit dependencies will be included in the dependency graph over " + + "which the query operates. An implicit dependency is one that is not explicitly " + + "specified in the BUILD file but added by blaze." + ) public boolean includeImplicitDeps; - @Option(name = "graph:node_limit", - defaultValue = "512", - category = "query", - help = "The maximum length of the label string for a graph node in the output. Longer labels" - + " will be truncated; -1 means no truncation. This option is only applicable to" - + " --output=graph.") + @Option( + name = "graph:node_limit", + defaultValue = "512", + category = "query", + help = + "The maximum length of the label string for a graph node in the output. Longer labels" + + " will be truncated; -1 means no truncation. This option is only applicable to" + + " --output=graph." + ) public int graphNodeStringLimit; - @Option(name = "graph:factored", - defaultValue = "true", - category = "query", - help = "If true, then the graph will be emitted 'factored', i.e. " - + "topologically-equivalent nodes will be merged together and their " - + "labels concatenated. This option is only applicable to " - + "--output=graph.") + @Option( + name = "graph:factored", + defaultValue = "true", + category = "query", + help = + "If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes " + + "will be merged together and their labels concatenated. This option is only " + + "applicable to --output=graph." + ) public boolean graphFactored; - @Option(name = "proto:default_values", - defaultValue = "true", - category = "query", - help = "If true, attributes whose value is not explicitly specified " - + "in the BUILD file are included; otherwise they are omitted. " - + "This option is applicable to --output=proto") + @Option( + name = "proto:default_values", + defaultValue = "true", + category = "query", + help = + "If true, attributes whose value is not explicitly specified in the BUILD file are " + + "included; otherwise they are omitted. This option is applicable to --output=proto" + ) public boolean protoIncludeDefaultValues; - @Option(name = "xml:line_numbers", - defaultValue = "true", - category = "query", - help = "If true, XML output contains line numbers. Disabling this option " - + "may make diffs easier to read. This option is only applicable to " - + "--output=xml.") + @Option( + name = "xml:line_numbers", + defaultValue = "true", + category = "query", + help = + "If true, XML output contains line numbers. Disabling this option may make diffs easier " + + "to read. This option is only applicable to --output=xml." + ) public boolean xmlLineNumbers; - @Option(name = "xml:default_values", - defaultValue = "false", - category = "query", - help = "If true, rule attributes whose value is not explicitly specified " - + "in the BUILD file are printed; otherwise they are omitted.") + @Option( + name = "xml:default_values", + defaultValue = "false", + category = "query", + help = + "If true, rule attributes whose value is not explicitly specified in the BUILD file are " + + "printed; otherwise they are omitted." + ) public boolean xmlShowDefaultValues; - @Option(name = "strict_test_suite", - defaultValue = "false", - category = "query", - help = "If true, the tests() expression gives an error if it encounters a test_suite " - + "containing non-test targets.") + @Option( + name = "strict_test_suite", + defaultValue = "false", + category = "query", + help = + "If true, the tests() expression gives an error if it encounters a test_suite containing " + + "non-test targets." + ) public boolean strictTestSuite; - @Option(name = "universe_scope", - converter = Converters.CommaSeparatedOptionListConverter.class, - defaultValue = "", - category = "query", - help = "A comma-separated set of target patterns (additive and subtractive). The query may " - + "be performed in the universe defined by the transitive closure of the specified " - + "targets.") + @Option( + name = "universe_scope", + converter = Converters.CommaSeparatedOptionListConverter.class, + defaultValue = "", + category = "query", + help = + "A comma-separated set of target patterns (additive and subtractive). The query may " + + "be performed in the universe defined by the transitive closure of the specified " + + "targets." + ) public List<String> universeScope; - @Option(name = "relative_locations", - defaultValue = "false", - category = "query", - help = "If true, the location of BUILD files in xml and proto outputs will be relative. " - + "By default, the location output is an absolute path and will not be consistent " - + "across machines. You can set this option to true to have a consistent result " - + "across machines.") + @Option( + name = "relative_locations", + defaultValue = "false", + category = "query", + help = + "If true, the location of BUILD files in xml and proto outputs will be relative. " + + "By default, the location output is an absolute path and will not be consistent " + + "across machines. You can set this option to true to have a consistent result " + + "across machines." + ) public boolean relativeLocations; - @Option(name = "aspect_deps", - converter = AspectResolutionModeConverter.class, - defaultValue = "conservative", - category = "query", - help = "How to resolve aspect dependencies when the output format is one of " - + "{xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' " - + "(the default) means all declared aspect dependencies are added regardless of whether " - + "they are viable given the rule class of direct dependencies, 'precise' means that " - + "only those aspects are added that are possibly active given the rule class of the " - + "direct dependencies. Note that precise mode requires loading other packages to " - + "evaluate a single target thus making it slower than the other modes. Also note that " - + "even precise mode is not completely precise: the decision whether to compute an " - + "aspect is decided in the analysis phase, which is not run during 'blaze query'.") + @Option( + name = "aspect_deps", + converter = AspectResolutionModeConverter.class, + defaultValue = "conservative", + category = "query", + help = + "How to resolve aspect dependencies when the output format is one of {xml,proto,record}. " + + "'off' means no aspect dependencies are resolved, 'conservative' (the default) means " + + "all declared aspect dependencies are added regardless of whether they are viable " + + "given the rule class of direct dependencies, 'precise' means that only those " + + "aspects are added that are possibly active given the rule class of the direct " + + "dependencies. Note that precise mode requires loading other packages to evaluate " + + "a single target thus making it slower than the other modes. Also note that even " + + "precise mode is not completely precise: the decision whether to compute an aspect " + + "is decided in the analysis phase, which is not run during 'blaze query'." + ) public AspectResolver.Mode aspectDeps; @Option( @@ -236,8 +272,8 @@ public class QueryOptions extends OptionsBase { defaultValue = "", category = "query", help = - "If set, query will read the query from the file named here, rather than on the " - + "command line. It is an error to specify a file here as well as a command-line query." + "If set, query will read the query from the file named here, rather than on the command " + + "line. It is an error to specify a file here as well as a command-line query." ) public String queryFile; diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java index b7e543e83a..3cfa842f9f 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java @@ -36,6 +36,7 @@ import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import java.util.List; import java.util.Set; @@ -189,35 +190,41 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { } } - /** - * Android configuration options. - */ + /** Android configuration options. */ public static class Options extends FragmentOptions { - @Option(name = "Android configuration distinguisher", - defaultValue = "MAIN", - converter = ConfigurationDistinguisherConverter.class, - category = "internal") + @Option( + name = "Android configuration distinguisher", + defaultValue = "MAIN", + converter = ConfigurationDistinguisherConverter.class, + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL + ) public ConfigurationDistinguisher configurationDistinguisher; // For deploying incremental installation of native libraries. Do not use on the command line. // The idea is that once this option works, we'll flip the default value in a config file, then // once it is proven that it works, remove it from Bazel and said config file. - @Option(name = "android_incremental_native_libs", - defaultValue = "false", - category = "undocumented") + @Option( + name = "android_incremental_native_libs", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED + ) public boolean incrementalNativeLibs; - @Option(name = "android_crosstool_top", - defaultValue = "//external:android/crosstool", - category = "semantics", - converter = EmptyToNullLabelConverter.class, - help = "The location of the C++ compiler used for Android builds.") + @Option( + name = "android_crosstool_top", + defaultValue = "//external:android/crosstool", + category = "semantics", + converter = EmptyToNullLabelConverter.class, + help = "The location of the C++ compiler used for Android builds." + ) public Label androidCrosstoolTop; - @Option(name = "android_cpu", - defaultValue = "armeabi", - category = "semantics", - help = "The Android target CPU.") + @Option( + name = "android_cpu", + defaultValue = "armeabi", + category = "semantics", + help = "The Android target CPU." + ) public String cpu; @Option( @@ -232,79 +239,94 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "android_dynamic_mode", defaultValue = "off", converter = DynamicModeConverter.class, - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = - "Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary " - + "does not explicitly create a shared library. 'default' means blaze will choose " - + "whether to link dynamically. 'fully' means all libraries will be linked " - + "dynamically. 'off' means that all libraries will be linked in mostly static mode." + "Determines whether C++ deps of Android rules will be linked dynamically when a " + + "cc_binary does not explicitly create a shared library. " + + "'default' means blaze will choose whether to link dynamically. " + + "'fully' means all libraries will be linked dynamically. " + + "'off' means that all libraries will be linked in mostly static mode." ) public DynamicMode dynamicMode; // Label of filegroup combining all Android tools used as implicit dependencies of // android_* rules - @Option(name = "android_sdk", - defaultValue = "@bazel_tools//tools/android:sdk", - category = "version", - converter = LabelConverter.class, - help = "Specifies Android SDK/platform that is used to build Android applications.") + @Option( + name = "android_sdk", + defaultValue = "@bazel_tools//tools/android:sdk", + category = "version", + converter = LabelConverter.class, + help = "Specifies Android SDK/platform that is used to build Android applications." + ) public Label sdk; // TODO(bazel-team): Maybe merge this with --android_cpu above. - @Option(name = "fat_apk_cpu", - converter = Converters.CommaSeparatedOptionListConverter.class, - defaultValue = "armeabi-v7a", - category = "semantics", - help = "Setting this option enables fat APKs, which contain native binaries for all " - + "specified target architectures, e.g., --fat_apk_cpu=x86,armeabi-v7a. If this " - + "flag is specified, then --android_cpu is ignored for dependencies of " - + "android_binary rules.") + @Option( + name = "fat_apk_cpu", + converter = Converters.CommaSeparatedOptionListConverter.class, + defaultValue = "armeabi-v7a", + category = "semantics", + help = + "Setting this option enables fat APKs, which contain native binaries for all " + + "specified target architectures, e.g., --fat_apk_cpu=x86,armeabi-v7a. If this " + + "flag is specified, then --android_cpu is ignored for dependencies of " + + "android_binary rules." + ) public List<String> fatApkCpus; // For desugaring lambdas when compiling Java 8 sources. Do not use on the command line. // The idea is that once this option works, we'll flip the default value in a config file, then // once it is proven that it works, remove it from Bazel and said config file. - @Option(name = "experimental_desugar_for_android", - defaultValue = "false", - category = "undocumented", - help = "Whether to desugar Java 8 bytecode before dexing.") + @Option( + name = "experimental_desugar_for_android", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Whether to desugar Java 8 bytecode before dexing." + ) public boolean desugarJava8; - @Option(name = "incremental_dexing", - defaultValue = "false", - category = "semantics", - help = "Does most of the work for dexing separately for each Jar file.") + @Option( + name = "incremental_dexing", + defaultValue = "false", + category = "semantics", + help = "Does most of the work for dexing separately for each Jar file." + ) public boolean incrementalDexing; // TODO(b/31711689): remove this flag from config files and here - @Option(name = "host_incremental_dexing", - defaultValue = "false", - category = "hidden", - help = "This flag is deprecated in favor of applying --incremental_dexing to both host " - + "and target configuration. This flag will be removed in a future release.") + @Option( + name = "host_incremental_dexing", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "This flag is deprecated in favor of applying --incremental_dexing to both host " + + "and target configuration. This flag will be removed in a future release." + ) public boolean hostIncrementalDexing; // Do not use on the command line. // The idea is that this option lets us gradually turn on incremental dexing for different // binaries. Users should rely on --noincremental_dexing to turn it off. // TODO(b/31711689): remove this flag from config files and here - @Option(name = "incremental_dexing_binary_types", - defaultValue = "all", - category = "undocumented", - converter = AndroidBinaryTypesConverter.class, - implicitRequirements = "--incremental_dexing", - help = "Kinds of binaries to incrementally dex if --incremental_dexing is true.") + @Option( + name = "incremental_dexing_binary_types", + defaultValue = "all", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = AndroidBinaryTypesConverter.class, + implicitRequirements = "--incremental_dexing", + help = "Kinds of binaries to incrementally dex if --incremental_dexing is true." + ) public Set<AndroidBinaryType> incrementalDexingBinaries; - /** - * Whether to look for incrementally dex protos built with java_lite_proto_library. - */ + /** Whether to look for incrementally dex protos built with java_lite_proto_library. */ // TODO(b/31711689): remove this flag from config files and here @Option( name = "experimental_incremental_dexing_for_lite_protos", defaultValue = "true", category = "experimental", - help = "Do not use.") + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Do not use." + ) public boolean incrementalDexingForLiteProtos; /** @@ -315,142 +337,181 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_incremental_dexing_error_on_missed_jars", defaultValue = "true", category = "experimental", - help = "Do not use.") + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Do not use." + ) public boolean incrementalDexingErrorOnMissedJars; // Do not use on the command line. // This flag is intended to be updated as we add supported flags to the incremental dexing tools - @Option(name = "non_incremental_per_target_dexopts", - converter = Converters.CommaSeparatedOptionListConverter.class, - defaultValue = "--positions", - category = "semantics", - help = "dx flags that that prevent incremental dexing for binary targets that list any of " - + "the flags listed here in their 'dexopts' attribute, which are ignored with " - + "incremental dexing (superseding --dexopts_supported_in_incremental_dexing). " - + "Defaults to --no-locals for safety but can in general be used " - + "to make sure the listed dx flags are honored, with additional build latency. " - + "Please notify us if you find yourself needing this flag.") + @Option( + name = "non_incremental_per_target_dexopts", + converter = Converters.CommaSeparatedOptionListConverter.class, + defaultValue = "--positions", + category = "semantics", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "dx flags that that prevent incremental dexing for binary targets that list any of " + + "the flags listed here in their 'dexopts' attribute, which are ignored with " + + "incremental dexing (superseding --dexopts_supported_in_incremental_dexing). " + + "Defaults to --no-locals for safety but can in general be used " + + "to make sure the listed dx flags are honored, with additional build latency. " + + "Please notify us if you find yourself needing this flag." + ) public List<String> nonIncrementalPerTargetDexopts; // Do not use on the command line. // This flag is intended to be updated as we add supported flags to the incremental dexing tools - @Option(name = "dexopts_supported_in_incremental_dexing", - converter = Converters.CommaSeparatedOptionListConverter.class, - defaultValue = "--no-optimize,--no-locals", - category = "hidden", - help = "dx flags supported when converting Jars to dex archives incrementally.") + @Option( + name = "dexopts_supported_in_incremental_dexing", + converter = Converters.CommaSeparatedOptionListConverter.class, + defaultValue = "--no-optimize,--no-locals", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "dx flags supported when converting Jars to dex archives incrementally." + ) public List<String> dexoptsSupportedInIncrementalDexing; // Do not use on the command line. // This flag is intended to be updated as we add supported flags to the incremental dexing tools // TODO(b/31711689): remove --no-optimize and --no-locals as DexFileMerger no longer needs them - @Option(name = "dexopts_supported_in_dexmerger", - converter = Converters.CommaSeparatedOptionListConverter.class, - defaultValue = "--no-optimize,--no-locals,--minimal-main-dex,--set-max-idx-number", - category = "hidden", - help = "dx flags supported in tool that merges dex archives into final classes.dex files.") + @Option( + name = "dexopts_supported_in_dexmerger", + converter = Converters.CommaSeparatedOptionListConverter.class, + defaultValue = "--no-optimize,--no-locals,--minimal-main-dex,--set-max-idx-number", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "dx flags supported in tool that merges dex archives into final classes.dex files." + ) public List<String> dexoptsSupportedInDexMerger; @Option( name = "experimental_android_rewrite_dexes_with_rex", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "use rex tool to rewrite dex files" ) public boolean useRexToCompressDexFiles; - @Option(name = "experimental_allow_android_library_deps_without_srcs", - defaultValue = "true", - category = "undocumented", - help = "Flag to help transition from allowing to disallowing srcs-less android_library" - + " rules with deps. The depot needs to be cleaned up to roll this out by default.") + @Option( + name = "experimental_allow_android_library_deps_without_srcs", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Flag to help transition from allowing to disallowing srcs-less android_library" + + " rules with deps. The depot needs to be cleaned up to roll this out by default." + ) public boolean allowAndroidLibraryDepsWithoutSrcs; - @Option(name = "experimental_android_resource_shrinking", - defaultValue = "false", - category = "undocumented", - help = "Enables resource shrinking for android_binary APKs that use ProGuard.") + @Option( + name = "experimental_android_resource_shrinking", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Enables resource shrinking for android_binary APKs that use ProGuard." + ) public boolean useExperimentalAndroidResourceShrinking; - @Option(name = "android_resource_shrinking", - defaultValue = "false", - category = "semantics", - help = "Enables resource shrinking for android_binary APKs that use ProGuard.") + @Option( + name = "android_resource_shrinking", + defaultValue = "false", + category = "semantics", + help = "Enables resource shrinking for android_binary APKs that use ProGuard." + ) public boolean useAndroidResourceShrinking; - @Option(name = "android_manifest_merger", - defaultValue = "android", - category = "semantics", - converter = AndroidManifestMergerConverter.class, - help = "Selects the manifest merger to use for android_binary rules. Flag to help the" - + "transition to the Android manifest merger from the legacy merger.") + @Option( + name = "android_manifest_merger", + defaultValue = "android", + category = "semantics", + converter = AndroidManifestMergerConverter.class, + help = + "Selects the manifest merger to use for android_binary rules. Flag to help the" + + "transition to the Android manifest merger from the legacy merger." + ) public AndroidManifestMerger manifestMerger; // Do not use on the command line. - @Option(name = "experimental_use_parallel_android_resource_processing", + @Option( + name = "experimental_use_parallel_android_resource_processing", defaultValue = "true", - category = "undocumented", - help = "Process android_library resources with higher parallelism. Generates library " - + "R classes from a merge action, separately from aapt.") + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Process android_library resources with higher parallelism. Generates library " + + "R classes from a merge action, separately from aapt." + ) public boolean useParallelResourceProcessing; - @Option(name = "apk_signing_method", - converter = ApkSigningMethodConverter.class, - defaultValue = "v1_v2", - category = "undocumented", - help = "Implementation to use to sign APKs") + @Option( + name = "apk_signing_method", + converter = ApkSigningMethodConverter.class, + defaultValue = "v1_v2", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Implementation to use to sign APKs" + ) public ApkSigningMethod apkSigningMethod; - @Option(name = "use_singlejar_apkbuilder", - defaultValue = "true", - category = "undocumented", - help = "Build Android APKs with SingleJar.") + @Option( + name = "use_singlejar_apkbuilder", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Build Android APKs with SingleJar." + ) public boolean useSingleJarApkBuilder; - @Option(name = "experimental_android_use_singlejar_for_multidex", - defaultValue = "true", - category = "undocumented", - help = "Use SingleJar for multidex dex extraction.") + @Option( + name = "experimental_android_use_singlejar_for_multidex", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Use SingleJar for multidex dex extraction." + ) public boolean useSingleJarForMultidex; - @Option(name = "experimental_android_resource_filtering_method", + @Option( + name = "experimental_android_resource_filtering_method", converter = ResourceFilter.Converter.class, defaultValue = "filter_in_execution", - category = "undocumented", - help = "Determines when resource filtering attributes, such as the android_binary " - + "'resource_configuration_filters' and 'densities' attributes, are applied. By default, " - + "bazel will 'filter_in_execution'. The experimental 'filter_in_analysis' option " - + "instead applies these filters earlier in the build process, with corresponding gains " - + "in speed. The experimental 'filter_in_analysis_with_dynamic_configuration' option " - + "also passes these options to the android_binary's dependencies, which also filter " - + "their internal resources in analysis, possibly making the build even faster " - + "(especially in systems that do not cache the results of those dependencies)." + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Determines when resource filtering attributes, such as the android_binary " + + "'resource_configuration_filters' and 'densities' attributes, are applied. " + + "By default, bazel will 'filter_in_execution'. The experimental " + + "'filter_in_analysis' option instead applies these filters earlier in the build " + + "process, with corresponding gains in speed. The experimental " + + "'filter_in_analysis_with_dynamic_configuration' option also passes these options " + + "to the android_binary's dependencies, which also filter their internal resources " + + "in analysis, possibly making the build even faster (especially in systems that " + + "do not cache the results of those dependencies)." ) // The ResourceFilter object holds the filtering behavior as well as settings for which // resources should be filtered. The filtering behavior is set from the command line, but the // other settings default to empty and are set or modified via dynamic configuration. public ResourceFilter resourceFilter; - @Option(name = "use_singlejar_for_proguard_libraryjars", - defaultValue = "false", - category = "undocumented", - help = "Use SingleJar to combine all ProGuard library jars.") + @Option( + name = "use_singlejar_for_proguard_libraryjars", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Use SingleJar to combine all ProGuard library jars." + ) public boolean useSingleJarForProguardLibraryJars; - @Option(name = "experimental_android_compress_java_resources", - defaultValue = "false", - category = "undocumented", - implicitRequirements = "--use_singlejar_apkbuilder", - help = "Compress Java resources in APKs") + @Option( + name = "experimental_android_compress_java_resources", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + implicitRequirements = "--use_singlejar_apkbuilder", + help = "Compress Java resources in APKs" + ) public boolean compressJavaResources; - @Option(name = "experimental_android_include_library_resource_jars", - defaultValue = "true", - category = "undocumented", - help = "Specifies whether resource JAR files for android_library targets should be included" - + " as runtime dependencies. Defaults to the old behavior, including them. These JARs" - + " are not nessecary for normal use as all required resources are included in the" - + " top-level android_binary resource JAR.") + @Option( + name = "experimental_android_include_library_resource_jars", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Specifies whether resource JAR files for android_library targets should be included" + + " as runtime dependencies. Defaults to the old behavior, including them. These JARs" + + " are not nessecary for normal use as all required resources are included in the" + + " top-level android_binary resource JAR." + ) public boolean includeLibraryResourceJars; @Override diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java index f588ff50e6..23977e16b0 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java @@ -30,6 +30,7 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.List; /** @@ -91,38 +92,38 @@ public class AppleCommandLineOptions extends FragmentOptions { public DottedVersion macOsSdkVersion; @Option( - name = "ios_minimum_os", - defaultValue = DEFAULT_MINIMUM_IOS, - category = "flags", - converter = DottedVersionConverter.class, - help = "Minimum compatible iOS version for target simulators and devices." + name = "ios_minimum_os", + defaultValue = DEFAULT_MINIMUM_IOS, + category = "flags", + converter = DottedVersionConverter.class, + help = "Minimum compatible iOS version for target simulators and devices." ) public DottedVersion iosMinimumOs; @Option( - name = "watchos_minimum_os", - defaultValue = "null", - category = "flags", - converter = DottedVersionConverter.class, - help = "Minimum compatible watchOS version for target simulators and devices." + name = "watchos_minimum_os", + defaultValue = "null", + category = "flags", + converter = DottedVersionConverter.class, + help = "Minimum compatible watchOS version for target simulators and devices." ) public DottedVersion watchosMinimumOs; @Option( - name = "tvos_minimum_os", - defaultValue = "null", - category = "flags", - converter = DottedVersionConverter.class, - help = "Minimum compatible tvOS version for target simulators and devices." + name = "tvos_minimum_os", + defaultValue = "null", + category = "flags", + converter = DottedVersionConverter.class, + help = "Minimum compatible tvOS version for target simulators and devices." ) public DottedVersion tvosMinimumOs; @Option( - name = "macos_minimum_os", - defaultValue = DEFAULT_MINIMUM_MACOS, - category = "flags", - converter = DottedVersionConverter.class, - help = "Minimum compatible macOS version for targets." + name = "macos_minimum_os", + defaultValue = DEFAULT_MINIMUM_MACOS, + category = "flags", + converter = DottedVersionConverter.class, + help = "Minimum compatible macOS version for targets." ) public DottedVersion macosMinimumOs; @@ -147,37 +148,44 @@ public class AppleCommandLineOptions extends FragmentOptions { */ public static final String DEFAULT_MACOS_CPU = "x86_64"; - @Option(name = "ios_cpu", - defaultValue = DEFAULT_IOS_CPU, - category = "build", - help = "Specifies to target CPU of iOS compilation.") + @Option( + name = "ios_cpu", + defaultValue = DEFAULT_IOS_CPU, + category = "build", + help = "Specifies to target CPU of iOS compilation." + ) public String iosCpu; @Option( - name = "apple_crosstool_top", - defaultValue = "@bazel_tools//tools/cpp:toolchain", - category = "version", - converter = LabelConverter.class, - help = "The label of the crosstool package to be used in Apple and Objc rules and their" + name = "apple_crosstool_top", + defaultValue = "@bazel_tools//tools/cpp:toolchain", + category = "version", + converter = LabelConverter.class, + help = + "The label of the crosstool package to be used in Apple and Objc rules and their" + " dependencies." - ) - public Label appleCrosstoolTop; - - @Option(name = "apple_platform_type", - defaultValue = "IOS", - category = "undocumented", - converter = PlatformTypeConverter.class, - help = - "Don't set this value from the command line - it is derived from other flags and " - + "configuration transitions derived from rule attributes") + ) + public Label appleCrosstoolTop; + + @Option( + name = "apple_platform_type", + defaultValue = "IOS", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = PlatformTypeConverter.class, + help = + "Don't set this value from the command line - it is derived from other flags and " + + "configuration transitions derived from rule attributes" + ) public PlatformType applePlatformType; - @Option(name = "apple_split_cpu", - defaultValue = "", - category = "undocumented", - help = - "Don't set this value from the command line - it is derived from other flags and " - + "configuration transitions derived from rule attributes") + @Option( + name = "apple_split_cpu", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Don't set this value from the command line - it is derived from other flags and " + + "configuration transitions derived from rule attributes" + ) public String appleSplitCpu; // This option exists because two configurations are not allowed to have the same cache key @@ -186,51 +194,64 @@ public class AppleCommandLineOptions extends FragmentOptions { // This option must only be set by those transitions for this purpose. // TODO(bazel-team): Remove this once we have dynamic configurations but make sure that different // configurations (e.g. by min os version) always use different output paths. - @Option(name = "apple configuration distinguisher", - defaultValue = "UNKNOWN", - converter = ConfigurationDistinguisherConverter.class, - category = "internal") + @Option( + name = "apple configuration distinguisher", + defaultValue = "UNKNOWN", + converter = ConfigurationDistinguisherConverter.class, + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL + ) public ConfigurationDistinguisher configurationDistinguisher; - @Option(name = "ios_multi_cpus", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = "", - category = "flags", - help = "Comma-separated list of architectures to build an ios_application with. The result " - + "is a universal binary containing all specified architectures.") + @Option( + name = "ios_multi_cpus", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = "", + category = "flags", + help = + "Comma-separated list of architectures to build an ios_application with. The result " + + "is a universal binary containing all specified architectures." + ) public List<String> iosMultiCpus; - @Option(name = "watchos_cpus", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = DEFAULT_WATCHOS_CPU, - category = "flags", - help = "Comma-separated list of architectures for which to build Apple watchOS binaries.") + @Option( + name = "watchos_cpus", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = DEFAULT_WATCHOS_CPU, + category = "flags", + help = "Comma-separated list of architectures for which to build Apple watchOS binaries." + ) public List<String> watchosCpus; - @Option(name = "tvos_cpus", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = DEFAULT_TVOS_CPU, - category = "flags", - help = "Comma-separated list of architectures for which to build Apple tvOS binaries.") + @Option( + name = "tvos_cpus", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = DEFAULT_TVOS_CPU, + category = "flags", + help = "Comma-separated list of architectures for which to build Apple tvOS binaries." + ) public List<String> tvosCpus; - @Option(name = "macos_cpus", - converter = CommaSeparatedOptionListConverter.class, - defaultValue = DEFAULT_MACOS_CPU, - category = "flags", - help = "Comma-separated list of architectures for which to build Apple macOS binaries.") + @Option( + name = "macos_cpus", + converter = CommaSeparatedOptionListConverter.class, + defaultValue = DEFAULT_MACOS_CPU, + category = "flags", + help = "Comma-separated list of architectures for which to build Apple macOS binaries." + ) public List<String> macosCpus; - @Option(name = "default_ios_provisioning_profile", - defaultValue = "", - category = "undocumented", - converter = DefaultProvisioningProfileConverter.class) + @Option( + name = "default_ios_provisioning_profile", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = DefaultProvisioningProfileConverter.class + ) public Label defaultProvisioningProfile; @Option( name = "xcode_version_config", defaultValue = "@local_config_xcode//:host_xcodes", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, help = "The label of the xcode_config rule to be used for selecting the Xcode version " @@ -256,26 +277,30 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "xcode_toolchain", defaultValue = "null", category = "flags", - help = "The identifier of an Xcode toolchain to use for builds. Currently only the toolchains " - + "that ship with Xcode are supported. For example, in addition to the default toolchain" - + " Xcode 8 has 'com.apple.dt.toolchain.Swift_2_3' which can be used for building legacy" - + " Swift code." + help = + "The identifier of an Xcode toolchain to use for builds. Currently only the toolchains " + + "that ship with Xcode are supported. For example, in addition to the default " + + "toolchain Xcode 8 has 'com.apple.dt.toolchain.Swift_2_3' which can be used for " + + "building legacy Swift code." ) public String xcodeToolchain; - @Option(name = "apple_bitcode", - converter = AppleBitcodeMode.Converter.class, - // TODO(blaze-team): Default to embedded_markers when fully implemented. - defaultValue = "none", - category = "flags", - help = "Specify the Apple bitcode mode for compile steps. " - + "Values: 'none', 'embedded_markers', 'embedded'.") + @Option( + name = "apple_bitcode", + converter = AppleBitcodeMode.Converter.class, + // TODO(blaze-team): Default to embedded_markers when fully implemented. + defaultValue = "none", + category = "flags", + help = + "Specify the Apple bitcode mode for compile steps. " + + "Values: 'none', 'embedded_markers', 'embedded'." + ) public AppleBitcodeMode appleBitcodeMode; @Option( name = "apple_crosstool_transition", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If true, the apple crosstool is used for all apple rules." ) public boolean enableAppleCrosstoolTransition; @@ -283,7 +308,7 @@ public class AppleCommandLineOptions extends FragmentOptions { @Option( name = "target_uses_apple_crosstool", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If true, this target uses the apple crosstool. Do not set this flag manually." ) public boolean targetUsesAppleCrosstool; diff --git a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java index 3d751c1721..dbb913d626 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java @@ -28,6 +28,7 @@ import com.google.devtools.build.lib.analysis.config.FragmentOptions; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.Map; import java.util.SortedMap; import javax.annotation.Nullable; @@ -56,10 +57,11 @@ public final class ConfigFeatureFlagConfiguration extends BuildConfiguration.Fra public static final class Options extends FragmentOptions { /** The mapping from config_feature_flag rules to their values. */ @Option( - name = "config_feature_flag values (private)", - category = "internal", - converter = EmptyImmutableSortedMapConverter.class, - defaultValue = "{}") + name = "config_feature_flag values (private)", + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, + converter = EmptyImmutableSortedMapConverter.class, + defaultValue = "{}" + ) public ImmutableSortedMap<Label, String> flagValues = ImmutableSortedMap.of(); /** Retrieves the set of flag-value pairs. */ diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java index 19af5fd0b8..baa5bfe613 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java @@ -33,6 +33,7 @@ import com.google.devtools.build.lib.view.config.crosstool.CrosstoolConfig.LipoM import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import java.util.LinkedHashSet; import java.util.List; @@ -129,7 +130,7 @@ public class CppOptions extends FragmentOptions { @Option( name = "lipo input collector", defaultValue = "false", - category = "internal", + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, help = "Internal flag, only used to create configurations with the LIPO-collector flag set." ) public boolean lipoCollector; @@ -603,7 +604,7 @@ public class CppOptions extends FragmentOptions { category = "strategy", help = "If true, headers found through system include paths (-isystem) are also required to be " - + "declared." + + "declared." ) public boolean strictSystemIncludes; diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java index 1fa3fbf228..f64373d5c5 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java @@ -29,6 +29,7 @@ import com.google.devtools.build.lib.rules.java.JavaConfiguration.JavaClasspathM import com.google.devtools.build.lib.rules.java.JavaConfiguration.JavaOptimizationMode; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.TriState; import java.util.HashMap; import java.util.LinkedHashSet; @@ -57,19 +58,24 @@ public class JavaOptions extends FragmentOptions { } } - @Option(name = "javabase", - defaultValue = "@bazel_tools//tools/jdk:jdk", - category = "version", - help = "JAVABASE used for the JDK invoked by Blaze. This is the " - + "JAVABASE which will be used to execute external Java " - + "commands.") + @Option( + name = "javabase", + defaultValue = "@bazel_tools//tools/jdk:jdk", + category = "version", + help = + "JAVABASE used for the JDK invoked by Blaze. This is the " + + "JAVABASE which will be used to execute external Java " + + "commands." + ) public String javaBase; - @Option(name = "java_toolchain", - defaultValue = "@bazel_tools//tools/jdk:toolchain", - category = "version", - converter = LabelConverter.class, - help = "The name of the toolchain rule for Java.") + @Option( + name = "java_toolchain", + defaultValue = "@bazel_tools//tools/jdk:toolchain", + category = "version", + converter = LabelConverter.class, + help = "The name of the toolchain rule for Java." + ) public Label javaToolchain; @Option( @@ -81,41 +87,54 @@ public class JavaOptions extends FragmentOptions { ) public Label hostJavaToolchain; - @Option(name = "host_javabase", - defaultValue = "@bazel_tools//tools/jdk:jdk", - category = "version", - help = "JAVABASE used for the host JDK. This is the JAVABASE which is used to execute " - + " tools during a build.") + @Option( + name = "host_javabase", + defaultValue = "@bazel_tools//tools/jdk:jdk", + category = "version", + help = + "JAVABASE used for the host JDK. This is the JAVABASE which is used to execute " + + " tools during a build." + ) public String hostJavaBase; - @Option(name = "javacopt", - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Additional options to pass to javac.") + @Option( + name = "javacopt", + allowMultiple = true, + defaultValue = "", + category = "flags", + help = "Additional options to pass to javac." + ) public List<String> javacOpts; - @Option(name = "jvmopt", - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Additional options to pass to the Java VM. These options will get added to the " - + "VM startup options of each java_binary target.") + @Option( + name = "jvmopt", + allowMultiple = true, + defaultValue = "", + category = "flags", + help = + "Additional options to pass to the Java VM. These options will get added to the " + + "VM startup options of each java_binary target." + ) public List<String> jvmOpts; - @Option(name = "use_ijars", - defaultValue = "true", - category = "strategy", - help = "If enabled, this option causes Java compilation to use interface jars. " - + "This will result in faster incremental compilation, " - + "but error messages can be different.") + @Option( + name = "use_ijars", + defaultValue = "true", + category = "strategy", + help = + "If enabled, this option causes Java compilation to use interface jars. " + + "This will result in faster incremental compilation, " + + "but error messages can be different." + ) public boolean useIjars; @Deprecated - @Option(name = "use_src_ijars", - defaultValue = "false", - category = "undocumented", - help = "No-op. Kept here for backwards compatibility.") + @Option( + name = "use_src_ijars", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "No-op. Kept here for backwards compatibility." + ) public boolean useSourceIjars; @Option( @@ -132,15 +151,17 @@ public class JavaOptions extends FragmentOptions { @Option( name = "experimental_optimize_header_compilation_annotation_processing", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "This flag is a noop and scheduled for removal." ) public boolean optimizeHeaderCompilationAnnotationProcessing; - @Option(name = "java_deps", - defaultValue = "true", - category = "strategy", - help = "Generate dependency information (for now, compile-time classpath) per Java target.") + @Option( + name = "java_deps", + defaultValue = "true", + category = "strategy", + help = "Generate dependency information (for now, compile-time classpath) per Java target." + ) public boolean javaDeps; @Option( @@ -154,15 +175,22 @@ public class JavaOptions extends FragmentOptions { ) public JavaClasspathMode javaClasspath; - @Option(name = "java_debug", - defaultValue = "null", - category = "testing", - expansion = {"--test_arg=--wrapper_script_flag=--debug", "--test_output=streamed", - "--test_strategy=exclusive", "--test_timeout=9999", "--nocache_test_results"}, - help = "Causes the Java virtual machine of a java test to wait for a connection from a " - + "JDWP-compliant debugger (such as jdb) before starting the test. Implies " - + "-test_output=streamed." - ) + @Option( + name = "java_debug", + defaultValue = "null", + category = "testing", + expansion = { + "--test_arg=--wrapper_script_flag=--debug", + "--test_output=streamed", + "--test_strategy=exclusive", + "--test_timeout=9999", + "--nocache_test_results" + }, + help = + "Causes the Java virtual machine of a java test to wait for a connection from a " + + "JDWP-compliant debugger (such as jdb) before starting the test. Implies " + + "-test_output=streamed." + ) public Void javaTestDebug; @Option( @@ -181,25 +209,31 @@ public class JavaOptions extends FragmentOptions { // TODO(bazel-team): This flag should ideally default to true (and eventually removed). We have // been accidentally supplying JUnit and Hamcrest deps to java_test targets indirectly via the // BazelTestRunner, and setting this flag to true fixes that behaviour. - @Option(name = "explicit_java_test_deps", - defaultValue = "false", - category = "semantics", - help = "Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of " - + " accidentally obtaining from the TestRunner's deps. Only works for bazel right now.") + @Option( + name = "explicit_java_test_deps", + defaultValue = "false", + category = "semantics", + help = + "Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of " + + " accidentally obtaining from the TestRunner's deps. Only works for bazel right now." + ) public boolean explicitJavaTestDeps; - @Option(name = "experimental_testrunner", - defaultValue = "false", - category = "undocumented", - help = "Use the experimental test runner in bazel which runs the tests under a separate " - + "classloader. We must set the --explicit_java_test_deps flag with this to ensure " - + "the test targets have their dependencies right.") + @Option( + name = "experimental_testrunner", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Use the experimental test runner in bazel which runs the tests under a separate " + + "classloader. We must set the --explicit_java_test_deps flag with this to ensure " + + "the test targets have their dependencies right." + ) public boolean experimentalTestRunner; @Option( name = "javabuilder_top", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String javaBuilderTop; @@ -207,7 +241,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "singlejar_top", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String singleJarTop; @@ -215,7 +249,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "genclass_top", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String genClassTop; @@ -223,7 +257,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "ijar_top", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String iJarTop; @@ -231,7 +265,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "java_langtools", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String javaLangtoolsJar; @@ -239,7 +273,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "javac_bootclasspath", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String javacBootclasspath; @@ -247,7 +281,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "javac_extdir", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "No-op. Kept here for backwards compatibility." ) public String javacExtdir; @@ -272,79 +306,99 @@ public class JavaOptions extends FragmentOptions { ) public Label javaLauncher; - @Option(name = "proguard_top", - defaultValue = "null", - category = "version", - converter = LabelConverter.class, - help = "Specifies which version of ProGuard to use for code removal when building a Java " - + "binary.") + @Option( + name = "proguard_top", + defaultValue = "null", + category = "version", + converter = LabelConverter.class, + help = + "Specifies which version of ProGuard to use for code removal when building a Java " + + "binary." + ) public Label proguard; - @Option(name = "extra_proguard_specs", - allowMultiple = true, - defaultValue = "", // Ignored - converter = LabelConverter.class, - category = "undocumented", - help = "Additional Proguard specs that will be used for all Proguard invocations. Note that " - + "using this option only has an effect when Proguard is used anyway.") + @Option( + name = "extra_proguard_specs", + allowMultiple = true, + defaultValue = "", // Ignored + converter = LabelConverter.class, + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Additional Proguard specs that will be used for all Proguard invocations. Note that " + + "using this option only has an effect when Proguard is used anyway." + ) public List<Label> extraProguardSpecs; /** * Comma-separated list of Mnemonic=label pairs of optimizers to run in the given order, treating - * {@code Proguard} specially by substituting in the relevant Proguard binary automatically. - * All optimizers must understand the same flags as Proguard. + * {@code Proguard} specially by substituting in the relevant Proguard binary automatically. All + * optimizers must understand the same flags as Proguard. */ - @Option(name = "experimental_bytecode_optimizers", - defaultValue = "Proguard", - converter = LabelMapConverter.class, - category = "undocumented", - help = "Do not use.") + @Option( + name = "experimental_bytecode_optimizers", + defaultValue = "Proguard", + converter = LabelMapConverter.class, + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Do not use." + ) public Map<String, Label> bytecodeOptimizers; - @Option(name = "translations", - defaultValue = "auto", - category = "semantics", - help = "Translate Java messages; bundle all translations into the jar " - + "for each affected rule.") + @Option( + name = "translations", + defaultValue = "auto", + category = "semantics", + help = + "Translate Java messages; bundle all translations into the jar " + "for each affected rule." + ) public TriState bundleTranslations; - @Option(name = "message_translations", - defaultValue = "", - category = "semantics", - allowMultiple = true, - help = "The message translations used for translating messages in Java targets.") + @Option( + name = "message_translations", + defaultValue = "", + category = "semantics", + allowMultiple = true, + help = "The message translations used for translating messages in Java targets." + ) public List<String> translationTargets; - @Option(name = "check_constraint", - allowMultiple = true, - defaultValue = "", - category = "checking", - help = "Check the listed constraint.") + @Option( + name = "check_constraint", + allowMultiple = true, + defaultValue = "", + category = "checking", + help = "Check the listed constraint." + ) public List<String> checkedConstraints; - @Option(name = "experimental_disable_jvm", - defaultValue = "false", - category = "undocumented", - help = "Disables the Jvm configuration entirely.") + @Option( + name = "experimental_disable_jvm", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Disables the Jvm configuration entirely." + ) public boolean disableJvm; - @Option(name = "java_optimization_mode", - defaultValue = "legacy", - converter = JavaOptimizationModeConverter.class, - category = "undocumented", - help = "Applies desired link-time optimizations to Java binaries and tests.") + @Option( + name = "java_optimization_mode", + defaultValue = "legacy", + converter = JavaOptimizationModeConverter.class, + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Applies desired link-time optimizations to Java binaries and tests." + ) public JavaOptimizationMode javaOptimizationMode; - @Option(name = "legacy_bazel_java_test", - defaultValue = "false", - category = "undocumented", - help = "Use the legacy mode of Bazel for java_test.") + @Option( + name = "legacy_bazel_java_test", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Use the legacy mode of Bazel for java_test." + ) public boolean legacyBazelJavaTest; @Option( name = "strict_deps_java_protos", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "When 'strict-deps' is on, .java files that depend on classes not declared in their rule's " + "'deps' fail to build. In other words, it's forbidden to depend on classes obtained " @@ -356,7 +410,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "experimental_java_header_compilation_direct_classpath", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Experimental option to limit the header compilation classpath to direct deps." ) public boolean headerCompilationDirectClasspath; @@ -364,7 +418,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "experimental_java_header_compilation_direct_classpath_fallback_error", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If --experimental_java_header_compilation_direct_classpath is set, transitive classpath" + " fallback is an error" @@ -374,7 +428,7 @@ public class JavaOptions extends FragmentOptions { @Option( name = "experimental_one_version_enforcement", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "When enabled, enforce that a java_binary rule can't contain more than one version " + "of the same class file on the classpath" diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java index 14d513627b..8ccf0308af 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java @@ -20,6 +20,7 @@ import com.google.devtools.build.lib.analysis.config.FragmentOptions; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.List; /** @@ -28,44 +29,51 @@ import java.util.List; * (specifically, J2ObjCAspects thereof). */ public class J2ObjcCommandLineOptions extends FragmentOptions { - @Option(name = "j2objc_translation_flags", - converter = Converters.CommaSeparatedOptionListConverter.class, - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Additional options to pass to the J2ObjC tool." - ) + @Option( + name = "j2objc_translation_flags", + converter = Converters.CommaSeparatedOptionListConverter.class, + allowMultiple = true, + defaultValue = "", + category = "flags", + help = "Additional options to pass to the J2ObjC tool." + ) public List<String> translationFlags; - @Option(name = "j2objc_dead_code_removal", - defaultValue = "false", - category = "undocumented", - help = "Whether to perform J2ObjC dead code removal to strip unused code from the final app " - + "bundle." - ) + @Option( + name = "j2objc_dead_code_removal", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Whether to perform J2ObjC dead code removal to strip unused code from the final app " + + "bundle." + ) public boolean removeDeadCode; - @Option(name = "j2objc_dead_code_report", - defaultValue = "null", - category = "undocumented", - converter = LabelConverter.class, - help = "Allows J2ObjC to strip dead code reported by ProGuard. Takes a label that can " - + "generate a dead code report as argument." + @Option( + name = "j2objc_dead_code_report", + defaultValue = "null", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = LabelConverter.class, + help = + "Allows J2ObjC to strip dead code reported by ProGuard. Takes a label that can " + + "generate a dead code report as argument." ) public Label deadCodeReport; - @Option(name = "explicit_jre_deps", - defaultValue = "true", - category = "flags", - help = "Requires JRE dependencies to be declared in j2objc_library's jre_deps attribute." - ) + @Option( + name = "explicit_jre_deps", + defaultValue = "true", + category = "flags", + help = "Requires JRE dependencies to be declared in j2objc_library's jre_deps attribute." + ) public boolean explicitJreDeps; - @Option(name = "experimental_j2objc_header_map", - defaultValue = "false", - category = "flags", - help = "Whether to generate J2ObjC header map in parallel of J2ObjC transpilation." - ) + @Option( + name = "experimental_j2objc_header_map", + defaultValue = "false", + category = "flags", + help = "Whether to generate J2ObjC header map in parallel of J2ObjC transpilation." + ) public boolean experimentalJ2ObjcHeaderMap; @Override diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java index 514e2a0c9c..1e45d7b829 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java @@ -22,7 +22,7 @@ import com.google.devtools.build.lib.rules.apple.DottedVersionConverter; import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; - +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.List; /** @@ -40,85 +40,105 @@ public class ObjcCommandLineOptions extends FragmentOptions { ) public DottedVersion iosSimulatorVersion; - @Option(name = "ios_simulator_device", - defaultValue = "iPhone 5s", - category = "run", - help = "The device to simulate when running an iOS application in the simulator, e.g. " - + "'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' " - + "on the machine the simulator will be run on.") + @Option( + name = "ios_simulator_device", + defaultValue = "iPhone 5s", + category = "run", + help = + "The device to simulate when running an iOS application in the simulator, e.g. " + + "'iPhone 6'. You can get a list of devices by running 'xcrun simctl list " + + "devicetypes' on the machine the simulator will be run on." + ) public String iosSimulatorDevice; @Option( - name = "watchos_simulator_version", - defaultValue = "2.0", - category = "run", - converter = DottedVersionConverter.class, - help = "The version of watchOS to run on the simulator when running or testing." + name = "watchos_simulator_version", + defaultValue = "2.0", + category = "run", + converter = DottedVersionConverter.class, + help = "The version of watchOS to run on the simulator when running or testing." ) public DottedVersion watchosSimulatorVersion; - @Option(name = "watchos_simulator_device", - defaultValue = "Apple Watch - 38mm", - category = "run", - help = "The device to simulate when running an watchOS application in the simulator, e.g. " - + "'Apple Watch - 38mm'. You can get a list of devices by running 'xcrun simctl list " - + "devicetypes' on the machine the simulator will be run on.") + @Option( + name = "watchos_simulator_device", + defaultValue = "Apple Watch - 38mm", + category = "run", + help = + "The device to simulate when running an watchOS application in the simulator, e.g. " + + "'Apple Watch - 38mm'. You can get a list of devices by running 'xcrun simctl list " + + "devicetypes' on the machine the simulator will be run on." + ) public String watchosSimulatorDevice; @Option( - name = "tvos_simulator_version", - defaultValue = "9.0", - category = "run", - converter = DottedVersionConverter.class, - help = "The version of tvOS to run on the simulator when running or testing." + name = "tvos_simulator_version", + defaultValue = "9.0", + category = "run", + converter = DottedVersionConverter.class, + help = "The version of tvOS to run on the simulator when running or testing." ) public DottedVersion tvosSimulatorVersion; - @Option(name = "tvos_simulator_device", - defaultValue = "Apple TV 1080p", - category = "run", - help = "The device to simulate when running an tvOS application in the simulator, e.g. " - + "'Apple TV 1080p'. You can get a list of devices by running 'xcrun simctl list " - + "devicetypes' on the machine the simulator will be run on.") + @Option( + name = "tvos_simulator_device", + defaultValue = "Apple TV 1080p", + category = "run", + help = + "The device to simulate when running an tvOS application in the simulator, e.g. " + + "'Apple TV 1080p'. You can get a list of devices by running 'xcrun simctl list " + + "devicetypes' on the machine the simulator will be run on." + ) public String tvosSimulatorDevice; - @Option(name = "objc_generate_linkmap", - defaultValue = "false", - category = "flags", - help = "Specifies whether to generate a linkmap file.") + @Option( + name = "objc_generate_linkmap", + defaultValue = "false", + category = "flags", + help = "Specifies whether to generate a linkmap file." + ) public boolean generateLinkmap; - @Option(name = "objccopt", - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Additional options to pass to Objective C compilation.") + @Option( + name = "objccopt", + allowMultiple = true, + defaultValue = "", + category = "flags", + help = "Additional options to pass to Objective C compilation." + ) public List<String> copts; - @Option(name = "ios_memleaks", - defaultValue = "false", - category = "misc", - help = "Enable checking for memory leaks in ios_test targets.") + @Option( + name = "ios_memleaks", + defaultValue = "false", + category = "misc", + help = "Enable checking for memory leaks in ios_test targets." + ) public boolean runMemleaks; - @Option(name = "experimental_enable_objc_cc_deps", - defaultValue = "false", - category = "undocumented", - help = "Allows objc_* rules to depend on cc_library and causes any objc dependencies to be " - + "built with --cpu set to \"ios_<--ios_cpu>\" for any values in --ios_multi_cpu.") + @Option( + name = "experimental_enable_objc_cc_deps", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "Allows objc_* rules to depend on cc_library and causes any objc dependencies to be " + + "built with --cpu set to \"ios_<--ios_cpu>\" for any values in --ios_multi_cpu." + ) public boolean enableCcDeps; - @Option(name = "experimental_objc_fastbuild_options", - defaultValue = "-O0,-DDEBUG=1", - category = "undocumented", - converter = CommaSeparatedOptionListConverter.class, - help = "Uses these strings as objc fastbuild compiler options.") + @Option( + name = "experimental_objc_fastbuild_options", + defaultValue = "-O0,-DDEBUG=1", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = CommaSeparatedOptionListConverter.class, + help = "Uses these strings as objc fastbuild compiler options." + ) public List<String> fastbuildOptions; @Option( name = "experimental_objc_enable_module_maps", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Enables module map generation and interpretation." ) public boolean enableModuleMaps; @@ -156,7 +176,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { @Option( name = "experimental_use_absolute_paths_for_actions", defaultValue = "false", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If set, then all actions objc actions will be executed with absolute paths." ) public boolean useAbsolutePathsForActions; @@ -184,10 +204,10 @@ public class ObjcCommandLineOptions extends FragmentOptions { @Option( name = "objc_debug_with_GLIBCXX", defaultValue = "true", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = - "If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, " - + " GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS." + "If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, " + + " GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS." ) public boolean debugWithGlibcxx; @@ -213,17 +233,15 @@ public class ObjcCommandLineOptions extends FragmentOptions { public boolean deviceDebugEntitlements; @Option( - name = "deprecated_generate_xcode_project", - defaultValue = "false", - category = "flags", - help = - "If set, will generate xcode project for targets that support this. Will be removed soon." + name = "deprecated_generate_xcode_project", + defaultValue = "false", + category = "flags", + help = + "If set, will generate xcode project for targets that support this. Will be removed soon." ) public boolean generateXcodeProject; - /** - * Specifies the circumstances under which a CROSSTOOL is used for objc in this configuration. - */ + /** Specifies the circumstances under which a CROSSTOOL is used for objc in this configuration. */ public enum ObjcCrosstoolMode { /** The CROSSTOOL is used for all objc compile, archive, and link actions. */ ALL, @@ -238,9 +256,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { OFF } - /** - * Converter for {@link ObjcCrosstoolMode}. - */ + /** Converter for {@link ObjcCrosstoolMode}. */ public static class ObjcCrosstoolUsageConverter extends EnumConverter<ObjcCrosstoolMode> { public ObjcCrosstoolUsageConverter() { super(ObjcCrosstoolMode.class, "objc crosstool mode"); @@ -248,18 +264,18 @@ public class ObjcCommandLineOptions extends FragmentOptions { } @Option( - name = "experimental_objc_crosstool", - defaultValue = "off", - category = "undocumented", - converter = ObjcCrosstoolUsageConverter.class + name = "experimental_objc_crosstool", + defaultValue = "off", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = ObjcCrosstoolUsageConverter.class ) public ObjcCrosstoolMode objcCrosstoolMode; // TODO(b/34260565): Remove in favor of --experimental_objc_crosstool @Option( - name = "experimental_objc_library", - defaultValue = "false", - category = "undocumented" + name = "experimental_objc_library", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED ) public boolean experimentalObjcLibrary; @@ -277,8 +293,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "enable_apple_binary_native_protos", defaultValue = "true", category = "flags", - help = - "If set, apple_binary will generate and link objc protos into the output binary." + help = "If set, apple_binary will generate and link objc protos into the output binary." ) public boolean enableAppleBinaryNativeProtos; @@ -295,7 +310,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { @Option( name = "objc_header_thinning_partition_size", defaultValue = "120", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "The maximum number of source files to process within in each header scanning action." ) public int objcHeaderThinningPartitionSize; @@ -303,7 +318,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { @Option( name = "objc_header_scanner_tool", defaultValue = "@bazel_tools//tools/objc:header_scanner", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, help = "Location of tool to scan Objective-C code for inclusions and output a .headers_list " @@ -314,7 +329,7 @@ public class ObjcCommandLineOptions extends FragmentOptions { @Option( name = "apple_sdk", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, help = "Location of target that will provide the appropriate Apple SDK for the current build " diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java index 601f37f5fd..f1906fa003 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java @@ -21,6 +21,7 @@ import com.google.devtools.build.lib.util.io.OutErr; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.io.IOException; import java.io.OutputStream; import java.io.PrintStream; @@ -56,102 +57,130 @@ public class BlazeCommandEventHandler implements EventHandler { public static class Options extends OptionsBase { - @Option(name = "show_progress", - defaultValue = "true", - category = "verbosity", - help = "Display progress messages during a build.") + @Option( + name = "show_progress", + defaultValue = "true", + category = "verbosity", + help = "Display progress messages during a build." + ) public boolean showProgress; - @Option(name = "show_task_finish", - defaultValue = "false", - category = "verbosity", - help = "Display progress messages when tasks complete, not just when they start.") + @Option( + name = "show_task_finish", + defaultValue = "false", + category = "verbosity", + help = "Display progress messages when tasks complete, not just when they start." + ) public boolean showTaskFinish; - @Option(name = "show_progress_rate_limit", - defaultValue = "0.03", // A nice middle ground; snappy but not too spammy in logs. - category = "verbosity", - help = "Minimum number of seconds between progress messages in the output.") + @Option( + name = "show_progress_rate_limit", + defaultValue = "0.03", // A nice middle ground; snappy but not too spammy in logs. + category = "verbosity", + help = "Minimum number of seconds between progress messages in the output." + ) public double showProgressRateLimit; - @Option(name = "color", - defaultValue = "auto", - converter = UseColorConverter.class, - category = "verbosity", - help = "Use terminal controls to colorize output.") + @Option( + name = "color", + defaultValue = "auto", + converter = UseColorConverter.class, + category = "verbosity", + help = "Use terminal controls to colorize output." + ) public UseColor useColorEnum; - @Option(name = "curses", - defaultValue = "auto", - converter = UseCursesConverter.class, - category = "verbosity", - help = "Use terminal cursor controls to minimize scrolling output") + @Option( + name = "curses", + defaultValue = "auto", + converter = UseCursesConverter.class, + category = "verbosity", + help = "Use terminal cursor controls to minimize scrolling output" + ) public UseCurses useCursesEnum; - @Option(name = "terminal_columns", - defaultValue = "80", - category = "hidden", - help = "A system-generated parameter which specifies the terminal " - + " width in columns.") + @Option( + name = "terminal_columns", + defaultValue = "80", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "A system-generated parameter which specifies the terminal width in columns." + ) public int terminalColumns; - @Option(name = "isatty", - defaultValue = "false", - category = "hidden", - help = "A system-generated parameter which is used to notify the " - + "server whether this client is running in a terminal. " - + "If this is set to false, then '--color=auto' will be treated as '--color=no'. " - + "If this is set to true, then '--color=auto' will be treated as '--color=yes'.") + @Option( + name = "isatty", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "A system-generated parameter which is used to notify the " + + "server whether this client is running in a terminal. " + + "If this is set to false, then '--color=auto' will be treated as '--color=no'. " + + "If this is set to true, then '--color=auto' will be treated as '--color=yes'." + ) public boolean isATty; // This lives here (as opposed to the more logical BuildRequest.Options) // because the client passes it to the server *always*. We don't want the // client to have to figure out when it should or shouldn't to send it. - @Option(name = "emacs", - defaultValue = "false", - category = "undocumented", - help = "A system-generated parameter which is true iff EMACS=t or INSIDE_EMACS is set " - + "in the environment of the client. This option controls certain display " - + "features.") + @Option( + name = "emacs", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "A system-generated parameter which is true iff EMACS=t or INSIDE_EMACS is set " + + "in the environment of the client. This option controls certain display " + + "features." + ) public boolean runningInEmacs; - @Option(name = "show_timestamps", - defaultValue = "false", - category = "verbosity", - help = "Include timestamps in messages") + @Option( + name = "show_timestamps", + defaultValue = "false", + category = "verbosity", + help = "Include timestamps in messages" + ) public boolean showTimestamp; - @Option(name = "progress_in_terminal_title", - defaultValue = "false", - category = "verbosity", - help = "Show the command progress in the terminal title. " - + "Useful to see what blaze is doing when having multiple terminal tabs.") + @Option( + name = "progress_in_terminal_title", + defaultValue = "false", + category = "verbosity", + help = + "Show the command progress in the terminal title. " + + "Useful to see what blaze is doing when having multiple terminal tabs." + ) public boolean progressInTermTitle; - @Option(name = "experimental_external_repositories", - defaultValue = "false", - category = "verbosity", - help = "Use external repositories for improved stability and speed when available.") + @Option( + name = "experimental_external_repositories", + defaultValue = "false", + category = "verbosity", + help = "Use external repositories for improved stability and speed when available." + ) public boolean externalRepositories; - @Option(name = "force_experimental_external_repositories", - defaultValue = "false", - category = "verbosity", - help = "Forces --experimental_external_repositories.") + @Option( + name = "force_experimental_external_repositories", + defaultValue = "false", + category = "verbosity", + help = "Forces --experimental_external_repositories." + ) public boolean forceExternalRepositories; @Option( name = "experimental_ui", defaultValue = "false", category = "verbosity", - help = "Switches to an alternative progress bar that more explicitly shows progress, such " - + "as loaded packages and executed actions.") + help = + "Switches to an alternative progress bar that more explicitly shows progress, such " + + "as loaded packages and executed actions." + ) public boolean experimentalUi; @Option( name = "experimental_ui_debug_all_events", defaultValue = "false", - category = "hidden", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "Report all events known to the experimental new Bazel UI." ) public boolean experimentalUiDebugAllEvents; diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java index 64a9da783e..f57d9d9671 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java @@ -19,6 +19,7 @@ import com.google.devtools.build.lib.vfs.PathFragment; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import java.util.Map; /** @@ -74,21 +75,25 @@ public class BlazeServerStartupOptions extends OptionsBase { * responsibility of the client to compute a proper default if * necessary. */ - @Option(name = "install_base", - defaultValue = "", // NOTE: purely decorative! See class docstring. - category = "hidden", - converter = OptionsUtils.PathFragmentConverter.class, - help = "This launcher option is intended for use only by tests.") + @Option( + name = "install_base", + defaultValue = "", // NOTE: purely decorative! See class docstring. + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = OptionsUtils.PathFragmentConverter.class, + help = "This launcher option is intended for use only by tests." + ) public PathFragment installBase; /* * The installation MD5 - a content hash of the blaze binary (includes the Blaze deploy JAR and * any other embedded binaries - anything that ends up in the install_base). */ - @Option(name = "install_md5", - defaultValue = "", // NOTE: purely decorative! See class docstring. - category = "hidden", - help = "This launcher option is intended for use only by tests.") + @Option( + name = "install_md5", + defaultValue = "", // NOTE: purely decorative! See class docstring. + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "This launcher option is intended for use only by tests." + ) public String installMD5; /* Note: The help string in this option applies to the client code; not @@ -96,137 +101,177 @@ public class BlazeServerStartupOptions extends OptionsBase { * the responsibility of the client to compute a proper default if * necessary. */ - @Option(name = "output_base", - defaultValue = "null", // NOTE: purely decorative! See class docstring. - category = "server startup", - converter = OptionsUtils.PathFragmentConverter.class, - valueHelp = "<path>", - help = "If set, specifies the output location to which all build output will be written. " - + "Otherwise, the location will be " - + "${OUTPUT_ROOT}/_blaze_${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a " - + "different option from one to the next Blaze invocation for this value, you'll likely " - + "start up a new, additional Blaze server. Blaze starts exactly one server per " - + "specified output base. Typically there is one output base per workspace - however, " - + "with this option you may have multiple output bases per workspace and thereby run " - + "multiple builds for the same client on the same machine concurrently. See " - + "'blaze help shutdown' on how to shutdown a Blaze server.") + @Option( + name = "output_base", + defaultValue = "null", // NOTE: purely decorative! See class docstring. + category = "server startup", + converter = OptionsUtils.PathFragmentConverter.class, + valueHelp = "<path>", + help = + "If set, specifies the output location to which all build output will be written. " + + "Otherwise, the location will be " + + "${OUTPUT_ROOT}/_blaze_${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a " + + "different option from one to the next Blaze invocation for this value, you'll " + + "likely start up a new, additional Blaze server. Blaze starts exactly one server per " + + "specified output base. Typically there is one output base per workspace - however, " + + "with this option you may have multiple output bases per workspace and thereby run " + + "multiple builds for the same client on the same machine concurrently. See " + + "'blaze help shutdown' on how to shutdown a Blaze server." + ) public PathFragment outputBase; /* Note: This option is only used by the C++ client, never by the Java server. * It is included here to make sure that the option is documented in the help * output, which is auto-generated by Java code. */ - @Option(name = "output_user_root", - defaultValue = "null", // NOTE: purely decorative! See class docstring. - category = "server startup", - converter = OptionsUtils.PathFragmentConverter.class, - valueHelp = "<path>", - help = "The user-specific directory beneath which all build outputs are written; " - + "by default, this is a function of $USER, but by specifying a constant, build outputs " - + "can be shared between collaborating users.") + @Option( + name = "output_user_root", + defaultValue = "null", // NOTE: purely decorative! See class docstring. + category = "server startup", + converter = OptionsUtils.PathFragmentConverter.class, + valueHelp = "<path>", + help = + "The user-specific directory beneath which all build outputs are written; by default, " + + "this is a function of $USER, but by specifying a constant, build outputs can be " + + "shared between collaborating users." + ) public PathFragment outputUserRoot; - @Option(name = "workspace_directory", - defaultValue = "", - category = "hidden", - converter = OptionsUtils.PathFragmentConverter.class, - help = "The root of the workspace, that is, the directory that Blaze uses as the root of the " - + "build. This flag is only to be set by the blaze client.") + @Option( + name = "workspace_directory", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = OptionsUtils.PathFragmentConverter.class, + help = + "The root of the workspace, that is, the directory that Blaze uses as the root of the " + + "build. This flag is only to be set by the blaze client." + ) public PathFragment workspaceDirectory; - @Option(name = "max_idle_secs", - defaultValue = "" + (3 * 3600), // NOTE: purely decorative! See class docstring. - category = "server startup", - valueHelp = "<integer>", - help = "The number of seconds the build server will wait idling before shutting down. Zero " - + "means that the server will never shutdown.") + @Option( + name = "max_idle_secs", + defaultValue = "" + (3 * 3600), // NOTE: purely decorative! See class docstring. + category = "server startup", + valueHelp = "<integer>", + help = + "The number of seconds the build server will wait idling before shutting down. Zero " + + "means that the server will never shutdown." + ) public int maxIdleSeconds; - @Option(name = "batch", - defaultValue = "false", // NOTE: purely decorative! See class docstring. - category = "server startup", - help = "If set, Blaze will be run in batch mode, instead of the standard client/server mode. " - + "Running in batch mode prevents Blaze from caching data in memory, which makes it a " - + "lot slower. We recommend against using this flag.") + @Option( + name = "batch", + defaultValue = "false", // NOTE: purely decorative! See class docstring. + category = "server startup", + help = + "If set, Blaze will be run in batch mode, instead of the standard client/server mode. " + + "Running in batch mode prevents Blaze from caching data in memory, which makes it a " + + "lot slower. We recommend against using this flag." + ) public boolean batch; - @Option(name = "deep_execroot", - defaultValue = "true", // NOTE: purely decorative! See class docstring. - category = "server startup", - help = "If set, the execution root will be under $OUTPUT_BASE/execroot instead of " - + "$OUTPUT_BASE.") + @Option( + name = "deep_execroot", + defaultValue = "true", // NOTE: purely decorative! See class docstring. + category = "server startup", + help = + "If set, the execution root will be under $OUTPUT_BASE/execroot instead of " + + "$OUTPUT_BASE." + ) public boolean deepExecRoot; @Option( name = "experimental_oom_more_eagerly", defaultValue = "false", // NOTE: purely decorative! See class docstring. category = "server startup", - help = "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only " - + "honored when --batch is also passed. In some cases, builds that previously succeeded " - + "may OOM if they were close to OOMing before.") + help = + "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only " + + "honored when --batch is also passed. In some cases, builds that previously " + + "succeeded may OOM if they were close to OOMing before." + ) public boolean oomMoreEagerly; @Option( name = "experimental_oom_more_eagerly_threshold", defaultValue = "100", // NOTE: purely decorative! See class docstring. category = "server startup", - help = "If this flag is set, Blaze will OOM if, after two full GC's, more than this " - + "percentage of the (old gen) heap is still occupied.") + help = + "If this flag is set, Blaze will OOM if, after two full GC's, more than this " + + "percentage of the (old gen) heap is still occupied." + ) public int oomMoreEagerlyThreshold; - @Option(name = "block_for_lock", - defaultValue = "true", // NOTE: purely decorative! See class docstring. - category = "server startup", - help = "When --noblock_for_lock is passed, Blaze does not wait for a running command to " - + "complete, but instead exits immediately.") + @Option( + name = "block_for_lock", + defaultValue = "true", // NOTE: purely decorative! See class docstring. + category = "server startup", + help = + "When --noblock_for_lock is passed, Blaze does not wait for a running command to " + + "complete, but instead exits immediately." + ) public boolean blockForLock; - @Option(name = "io_nice_level", - defaultValue = "-1", // NOTE: purely decorative! - category = "server startup", - valueHelp = "{-1,0,1,2,3,4,5,6,7}", - help = "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the " - + "sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory " - + "scheduler may only honor up to priority 4. If set to a negative value, then Blaze " - + "does not perform a system call.") + @Option( + name = "io_nice_level", + defaultValue = "-1", // NOTE: purely decorative! + category = "server startup", + valueHelp = "{-1,0,1,2,3,4,5,6,7}", + help = + "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the " + + "sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory " + + "scheduler may only honor up to priority 4. If set to a negative value, then Blaze " + + "does not perform a system call." + ) public int ioNiceLevel; - @Option(name = "batch_cpu_scheduling", - defaultValue = "false", // NOTE: purely decorative! - category = "server startup", - help = "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for " - + "workloads that are non-interactive, but do not want to lower their nice value. " - + "See 'man 2 sched_setscheduler'. If false, then Blaze does not perform a system call.") + @Option( + name = "batch_cpu_scheduling", + defaultValue = "false", // NOTE: purely decorative! + category = "server startup", + help = + "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for " + + "workloads that are non-interactive, but do not want to lower their nice value. " + + "See 'man 2 sched_setscheduler'. If false, then Blaze does not perform a system call." + ) public boolean batchCpuScheduling; - @Option(name = "blazerc", - defaultValue = "null", // NOTE: purely decorative! - category = "misc", - valueHelp = "<path>", - help = "The location of the .%{product}rc file containing default values of " - + "Blaze command options. By default, Blaze first checks the current directory, then " - + "the user's home directory, and then looks for a file named .$(basename $0)rc " - + "(i.e. .%{product}rc). Use /dev/null to disable the search for a %{product}rc file, " - + "e.g. in release builds.") + @Option( + name = "blazerc", + defaultValue = "null", // NOTE: purely decorative! + category = "misc", + valueHelp = "<path>", + help = + "The location of the .%{product}rc file containing default values of " + + "Blaze command options. By default, Blaze first checks the current directory, then " + + "the user's home directory, and then looks for a file named .$(basename $0)rc " + + "(i.e. .%{product}rc). Use /dev/null to disable the search for a %{product}rc file, " + + "e.g. in release builds." + ) public String blazerc; - @Option(name = "master_blazerc", - defaultValue = "true", // NOTE: purely decorative! - category = "misc", - help = "If this option is false, the master %{product}rc next to the binary is not read.") + @Option( + name = "master_blazerc", + defaultValue = "true", // NOTE: purely decorative! + category = "misc", + help = "If this option is false, the master %{product}rc next to the binary is not read." + ) public boolean masterBlazerc; - @Option(name = "fatal_event_bus_exceptions", - defaultValue = "false", // NOTE: purely decorative! - category = "undocumented", - help = "Whether or not to exit if an exception is thrown by an internal EventBus handler.") + @Option( + name = "fatal_event_bus_exceptions", + defaultValue = "false", // NOTE: purely decorative! + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Whether or not to exit if an exception is thrown by an internal EventBus handler." + ) public boolean fatalEventBusExceptions; - @Option(name = "option_sources", - converter = OptionSourcesConverter.class, - defaultValue = "", - category = "hidden", - help = "") + @Option( + name = "option_sources", + converter = OptionSourcesConverter.class, + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "" + ) public Map<String, String> optionSources; // TODO(bazel-team): In order to make it easier to have local watchers in open source Bazel, @@ -241,49 +286,65 @@ public class BlazeServerStartupOptions extends OptionsBase { ) public boolean watchFS; - @Option(name = "invocation_policy", - defaultValue = "", - category = "undocumented", - help = "A base64-encoded-binary-serialized or text-formated " - + "invocation_policy.InvocationPolicy proto. Unlike other options, it is an error to " - + "specify --invocation_policy multiple times.") + @Option( + name = "invocation_policy", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "A base64-encoded-binary-serialized or text-formated " + + "invocation_policy.InvocationPolicy proto. Unlike other options, it is an error to " + + "specify --invocation_policy multiple times." + ) public String invocationPolicy; - @Option(name = "command_port", - defaultValue = "0", - category = "undocumented", - help = "Port to start up the gRPC command server on. If 0, let the kernel choose.") + @Option( + name = "command_port", + defaultValue = "0", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Port to start up the gRPC command server on. If 0, let the kernel choose." + ) public int commandPort; - @Option(name = "product_name", - defaultValue = "bazel", // NOTE: purely decorative! - category = "hidden", - help = "The name of the build system. It is used as part of the name of the generated " - + "directories (e.g. productName-bin for binaries) as well as for printing error " - + "messages and logging") + @Option( + name = "product_name", + defaultValue = "bazel", // NOTE: purely decorative! + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "The name of the build system. It is used as part of the name of the generated " + + "directories (e.g. productName-bin for binaries) as well as for printing error " + + "messages and logging" + ) public String productName; - @Option(name = "exoblaze", - defaultValue = "false", - category = "server startup", - help = "If true, Blaze runs as Exoblaze") + @Option( + name = "exoblaze", + defaultValue = "false", + category = "server startup", + help = "If true, Blaze runs as Exoblaze" + ) public boolean exoblaze; - @Option(name = "write_command_log", - defaultValue = "true", - category = "undocumented", - help = "Whether or not to write the command.log file") + @Option( + name = "write_command_log", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Whether or not to write the command.log file" + ) public boolean writeCommandLog; - @Option(name = "client_debug", - defaultValue = "false", // NOTE: purely decorative! - category = "server startup", - help = "If true, log debug information from the client to stderr") + @Option( + name = "client_debug", + defaultValue = "false", // NOTE: purely decorative! + category = "server startup", + help = "If true, log debug information from the client to stderr" + ) public boolean clientDebug; - @Option(name = "connect_timeout_secs", - defaultValue = "10", - category = "server startup", - help = "The amount of time the client waits for each attempt to connect to the server") + @Option( + name = "connect_timeout_secs", + defaultValue = "10", + category = "server startup", + help = "The amount of time the client waits for each attempt to connect to the server" + ) public int connectTimeoutSecs; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java index 8e6cc14b31..76d97151e2 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java @@ -19,6 +19,7 @@ import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import java.util.List; import java.util.Map; @@ -109,167 +110,206 @@ public class CommonCommandOptions extends OptionsBase { ) public Void allIncompatibleChanges; - @Option(name = "config", - defaultValue = "", - category = "misc", - allowMultiple = true, - help = "Selects additional config sections from the rc files; for every <command>, it " - + "also pulls in the options from <command>:<config> if such a section exists; " - + "if the section does not exist, this flag is ignored. " - + "Note that it is currently only possible to provide these options on the " - + "command line, not in the rc files. The config sections and flag combinations " - + "they are equivalent to are located in the tools/*.blazerc config files.") + @Option( + name = "config", + defaultValue = "", + category = "misc", + allowMultiple = true, + help = + "Selects additional config sections from the rc files; for every <command>, it " + + "also pulls in the options from <command>:<config> if such a section exists; " + + "if the section does not exist, this flag is ignored. " + + "Note that it is currently only possible to provide these options on the " + + "command line, not in the rc files. The config sections and flag combinations " + + "they are equivalent to are located in the tools/*.blazerc config files." + ) public List<String> configs; - @Option(name = "logging", - defaultValue = "3", // Level.INFO - category = "verbosity", - converter = Converters.LogLevelConverter.class, - help = "The logging level.") + @Option( + name = "logging", + defaultValue = "3", // Level.INFO + category = "verbosity", + converter = Converters.LogLevelConverter.class, + help = "The logging level." + ) public Level verbosity; - @Option(name = "client_env", - defaultValue = "", - category = "hidden", - converter = Converters.AssignmentConverter.class, - allowMultiple = true, - help = "A system-generated parameter which specifies the client's environment") + @Option( + name = "client_env", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = Converters.AssignmentConverter.class, + allowMultiple = true, + help = "A system-generated parameter which specifies the client's environment" + ) public List<Map.Entry<String, String>> clientEnv; - @Option(name = "ignore_client_env", - defaultValue = "false", - category = "hidden", - deprecationWarning = "Deprecated, no-op.", - help = "Deprecated, no-op." + @Option( + name = "ignore_client_env", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + deprecationWarning = "Deprecated, no-op.", + help = "Deprecated, no-op." ) // TODO(laszlocsomor, dslomov) 2017-03-07: remove this flag after 2017-06-01 (~3 months from now) // and all of its occurrences. public boolean ignoreClientEnv; - @Option(name = "client_cwd", - defaultValue = "", - category = "hidden", - converter = OptionsUtils.PathFragmentConverter.class, - help = "A system-generated parameter which specifies the client's working directory") + @Option( + name = "client_cwd", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = OptionsUtils.PathFragmentConverter.class, + help = "A system-generated parameter which specifies the client's working directory" + ) public PathFragment clientCwd; - @Option(name = "announce_rc", - defaultValue = "false", - category = "verbosity", - help = "Whether to announce rc options.") + @Option( + name = "announce_rc", + defaultValue = "false", + category = "verbosity", + help = "Whether to announce rc options." + ) public boolean announceRcOptions; /** - * These are the actual default overrides. - * Each value is a pair of (command name, value). + * These are the actual default overrides. Each value is a pair of (command name, value). * - * For example: "--default_override=build=--cpu=piii" + * <p>For example: "--default_override=build=--cpu=piii" */ - @Option(name = "default_override", - defaultValue = "", - allowMultiple = true, - category = "hidden", - converter = OptionOverrideConverter.class, - help = "") + @Option( + name = "default_override", + defaultValue = "", + allowMultiple = true, + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + converter = OptionOverrideConverter.class, + help = "" + ) public List<OptionOverride> optionsOverrides; - /** - * This is the filename that the Blaze client parsed. - */ - @Option(name = "rc_source", - defaultValue = "", - allowMultiple = true, - category = "hidden", - help = "") + /** This is the filename that the Blaze client parsed. */ + @Option( + name = "rc_source", + defaultValue = "", + allowMultiple = true, + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "" + ) public List<String> rcSource; - @Option(name = "always_profile_slow_operations", - defaultValue = "true", - category = "undocumented", - help = "Whether profiling slow operations is always turned on") + @Option( + name = "always_profile_slow_operations", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = "Whether profiling slow operations is always turned on" + ) public boolean alwaysProfileSlowOperations; - @Option(name = "profile", - defaultValue = "null", - category = "misc", - converter = OptionsUtils.PathFragmentConverter.class, - help = "If set, profile Blaze and write data to the specified " - + "file. Use blaze analyze-profile to analyze the profile.") + @Option( + name = "profile", + defaultValue = "null", + category = "misc", + converter = OptionsUtils.PathFragmentConverter.class, + help = + "If set, profile Blaze and write data to the specified " + + "file. Use blaze analyze-profile to analyze the profile." + ) public PathFragment profilePath; - @Option(name = "record_full_profiler_data", - defaultValue = "false", - category = "undocumented", - help = "By default, Blaze profiler will record only aggregated data for fast but numerous " - + "events (such as statting the file). If this option is enabled, profiler will record " - + "each event - resulting in more precise profiling data but LARGE performance " - + "hit. Option only has effect if --profile used as well.") + @Option( + name = "record_full_profiler_data", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + help = + "By default, Blaze profiler will record only aggregated data for fast but numerous " + + "events (such as statting the file). If this option is enabled, profiler will record " + + "each event - resulting in more precise profiling data but LARGE performance " + + "hit. Option only has effect if --profile used as well." + ) public boolean recordFullProfilerData; - @Option(name = "memory_profile", - defaultValue = "null", - category = "undocumented", - converter = OptionsUtils.PathFragmentConverter.class, - help = "If set, write memory usage data to the specified " - + "file at phase ends.") + @Option( + name = "memory_profile", + defaultValue = "null", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + converter = OptionsUtils.PathFragmentConverter.class, + help = "If set, write memory usage data to the specified " + "file at phase ends." + ) public PathFragment memoryProfilePath; - @Option(name = "gc_watchdog", - defaultValue = "false", - category = "undocumented", - deprecationWarning = "Ignoring: this option is no longer supported", - help = "Deprecated.") + @Option( + name = "gc_watchdog", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + deprecationWarning = "Ignoring: this option is no longer supported", + help = "Deprecated." + ) public boolean gcWatchdog; - @Option(name = "startup_time", - defaultValue = "0", - category = "hidden", - help = "The time in ms the launcher spends before sending the request to the blaze server.") + @Option( + name = "startup_time", + defaultValue = "0", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "The time in ms the launcher spends before sending the request to the blaze server." + ) public long startupTime; @Option( name = "extract_data_time", defaultValue = "0", - category = "hidden", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The time in ms spent on extracting the new blaze version." ) public long extractDataTime; - @Option(name = "command_wait_time", - defaultValue = "0", - category = "hidden", - help = "The time in ms a command had to wait on a busy Blaze server process.") + @Option( + name = "command_wait_time", + defaultValue = "0", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "The time in ms a command had to wait on a busy Blaze server process." + ) public long waitTime; - @Option(name = "tool_tag", - defaultValue = "", - category = "misc", - help = "A tool name to attribute this Blaze invocation to.") + @Option( + name = "tool_tag", + defaultValue = "", + category = "misc", + help = "A tool name to attribute this Blaze invocation to." + ) public String toolTag; - @Option(name = "restart_reason", - defaultValue = "no_restart", - category = "hidden", - help = "The reason for the server restart.") + @Option( + name = "restart_reason", + defaultValue = "no_restart", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "The reason for the server restart." + ) public String restartReason; - @Option(name = "binary_path", - defaultValue = "", - category = "hidden", - help = "The absolute path of the blaze binary.") + @Option( + name = "binary_path", + defaultValue = "", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "The absolute path of the blaze binary." + ) public String binaryPath; - @Option(name = "experimental_allow_project_files", - defaultValue = "false", - category = "hidden", - help = "Enable processing of +<file> parameters.") + @Option( + name = "experimental_allow_project_files", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = "Enable processing of +<file> parameters." + ) public boolean allowProjectFiles; - @Option(name = "block_for_lock", - defaultValue = "true", - category = "hidden", - help = "If set (the default), a command will block if there is another one running. If " - + "unset, these commands will immediately return with an error.") + @Option( + name = "block_for_lock", + defaultValue = "true", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + help = + "If set (the default), a command will block if there is another one running. If " + + "unset, these commands will immediately return with an error." + ) public boolean blockForLock; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java index 01519a54a1..2831e6babe 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java @@ -29,6 +29,7 @@ import com.google.devtools.build.lib.util.ExitCode; import com.google.devtools.common.options.Option; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; +import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import com.google.devtools.common.options.OptionsProvider; import java.util.Collection; @@ -87,13 +88,17 @@ public final class CanonicalizeCommand implements BlazeCommand { * are undocumented no-ops, and are not to be used by anything outside of that test. */ public static class FlagClashCanaryOptions extends OptionsBase { - @Option(name = "flag_clash_canary", defaultValue = "false", category = "undocumented") + @Option( + name = "flag_clash_canary", + defaultValue = "false", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED + ) public boolean flagClashCanary; @Option( name = "flag_clash_canary_expander1", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, expansion = {"--flag_clash_canary=1"} ) public Void flagClashCanaryExpander1; @@ -101,7 +106,7 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "flag_clash_canary_expander2", defaultValue = "null", - category = "undocumented", + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, expansion = {"--flag_clash_canary=0"} ) public Void flagClashCanaryExpander2; |