execute

Documentation

Overview

Package execute runs commands.

Index

• func ResultFromEntries(result *rpb.ActionResult, entries []merkletree.Entry)
• type Cmd
  • func (c *Cmd) ActionDigest() digest.Digest
  • func (c *Cmd) ActionResult() (*rpb.ActionResult, bool)
  • func (c *Cmd) AllInputs() []string
  • func (c *Cmd) AllOutputs() []string
  • func (c *Cmd) Digest(ctx context.Context, ds *digest.Store) (digest.Digest, error)
  • func (c *Cmd) InitOutputs()
  • func (c *Cmd) OutputResult() string
  • func (c *Cmd) RecordOutputs(ctx context.Context, ds hashfs.DataSource, now time.Time) error
  • func (c *Cmd) RecordOutputsFromLocal(ctx context.Context, now time.Time) error
  • func (c *Cmd) RecordPreOutputs(ctx context.Context)
  • func (c *Cmd) RemoteArgs() ([]string, error)
  • func (c *Cmd) RemoteFallbackResult() (*rpb.ActionResult, error)
  • func (c *Cmd) SetActionDigest(d digest.Digest)
  • func (c *Cmd) SetActionResult(result *rpb.ActionResult, cached bool)
  • func (c *Cmd) SetOutputResult(msg string)
  • func (c *Cmd) SetRemoteFallbackResult(result *rpb.ActionResult, err error)
  • func (c *Cmd) Stderr() []byte
  • func (c *Cmd) StderrWriter() *bytes.Buffer
  • func (c *Cmd) Stdout() []byte
  • func (c *Cmd) StdoutWriter() *bytes.Buffer
  • func (c *Cmd) String() string
• type Executor
• type ExitError
  • func (e ExitError) Error() string
• type FileTrace
• type REProxyConfig
  • func (c *REProxyConfig) Copy() *REProxyConfig

Functions

func ResultFromEntries

func ResultFromEntries(result *rpb.ActionResult, entries []merkletree.Entry)

ResultFromEntries updates result from entries.

Types

type Cmd

type Cmd struct {
	// ID is used as a unique identifier for this action in logs and tracing.
	// It does not have to be human-readable, so using a UUID is fine.
	ID string

	// Desc is a short, human-readable identifier that is shown to the user when referencing this action in the UI or a log file.
	// Example: "CXX hello.o"
	Desc string

	// ActionName is the name of the rule that generated this action.
	// Example: "cxx" or "link"
	ActionName string

	// Args holds command line arguments.
	Args []string

	// Env specifies the environment of the process.
	Env []string

	// RSPFile is the filename of the response file for the cmd.
	// If set,  Siso will write the RSPFileContent to the file before executing the action, and delete the file after executing the cmd successfully.
	RSPFile string

	// RSPFileContent is the content of the response file for the cmd.
	// The bindings are already expanded.
	RSPFileContent []byte

	// CmdHash is a hash of the command line, which is used to check for changes in the command line since it was last executed.
	CmdHash []byte

	// ExecRoot is an exec root directory of the cmd.
	ExecRoot string

	// Dir specifies the working directory of the cmd,
	// relative to ExecRoot.
	Dir string

	// Inputs are input files of the cmd, relative to ExecRoot.
	// They may be overridden by deps inputs.
	Inputs []string

	// ToolInputs are tool input files of the cmd, relative to ExecRoot.
	// They are specified by the siso config, not overridden by deps.
	// (or inputs would be deps + tool inputs).
	// These are expected to be toolchain input files, not by specified
	// by build deps, nor in deps log.
	ToolInputs []string

	// TreeInputs are precomputed subtree inputs of the cmd.
	TreeInputs []merkletree.TreeEntry

	// If UseSystemInputs is true, inputs may include system includes,
	// but it won't be included in remote exec request and expect such
	// files exist in platform container image.
	UseSystemInput bool

	// Outputs are output files of the cmd, relative to ExecRoot.
	Outputs []string

	// ReconcileOutputdirs are output directories where the cmd would
	// modify files/dirs, invisible to build graph.
	ReconcileOutputdirs []string

	// Deps specifies deps type of the cmd, "gcc", "msvc".
	Deps string

	// Depfile specifies a filename for dep info, relative to ExecRoot.
	Depfile string

	// If Restat is true,
	// output files may be used only for inputs. i.e.
	// output files would not be produced if they would be the same
	// as before by local command execution, so mtime would not be
	// updated, but UpdateTime is updated and IsChagned becomes true.
	Restat bool

	// If RestatContent is true, works as if reset=true for content.
	// i.e. if output content is the same as before, don't update mtime
	// but update UpdateTime and IsChagned to be false.
	RestatContent bool

	// Pure indicates whether the cmd is pure.
	// This is analogue to pure function.
	// For example, a cmd is pure when the inputs/outputs of the cmd are fully specified,
	// and it doesn't access other files during execution.
	// A pure cmd can execute remotely and the outputs can be safely cacheable.
	Pure bool

	// SkipCacheLookup specifies it won't lookup cache in remote execution.
	SkipCacheLookup bool

	// HashFS is a hash fs that the cmd runs on.
	HashFS *hashfs.HashFS

	// Platform is a platform properties for remote execution.
	// e.g. OSFamily: {Linux, Windows}
	Platform map[string]string

	// RemoteWrapper is a wrapper command when the cmd runs on remote execution backend.
	// It can be used to specify a wrapper command/script that exist on the worker.
	RemoteWrapper string

	// RemoteCommand is an argv[0] when the cmd runs on remote execution backend, if not empty.
	// e.g. "python3" for python actions sent from Windows host to Linux worker.
	RemoteCommand string

	// RemoteInputs are the substitute files for remote execution.
	// The key is the filename used in remote execution.
	// The value is the filename on local disk.
	// The file names are relative to ExecRoot.
	RemoteInputs map[string]string

	// REProxyConfig specifies configuration options for using reproxy.
	// If using reproxy, this config takes precedence over options in this struct.
	REProxyConfig *REProxyConfig

	// CanonicalizeDir specifies whether remote execution will canonicalize
	// working directory or not.
	CanonicalizeDir bool

	// DoNotCache specifies whether it won't update cache in remote execution.
	DoNotCache bool

	// Timeout specifies timeout of the cmd.
	Timeout time.Duration

	// ActionSalt is arbitrary bytes used for cache salt.
	ActionSalt []byte

	// FileTrace is a FileTrace info if enabled.
	FileTrace *FileTrace

	// Console indicates the command attaches stdin/stdout/stderr when
	// running.  localexec only.
	Console bool

	// ConsoleOut indicates the command outputs to the console.
	ConsoleOut *atomic.Bool
	// contains filtered or unexported fields
}

Cmd includes all the information required to run a build command.

func (*Cmd) ActionDigest

func (c *Cmd) ActionDigest() digest.Digest

ActionDigest returns action digest of the cmd.

func (*Cmd) ActionResult

func (c *Cmd) ActionResult() (*rpb.ActionResult, bool)

ActionResult returns the action result of the cmd.

func (*Cmd) AllInputs

func (c *Cmd) AllInputs() []string

AllInputs returns all inputs of the cmd.

func (*Cmd) AllOutputs

func (c *Cmd) AllOutputs() []string

AllOutputs returns all outputs of the cmd.

func (*Cmd) Digest

func (c *Cmd) Digest(ctx context.Context, ds *digest.Store) (digest.Digest, error)

Digest computes action digest of the cmd. If ds is nil, then it will reuse the previous calculated digest if any.

func (*Cmd) InitOutputs

func (c *Cmd) InitOutputs()

InitOutputs initializes outputs for the cmd. c.Outputs will be recorded as outputs of the command in hashfs in RecordOutputs or RecordOutputsFromLocal.

func (*Cmd) OutputResult

func (c *Cmd) OutputResult() string

func (*Cmd) RecordOutputs

func (c *Cmd) RecordOutputs(ctx context.Context, ds hashfs.DataSource, now time.Time) error

RecordOutputs records cmd's outputs from action result in hashfs.

func (*Cmd) RecordOutputsFromLocal

func (c *Cmd) RecordOutputsFromLocal(ctx context.Context, now time.Time) error

RecordOutputsFromLocal records cmd's outputs from local disk in hashfs.

func (*Cmd) RecordPreOutputs

func (c *Cmd) RecordPreOutputs(ctx context.Context)

RecordPreOutputs records output entries before running command. hashfs would lazily compute digest of files, so it would cause ERROR_SHARING_VIOLATION when running command on Windows. to prevent the error, compute digest before running step. TODO: use this to enable restat for remote execution.

func (*Cmd) RemoteArgs

func (c *Cmd) RemoteArgs() ([]string, error)

RemoteArgs returns arguments to the remote command. The original args are adjusted with RemoteWrapper, RemoteCommand, Platform.

func (*Cmd) RemoteFallbackResult

func (c *Cmd) RemoteFallbackResult() (*rpb.ActionResult, error)

RemoteFallbackResult returns the remote action failed result and remote error of the cmd, which ended up with local fallback.

func (*Cmd) SetActionDigest

func (c *Cmd) SetActionDigest(d digest.Digest)

SetActionDigest sets action digest. This is used to set the digest provided by Reproxy.

func (*Cmd) SetActionResult

func (c *Cmd) SetActionResult(result *rpb.ActionResult, cached bool)

SetActionResult sets action result to the cmd.

func (*Cmd) SetOutputResult

func (c *Cmd) SetOutputResult(msg string)

func (*Cmd) SetRemoteFallbackResult

func (c *Cmd) SetRemoteFallbackResult(result *rpb.ActionResult, err error)

SetRemoteFallbackResult sets remote action failed result and remote error of the cmd, which ended up with local fallback.

func (*Cmd) Stderr

func (c *Cmd) Stderr() []byte

Stderr returns stderr output of the cmd. Since RBE merges stderr into stdout, we won't get stderr for remote actions. b/149501385 Therefore, we need to be careful how we use stdout/stderr for now. For example, if we use /showIncludes to stderr, it will be on stdout from a remote action.

func (*Cmd) StderrWriter

func (c *Cmd) StderrWriter() *bytes.Buffer

StderrWriter returns a writer set for stderr.

func (*Cmd) Stdout

func (c *Cmd) Stdout() []byte

Stdout returns stdout output of the cmd.

func (*Cmd) StdoutWriter

func (c *Cmd) StdoutWriter() *bytes.Buffer

StdoutWriter returns a writer set for stdout.

func (*Cmd) String

func (c *Cmd) String() string

String returns an ID of the cmd.

type Executor

type Executor interface {
	Run(ctx context.Context, cmd *Cmd) error
}

Executor is an interface to run the cmd.

type ExitError

type ExitError struct {
	ExitCode int
}

ExitError is an error of cmd exit.

func (ExitError) Error

func (e ExitError) Error() string

type FileTrace

type FileTrace struct {
	Inputs  []string
	Outputs []string
}

FileTrace is the results of file trace of the cmd. The paths are relative to ExecRoot of the cmd.

type REProxyConfig

type REProxyConfig struct {
	CanonicalizeWorkingDir bool              `json:"canonicalize_working_dir,omitempty"`
	DownloadOutputs        bool              `json:"download_outputs,omitempty"`
	PreserveSymlinks       bool              `json:"preserve_symlinks,omitempty"`
	ExecStrategy           string            `json:"exec_strategy,omitempty"`
	ExecTimeout            string            `json:"exec_timeout,omitempty"`     // duration format
	ReclientTimeout        string            `json:"reclient_timeout,omitempty"` // duration format
	Inputs                 []string          `json:"inputs,omitempty"`
	ToolchainInputs        []string          `json:"toolchain_inputs,omitempty"`
	Labels                 map[string]string `json:"labels,omitempty"`
	Platform               map[string]string `json:"platform,omitempty"`
	RemoteWrapper          string            `json:"remote_wrapper,omitempty"`
	ServerAddress          string            `json:"server_address,omitempty"`
}

REProxyConfig specifies configuration options for using reproxy.

func (*REProxyConfig) Copy

func (c *REProxyConfig) Copy() *REProxyConfig

Copy returns a deep copy of *REProxyConfig which can be safely mutated. Will return nil if given *REProxyConfig is nil.