| // 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.build.lib.buildtool; | |
| import com.github.benmanes.caffeine.cache.CaffeineSpec; | |
| import com.google.common.annotations.VisibleForTesting; | |
| import com.google.common.collect.ImmutableSet; | |
| import com.google.common.flogger.GoogleLogger; | |
| import com.google.devtools.build.lib.analysis.config.CoreOptionConverters.EmptyToNullLabelConverter; | |
| import com.google.devtools.build.lib.cmdline.Label; | |
| import com.google.devtools.build.lib.util.OptionsUtils; | |
| import com.google.devtools.build.lib.util.ResourceConverter; | |
| import com.google.devtools.build.lib.vfs.PathFragment; | |
| import com.google.devtools.common.options.BoolOrEnumConverter; | |
| import com.google.devtools.common.options.Converters; | |
| import com.google.devtools.common.options.Converters.CaffeineSpecConverter; | |
| import com.google.devtools.common.options.Converters.PercentageConverter; | |
| 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.OptionEffectTag; | |
| import com.google.devtools.common.options.OptionMetadataTag; | |
| import com.google.devtools.common.options.OptionsBase; | |
| import com.google.devtools.common.options.OptionsClass; | |
| import com.google.devtools.common.options.OptionsParsingException; | |
| import com.google.devtools.common.options.RegexPatternOption; | |
| import java.util.List; | |
| import java.util.Map; | |
| import javax.annotation.Nullable; | |
| /** | |
| * Options interface for {@link BuildRequest}: can be used to parse command-line arguments. | |
| * | |
| * <p>See also {@code ExecutionOptions}; from the user's point of view, there's no qualitative | |
| * difference between these two sets of options. | |
| */ | |
| @OptionsClass | |
| public abstract class BuildRequestOptions extends OptionsBase { | |
| private static final GoogleLogger logger = GoogleLogger.forEnclosingClass(); | |
| private static final int JOBS_TOO_HIGH_WARNING = 2500; | |
| @VisibleForTesting public static final int MAX_JOBS = 5000; | |
| /* "Execution": options related to the execution of a build: */ | |
| @Option( | |
| name = "jobs", | |
| abbrev = 'j', | |
| defaultValue = "auto", | |
| documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, | |
| effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION}, | |
| converter = JobsConverter.class, | |
| help = | |
| "The number of concurrent jobs to run. Takes " | |
| + ResourceConverter.FLAG_SYNTAX | |
| + ". Values must be between 1 and " | |
| + MAX_JOBS | |
| + ". Values above " | |
| + JOBS_TOO_HIGH_WARNING | |
| + " may cause memory issues. \"auto\" calculates a reasonable default based on" | |
| + " host resources.") | |
| public abstract int getJobs(); | |
| @Option( | |
| name = "experimental_async_execution", | |
| defaultValue = "false", | |
| documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, | |
| metadataTags = OptionMetadataTag.INCOMPATIBLE_CHANGE, | |
| effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION}, | |
| help = | |
| """ | |
| If set to true, Bazel is allowed to run action in a virtual thread. The number of | |
| actions in flight is still capped with `--jobs`. | |
| """) | |
| public abstract boolean getUseAsyncExecution(); | |
| @Option( | |
| name = "experimental_async_execution_max_concurrent_actions", | |
| defaultValue = "5000", | |
| documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, | |
| effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION}, | |
| help = | |
| """ | |
| The number of maximum concurrent actions to run with async execution. If the value is | |
| less than `--jobs`, it is clamped to `--jobs`. | |
| """) | |
| public abstract int getAsyncExecutionMaxConcurrentActions(); | |
| @Option( | |
| name = "bust_action_caches", | |
| converter = EmptyToNullLabelConverter.class, | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| metadataTags = {OptionMetadataTag.EXPERIMENTAL}, | |
| help = | |
| """ | |
| If set to a target label, unconditionally executes all actions of this target, | |
| circumventing the usual caching layers. Intended for debugging only; no guarantees are | |
| made that every execution strategy will respect it. | |
| """) | |
| @Nullable | |
| public abstract Label getBustActionCachesTarget(); | |
| @Option( | |
| name = "progress_report_interval", | |
| defaultValue = "0", | |
| documentationCategory = OptionDocumentationCategory.LOGGING, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| converter = ProgressReportIntervalConverter.class, | |
| help = | |
| """ | |
| The number of seconds to wait between reports on still running jobs. The | |
| default value 0 means the first report will be printed after 10 | |
| seconds, then 30 seconds and after that progress is reported once every minute. | |
| When `--curses` is enabled, progress is reported every second. | |
| """) | |
| public abstract int getProgressReportInterval(); | |
| @Option( | |
| name = "explain", | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.LOGGING, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| converter = OptionsUtils.PathFragmentConverter.class, | |
| help = | |
| "Causes the build system to explain each executed step of the " | |
| + "build. The explanation is written to the specified log file.") | |
| public abstract PathFragment getExplanationPath(); | |
| @Option( | |
| name = "output_filter", | |
| converter = Converters.RegexPatternConverter.class, | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.LOGGING, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| "Only shows warnings and action outputs for rules with a name matching the provided " | |
| + "regular expression.") | |
| @Nullable | |
| public abstract RegexPatternOption getOutputFilter(); | |
| @Option( | |
| name = "analyze", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| Execute the loading/analysis phase; this is the usual behaviour. Specifying `--noanalyze` | |
| causes the build to stop before starting the loading/analysis phase, just doing | |
| target pattern parsing and returning zero if that completed successfully; this | |
| mode is useful for testing. | |
| """) | |
| public abstract boolean getPerformAnalysisPhase(); | |
| @Option( | |
| name = "build", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| Execute the build; this is the usual behaviour. | |
| Specifying `--nobuild` causes the build to stop before executing the build | |
| actions, returning zero if the package loading and analysis phases completed | |
| successfully; this mode is useful for testing those phases. | |
| """) | |
| public abstract boolean getPerformExecutionPhase(); | |
| @Option( | |
| name = "output_groups", | |
| converter = Converters.CommaSeparatedOptionListConverter.class, | |
| allowMultiple = true, | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| defaultValue = "null", | |
| help = | |
| """ | |
| A list of comma-separated output group names, each of which optionally prefixed by a `+` | |
| or a `-`. A group prefixed by `+` is added to the default set of output groups, | |
| while a group prefixed by `-` is removed from the default set. If at least one | |
| group is not prefixed, the default set of output groups is omitted. For example, | |
| `--output_groups=+foo,+bar` builds the union of the default set, foo, and bar, | |
| while `--output_groups=foo,bar` overrides the default set such that only foo and | |
| bar are built. | |
| """) | |
| public abstract List<String> getOutputGroups(); | |
| @Option( | |
| name = "extra_default_output_groups", | |
| converter = Converters.CommaSeparatedOptionListConverter.class, | |
| allowMultiple = true, | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| defaultValue = "null", | |
| help = | |
| """ | |
| A list of comma-separated output group names to treat as part of the default set of | |
| output groups. Unlike `--output_groups=+foo`, which is always built, an extra default | |
| output group is only built when the default set is: it is omitted if `--output_groups` | |
| contains an unprefixed group, and can be removed with `--output_groups=-foo`. Intended | |
| for wrappers and rc files that want to augment the default outputs without overriding | |
| an explicit `--output_groups` selection. Artifacts in these output groups are hidden | |
| from results as if listed in `--hide_output_group_results`. | |
| """) | |
| public abstract List<String> getExtraDefaultOutputGroups(); | |
| @Option( | |
| name = "incompatible_fail_on_unknown_output_groups", | |
| defaultValue = "false", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE}, | |
| help = | |
| "If true, building explicitly requested output groups that are not present on any" | |
| + " top-level target or aspect fails the build.") | |
| public abstract boolean getIncompatibleFailOnUnknownOutputGroups(); | |
| @Option( | |
| name = "run_validations", | |
| oldName = "experimental_run_validations", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| Whether to run validation actions as part of the build. See [Validation Actions]. | |
| [Validation Actions]: https://bazel.build/extending/rules#validation_actions | |
| """) | |
| public abstract boolean getRunValidationActions(); | |
| @Option( | |
| name = "experimental_use_validation_aspect", | |
| defaultValue = "false", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION, | |
| effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = "Whether to run validation actions using aspect (for parallelism with tests).") | |
| public abstract boolean getUseValidationAspect(); | |
| @Option( | |
| name = "show_result", | |
| defaultValue = "1", | |
| 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 | |
| are convenient strings for copy+pasting to the shell, to execute them. | |
| This option requires an integer argument, which is the threshold number of targets | |
| above which result information is not printed. Thus zero causes suppression of | |
| the message and `MAX_INT` causes printing of the result to occur always. The | |
| default is one. | |
| If nothing was built for a target its results may be omitted to keep the output | |
| under the threshold. | |
| """) | |
| public abstract int getMaxResultTargets(); | |
| @Option( | |
| name = "hide_aspect_results", | |
| converter = Converters.CommaSeparatedOptionListConverter.class, | |
| defaultValue = "", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.TERMINAL_OUTPUT}, | |
| help = | |
| """ | |
| Comma-separated list of aspect names to not display in results (see `--show_result`). | |
| Useful for keeping aspects added by wrappers which are typically not interesting | |
| to end users out of console output. | |
| """) | |
| public abstract List<String> getHideAspectResults(); | |
| // TODO(b/577126732): Remove in favor of --extra_default_output_groups once blazercs no longer | |
| // set this flag. | |
| @Option( | |
| name = "hide_output_group_results", | |
| converter = Converters.CommaSeparatedOptionListConverter.class, | |
| defaultValue = "", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.TERMINAL_OUTPUT}, | |
| help = | |
| """ | |
| Comma-separated list of output group names whose artifacts are not displayed in | |
| results (see `--show_result`). The output groups are still built and treated as | |
| important outputs; only console output is affected. An artifact that also belongs to | |
| a requested output group not in this list is still displayed. Also suppresses the | |
| warning for listed output groups that are requested but not present on any top-level | |
| target or aspect (but not the error under | |
| `--incompatible_fail_on_unknown_output_groups`). | |
| """) | |
| public abstract List<String> getHideOutputGroupResults(); | |
| /** | |
| * Returns the output groups whose artifacts are not displayed in results: those listed in {@code | |
| * --hide_output_group_results} plus those in {@code --extra_default_output_groups}, which are | |
| * added by wrappers rather than requested by the user and so are implicitly hidden. | |
| */ | |
| public ImmutableSet<String> getAllHiddenOutputGroupResults() { | |
| return ImmutableSet.<String>builder() | |
| .addAll(getHideOutputGroupResults()) | |
| .addAll(getExtraDefaultOutputGroups()) | |
| .build(); | |
| } | |
| @Option( | |
| name = "symlink_prefix", | |
| defaultValue = "null", | |
| 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 omitted, the default value is the name of the build tool | |
| followed by a hyphen. If `/` is passed, then no symlinks are created and no | |
| warning is emitted. Warning: the special functionality for `/` will be deprecated | |
| soon; use `--experimental_convenience_symlinks=ignore` instead. | |
| """) | |
| @Nullable | |
| public abstract String getSymlinkPrefix(); | |
| @Option( | |
| name = "experimental_convenience_symlinks", | |
| converter = ConvenienceSymlinksConverter.class, | |
| defaultValue = "normal", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| This flag controls how the convenience symlinks (the symlinks that appear in the | |
| workspace after the build) will be managed. Possible values: | |
| - `normal` (default): Each kind of convenience symlink will be created or deleted, | |
| as determined by the build. | |
| - `clean`: All symlinks will be unconditionally deleted. | |
| - `ignore`: Symlinks will not be created or cleaned up. | |
| - `log_only`: Generate log messages as if `normal` were passed, but don't actually | |
| perform any filesystem operations (useful for tools). | |
| Note that only symlinks whose names are generated by the current value of | |
| `--symlink_prefix` can be affected; if the prefix changes, any pre-existing | |
| symlinks will be left alone. | |
| """) | |
| @Nullable | |
| public abstract ConvenienceSymlinksMode getExperimentalConvenienceSymlinks(); | |
| @Option( | |
| name = "experimental_convenience_symlinks_bep_event", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| This flag controls whether or not we will post the build event | |
| `ConvenienceSymlinksIdentified` to the Build Event Protocol. If the value is true, | |
| the BEP will have an entry for `convenienceSymlinksIdentified`, | |
| listing all of the convenience symlinks created in your workspace. If false, then | |
| the `convenienceSymlinksIdentified` entry in the BEP will be empty. | |
| """) | |
| public abstract boolean getExperimentalConvenienceSymlinksBepEvent(); | |
| @Option( | |
| name = "output_tree_tracking", | |
| oldName = "experimental_output_tree_tracking", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION}, | |
| help = | |
| "If set, tell the output service (if any) to track when files in the output " | |
| + "tree have been modified externally (not by the build system). " | |
| + "This should improve incremental build speed when an appropriate output service " | |
| + "is enabled.") | |
| public abstract boolean getFinalizeActions(); | |
| @Option( | |
| name = "directory_creation_cache", | |
| defaultValue = "maximumSize=100000", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| converter = CaffeineSpecConverter.class, | |
| help = | |
| "Describes the cache used to store known regular directories as they're created. Parent" | |
| + " directories of output files are created on-demand during action execution.") | |
| public abstract CaffeineSpec getDirectoryCreationCacheSpec(); | |
| @Option( | |
| name = "aspects", | |
| converter = Converters.CommaSeparatedOptionListConverter.class, | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, | |
| effectTags = {OptionEffectTag.UNKNOWN}, | |
| allowMultiple = true, | |
| help = | |
| """ | |
| Comma-separated list of aspects to be applied to top-level targets. In the list, if | |
| aspect `some_aspect` specifies required aspect providers via | |
| `required_aspect_providers`, `some_aspect` will run after | |
| every aspect that was mentioned before it in the aspects list whose advertised | |
| providers satisfy `some_aspect` required aspect providers. Moreover, | |
| `some_aspect` will run after all its required aspects specified by | |
| `requires` attribute. | |
| `some_aspect` will then have access to the values of those aspects' | |
| providers. | |
| `{bzl-file-label}%{aspect_name}`, for example `//tools:my_def.bzl%my_aspect`, where | |
| `my_aspect` is a top-level value from a file `tools/my_def.bzl`. | |
| """) | |
| public abstract List<String> getAspects(); | |
| @Option( | |
| name = "aspects_parameters", | |
| converter = Converters.AssignmentConverter.class, | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.GENERIC_INPUTS, | |
| effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS}, | |
| allowMultiple = true, | |
| help = | |
| """ | |
| Specifies the values of the command-line aspects parameters. Each parameter value is | |
| specified via `<param_name>=<param_value>`, for example `my_param=my_val` where | |
| `my_param` is a parameter of some aspect in `--aspects` list or required by an | |
| aspect in the list. This option can be used multiple times. However, it is not | |
| allowed to assign values to the same parameter more than once. | |
| """) | |
| public abstract List<Map.Entry<String, String>> getAspectsParameters(); | |
| public BuildRequestOptions() {} | |
| public String getSymlinkPrefix(String productName) { | |
| return getSymlinkPrefix() == null ? productName + "-" : getSymlinkPrefix(); | |
| } | |
| @Option( | |
| name = "use_action_cache", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = { | |
| OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION, | |
| OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS | |
| }, | |
| help = "Whether to use the action cache") | |
| public abstract boolean getUseActionCache(); | |
| @Option( | |
| name = "rewind_lost_inputs", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.REMOTE, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| help = "Whether to use action rewinding to recover from lost inputs.") | |
| public abstract boolean getRewindLostInputs(); | |
| @Option( | |
| name = "experimental_check_rewound_action_outputs", | |
| defaultValue = "false", | |
| documentationCategory = OptionDocumentationCategory.REMOTE, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| metadataTags = {OptionMetadataTag.EXPERIMENTAL}, | |
| help = | |
| "Fail if regenerating a rewound action changes its recorded output contents. This detects" | |
| + " nondeterministic regeneration before dependent actions consume the new result." | |
| + " Best effort: requires previous output metadata and may miss changes when another" | |
| + " shared action regenerates the outputs.") | |
| public abstract boolean getCheckRewoundActionOutputs(); | |
| @Option( | |
| name = "experimental_max_repeated_lost_inputs", | |
| defaultValue = "20", | |
| documentationCategory = OptionDocumentationCategory.REMOTE, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| help = | |
| "The maximum number of times action rewinding will try to recover the same lost input (or" | |
| + " top-level output) for the same action before giving up and failing the build. Set" | |
| + " this lower to fail fast on an unstable remote cache instead of repeatedly" | |
| + " rewinding a single lost input; 0 fails on the first lost input. Only takes effect" | |
| + " when --rewind_lost_inputs is enabled.") | |
| public abstract int getMaxRepeatedLostInputs(); | |
| @Option( | |
| name = "experimental_precise_rewinding", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| metadataTags = {OptionMetadataTag.EXPERIMENTAL}, | |
| help = "No-op slated for removal.") | |
| public abstract boolean getExperimentalPreciseRewinding(); | |
| @Option( | |
| name = "incompatible_skip_genfiles_symlink", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE}, | |
| effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE}, | |
| help = | |
| """ | |
| If set to true, the genfiles symlink will not be created. For more information, see | |
| [GH-8651]. | |
| [GH-8651]: https://github.com/bazelbuild/bazel/issues/8651 | |
| """) | |
| public abstract boolean getIncompatibleSkipGenfilesSymlink(); | |
| @Option( | |
| name = "target_pattern_file", | |
| defaultValue = "", | |
| documentationCategory = OptionDocumentationCategory.GENERIC_INPUTS, | |
| effectTags = {OptionEffectTag.CHANGES_INPUTS}, | |
| help = | |
| "If set, build will read patterns from the file named here, rather than on the command " | |
| + "line. It is an error to specify a file here as well as command-line patterns.") | |
| public abstract String getTargetPatternFile(); | |
| @Option( | |
| name = "target_query", | |
| defaultValue = "", | |
| documentationCategory = OptionDocumentationCategory.GENERIC_INPUTS, | |
| effectTags = {OptionEffectTag.CHANGES_INPUTS}, | |
| help = | |
| "If set, build will evaluate the query expression and build the resulting targets. " | |
| + "Example: --target_query='deps(//foo) - deps(//bar)'. May be combined with " | |
| + "command-line target patterns. Cannot be used with --target_pattern_file or " | |
| + "--target_query_file.") | |
| public abstract String getTargetQuery(); | |
| @Option( | |
| name = "target_query_file", | |
| defaultValue = "", | |
| documentationCategory = OptionDocumentationCategory.GENERIC_INPUTS, | |
| effectTags = {OptionEffectTag.CHANGES_INPUTS}, | |
| help = | |
| "If set, build will read a query expression from the file named here and build the " | |
| + "resulting targets. May be combined with command-line target patterns. Cannot be " | |
| + "used with --target_pattern_file or --target_query.") | |
| public abstract String getTargetQueryFile(); | |
| /** | |
| * Do not use directly. Instead use {@link | |
| * com.google.devtools.build.lib.runtime.CommandEnvironment#withMergedAnalysisAndExecutionSourceOfTruth()}. | |
| */ | |
| @Option( | |
| name = "experimental_merged_skyframe_analysis_execution", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| metadataTags = OptionMetadataTag.EXPERIMENTAL, | |
| effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS, OptionEffectTag.EXECUTION}, | |
| help = "If this flag is set, the analysis and execution phases of Skyframe are merged.") | |
| public abstract boolean getMergedSkyframeAnalysisExecutionDoNotUseDirectly(); | |
| @Option( | |
| name = "experimental_skymeld_analysis_overlap_percentage", | |
| defaultValue = "100", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| metadataTags = OptionMetadataTag.EXPERIMENTAL, | |
| effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS, OptionEffectTag.EXECUTION}, | |
| converter = PercentageConverter.class, | |
| help = | |
| "The value represents the % of the analysis phase which will be overlapped with the" | |
| + " execution phase. A value of x means Skyframe will queue up execution tasks and" | |
| + " wait until there's x% of the top level target left to be analyzed before allowing" | |
| + " them to launch. When the value is 0%, we'd wait for all analysis to finish before" | |
| + " executing (no overlap). When it's 100%, the phases are free to overlap as much as" | |
| + " they can.") | |
| public abstract int getSkymeldAnalysisOverlapPercentage(); | |
| /** Converter for filesystem value checker threads. */ | |
| public static class ThreadConverter extends ResourceConverter.IntegerConverter { | |
| public ThreadConverter() { | |
| super(/* auto= */ HOST_CPUS_SUPPLIER, /* minValue= */ 1, /* maxValue= */ Integer.MAX_VALUE); | |
| } | |
| } | |
| @Option( | |
| name = "experimental_fsvc_threads", | |
| defaultValue = "200", | |
| converter = ThreadConverter.class, | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| metadataTags = OptionMetadataTag.EXPERIMENTAL, | |
| effectTags = {OptionEffectTag.EXECUTION}, | |
| help = "The number of threads that are used by the `FileSystemValueChecker`.") | |
| public abstract int getFsvcThreads(); | |
| @Option( | |
| name = "experimental_skyframe_memory_dump", | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| Dump the memory use of individual nodes in the Skyframe graph after the build. This | |
| option takes a number of flags separated by commas: | |
| - `json` (no-op, that's the only format). | |
| - `notransient` (don't traverse transient fields). | |
| - `noconfig` (ignore objects related to configurations). | |
| - `noprecomputed` (ignore precomputed values). | |
| - `noworkspacestatus` (ignore objects related to the workspace status machinery). | |
| """) | |
| public abstract String getSkyframeMemoryDump(); | |
| @Option( | |
| name = "enforce_project_configs", | |
| defaultValue = "true", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS, OptionEffectTag.AFFECTS_OUTPUTS}, | |
| metadataTags = {OptionMetadataTag.EXPERIMENTAL}, | |
| // TODO: b/341931019 - link to user documentation when available. | |
| help = | |
| "If true, interactive builds may only pass the --scl_config build flag; they may not use" | |
| + " any other build flags. --scl_config must be set to an officially supported" | |
| + " project configuration. Supported configurations are defined in the target's" | |
| + " PROJECT.scl, which can be found by walking up the target's packagge path. See" | |
| + " b/324126745.") | |
| public abstract boolean getEnforceProjectConfigs(); | |
| @Option( | |
| name = "experimental_aquery_dump_after_build_format", | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| help = | |
| """ | |
| Writes the state of Skyframe (which includes previous invocations on this blaze instance | |
| as well) after a build. Output is streamed remotely unless local output is | |
| requested with `--experimental_aquery_dump_after_build_output_file`. Does not | |
| honor aquery flags for `--include_*`, but uses the same defaults, except for | |
| `--include_commandline=false`. Possible output formats: | |
| `proto|streamed_proto|textproto|jsonproto`. Using this will disable Skymeld. | |
| """) | |
| @Nullable | |
| public abstract String getAqueryDumpAfterBuildFormat(); | |
| @Option( | |
| name = "experimental_aquery_dump_after_build_output_file", | |
| defaultValue = "null", | |
| documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, | |
| effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, | |
| converter = OptionsUtils.PathFragmentConverter.class, | |
| // NOTE: This produces a very very large amount of data on large builds, | |
| // very useful for debugging, but may not be used regularly. When removing | |
| // unused flags based on usage this may not be a good candidate for | |
| // removal. | |
| help = | |
| """ | |
| Specify the output file for the aquery dump after a build. Use in conjunction with | |
| `--experimental_aquery_dump_after_build_format`. The path provided is relative to | |
| Bazel's output base, unless it's an absolute path. Using this will disable Skymeld. | |
| """) | |
| @Nullable | |
| public abstract PathFragment getAqueryDumpAfterBuildOutputFile(); | |
| /** | |
| * Converter for jobs: Takes keyword ({@value #FLAG_SYNTAX}). Values must be between 1 and | |
| * MAX_JOBS. | |
| */ | |
| public static class JobsConverter extends ResourceConverter.IntegerConverter { | |
| public JobsConverter() { | |
| super(/* auto= */ HOST_CPUS_SUPPLIER, /* minValue= */ 1, /* maxValue= */ MAX_JOBS); | |
| } | |
| @Override | |
| public Integer checkAndLimit(Integer value) throws OptionsParsingException { | |
| if (value.doubleValue() < minValue) { | |
| throw new OptionsParsingException( | |
| String.format("Value '(%d)' must be at least %d.", value, minValue)); | |
| } | |
| if (value.doubleValue() > maxValue) { | |
| logger.atWarning().log( | |
| "Flag remoteWorker \"jobs\" ('%d') was set too high. " | |
| + "This is a result of passing large values to --local_resources or --jobs. " | |
| + "Using '%d' jobs", | |
| value, maxValue); | |
| return maxValue; | |
| } | |
| return value; | |
| } | |
| } | |
| /** Converter for progress_report_interval: [0, 3600]. */ | |
| public static class ProgressReportIntervalConverter extends RangeConverter { | |
| public ProgressReportIntervalConverter() { | |
| super(0, 3600); | |
| } | |
| } | |
| /** | |
| * The {@link BoolOrEnumConverter} for the {@link ConvenienceSymlinksMode} where NORMAL is true | |
| * and IGNORE is false. | |
| */ | |
| public static class ConvenienceSymlinksConverter | |
| extends BoolOrEnumConverter<ConvenienceSymlinksMode> { | |
| public ConvenienceSymlinksConverter() { | |
| super( | |
| ConvenienceSymlinksMode.class, | |
| "convenience symlinks mode", | |
| ConvenienceSymlinksMode.NORMAL, | |
| ConvenienceSymlinksMode.IGNORE); | |
| } | |
| } | |
| /** Determines how the convenience symlinks are presented to the user */ | |
| enum ConvenienceSymlinksMode { | |
| /** Will manage symlinks based on the symlink prefix. */ | |
| NORMAL, | |
| /** Will clean up any existing symlinks. */ | |
| CLEAN, | |
| /** Will not create or clean up any symlinks. */ | |
| IGNORE, | |
| /** Will not create or clean up any symlinks, but will record the symlinks. */ | |
| LOG_ONLY | |
| } | |
| } |