// 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.flogger.GoogleLogger; import com.google.devtools.build.lib.actions.LocalHostCapacity; 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.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. * *

See also {@code ExecutionOptions}; from the user's point of view, there's no qualitative * difference between these two sets of options. */ public 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 int jobs; @Option( name = "experimental_use_semaphore_for_jobs", defaultValue = "false", documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY, effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION}, help = "If set to true, additionally use semaphore to limit number of concurrent jobs.") public boolean useSemaphoreForJobs; @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 int progressReportInterval; @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 PathFragment explanationPath; @Option( name = "verbose_explanations", defaultValue = "false", 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.") public boolean verboseExplanations; @Option( name = "output_filter", converter = Converters.RegexPatternConverter.class, defaultValue = "null", documentationCategory = OptionDocumentationCategory.LOGGING, effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "Only shows warnings for rules with a name matching the provided regular expression.") @Nullable public RegexPatternOption outputFilter; @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 iff that completed successfully; this " + "mode is useful for testing.") public boolean performAnalysisPhase; @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 iff the package loading and analysis phases completed " + "successfully; this mode is useful for testing those phases.") public boolean performExecutionPhase; @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 List outputGroups; @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" + " https://bazel.build/extending/rules#validation_actions") public boolean runValidationActions; @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 boolean useValidationAspect; @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.\n" + "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.\n" + "If nothing was built for a target its results may be omitted to keep the output" + " under the threshold.") public int maxResultTargets; @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 String symlinkPrefix; @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:\n" + " normal (default): Each kind of convenience symlink will be created or deleted, " + "as determined by the build.\n" + " clean: All symlinks will be unconditionally deleted.\n" + " ignore: Symlinks will be left alone.\n" + " log_only: Generate log messages as if 'normal' were passed, but don't actually " + "perform any filesystem operations (useful for tools).\n" + "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 ConvenienceSymlinksMode experimentalConvenienceSymlinks; @Option( name = "experimental_convenience_symlinks_bep_event", defaultValue = "false", documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS, effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "This flag controls whether or not we will post the build event" + "ConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, " + "the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, " + "listing all of the convenience symlinks created in your workspace. If false, then " + "the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty.") public boolean experimentalConvenienceSymlinksBepEvent; @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 boolean finalizeActions; @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 CaffeineSpec directoryCreationCacheSpec; @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." + " %, for example '//tools:my_def.bzl%my_aspect', where" + " 'my_aspect' is a top-level value from a file tools/my_def.bzl") public List aspects; @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 =, 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 List> aspectsParameters; public BuildRequestOptions() throws OptionsParsingException {} public String getSymlinkPrefix(String productName) { return symlinkPrefix == null ? productName + "-" : symlinkPrefix; } @Option( name = "experimental_create_py_symlinks", defaultValue = "false", documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, help = "If enabled, two convenience symlinks, `py2` and `py3`, will be created (with the" + " appropriate prefix). These point to the output directories for the Python 2 and" + " Python 3 configurations, respectively. This can be used to access outputs in the" + " bin directory of a specific Python version. For instance, if --symlink_prefix is" + " `foo-`, the path `foo-py2/bin` behaves like `foo-bin` except that it is" + " guaranteed to contain artifacts built in the Python 2 configuration. IMPORTANT:" + " This flag is not planned to be enabled by default, and should not be relied on.") public boolean experimentalCreatePySymlinks; @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 boolean useActionCache; @Option( name = "rewind_lost_inputs", defaultValue = "false", documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, effectTags = {OptionEffectTag.EXECUTION}, help = "Whether to use action rewinding to recover from lost inputs. Ignored unless" + " prerequisites for rewinding are met (no incrementality, no action cache).") public boolean rewindLostInputs; @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 " + "https://github.com/bazelbuild/bazel/issues/8651") public boolean incompatibleSkipGenfilesSymlink; @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 String targetPatternFile; /** * Do not use directly. Instead use {@link * com.google.devtools.build.lib.runtime.CommandEnvironment#withMergedAnalysisAndExecutionSourceOfTruth()}. */ @Option( name = "experimental_merged_skyframe_analysis_execution", defaultValue = "false", 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 boolean mergedSkyframeAnalysisExecutionDoNotUseDirectly; @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 int skymeldAnalysisOverlapPercentage; /** Converter for filesystem value checker threads. */ public static class ThreadConverter extends ResourceConverter { public ThreadConverter() { super( /* autoSupplier= */ () -> (int) Math.ceil(LocalHostCapacity.getLocalHostCapacity().getCpuUsage()), /* 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 int fsvcThreads; @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) to stdout after a build, in the same format as aquery's." + " Possible formats: proto|textproto|jsonproto.") @Nullable public String aqueryDumpAfterBuildFormat; @Option( name = "experimental_aquery_dump_after_build_output_file", defaultValue = "null", documentationCategory = OptionDocumentationCategory.UNDOCUMENTED, effectTags = {OptionEffectTag.AFFECTS_OUTPUTS}, converter = OptionsUtils.PathFragmentConverter.class, 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.") @Nullable public PathFragment aqueryDumpAfterBuildOutputFile; /** * Converter for jobs: Takes keyword ({@value #FLAG_SYNTAX}). Values must be between 1 and * MAX_JOBS. */ public static class JobsConverter extends ResourceConverter { public JobsConverter() { super( () -> (int) Math.ceil(LocalHostCapacity.getLocalHostCapacity().getCpuUsage()), 1, MAX_JOBS); } @Override public int checkAndLimit(int value) throws OptionsParsingException { if (value < minValue) { throw new OptionsParsingException( String.format("Value '(%d)' must be at least %d.", value, minValue)); } if (value > 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); value = 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 { 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 } }