// Copyright 2019 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package chromiumos;

option go_package = "go.chromium.org/chromiumos/infra/proto/go/chromiumos";

import "chromiumos/common.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

// Configuration used by a builder during execution.
message BuilderConfig {

  // Used to control running of special steps.
  enum RunSpec {
    RUN_SPEC_UNSPECIFIED = 0;
    // Do not run.
    NO_RUN = 1;
    // Run.
    RUN = 2;
    // Run and then exit.
    RUN_EXIT = 3;
  }

  // Unique identifier of the builder configuration.
  message Id {
    // The name of the configuration such as "arm-generic-postsubmit".
    string name = 1;
    // Branch the configuration applies to such as "release-R73-11647.B".
    string branch = 2;
    // Type of build.
    enum Type {
      TYPE_UNSPECIFIED = 0;
      // Commit queue build.
      CQ = 1;
      // Postsubmit build.
      POSTSUBMIT = 2;
      // Toolchain build.
      TOOLCHAIN = 3;
      // Informational build.
      INFORMATIONAL = 4;
    }
    Type type = 3;
  }
  Id id = 1;

  // General configuration for the builder.
  message General {
    // Whether or not the build is considered critical. A failure in a critical
    // build for a CQ builder may, for example, prevent submission of the CL.
    google.protobuf.BoolValue critical = 1;

    enum Environment {
      ENVIRONMENT_UNSPECIFIED = 0;
      PRODUCTION = 1;
      STAGING = 2;
    }
    Environment environment = 2;

    // Rule describing conditions under which a builder should be launched.
    message RunWhen {
      enum Mode {
        MODE_UNSPECIFIED = 0;

        // Always run this builder. The file_patterns field will be ignored
        // when this mode is selected.
        ALWAYS_RUN = 1;

        // Only run this builder if any file in the input gerrit_changes
        // matches any file_pattern specified below. If file_patterns is empty,
        // this option implies the builder will never run.
        ONLY_RUN_ON_FILE_MATCH = 2;

        // Do not run the builder if all files in the input gerrit_changes
        // match any file_attern speicifed below. If file_patterns is empty,
        // this option implies the builder will always run.
        NO_RUN_ON_FILE_MATCH = 3;
      }

      Mode mode = 1;

      // chromiumos code file patterns, relative to chromiumos root, which may
      // use * or ** for globbing.
      // e.g.
      // chromite/myfile.txt
      // chromite/config/*
      // **/*.md
      repeated string file_patterns = 2;
    }

    // A rule describing conditions under which this builder should be launched.
    RunWhen run_when = 3;

    // Time before which ToT had a bug that would not manifest at the
    // build stage. The CQ orchestrator should NOT reuse successful builds
    // of the build_config before this.
    google.protobuf.Timestamp broken_before = 4;

    // If present, this version number will be written to a version file
    // alongside a bot's SDK Cache (chroot). On subsequent bot-run where an SDK
    // Cache already exists, the version number in config will be compared to
    // the number present in the version file, and the SDK Cache will be
    // invalidated if there is a mismatch.
    int32 sdk_cache_version = 5;
  }
  General general = 2;

  // Configuration pertaining to builders operating as "orchestrators".
  // Orchestrators orchestrate the running of other child builders.
  message Orchestrator {
    reserved 1;

    // Defines a child the orchestrator spawns and how it is handled.
    message ChildSpec {
      // BuilderConfig.Id.name of the child build. Would be expected to match
      // this name and the BuilderConfig.Id.branch and BuilderConfig.Id.type of
      // this parent orchestrator builder.
      string name = 1;

      enum CollectHandling {
        COLLECT_HANDLING_UNSPECIFIED = 0;
        // Indicates the result should be collected. Currently also indicates
        // that should the orchestrator terminate before this child finishes
        // the child will be killed.
        COLLECT = 1;
        // Indicates the result should not be collected. Currently also
        // indicates that should the orchestrator terminate before this child
        // finishes this child is allowed to continue.
        NO_COLLECT = 2;
      }
      CollectHandling collect_handling = 2;
    }
    repeated ChildSpec child_specs = 5;

    // GitilesCommit to use if not provided.
    GitilesCommit gitiles_commit = 2;

    // GerritChanges to use if not provided.
    repeated GerritChange gerrit_changes = 3;

    // Follow on orchestrator to launch, and possibly wait for.
    message FollowOnOrchestrator {
      // BuilderConfig.Id.name of the follow on orchestrator.
      string name = 1;

      // Whether to wait for the follow on orchestrator to finish.
      bool await_completion = 2;
    }
    FollowOnOrchestrator follow_on_orchestrator = 4;
  }
  Orchestrator orchestrator = 3;

  // Configuration pertaining to artifacts produced during a build.
  message Artifacts {
    // How to handle the uploading of prebuilts.
    enum Prebuilts {
      PREBUILTS_UNSPECIFIED = 0;
      PUBLIC = 1;
      PRIVATE = 2;
      NONE = 3;
    }
    Prebuilts prebuilts = 1;

    // Used to indicate artifact types that should be uploaded by the builder.
    // Must be kept in sync with the dictionary in:
    // https://chromium.googlesource.com/chromiumos/infra/recipes/+/refs/heads/master/recipe_modules/cros_artifacts/api.py
    // TODO(crbug/1027720): Migrate this to common.proto
    enum ArtifactTypes {
      ARTIFACT_TYPES_UNSPECIFIED = 0;
      // Indicates wanting a zip file of everything in the image directory.
      IMAGE_ZIP = 1;
      // Indicates wanting update payloads.
      TEST_UPDATE_PAYLOAD = 2;
      // Indicates wanting the autotest tarballs.
      AUTOTEST_FILES = 3;
      // Indicates wanting a tarball containing private TAST test bundles.
      TAST_FILES = 4;
      // Indicates wanting a tarball containing guest images and test bundles.
      PINNED_GUEST_IMAGES = 5;
      // Indicates wanting an archive of firmware images built from source.
      FIRMWARE = 6;
      // Indicates wanting a tarball of the Ebuilds logs.
      EBUILD_LOGS = 7;
      // Indicates wanting an archive of the ChromeOS Config.
      CHROMEOS_CONFIG = 8;
      // Indicates wanting the CPE report.
      CPE_REPORT = 9;
      // Indicates wanting a tar.xz archive for each image that has been created.
      IMAGE_ARCHIVES = 10;

      // Artifacts used by the toolchain.
      //
      // Indicates an unvetted orderfile for Chrome.
      UNVERIFIED_CHROME_LLVM_ORDERFILE = 11;
      // Indicates a vetted orderfile for Chrome.
      VERIFIED_CHROME_LLVM_ORDERFILE = 12;
      // Indicates a clang-tidy artifact.
      CHROME_CLANG_WARNINGS_FILE = 13;
      // Indicates a PGO artifact for the compiler.
      UNVERIFIED_LLVM_PGO_FILE = 14;

      // Indicates an unvetted AFDO Chrome profile.  (Generated by HW Tests in
      // the benchmark-afdo-generate builder.)
      UNVERIFIED_CHROME_BENCHMARK_AFDO_FILE = 15;
      // Indicates a vetted AFDO Chrome profile.
      VERIFIED_CHROME_BENCHMARK_AFDO_FILE = 16;

      // Indicates a vetted AFDO Kernel profile.
      VERIFIED_KERNEL_CWP_AFDO_FILE = 17;
      // Indicates an unvetted AFDO Kernel CWP profile.
      UNVERIFIED_KERNEL_CWP_AFDO_FILE = 18;

      // Indicates an unvetted AFDO Chrome CWP profile.
      UNVERIFIED_CHROME_CWP_AFDO_FILE = 19;
      // Indicates a vetted AFDO Chrome CWP profile.
      VERIFIED_CHROME_CWP_AFDO_FILE = 20;
      // Indicates a vetted AFDO profile for release.
      VERIFIED_RELEASE_AFDO_FILE = 21;

      // Indicates an unvetted AFDO perf data file (from HW Test).
      UNVERIFIED_CHROME_BENCHMARK_PERF_FILE = 22;
    }
    repeated ArtifactTypes artifact_types = 2;

    // Google storage bucket to upload prebuilts to.
    string prebuilts_gs_bucket = 3;

    // Google storage bucket to upload artifacts to.
    string artifacts_gs_bucket = 4;

    message PublishInfo {
      reserved 1;

      // Artifact types to publish to this bucket.
      repeated ArtifactTypes publish_types = 2;

      // GS location in which to publish artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      string publish_gs_location = 3;
    }
    // There may be more than one set of publishing instructions.
    repeated PublishInfo publish_artifacts = 5;

    message InputArtifactInfo {
      // Artifact type to seek in these buckets.  Use the first instance of the
      // artifact found in the list of locations.
      ArtifactTypes input_artifact_type = 1;

      // Google storage locations containing these artifacts.
      repeated string input_artifact_gs_locations = 2;
    }
    // There may be more than one set of consumable artifacts.
    repeated InputArtifactInfo input_artifacts = 6;
  }
  Artifacts artifacts = 4;

  // Configuration pertaining to Chrome.
  message Chrome {
    // Whether to build internal or external Chrome. Internal chrome adds
    // Chrome branding.
    bool internal = 1;
  }
  Chrome chrome = 5;

  // Build specific configuration.
  message Build {
    // USE flags to use with the build.
    repeated UseFlag use_flags = 1;

    // The profile of the variant to set up and build.
    message PortageProfile {
      string profile = 1;
    }
    PortageProfile portage_profile = 2;

    reserved 3 to 5;

    // Whether to apply gerrit changes, if any. Use case is to build without
    // changes after failure to identify the changes as the culprit.
    bool apply_gerrit_changes = 6;

    reserved 7 to 11;

    // Below here are configuration specifications for the steps that call the
    // Build API endpoints.  They are listed in the order in which steps are
    // generally called, rather than in numerical order.

    // Controls for the call to cros_artifacts.prepare_for_build.
    message PrepareForBuild {
      // Additional arguments from common.proto, passed into any
      // PrepareFor*Build endpoint.
      PrepareForBuildAdditionalArgs additional_args = 1;
    }
    PrepareForBuild prepare_for_build = 17;

    // Controls for the call to SdkService.Update.
    message SdkUpdate {
      // Whether to compile from source (vs using prebuilts when able.)
      bool compile_source = 1;
    }
    SdkUpdate sdk_update = 12;

    // Controls for the call to SysrootService.InstallToolchain.
    message InstallToolchain {
      // Whether to compile from source (vs using prebuilts when able.)
      bool compile_source = 1;
    }
    InstallToolchain install_toolchain = 13;

    // Controls for the call to InstallPackages.
    message InstallPackages {
      // Whether to compile from source (vs using prebuilts when able.)
      bool compile_source = 1;

      // Controls the running of the install packages step.
      RunSpec run_spec = 2;

      // Packages to build, or empty to build all packages.
      repeated PackageInfo packages = 3;

      // Certain builders (e.g., clang-tidy-toolchain) need to build Chrome with
      // goma disabled.
      bool disable_goma = 4;
    }
    reserved 14;
    InstallPackages install_packages = 16;

    message BuildImages {
      // Image types to build.
      repeated ImageType image_types = 1;
    }
    BuildImages build_images = 15;
  }
  Build build = 6;

  message UnitTests {
    // Skipped packages.
    repeated PackageInfo package_blacklist = 4;

    // Controls the running of ebuild tests with possible early exit.
    RunSpec ebuilds_run_spec = 5;

    // Whether to assume the sysroot is empty.
    bool empty_sysroot = 6;
  }
  UnitTests unit_tests = 7;
}

// List of builder configs. Intended to be serialized to / from disk.
message BuilderConfigs {
  repeated BuilderConfig builder_configs = 1;
}