diff options
author | Florian Klink <flokli@flokli.de> | 2024-01-05T13·32+0200 |
---|---|---|
committer | clbot <clbot@tvl.fyi> | 2024-01-05T16·43+0000 |
commit | 70e40f5ce8735229328fb0bc15becb04e5e6f268 (patch) | |
tree | 1f3e1f45315a8982389a33dad96e255bf7401261 | |
parent | 8e794478bf181b79f54f9a71ff329da5c9c43b29 (diff) |
docs(tvix/build): document requirements for paths and sorting r/7349
Change-Id: I466fac025b9b5b2279a6188fa35cb1f7d8ab7bc5 Reviewed-on: https://cl.tvl.fyi/c/depot/+/10536 Autosubmit: flokli <flokli@flokli.de> Reviewed-by: raitobezarius <tvl@lahfa.xyz> Tested-by: BuildkiteCI
-rw-r--r-- | tvix/build-go/build.pb.go | 16 | ||||
-rw-r--r-- | tvix/build/protos/build.proto | 16 |
2 files changed, 28 insertions, 4 deletions
diff --git a/tvix/build-go/build.pb.go b/tvix/build-go/build.pb.go index acd58b37375c..96fc09d3640f 100644 --- a/tvix/build-go/build.pb.go +++ b/tvix/build-go/build.pb.go @@ -68,7 +68,7 @@ type BuildRequest struct { // time of the build. // As root nodes are content-addressed, no additional signatures are needed // to substitute / make these available in the build environment. - // Inputs are sorted by their names. + // Inputs MUST be sorted by their names. Inputs []*castore_go.Node `protobuf:"bytes,1,rep,name=inputs,proto3" json:"inputs,omitempty"` // The command (and its args) executed as the build script. // In the case of a Nix derivation, this is usually @@ -76,19 +76,26 @@ type BuildRequest struct { CommandArgs []string `protobuf:"bytes,2,rep,name=command_args,json=commandArgs,proto3" json:"command_args,omitempty"` // The working dir of the command, relative to the build root. // "build", in the case of Nix. + // This MUST be a clean relative path, without any ".", "..", or superfluous + // slashes. WorkingDir string `protobuf:"bytes,3,opt,name=working_dir,json=workingDir,proto3" json:"working_dir,omitempty"` // A list of "scratch" paths, relative to the build root. // These will be write-able during the build. // [build, nix/store] in the case of Nix. + // These MUST be clean relative paths, without any ".", "..", or superfluous + // slashes, and sorted. ScratchPaths []string `protobuf:"bytes,4,rep,name=scratch_paths,json=scratchPaths,proto3" json:"scratch_paths,omitempty"` // The path where the castore input nodes will be located at, // "/nix/store" in case of Nix. // Builds might also write into here (Nix builds do that). + // This MUST be a clean relative path, without any ".", "..", or superfluous + // slashes. InputsDir string `protobuf:"bytes,5,opt,name=inputs_dir,json=inputsDir,proto3" json:"inputs_dir,omitempty"` // The list of output paths the build is expected to produce, // relative to the root. // If the path is not produced, the build is considered to have failed. - // Outputs are sorted. + // These MUST be clean relative paths, without any ".", "..", or superfluous + // slashes, and sorted. Outputs []string `protobuf:"bytes,6,rep,name=outputs,proto3" json:"outputs,omitempty"` // The list of environment variables and their values that should be set // inside the build environment. @@ -269,6 +276,7 @@ type BuildRequest_EnvVar struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // name of the environment variable. Must not contain =. Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"` Value []byte `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` } @@ -330,12 +338,16 @@ type BuildRequest_BuildConstraints struct { unknownFields protoimpl.UnknownFields // The system that's needed to execute the build. + // Must not be empty. System string `protobuf:"bytes,1,opt,name=system,proto3" json:"system,omitempty"` // The amount of memory required to be available for the build, in bytes. MinMemory uint64 `protobuf:"varint,2,opt,name=min_memory,json=minMemory,proto3" json:"min_memory,omitempty"` // A list of (absolute) paths that need to be available in the build // environment, like `/dev/kvm`. // This is distinct from the castore nodes in inputs. + // TODO: check if these should be individual constraints instead. + // These MUST be clean absolute paths, without any ".", "..", or superfluous + // slashes, and sorted. AvailableRoPaths []string `protobuf:"bytes,3,rep,name=available_ro_paths,json=availableRoPaths,proto3" json:"available_ro_paths,omitempty"` // Whether the build should be able to access the network, NetworkAccess bool `protobuf:"varint,4,opt,name=network_access,json=networkAccess,proto3" json:"network_access,omitempty"` diff --git a/tvix/build/protos/build.proto b/tvix/build/protos/build.proto index f6c62b877431..733636d2221c 100644 --- a/tvix/build/protos/build.proto +++ b/tvix/build/protos/build.proto @@ -49,7 +49,7 @@ message BuildRequest { // time of the build. // As root nodes are content-addressed, no additional signatures are needed // to substitute / make these available in the build environment. - // Inputs are sorted by their names. + // Inputs MUST be sorted by their names. repeated tvix.castore.v1.Node inputs = 1; // The command (and its args) executed as the build script. @@ -59,22 +59,29 @@ message BuildRequest { // The working dir of the command, relative to the build root. // "build", in the case of Nix. + // This MUST be a clean relative path, without any ".", "..", or superfluous + // slashes. string working_dir = 3; // A list of "scratch" paths, relative to the build root. // These will be write-able during the build. // [build, nix/store] in the case of Nix. + // These MUST be clean relative paths, without any ".", "..", or superfluous + // slashes, and sorted. repeated string scratch_paths = 4; // The path where the castore input nodes will be located at, // "/nix/store" in case of Nix. // Builds might also write into here (Nix builds do that). + // This MUST be a clean relative path, without any ".", "..", or superfluous + // slashes. string inputs_dir = 5; // The list of output paths the build is expected to produce, // relative to the root. // If the path is not produced, the build is considered to have failed. - // Outputs are sorted. + // These MUST be clean relative paths, without any ".", "..", or superfluous + // slashes, and sorted. repeated string outputs = 6; // The list of environment variables and their values that should be set @@ -90,6 +97,7 @@ message BuildRequest { repeated EnvVar environment_vars = 7; message EnvVar { + // name of the environment variable. Must not contain =. string key = 1; bytes value = 2; } @@ -105,6 +113,7 @@ message BuildRequest { // wouldn't be hermetic enough - see the comment around inputs too. message BuildConstraints { // The system that's needed to execute the build. + // Must not be empty. string system = 1; // The amount of memory required to be available for the build, in bytes. @@ -113,6 +122,9 @@ message BuildRequest { // A list of (absolute) paths that need to be available in the build // environment, like `/dev/kvm`. // This is distinct from the castore nodes in inputs. + // TODO: check if these should be individual constraints instead. + // These MUST be clean absolute paths, without any ".", "..", or superfluous + // slashes, and sorted. repeated string available_ro_paths = 3; // Whether the build should be able to access the network, |