diff options
Diffstat (limited to 'src/main/java/com/google')
7 files changed, 261 insertions, 9 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD index ca9f117d3e..c0c72c71ca 100644 --- a/src/main/java/com/google/devtools/build/lib/BUILD +++ b/src/main/java/com/google/devtools/build/lib/BUILD @@ -630,6 +630,7 @@ java_library( "//src/main/java/com/google/devtools/common/options", "//src/main/protobuf:extra_actions_base_java_proto", "//src/main/protobuf:invocation_policy_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:test_status_java_proto", "//third_party:auto_value", "//third_party:guava", @@ -1180,6 +1181,7 @@ java_library( "//src/main/protobuf:command_server_java_grpc", "//src/main/protobuf:command_server_java_proto", "//src/main/protobuf:invocation_policy_java_proto", + "//src/main/protobuf:option_filters_java_proto", "//src/main/protobuf:test_status_java_proto", "//third_party:guava", "//third_party:joda_time", 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 41ef44291c..ed9c1f6e9a 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 @@ -37,11 +37,14 @@ import com.google.devtools.build.lib.vfs.PathFragment; import com.google.devtools.common.options.Converters; import com.google.devtools.common.options.Converters.RangeConverter; 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.OptionsClassProvider; 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 com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag; import java.util.ArrayList; import java.util.List; import java.util.UUID; @@ -73,6 +76,8 @@ public class BuildRequest implements OptionsClassProvider { abbrev = 'j', defaultValue = "auto", category = "strategy", + documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, + effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION}, converter = JobsConverter.class, help = "The number of concurrent jobs to run. 0 means build sequentially." @@ -89,6 +94,8 @@ public class BuildRequest implements OptionsClassProvider { name = "progress_report_interval", defaultValue = "0", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, converter = ProgressReportIntervalConverter.class, help = "The number of seconds to wait between two reports on still running jobs. The " @@ -100,6 +107,8 @@ public class BuildRequest implements OptionsClassProvider { name = "explain", defaultValue = "null", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, converter = OptionsUtils.PathFragmentConverter.class, help = "Causes the build system to explain each executed step of the " @@ -111,6 +120,8 @@ public class BuildRequest implements OptionsClassProvider { name = "verbose_explanations", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Increases the verbosity of the explanations issued if --explain is enabled. " + "Has no effect if --explain is not enabled." @@ -122,6 +133,8 @@ public class BuildRequest implements OptionsClassProvider { converter = Converters.RegexPatternConverter.class, defaultValue = "null", category = "flags", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Only shows warnings for rules with a name matching the provided regular expression." ) public Pattern outputFilter; @@ -130,6 +143,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_makefile", defaultValue = "false", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "this flag has no effect." ) @@ -139,6 +154,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_action_graph", defaultValue = "false", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "this flag has no effect." ) @@ -149,6 +166,8 @@ public class BuildRequest implements OptionsClassProvider { name = "dump_action_graph_for_package", allowMultiple = true, defaultValue = "", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "this flag has no effect." ) @@ -158,6 +177,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_action_graph_with_middlemen", defaultValue = "true", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "this flag has no effect." ) @@ -167,6 +188,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_providers", defaultValue = "false", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "This is a no-op." ) @@ -176,6 +199,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_targets", defaultValue = "null", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "this flag has no effect." ) @@ -185,6 +210,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_host_deps", defaultValue = "true", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Deprecated" ) @@ -194,6 +221,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "dump_to_stdout", defaultValue = "false", + effectTags = {OptionEffectTag.NO_OP}, + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Deprecated" ) @@ -202,6 +231,11 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "analyze", defaultValue = "true", + effectTags = { + OptionEffectTag.LOADING_AND_ANALYSIS, + OptionEffectTag.EAGERNESS_TO_EXIT, + OptionEffectTag.AFFECTS_OUTPUTS + }, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Execute the analysis phase; this is the usual behaviour. Specifying --noanalyze causes " @@ -214,6 +248,12 @@ public class BuildRequest implements OptionsClassProvider { name = "build", defaultValue = "true", category = "what", + documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, + effectTags = { + OptionEffectTag.EXECUTION, + OptionEffectTag.EAGERNESS_TO_EXIT, + OptionEffectTag.AFFECTS_OUTPUTS + }, help = "Execute the build; this is the usual behaviour. " + "Specifying --nobuild causes the build to stop before executing the build " @@ -226,6 +266,8 @@ public class BuildRequest implements OptionsClassProvider { name = "output_groups", converter = Converters.CommaSeparatedOptionListConverter.class, allowMultiple = true, + documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, + effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, defaultValue = "", help = "Specifies which output groups of the top-level targets to build. If omitted, a default " @@ -239,6 +281,8 @@ public class BuildRequest implements OptionsClassProvider { name = "show_result", defaultValue = "1", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Show the results of the build. For each target, state whether or not it was brought " + "up-to-date, and if so, a list of output files that were built. The printed files " @@ -253,6 +297,8 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "experimental_show_artifacts", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Output a list of all top level artifacts produced by this build." @@ -266,6 +312,8 @@ public class BuildRequest implements OptionsClassProvider { name = "announce", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Deprecated. No-op.", deprecationWarning = "This option is now deprecated and is a no-op" ) @@ -275,6 +323,8 @@ public class BuildRequest implements OptionsClassProvider { name = "symlink_prefix", defaultValue = "null", category = "misc", + documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "The prefix that is prepended to any of the convenience symlinks that are created " + "after a build. If '/' is passed, then no symlinks are created and no warning is " @@ -288,6 +338,9 @@ public class BuildRequest implements OptionsClassProvider { allowMultiple = true, defaultValue = "", category = "semantics", + documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, + metadataTags = {OptionMetadataTag.EXPERIMENTAL}, help = "This flag allows specifying multiple target CPUs. If this is specified, " + "the --cpu option is ignored." @@ -298,6 +351,7 @@ public class BuildRequest implements OptionsClassProvider { name = "output_tree_tracking", oldName = "experimental_output_tree_tracking", defaultValue = "true", + effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "If set, tell the output service (if any) to track when files in the output " @@ -311,6 +365,7 @@ public class BuildRequest implements OptionsClassProvider { name = "aspects", converter = Converters.CommaSeparatedOptionListConverter.class, defaultValue = "", + documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, allowMultiple = true, help = "Comma-separated list of aspects to be applied to top-level targets. All aspects " @@ -318,7 +373,6 @@ public class BuildRequest implements OptionsClassProvider { + "the form <bzl-file-label>%<aspect_name>, " + "for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level " + "value from from a file tools/my_def.bzl" - ) public List<String> aspects; @@ -329,6 +383,11 @@ public class BuildRequest implements OptionsClassProvider { @Option( name = "use_action_cache", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, + effectTags = { + OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION, + OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS + }, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Whether to use the action cache" ) 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 02933499d4..8e242f012d 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 @@ -18,8 +18,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.proto.OptionFilters.OptionEffectTag; +import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag; import java.util.Map; /** @@ -78,6 +81,8 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "install_base", defaultValue = "", // NOTE: purely decorative! See class docstring. + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.CHANGES_INPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, converter = OptionsUtils.PathFragmentConverter.class, help = "This launcher option is intended for use only by tests." @@ -91,6 +96,11 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "install_md5", defaultValue = "", // NOTE: purely decorative! See class docstring. + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = { + OptionEffectTag.LOSES_INCREMENTAL_STATE, + OptionEffectTag.BAZEL_MONITORING + }, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "This launcher option is intended for use only by tests." ) @@ -105,6 +115,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "output_base", defaultValue = "null", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE}, converter = OptionsUtils.PathFragmentConverter.class, valueHelp = "<path>", help = @@ -128,6 +140,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "output_user_root", defaultValue = "null", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE}, converter = OptionsUtils.PathFragmentConverter.class, valueHelp = "<path>", help = @@ -140,6 +154,8 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "workspace_directory", defaultValue = "", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.CHANGES_INPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, converter = OptionsUtils.PathFragmentConverter.class, help = @@ -152,6 +168,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "max_idle_secs", defaultValue = "" + (3 * 3600), // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT, OptionEffectTag.LOSES_INCREMENTAL_STATE}, valueHelp = "<integer>", help = "The number of seconds the build server will wait idling before shutting down. Zero " @@ -163,6 +181,11 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "batch", defaultValue = "false", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = { + OptionEffectTag.LOSES_INCREMENTAL_STATE, + OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION + }, help = "If set, Blaze will be run as just a client process without a server, instead of in " + "the standard client/server mode." @@ -173,6 +196,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "deep_execroot", defaultValue = "true", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EXECUTION}, help = "If set, the execution root will be under $OUTPUT_BASE/execroot instead of " + "$OUTPUT_BASE." @@ -183,6 +208,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "experimental_oom_more_eagerly", defaultValue = "false", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EAGERNESS_TO_EXIT}, help = "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only " + "honored when --batch is also passed. In some cases, builds that previously " @@ -194,6 +221,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "experimental_oom_more_eagerly_threshold", defaultValue = "100", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EAGERNESS_TO_EXIT}, help = "If this flag is set, Blaze will OOM if, after two full GC's, more than this " + "percentage of the (old gen) heap is still occupied." @@ -204,6 +233,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "block_for_lock", defaultValue = "true", // NOTE: purely decorative! See class docstring. category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT}, help = "When --noblock_for_lock is passed, Blaze does not wait for a running command to " + "complete, but instead exits immediately." @@ -214,6 +245,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "io_nice_level", defaultValue = "-1", // NOTE: purely decorative! category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS}, valueHelp = "{-1,0,1,2,3,4,5,6,7}", help = "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the " @@ -227,6 +260,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "batch_cpu_scheduling", defaultValue = "false", // NOTE: purely decorative! category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS}, help = "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for " + "workloads that are non-interactive, but do not want to lower their nice value. " @@ -238,6 +273,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "blazerc", defaultValue = "null", // NOTE: purely decorative! category = "misc", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, valueHelp = "<path>", help = "The location of the .%{product}rc file containing default values of " @@ -252,6 +289,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "master_blazerc", defaultValue = "true", // NOTE: purely decorative! category = "misc", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, help = "If this option is false, the master %{product}rc next to the binary is not read." ) public boolean masterBlazerc; @@ -260,6 +299,7 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "fatal_event_bus_exceptions", defaultValue = "false", // NOTE: purely decorative! 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." ) public boolean fatalEventBusExceptions; @@ -268,6 +308,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "option_sources", converter = OptionSourcesConverter.class, defaultValue = "", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "" ) @@ -279,6 +321,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "watchfs", defaultValue = "false", category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + metadataTags = OptionMetadataTag.DEPRECATED, 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." @@ -288,6 +332,8 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "invocation_policy", defaultValue = "", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "A base64-encoded-binary-serialized or text-formated " @@ -299,6 +345,11 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "command_port", defaultValue = "0", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = { + OptionEffectTag.LOSES_INCREMENTAL_STATE, + OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION + }, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Port to start up the gRPC command server on. If 0, let the kernel choose." ) @@ -307,6 +358,12 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "product_name", defaultValue = "bazel", // NOTE: purely decorative! + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = { + OptionEffectTag.LOSES_INCREMENTAL_STATE, + OptionEffectTag.AFFECTS_OUTPUTS, + OptionEffectTag.BAZEL_MONITORING + }, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The name of the build system. It is used as part of the name of the generated " @@ -319,6 +376,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "exoblaze", defaultValue = "false", category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE}, help = "If true, Blaze runs as Exoblaze" ) public boolean exoblaze; @@ -327,6 +386,8 @@ public class BlazeServerStartupOptions extends OptionsBase { @Option( name = "write_command_log", defaultValue = "true", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Whether or not to write the command.log file" ) @@ -336,6 +397,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "client_debug", defaultValue = "false", // NOTE: purely decorative! category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, help = "If true, log debug information from the client to stderr" ) public boolean clientDebug; @@ -344,6 +407,8 @@ public class BlazeServerStartupOptions extends OptionsBase { name = "connect_timeout_secs", defaultValue = "10", category = "server startup", + documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, + effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, help = "The amount of time the client waits for each attempt to connect to the server" ) public int connectTimeoutSecs; diff --git a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java index 97bec45979..bb784a8b06 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 @@ -18,9 +18,12 @@ import com.google.devtools.build.lib.vfs.PathFragment; 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 com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag; import java.util.List; import java.util.Map; import java.util.logging.Level; @@ -97,12 +100,13 @@ public class CommonCommandOptions extends OptionsBase { } } - // To create a new incompatible change, see the javadoc for AllIncompatibleChangesExpansion. @Option( name = "all_incompatible_changes", defaultValue = "null", category = "misc", + effectTags = {OptionEffectTag.UNKNOWN}, + metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE}, expansionFunction = AllIncompatibleChangesExpansion.class, help = "Enables all options of the form --incompatible_*. Use this option to find places where " @@ -114,6 +118,7 @@ public class CommonCommandOptions extends OptionsBase { name = "config", defaultValue = "", category = "misc", + effectTags = {OptionEffectTag.UNKNOWN}, allowMultiple = true, help = "Selects additional config sections from the rc files; for every <command>, it " @@ -129,6 +134,8 @@ public class CommonCommandOptions extends OptionsBase { name = "logging", defaultValue = "3", // Level.INFO category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, converter = Converters.LogLevelConverter.class, help = "The logging level." ) @@ -138,16 +145,19 @@ public class CommonCommandOptions extends OptionsBase { name = "client_env", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, converter = Converters.AssignmentConverter.class, allowMultiple = true, help = "A system-generated parameter which specifies the client's environment" ) public List<Map.Entry<String, String>> clientEnv; + @Deprecated @Option( name = "ignore_client_env", defaultValue = "false", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + metadataTags = OptionMetadataTag.DEPRECATED, deprecationWarning = "Deprecated, no-op.", help = "Deprecated, no-op." ) @@ -159,6 +169,7 @@ public class CommonCommandOptions extends OptionsBase { name = "client_cwd", defaultValue = "", optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, converter = OptionsUtils.PathFragmentConverter.class, help = "A system-generated parameter which specifies the client's working directory" ) @@ -168,6 +179,8 @@ public class CommonCommandOptions extends OptionsBase { name = "announce_rc", defaultValue = "false", category = "verbosity", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Whether to announce rc options." ) public boolean announceRcOptions; @@ -181,6 +194,7 @@ public class CommonCommandOptions extends OptionsBase { name = "default_override", defaultValue = "", allowMultiple = true, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, converter = OptionOverrideConverter.class, help = "" @@ -192,6 +206,7 @@ public class CommonCommandOptions extends OptionsBase { name = "rc_source", defaultValue = "", allowMultiple = true, + effectTags = {OptionEffectTag.CHANGES_INPUTS}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "" ) @@ -200,6 +215,7 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "always_profile_slow_operations", defaultValue = "true", + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Whether profiling slow operations is always turned on" ) @@ -209,6 +225,7 @@ public class CommonCommandOptions extends OptionsBase { name = "allow_undefined_configs", defaultValue = "true", category = "flags", + effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT}, help = "Do not throw an error when the config is not defined." ) public boolean allowUndefinedConfigs; @@ -217,6 +234,8 @@ public class CommonCommandOptions extends OptionsBase { name = "profile", defaultValue = "null", category = "misc", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, converter = OptionsUtils.PathFragmentConverter.class, help = "If set, profile Blaze and write data to the specified " @@ -227,6 +246,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "record_full_profiler_data", defaultValue = "false", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "By default, Blaze profiler will record only aggregated data for fast but numerous " @@ -239,15 +260,19 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "memory_profile", defaultValue = "null", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, converter = OptionsUtils.PathFragmentConverter.class, - help = "If set, write memory usage data to the specified " + "file at phase ends." + help = "If set, write memory usage data to the specified file at phase ends." ) public PathFragment memoryProfilePath; + @Deprecated @Option( name = "gc_watchdog", defaultValue = "false", + metadataTags = {OptionMetadataTag.DEPRECATED}, optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, deprecationWarning = "Ignoring: this option is no longer supported", help = "Deprecated." @@ -257,6 +282,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "startup_time", defaultValue = "0", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The time in ms the launcher spends before sending the request to the blaze server." ) @@ -265,6 +292,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "extract_data_time", defaultValue = "0", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The time in ms spent on extracting the new blaze version." ) @@ -273,6 +302,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "command_wait_time", defaultValue = "0", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The time in ms a command had to wait on a busy Blaze server process." ) @@ -282,6 +313,8 @@ public class CommonCommandOptions extends OptionsBase { name = "tool_tag", defaultValue = "", category = "misc", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, help = "A tool name to attribute this Blaze invocation to." ) public String toolTag; @@ -289,6 +322,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "restart_reason", defaultValue = "no_restart", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The reason for the server restart." ) @@ -297,6 +332,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "binary_path", defaultValue = "", + documentationCategory = OptionDocumentationCategory.LOGGING, + effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "The absolute path of the blaze binary." ) @@ -305,6 +342,8 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "experimental_allow_project_files", defaultValue = "false", + effectTags = {OptionEffectTag.CHANGES_INPUTS}, + metadataTags = {OptionMetadataTag.EXPERIMENTAL}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "Enable processing of +<file> parameters." ) @@ -313,11 +352,11 @@ public class CommonCommandOptions extends OptionsBase { @Option( name = "block_for_lock", defaultValue = "true", + effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, optionUsageRestrictions = OptionUsageRestrictions.HIDDEN, help = "If set (the default), a command will block if there is another one running. If " + "unset, these commands will immediately return with an error." ) public boolean blockForLock; - } diff --git a/src/main/java/com/google/devtools/common/options/BUILD b/src/main/java/com/google/devtools/common/options/BUILD index 45cdf205b0..ccea13d237 100644 --- a/src/main/java/com/google/devtools/common/options/BUILD +++ b/src/main/java/com/google/devtools/common/options/BUILD @@ -8,6 +8,7 @@ java_library( srcs = glob(["*.java"]), deps = [ "//src/main/protobuf:invocation_policy_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/common/options/Option.java b/src/main/java/com/google/devtools/common/options/Option.java index e040046624..7489bd668d 100644 --- a/src/main/java/com/google/devtools/common/options/Option.java +++ b/src/main/java/com/google/devtools/common/options/Option.java @@ -14,6 +14,8 @@ package com.google.devtools.common.options; import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; +import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag; +import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; @@ -72,11 +74,21 @@ public @interface Option { String defaultValue(); /** - * A string describing the role of the option. Some existing categories are "input," "output," - * "config," "semantics," and "strategy," among others. + * This category field is deprecated. Bazel is in the process of migrating all options to use the + * better defined enums in OptionDocumentationCategory and the tags in the option_filters.proto + * file. It will still be used for the usage documentation until a sufficient proportion of + * options are using the new system. * - * <p>The category of options that this belongs to dictates how options are grouped by {@link - * OptionsParser#describeOptions}, for the usage documentation. + * <p>Please leave the old category field in existing options to minimize disruption to the Help + * output during the transition period. All uses of this field will be removed when transition is + * complete. This category field has no effect on the other fields below, having both set is not a + * problem. + */ + @Deprecated + String category() default "misc"; + + /** + * Grouping categories used for usage documentation. See the enum's definition for details. * * <p>For undocumented flags that aren't listed anywhere, this is currently a no-op. Feel free to * set the value that it would have if it were documented, which might be helpful if a flag is @@ -86,7 +98,27 @@ public @interface Option { * <p>For hidden or internal options, use the category field only if it is helpful for yourself or * other Bazel developers. */ - String category() default "misc"; + OptionDocumentationCategory documentationCategory() default + OptionDocumentationCategory.UNCATEGORIZED; + + /** + * Tag about the intent or effect of this option. Unless this option is a no-op (and the reason + * for this should be documented) all options should have some effect, so this needs to have at + * least one value. + * + * <p>No option should list NO_OP_OR_UNKNOWN with other effects listed, but all other combinations + * are allowed. + */ + OptionEffectTag[] effectTags() default {OptionEffectTag.UNKNOWN}; + + /** + * Tag about the state of this option, such as if it gates an experimental feature, or is + * deprecated. + * + * <p>If one or more of the OptionMetadataTag values apply, please include, but otherwise, this + * list can be left blank. + */ + OptionMetadataTag[] metadataTags() default {}; /** * Options have multiple uses, some flags, some not. For user-visible flags, they are diff --git a/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java b/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java new file mode 100644 index 0000000000..eb39871ca6 --- /dev/null +++ b/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java @@ -0,0 +1,54 @@ +// Copyright 2017 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +package com.google.devtools.common.options; + +/** + * These categories are used to logically group options in generated documentation, both the command + * line output for the standard HelpCommand and the html output used for command-line-reference on + * the website. + * + * <p>Grouping things is only a useful exercise if the group includes multiple units. Please only + * add categories that group a useful subset of options. (>2, <200, let's say) + */ +public enum OptionDocumentationCategory { + /** + * A category to aid transition, to make it obvious that an option needs to be categorized. Note: + * Do NOT add this to new flags! + */ + UNCATEGORIZED, + + /** + * Startup options appear before the command and are parsed by the client. Changing them may cause + * a server restart, see OptionEffectTag.LOSES_INCREMENTAL_STATE. + */ + BAZEL_CLIENT_OPTIONS, + + /** This option's primary purpose is to affect the verbosity, format or location of logging. */ + LOGGING, + + /** This option deals with how to go about executing the build. */ + EXECUTION_STRATEGY, + + /** + * This option lets a user specify WHICH output they wish the command to have. It might be a + * selective filter on the outputs, or a blanket on/off switch. + */ + OUTPUT_SELECTION, + + /** + * This option lets a user configure the outputs. Unlike OUTPUT_SELECTION, which specifies whether + * or not an output is built, this specifies qualities of the output. + */ + OUTPUT_PARAMETERS, +} |