// 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.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.
 *
 * <p>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 = "true",
      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 = "experimental_async_execution",
      defaultValue = "false",
      documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
      metadataTags = OptionMetadataTag.INCOMPATIBLE_CHANGE,
      effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION},
      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 boolean useAsyncExecution;

  @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 and action outputs 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<String> 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 = "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 List<String> hideAspectResults;

  @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."
              + " <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 List<String> 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 <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 List<Map.Entry<String, String>> aspectsParameters;

  public BuildRequestOptions() throws OptionsParsingException {}

  public String getSymlinkPrefix(String productName) {
    return symlinkPrefix == null ? productName + "-" : symlinkPrefix;
  }

  @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.")
  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 = "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 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.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 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.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
  }
}