go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/cipkg/core/derivation.proto (about)

     1  // Copyright 2023 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  syntax = "proto3";
    16  
    17  option go_package = "go.chromium.org/luci/cipkg/core";
    18  
    19  // Derivation is the atomic step transformed from different types of actions. It
    20  // should contain all information used during the execution in its definition.
    21  // NOTE: ${out} enviroment variable is not part of the derivation. We can't
    22  // determine the output directory before we have a deterministic derivation so
    23  // it has to be excluded from derivation to avoid self-reference.
    24  message Derivation {
    25    // Name is the name of the derivation's output and serves ONLY as an
    26    // indicator of its output.
    27    // The name shouldn't include version of the package and should represents
    28    // its content (e.g. cpython3, curl, ninja), NOT the action taken place
    29    // (e.g. build_cpython3, build_curl, build_ninja).
    30    string name = 1;
    31  
    32    // Platform is a textual description of the platform in which this Derivation
    33    // should be performed, and serves ONLY as an indicator of implicit
    34    // environmental contamination of the output of the derivation.
    35    // Actions should relies on cipkg/base/actions.ActionProcessor to populate
    36    // this field appropriately.
    37    string platform = 2;
    38  
    39    // Args are the `argv` vector of the derivation when executed.
    40    repeated string args = 3;
    41  
    42    // Env includes all the environment variables for the execution isolated from
    43    // host.
    44    // NOTE: ${out} is not included here but will be presented in the environment
    45    // during execution.
    46    repeated string env = 4;
    47  
    48    // Inputs are ids of all packages referred by this derivation.
    49    // It depends on the package manager to ensure packages represented by the
    50    // derivation IDs will be available before execution.
    51    // Ideally derivation should only be able to access derivations listed in the
    52    // inputs. Executor may lock down the runtime environment to prevent the
    53    // derivation from accessing any resource other than those listed in the
    54    // future.
    55    repeated string inputs = 5;
    56  
    57    // fixed_output, if set, represents the content of the output. ID will be
    58    // generated based on fixed_output exclusively.
    59    // WARNING: Using fixed_output means shifting away the responsibility for
    60    // detecting any change from derivation. This should be rarely touched and
    61    // most of its use cases have a builtin implementation to take care of the
    62    // generated fixed_output value. Any use of it outside the builtin modules
    63    // are strongly discouraged. YOU HAVE BEEN WARNED.
    64    string fixed_output = 6;
    65  }