diff options
Diffstat (limited to 'src/main/java/com/google')
63 files changed, 1484 insertions, 354 deletions
diff --git a/src/main/java/com/google/devtools/build/docgen/BUILD b/src/main/java/com/google/devtools/build/docgen/BUILD index 1c7405fdfb..07aa167135 100644 --- a/src/main/java/com/google/devtools/build/docgen/BUILD +++ b/src/main/java/com/google/devtools/build/docgen/BUILD @@ -23,6 +23,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/rules/objc", "//src/main/java/com/google/devtools/build/lib/rules/platform", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:apache_velocity", "//third_party:guava", "//third_party:jsr305", @@ -38,6 +39,7 @@ java_binary( "//src/main/java/com/google/devtools/build/lib:bazel-rules", "//src/main/java/com/google/devtools/build/lib:build-base", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", ], ) diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java index 92e51a219f..f77ad5b482 100644 --- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java +++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java @@ -14,7 +14,9 @@ package com.google.devtools.build.docgen; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -26,6 +28,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { abbrev = 'i', defaultValue = "", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "An input directory to read source files" ) public List<String> inputDirs; @@ -34,6 +38,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { name = "provider", abbrev = 'p', defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The name of the rule class provider" ) public String provider; @@ -42,6 +48,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { name = "output_dir", abbrev = 'o', defaultValue = ".", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "An output directory." ) public String outputDir; @@ -50,6 +58,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { name = "blacklist", abbrev = 'b', defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A path to a file listing rules not to document." ) public String blacklist; @@ -58,6 +68,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { name = "single_page", abbrev = '1', defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to generate the BE as a single HTML page or one page per rule family." ) public boolean singlePage; @@ -66,6 +78,8 @@ public class BuildEncyclopediaOptions extends OptionsBase { name = "help", abbrev = 'h', defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Prints the help string." ) public boolean help; diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD index c0c72c71ca..fe6e13701f 100644 --- a/src/main/java/com/google/devtools/build/lib/BUILD +++ b/src/main/java/com/google/devtools/build/lib/BUILD @@ -371,6 +371,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/buildeventstream/proto:build_event_stream_java_proto", "//src/main/java/com/google/devtools/build/lib/buildeventstream/transports", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:joda_time", "//third_party:jsr305", @@ -396,6 +397,7 @@ java_library( ], deps = [ "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", ], ) @@ -459,6 +461,7 @@ java_library( ":vfs", "//src/main/java/com/google/devtools/build/lib/cmdline", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:asm", "//third_party:asm-commons", "//third_party:asm-util", @@ -514,6 +517,7 @@ java_library( "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects", "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:build_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", "//third_party/protobuf:protobuf_java", @@ -713,6 +717,7 @@ java_library( "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects", "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:crosstool_config_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:android_common_25_0_0", "//third_party:auto_value", "//third_party:guava", @@ -754,6 +759,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/worker", "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", ], @@ -774,6 +780,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/query2", "//src/main/java/com/google/devtools/build/lib/query2:query-engine", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", ], ) @@ -818,6 +825,7 @@ java_library( "//src/main/java/com/google/devtools/build/skyframe", "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:aether", "//third_party:apache_commons_compress", "//third_party:auto_value", @@ -876,6 +884,7 @@ java_library( ":vfs", "//src/main/java/com/google/devtools/build/lib/actions", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:auto_value", "//third_party:guava", "//third_party:jsr305", @@ -1027,6 +1036,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/rules/cpp", "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:extra_actions_base_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:auto_value", "//third_party:guava", "//third_party:joda_time", @@ -1067,6 +1077,7 @@ java_library( "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:android_deploy_info_java_proto", "//src/main/protobuf:apk_manifest_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:android_common_25_0_0", "//third_party:auto_value", "//third_party:guava", @@ -1093,6 +1104,7 @@ java_library( "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:crosstool_config_java_proto", "//src/main/protobuf:extra_actions_base_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", "//third_party/protobuf:protobuf_java", 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 ba5b06c19a..a2c9ec75a7 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,9 +95,11 @@ import com.google.devtools.build.skyframe.SkyKey; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.ArrayList; import java.util.Collection; import java.util.HashMap; @@ -168,6 +170,8 @@ public class BuildView { defaultValue = "-1", category = "what", converter = LoadingPhaseThreadCountConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Number of parallel threads to use for the loading/analysis phase." ) public int loadingPhaseThreads; @@ -177,6 +181,8 @@ public class BuildView { abbrev = 'k', defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -191,6 +197,8 @@ public class BuildView { + " an upcoming Blaze release", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Treat visible analysis warnings as errors." ) public boolean analysisWarningsAsErrors; @@ -199,6 +207,8 @@ public class BuildView { name = "discard_analysis_cache", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Discard the analysis cache immediately after the analysis phase completes." + " Reduces memory usage by ~10%, but makes further incremental builds slower." @@ -210,6 +220,8 @@ public class BuildView { defaultValue = "", category = "experimental", converter = RegexFilter.RegexFilterConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Filters set of targets to schedule extra_actions for." ) public RegexFilter extraActionFilter; @@ -218,6 +230,8 @@ public class BuildView { name = "experimental_extra_action_top_level_only", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Only schedules extra_actions for top level targets." ) public boolean extraActionTopLevelOnly; @@ -226,6 +240,8 @@ public class BuildView { name = "version_window_for_dirty_node_gc", defaultValue = "0", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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," @@ -238,6 +254,8 @@ public class BuildView { name = "experimental_interleave_loading_and_analysis", defaultValue = "true", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op." ) public boolean interleaveLoadingAndAnalysis; diff --git a/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java b/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java index dbe8ae1da0..8b3e28fc47 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java @@ -19,7 +19,9 @@ import com.google.devtools.build.lib.analysis.config.BuildConfiguration; import com.google.devtools.build.lib.analysis.config.FragmentOptions; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** Command-line options for platform-related configuration. */ @@ -29,6 +31,8 @@ public class PlatformOptions extends FragmentOptions { name = "experimental_host_platform", converter = BuildConfiguration.LabelConverter.class, defaultValue = "@bazel_tools//platforms:host_platform", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionsParser.OptionUsageRestrictions.HIDDEN, help = "Declare the platform the build is started from" ) @@ -40,6 +44,8 @@ public class PlatformOptions extends FragmentOptions { name = "experimental_platforms", converter = BuildConfiguration.LabelListConverter.class, defaultValue = "@bazel_tools//platforms:target_platform", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionsParser.OptionUsageRestrictions.HIDDEN, help = "Declare the platforms targeted by the current build" ) 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 fb8bafd171..279a1a4546 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 @@ -28,8 +28,10 @@ import com.google.devtools.build.lib.vfs.FileSystemUtils; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.util.HashMap; import java.util.List; @@ -61,6 +63,8 @@ public abstract class WorkspaceStatusAction extends AbstractAction { defaultValue = "", category = "misc", valueHelp = "<string>", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Embed source control revision or release label in binary" ) public String embedLabel; @@ -69,6 +73,8 @@ public abstract class WorkspaceStatusAction extends AbstractAction { name = "experimental_embed_timestamp_epoch", defaultValue = "-1", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Alternative timestamp to be used in stamping the binary" ) public long embedTimestampEpoch; @@ -79,6 +85,8 @@ public abstract class WorkspaceStatusAction extends AbstractAction { category = "misc", converter = OptionsUtils.PathFragmentConverter.class, valueHelp = "<path>", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A command invoked at the beginning of the build to provide status " + "information about the workspace in the form of key/value pairs. " 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 fe2f272fca..993394a2d3 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 @@ -79,9 +79,11 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; import com.google.devtools.common.options.TriState; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; @@ -464,6 +466,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "", category = "semantics", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Each --define option specifies an assignment for a build variable." ) public List<Map.Entry<String, String>> commandLineBuildVariables; @@ -473,6 +477,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "", category = "semantics", converter = AutoCpuConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The target CPU." ) public String cpu; @@ -488,6 +494,8 @@ public final class BuildConfiguration implements BuildEvent { @Option( name = "experimental multi cpu distinguisher", defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.INTERNAL ) public String experimentalMultiCpuDistinguisher; @@ -496,6 +504,8 @@ public final class BuildConfiguration implements BuildEvent { name = "min_param_file_size", defaultValue = "32768", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum command line length before creating a parameter file." ) public int minParamFileSize; @@ -504,6 +514,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_extended_sanity_checks", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables internal validation checks to make sure that configured target " + "implementations only access things they should. Causes a performance hit." @@ -514,6 +526,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_allow_runtime_deps_on_neverlink", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -524,6 +538,8 @@ public final class BuildConfiguration implements BuildEvent { name = "strict_filesets", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If this option is enabled, filesets crossing package boundaries are reported " + "as errors. It does not work when check_fileset_dependencies_recursively is " @@ -541,6 +557,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Plugins to use in the build. Currently works with java_plugin." ) public List<Label> pluginList; @@ -551,6 +569,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, category = "flags", defaultValue = ":", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Plugin options" ) public List<Map.Entry<String, String>> pluginCoptList; @@ -559,6 +579,8 @@ public final class BuildConfiguration implements BuildEvent { name = "stamp", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Stamp binaries with the date, username, hostname, workspace information, etc." ) public boolean stampBinaries; @@ -570,6 +592,8 @@ public final class BuildConfiguration implements BuildEvent { converter = RegexFilter.RegexFilterConverter.class, defaultValue = "-/javatests[/:]", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When coverage is enabled, only rules with names included by the " + "specified regex-based filter will be instrumented. Rules prefixed " @@ -582,6 +606,8 @@ public final class BuildConfiguration implements BuildEvent { name = "instrument_test_targets", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When coverage is enabled, specifies whether to consider instrumenting test rules. " + "When set, test rules included by --instrumentation_filter are instrumented. " @@ -594,6 +620,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "", category = "semantics", converter = AutoCpuConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The host CPU." ) public String hostCpu; @@ -604,6 +632,8 @@ public final class BuildConfiguration implements BuildEvent { converter = CompilationMode.Converter.class, defaultValue = "fastbuild", category = "semantics", // Should this be "flags"? + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specify the mode the binary will be built in. " + "Values: 'fastbuild', 'dbg', 'opt'." ) public CompilationMode compilationMode; @@ -616,6 +646,8 @@ public final class BuildConfiguration implements BuildEvent { @Option( name = "output directory name", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.INTERNAL ) public String outputDirectoryName; @@ -624,6 +656,8 @@ public final class BuildConfiguration implements BuildEvent { name = "platform_suffix", defaultValue = "null", category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies a suffix to be added to the configuration directory." ) public String platformSuffix; @@ -637,6 +671,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -655,6 +691,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the set of environment variables available to actions. " + "Variables can be either specified by name, in which case the value will be " @@ -669,6 +707,8 @@ public final class BuildConfiguration implements BuildEvent { name = "collect_code_coverage", defaultValue = "false", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, Bazel will instrument code (using offline instrumentation where " + "possible) and will collect coverage information during tests. Only targets that " @@ -682,6 +722,8 @@ public final class BuildConfiguration implements BuildEvent { converter = LabelConverter.class, defaultValue = "@bazel_tools//tools/test:coverage_support", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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'." @@ -693,6 +735,8 @@ public final class BuildConfiguration implements BuildEvent { converter = LabelConverter.class, defaultValue = "@bazel_tools//tools/test:coverage_report_generator", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -704,6 +748,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_use_llvm_covmap", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, Bazel will generate llvm-cov coverage map information rather than " + "gcov when collect_code_coverage is enabled." @@ -715,6 +761,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "auto", category = "testing", abbrev = 't', // it's useful to toggle this on/off quickly + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -732,6 +780,8 @@ public final class BuildConfiguration implements BuildEvent { name = "test_result_expiration", defaultValue = "-1", // No expiration by defualt. category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This option is deprecated and has no effect." ) public int testResultExpiration; @@ -741,6 +791,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "explicit", category = "testing", converter = TestActionBuilder.ShardingStrategyConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specify strategy for test sharding: " + "'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. " @@ -757,6 +809,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "1", category = "testing", converter = RunsPerTestConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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. " @@ -776,6 +830,8 @@ public final class BuildConfiguration implements BuildEvent { name = "build_runfile_links", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, build runfiles symlink forests for all targets. " + "If false, write only manifests when possible." @@ -786,6 +842,8 @@ public final class BuildConfiguration implements BuildEvent { name = "legacy_external_runfiles", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, build runfiles symlink forests for external repositories under " + ".runfiles/wsname/external/repo (in addition to .runfiles/repo)." @@ -797,6 +855,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies additional options and arguments that should be passed to the test " + "executable. Can be used multiple times to specify several arguments. " @@ -810,6 +870,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = false, defaultValue = "null", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -820,6 +882,8 @@ public final class BuildConfiguration implements BuildEvent { name = "check_fileset_dependencies_recursively", defaultValue = "true", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If false, fileset targets will, whenever possible, create " + "symlinks to directories instead of creating one symlink for each " @@ -834,6 +898,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_skyframe_native_filesets", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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" @@ -847,6 +913,8 @@ public final class BuildConfiguration implements BuildEvent { category = "run", defaultValue = "null", converter = RunUnderConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Prefix to insert in front of command before running. " + "Examples:\n" @@ -863,6 +931,8 @@ public final class BuildConfiguration implements BuildEvent { name = "distinct_host_configuration", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -882,6 +952,8 @@ public final class BuildConfiguration implements BuildEvent { name = "check_visibility", defaultValue = "true", category = "checking", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If disabled, visibility errors are demoted to warnings." ) public boolean checkVisibility; @@ -893,6 +965,8 @@ public final class BuildConfiguration implements BuildEvent { name = "check_licenses", defaultValue = "false", category = "checking", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Check that licensing constraints imposed by dependent packages " + "do not conflict with distribution modes of the targets being built. " @@ -904,6 +978,8 @@ public final class BuildConfiguration implements BuildEvent { name = "enforce_constraints", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Checks the environments each target is compatible with and reports errors if any " + "target has dependencies that don't support the same environments", @@ -917,6 +993,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "", category = "experimental", converter = LabelListConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use action_listener to attach an extra_action to existing build actions." ) public List<Label> actionListeners; @@ -928,6 +1006,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_transparent_compression", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables gzip compression for the contents of FileWriteActions, which reduces " + "memory usage in the analysis phase at the expense of additional time overhead." @@ -938,6 +1018,8 @@ public final class BuildConfiguration implements BuildEvent { name = "is host configuration", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Shows whether these options are set for host configuration." ) public boolean isHost; @@ -947,6 +1029,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The given features will be enabled or disabled by default for all packages. " + "Specifying -<feature> will disable the feature globally. " @@ -962,6 +1046,8 @@ public final class BuildConfiguration implements BuildEvent { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Declares this build's target environment. Must be a label reference to an " + "\"environment\" rule. If specified, all top-level targets must be " @@ -1002,6 +1088,8 @@ public final class BuildConfiguration implements BuildEvent { defaultValue = "notrim", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = DynamicConfigsConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Dynamically instantiates build configurations instead of using the default " + "static globally defined ones" @@ -1012,6 +1100,8 @@ public final class BuildConfiguration implements BuildEvent { name = "experimental_enable_runfiles", defaultValue = "auto", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enable runfiles; off on Windows, on on other platforms" ) public TriState enableRunfiles; @@ -1020,6 +1110,8 @@ public final class BuildConfiguration implements BuildEvent { name = "build_python_zip", defaultValue = "auto", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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/authandtls/AuthAndTLSOptions.java b/src/main/java/com/google/devtools/build/lib/authandtls/AuthAndTLSOptions.java index 04bbc9f6a2..ecb5e62577 100644 --- a/src/main/java/com/google/devtools/build/lib/authandtls/AuthAndTLSOptions.java +++ b/src/main/java/com/google/devtools/build/lib/authandtls/AuthAndTLSOptions.java @@ -15,65 +15,83 @@ package com.google.devtools.build.lib.authandtls; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** * Common options for authentication and TLS. */ public class AuthAndTLSOptions extends OptionsBase { @Option( - name = "auth_enabled", - defaultValue = "false", - category = "remote", - help = "Whether to enable authentication for remote execution/caching and the build event " - + "service (BES). If not otherwise specified 'Google Application Default Credentials' " - + "are used. Disabled by default." + name = "auth_enabled", + defaultValue = "false", + category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Whether to enable authentication for remote execution/caching and the build event " + + "service (BES). If not otherwise specified 'Google Application Default Credentials' " + + "are used. Disabled by default." ) public boolean authEnabled; @Option( - name = "auth_scope", - defaultValue = "null", - category = "remote", - help = "If server authentication requires a scope, provide it here." + name = "auth_scope", + defaultValue = "null", + category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "If server authentication requires a scope, provide it here." ) public String authScope; @Option( - name = "auth_credentials", - defaultValue = "null", - category = "remote", - help = "Specifies the file to get authentication credentials from. See " - + "https://cloud.google.com/docs/authentication for more details. 'Google Application " - + "Default Credentials' are used by default." + name = "auth_credentials", + defaultValue = "null", + category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specifies the file to get authentication credentials from. See " + + "https://cloud.google.com/docs/authentication for more details. 'Google Application " + + "Default Credentials' are used by default." ) public String authCredentials; @Option( - name = "tls_enabled", - defaultValue = "false", - category = "remote", - help = "Specifies whether to use TLS for remote execution/caching and the build event service" - + " (BES)." + name = "tls_enabled", + defaultValue = "false", + category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specifies whether to use TLS for remote execution/caching and the build event service" + + " (BES)." ) public boolean tlsEnabled; @Option( - name = "tls_certificate", - defaultValue = "null", - category = "remote", - help = "Specify the TLS client certificate to use." + name = "tls_certificate", + defaultValue = "null", + category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Specify the TLS client certificate to use." ) public String tlsCertificate; @Option( - name = "tls_authority_override", - defaultValue = "null", - category = "remote", - optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, - help = "TESTING ONLY! Can be used with a self-signed certificate to consider the specified " - + "value a valid TLS authority." + name = "tls_authority_override", + defaultValue = "null", + category = "remote", + optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "TESTING ONLY! Can be used with a self-signed certificate to consider the specified " + + "value a valid TLS authority." ) public String tlsAuthorityOverride; } diff --git a/src/main/java/com/google/devtools/build/lib/bazel/commands/FetchOptions.java b/src/main/java/com/google/devtools/build/lib/bazel/commands/FetchOptions.java index b6472e5051..98a2048d3e 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/commands/FetchOptions.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/commands/FetchOptions.java @@ -15,19 +15,26 @@ package com.google.devtools.build.lib.bazel.commands; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** * Command-line options for the fetch command. */ public class FetchOptions extends OptionsBase { - @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", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + 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; } 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 0072f10ecb..6a3ff207f7 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 @@ -21,9 +21,11 @@ import com.google.devtools.build.lib.util.OptionsUtils; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -34,6 +36,8 @@ public class RepositoryOptions extends OptionsBase { @Option( name = "experimental_repository_cache", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, converter = OptionsUtils.PathFragmentConverter.class, help = @@ -42,11 +46,15 @@ public class RepositoryOptions extends OptionsBase { ) public PathFragment experimentalRepositoryCache; - @Option(name = "override_repository", - defaultValue = "null", - allowMultiple = true, - converter = RepositoryOverrideConverter.class, - help = "Overrides a repository with a local directory.") + @Option( + name = "override_repository", + defaultValue = "null", + allowMultiple = true, + converter = RepositoryOverrideConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Overrides a repository with a local directory." + ) public List<RepositoryOverride> repositoryOverrides; /** diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelStrategyModule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelStrategyModule.java index 1edc643ac8..512b5c0f3b 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelStrategyModule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelStrategyModule.java @@ -23,8 +23,9 @@ import com.google.devtools.build.lib.runtime.Command; import com.google.devtools.build.lib.runtime.CommandEnvironment; import com.google.devtools.common.options.Converters.AssignmentConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; - +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; import java.util.Map; @@ -38,6 +39,8 @@ public class BazelStrategyModule extends BlazeModule { name = "spawn_strategy", defaultValue = "", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specify how spawn actions are executed by default." + "'standalone' means run all of them locally." @@ -49,6 +52,8 @@ public class BazelStrategyModule extends BlazeModule { name = "genrule_strategy", defaultValue = "", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specify how to execute genrules." + "'standalone' means run all of them locally." @@ -56,14 +61,19 @@ public class BazelStrategyModule extends BlazeModule { ) public String genruleStrategy; - @Option(name = "strategy", - allowMultiple = true, - converter = AssignmentConverter.class, - defaultValue = "", - category = "strategy", - help = "Specify how to distribute compilation of other spawn actions. " - + "Example: 'Javac=local' means to spawn Java compilation locally. " - + "'JavaIjar=sandboxed' means to spawn Java Ijar actions in a sandbox. ") + @Option( + name = "strategy", + allowMultiple = true, + converter = AssignmentConverter.class, + defaultValue = "", + category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specify how to distribute compilation of other spawn actions. " + + "Example: 'Javac=local' means to spawn Java compilation locally. " + + "'JavaIjar=sandboxed' means to spawn Java Ijar actions in a sandbox. " + ) public List<Map.Entry<String, String>> strategy; } 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 b1b1348be5..90a888c3b2 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,7 +26,9 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import javax.annotation.Nullable; /** @@ -57,10 +59,14 @@ public class BazelPythonConfiguration extends BuildConfiguration.Fragment { * Bazel-specific Python configuration options. */ public static final class Options extends FragmentOptions { - @Option(name = "python2_path", + @Option( + name = "python2_path", defaultValue = "python", category = "version", - help = "Local path to the Python2 executable.") + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Local path to the Python2 executable." + ) public String python2Path; @Option( @@ -68,6 +74,8 @@ public class BazelPythonConfiguration extends BuildConfiguration.Fragment { converter = Python3PathConverter.class, defaultValue = "auto", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Local path to the Python3 executable." ) public String python3Path; @@ -76,6 +84,8 @@ public class BazelPythonConfiguration extends BuildConfiguration.Fragment { name = "experimental_python_import_all_repositories", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Do not use." ) public boolean experimentalPythonImportAllRepositories; diff --git a/src/main/java/com/google/devtools/build/lib/buildeventservice/BuildEventServiceOptions.java b/src/main/java/com/google/devtools/build/lib/buildeventservice/BuildEventServiceOptions.java index 338cd5b950..f2ea1c39d1 100644 --- a/src/main/java/com/google/devtools/build/lib/buildeventservice/BuildEventServiceOptions.java +++ b/src/main/java/com/google/devtools/build/lib/buildeventservice/BuildEventServiceOptions.java @@ -16,8 +16,10 @@ package com.google.devtools.build.lib.buildeventservice; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.regex.Matcher; import java.util.regex.Pattern; import org.joda.time.Duration; @@ -26,44 +28,57 @@ import org.joda.time.Duration; public class BuildEventServiceOptions extends OptionsBase { @Option( - name = "bes_backend", - defaultValue = "", - help = "Specifies the build event service (BES) backend endpoint as HOST or HOST:PORT. " - + "Disabled by default." + name = "bes_backend", + defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specifies the build event service (BES) backend endpoint as HOST or HOST:PORT. " + + "Disabled by default." ) public String besBackend; @Option( - name = "bes_timeout", - defaultValue = "0s", - converter = DurationConverter.class, - help = "Specifies how long bazel should wait for the BES/BEP upload to complete after the " - + "build and tests have finished. A valid timeout is a natural number followed by a " - + "unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The " - + "default value is '0' which means that there is no timeout and that the upload will " - + "continue in the background after a build has finished." + name = "bes_timeout", + defaultValue = "0s", + converter = DurationConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specifies how long bazel should wait for the BES/BEP upload to complete after the " + + "build and tests have finished. A valid timeout is a natural number followed by a " + + "unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The " + + "default value is '0' which means that there is no timeout and that the upload will " + + "continue in the background after a build has finished." ) public Duration besTimeout; @Option( - name = "bes_best_effort", - defaultValue = "true", - help = "Specifies whether a failure to upload the BES protocol should also result in a build " - + "failure. If 'true', bazel exits with ExitCode.PUBLISH_ERROR. (defaults to 'true')." + name = "bes_best_effort", + defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Specifies whether a failure to upload the BES protocol should also result in a build " + + "failure. If 'true', bazel exits with ExitCode.PUBLISH_ERROR. (defaults to 'true')." ) public boolean besBestEffort; @Option( - name = "bes_lifecycle_events", - defaultValue = "true", - help = "Specifies whether to publish BES lifecycle events. (defaults to 'true')." + name = "bes_lifecycle_events", + defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Specifies whether to publish BES lifecycle events. (defaults to 'true')." ) public boolean besLifecycleEvents; @Option( - name = "project_id", - defaultValue = "null", - help = "Specifies the BES project identifier. Defaults to null." + name = "project_id", + defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Specifies the BES project identifier. Defaults to null." ) public String projectId; diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BUILD b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BUILD index e75fb5c1b8..b3fc23507a 100644 --- a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BUILD +++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BUILD @@ -13,6 +13,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib:vfs", "//src/main/java/com/google/devtools/build/lib/buildeventstream/proto:build_event_stream_java_proto", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party/protobuf:protobuf_java", "//third_party/protobuf:protobuf_java_util", 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 c184714440..6024755421 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 @@ -15,8 +15,10 @@ package com.google.devtools.build.lib.buildeventstream.transports; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** Options used to configure BuildEventStreamer and its BuildEventTransports. */ public class BuildEventStreamOptions extends OptionsBase { @@ -25,6 +27,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_text_file", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If non-empty, write a textual representation of the build event protocol to that file" ) public String buildEventTextFile; @@ -33,6 +37,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_binary_file", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If non-empty, write a varint delimited binary representation of representation of the" + " build event protocol to that file." @@ -43,6 +49,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_json_file", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If non-empty, write a JSON serialisation of the build event protocol to that file." ) public String buildEventJsonFile; @@ -51,6 +59,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_text_file_path_conversion", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -62,6 +72,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_binary_file_path_conversion", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -73,6 +85,8 @@ public class BuildEventStreamOptions extends OptionsBase { name = "experimental_build_event_json_file_path_conversion", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Convert paths in the json file representation of the build event protocol to more " + "globally valid URIs whenever possible; if disabled, the file:// uri scheme will " 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 ed9c1f6e9a..6ed73670b3 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 @@ -143,6 +143,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_makefile", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -154,6 +155,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_action_graph", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -166,6 +168,7 @@ public class BuildRequest implements OptionsClassProvider { name = "dump_action_graph_for_package", allowMultiple = true, defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -177,6 +180,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_action_graph_with_middlemen", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -188,6 +192,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_providers", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -199,6 +204,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_targets", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -210,6 +216,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_host_deps", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -221,6 +228,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_to_stdout", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, @@ -231,6 +239,7 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "analyze", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = { OptionEffectTag.LOADING_AND_ANALYSIS, OptionEffectTag.EAGERNESS_TO_EXIT, @@ -351,6 +360,7 @@ public class BuildRequest implements OptionsClassProvider { name = "output_tree_tracking", oldName = "experimental_output_tree_tracking", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = @@ -366,6 +376,7 @@ public class BuildRequest implements OptionsClassProvider { converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "", documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, + effectTags = {OptionEffectTag.UNKNOWN}, allowMultiple = true, help = "Comma-separated list of aspects to be applied to top-level targets. All aspects " 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 1b0bb10c5e..7462cffc29 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 @@ -20,9 +20,11 @@ import com.google.devtools.build.lib.packages.TestTimeout; import com.google.devtools.build.lib.util.OptionsUtils; import com.google.devtools.build.lib.vfs.PathFragment; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.Options; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.Map; /** @@ -49,6 +51,8 @@ public class ExecutionOptions extends OptionsBase { name = "verbose_failures", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If a command fails, print out the full command line." ) public boolean verboseFailures; @@ -58,6 +62,8 @@ public class ExecutionOptions extends OptionsBase { abbrev = 's', defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Display the subcommands executed during a build." ) public boolean showSubcommands; @@ -66,6 +72,8 @@ public class ExecutionOptions extends OptionsBase { name = "check_up_to_date", defaultValue = "false", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Don't perform the build, just check if it is up-to-date. If all targets are " + "up-to-date, the build completes successfully. If any step needs to be executed " @@ -78,6 +86,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "false", category = "testing", implicitRequirements = {"--check_up_to_date"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Don't run tests, just check if they are up-to-date. If all tests results are " + "up-to-date, the testing completes successfully. If any test needs to be built or " @@ -90,6 +100,8 @@ public class ExecutionOptions extends OptionsBase { name = "test_strategy", defaultValue = "", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies which strategy to use when running tests." ) public String testStrategy; @@ -98,6 +110,8 @@ public class ExecutionOptions extends OptionsBase { name = "test_keep_going", defaultValue = "true", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When disabled, any non-passing test will cause the entire build to stop. By default " + "all tests are run, even if some do not pass." @@ -108,6 +122,8 @@ public class ExecutionOptions extends OptionsBase { name = "runs_per_test_detects_flakes", defaultValue = "false", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, any shard in which at least one run/attempt passes and at least one " + "run/attempt fails gets a FLAKY status." @@ -119,6 +135,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "default", category = "testing", converter = TestStrategy.TestAttemptsConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -135,6 +153,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "null", category = "testing", converter = OptionsUtils.PathFragmentConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the base temporary directory for 'blaze test' to use." ) public PathFragment testTmpDir; @@ -144,6 +164,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "summary", category = "testing", converter = TestStrategy.TestOutputFormat.Converter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -158,6 +180,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "short", category = "testing", converter = TestStrategy.TestSummaryFormat.Converter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -171,6 +195,8 @@ public class ExecutionOptions extends OptionsBase { defaultValue = "-1", category = "testing", converter = TestTimeout.TestTimeoutConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -184,6 +210,8 @@ public class ExecutionOptions extends OptionsBase { name = "resource_autosense", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag has no effect, and is deprecated" ) public boolean useResourceAutoSense; @@ -192,6 +220,8 @@ public class ExecutionOptions extends OptionsBase { name = "ram_utilization_factor", defaultValue = "67", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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. " @@ -209,6 +239,8 @@ public class ExecutionOptions extends OptionsBase { name = "local_resources", defaultValue = "null", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Explicitly set amount of local resources available to Blaze. " + "By default, Blaze will query system configuration to estimate amount of RAM (in MB) " @@ -224,6 +256,8 @@ public class ExecutionOptions extends OptionsBase { name = "local_test_jobs", defaultValue = "0", category = "testing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -239,6 +273,8 @@ public class ExecutionOptions extends OptionsBase { name = "debug_print_action_contexts", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Print the contents of the SpawnActionContext and ContextProviders maps." ) public boolean debugPrintActionContexts; @@ -247,6 +283,8 @@ public class ExecutionOptions extends OptionsBase { name = "cache_computed_file_digests", defaultValue = "50000", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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. " @@ -260,6 +298,8 @@ public class ExecutionOptions extends OptionsBase { name = "experimental_enable_critical_path_profiling", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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/BUILD b/src/main/java/com/google/devtools/build/lib/exec/local/BUILD index 74f4f7b76c..841407c458 100644 --- a/src/main/java/com/google/devtools/build/lib/exec/local/BUILD +++ b/src/main/java/com/google/devtools/build/lib/exec/local/BUILD @@ -19,6 +19,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib:vfs", "//src/main/java/com/google/devtools/build/lib/actions", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", ], 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 565631e24f..9aa93d25d1 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 @@ -15,8 +15,10 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.regex.Pattern; /** @@ -28,6 +30,8 @@ public class LocalExecutionOptions extends OptionsBase { name = "local_termination_grace_seconds", oldName = "local_sigkill_grace_seconds", category = "remote execution", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, defaultValue = "15", help = "Time to wait between terminating a local process due to timeout and forcefully " @@ -37,6 +41,8 @@ public class LocalExecutionOptions extends OptionsBase { @Option( name = "allowed_local_actions_regex", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = Converters.RegexPatternConverter.class, defaultValue = "null", 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 d6a82fad63..0cb1394a73 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 @@ -17,8 +17,10 @@ import com.google.devtools.build.lib.packages.TestSize; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; import java.util.Set; @@ -30,6 +32,8 @@ public class LoadingOptions extends OptionsBase { name = "build_tests_only", defaultValue = "false", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -41,6 +45,8 @@ public class LoadingOptions extends OptionsBase { name = "compile_one_dependency", defaultValue = "false", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -56,6 +62,8 @@ public class LoadingOptions extends OptionsBase { converter = CommaSeparatedOptionListConverter.class, defaultValue = "", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -70,6 +78,8 @@ public class LoadingOptions extends OptionsBase { converter = CommaSeparatedOptionListConverter.class, defaultValue = "", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -83,6 +93,8 @@ public class LoadingOptions extends OptionsBase { converter = TestSize.TestSizeFilterConverter.class, defaultValue = "", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -96,6 +108,8 @@ public class LoadingOptions extends OptionsBase { converter = TestTimeout.TestTimeoutFilterConverter.class, defaultValue = "", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies a comma-separated list of test timeouts. Each timeout can be " + "optionally preceded with '-' to specify excluded timeouts. Only those test " @@ -110,6 +124,8 @@ public class LoadingOptions extends OptionsBase { converter = CommaSeparatedOptionListConverter.class, defaultValue = "", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies a comma-separated list of test languages. Each language can be " + "optionally preceded with '-' to specify excluded languages. Only those " @@ -124,6 +140,8 @@ public class LoadingOptions extends OptionsBase { name = "build_manual_tests", defaultValue = "false", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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)." @@ -139,6 +157,8 @@ public class LoadingOptions extends OptionsBase { name = "experimental_skyframe_target_pattern_evaluator", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use the Skyframe-based target pattern evaluator; implies " + "--experimental_interleave_loading_and_analysis." 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 626d76faa3..8f0895d4b3 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 @@ -25,9 +25,11 @@ import com.google.devtools.build.lib.packages.RuleVisibility; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -62,6 +64,8 @@ public class PackageCacheOptions extends OptionsBase { defaultValue = "%workspace%", category = "package loading", converter = Converters.ColonSeparatedOptionListConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A colon-separated list of where to look for packages. " + "Elements beginning with '%workspace%' are relative to the enclosing " @@ -75,6 +79,8 @@ public class PackageCacheOptions extends OptionsBase { defaultValue = "false", category = "verbosity", deprecationWarning = "This flag is no longer supported and will go away soon.", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, causes Blaze to print the location on the --package_path " + "from which each package was loaded." @@ -85,6 +91,8 @@ public class PackageCacheOptions extends OptionsBase { name = "show_loading_progress", defaultValue = "true", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, causes Blaze to print \"Loading package:\" messages." ) public boolean showLoadingProgress; @@ -94,6 +102,8 @@ public class PackageCacheOptions extends OptionsBase { defaultValue = "", category = "package loading", converter = CommaSeparatedPackageNameListConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A comma-separated list of names of packages which the " + "build system will consider non-existent, even if they are " @@ -112,6 +122,8 @@ public class PackageCacheOptions extends OptionsBase { defaultValue = "private", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = DefaultVisibilityConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Default visibility for packages that don't set it explicitly ('public' or " + "'private')." ) @@ -121,6 +133,8 @@ public class PackageCacheOptions extends OptionsBase { name = "legacy_globbing_threads", defaultValue = "100", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Number of threads to use for glob evaluation." ) public int globbingThreads; @@ -129,6 +143,8 @@ public class PackageCacheOptions extends OptionsBase { name = "experimental_max_directories_to_eagerly_visit_in_globbing", defaultValue = "-1", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -140,6 +156,8 @@ public class PackageCacheOptions extends OptionsBase { name = "fetch", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Allows the command to fetch external dependencies" ) public boolean fetch; @@ -148,6 +166,8 @@ public class PackageCacheOptions extends OptionsBase { name = "experimental_check_output_files", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." diff --git a/src/main/java/com/google/devtools/build/lib/query2/BUILD b/src/main/java/com/google/devtools/build/lib/query2/BUILD index 72fb496fbe..01c21faa76 100644 --- a/src/main/java/com/google/devtools/build/lib/query2/BUILD +++ b/src/main/java/com/google/devtools/build/lib/query2/BUILD @@ -34,6 +34,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib:util", "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:build_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", ], 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 34ba0d40f9..ee29c024a6 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 @@ -17,8 +17,10 @@ import com.google.devtools.build.lib.query2.engine.QueryEnvironment.Setting; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.EnumSet; import java.util.List; import java.util.Set; @@ -45,6 +47,8 @@ public class QueryOptions extends OptionsBase { name = "output", defaultValue = "label", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -56,6 +60,8 @@ public class QueryOptions extends OptionsBase { defaultValue = "null", category = "query", expansion = {"--line_terminator_null=true"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether each format is terminated with \0 instead of newline." ) public Void isNull; @@ -64,6 +70,8 @@ public class QueryOptions extends OptionsBase { name = "line_terminator_null", defaultValue = "false", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether each format is terminated with \0 instead of newline." ) public boolean lineTerminatorNull; @@ -74,6 +82,8 @@ public class QueryOptions extends OptionsBase { category = "query", deprecationWarning = "Please use --order_output=auto or --order_output=no instead of this flag", expansion = {"--order_output=auto"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Output the results in dependency-ordered (default) or unordered fashion. The " + "unordered output is faster but only supported when --output is not minrank, " @@ -87,6 +97,8 @@ public class QueryOptions extends OptionsBase { category = "query", deprecationWarning = "Please use --order_output=no or --order_output=auto instead of this flag", expansion = {"--order_output=no"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Output the results in dependency-ordered (default) or unordered fashion. The " + "unordered output is faster but only supported when --output is not minrank, " @@ -107,6 +119,8 @@ public class QueryOptions extends OptionsBase { converter = OrderOutputConverter.class, defaultValue = "auto", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). " + "The default is 'auto', meaning that results are output either dependency-ordered or " @@ -122,6 +136,8 @@ public class QueryOptions extends OptionsBase { abbrev = 'k', defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -132,6 +148,8 @@ public class QueryOptions extends OptionsBase { name = "loading_phase_threads", defaultValue = "200", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Number of parallel threads to use for the loading phase." ) public int loadingPhaseThreads; @@ -140,6 +158,8 @@ public class QueryOptions extends OptionsBase { name = "host_deps", defaultValue = "true", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, dependencies on 'host configuration' targets will be included in the " + "dependency graph over which the query operates. A 'host configuration' dependency " @@ -156,6 +176,8 @@ public class QueryOptions extends OptionsBase { name = "implicit_deps", defaultValue = "true", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -167,6 +189,8 @@ public class QueryOptions extends OptionsBase { name = "graph:node_limit", defaultValue = "512", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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" @@ -178,6 +202,8 @@ public class QueryOptions extends OptionsBase { name = "graph:factored", defaultValue = "true", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -189,6 +215,8 @@ public class QueryOptions extends OptionsBase { name = "proto:default_values", defaultValue = "true", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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" @@ -199,6 +227,8 @@ public class QueryOptions extends OptionsBase { name = "xml:line_numbers", defaultValue = "true", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -209,6 +239,8 @@ public class QueryOptions extends OptionsBase { name = "xml:default_values", defaultValue = "false", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, rule attributes whose value is not explicitly specified in the BUILD file are " + "printed; otherwise they are omitted." @@ -219,6 +251,8 @@ public class QueryOptions extends OptionsBase { name = "strict_test_suite", defaultValue = "false", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, the tests() expression gives an error if it encounters a test_suite containing " + "non-test targets." @@ -230,6 +264,8 @@ public class QueryOptions extends OptionsBase { converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -241,6 +277,8 @@ public class QueryOptions extends OptionsBase { name = "relative_locations", defaultValue = "false", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -254,6 +292,8 @@ public class QueryOptions extends OptionsBase { converter = AspectResolutionModeConverter.class, defaultValue = "conservative", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -271,12 +311,14 @@ public class QueryOptions extends OptionsBase { name = "query_file", defaultValue = "", category = "query", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." ) public String queryFile; - + /** Ugly workaround since line terminator option default has to be constant expression. */ public String getLineTerminator() { if (lineTerminatorNull) { diff --git a/src/main/java/com/google/devtools/build/lib/remote/BUILD b/src/main/java/com/google/devtools/build/lib/remote/BUILD index 3a5404e970..61fd521ae6 100644 --- a/src/main/java/com/google/devtools/build/lib/remote/BUILD +++ b/src/main/java/com/google/devtools/build/lib/remote/BUILD @@ -25,6 +25,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/exec/local", "//src/main/java/com/google/devtools/build/lib/standalone", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:apache_httpclient", "//third_party:apache_httpcore", "//third_party:auth", diff --git a/src/main/java/com/google/devtools/build/lib/remote/RemoteOptions.java b/src/main/java/com/google/devtools/build/lib/remote/RemoteOptions.java index ebbf4fd487..07aaff11f7 100644 --- a/src/main/java/com/google/devtools/build/lib/remote/RemoteOptions.java +++ b/src/main/java/com/google/devtools/build/lib/remote/RemoteOptions.java @@ -15,7 +15,9 @@ package com.google.devtools.build.lib.remote; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** Options for remote execution and distributed caching. */ public final class RemoteOptions extends OptionsBase { @@ -23,6 +25,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_rest_cache", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A base URL for a RESTful cache server for storing build artifacts." + "It has to support PUT, GET, and HEAD requests." @@ -33,6 +37,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_rest_cache_pool_size", defaultValue = "20", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Size of the HTTP pool for making requests to the REST cache." ) public int restCachePoolSize; @@ -41,6 +47,8 @@ public final class RemoteOptions extends OptionsBase { name = "hazelcast_node", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A comma separated list of hostnames of hazelcast nodes." ) public String hazelcastNode; @@ -49,6 +57,8 @@ public final class RemoteOptions extends OptionsBase { name = "hazelcast_client_config", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A file path to a hazelcast client config XML file." ) public String hazelcastClientConfig; @@ -57,6 +67,8 @@ public final class RemoteOptions extends OptionsBase { name = "hazelcast_standalone_listen_port", defaultValue = "0", category = "build_worker", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Runs an embedded hazelcast server that listens to this port. The server does not join" + " any cluster. This is useful for testing." @@ -67,6 +79,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_executor", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "HOST or HOST:PORT of a remote execution endpoint." ) public String remoteExecutor; @@ -75,6 +89,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_cache", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "HOST or HOST:PORT of a remote caching endpoint." ) public String remoteCache; @@ -83,6 +99,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_timeout", defaultValue = "60", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The maximum number of seconds to wait for remote execution and cache calls." ) public int remoteTimeout; @@ -91,6 +109,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_accept_cached", defaultValue = "true", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to accept remotely cached action results." ) public boolean remoteAcceptCached; @@ -99,6 +119,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_local_fallback", defaultValue = "false", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to fall back to standalone local execution strategy if remote execution fails." ) public boolean remoteLocalFallback; @@ -107,6 +129,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_upload_local_results", defaultValue = "true", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to upload locally executed action results to the remote cache." ) public boolean remoteUploadLocalResults; @@ -115,6 +139,8 @@ public final class RemoteOptions extends OptionsBase { name = "experimental_remote_platform_override", defaultValue = "null", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Temporary, for testing only. Manually set a Platform to pass to remote execution." ) public String experimentalRemotePlatformOverride; @@ -123,6 +149,8 @@ public final class RemoteOptions extends OptionsBase { name = "remote_instance_name", defaultValue = "", category = "remote", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Value to pass as instance_name in the remote execution API." ) public String remoteInstanceName; 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 40159bda72..b6c1e46b63 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 @@ -37,8 +37,10 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; import java.util.Set; @@ -229,7 +231,9 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "Android configuration distinguisher", defaultValue = "MAIN", converter = ConfigurationDistinguisherConverter.class, - optionUsageRestrictions = OptionUsageRestrictions.INTERNAL + optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN} ) public ConfigurationDistinguisher configurationDistinguisher; @@ -239,7 +243,9 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { @Option( name = "android_incremental_native_libs", defaultValue = "false", - optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN} ) public boolean incrementalNativeLibs; @@ -248,6 +254,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "//external:android/crosstool", category = "semantics", converter = EmptyToNullLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The location of the C++ compiler used for Android builds." ) public Label androidCrosstoolTop; @@ -256,6 +264,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "android_cpu", defaultValue = "armeabi", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The Android target CPU." ) public String cpu; @@ -264,6 +274,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "android_compiler", defaultValue = "null", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The Android target compiler." ) public String cppCompiler; @@ -273,6 +285,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "off", converter = DynamicModeConverter.class, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Determines whether C++ deps of Android rules will be linked dynamically when a " + "cc_binary does not explicitly create a shared library. " @@ -289,6 +303,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "@bazel_tools//tools/android:sdk", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies Android SDK/platform that is used to build Android applications." ) public Label sdk; @@ -299,6 +315,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "armeabi-v7a", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -314,6 +332,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_desugar_for_android", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to desugar Java 8 bytecode before dexing." ) public boolean desugarJava8; @@ -322,6 +342,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "incremental_dexing", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Does most of the work for dexing separately for each Jar file." ) public boolean incrementalDexing; @@ -331,6 +353,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "host_incremental_dexing", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -347,6 +371,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = AndroidBinaryTypesConverter.class, implicitRequirements = "--incremental_dexing", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Kinds of binaries to incrementally dex if --incremental_dexing is true." ) public Set<AndroidBinaryType> incrementalDexingBinaries; @@ -358,6 +384,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "true", category = "experimental", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Do not use." ) public boolean incrementalDexingForLiteProtos; @@ -371,6 +399,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "true", category = "experimental", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Do not use." ) public boolean incrementalDexingErrorOnMissedJars; @@ -380,6 +410,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { category = "experimental", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use dex2oat in parallel to possibly speed up android_test." ) public boolean useParallelDex2Oat; @@ -392,6 +424,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "--positions", category = "semantics", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -409,6 +443,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "--no-optimize,--no-locals", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "dx flags supported when converting Jars to dex archives incrementally." ) public List<String> dexoptsSupportedInIncrementalDexing; @@ -421,6 +457,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "--no-optimize,--no-locals,--minimal-main-dex,--set-max-idx-number", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "dx flags supported in tool that merges dex archives into final classes.dex files." ) public List<String> dexoptsSupportedInDexMerger; @@ -429,6 +467,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_rewrite_dexes_with_rex", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "use rex tool to rewrite dex files" ) public boolean useRexToCompressDexFiles; @@ -437,6 +477,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_allow_android_library_deps_without_srcs", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -447,6 +489,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_resource_shrinking", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables resource shrinking for android_binary APKs that use ProGuard." ) public boolean useExperimentalAndroidResourceShrinking; @@ -455,6 +499,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "android_resource_shrinking", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables resource shrinking for android_binary APKs that use ProGuard." ) public boolean useAndroidResourceShrinking; @@ -464,6 +510,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { defaultValue = "android", category = "semantics", converter = AndroidManifestMergerConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -487,6 +535,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_use_parallel_android_resource_processing", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Process android_library resources with higher parallelism. Generates library " + "R classes from a merge action, separately from aapt." @@ -498,6 +548,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { converter = ApkSigningMethodConverter.class, defaultValue = "v1_v2", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Implementation to use to sign APKs" ) public ApkSigningMethod apkSigningMethod; @@ -506,6 +558,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "use_singlejar_apkbuilder", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Build Android APKs with SingleJar." ) public boolean useSingleJarApkBuilder; @@ -516,6 +570,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, deprecationWarning = "This flag is deprecated and is a no-op. It will be removed in a future release.", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag is deprecated and is a no-op. It will be removed in a future release." ) public boolean useSingleJarForMultidex; @@ -525,6 +581,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { converter = ResourceFilter.Converter.class, defaultValue = "filter_in_execution", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Determines when resource filtering attributes, such as the android_binary " + "'resource_configuration_filters' and 'densities' attributes, are applied. " @@ -545,6 +603,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_compress_java_resources", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Compress Java resources in APKs" ) public boolean compressJavaResources; @@ -553,6 +613,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_include_library_resource_jars", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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" @@ -565,6 +627,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_use_nocompress_extensions_on_apk", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use the value of nocompress_extensions attribute with the SingleJar " + "--nocompress_suffixes flag when building the APK." @@ -575,6 +639,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_library_exports_manifest_default", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.DOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The default value of the exports_manifest attribute on android_library." ) public boolean exportsManifestDefault; @@ -583,6 +649,8 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment { name = "experimental_android_generate_robolectric_r_class", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If passed, R classes will be generated for Robolectric tests. Otherwise, only inherited" + " R classes will be used." diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/WriteAdbArgsAction.java b/src/main/java/com/google/devtools/build/lib/rules/android/WriteAdbArgsAction.java index ed1b644175..d65f3541ec 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/android/WriteAdbArgsAction.java +++ b/src/main/java/com/google/devtools/build/lib/rules/android/WriteAdbArgsAction.java @@ -23,7 +23,9 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.util.Fingerprint; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.io.OutputStream; import java.io.PrintStream; @@ -41,53 +43,83 @@ public final class WriteAdbArgsAction extends AbstractFileWriteAction { * Options of the {@code mobile-install} command pertaining to the way {@code adb} is invoked. */ public static final class Options extends OptionsBase { - @Option(name = "adb", - category = "mobile-install", - defaultValue = "", - help = "adb binary to use for the 'mobile-install' command. If unspecified, the one in " - + "the Android SDK specified by the --android_sdk command line option (or the default " - + "SDK if --android_sdk is not specified) is used.") + @Option( + name = "adb", + category = "mobile-install", + defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "adb binary to use for the 'mobile-install' command. If unspecified, the one in " + + "the Android SDK specified by the --android_sdk command line option (or the " + + "default SDK if --android_sdk is not specified) is used." + ) public String adb; - @Option(name = "adb_arg", - category = "mobile-install", - allowMultiple = true, - defaultValue = "", - help = "Extra arguments to pass to adb. Usually used to designate a device to install to.") + @Option( + name = "adb_arg", + category = "mobile-install", + allowMultiple = true, + defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Extra arguments to pass to adb. Usually used to designate a device to install to." + ) public List<String> adbArgs; - @Option(name = "adb_jobs", - category = "mobile-install", - defaultValue = "2", - help = "The number of instances of adb to use in parallel to update files on the device") + @Option( + name = "adb_jobs", + category = "mobile-install", + defaultValue = "2", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "The number of instances of adb to use in parallel to update files on the device" + ) public int adbJobs; - @Option(name = "incremental_install_verbosity", - category = "mobile-install", - defaultValue = "", - help = "The verbosity for incremental install. Set to 1 for debug logging.") + @Option( + name = "incremental_install_verbosity", + category = "mobile-install", + defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "The verbosity for incremental install. Set to 1 for debug logging." + ) public String incrementalInstallVerbosity; - @Option(name = "start", - category = "mobile-install", - converter = StartTypeConverter.class, - defaultValue = "NO", - help = "How the app should be started after installing it. Set to WARM to preserve " - + "and restore application state on incremental installs.") + @Option( + name = "start", + category = "mobile-install", + converter = StartTypeConverter.class, + defaultValue = "NO", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "How the app should be started after installing it. Set to WARM to preserve " + + "and restore application state on incremental installs." + ) public StartType start; - @Option(name = "start_app", - category = "mobile-install", - defaultValue = "null", - help = "Whether to start the app after installing it.", - expansion = {"--start=COLD"}) + @Option( + name = "start_app", + category = "mobile-install", + defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Whether to start the app after installing it.", + expansion = {"--start=COLD"} + ) public Void startApp; - @Option(name = "debug_app", - category = "mobile-install", - defaultValue = "null", - help = "Whether to wait for the debugger before starting the app.", - expansion = {"--start=DEBUG"}) + @Option( + name = "debug_app", + category = "mobile-install", + defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Whether to wait for the debugger before starting the app.", + expansion = {"--start=DEBUG"} + ) public Void debugApp; } 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 951b3670de..fd328754ec 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,7 +30,9 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -47,6 +49,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", category = "build", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, uses Xcode of the given version for relevant build actions. " + "If unspecified, uses the executor default version of Xcode." @@ -60,6 +64,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", converter = DottedVersionConverter.class, category = "build", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the version of the iOS SDK to use to build iOS applications." ) public DottedVersion iosSdkVersion; @@ -69,6 +75,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", converter = DottedVersionConverter.class, category = "build", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the version of the watchOS SDK to use to build watchOS applications." ) public DottedVersion watchOsSdkVersion; @@ -78,6 +86,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", converter = DottedVersionConverter.class, category = "build", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the version of the tvOS SDK to use to build tvOS applications." ) public DottedVersion tvOsSdkVersion; @@ -87,6 +97,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", converter = DottedVersionConverter.class, category = "build", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the version of the macOS SDK to use to build macOS applications." ) public DottedVersion macOsSdkVersion; @@ -96,6 +108,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = DEFAULT_MINIMUM_IOS, category = "flags", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum compatible iOS version for target simulators and devices." ) public DottedVersion iosMinimumOs; @@ -105,6 +119,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", category = "flags", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum compatible watchOS version for target simulators and devices." ) public DottedVersion watchosMinimumOs; @@ -114,6 +130,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "null", category = "flags", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum compatible tvOS version for target simulators and devices." ) public DottedVersion tvosMinimumOs; @@ -123,6 +141,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = DEFAULT_MINIMUM_MACOS, category = "flags", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum compatible macOS version for targets." ) public DottedVersion macosMinimumOs; @@ -152,6 +172,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "ios_cpu", defaultValue = DEFAULT_IOS_CPU, category = "build", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies to target CPU of iOS compilation." ) public String iosCpu; @@ -161,6 +183,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "@bazel_tools//tools/cpp:toolchain", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The label of the crosstool package to be used in Apple and Objc rules and their" + " dependencies." @@ -172,6 +196,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "IOS", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = PlatformTypeConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Don't set this value from the command line - it is derived from other flags and " + "configuration transitions derived from rule attributes" @@ -182,6 +208,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "apple_split_cpu", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Don't set this value from the command line - it is derived from other flags and " + "configuration transitions derived from rule attributes" @@ -198,6 +226,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "apple configuration distinguisher", defaultValue = "UNKNOWN", converter = ConfigurationDistinguisherConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.INTERNAL ) public ConfigurationDistinguisher configurationDistinguisher; @@ -207,6 +237,8 @@ public class AppleCommandLineOptions extends FragmentOptions { converter = CommaSeparatedOptionListConverter.class, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Comma-separated list of architectures to build an ios_application with. The result " + "is a universal binary containing all specified architectures." @@ -218,6 +250,8 @@ public class AppleCommandLineOptions extends FragmentOptions { converter = CommaSeparatedOptionListConverter.class, defaultValue = DEFAULT_WATCHOS_CPU, category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Comma-separated list of architectures for which to build Apple watchOS binaries." ) public List<String> watchosCpus; @@ -227,6 +261,8 @@ public class AppleCommandLineOptions extends FragmentOptions { converter = CommaSeparatedOptionListConverter.class, defaultValue = DEFAULT_TVOS_CPU, category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Comma-separated list of architectures for which to build Apple tvOS binaries." ) public List<String> tvosCpus; @@ -236,6 +272,8 @@ public class AppleCommandLineOptions extends FragmentOptions { converter = CommaSeparatedOptionListConverter.class, defaultValue = DEFAULT_MACOS_CPU, category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Comma-separated list of architectures for which to build Apple macOS binaries." ) public List<String> macosCpus; @@ -244,6 +282,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "default_ios_provisioning_profile", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, converter = DefaultProvisioningProfileConverter.class ) public Label defaultProvisioningProfile; @@ -253,6 +293,8 @@ public class AppleCommandLineOptions extends FragmentOptions { defaultValue = "@local_config_xcode//:host_xcodes", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The label of the xcode_config rule to be used for selecting the Xcode version " + "in the build configuration." @@ -277,6 +319,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "xcode_toolchain", defaultValue = "null", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -291,6 +335,8 @@ public class AppleCommandLineOptions extends FragmentOptions { // TODO(blaze-team): Default to embedded_markers when fully implemented. defaultValue = "none", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specify the Apple bitcode mode for compile steps. " + "Values: 'none', 'embedded_markers', 'embedded'." @@ -301,6 +347,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "apple_crosstool_transition", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, the apple crosstool is used for all apple rules." ) public boolean enableAppleCrosstoolTransition; @@ -309,6 +357,8 @@ public class AppleCommandLineOptions extends FragmentOptions { name = "target_uses_apple_crosstool", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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/apple/BUILD b/src/main/java/com/google/devtools/build/lib/rules/apple/BUILD index 15ae78dbf2..ea1d76e922 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/BUILD +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/BUILD @@ -21,6 +21,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/actions", "//src/main/java/com/google/devtools/build/lib/cmdline", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", ], diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/BUILD b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/BUILD index d8aaf10fc2..0899232fd7 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/BUILD +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/BUILD @@ -13,6 +13,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib:concurrent", "//src/main/java/com/google/devtools/build/lib:skylarkinterface", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", ], ) diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftCommandLineOptions.java index 95a3f52c6d..b4151d1ba2 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftCommandLineOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftCommandLineOptions.java @@ -16,6 +16,8 @@ package com.google.devtools.build.lib.rules.apple.swift; import com.google.devtools.build.lib.analysis.config.FragmentOptions; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** Command-line options for building with Swift tools. */ @@ -26,6 +28,8 @@ public class SwiftCommandLineOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to Swift compilation." ) public List<String> copts; @@ -34,6 +38,8 @@ public class SwiftCommandLineOptions extends FragmentOptions { name = "swift_whole_module_optimization", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to enable Whole Module Optimization" ) public boolean enableWholeModuleOptimization; diff --git a/src/main/java/com/google/devtools/build/lib/rules/config/BUILD b/src/main/java/com/google/devtools/build/lib/rules/config/BUILD index 99ec4230cf..eed0601673 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/config/BUILD +++ b/src/main/java/com/google/devtools/build/lib/rules/config/BUILD @@ -21,6 +21,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/actions", "//src/main/java/com/google/devtools/build/lib/cmdline", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", "//third_party:jsr305", ], 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 4f471e8838..bd8507f0c5 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,7 +28,9 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.Map; import java.util.SortedMap; import javax.annotation.Nullable; @@ -58,6 +60,8 @@ public final class ConfigFeatureFlagConfiguration extends BuildConfiguration.Fra /** The mapping from config_feature_flag rules to their values. */ @Option( name = "config_feature_flag values (private)", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, converter = EmptyImmutableSortedMapConverter.class, defaultValue = "{}" diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/BUILD b/src/main/java/com/google/devtools/build/lib/rules/cpp/BUILD index 15011dc109..8a7d9fbd52 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/cpp/BUILD +++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/BUILD @@ -30,6 +30,7 @@ java_library( "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:crosstool_config_java_proto", "//src/main/protobuf:extra_actions_base_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//third_party:auto_value", "//third_party:guava", "//third_party:jsr305", 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 5361b53f09..888a276364 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 @@ -34,8 +34,10 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.LinkedHashSet; import java.util.List; import java.util.Map; @@ -134,6 +136,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "@bazel_tools//tools/cpp:toolchain", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The label of the crosstool package to be used for compiling C++ code." ) public Label crosstoolTop; @@ -142,6 +146,8 @@ public class CppOptions extends FragmentOptions { name = "compiler", defaultValue = "null", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The C++ compiler to use for compiling the target." ) public String cppCompiler; @@ -150,6 +156,8 @@ public class CppOptions extends FragmentOptions { name = "glibc", defaultValue = "null", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The version of glibc the target should be linked against. " + "By default, a suitable version is chosen based on --cpu." @@ -162,6 +170,8 @@ public class CppOptions extends FragmentOptions { name = "start_end_lib", defaultValue = "true", category = "strategy", // but also adds edges to the action graph + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use the --start-lib/--end-lib ld options if supported by the toolchain." ) public boolean useStartEndLib; @@ -170,6 +180,8 @@ public class CppOptions extends FragmentOptions { name = "interface_shared_objects", defaultValue = "true", category = "strategy", // but also adds edges to the action graph + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use interface shared objects if supported by the toolchain. " + "All ELF toolchains currently support this setting." @@ -181,6 +193,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "no", converter = FissionOptionConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies which compilation modes use fission for C++ compilations and links. " + " May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' " @@ -192,6 +206,8 @@ public class CppOptions extends FragmentOptions { name = "build_test_dwp", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, when building C++ tests statically and with fission the .dwp file " + " for the test binary will be automatically built as well." @@ -203,6 +219,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "default", converter = DynamicModeConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Determines whether C++ binaries will be linked dynamically. 'default' means " + "blaze will choose whether to link dynamically. 'fully' means all libraries " @@ -215,6 +233,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_link_compile_output_separately", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag is experimental and may go away at any time. " + "If true, dynamically linked binary targets will build and link their own srcs as " @@ -226,6 +246,8 @@ public class CppOptions extends FragmentOptions { name = "force_pic", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, all C++ compilations produce position-independent code (\"-fPIC\")," + " links prefer PIC pre-built libraries over non-PIC libraries, and links produce" @@ -237,6 +259,8 @@ public class CppOptions extends FragmentOptions { name = "force_ignore_dash_static", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, '-static' options in the linkopts of cc_* rules will be ignored." ) public boolean forceIgnoreDashStatic; @@ -245,6 +269,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_skip_static_outputs", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag is experimental and may go away at any time. " + "If true, linker output for mostly-static C++ executables is a tiny amount of " @@ -259,6 +285,8 @@ public class CppOptions extends FragmentOptions { name = "send_transitive_header_module_srcs", defaultValue = "true", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Obsolete. Don't use." ) public boolean sendTransitiveHeaderModuleSrcs; @@ -267,6 +295,8 @@ public class CppOptions extends FragmentOptions { name = "process_headers_in_dependencies", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When building a target //a:a, process headers in all targets that //a:a depends " + "on (if header processing is enabled for the toolchain)." @@ -278,6 +308,8 @@ public class CppOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to gcc." ) public List<String> coptList; @@ -287,6 +319,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "", category = "flags", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional option to pass to gcc when compiling C++ source files." ) public List<String> cxxoptList; @@ -296,6 +330,8 @@ public class CppOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional option to pass to gcc when compiling C source files." ) public List<String> conlyoptList; @@ -305,6 +341,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "", category = "flags", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional option to pass to gcc when linking." ) public List<String> linkoptList; @@ -314,6 +352,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "", category = "flags", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional option to pass to the LTO indexing step (under --features=thin_lto)." ) public List<String> ltoindexoptList; @@ -323,6 +363,8 @@ public class CppOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to strip when generating a '<name>.stripped' binary." ) public List<String> stripoptList; @@ -331,6 +373,8 @@ public class CppOptions extends FragmentOptions { name = "custom_malloc", defaultValue = "null", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies a custom malloc implementation. This setting overrides malloc " + "attributes in build rules.", @@ -342,6 +386,8 @@ public class CppOptions extends FragmentOptions { name = "legacy_whole_archive", defaultValue = "true", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When on, use --whole-archive for cc_binary rules that have " + "linkshared=1 and either linkstatic=1 or '-static' in linkopts. " @@ -354,6 +400,8 @@ public class CppOptions extends FragmentOptions { name = "strip", defaultValue = "sometimes", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies whether to strip binaries and shared libraries " + " (using \"-Wl,--strip-debug\"). The default value of 'sometimes'" @@ -368,6 +416,8 @@ public class CppOptions extends FragmentOptions { converter = OptionsUtils.PathFragmentConverter.class, category = "flags", implicitRequirements = {"--copt=-Wno-error"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Generate binaries with FDO instrumentation. Specify the relative " + "directory name for the .gcda files at runtime with GCC compiler. " @@ -376,8 +426,8 @@ public class CppOptions extends FragmentOptions { ) /** * Never read FDO/LIPO options directly. This is because {@link #lipoConfigurationState} - * determines whether these options are actually "active" for this configuration. Instead, use - * the equivalent getter method, which takes that into account. + * determines whether these options are actually "active" for this configuration. Instead, use the + * equivalent getter method, which takes that into account. */ public PathFragment fdoInstrumentForBuild; @@ -393,6 +443,8 @@ public class CppOptions extends FragmentOptions { name = "fdo_optimize", defaultValue = "null", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use FDO profile information to optimize compilation. Specify the name " + "of the zip file containing the .gcda file tree or an afdo file containing " @@ -403,8 +455,8 @@ public class CppOptions extends FragmentOptions { ) /** * Never read FDO/LIPO options directly. This is because {@link #lipoConfigurationState} - * determines whether these options are actually "active" for this configuration. Instead, use - * the equivalent getter method, which takes that into account. + * determines whether these options are actually "active" for this configuration. Instead, use the + * equivalent getter method, which takes that into account. */ public String fdoOptimizeForBuild; @@ -420,14 +472,16 @@ public class CppOptions extends FragmentOptions { name = "autofdo_lipo_data", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true then the directory name for non-LIPO targets will have a " + "'-lipodata' suffix in AutoFDO mode." ) /** * Never read FDO/LIPO options directly. This is because {@link #lipoConfigurationState} - * determines whether these options are actually "active" for this configuration. Instead, use - * the equivalent getter method, which takes that into account. + * determines whether these options are actually "active" for this configuration. Instead, use the + * equivalent getter method, which takes that into account. */ public boolean autoFdoLipoDataForBuild; @@ -441,11 +495,14 @@ public class CppOptions extends FragmentOptions { : lipoModeForBuild != LipoMode.OFF && fdoOptimizeForBuild != null && FdoSupport.isAutoFdo( fdoOptimizeForBuild); } + @Option( name = "lipo", defaultValue = "off", converter = LipoModeConverter.class, category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enable LIPO optimization (lightweight inter-procedural optimization, The allowed " + "values for this option are 'off' and 'binary', which enables LIPO. This option " @@ -454,8 +511,8 @@ public class CppOptions extends FragmentOptions { ) /** * Never read FDO/LIPO options directly. This is because {@link #lipoConfigurationState} - * determines whether these options are actually "active" for this configuration. Instead, use - * the equivalent getter method, which takes that into account. + * determines whether these options are actually "active" for this configuration. Instead, use the + * equivalent getter method, which takes that into account. */ public LipoMode lipoModeForBuild; @@ -473,12 +530,14 @@ public class CppOptions extends FragmentOptions { category = "flags", converter = LabelConverter.class, implicitRequirements = {"--linkopt=-Wl,--warn-unresolved-symbols"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies the binary from which the LIPO profile information comes." ) /** * Never read FDO/LIPO options directly. This is because {@link #lipoConfigurationState} - * determines whether these options are actually "active" for this configuration. Instead, use - * the equivalent getter method, which takes that into account. + * determines whether these options are actually "active" for this configuration. Instead, use the + * equivalent getter method, which takes that into account. */ public Label lipoContextForBuild; @@ -528,6 +587,8 @@ public class CppOptions extends FragmentOptions { name = "lipo configuration state", defaultValue = "apply_lipo", optionUsageRestrictions = OptionUsageRestrictions.INTERNAL, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, converter = LipoConfigurationStateConverter.class ) public LipoConfigurationState lipoConfigurationState; @@ -557,6 +618,8 @@ public class CppOptions extends FragmentOptions { converter = LabelConverter.class, defaultValue = "null", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, use this label instead of the default STL implementation. " + "This option is EXPERIMENTAL and may go away in a future release." @@ -567,6 +630,8 @@ public class CppOptions extends FragmentOptions { name = "save_temps", defaultValue = "false", category = "what", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, temporary outputs from gcc will be saved. " + "These include .s files (assembler code), .i files (preprocessed C) and " @@ -580,6 +645,8 @@ public class CppOptions extends FragmentOptions { converter = PerLabelOptions.PerLabelOptionsConverter.class, defaultValue = "", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to selectively pass to gcc when compiling certain files. " + "This option can be passed multiple times. " @@ -600,6 +667,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "null", converter = LabelConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "By default, the --crosstool_top and --compiler options are also used " + "for the host configuration. If this flag is provided, Blaze uses the default libc " @@ -612,6 +681,8 @@ public class CppOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to gcc for host tools." ) public List<String> hostCoptList; @@ -621,6 +692,8 @@ public class CppOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to gcc for host tools." ) public List<String> hostCxxoptList; @@ -630,6 +703,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "null", // The default value is chosen by the toolchain. category = "version", converter = LibcTopLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A label to a checked-in libc library. The default value is selected by the crosstool " + "toolchain, and you almost never need to override it." @@ -641,6 +716,8 @@ public class CppOptions extends FragmentOptions { defaultValue = "null", // The default value is chosen by the toolchain. category = "version", converter = LibcTopLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, this setting overrides the libc top-level directory (--grte_top) " + "for the host configuration." @@ -651,6 +728,8 @@ public class CppOptions extends FragmentOptions { name = "output_symbol_counts", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, for every C++ binary linked with gold, the number of defined symbols " + "and the number of used symbols per input file is stored in a .sc file." @@ -661,6 +740,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_inmemory_dotd_files", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, C++ .d files will be passed through in memory directly from the remote " + "build nodes instead of being written to disk." @@ -671,6 +752,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_skip_unused_modules", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Deprecated. No effect." ) public boolean skipUnusedModules; @@ -679,6 +762,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_prune_more_modules", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Deprecated. No effect." ) public boolean pruneMoreModules; @@ -687,6 +772,8 @@ public class CppOptions extends FragmentOptions { name = "prune_cpp_modules", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, use the results of input discovery to reduce the number of used modules." ) public boolean pruneCppModules; @@ -695,6 +782,8 @@ public class CppOptions extends FragmentOptions { name = "parse_headers_verifies_modules", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, the parse_headers feature verifies that a header module can be built for the " + "target in question instead of doing a separate compile of the header." @@ -705,6 +794,8 @@ public class CppOptions extends FragmentOptions { name = "experimental_omitfp", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, use libunwind for stack unwinding, and compile with " + "-fomit-frame-pointer and -fasynchronous-unwind-tables." @@ -715,6 +806,8 @@ public class CppOptions extends FragmentOptions { name = "share_native_deps", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, native libraries that contain identical functionality " + "will be shared among different targets" @@ -725,6 +818,8 @@ public class CppOptions extends FragmentOptions { name = "strict_system_includes", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, headers found through system include paths (-isystem) are also required to be " + "declared." 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 f5764e6a18..33ba628d1f 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 @@ -30,8 +30,10 @@ import com.google.devtools.build.lib.rules.java.JavaConfiguration.JavaOptimizati import com.google.devtools.build.lib.rules.java.JavaConfiguration.OneVersionEnforcementLevel; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.TriState; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.HashMap; import java.util.LinkedHashSet; import java.util.List; @@ -71,6 +73,8 @@ public class JavaOptions extends FragmentOptions { name = "javabase", defaultValue = "@bazel_tools//tools/jdk:jdk", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "JAVABASE used for the JDK invoked by Blaze. This is the " + "JAVABASE which will be used to execute external Java " @@ -83,6 +87,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "@bazel_tools//tools/jdk:toolchain", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The name of the toolchain rule for Java." ) public Label javaToolchain; @@ -92,6 +98,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "@bazel_tools//tools/jdk:toolchain", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The Java toolchain used to build tools that are executed during a build." ) public Label hostJavaToolchain; @@ -100,6 +108,8 @@ public class JavaOptions extends FragmentOptions { name = "host_javabase", defaultValue = "@bazel_tools//tools/jdk:jdk", category = "version", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "JAVABASE used for the host JDK. This is the JAVABASE which is used to execute " + " tools during a build." @@ -111,6 +121,8 @@ public class JavaOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to javac." ) public List<String> javacOpts; @@ -120,6 +132,8 @@ public class JavaOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to the Java VM. These options will get added to the " + "VM startup options of each java_binary target." @@ -130,6 +144,8 @@ public class JavaOptions extends FragmentOptions { name = "use_ijars", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, this option causes Java compilation to use interface jars. " + "This will result in faster incremental compilation, " @@ -142,6 +158,8 @@ public class JavaOptions extends FragmentOptions { name = "use_src_ijars", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public boolean useSourceIjars; @@ -150,6 +168,8 @@ public class JavaOptions extends FragmentOptions { name = "java_header_compilation", defaultValue = "true", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Compile ijars directly from source.", oldName = "experimental_java_header_compilation" ) @@ -161,6 +181,8 @@ public class JavaOptions extends FragmentOptions { name = "experimental_optimize_header_compilation_annotation_processing", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag is a noop and scheduled for removal." ) public boolean optimizeHeaderCompilationAnnotationProcessing; @@ -169,6 +191,8 @@ public class JavaOptions extends FragmentOptions { name = "java_deps", defaultValue = "true", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Generate dependency information (for now, compile-time classpath) per Java target." ) public boolean javaDeps; @@ -179,6 +203,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "javabuilder", converter = JavaClasspathModeConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables reduced classpaths for Java compilations.", oldName = "experimental_java_classpath" ) @@ -195,6 +221,8 @@ public class JavaOptions extends FragmentOptions { "--test_timeout=9999", "--nocache_test_results" }, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -208,6 +236,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "default", converter = StrictDepsConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, checks that a Java target explicitly declares all directly used " + "targets as dependencies.", @@ -222,6 +252,8 @@ public class JavaOptions extends FragmentOptions { name = "explicit_java_test_deps", defaultValue = "false", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -232,6 +264,8 @@ public class JavaOptions extends FragmentOptions { name = "experimental_testrunner", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -243,6 +277,8 @@ public class JavaOptions extends FragmentOptions { name = "javabuilder_top", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String javaBuilderTop; @@ -251,6 +287,8 @@ public class JavaOptions extends FragmentOptions { name = "singlejar_top", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String singleJarTop; @@ -259,6 +297,8 @@ public class JavaOptions extends FragmentOptions { name = "genclass_top", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String genClassTop; @@ -267,6 +307,8 @@ public class JavaOptions extends FragmentOptions { name = "ijar_top", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String iJarTop; @@ -275,6 +317,8 @@ public class JavaOptions extends FragmentOptions { name = "java_langtools", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String javaLangtoolsJar; @@ -283,6 +327,8 @@ public class JavaOptions extends FragmentOptions { name = "javac_bootclasspath", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String javacBootclasspath; @@ -291,6 +337,8 @@ public class JavaOptions extends FragmentOptions { name = "javac_extdir", defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "No-op. Kept here for backwards compatibility." ) public String javacExtdir; @@ -300,6 +348,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "null", converter = LabelConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The Java launcher used by tools that are executed during a build." ) public Label hostJavaLauncher; @@ -309,6 +359,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "null", converter = LabelConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The Java launcher to use when building Java binaries. " + "The \"launcher\" attribute overrides this flag. " @@ -320,6 +372,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "null", category = "version", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies which version of ProGuard to use for code removal when building a Java " + "binary." @@ -332,6 +386,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "", // Ignored converter = LabelConverter.class, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -348,6 +404,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "Proguard", converter = LabelMapConverter.class, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Do not use." ) public Map<String, Label> bytecodeOptimizers; @@ -356,6 +414,8 @@ public class JavaOptions extends FragmentOptions { name = "translations", defaultValue = "auto", category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Translate Java messages; bundle all translations into the jar " + "for each affected rule." ) @@ -366,6 +426,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "", category = "semantics", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The message translations used for translating messages in Java targets." ) public List<String> translationTargets; @@ -375,6 +437,8 @@ public class JavaOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "checking", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Check the listed constraint." ) public List<String> checkedConstraints; @@ -383,6 +447,8 @@ public class JavaOptions extends FragmentOptions { name = "experimental_disable_jvm", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Disables the Jvm configuration entirely." ) public boolean disableJvm; @@ -392,6 +458,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "legacy", converter = JavaOptimizationModeConverter.class, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Applies desired link-time optimizations to Java binaries and tests." ) public JavaOptimizationMode javaOptimizationMode; @@ -400,6 +468,8 @@ public class JavaOptions extends FragmentOptions { name = "legacy_bazel_java_test", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use the legacy mode of Bazel for java_test." ) public boolean legacyBazelJavaTest; @@ -408,6 +478,8 @@ public class JavaOptions extends FragmentOptions { name = "strict_deps_java_protos", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -420,6 +492,8 @@ public class JavaOptions extends FragmentOptions { name = "experimental_java_header_compilation_disable_javac_fallback", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If --java_header_compilation is set, report diagnostics from turbine instead of falling " + " back to javac. Diagnostics will be produced more quickly, but may be less helpful." @@ -431,6 +505,8 @@ public class JavaOptions extends FragmentOptions { defaultValue = "OFF", converter = OneVersionEnforcementLevelConverter.class, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When enabled, enforce that a java_binary rule can't contain more than one version " + "of the same class file on the classpath. This enforcement can break the build, or " diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/BUILD b/src/main/java/com/google/devtools/build/lib/rules/objc/BUILD index 4d3bdace65..6e665633b7 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/BUILD +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/BUILD @@ -28,6 +28,7 @@ java_library( "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:bundlemerge_java_proto", "//src/main/protobuf:extra_actions_base_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:plmerge_java_proto", "//third_party:auto_value", "//third_party:guava", 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 48025e15b2..6c35ba171f 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,7 +20,9 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -35,6 +37,8 @@ public class J2ObjcCommandLineOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to the J2ObjC tool." ) public List<String> translationFlags; @@ -43,6 +47,8 @@ public class J2ObjcCommandLineOptions extends FragmentOptions { name = "j2objc_dead_code_removal", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to perform J2ObjC dead code removal to strip unused code from the final app " + "bundle." @@ -54,6 +60,8 @@ public class J2ObjcCommandLineOptions extends FragmentOptions { defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Allows J2ObjC to strip dead code reported by ProGuard. Takes a label that can " + "generate a dead code report as argument." @@ -64,6 +72,8 @@ public class J2ObjcCommandLineOptions extends FragmentOptions { name = "explicit_jre_deps", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "This flag is a noop and will be removed." ) public boolean explicitJreDeps; @@ -72,6 +82,8 @@ public class J2ObjcCommandLineOptions extends FragmentOptions { name = "experimental_j2objc_header_map", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to generate J2ObjC header map in parallel of J2ObjC transpilation." ) public boolean experimentalJ2ObjcHeaderMap; 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 a82f6d9ed7..ee7427fe04 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,9 @@ 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -34,6 +36,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "9.3", category = "run", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The version of iOS to run on the simulator when running or testing. This is ignored " + "for ios_test rules if a target device is specified in the rule." @@ -44,6 +48,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "ios_simulator_device", defaultValue = "iPhone 5s", category = "run", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -56,6 +62,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "2.0", category = "run", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The version of watchOS to run on the simulator when running or testing." ) public DottedVersion watchosSimulatorVersion; @@ -64,6 +72,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "watchos_simulator_device", defaultValue = "Apple Watch - 38mm", category = "run", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -76,6 +86,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "9.0", category = "run", converter = DottedVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The version of tvOS to run on the simulator when running or testing." ) public DottedVersion tvosSimulatorVersion; @@ -84,6 +96,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "tvos_simulator_device", defaultValue = "Apple TV 1080p", category = "run", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -95,6 +109,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_generate_linkmap", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Specifies whether to generate a linkmap file." ) public boolean generateLinkmap; @@ -104,6 +120,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { allowMultiple = true, defaultValue = "", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Additional options to pass to Objective C compilation." ) public List<String> copts; @@ -112,6 +130,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "ios_memleaks", defaultValue = "false", category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enable checking for memory leaks in ios_test targets." ) public boolean runMemleaks; @@ -120,6 +140,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "experimental_enable_objc_cc_deps", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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." @@ -131,6 +153,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "-O0,-DDEBUG=1", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = CommaSeparatedOptionListConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Uses these strings as objc fastbuild compiler options." ) public List<String> fastbuildOptions; @@ -139,6 +163,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "experimental_objc_enable_module_maps", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enables module map generation and interpretation." ) public boolean enableModuleMaps; @@ -147,6 +173,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_enable_binary_stripping", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to perform symbol and dead-code strippings on linked binaries. Binary " + "strippings will be performed if both this flag and --compilationMode=opt are " @@ -158,6 +186,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "apple_generate_dsym", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to generate debug symbol(.dSYM) file(s)." ) public boolean appleGenerateDsym; @@ -166,6 +196,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "ios_signing_cert_name", defaultValue = "null", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Certificate name to use for iOS signing. If not set will fall back to provisioning " + "profile. May be the certificate's keychain identity preference or (substring) of " @@ -177,6 +209,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "experimental_use_absolute_paths_for_actions", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, then all actions objc actions will be executed with absolute paths." ) public boolean useAbsolutePathsForActions; @@ -185,6 +219,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "xcode_override_workspace_root", defaultValue = "", category = "xcode", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, then this path will be used as workspace_root and mainGroup path when " + "generating an .xcodeproj/project.pbxproj file." @@ -195,6 +231,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_includes_prioritize_static_libs", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, the linker invocation will contain static library includes before frameworks" + " and system libraries." @@ -205,6 +243,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_debug_with_GLIBCXX", defaultValue = "true", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, " + " GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS." @@ -216,6 +256,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "null", category = "flags", converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Location of a .entitlements file that is merged into any iOS signing action in this " + "build." @@ -226,6 +268,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "device_debug_entitlements", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, and compilation mode is not 'opt', objc apps will include debug entitlements " + "when signing." @@ -236,6 +280,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "deprecated_generate_xcode_project", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, will generate xcode project for targets that support this. Will be removed soon." ) @@ -267,6 +313,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "experimental_objc_crosstool", defaultValue = "off", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, converter = ObjcCrosstoolUsageConverter.class ) public ObjcCrosstoolMode objcCrosstoolMode; @@ -275,6 +323,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_use_dotd_pruning", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, .d files emited by clang will be used to prune the set of inputs passed into objc " + "compiles." @@ -285,6 +335,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "enable_apple_binary_native_protos", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set, apple_binary will generate and link objc protos into the output binary." ) public boolean enableAppleBinaryNativeProtos; @@ -293,6 +345,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "experimental_objc_header_thinning", defaultValue = "false", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set then ObjcCompile actions will have their action inputs reduced by running a tool " + "to detect which headers are actually required for compilation." @@ -303,6 +357,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { name = "objc_header_thinning_partition_size", defaultValue = "120", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The maximum number of source files to process within in each header scanning action." ) public int objcHeaderThinningPartitionSize; @@ -312,6 +368,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "@bazel_tools//tools/objc:header_scanner", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Location of tool to scan Objective-C code for inclusions and output a .headers_list " + "file." @@ -323,6 +381,8 @@ public class ObjcCommandLineOptions extends FragmentOptions { defaultValue = "null", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Location of target that will provide the appropriate Apple SDK for the current build " + "configuration." diff --git a/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoConfiguration.java index 83faa0783e..30c278a2df 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoConfiguration.java @@ -30,6 +30,8 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -49,17 +51,23 @@ public class ProtoConfiguration extends Fragment { * Command line options. */ public static class Options extends FragmentOptions { - @Option(name = "protocopt", - allowMultiple = true, - defaultValue = "", - category = "flags", - help = "Additional options to pass to the protobuf compiler.") + @Option( + name = "protocopt", + allowMultiple = true, + defaultValue = "", + category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Additional options to pass to the protobuf compiler." + ) public List<String> protocOpts; @Option( name = "experimental_proto_extra_actions", defaultValue = "false", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Run extra actions for alternative Java api versions in a proto_library." ) public boolean experimentalProtoExtraActions; @@ -69,6 +77,8 @@ public class ProtoConfiguration extends Fragment { defaultValue = "@com_google_protobuf//:protoc", category = "flags", converter = BuildConfiguration.LabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The label of the proto-compiler." ) public Label protoCompiler; @@ -78,6 +88,8 @@ public class ProtoConfiguration extends Fragment { defaultValue = "@com_google_protobuf_javalite//:javalite_toolchain", category = "flags", converter = BuildConfiguration.EmptyToNullLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Label of proto_lang_toolchain() which describes how to compile JavaLite protos" ) public Label protoToolchainForJavaLite; @@ -87,6 +99,8 @@ public class ProtoConfiguration extends Fragment { defaultValue = "@com_google_protobuf_java//:java_toolchain", category = "flags", converter = BuildConfiguration.EmptyToNullLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Label of proto_lang_toolchain() which describes how to compile Java protos" ) public Label protoToolchainForJava; @@ -96,6 +110,8 @@ public class ProtoConfiguration extends Fragment { defaultValue = "@com_google_protobuf_cc//:cc_toolchain", category = "flags", converter = BuildConfiguration.EmptyToNullLabelConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Label of proto_lang_toolchain() which describes how to compile C++ protos" ) public Label protoToolchainForCc; @@ -105,6 +121,8 @@ public class ProtoConfiguration extends Fragment { defaultValue = "strict", converter = BuildConfiguration.StrictDepsConverter.class, category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If true, checks that a proto_library target explicitly declares all directly " + "used targets as dependencies." @@ -112,20 +130,24 @@ public class ProtoConfiguration extends Fragment { public StrictDepsMode strictProtoDeps; @Option( - name = "cc_proto_library_header_suffixes", - defaultValue = ".pb.h", - category = "semantics", - help = "Sets the prefixes of header files that a cc_proto_library creates.", - converter = Converters.CommaSeparatedOptionListConverter.class + name = "cc_proto_library_header_suffixes", + defaultValue = ".pb.h", + category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Sets the prefixes of header files that a cc_proto_library creates.", + converter = Converters.CommaSeparatedOptionListConverter.class ) public List<String> ccProtoLibraryHeaderSuffixes; @Option( - name = "cc_proto_library_source_suffixes", - defaultValue = ".pb.cc", - category = "semantics", - help = "Sets the prefixes of source files that a cc_proto_library creates.", - converter = Converters.CommaSeparatedOptionListConverter.class + name = "cc_proto_library_source_suffixes", + defaultValue = ".pb.cc", + category = "semantics", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Sets the prefixes of source files that a cc_proto_library creates.", + converter = Converters.CommaSeparatedOptionListConverter.class ) public List<String> ccProtoLibrarySourceSuffixes; @@ -133,6 +155,8 @@ public class ProtoConfiguration extends Fragment { name = "reuseJavaCompileActionsFromProtoLibrary", defaultValue = "true", category = "experimental", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "ignored" ) public boolean reuseJavaCompileActionsFromProtoLibrary; diff --git a/src/main/java/com/google/devtools/build/lib/rules/python/PythonOptions.java b/src/main/java/com/google/devtools/build/lib/rules/python/PythonOptions.java index 0b6deb2086..1960a51231 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/python/PythonOptions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/python/PythonOptions.java @@ -16,6 +16,8 @@ package com.google.devtools.build.lib.rules.python; import com.google.devtools.build.lib.analysis.config.FragmentOptions; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** * Python-related command-line options. @@ -32,11 +34,15 @@ public class PythonOptions extends FragmentOptions { } } - @Option(name = "force_python", - defaultValue = "null", - category = "version", - converter = PythonVersionConverter.class, - help = "Overrides default_python_version attribute. Can be \"PY2\" or \"PY3\".") + @Option( + name = "force_python", + defaultValue = "null", + category = "version", + converter = PythonVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Overrides default_python_version attribute. Can be \"PY2\" or \"PY3\"." + ) public PythonVersion forcePython; @Option( @@ -44,6 +50,8 @@ public class PythonOptions extends FragmentOptions { defaultValue = "null", category = "version", converter = PythonVersionConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Overrides default_python_version attribute for the host configuration." + " Can be \"PY2\" or \"PY3\"." 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 a8ade4e882..187aa12e23 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 @@ -20,8 +20,10 @@ import com.google.devtools.build.lib.events.Location; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.io.OutputStream; import java.io.PrintStream; @@ -61,6 +63,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "show_progress", defaultValue = "true", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Display progress messages during a build." ) public boolean showProgress; @@ -69,6 +73,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "show_task_finish", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Display progress messages when tasks complete, not just when they start." ) public boolean showTaskFinish; @@ -77,6 +83,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "show_progress_rate_limit", defaultValue = "0.03", // A nice middle ground; snappy but not too spammy in logs. category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Minimum number of seconds between progress messages in the output." ) public double showProgressRateLimit; @@ -86,6 +94,8 @@ public class BlazeCommandEventHandler implements EventHandler { defaultValue = "auto", converter = UseColorConverter.class, category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use terminal controls to colorize output." ) public UseColor useColorEnum; @@ -95,6 +105,8 @@ public class BlazeCommandEventHandler implements EventHandler { defaultValue = "auto", converter = UseCursesConverter.class, category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use terminal cursor controls to minimize scrolling output" ) public UseCurses useCursesEnum; @@ -103,6 +115,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "terminal_columns", defaultValue = "80", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A system-generated parameter which specifies the terminal width in columns." ) public int terminalColumns; @@ -111,6 +125,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "isatty", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "A system-generated parameter which is used to notify the " + "server whether this client is running in a terminal. " @@ -126,6 +142,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "emacs", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, 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 " @@ -137,6 +155,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "show_timestamps", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Include timestamps in messages" ) public boolean showTimestamp; @@ -145,6 +165,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "progress_in_terminal_title", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Show the command progress in the terminal title. " + "Useful to see what blaze is doing when having multiple terminal tabs." @@ -155,6 +177,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "experimental_external_repositories", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Use external repositories for improved stability and speed when available." ) public boolean externalRepositories; @@ -163,6 +187,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "force_experimental_external_repositories", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Forces --experimental_external_repositories." ) public boolean forceExternalRepositories; @@ -171,6 +197,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "experimental_ui", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Switches to an alternative progress bar that more explicitly shows progress, such " + "as loaded packages and executed actions." @@ -181,6 +209,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "experimental_ui_debug_all_events", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Report all events known to the experimental new Bazel UI." ) public boolean experimentalUiDebugAllEvents; @@ -189,6 +219,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "experimental_ui_actions_shown", defaultValue = "3", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Number of concurrent actions shown in the alternative progress bar; each " + "action is shown on a separate line. The alternative progress bar always shows " @@ -201,6 +233,8 @@ public class BlazeCommandEventHandler implements EventHandler { name = "experimental_ui_limit_console_output", defaultValue = "0", category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Number of bytes to which the experimental UI will limit its output (non-positive " + "values indicate unlimited). Once the limit is approaching, the experimental UI " 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 8e242f012d..17fb032ac5 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 @@ -298,6 +298,7 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "fatal_event_bus_exceptions", defaultValue = "false", // NOTE: purely decorative! + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT, OptionEffectTag.LOSES_INCREMENTAL_STATE}, help = "Whether or not to exit if an exception is thrown by an internal EventBus handler." @@ -322,6 +323,7 @@ public class BlazeServerStartupOptions extends OptionsBase { defaultValue = "false", category = "server startup", documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.UNKNOWN}, metadataTags = OptionMetadataTag.DEPRECATED, help = "If true, %{product} tries to use the operating system's file watch service for local " 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 bb784a8b06..110ef96b95 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 @@ -105,6 +105,7 @@ public class CommonCommandOptions extends OptionsBase { name = "all_incompatible_changes", defaultValue = "null", category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.UNKNOWN}, metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE}, expansionFunction = AllIncompatibleChangesExpansion.class, @@ -118,6 +119,7 @@ public class CommonCommandOptions extends OptionsBase { name = "config", defaultValue = "", category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.UNKNOWN}, allowMultiple = true, help = @@ -144,6 +146,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "client_env", defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, effectTags = {OptionEffectTag.CHANGES_INPUTS}, converter = Converters.AssignmentConverter.class, @@ -156,7 +159,9 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "ignore_client_env", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + effectTags = {OptionEffectTag.NO_OP}, metadataTags = OptionMetadataTag.DEPRECATED, deprecationWarning = "Deprecated, no-op.", help = "Deprecated, no-op." @@ -168,6 +173,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "client_cwd", defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, effectTags = {OptionEffectTag.CHANGES_INPUTS}, converter = OptionsUtils.PathFragmentConverter.class, @@ -194,6 +200,7 @@ public class CommonCommandOptions extends OptionsBase { name = "default_override", defaultValue = "", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.CHANGES_INPUTS}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, converter = OptionOverrideConverter.class, @@ -206,6 +213,7 @@ public class CommonCommandOptions extends OptionsBase { name = "rc_source", defaultValue = "", allowMultiple = true, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.CHANGES_INPUTS}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "" @@ -215,6 +223,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "always_profile_slow_operations", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Whether profiling slow operations is always turned on" @@ -225,6 +234,7 @@ public class CommonCommandOptions extends OptionsBase { name = "allow_undefined_configs", defaultValue = "true", category = "flags", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT}, help = "Do not throw an error when the config is not defined." ) @@ -272,6 +282,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "gc_watchdog", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.NO_OP}, metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, deprecationWarning = "Ignoring: this option is no longer supported", @@ -342,6 +354,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "experimental_allow_project_files", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.CHANGES_INPUTS}, metadataTags = {OptionMetadataTag.EXPERIMENTAL}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, @@ -352,6 +365,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "block_for_lock", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = diff --git a/src/main/java/com/google/devtools/build/lib/runtime/HostJvmStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/HostJvmStartupOptions.java index 158b661d36..3661b1ecc0 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/HostJvmStartupOptions.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/HostJvmStartupOptions.java @@ -15,8 +15,9 @@ package com.google.devtools.build.lib.runtime; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; - +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** @@ -28,39 +29,57 @@ import java.util.List; */ public class HostJvmStartupOptions extends OptionsBase { - @Option(name = "host_javabase", - defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. - category = "host jvm startup", - valueHelp = "<jvm path>", - help = "Path to the JVM used to execute Blaze itself.") + @Option( + name = "host_javabase", + defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. + category = "host jvm startup", + valueHelp = "<jvm path>", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Path to the JVM used to execute Blaze itself." + ) public String hostJavabase; - @Option(name = "host_jvm_args", - defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. - category = "host jvm startup", - allowMultiple = true, - valueHelp = "<jvm_arg>", - help = "Flags to pass to the JVM executing Blaze.") + @Option( + name = "host_jvm_args", + defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. + category = "host jvm startup", + allowMultiple = true, + valueHelp = "<jvm_arg>", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Flags to pass to the JVM executing Blaze." + ) public List<String> hostJvmArgs; - @Option(name = "host_jvm_profile", - defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. - category = "host jvm startup", - valueHelp = "<profiler_name>", - help = "Convenience option to add some profiler/debugger-specific JVM startup flags. " - + "Blaze has a list of known values that it maps to hard-coded JVM startup flags, " - + "possibly searching some hardcoded paths for certain files.") + @Option( + name = "host_jvm_profile", + defaultValue = "", // NOTE: purely decorative! See BlazeServerStartupOptions. + category = "host jvm startup", + valueHelp = "<profiler_name>", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Convenience option to add some profiler/debugger-specific JVM startup flags. " + + "Blaze has a list of known values that it maps to hard-coded JVM startup flags, " + + "possibly searching some hardcoded paths for certain files." + ) public String hostJvmProfile; - @Option(name = "host_jvm_debug", - defaultValue = "null", // NOTE: purely decorative! See BlazeServerStartupOptions. - category = "host jvm startup", - help = "Convenience option to add some additional JVM startup flags, which cause " - + "the JVM to wait during startup until you connect from a JDWP-compliant debugger " - + "(like Eclipse) to port 5005.", - expansion = { - "--host_jvm_args=-Xdebug", - "--host_jvm_args=-Xrunjdwp:transport=dt_socket,server=y,address=5005", - }) + @Option( + name = "host_jvm_debug", + defaultValue = "null", // NOTE: purely decorative! See BlazeServerStartupOptions. + category = "host jvm startup", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Convenience option to add some additional JVM startup flags, which cause " + + "the JVM to wait during startup until you connect from a JDWP-compliant debugger " + + "(like Eclipse) to port 5005.", + expansion = { + "--host_jvm_args=-Xdebug", + "--host_jvm_args=-Xrunjdwp:transport=dt_socket,server=y,address=5005", + } + ) public Void hostJvmDebug; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/TerminalTestResultNotifier.java b/src/main/java/com/google/devtools/build/lib/runtime/TerminalTestResultNotifier.java index 36c2bfc7c4..7624c757b6 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/TerminalTestResultNotifier.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/TerminalTestResultNotifier.java @@ -22,8 +22,10 @@ import com.google.devtools.build.lib.util.StringUtil; import com.google.devtools.build.lib.util.io.AnsiTerminalPrinter; import com.google.devtools.build.lib.view.test.TestStatus.BlazeTestStatus; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.ArrayList; import java.util.List; import java.util.Set; @@ -48,18 +50,28 @@ public class TerminalTestResultNotifier implements TestResultNotifier { * Flags specific to test summary reporting. */ public static class TestSummaryOptions extends OptionsBase { - @Option(name = "verbose_test_summary", - defaultValue = "true", - category = "verbosity", - help = "If true, print additional information (timing, number of failed runs, etc) in the" - + " test summary.") + @Option( + name = "verbose_test_summary", + defaultValue = "true", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "If true, print additional information (timing, number of failed runs, etc) in the" + + " test summary." + ) public boolean verboseSummary; - @Option(name = "test_verbose_timeout_warnings", - defaultValue = "false", - category = "verbosity", - help = "If true, print additional warnings when the actual test execution time does not " + - "match the timeout defined by the test (whether implied or explicit).") + @Option( + name = "test_verbose_timeout_warnings", + defaultValue = "false", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "If true, print additional warnings when the actual test execution time does not " + + "match the timeout defined by the test (whether implied or explicit)." + ) public boolean testVerboseTimeoutWarnings; } 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 d2d3f5a58b..18455b17e5 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 @@ -27,25 +27,28 @@ import com.google.devtools.build.lib.util.ExitCode; import com.google.devtools.common.options.InvocationPolicyEnforcer; import com.google.devtools.common.options.InvocationPolicyParser; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; 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 com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.Collection; import java.util.List; -/** - * The 'blaze canonicalize-flags' command. - */ -@Command(name = "canonicalize-flags", - options = { CanonicalizeCommand.Options.class }, - allowResidue = true, - mustRunInWorkspace = false, - shortDescription = "Canonicalizes a list of %{product} options.", - help = "This command canonicalizes a list of %{product} options. Don't forget to prepend " - + " '--' to end option parsing before the flags to canonicalize.\n" - + "%{options}") +/** The 'blaze canonicalize-flags' command. */ +@Command( + name = "canonicalize-flags", + options = {CanonicalizeCommand.Options.class}, + allowResidue = true, + mustRunInWorkspace = false, + shortDescription = "Canonicalizes a list of %{product} options.", + help = + "This command canonicalizes a list of %{product} options. Don't forget to prepend " + + " '--' to end option parsing before the flags to canonicalize.\n" + + "%{options}" +) public final class CanonicalizeCommand implements BlazeCommand { public static class Options extends OptionsBase { @@ -53,6 +56,8 @@ public final class CanonicalizeCommand implements BlazeCommand { name = "for_command", defaultValue = "build", category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The command for which the options should be canonicalized." ) public String forCommand; @@ -60,6 +65,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "invocation_policy", defaultValue = "", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Applies an invocation policy to the options to be canonicalized." ) public String invocationPolicy; @@ -67,6 +74,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "canonicalize_policy", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Output the canonical policy, after expansion and filtering. To keep the output " + "clean, the canonicalized command arguments will NOT be shown when this option is " @@ -78,6 +87,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "show_warnings", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Output parser warnings to standard error (e.g. for conflicting flag options)." ) public boolean showWarnings; @@ -92,6 +103,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "flag_clash_canary", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED ) public boolean flagClashCanary; @@ -99,6 +112,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "flag_clash_canary_expander1", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, expansion = {"--flag_clash_canary=1"} ) @@ -107,6 +122,8 @@ public final class CanonicalizeCommand implements BlazeCommand { @Option( name = "flag_clash_canary_expander2", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, expansion = {"--flag_clash_canary=0"} ) diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java index ef107885dd..375a581e7f 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java @@ -31,9 +31,11 @@ import com.google.devtools.build.lib.util.ShellEscaper; import com.google.devtools.build.lib.vfs.FileSystemUtils; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.FileDescriptor; import java.io.FileOutputStream; import java.io.IOException; @@ -60,6 +62,8 @@ public final class CleanCommand implements BlazeCommand { name = "clean_style", defaultValue = "", category = "clean", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Can be 'expunge', 'expunge_async', or 'async'." ) public String cleanStyle; @@ -69,6 +73,8 @@ public final class CleanCommand implements BlazeCommand { defaultValue = "null", category = "clean", expansion = "--clean_style=expunge", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, clean removes the entire working tree for this %{product} " + "instance, which includes all %{product}-created temporary and build output " @@ -81,6 +87,8 @@ public final class CleanCommand implements BlazeCommand { defaultValue = "null", category = "clean", expansion = "--clean_style=expunge_async", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, clean asynchronously removes the entire working tree for " + "this %{product} instance, which includes all %{product}-created temporary and " @@ -95,6 +103,8 @@ public final class CleanCommand implements BlazeCommand { defaultValue = "null", category = "clean", expansion = "--clean_style=async", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If specified, clean asynchronously removes the entire working tree for " + "this %{product} instance, which includes all %{product}-created temporary and " diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/DumpCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/DumpCommand.java index 0e7965ea2d..68b6153217 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/DumpCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/DumpCommand.java @@ -28,10 +28,11 @@ import com.google.devtools.build.lib.util.ExitCode; import com.google.devtools.build.lib.vfs.FileSystemUtils; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; - +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.io.PrintStream; import java.util.ArrayList; @@ -41,18 +42,19 @@ import java.util.HashMap; import java.util.List; import java.util.Map; -/** - * Implementation of the dump command. - */ -@Command(allowResidue = false, - mustRunInWorkspace = false, - options = { DumpCommand.DumpOptions.class }, - help = "Usage: %{product} dump <options>\n" - + "Dumps the internal state of the %{product} server process. This command is provided " - + "as an aid to debugging, not as a stable interface, so users should not try to " - + "parse the output; instead, use 'query' or 'info' for this purpose.\n%{options}", - name = "dump", - shortDescription = "Dumps the internal state of the %{product} server process.") +/** Implementation of the dump command. */ +@Command( + allowResidue = false, + mustRunInWorkspace = false, + options = {DumpCommand.DumpOptions.class}, + help = + "Usage: %{product} dump <options>\n" + + "Dumps the internal state of the %{product} server process. This command is provided " + + "as an aid to debugging, not as a stable interface, so users should not try to " + + "parse the output; instead, use 'query' or 'info' for this purpose.\n%{options}", + name = "dump", + shortDescription = "Dumps the internal state of the %{product} server process." +) public class DumpCommand implements BlazeCommand { /** @@ -61,35 +63,55 @@ public class DumpCommand implements BlazeCommand { */ public static class DumpOptions extends OptionsBase { - @Option(name = "packages", - defaultValue = "false", - category = "verbosity", - help = "Dump package cache content.") + @Option( + name = "packages", + defaultValue = "false", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Dump package cache content." + ) public boolean dumpPackages; - @Option(name = "vfs", - defaultValue = "false", - category = "verbosity", - help = "Dump virtual filesystem cache content.") + @Option( + name = "vfs", + defaultValue = "false", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Dump virtual filesystem cache content." + ) public boolean dumpVfs; - @Option(name = "action_cache", - defaultValue = "false", - category = "verbosity", - help = "Dump action cache content.") + @Option( + name = "action_cache", + defaultValue = "false", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Dump action cache content." + ) public boolean dumpActionCache; - @Option(name = "rule_classes", - defaultValue = "false", - category = "verbosity", - help = "Dump rule classes.") + @Option( + name = "rule_classes", + defaultValue = "false", + category = "verbosity", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Dump rule classes." + ) public boolean dumpRuleClasses; - @Option(name = "skyframe", - defaultValue = "off", - category = "verbosity", - converter = SkyframeDumpEnumConverter.class, - help = "Dump Skyframe graph: 'off', 'summary', or 'detailed'.") + @Option( + name = "skyframe", + defaultValue = "off", + category = "verbosity", + converter = SkyframeDumpEnumConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Dump Skyframe graph: 'off', 'summary', or 'detailed'." + ) public SkyframeDumpOption dumpSkyframe; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/HelpCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/HelpCommand.java index 9790984923..ed64a4f088 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/HelpCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/HelpCommand.java @@ -37,9 +37,11 @@ import com.google.devtools.build.lib.util.StringUtil; import com.google.devtools.build.lib.util.io.OutErr; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.ArrayList; import java.util.Collections; import java.util.HashSet; @@ -48,17 +50,16 @@ import java.util.Locale; import java.util.Map; import java.util.Set; -/** - * The 'blaze help' command, which prints all available commands as well as - * specific help pages. - */ -@Command(name = "help", - options = { HelpCommand.Options.class }, - allowResidue = true, - mustRunInWorkspace = false, - shortDescription = "Prints help for commands, or the index.", - completion = "command|{startup_options,target-syntax,info-keys}", - help = "resource:help.txt") +/** The 'blaze help' command, which prints all available commands as well as specific help pages. */ +@Command( + name = "help", + options = {HelpCommand.Options.class}, + allowResidue = true, + mustRunInWorkspace = false, + shortDescription = "Prints help for commands, or the index.", + completion = "command|{startup_options,target-syntax,info-keys}", + help = "resource:help.txt" +) public final class HelpCommand implements BlazeCommand { private static final Joiner SPACE_JOINER = Joiner.on(" "); @@ -70,26 +71,38 @@ public final class HelpCommand implements BlazeCommand { public static class Options extends OptionsBase { - @Option(name = "help_verbosity", - category = "help", - defaultValue = "medium", - converter = Converters.HelpVerbosityConverter.class, - help = "Select the verbosity of the help command.") + @Option( + name = "help_verbosity", + category = "help", + defaultValue = "medium", + converter = Converters.HelpVerbosityConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Select the verbosity of the help command." + ) public OptionsParser.HelpVerbosity helpVerbosity; - @Option(name = "long", - abbrev = 'l', - defaultValue = "null", - category = "help", - expansion = {"--help_verbosity=long"}, - help = "Show full description of each option, instead of just its name.") + @Option( + name = "long", + abbrev = 'l', + defaultValue = "null", + category = "help", + expansion = {"--help_verbosity=long"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Show full description of each option, instead of just its name." + ) public Void showLongFormOptions; - @Option(name = "short", - defaultValue = "null", - category = "help", - expansion = {"--help_verbosity=short"}, - help = "Show only the names of the options, not their types or meanings.") + @Option( + name = "short", + defaultValue = "null", + category = "help", + expansion = {"--help_verbosity=short"}, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Show only the names of the options, not their types or meanings." + ) public Void showShortFormOptions; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/InfoCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/InfoCommand.java index 27eb32c3fc..802d18c1d9 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/InfoCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/InfoCommand.java @@ -28,9 +28,11 @@ import com.google.devtools.build.lib.util.AbruptExitException; import com.google.devtools.build.lib.util.ExitCode; import com.google.devtools.build.lib.util.io.OutErr; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.util.List; @@ -61,10 +63,14 @@ import java.util.TreeMap; public class InfoCommand implements BlazeCommand { public static class Options extends OptionsBase { - @Option(name = "show_make_env", - defaultValue = "false", - category = "misc", - help = "Include the \"Make\" environment in the output.") + @Option( + name = "show_make_env", + defaultValue = "false", + category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Include the \"Make\" environment in the output." + ) public boolean showMakeEnvironment; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/ProfileCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/ProfileCommand.java index 91c4c99d77..7211a87679 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/ProfileCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/ProfileCommand.java @@ -38,26 +38,27 @@ import com.google.devtools.build.lib.util.TimeUtilities; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; - +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.BufferedOutputStream; import java.io.IOException; import java.io.PrintStream; import java.util.EnumMap; import java.util.regex.Pattern; -/** - * Command line wrapper for analyzing Blaze build profiles. - */ -@Command(name = "analyze-profile", - options = { ProfileCommand.ProfileOptions.class }, - shortDescription = "Analyzes build profile data.", - help = "resource:analyze-profile.txt", - allowResidue = true, - completion = "path", - mustRunInWorkspace = false) +/** Command line wrapper for analyzing Blaze build profiles. */ +@Command( + name = "analyze-profile", + options = {ProfileCommand.ProfileOptions.class}, + shortDescription = "Analyzes build profile data.", + help = "resource:analyze-profile.txt", + allowResidue = true, + completion = "path", + mustRunInWorkspace = false +) public final class ProfileCommand implements BlazeCommand { public static class DumpConverter extends Converters.StringSetConverter { @@ -70,6 +71,8 @@ public final class ProfileCommand implements BlazeCommand { @Option( name = "chart", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If --nochart is present, do not include the task chart with --html_details." + " The default is --chart." @@ -79,6 +82,8 @@ public final class ProfileCommand implements BlazeCommand { @Option( name = "combine", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If present, the statistics of all given profile files will be combined and output" + " in text/--html format to the file named in the argument. Does not output HTML" @@ -86,29 +91,46 @@ public final class ProfileCommand implements BlazeCommand { ) public String combine; - @Option(name = "dump", - abbrev='d', - converter = DumpConverter.class, - defaultValue = "null", - help = "output full profile data dump either in human-readable 'text' format or" - + " script-friendly 'raw' format, either sorted or unsorted.") + @Option( + name = "dump", + abbrev = 'd', + converter = DumpConverter.class, + defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "output full profile data dump either in human-readable 'text' format or" + + " script-friendly 'raw' format, either sorted or unsorted." + ) public String dumpMode; - @Option(name = "html", - defaultValue = "false", - help = "If present, an HTML file visualizing the tasks of the profiled build is created. " - + "The name of the html file is the name of the profile file plus '.html'.") + @Option( + name = "html", + defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "If present, an HTML file visualizing the tasks of the profiled build is created. " + + "The name of the html file is the name of the profile file plus '.html'." + ) public boolean html; - @Option(name = "html_pixels_per_second", - defaultValue = "50", - help = "Defines the scale of the time axis of the task diagram. The unit is " - + "pixels per second. Default is 50 pixels per second. ") + @Option( + name = "html_pixels_per_second", + defaultValue = "50", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Defines the scale of the time axis of the task diagram. The unit is " + + "pixels per second. Default is 50 pixels per second. " + ) public int htmlPixelsPerSecond; @Option( name = "html_details", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If --html_details is present, the task diagram contains all tasks of the profile " + " and performance statistics on user-defined and built-in Skylark functions. " @@ -120,6 +142,8 @@ public final class ProfileCommand implements BlazeCommand { @Option( name = "html_histograms", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If --html_histograms and --html_details is present, the HTML output will display" + " histograms for Skylark functions clicked in the statistics table. This will" @@ -131,6 +155,8 @@ public final class ProfileCommand implements BlazeCommand { name = "task_tree", defaultValue = "null", converter = Converters.RegexPatternConverter.class, + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Print the tree of profiler tasks from all tasks matching the given regular expression." ) @@ -139,20 +165,30 @@ public final class ProfileCommand implements BlazeCommand { @Option( name = "task_tree_threshold", defaultValue = "50", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "When printing a task tree, will skip tasks with a duration that is less than the" + " given threshold in milliseconds." ) public long taskTreeThreshold; - @Option(name = "vfs_stats", - defaultValue = "false", - help = "If present, include VFS path statistics.") + @Option( + name = "vfs_stats", + defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "If present, include VFS path statistics." + ) public boolean vfsStats; - @Option(name = "vfs_stats_limit", - defaultValue = "-1", - help = "Maximum number of VFS path statistics to print.") + @Option( + name = "vfs_stats_limit", + defaultValue = "-1", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = "Maximum number of VFS path statistics to print." + ) public int vfsStatsLimit; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/RunCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/RunCommand.java index 6a6dbbc66a..8d146945f3 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/RunCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/RunCommand.java @@ -62,9 +62,11 @@ import com.google.devtools.build.lib.vfs.FileSystemUtils; 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.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.util.ArrayList; @@ -92,6 +94,8 @@ public class RunCommand implements BlazeCommand { name = "script_path", category = "run", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, converter = OptionsUtils.PathFragmentConverter.class, help = "If set, write a shell script to the given file which invokes the " diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/ShutdownCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/ShutdownCommand.java index 13a5d8df9d..6cfe6a0be6 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/commands/ShutdownCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/ShutdownCommand.java @@ -19,9 +19,11 @@ import com.google.devtools.build.lib.runtime.Command; import com.google.devtools.build.lib.runtime.CommandEnvironment; import com.google.devtools.build.lib.util.ExitCode; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser; import com.google.devtools.common.options.OptionsProvider; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** * The 'blaze shutdown' command. @@ -37,12 +39,17 @@ public final class ShutdownCommand implements BlazeCommand { public static class Options extends OptionsBase { - @Option(name="iff_heap_size_greater_than", - defaultValue = "0", - category = "misc", - help="Iff non-zero, then shutdown will only shut down the " + - "server if the total memory (in MB) consumed by the JVM " + - "exceeds this value.") + @Option( + name = "iff_heap_size_greater_than", + defaultValue = "0", + category = "misc", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Iff non-zero, then shutdown will only shut down the " + + "server if the total memory (in MB) consumed by the JVM " + + "exceeds this value." + ) public int heapSizeLimit; } diff --git a/src/main/java/com/google/devtools/build/lib/runtime/mobileinstall/MobileInstallCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/mobileinstall/MobileInstallCommand.java index ed9329ed27..4ed187fb39 100644 --- a/src/main/java/com/google/devtools/build/lib/runtime/mobileinstall/MobileInstallCommand.java +++ b/src/main/java/com/google/devtools/build/lib/runtime/mobileinstall/MobileInstallCommand.java @@ -39,30 +39,31 @@ import com.google.devtools.build.lib.util.io.OutErr; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.common.options.EnumConverter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionPriority; 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 com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.ArrayList; import java.util.Collection; import java.util.List; -/** - * Implementation of the 'mobile-install' command. - */ - @Command(name = "mobile-install", - builds = true, - options = { MobileInstallCommand.Options.class, WriteAdbArgsAction.Options.class }, - inherits = { BuildCommand.class }, - shortDescription = "Installs targets to mobile devices.", - completion = "label", - allowResidue = true, - help = "resource:mobile-install.txt") +/** Implementation of the 'mobile-install' command. */ +@Command( + name = "mobile-install", + builds = true, + options = {MobileInstallCommand.Options.class, WriteAdbArgsAction.Options.class}, + inherits = {BuildCommand.class}, + shortDescription = "Installs targets to mobile devices.", + completion = "label", + allowResidue = true, + help = "resource:mobile-install.txt" +) public class MobileInstallCommand implements BlazeCommand { - /** * An enumeration of all the modes that mobile-install supports. */ @@ -102,21 +103,31 @@ public class MobileInstallCommand implements BlazeCommand { * Command line options for the 'mobile-install' command. */ public static final class Options extends OptionsBase { - @Option(name = "split_apks", - defaultValue = "false", - category = "mobile-install", - help = "Whether to use split apks to install and update the " - + "application on the device. Works only with devices with " - + "Marshmallow or later") + @Option( + name = "split_apks", + defaultValue = "false", + category = "mobile-install", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Whether to use split apks to install and update the " + + "application on the device. Works only with devices with " + + "Marshmallow or later" + ) public boolean splitApks; - @Option(name = "incremental", - category = "mobile-install", - defaultValue = "false", - help = "Whether to do an incremental install. If true, try to avoid unnecessary additional " - + "work by reading the state of the device the code is to be installed on and using " - + "that information to avoid unnecessary work. If false (the default), always do a " - + "full install.") + @Option( + name = "incremental", + category = "mobile-install", + defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Whether to do an incremental install. If true, try to avoid unnecessary additional " + + "work by reading the state of the device the code is to be installed on and using " + + "that information to avoid unnecessary work. If false (the default), always do a " + + "full install." + ) public boolean incremental; @Option( @@ -124,10 +135,14 @@ public class MobileInstallCommand implements BlazeCommand { category = "mobile-install", defaultValue = "classic", converter = ModeConverter.class, - help = "Select how to run mobile-install. \"classic\" runs the current version of " - + "mobile-install. \"skylark\" uses the new skylark version, which has support for " - + "android_test. \"skylark_incremental_res\" is the same as \"skylark\" plus incremental " - + "resource processing. \"skylark_incremental_res\" requires a device with root access.", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Select how to run mobile-install. \"classic\" runs the current version of " + + "mobile-install. \"skylark\" uses the new skylark version, which has support for " + + "android_test. \"skylark_incremental_res\" is the same as \"skylark\" plus " + + "incremental resource processing. \"skylark_incremental_res\" requires a device " + + "with root access.", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED ) public Mode mode; @@ -136,6 +151,8 @@ public class MobileInstallCommand implements BlazeCommand { name = "mobile_install_aspect", category = "mobile-install", defaultValue = "@android_test_support//tools/android/mobile_install:mobile-install.bzl", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "The aspect to use for mobile-install.", optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED ) diff --git a/src/main/java/com/google/devtools/build/lib/sandbox/BUILD b/src/main/java/com/google/devtools/build/lib/sandbox/BUILD index d93532c094..8048b8793b 100644 --- a/src/main/java/com/google/devtools/build/lib/sandbox/BUILD +++ b/src/main/java/com/google/devtools/build/lib/sandbox/BUILD @@ -22,6 +22,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/exec/local", "//src/main/java/com/google/devtools/build/lib/standalone", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", ], ) diff --git a/src/main/java/com/google/devtools/build/lib/sandbox/SandboxOptions.java b/src/main/java/com/google/devtools/build/lib/sandbox/SandboxOptions.java index 3c074aaf70..36a2aa9c01 100644 --- a/src/main/java/com/google/devtools/build/lib/sandbox/SandboxOptions.java +++ b/src/main/java/com/google/devtools/build/lib/sandbox/SandboxOptions.java @@ -19,8 +19,10 @@ import com.google.common.collect.Lists; import com.google.common.collect.Maps; import com.google.devtools.common.options.Converter; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParsingException; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; /** Options for sandboxed execution. */ @@ -71,6 +73,8 @@ public class SandboxOptions extends OptionsBase { name = "ignore_unsupported_sandboxing", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Do not print a warning when sandboxed execution is not supported on this system." ) public boolean ignoreUnsupportedSandboxing; @@ -79,6 +83,8 @@ public class SandboxOptions extends OptionsBase { name = "sandbox_debug", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Let the sandbox print debug information on execution. This might help developers of " + "Bazel or Skylark rules with debugging failures due to missing input files, etc." @@ -89,6 +95,8 @@ public class SandboxOptions extends OptionsBase { name = "experimental_sandbox_base", defaultValue = "", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Lets the sandbox create its sandbox directories underneath this path. Specify a path " + "on tmpfs (like /run/shm) to possibly improve performance a lot when your build / " @@ -101,6 +109,8 @@ public class SandboxOptions extends OptionsBase { name = "sandbox_fake_hostname", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Change the current hostname to 'localhost' for sandboxed actions." ) public boolean sandboxFakeHostname; @@ -109,6 +119,8 @@ public class SandboxOptions extends OptionsBase { name = "sandbox_fake_username", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Change the current username to 'nobody' for sandboxed actions." ) public boolean sandboxFakeUsername; @@ -118,27 +130,35 @@ public class SandboxOptions extends OptionsBase { allowMultiple = true, defaultValue = "", category = "config", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "For sandboxed actions, disallow access to this path." ) public List<String> sandboxBlockPath; @Option( - name = "sandbox_tmpfs_path", - allowMultiple = true, - defaultValue = "", - category = "config", - help = "For sandboxed actions, mount an empty, writable directory at this path" - + " (if supported by the sandboxing implementation, ignored otherwise)." + name = "sandbox_tmpfs_path", + allowMultiple = true, + defaultValue = "", + category = "config", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "For sandboxed actions, mount an empty, writable directory at this path" + + " (if supported by the sandboxing implementation, ignored otherwise)." ) public List<String> sandboxTmpfsPath; @Option( - name = "sandbox_writable_path", - allowMultiple = true, - defaultValue = "", - category = "config", - help = "For sandboxed actions, make an existing directory writable in the sandbox" - + " (if supported by the sandboxing implementation, ignored otherwise)." + name = "sandbox_writable_path", + allowMultiple = true, + defaultValue = "", + category = "config", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "For sandboxed actions, make an existing directory writable in the sandbox" + + " (if supported by the sandboxing implementation, ignored otherwise)." ) public List<String> sandboxWritablePath; @@ -148,6 +168,8 @@ public class SandboxOptions extends OptionsBase { converter = MountPairConverter.class, defaultValue = "", category = "config", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Add additional path pair to mount in sandbox." ) public List<ImmutableMap.Entry<String, String>> sandboxAdditionalMounts; diff --git a/src/main/java/com/google/devtools/build/lib/skyframe/LocalDiffAwareness.java b/src/main/java/com/google/devtools/build/lib/skyframe/LocalDiffAwareness.java index 4874d89d5c..882bc12d12 100644 --- a/src/main/java/com/google/devtools/build/lib/skyframe/LocalDiffAwareness.java +++ b/src/main/java/com/google/devtools/build/lib/skyframe/LocalDiffAwareness.java @@ -24,7 +24,9 @@ import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.ModifiedFileSet; import com.google.devtools.build.lib.vfs.PathFragment; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.IOException; import java.nio.file.FileSystems; import java.nio.file.Path; @@ -45,11 +47,14 @@ public abstract class LocalDiffAwareness implements DiffAwareness { */ public static final class Options extends OptionsBase { @Option( - name = "watchfs", - defaultValue = "false", - category = "server startup", - help = "If true, %{product} tries to use the operating system's file watch service for " - + "local changes instead of scanning every file for a change." + name = "watchfs", + defaultValue = "false", + category = "server startup", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "If true, %{product} tries to use the operating system's file watch service for " + + "local changes instead of scanning every file for a change." ) public boolean watchFS; } diff --git a/src/main/java/com/google/devtools/build/lib/ssd/BUILD b/src/main/java/com/google/devtools/build/lib/ssd/BUILD index fa77e290f4..78035e86c8 100644 --- a/src/main/java/com/google/devtools/build/lib/ssd/BUILD +++ b/src/main/java/com/google/devtools/build/lib/ssd/BUILD @@ -9,6 +9,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib:runtime", "//src/main/java/com/google/devtools/build/lib/actions", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//third_party:guava", ], ) diff --git a/src/main/java/com/google/devtools/build/lib/ssd/SsdOptions.java b/src/main/java/com/google/devtools/build/lib/ssd/SsdOptions.java index a9da284f24..d75c628a89 100644 --- a/src/main/java/com/google/devtools/build/lib/ssd/SsdOptions.java +++ b/src/main/java/com/google/devtools/build/lib/ssd/SsdOptions.java @@ -14,7 +14,9 @@ package com.google.devtools.build.lib.ssd; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; /** * Options that tune Bazel's performance in order to increase performance on workstations with an @@ -24,6 +26,8 @@ public class SsdOptions extends OptionsBase { @Option( name = "experimental_multi_threaded_digest", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Whether to always compute MD5 digests of files with multiple threads. Might improve " + "performance when using an SSD." diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java index 07419e4992..8c69a561b6 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java @@ -15,9 +15,11 @@ package com.google.devtools.build.lib.syntax; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.OptionsBase; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; import com.google.devtools.common.options.UsesOnlyCoreTypes; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.io.Serializable; /** @@ -37,9 +39,11 @@ import java.io.Serializable; public class SkylarkSemanticsOptions extends OptionsBase implements Serializable { // Used in an integration test to confirm that flags are visible to the interpreter. @Option( - name = "internal_skylark_flag_test_canary", - defaultValue = "false", - optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED + name = "internal_skylark_flag_test_canary", + defaultValue = "false", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED ) public boolean skylarkFlagTestCanary; @@ -47,6 +51,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_disallow_set_constructor", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, disables the deprecated `set` constructor for depsets." ) public boolean incompatibleDisallowSetConstructor; @@ -55,6 +61,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_disallow_keyword_only_args", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, disables the keyword-only argument syntax in function definition." ) public boolean incompatibleDisallowKeywordOnlyArgs; @@ -63,6 +71,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_list_plus_equals_inplace", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, `+=` on lists works like the `extend` method mutating the original " + "list. Otherwise it copies the original list without mutating it." @@ -73,6 +83,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_disallow_dict_plus", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, the `+` becomes disabled for dicts." ) public boolean incompatibleDisallowDictPlus; @@ -81,6 +93,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_bzl_disallow_load_after_statement", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, all `load` must be called at the top of .bzl files, before any other " + "statement." @@ -91,6 +105,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_load_argument_is_label", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, the first argument of 'load' statements is a label (not a path). " + "It must start with '//' or ':'." @@ -101,6 +117,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_disallow_toplevel_if_statement", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, 'if' statements are forbidden at the top-level " + "(outside a function definition)" @@ -111,6 +129,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_comprehension_variables_do_not_leak", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, loop variables in a comprehension shadow any existing variable by " + "the same name. If the existing variable was declared in the same scope that " @@ -123,6 +143,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_depset_is_not_iterable", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, depset type is not iterable. For loops and functions expecting an " + "iterable will reject depset objects. Use the `.to_list` method to explicitly " @@ -134,6 +156,8 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable name = "incompatible_dict_literal_has_no_duplicates", defaultValue = "false", category = "incompatible changes", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If set to true, the dictionary literal syntax doesn't allow duplicated keys." ) public boolean incompatibleDictLiteralHasNoDuplicates; diff --git a/src/main/java/com/google/devtools/build/lib/worker/BUILD b/src/main/java/com/google/devtools/build/lib/worker/BUILD index ef7427542e..0500c8e372 100644 --- a/src/main/java/com/google/devtools/build/lib/worker/BUILD +++ b/src/main/java/com/google/devtools/build/lib/worker/BUILD @@ -18,6 +18,7 @@ java_library( "//src/main/java/com/google/devtools/build/lib/sandbox", "//src/main/java/com/google/devtools/build/lib/standalone", "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:test_status_java_proto", "//src/main/protobuf:worker_protocol_java_proto", "//third_party:apache_commons_pool2", diff --git a/src/main/java/com/google/devtools/build/lib/worker/WorkerOptions.java b/src/main/java/com/google/devtools/build/lib/worker/WorkerOptions.java index f4d3337827..340e28bd7e 100644 --- a/src/main/java/com/google/devtools/build/lib/worker/WorkerOptions.java +++ b/src/main/java/com/google/devtools/build/lib/worker/WorkerOptions.java @@ -15,8 +15,10 @@ package com.google.devtools.build.lib.worker; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Option; +import com.google.devtools.common.options.OptionDocumentationCategory; import com.google.devtools.common.options.Options; import com.google.devtools.common.options.OptionsBase; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; import java.util.List; import java.util.Map.Entry; @@ -30,6 +32,8 @@ public class WorkerOptions extends OptionsBase { name = "experimental_persistent_javac", defaultValue = "null", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "Enable the experimental persistent Java compiler.", expansion = { "--strategy=Javac=worker", @@ -45,6 +49,8 @@ public class WorkerOptions extends OptionsBase { name = "worker_max_instances", defaultValue = "4", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "How many instances of a worker process (like the persistent Java compiler) may be " + "launched if you use the 'worker' strategy." @@ -55,6 +61,8 @@ public class WorkerOptions extends OptionsBase { name = "worker_quit_after_build", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, all workers quit after a build is done." ) public boolean workerQuitAfterBuild; @@ -63,19 +71,23 @@ public class WorkerOptions extends OptionsBase { name = "worker_verbose", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, prints verbose messages when workers are started, shutdown, ..." ) public boolean workerVerbose; @Option( - name = "worker_extra_flag", - converter = Converters.AssignmentConverter.class, - defaultValue = "", - category = "strategy", - help = - "Extra command-flags that will be passed to worker processes in addition to " - + "--persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug.", - allowMultiple = true + name = "worker_extra_flag", + converter = Converters.AssignmentConverter.class, + defaultValue = "", + category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, + help = + "Extra command-flags that will be passed to worker processes in addition to " + + "--persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug.", + allowMultiple = true ) public List<Entry<String, String>> workerExtraFlags; @@ -83,6 +95,8 @@ public class WorkerOptions extends OptionsBase { name = "worker_sandboxing", defaultValue = "false", category = "strategy", + documentationCategory = OptionDocumentationCategory.UNCATEGORIZED, + effectTags = {OptionEffectTag.UNKNOWN}, help = "If enabled, workers will be executed in a sandboxed environment." ) public boolean workerSandboxing; |