Documentation
¶
Overview ¶
Package dangv2 evaluates Dagger modules written in Dang with the github.com/vito/dang/v2 library, which parses every Dang language version since 1.0: each module's source is parsed as the version it is written in (ModuleSource.DangVersion). See core/sdk/dang/README.md.
Index ¶
- Constants
- func ContextWithDangVersion(ctx context.Context, version string) (context.Context, error)
- func DeclaresEntrypointSources(ctx context.Context, dir string, dangVersion string) (bool, error)
- func DefaultModuleDangVersion(engineVersion string) dang.Version
- func EntrypointModuleTypes(ctx context.Context, deps *core.SchemaBuilder, ...) (inst dagql.ObjectResult[*core.Module], rerr error)
- func EntrypointPrebuildFile(ctx context.Context, mod dagql.ObjectResult[*core.Module], ...) (file dagql.ObjectResult[*core.File], declared bool, rerr error)
- func EntrypointRuntimeImage(ctx context.Context, mod dagql.ObjectResult[*core.Module], ...) (image dagql.ObjectResult[*core.Container], declared bool, rerr error)
- func EntrypointSources(ctx context.Context, src *core.ModuleSource, ...) (dagql.ObjectResult[*core.Directory], error)
- func NewEntrypointRuntime(deps *core.SchemaBuilder, source dagql.ObjectResult[*core.ModuleSource]) core.ModuleRuntime
- type Impl
- type Versions
- func DefaultEntrypointVersions() Versions
- func DefaultModuleVersions(engineVersion string) Versions
- func ResolveEntrypointVersions(ctx context.Context, configPath string, data []byte) (Versions, error)
- func ResolveModuleVersions(ctx context.Context, configPath string, data []byte, engineVersion string) (Versions, error)
- func ResolveModuleVersionsWithOverride(ctx context.Context, configPath string, data []byte, ...) (Versions, error)
Constants ¶
const ConfigFilename = "dang.toml"
ConfigFilename is the Dang project file that declares the versions a Dang module is written against.
const DefaultEntrypointEngineVersion = "v1.0.0-beta.25"
DefaultEntrypointEngineVersion is the engine version of a Dang module entrypoint whose dang.toml declares no Dagger version, or that has no dang.toml at all.
Entrypoints written before the version could be declared were served at whatever engine ran them, v1.0.0-beta.16 to v1.0.0-beta.25: the v1 API, Dang 2.1 and the naming rules from before the cut at engine.IdentifierCasingVersion (v1.0.0-beta.26). This is the last of those releases, so an entrypoint keeps the API they shipped, including what the releases from engine.PrereleaseViewsVersion on added (they have views of their own), without the renames. It is pinned and must NOT follow engine.Version: an entrypoint that declares nothing would otherwise change meaning with every engine release.
const EntrypointPrebuildMember = "prebuild"
EntrypointPrebuildMember is the optional entrypoint member that returns the file every call of the module builds on, such as the module's compiled binary. The engine calls it without arguments for its own calls, and with a platform, as a string such as "linux/arm64", for the calls of an engine of another platform, as an engine image of that platform ships: a member that takes no platform declares no file for another. Since the file doesn't depend on a call, the engine can build it ahead of the module's first call, and a call that builds on the same file then finds it built or joins its build.
const EntrypointRuntimeImageMember = "runtimeImage"
EntrypointRuntimeImageMember is the optional entrypoint member that returns the image every call of the module runs its process in, which the call starts its container from. The engine calls it as it calls EntrypointPrebuildMember, with a platform for another platform's engine. What a fresh engine fetches before the module's first call, such as an engine image pre-warms, is then read from the module, not from its entrypoint's text.
const EntrypointSourcesMember = "sources"
EntrypointSourcesMember is the optional entrypoint member that returns the files the module builds from. Declaring it selects the entrypoint contract in which types and call receive no workspace.
Variables ¶
This section is empty.
Functions ¶
func ContextWithDangVersion ¶
ContextWithDangVersion sets the Dang version of a module's source, version as ModuleSource.DangVersion holds it (empty: Dang's own default).
func DeclaresEntrypointSources ¶
DeclaresEntrypointSources reports whether a type that implements ModuleEntrypoint in the top-level Dang files of dir declares a public sources member. A comment, a string, a private member or a member of another type does not count. A file that does not parse declares nothing, so its error surfaces when the entrypoint runs. dangVersion is the Dang version the files are written in (ModuleSource.DangVersion).
func DefaultModuleDangVersion ¶
DefaultModuleDangVersion is the Dang version of a Dang SDK module (one that is not a manifest v2 entrypoint) at engine version engineVersion when no dang.toml declares one.
Modules written for an engine before engine.MinimumDangV2ModuleVersion were evaluated with the Dang v1 line, so their source is Dang 1.0 (dang.Version1_0). Later modules are not pinned: the zero Version, which leaves the version to Dang, i.e. dang.CurrentVersion without a dang.toml and dang.DefaultVersion with one that declares none, as they always were.
func EntrypointModuleTypes ¶
func EntrypointModuleTypes( ctx context.Context, deps *core.SchemaBuilder, src dagql.ObjectResult[*core.ModuleSource], moduleContext dagql.ObjectResult[*core.Module], ) (inst dagql.ObjectResult[*core.Module], rerr error)
EntrypointModuleTypes calls types on a built-in Dang module entrypoint.
func EntrypointPrebuildFile ¶
func EntrypointPrebuildFile( ctx context.Context, mod dagql.ObjectResult[*core.Module], platform *core.Platform, ) (file dagql.ObjectResult[*core.File], declared bool, rerr error)
EntrypointPrebuildFile returns the file of mod's built-in Dang module entrypoint's prebuild member, not yet built, or false when the entrypoint declares no such member. The entrypoint runs as the module's calls see it: currentModule is mod.
func EntrypointRuntimeImage ¶
func EntrypointRuntimeImage( ctx context.Context, mod dagql.ObjectResult[*core.Module], platform *core.Platform, ) (image dagql.ObjectResult[*core.Container], declared bool, rerr error)
EntrypointRuntimeImage returns the container of mod's built-in Dang module entrypoint's runtimeImage member, not yet pulled, or false when the entrypoint declares no such member, as EntrypointPrebuildFile returns its prebuild file.
func EntrypointSources ¶
func EntrypointSources( ctx context.Context, src *core.ModuleSource, entryDir dagql.ObjectResult[*core.Directory], schemaFile dagql.Result[*core.File], workspace dagql.ObjectResult[*core.Workspace], ) (dagql.ObjectResult[*core.Directory], error)
EntrypointSources calls the sources member of the entrypoint in entryDir with workspace and returns the Directory it returns. No module exists yet, so the program runs without currentModule. Its nested client has what a module function has: the Dagger API, and the host only through the workspace it is given.
func NewEntrypointRuntime ¶
func NewEntrypointRuntime( deps *core.SchemaBuilder, source dagql.ObjectResult[*core.ModuleSource], ) core.ModuleRuntime
NewEntrypointRuntime returns the built-in Dang module entrypoint runtime.
Types ¶
type Impl ¶
type Impl struct{}
Impl is the Dang implementation behind the dang SDK.
func (Impl) ModuleTypes ¶
func (Impl) ModuleTypes( ctx context.Context, deps *core.SchemaBuilder, src dagql.ObjectResult[*core.ModuleSource], scopedMod dagql.ObjectResult[*core.Module], ) (inst dagql.ObjectResult[*core.Module], rerr error)
func (Impl) Runtime ¶
func (Impl) Runtime( ctx context.Context, deps *core.SchemaBuilder, source dagql.ObjectResult[*core.ModuleSource], ) (core.ModuleRuntime, error)
type Versions ¶
type Versions struct {
// Engine is the Dagger engine version: the module's engineVersion, which
// selects its API view, naming rules and default caching.
Engine string
// Dang is the Dang language version the module source is parsed as.
Dang dang.Version
// DeclaredEngine is the Dagger version the dang.toml declares, if any.
// Engine is that version unless an API-chain override was supplied.
DeclaredEngine string
// DangDeclared reports whether the dang.toml declares Dang.
DangDeclared bool
}
Versions are the versions a Dang module is written against.
func DefaultEntrypointVersions ¶
func DefaultEntrypointVersions() Versions
DefaultEntrypointVersions are the versions of an entrypoint that no dang.toml governs.
func DefaultModuleVersions ¶
DefaultModuleVersions are the versions of a Dang SDK module at engine version engineVersion that no dang.toml governs.
func ResolveEntrypointVersions ¶
func ResolveEntrypointVersions(ctx context.Context, configPath string, data []byte) (Versions, error)
ResolveEntrypointVersions reads the versions of a Dang module entrypoint from the dang.toml that governs it, data, at configPath (used in errors). Nil data means no dang.toml governs the entrypoint.
A Dagger import's `dagger = "vX.Y.Z"` is the engine version. Without one (no dang.toml, no Dagger import, or `dagger = true`), the engine version is DefaultEntrypointEngineVersion. `dang = "X.Y"` is the Dang version. Without one, the Dang version is dang.DefaultVersion, as Dang reads a dang.toml without the key; an entrypoint without a dang.toml gets the same, so that it does not follow dang.CurrentVersion forward either.
A declared engine version must be one this engine can serve, checked as a dagger.json engineVersion is: not older than engine.MinimumModuleVersion, and no later base version than engine.Version's. A later prerelease of the engine's base version, or the release itself, is accepted and served the engine's own view (engine.ModuleAPIViewVersion caps it).
func ResolveModuleVersions ¶
func ResolveModuleVersions(ctx context.Context, configPath string, data []byte, engineVersion string) (Versions, error)
ResolveModuleVersions reads the versions of a Dang SDK module from the dang.toml that governs its source, data, at configPath (used in errors). Nil data means no dang.toml governs it. engineVersion is the module's engineVersion as its manifest declares it (dagger.json or dagger-module.toml).
The dang.toml wins: a Dagger import's `dagger = "vX.Y.Z"` is the engine version, whatever the manifest says. Without one (no dang.toml, no Dagger import, or `dagger = true`) the engine version is the manifest's, as the Dang CLI reads `dagger = true`. `dang = "X.Y"` is the Dang version; without one, it is DefaultModuleDangVersion of the resulting engine version, or the version Dang picks for the source on its own.
A declared engine version must be one this engine can serve, as an engineVersion must.
func ResolveModuleVersionsWithOverride ¶
func ResolveModuleVersionsWithOverride(ctx context.Context, configPath string, data []byte, engineVersion, override string) (Versions, error)
ResolveModuleVersionsWithOverride resolves the same declarations, then applies an explicit API-chain engine version before choosing an undeclared grammar's default. The override is not compatibility-checked here: withEngineVersion can also be used to write a requirement for a newer engine without loading code.
func (Versions) DangString ¶
DangString is the Dang version as dang.toml writes it, e.g. "2.1".
Source Files