Split out option usage restriction from option category.
These are two different concepts. Do not remove category overload compatibility in this CL, to keep this change limited to converting the current uses of category.
With some flyby formatting fixes on affected OptionsBases.
RELNOTES: None.
PiperOrigin-RevId: 153390002
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 b67ecee..4906aec 100644
--- a/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java
@@ -18,6 +18,7 @@
import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter;
import com.google.devtools.common.options.Option;
import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
import java.util.List;
import java.util.Set;
@@ -25,92 +26,107 @@
* Options that affect how command-line target patterns are resolved to individual targets.
*/
public class LoadingOptions extends OptionsBase {
- @Option(name = "build_tests_only",
- defaultValue = "false",
- category = "what",
- help = "If specified, only *_test and test_suite rules will be built "
- + "and other targets specified on the command line will be ignored. "
- + "By default everything that was requested will be built.")
+ @Option(
+ name = "build_tests_only",
+ defaultValue = "false",
+ category = "what",
+ help =
+ "If specified, only *_test and test_suite rules will be built and other targets specified "
+ + "on the command line will be ignored. By default everything that was requested "
+ + "will be built."
+ )
public boolean buildTestsOnly;
- @Option(name = "compile_one_dependency",
- defaultValue = "false",
- category = "what",
- help = "Compile a single dependency of the argument files. "
- + "This is useful for syntax checking source files in IDEs, "
- + "for example, by rebuilding a single target that depends on "
- + "the source file to detect errors as early as possible in the "
- + "edit/build/test cycle. This argument affects the way all "
- + "non-flag arguments are interpreted; instead of being targets "
- + "to build they are source filenames. For each source filename "
- + "an arbitrary target that depends on it will be built.")
+ @Option(
+ name = "compile_one_dependency",
+ defaultValue = "false",
+ category = "what",
+ help =
+ "Compile a single dependency of the argument files. This is useful for syntax checking "
+ + "source files in IDEs, for example, by rebuilding a single target that depends on "
+ + "the source file to detect errors as early as possible in the edit/build/test cycle. "
+ + "This argument affects the way all non-flag arguments are interpreted; instead of "
+ + "being targets to build they are source filenames. For each source filename "
+ + "an arbitrary target that depends on it will be built."
+ )
public boolean compileOneDependency;
- @Option(name = "build_tag_filters",
- converter = CommaSeparatedOptionListConverter.class,
- defaultValue = "",
- category = "what",
- help = "Specifies a comma-separated list of tags. Each tag can be optionally "
- + "preceded with '-' to specify excluded tags. Only those targets will be built that "
- + "contain at least one included tag and do not contain any excluded tags. This option "
- + "does not affect the set of tests executed with the 'test' command; those are be "
- + "governed by the test filtering options, for example '--test_tag_filters'"
- )
+ @Option(
+ name = "build_tag_filters",
+ converter = CommaSeparatedOptionListConverter.class,
+ defaultValue = "",
+ category = "what",
+ help =
+ "Specifies a comma-separated list of tags. Each tag can be optionally "
+ + "preceded with '-' to specify excluded tags. Only those targets will be built that "
+ + "contain at least one included tag and do not contain any excluded tags. This option "
+ + "does not affect the set of tests executed with the 'test' command; those are be "
+ + "governed by the test filtering options, for example '--test_tag_filters'"
+ )
public List<String> buildTagFilterList;
- @Option(name = "test_tag_filters",
- converter = CommaSeparatedOptionListConverter.class,
- defaultValue = "",
- category = "what",
- help = "Specifies a comma-separated list of test tags. Each tag can be optionally " +
- "preceded with '-' to specify excluded tags. Only those test targets will be " +
- "found that contain at least one included tag and do not contain any excluded " +
- "tags. This option affects --build_tests_only behavior and the test command."
- )
+ @Option(
+ name = "test_tag_filters",
+ converter = CommaSeparatedOptionListConverter.class,
+ defaultValue = "",
+ category = "what",
+ help =
+ "Specifies a comma-separated list of test tags. Each tag can be optionally "
+ + "preceded with '-' to specify excluded tags. Only those test targets will be "
+ + "found that contain at least one included tag and do not contain any excluded "
+ + "tags. This option affects --build_tests_only behavior and the test command."
+ )
public List<String> testTagFilterList;
- @Option(name = "test_size_filters",
- converter = TestSize.TestSizeFilterConverter.class,
- defaultValue = "",
- category = "what",
- help = "Specifies a comma-separated list of test sizes. Each size can be optionally " +
- "preceded with '-' to specify excluded sizes. Only those test targets will be " +
- "found that contain at least one included size and do not contain any excluded " +
- "sizes. This option affects --build_tests_only behavior and the test command."
- )
+ @Option(
+ name = "test_size_filters",
+ converter = TestSize.TestSizeFilterConverter.class,
+ defaultValue = "",
+ category = "what",
+ help =
+ "Specifies a comma-separated list of test sizes. Each size can be optionally "
+ + "preceded with '-' to specify excluded sizes. Only those test targets will be "
+ + "found that contain at least one included size and do not contain any excluded "
+ + "sizes. This option affects --build_tests_only behavior and the test command."
+ )
public Set<TestSize> testSizeFilterSet;
- @Option(name = "test_timeout_filters",
- converter = TestTimeout.TestTimeoutFilterConverter.class,
- defaultValue = "",
- category = "what",
- help = "Specifies a comma-separated list of test timeouts. Each timeout can be " +
- "optionally preceded with '-' to specify excluded timeouts. Only those test " +
- "targets will be found that contain at least one included timeout and do not " +
- "contain any excluded timeouts. This option affects --build_tests_only behavior " +
- "and the test command."
- )
+ @Option(
+ name = "test_timeout_filters",
+ converter = TestTimeout.TestTimeoutFilterConverter.class,
+ defaultValue = "",
+ category = "what",
+ help =
+ "Specifies a comma-separated list of test timeouts. Each timeout can be "
+ + "optionally preceded with '-' to specify excluded timeouts. Only those test "
+ + "targets will be found that contain at least one included timeout and do not "
+ + "contain any excluded timeouts. This option affects --build_tests_only behavior "
+ + "and the test command."
+ )
public Set<TestTimeout> testTimeoutFilterSet;
- @Option(name = "test_lang_filters",
- converter = CommaSeparatedOptionListConverter.class,
- defaultValue = "",
- category = "what",
- help = "Specifies a comma-separated list of test languages. Each language can be " +
- "optionally preceded with '-' to specify excluded languages. Only those " +
- "test targets will be found that are written in the specified languages. " +
- "The name used for each language should be the same as the language prefix in the " +
- "*_test rule, e.g. one of 'cc', 'java', 'py', etc." +
- "This option affects --build_tests_only behavior and the test command."
- )
+ @Option(
+ name = "test_lang_filters",
+ converter = CommaSeparatedOptionListConverter.class,
+ defaultValue = "",
+ category = "what",
+ help =
+ "Specifies a comma-separated list of test languages. Each language can be "
+ + "optionally preceded with '-' to specify excluded languages. Only those "
+ + "test targets will be found that are written in the specified languages. "
+ + "The name used for each language should be the same as the language prefix in the "
+ + "*_test rule, e.g. one of 'cc', 'java', 'py', etc."
+ + "This option affects --build_tests_only behavior and the test command."
+ )
public List<String> testLangFilterList;
- @Option(name = "build_manual_tests",
- defaultValue = "false",
- category = "what",
- help = "Forces test targets tagged 'manual' to be built. "
- + "'manual' tests are excluded from processing. This option forces "
- + "them to be built (but not executed)."
+ @Option(
+ name = "build_manual_tests",
+ defaultValue = "false",
+ category = "what",
+ help =
+ "Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from "
+ + "processing. This option forces them to be built (but not executed)."
)
public boolean buildManualTests;
@@ -119,10 +135,13 @@
// the loading phase at all, and therefore can't currently support the other flag. If we roll this
// out soonish, then we're never going to implement the legacy code path in the new
// implementation, making it a moot point.
- @Option(name = "experimental_skyframe_target_pattern_evaluator",
- defaultValue = "false",
- category = "hidden",
- help = "Use the Skyframe-based target pattern evaluator; implies "
- + "--experimental_interleave_loading_and_analysis.")
+ @Option(
+ name = "experimental_skyframe_target_pattern_evaluator",
+ defaultValue = "false",
+ optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+ help =
+ "Use the Skyframe-based target pattern evaluator; implies "
+ + "--experimental_interleave_loading_and_analysis."
+ )
public boolean useSkyframeTargetPatternEvaluator;
}
diff --git a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
index 8237e84..626d76f 100644
--- a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
@@ -26,6 +26,7 @@
import com.google.devtools.common.options.Converters;
import com.google.devtools.common.options.Option;
import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
import com.google.devtools.common.options.OptionsParsingException;
import java.util.List;
@@ -56,64 +57,78 @@
}
}
- @Option(name = "package_path",
- defaultValue = "%workspace%",
- category = "package loading",
- converter = Converters.ColonSeparatedOptionListConverter.class,
- help = "A colon-separated list of where to look for packages. "
- + "Elements beginning with '%workspace%' are relative to the enclosing "
- + "workspace. If omitted or empty, the default is the output of "
- + "'blaze info default-package-path'.")
+ @Option(
+ name = "package_path",
+ defaultValue = "%workspace%",
+ category = "package loading",
+ converter = Converters.ColonSeparatedOptionListConverter.class,
+ help =
+ "A colon-separated list of where to look for packages. "
+ + "Elements beginning with '%workspace%' are relative to the enclosing "
+ + "workspace. If omitted or empty, the default is the output of "
+ + "'blaze info default-package-path'."
+ )
public List<String> packagePath;
- @Option(name = "show_package_location",
- defaultValue = "false",
- category = "verbosity",
- deprecationWarning = "This flag is no longer supported and will go away soon.",
- help = "If enabled, causes Blaze to print the location on the --package_path "
- + "from which each package was loaded.")
+ @Option(
+ name = "show_package_location",
+ defaultValue = "false",
+ category = "verbosity",
+ deprecationWarning = "This flag is no longer supported and will go away soon.",
+ help =
+ "If enabled, causes Blaze to print the location on the --package_path "
+ + "from which each package was loaded."
+ )
public boolean showPackageLocation;
- @Option(name = "show_loading_progress",
- defaultValue = "true",
- category = "verbosity",
- help = "If enabled, causes Blaze to print \"Loading package:\" messages.")
+ @Option(
+ name = "show_loading_progress",
+ defaultValue = "true",
+ category = "verbosity",
+ help = "If enabled, causes Blaze to print \"Loading package:\" messages."
+ )
public boolean showLoadingProgress;
- @Option(name = "deleted_packages",
- defaultValue = "",
- category = "package loading",
- converter = CommaSeparatedPackageNameListConverter.class,
- help = "A comma-separated list of names of packages which the "
- + "build system will consider non-existent, even if they are "
- + "visible somewhere on the package path."
- + "\n"
- + "Use this option when deleting a subpackage 'x/y' of an "
- + "existing package 'x'. For example, after deleting x/y/BUILD "
- + "in your client, the build system may complain if it "
- + "encounters a label '//x:y/z' if that is still provided by another "
- + "package_path entry. Specifying --deleted_packages x/y avoids this "
- + "problem.")
+ @Option(
+ name = "deleted_packages",
+ defaultValue = "",
+ category = "package loading",
+ converter = CommaSeparatedPackageNameListConverter.class,
+ help =
+ "A comma-separated list of names of packages which the "
+ + "build system will consider non-existent, even if they are "
+ + "visible somewhere on the package path.\n"
+ + "Use this option when deleting a subpackage 'x/y' of an "
+ + "existing package 'x'. For example, after deleting x/y/BUILD "
+ + "in your client, the build system may complain if it "
+ + "encounters a label '//x:y/z' if that is still provided by another "
+ + "package_path entry. Specifying --deleted_packages x/y avoids this "
+ + "problem."
+ )
public List<PackageIdentifier> deletedPackages;
- @Option(name = "default_visibility",
- defaultValue = "private",
- category = "undocumented",
- converter = DefaultVisibilityConverter.class,
- help = "Default visibility for packages that don't set it explicitly ('public' or "
- + "'private').")
+ @Option(
+ name = "default_visibility",
+ defaultValue = "private",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+ converter = DefaultVisibilityConverter.class,
+ help =
+ "Default visibility for packages that don't set it explicitly ('public' or " + "'private')."
+ )
public RuleVisibility defaultVisibility;
- @Option(name = "legacy_globbing_threads",
- defaultValue = "100",
- category = "undocumented",
- help = "Number of threads to use for glob evaluation.")
+ @Option(
+ name = "legacy_globbing_threads",
+ defaultValue = "100",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+ help = "Number of threads to use for glob evaluation."
+ )
public int globbingThreads;
@Option(
name = "experimental_max_directories_to_eagerly_visit_in_globbing",
defaultValue = "-1",
- category = "undocumented",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
help =
"If non-negative, the first time a glob is evaluated in a package, the subdirectories of "
+ "the package will be traversed in order to warm filesystem caches and compensate for "
@@ -121,17 +136,22 @@
)
public int maxDirectoriesToEagerlyVisitInGlobbing;
- @Option(name = "fetch",
- defaultValue = "true",
- category = "undocumented",
- help = "Allows the command to fetch external dependencies")
+ @Option(
+ name = "fetch",
+ defaultValue = "true",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+ help = "Allows the command to fetch external dependencies"
+ )
public boolean fetch;
- @Option(name = "experimental_check_output_files",
- defaultValue = "true",
- category = "undocumented",
- help = "Check for modifications made to the output files of a build. Consider setting "
- + "this flag to false to see the effect on incremental build times.")
+ @Option(
+ name = "experimental_check_output_files",
+ defaultValue = "true",
+ optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+ help =
+ "Check for modifications made to the output files of a build. Consider setting "
+ + "this flag to false to see the effect on incremental build times."
+ )
public boolean checkOutputFiles;
/**
