diff options
| author |  ccalvarin <ccalvarin@google.com> | 2017-06-27 17:58:35 +0200 |
|---|---|---|
| committer |  Marcel Hlopko <hlopko@google.com> | 2017-06-28 10:17:40 +0200 |
| commit | 3bc1547a5cd78bd6639d968b3cfddbe26b1c31d5 (patch) | |
| tree | ad80da2596d9150632ca6a1f1510060fe849fa3a | |
| parent | 9b394a24dc65c794242e98a8a41eb8a60c78367b (diff) | |
Add the default category and tag to all options.
Move the default from the annotation to every mention. This makes the incompleteness explicit. Will add the defaults to test targets in a separate change.
Once all dependencies are cleaned up, the Option annotation will no longer allow options without the documentationCategory or effectTag, to prevent new options being added without categories while we migrate to the new option categorization.
PiperOrigin-RevId: 160281252
65 files changed, 1486 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; diff --git a/src/test/java/com/google/devtools/build/lib/BUILD b/src/test/java/com/google/devtools/build/lib/BUILD index 47bb2421d1..55282d337e 100644 --- a/src/test/java/com/google/devtools/build/lib/BUILD +++ b/src/test/java/com/google/devtools/build/lib/BUILD @@ -1262,6 +1262,7 @@ java_library( ], deps = [ "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:worker_protocol_java_proto", "//third_party:guava", ], diff --git a/src/tools/android/java/com/google/devtools/build/android/BUILD b/src/tools/android/java/com/google/devtools/build/android/BUILD index 209f8c05a8..d3bc605e3e 100644 --- a/src/tools/android/java/com/google/devtools/build/android/BUILD +++ b/src/tools/android/java/com/google/devtools/build/android/BUILD @@ -36,6 +36,7 @@ java_library( ]), deps = [ "//src/main/java/com/google/devtools/common/options", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:package_manifest_java_proto", "//src/tools/android/java/com/google/devtools/build/android/proto:serialize_format_java_pb", "//src/tools/android/java/com/google/devtools/build/android/resources", |