buildv1

package module
v0.0.0-...-c80db3f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 19, 2024 License: MIT Imports: 9 Imported by: 0

README

build-go

This directory contains generated golang bindings, both for the tvix-build data models, as well as the gRPC bindings.

They are generated with mg run //tvix/build-go:regenerate. These files end with .pb.go, and are ensured to be up to date by a CI check.

Additionally, code useful when interacting with these data structures (ending just with .go) is provided.

Documentation

Index

Constants

View Source 
const (
	BuildService_DoBuild_FullMethodName = "/tvix.build.v1.BuildService/DoBuild"
)

Variables

View Source 
var BuildService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "tvix.build.v1.BuildService",
	HandlerType: (*BuildServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "DoBuild",
			Handler:    _BuildService_DoBuild_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "tvix/build/protos/rpc_build.proto",
}

BuildService_ServiceDesc is the grpc.ServiceDesc for BuildService service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

View Source 
var File_tvix_build_protos_build_proto protoreflect.FileDescriptor
View Source 
var File_tvix_build_protos_rpc_build_proto protoreflect.FileDescriptor

Functions

func RegisterBuildServiceServer 

func RegisterBuildServiceServer(s grpc.ServiceRegistrar, srv BuildServiceServer)

Types

type Build 

type Build struct {

	// The orginal build request producing the build.
	BuildRequest *BuildRequest `protobuf:"bytes,1,opt,name=build_request,json=buildRequest,proto3" json:"build_request,omitempty"` // <- TODO: define hashing scheme for BuildRequest, refer to it by hash?
	// The outputs that were produced after successfully building.
	// They are sorted by their names.
	Outputs []*castore_go.Node `protobuf:"bytes,2,rep,name=outputs,proto3" json:"outputs,omitempty"`
	// contains filtered or unexported fields
}

A Build is (one possible) outcome of executing a BuildRequest.

func (*Build) Descriptor deprecated 

func (*Build) Descriptor() ([]byte, []int)

Deprecated: Use Build.ProtoReflect.Descriptor instead.

func (*Build) GetBuildRequest 

func (x *Build) GetBuildRequest() *BuildRequest

func (*Build) GetOutputs 

func (x *Build) GetOutputs() []*castore_go.Node

func (*Build) ProtoMessage 

func (*Build) ProtoMessage()

func (*Build) ProtoReflect 

func (x *Build) ProtoReflect() protoreflect.Message

func (*Build) Reset 

func (x *Build) Reset()

func (*Build) String 

func (x *Build) String() string

type BuildRequest 

type BuildRequest struct {

	// The list of all root nodes that should be visible in `inputs_dir` at the
	// 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 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
	// ["/path/to/some-bash/bin/bash", "-e", "/path/to/some/builder.sh"].
	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.
	// 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.
	// This includes both environment vars set inside the derivation, as well as
	// more "ephemeral" ones like NIX_BUILD_CORES, controlled by the `--cores`
	// CLI option of `nix-build`.
	// For now, we consume this as an option when turning a Derivation into a BuildRequest,
	// similar to how Nix has a `--cores` option.
	// We don't want to bleed these very nix-specific sandbox impl details into
	// (dumber) builders if we don't have to.
	// Environment variables are sorted by their keys.
	EnvironmentVars []*BuildRequest_EnvVar `protobuf:"bytes,7,rep,name=environment_vars,json=environmentVars,proto3" json:"environment_vars,omitempty"`
	// A set of constraints that need to be satisfied on a build host before a
	// Build can be started.
	Constraints *BuildRequest_BuildConstraints `protobuf:"bytes,8,opt,name=constraints,proto3" json:"constraints,omitempty"`
	// Additional (small) files and their contents that should be placed into the
	// build environment, but outside inputs_dir.
	// Used for passAsFile and structuredAttrs in Nix.
	AdditionalFiles []*BuildRequest_AdditionalFile `protobuf:"bytes,9,rep,name=additional_files,json=additionalFiles,proto3" json:"additional_files,omitempty"`
	// contains filtered or unexported fields
}

A BuildRequest describes the request of something to be run on the builder. It is distinct from an actual Build that has already happened, or might be currently ongoing.

A BuildRequest can be seen as a more normalized version of a Derivation (parsed from A-Term), "writing out" some of the Nix-internal details about how e.g. environment variables in the build are set.

Nix has some impurities when building a Derivation, for example the --cores option ends up as an environment variable in the build, that's not part of the ATerm.

As of now, we serialize this into the BuildRequest, so builders can stay dumb. This might change in the future.

There's also a big difference when it comes to how inputs are modelled:

  • Nix only uses store path (strings) to describe the inputs. As store paths can be input-addressed, a certain store path can contain different contents (as not all store paths are binary reproducible). This requires that for every input-addressed input, the builder has access to either the input's deriver (and needs to build it) or else a trusted source for the built input. to upload input-addressed paths, requiring the trusted users concept.
  • tvix-build records a list of tvix.castore.v1.Node as inputs. These map from the store path base name to their contents, relieving the builder from having to "trust" any input-addressed paths, contrary to Nix.

While this approach gives a better hermeticity, it has one downside: A BuildRequest can only be sent once the contents of all its inputs are known.

As of now, we're okay to accept this, but it prevents uploading an entirely-non-IFD subgraph of BuildRequests eagerly.

FUTUREWORK: We might be introducing another way to refer to inputs, to support "send all BuildRequest for a nixpkgs eval to a remote builder and put the laptop to sleep" usecases later.

func (*BuildRequest) Descriptor deprecated 

func (*BuildRequest) Descriptor() ([]byte, []int)

Deprecated: Use BuildRequest.ProtoReflect.Descriptor instead.

func (*BuildRequest) GetAdditionalFiles 

func (x *BuildRequest) GetAdditionalFiles() []*BuildRequest_AdditionalFile

func (*BuildRequest) GetCommandArgs 

func (x *BuildRequest) GetCommandArgs() []string

func (*BuildRequest) GetConstraints 

func (x *BuildRequest) GetConstraints() *BuildRequest_BuildConstraints

func (*BuildRequest) GetEnvironmentVars 

func (x *BuildRequest) GetEnvironmentVars() []*BuildRequest_EnvVar

func (*BuildRequest) GetInputs 

func (x *BuildRequest) GetInputs() []*castore_go.Node

func (*BuildRequest) GetInputsDir 

func (x *BuildRequest) GetInputsDir() string

func (*BuildRequest) GetOutputs 

func (x *BuildRequest) GetOutputs() []string

func (*BuildRequest) GetScratchPaths 

func (x *BuildRequest) GetScratchPaths() []string

func (*BuildRequest) GetWorkingDir 

func (x *BuildRequest) GetWorkingDir() string

func (*BuildRequest) ProtoMessage 

func (*BuildRequest) ProtoMessage()

func (*BuildRequest) ProtoReflect 

func (x *BuildRequest) ProtoReflect() protoreflect.Message

func (*BuildRequest) Reset 

func (x *BuildRequest) Reset()

func (*BuildRequest) String 

func (x *BuildRequest) String() string

type BuildRequest_AdditionalFile 

type BuildRequest_AdditionalFile struct {
	Path     string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
	Contents []byte `protobuf:"bytes,2,opt,name=contents,proto3" json:"contents,omitempty"`
	// contains filtered or unexported fields
}

func (*BuildRequest_AdditionalFile) Descriptor deprecated 

func (*BuildRequest_AdditionalFile) Descriptor() ([]byte, []int)

Deprecated: Use BuildRequest_AdditionalFile.ProtoReflect.Descriptor instead.

func (*BuildRequest_AdditionalFile) GetContents 

func (x *BuildRequest_AdditionalFile) GetContents() []byte

func (*BuildRequest_AdditionalFile) GetPath 

func (x *BuildRequest_AdditionalFile) GetPath() string

func (*BuildRequest_AdditionalFile) ProtoMessage 

func (*BuildRequest_AdditionalFile) ProtoMessage()

func (*BuildRequest_AdditionalFile) ProtoReflect 

func (x *BuildRequest_AdditionalFile) ProtoReflect() protoreflect.Message

func (*BuildRequest_AdditionalFile) Reset 

func (x *BuildRequest_AdditionalFile) Reset()

func (*BuildRequest_AdditionalFile) String 

func (x *BuildRequest_AdditionalFile) String() string

type BuildRequest_BuildConstraints 

type BuildRequest_BuildConstraints struct {

	// 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"`
	// Whether to provide a /bin/sh inside the build environment, usually a static bash.
	ProvideBinSh bool `protobuf:"varint,5,opt,name=provide_bin_sh,json=provideBinSh,proto3" json:"provide_bin_sh,omitempty"`
	// contains filtered or unexported fields
}

BuildConstraints represents certain conditions that must be fulfilled inside the build environment to be able to build this. Constraints can be things like required architecture and minimum amount of memory. The required input paths are *not* represented in here, because it wouldn't be hermetic enough - see the comment around inputs too.

func (*BuildRequest_BuildConstraints) Descriptor deprecated 

func (*BuildRequest_BuildConstraints) Descriptor() ([]byte, []int)

Deprecated: Use BuildRequest_BuildConstraints.ProtoReflect.Descriptor instead.

func (*BuildRequest_BuildConstraints) GetAvailableRoPaths 

func (x *BuildRequest_BuildConstraints) GetAvailableRoPaths() []string

func (*BuildRequest_BuildConstraints) GetMinMemory 

func (x *BuildRequest_BuildConstraints) GetMinMemory() uint64

func (*BuildRequest_BuildConstraints) GetNetworkAccess 

func (x *BuildRequest_BuildConstraints) GetNetworkAccess() bool

func (*BuildRequest_BuildConstraints) GetProvideBinSh 

func (x *BuildRequest_BuildConstraints) GetProvideBinSh() bool

func (*BuildRequest_BuildConstraints) GetSystem 

func (x *BuildRequest_BuildConstraints) GetSystem() string

func (*BuildRequest_BuildConstraints) ProtoMessage 

func (*BuildRequest_BuildConstraints) ProtoMessage()

func (*BuildRequest_BuildConstraints) ProtoReflect 

func (x *BuildRequest_BuildConstraints) ProtoReflect() protoreflect.Message

func (*BuildRequest_BuildConstraints) Reset 

func (x *BuildRequest_BuildConstraints) Reset()

func (*BuildRequest_BuildConstraints) String 

func (x *BuildRequest_BuildConstraints) String() string

type BuildRequest_EnvVar 

type BuildRequest_EnvVar struct {

	// 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"`
	// contains filtered or unexported fields
}

func (*BuildRequest_EnvVar) Descriptor deprecated 

func (*BuildRequest_EnvVar) Descriptor() ([]byte, []int)

Deprecated: Use BuildRequest_EnvVar.ProtoReflect.Descriptor instead.

func (*BuildRequest_EnvVar) GetKey 

func (x *BuildRequest_EnvVar) GetKey() string

func (*BuildRequest_EnvVar) GetValue 

func (x *BuildRequest_EnvVar) GetValue() []byte

func (*BuildRequest_EnvVar) ProtoMessage 

func (*BuildRequest_EnvVar) ProtoMessage()

func (*BuildRequest_EnvVar) ProtoReflect 

func (x *BuildRequest_EnvVar) ProtoReflect() protoreflect.Message

func (*BuildRequest_EnvVar) Reset 

func (x *BuildRequest_EnvVar) Reset()

func (*BuildRequest_EnvVar) String 

func (x *BuildRequest_EnvVar) String() string

type BuildServiceClient 

type BuildServiceClient interface {
	DoBuild(ctx context.Context, in *BuildRequest, opts ...grpc.CallOption) (*Build, error)
}

BuildServiceClient is the client API for BuildService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewBuildServiceClient 

func NewBuildServiceClient(cc grpc.ClientConnInterface) BuildServiceClient

type BuildServiceServer 

type BuildServiceServer interface {
	DoBuild(context.Context, *BuildRequest) (*Build, error)
	// contains filtered or unexported methods
}

BuildServiceServer is the server API for BuildService service. All implementations must embed UnimplementedBuildServiceServer for forward compatibility

type UnimplementedBuildServiceServer 

type UnimplementedBuildServiceServer struct {
}

UnimplementedBuildServiceServer must be embedded to have forward compatible implementations.

func (UnimplementedBuildServiceServer) DoBuild 

func (UnimplementedBuildServiceServer) DoBuild(context.Context, *BuildRequest) (*Build, error)

type UnsafeBuildServiceServer 

type UnsafeBuildServiceServer interface {
	// contains filtered or unexported methods
}

UnsafeBuildServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to BuildServiceServer will result in compilation errors.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.