builder

Documentation

Index

• Variables
• type ArtifactString
  • func (a ArtifactString) Expand(artifactDir paths.FS) string
  • func (a ArtifactString) Join(strs ...string) ArtifactString
• type ArtifactStrings
  • func (a ArtifactStrings) Expand(artifactDir paths.FS) []string
• type BuildInfo
  • func DefaultBuildInfo() BuildInfo
  • func (b *BuildInfo) IsCrossBuild() bool
• type BuildOutput
• type Cmd
• type CmdSpec
  • func (s *CmdSpec) Expand(artifactDir paths.FS) Cmd
• type CompileParams
• type CompileResult
• type DebugMode
• type Entrypoint
• type GenUserFacingParams
• type GoBuildOutput
  • func (o *GoBuildOutput) GetArtifactDir() paths.FS
  • func (o *GoBuildOutput) GetEntrypoints() []Entrypoint
• type Impl
• type JSBuildOutput
  • func (o *JSBuildOutput) GetArtifactDir() paths.FS
  • func (o *JSBuildOutput) GetEntrypoints() []Entrypoint
• type ParseParams
• type ParseResult
• type RunTestsParams
• type ServiceConfigsParams
• type ServiceConfigsResult
• type TestSpecParams
• type TestSpecResult

Variables

var ErrNoTests = errors.New("no tests found")

ErrNoTests is reported by TestSpec when there aren't any tests to run.

var LocalBuildTags = []string{
	"encore_local",
	"encore_no_gcp", "encore_no_aws", "encore_no_azure",
	"encore_no_datadog", "encore_no_prometheus",
}

Types

type ArtifactString

type ArtifactString string

func (ArtifactString) Expand

func (a ArtifactString) Expand(artifactDir paths.FS) string

func (ArtifactString) Join

func (a ArtifactString) Join(strs ...string) ArtifactString

type ArtifactStrings

type ArtifactStrings []ArtifactString

func (ArtifactStrings) Expand

func (a ArtifactStrings) Expand(artifactDir paths.FS) []string

type BuildInfo

type BuildInfo struct {
	BuildTags          []string
	CgoEnabled         bool
	StaticLink         bool
	DebugMode          DebugMode
	Environ            []string
	GOOS, GOARCH       string
	KeepOutput         bool
	Revision           string
	UncommittedChanges bool

	// MainPkg is the path to the existing main package to use, if any.
	MainPkg option.Option[paths.Pkg]

	// Overrides to explicitly set the GoRoot and EncoreRuntime paths.
	// if not set, they will be inferred from the current executable.
	GoRoot         option.Option[paths.FS]
	EncoreRuntimes option.Option[paths.FS]

	// UseLocalJSRuntime specifies whether to override the installed Encore version
	// with the local JS runtime.
	UseLocalJSRuntime bool

	// Logger allows a custom logger to be used by the various phases of the builder.
	Logger option.Option[zerolog.Logger]
}

func DefaultBuildInfo

func DefaultBuildInfo() BuildInfo

DefaultBuildInfo returns a BuildInfo with default values. It can be modified afterwards.

func (*BuildInfo) IsCrossBuild

func (b *BuildInfo) IsCrossBuild() bool

type BuildOutput

type BuildOutput interface {
	GetArtifactDir() paths.FS
	GetEntrypoints() []Entrypoint
}

type Cmd

type Cmd struct {
	// The command to execute, with arguments.
	Command []string

	// Additional env variables to pass in.
	Env []string
}

Cmd defines a command to run. It's like CmdSpec, but uses expanded paths instead of ArtifactStrings. A CmdSpec can be turned into a Cmd using Expand.

type CmdSpec

type CmdSpec struct {
	// The command to execute. Can either be a filesystem path
	// or a path to a binary (using "${ARTIFACT_DIR}" as a placeholder).
	Command ArtifactStrings `json:"command"`

	// Additional env variables to pass in.
	Env ArtifactStrings `json:"env"`

	// PrioritizedFiles are file paths that should be prioritized when
	// building a streamable docker image.
	PrioritizedFiles ArtifactStrings `json:"prioritized_files"`
}

CmdSpec is a specification for a command to run.

The fields can refer to file paths within the artifact directory using the "${ARTIFACT_DIR}" placeholder (substituted with os.ExpandEnv). This is necessary when building docker images, as otherwise the file paths will refer to the wrong filesystem location in the built docker image.

func (*CmdSpec) Expand

func (s *CmdSpec) Expand(artifactDir paths.FS) Cmd

type CompileParams

type CompileParams struct {
	Build       BuildInfo
	App         *apps.Instance
	Parse       *ParseResult
	OpTracker   *optracker.OpTracker
	Experiments *experiments.Set
	WorkingDir  string

	// Override to explicitly allow the Encore version to be set.
	EncoreVersion option.Option[string]

	Environ []string
}

type CompileResult

type CompileResult struct {
	OS      string
	Arch    string
	Outputs []BuildOutput
}

type DebugMode

type DebugMode string

DebugMode specifies how to compile the application for debugging.

const (
	DebugModeDisabled DebugMode = "disabled"
	DebugModeEnabled  DebugMode = "enabled"
	DebugModeBreak    DebugMode = "break"
)

type Entrypoint

type Entrypoint struct {
	// How to run this entrypoint.
	Cmd CmdSpec `json:"cmd"`
	// Services hosted by this entrypoint.
	Services []string `json:"services"`
	// Gateways hosted by this entrypoint.
	Gateways []string `json:"gateways"`
	// Whether this entrypoint uses the new runtime config.
	UseRuntimeConfigV2 bool `json:"use_runtime_config_v2"`
}

type GenUserFacingParams

type GenUserFacingParams struct {
	Build BuildInfo
	App   *apps.Instance
	Parse *ParseResult
}

type GoBuildOutput

type GoBuildOutput struct {
	// The folder containing the build artifacts.
	// These artifacts are assumed to be relocatable.
	ArtifactDir paths.FS `json:"artifact_dir"`

	// The entrypoints that are part of this build output.
	Entrypoints []Entrypoint `json:"entrypoints"`
}

func (*GoBuildOutput) GetArtifactDir

func (o *GoBuildOutput) GetArtifactDir() paths.FS

func (*GoBuildOutput) GetEntrypoints

func (o *GoBuildOutput) GetEntrypoints() []Entrypoint

type Impl

type Impl interface {
	Parse(context.Context, ParseParams) (*ParseResult, error)
	Compile(context.Context, CompileParams) (*CompileResult, error)
	TestSpec(context.Context, TestSpecParams) (*TestSpecResult, error)
	RunTests(context.Context, RunTestsParams) error
	ServiceConfigs(context.Context, ServiceConfigsParams) (*ServiceConfigsResult, error)
	GenUserFacing(context.Context, GenUserFacingParams) error
	UseNewRuntimeConfig() bool
	NeedsMeta() bool
	Close() error
}

type JSBuildOutput

type JSBuildOutput struct {
	// NodeModules are the node modules that the build artifacts rely on.
	// It's None if the artifacts don't rely on any node modules.
	NodeModules option.Option[paths.FS] `json:"node_modules"`

	// The folder containing the build artifacts.
	// These artifacts are assumed to be relocatable.
	ArtifactDir paths.FS `json:"artifact_dir"`

	// PackageJson is the path to the package.json file to use.
	PackageJson paths.FS `json:"package_json"`

	// The entrypoints that are part of this build output.
	Entrypoints []Entrypoint `json:"entrypoints"`

	// Whether the build output uses the local runtime on the builder,
	// as opposed to installing a published release via e.g. 'npm install'.
	UsesLocalRuntime bool `json:"uses_local_runtime"`
}

func (*JSBuildOutput) GetArtifactDir

func (o *JSBuildOutput) GetArtifactDir() paths.FS

func (*JSBuildOutput) GetEntrypoints

func (o *JSBuildOutput) GetEntrypoints() []Entrypoint

type ParseParams

type ParseParams struct {
	Build       BuildInfo
	App         *apps.Instance
	Experiments *experiments.Set
	WorkingDir  string
	ParseTests  bool
}

type ParseResult

type ParseResult struct {
	Meta *meta.Data
	Data any
}

type RunTestsParams

type RunTestsParams struct {
	Spec *TestSpecResult

	// WorkingDir is the directory to invoke the test command from.
	WorkingDir paths.FS

	// Stdout and Stderr are where to redirect the command output.
	Stdout, Stderr io.Writer
}

type ServiceConfigsParams

type ServiceConfigsParams struct {
	Parse   *ParseResult
	CueMeta *cueutil.Meta
}

type ServiceConfigsResult

type ServiceConfigsResult struct {
	Configs     map[string]string
	ConfigFiles fs.FS
}

type TestSpecParams

type TestSpecParams struct {
	Compile CompileParams

	// Env sets environment variables for "go test".
	Env []string

	// Args sets extra arguments for "go test".
	Args []string
}

type TestSpecResult

type TestSpecResult struct {
	Command string
	Args    []string
	Environ []string

	// For use by the builder when invoking RunTests.
	BuilderData any
}