diff --git a/docs/reference/README.md b/docs/reference/README.md index 78ff3c71..e8c56b53 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -16,10 +16,13 @@ - [azure/storage](./azure/storage.md) - - - [bats](./bats.md) - - - [dagger](./dagger/README.md) - Dagger core types -- [dagger/engine](./dagger/engine.md) - - - [dagger/op](./dagger/op.md) - op: low-level operations for Dagger processing pipelines - [docker](./docker/README.md) - Docker container operations - [docker/compose](./docker/compose.md) - Docker-compose operations +- [europa/dagger](./europa/dagger/README.md) - The Dagger API. +- [europa/dagger/engine](./europa/dagger/engine/README.md) - - +- [europa/dagger/engine/spec](./europa/dagger/engine/spec/README.md) - Placeholder package, to keep docs generating tool happy. +- [europa/dagger/engine/spec/engine](./europa/dagger/engine/spec/engine.md) - - - [gcp](./gcp/README.md) - Google Cloud Platform - [gcp/cloudrun](./gcp/cloudrun.md) - - - [gcp/gcr](./gcp/gcr.md) - Google Container Registry diff --git a/docs/reference/europa/dagger/README.md b/docs/reference/europa/dagger/README.md new file mode 100644 index 00000000..82a37e3a --- /dev/null +++ b/docs/reference/europa/dagger/README.md @@ -0,0 +1,95 @@ +--- +sidebar_label: dagger +--- + +# alpha.dagger.io/europa/dagger + +The Dagger API. + +```cue +import "alpha.dagger.io/europa/dagger" +``` + +## dagger.#DAG + +A special kind of program which `dagger` can execute. + +### dagger.#DAG Inputs + +_No input._ + +### dagger.#DAG Outputs + +_No output._ + +## dagger.#FS + +A reference to a filesystem tree. For example: - The root filesystem of a container - A source code repository - A directory containing binary artifacts Rule of thumb: if it fits in a tar archive, it fits in a #FS. + +### dagger.#FS Inputs + +_No input._ + +### dagger.#FS Outputs + +_No output._ + +## dagger.#Plan + +A deployment plan executed by `dagger up` + +### dagger.#Plan Inputs + +_No input._ + +### dagger.#Plan Outputs + +_No output._ + +## dagger.#Secret + +A reference to an external secret, for example: - A password - A SSH private key - An API token Secrets are never merged in the Cue tree. They can only be used by a special filesystem mount designed to minimize leak risk. + +### dagger.#Secret Inputs + +_No input._ + +### dagger.#Secret Outputs + +_No output._ + +## dagger.#Service + +A reference to a network service endpoint, for example: - A TCP or UDP port - A unix socket - An HTTPS endpoint + +### dagger.#Service Inputs + +_No input._ + +### dagger.#Service Outputs + +_No output._ + +## dagger.#Stream + +A reference to a stream of bytes, for example: - The standard output or error stream of a command - The standard input stream of a command - The contents of a file or named pipe + +### dagger.#Stream Inputs + +_No input._ + +### dagger.#Stream Outputs + +_No output._ + +## dagger.#Subdir + +Select a subdirectory from a filesystem tree + +### dagger.#Subdir Inputs + +_No input._ + +### dagger.#Subdir Outputs + +_No output._ diff --git a/docs/reference/europa/dagger/engine/README.md b/docs/reference/europa/dagger/engine/README.md new file mode 100644 index 00000000..6bb38f9c --- /dev/null +++ b/docs/reference/europa/dagger/engine/README.md @@ -0,0 +1,91 @@ +--- +sidebar_label: engine +--- + +# alpha.dagger.io/europa/dagger/engine + +```cue +import "alpha.dagger.io/europa/dagger/engine" +``` + +## engine.#Context + +### engine.#Context Inputs + +_No input._ + +### engine.#Context Outputs + +_No output._ + +## engine.#FS + +A reference to a filesystem tree. For example: - The root filesystem of a container - A source code repository - A directory containing binary artifacts Rule of thumb: if it fits in a tar archive, it fits in a #FS. + +### engine.#FS Inputs + +_No input._ + +### engine.#FS Outputs + +_No output._ + +## engine.#ImageConfig + +Container image config. See [OCI](https://www.opencontainers.org/). Spec left open on purpose to account for additional fields. [Image Spec](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/config.go) [Docker Superset](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/dockerfile2llb/image.go) + +### engine.#ImageConfig Inputs + +_No input._ + +### engine.#ImageConfig Outputs + +_No output._ + +## engine.#Plan + +A deployment plan executed by `dagger up` + +### engine.#Plan Inputs + +_No input._ + +### engine.#Plan Outputs + +_No output._ + +## engine.#Pull + +Download a container image from a remote repository + +### engine.#Pull Inputs + +_No input._ + +### engine.#Pull Outputs + +_No output._ + +## engine.#Secret + +A reference to an external secret, for example: - A password - A SSH private key - An API token Secrets are never merged in the Cue tree. They can only be used by a special filesystem mount designed to minimize leak risk. + +### engine.#Secret Inputs + +_No input._ + +### engine.#Secret Outputs + +_No output._ + +## engine.#Service + +A reference to a network service endpoint, for example: - A TCP or UDP port - A unix or npipe socket - An HTTPS endpoint + +### engine.#Service Inputs + +_No input._ + +### engine.#Service Outputs + +_No output._ diff --git a/docs/reference/europa/dagger/engine/spec/README.md b/docs/reference/europa/dagger/engine/spec/README.md new file mode 100644 index 00000000..16a956c6 --- /dev/null +++ b/docs/reference/europa/dagger/engine/spec/README.md @@ -0,0 +1,11 @@ +--- +sidebar_label: spec +--- + +# alpha.dagger.io/europa/dagger/engine/spec + +Placeholder package, to keep docs generating tool happy. + +```cue +import "alpha.dagger.io/europa/dagger/engine/spec" +``` diff --git a/docs/reference/europa/dagger/engine/spec/engine.md b/docs/reference/europa/dagger/engine/spec/engine.md new file mode 100644 index 00000000..7a5e390b --- /dev/null +++ b/docs/reference/europa/dagger/engine/spec/engine.md @@ -0,0 +1,261 @@ +--- +sidebar_label: engine +--- + +# alpha.dagger.io/europa/dagger/engine/spec/engine + +```cue +import "alpha.dagger.io/europa/dagger/engine/spec/engine" +``` + +## engine.#Build + +Build a container image using buildkit + +### engine.#Build Inputs + +_No input._ + +### engine.#Build Outputs + +_No output._ + +## engine.#CacheDir + +A (best effort) persistent cache dir + +### engine.#CacheDir Inputs + +_No input._ + +### engine.#CacheDir Outputs + +_No output._ + +## engine.#Context + +### engine.#Context Inputs + +_No input._ + +### engine.#Context Outputs + +_No output._ + +## engine.#Copy + +### engine.#Copy Inputs + +_No input._ + +### engine.#Copy Outputs + +_No output._ + +## engine.#CopyInfo + +### engine.#CopyInfo Inputs + +_No input._ + +### engine.#CopyInfo Outputs + +_No output._ + +## engine.#Exec + +Execute a command in a container + +### engine.#Exec Inputs + +_No input._ + +### engine.#Exec Outputs + +_No output._ + +## engine.#FS + +A reference to a filesystem tree. For example: - The root filesystem of a container - A source code repository - A directory containing binary artifacts Rule of thumb: if it fits in a tar archive, it fits in a #FS. A filesystem state + +### engine.#FS Inputs + +_No input._ + +### engine.#FS Outputs + +_No output._ + +## engine.#GitPull + +Pull a directory from a git remote + +### engine.#GitPull Inputs + +_No input._ + +### engine.#GitPull Outputs + +_No output._ + +## engine.#GitPush + +Push a directory to a git remote + +### engine.#GitPush Inputs + +_No input._ + +### engine.#GitPush Outputs + +_No output._ + +## engine.#ImageConfig + +Container image config. See [OCI](https://www.opencontainers.org/). Spec left open on purpose to account for additional fields. [Image Spec](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/config.go) [Docker Superset](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/dockerfile2llb/image.go) Container image config See [OCI](https://www.opencontainers.org) + +### engine.#ImageConfig Inputs + +_No input._ + +### engine.#ImageConfig Outputs + +_No output._ + +## engine.#Merge + +### engine.#Merge Inputs + +_No input._ + +### engine.#Merge Outputs + +_No output._ + +## engine.#Mount + +A transient filesystem mount. + +### engine.#Mount Inputs + +_No input._ + +### engine.#Mount Outputs + +_No output._ + +## engine.#Plan + +A deployment plan executed by `dagger up` + +### engine.#Plan Inputs + +_No input._ + +### engine.#Plan Outputs + +_No output._ + +## engine.#Pull + +Download a container image from a remote repository + +### engine.#Pull Inputs + +_No input._ + +### engine.#Pull Outputs + +_No output._ + +## engine.#Push + +Upload a container image to a remote repository + +### engine.#Push Inputs + +_No input._ + +### engine.#Push Outputs + +_No output._ + +## engine.#ReadFile + +### engine.#ReadFile Inputs + +_No input._ + +### engine.#ReadFile Outputs + +_No output._ + +## engine.#Scratch + +Produce an empty directory + +### engine.#Scratch Inputs + +_No input._ + +### engine.#Scratch Outputs + +_No output._ + +## engine.#Secret + +A reference to an external secret, for example: - A password - A SSH private key - An API token Secrets are never merged in the Cue tree. They can only be used by a special filesystem mount designed to minimize leak risk. An external secret + +### engine.#Secret Inputs + +_No input._ + +### engine.#Secret Outputs + +_No output._ + +## engine.#Service + +A reference to a network service endpoint, for example: - A TCP or UDP port - A unix or npipe socket - An HTTPS endpoint An external network service + +### engine.#Service Inputs + +_No input._ + +### engine.#Service Outputs + +_No output._ + +## engine.#Stream + +A stream of bytes + +### engine.#Stream Inputs + +_No input._ + +### engine.#Stream Outputs + +_No output._ + +## engine.#TempDir + +A temporary directory for command execution + +### engine.#TempDir Inputs + +_No input._ + +### engine.#TempDir Outputs + +_No output._ + +## engine.#WriteFile + +### engine.#WriteFile Inputs + +_No input._ + +### engine.#WriteFile Outputs + +_No output._ diff --git a/europa-universe/README.md b/europa-universe/README.md new file mode 100644 index 00000000..d08a99fa --- /dev/null +++ b/europa-universe/README.md @@ -0,0 +1,76 @@ +# Europa Universe + +## About this directory + +`europa-universe/` is a staging area for the upcoming `universe.dagger.io` package namespace, +which will be shipped as part of the [Europa release](https://github.com/dagger/dagger/issues/1088). + +## What is Universe? + +The Dagger Universe is a catalog of reusable Cue packages, curated by Dagger but possibly authored by third parties. Most packages in Universe contain reusable actions; some may also contain entire configuration templates. + +The import domain for Universe will be `universe.dagger.io`. It will deprecate the current domain `alpha.dagger.io`. + +## Where is the `dagger` package? + +Europa will also introduce a new package for the Dagger Core API: `dagger.io/dagger`. +This is a core package, and is *not* part of Universe (note the import domain). + +The development version of the Europa core API can be imported as [alpha.dagger.io/europa/dagger](../stdlib/europa/dagger). + +## Where is the `dagger/engine` package? + +Europa will also introduce a new package for the Low-Level Dagger Engine API : `dagger.io/dagger/engine`. +This is a core package, and is *not* part of Universe (note the import domain). + +The development version of the Europa Low-Level Engine API can be imported as either: + +* [alpha.dagger.io/europa/dagger/engine/spec/engine](../stdlib/europa/dagger/engine/spec/engine) for the full spec +* [alpha.dagger.io/dagger/europa/engine](../stdlib/europa/dagger/engine) for the implemented subset of the spec + +## Universe vs other packages + +This table compares Dagger core packages, Dagger Universe packages, and the overall CUE package ecosystem. + +| | *Dagger core* | *Dagger Universe* | *CUE ecosystem* | +|----------|--------------|------| +| Import path | `dagger.io` | `universe.dagger.io` | Everything else | +| Purpose | Access core Dagger features | Safely reuse code from the Dagger community | Reuse any CUE code from anyone | +| Author | Dagger team | Dagger community, curated by Dagger | Anyone | +| Release cycle | Released with Dagger engine | Released continuously | No release cycle | +| Size | Small | Large | Very large | +| Growth rate | Grows slowly, with engine features | Grows fast, with Dagger community | Grows even faster, with CUE ecosystem | + + +## Notable packages + +### Docker API + +*Import path: [`universe.dagger.io/docker`](./universe/docker)* + +The `docker` package is a native Cue API for Docker. You can use it to build, run, push and pull Docker containers directly from Cue. + +The Dagger container API defines the following types: + +* `#Image`: a container image +* `#Run`: run a comand in a container +* `#Push`: upload an image to a repository +* `#Pull`: download an image from a repository +* `#Build`: build an image + +### Examples + +*Import path: [`universe.dagger.io/examples`](./examples)* + +This package contains examples of complete Dagger configurations, including the result of following tutorials in the documentations. + +For example, [the todoapp example](./examples/todoapp) corresponds to the [Getting Started tutorial](https://docs.dagger.io/1003/get-started/) + + +## TODO LIST + +* Support native language dev in `docker.#Run` with good DX (Python, Go, Typescript etc.) +* Coding style. When to use verbs vs. nouns? +* Easy file injection API (`container.#Image.files` ?) +* Use file injection instead of inline for `#Command.script` (to avoid hitting arg character limits) +* Organize universe packages in sub-categories? diff --git a/europa/universe/alpine/alpine.cue b/europa-universe/alpine/alpine.cue similarity index 100% rename from europa/universe/alpine/alpine.cue rename to europa-universe/alpine/alpine.cue diff --git a/europa/universe/alpine/tests/simple/simple.cue b/europa-universe/alpine/tests/simple/simple.cue similarity index 100% rename from europa/universe/alpine/tests/simple/simple.cue rename to europa-universe/alpine/tests/simple/simple.cue diff --git a/europa/universe/bash/bash.cue b/europa-universe/bash/bash.cue similarity index 100% rename from europa/universe/bash/bash.cue rename to europa-universe/bash/bash.cue diff --git a/europa/universe/cue.mod/module.cue b/europa-universe/cue.mod/module.cue similarity index 100% rename from europa/universe/cue.mod/module.cue rename to europa-universe/cue.mod/module.cue diff --git a/europa/universe/cue.mod/pkg/dagger.io b/europa-universe/cue.mod/pkg/alpha.dagger.io similarity index 100% rename from europa/universe/cue.mod/pkg/dagger.io rename to europa-universe/cue.mod/pkg/alpha.dagger.io diff --git a/europa-universe/cue.mod/pkg/dagger.io b/europa-universe/cue.mod/pkg/dagger.io new file mode 120000 index 00000000..b455e754 --- /dev/null +++ b/europa-universe/cue.mod/pkg/dagger.io @@ -0,0 +1 @@ +../../../stdlib/europa \ No newline at end of file diff --git a/europa/universe/docker/build.cue b/europa-universe/docker/build.cue similarity index 97% rename from europa/universe/docker/build.cue rename to europa-universe/docker/build.cue index c7ec2128..5a12986a 100644 --- a/europa/universe/docker/build.cue +++ b/europa-universe/docker/build.cue @@ -2,7 +2,7 @@ package docker import ( "dagger.io/dagger" - "dagger.io/dagger/engine" + "dagger.io/dagger/engine/spec/engine" ) // Modular build API for Docker containers diff --git a/europa/universe/docker/docker.cue b/europa-universe/docker/docker.cue similarity index 99% rename from europa/universe/docker/docker.cue rename to europa-universe/docker/docker.cue index 9f88d192..e755cfff 100644 --- a/europa/universe/docker/docker.cue +++ b/europa-universe/docker/docker.cue @@ -4,7 +4,7 @@ package docker import ( "list" - "dagger.io/dagger/engine" + "dagger.io/dagger/engine/spec/engine" "dagger.io/dagger" ) diff --git a/europa/universe/docker/test/bash/bash.cue b/europa-universe/docker/test/bash/bash.cue similarity index 100% rename from europa/universe/docker/test/bash/bash.cue rename to europa-universe/docker/test/bash/bash.cue diff --git a/europa/universe/docker/test/build/build.cue b/europa-universe/docker/test/build/build.cue similarity index 100% rename from europa/universe/docker/test/build/build.cue rename to europa-universe/docker/test/build/build.cue diff --git a/europa/universe/examples/README.md b/europa-universe/examples/README.md similarity index 100% rename from europa/universe/examples/README.md rename to europa-universe/examples/README.md diff --git a/europa/universe/examples/todoapp/base.cue b/europa-universe/examples/todoapp/base.cue similarity index 100% rename from europa/universe/examples/todoapp/base.cue rename to europa-universe/examples/todoapp/base.cue diff --git a/europa/universe/examples/todoapp/dev/dev.cue b/europa-universe/examples/todoapp/dev/dev.cue similarity index 100% rename from europa/universe/examples/todoapp/dev/dev.cue rename to europa-universe/examples/todoapp/dev/dev.cue diff --git a/europa/universe/examples/todoapp/staging/staging.cue b/europa-universe/examples/todoapp/staging/staging.cue similarity index 100% rename from europa/universe/examples/todoapp/staging/staging.cue rename to europa-universe/examples/todoapp/staging/staging.cue diff --git a/europa/fmt.sh b/europa-universe/fmt.sh similarity index 100% rename from europa/fmt.sh rename to europa-universe/fmt.sh diff --git a/europa/universe/git/git.cue b/europa-universe/git/git.cue similarity index 100% rename from europa/universe/git/git.cue rename to europa-universe/git/git.cue diff --git a/europa/universe/netlify/deploy.sh b/europa-universe/netlify/deploy.sh similarity index 100% rename from europa/universe/netlify/deploy.sh rename to europa-universe/netlify/deploy.sh diff --git a/europa/universe/netlify/deploy.sh.cue b/europa-universe/netlify/deploy.sh.cue similarity index 100% rename from europa/universe/netlify/deploy.sh.cue rename to europa-universe/netlify/deploy.sh.cue diff --git a/europa/universe/netlify/netlify.cue b/europa-universe/netlify/netlify.cue similarity index 100% rename from europa/universe/netlify/netlify.cue rename to europa-universe/netlify/netlify.cue diff --git a/europa/universe/netlify/test/simple/simple.cue b/europa-universe/netlify/test/simple/simple.cue similarity index 100% rename from europa/universe/netlify/test/simple/simple.cue rename to europa-universe/netlify/test/simple/simple.cue diff --git a/europa/universe/nginx/nginx.cue b/europa-universe/nginx/nginx.cue similarity index 100% rename from europa/universe/nginx/nginx.cue rename to europa-universe/nginx/nginx.cue diff --git a/europa/universe/python/python.cue b/europa-universe/python/python.cue similarity index 100% rename from europa/universe/python/python.cue rename to europa-universe/python/python.cue diff --git a/europa/search.sh b/europa-universe/search.sh similarity index 100% rename from europa/search.sh rename to europa-universe/search.sh diff --git a/europa/test.sh b/europa-universe/test.sh similarity index 89% rename from europa/test.sh rename to europa-universe/test.sh index 42f1510a..f66509b7 100755 --- a/europa/test.sh +++ b/europa-universe/test.sh @@ -2,9 +2,6 @@ set -e -# Run all tests from universe/ -cd universe - targets=( dagger.io/dagger dagger.io/dagger/engine diff --git a/europa/universe/yarn/tests/simple/simple.cue b/europa-universe/yarn/tests/simple/simple.cue similarity index 100% rename from europa/universe/yarn/tests/simple/simple.cue rename to europa-universe/yarn/tests/simple/simple.cue diff --git a/europa/universe/yarn/tests/testdata/package.json b/europa-universe/yarn/tests/testdata/package.json similarity index 100% rename from europa/universe/yarn/tests/testdata/package.json rename to europa-universe/yarn/tests/testdata/package.json diff --git a/europa/universe/yarn/tests/testdata2/package.json b/europa-universe/yarn/tests/testdata2/package.json similarity index 100% rename from europa/universe/yarn/tests/testdata2/package.json rename to europa-universe/yarn/tests/testdata2/package.json diff --git a/europa/universe/yarn/yarn.cue b/europa-universe/yarn/yarn.cue similarity index 96% rename from europa/universe/yarn/yarn.cue rename to europa-universe/yarn/yarn.cue index 5f1aa879..3b51cf19 100644 --- a/europa/universe/yarn/yarn.cue +++ b/europa-universe/yarn/yarn.cue @@ -5,7 +5,7 @@ import ( "strings" "dagger.io/dagger" - "dagger.io/dagger/engine" // FIXME: should not be needed for common cases + "dagger.io/dagger/engine/spec/engine" "universe.dagger.io/alpine" "universe.dagger.io/bash" diff --git a/europa/README.md b/europa/README.md deleted file mode 100644 index 047c9b25..00000000 --- a/europa/README.md +++ /dev/null @@ -1,120 +0,0 @@ -# Europa release staging - -## About the europa/ directory - -This directory is a staging area for the upcoming Europa release. -It is intended for experimentation and review without requiring long-lived development branches. -Its contents MUST NOT BE USED by `dagger` or its build and release tooling. - -As part of the Europa release, this directory will be removed. - -## About the Europa release - -Europa is the codename of the final major release of Dagger before launch. -For more details on the Europa release, see the [Europa epic](https://github.com/dagger/dagger/issues/1088). - -## New CUE packages - -Europa introduces a new set of CUE packages for developers to use. These new packages are a complete, incompatible replacement for the pre-Europa packages. -* The bad news is that pre-Europa configurations will need to be manually adapted -* The good news is that Europa APIs are much better. So once ported to Europa, configurations will be shorter, easier to maintain, faster and more reliable (at least that's the goal!) - -We intend for Europa to be the last breaking update. Going forward, we will aim for 100% compatibility -whenever possible, and when that is not possible, a migration path that is as automated and painless -as possible. - -Starting with Europa, Dagger separates its Cue packages in two distinct namespaces: *stdlib* and *universe*. - -* The Dagger Universe is a catalog of reusable Cue packages, curated by Dagger but possibly authored by third parties. Most packages in Universe contain reusable actions; some may also contain entire configuration templates. -* The Dagger Stdlib are core packages shipped with the Dagger engine. - -| | *Stdlib* | *Universe* | -|----------|--------------|------| -| Import path | `dagger.io` | `universe.dagger.io` | -| Purpose | Access core Dagger features | Safely reuse code from the community | -| Author | Dagger team | Dagger community, curated by Dagger | -| Release cycle | Released with Dagger engine | Released continuously | -| Size | Small | Large | -| Growth rate | Grows slowly, with engine features | Grows fast, with community | - -### Dagger Core API - -*Import path: [`dagger.io/dagger`](./stdlib/dagger)* - -The Dagger Core API defines core types and utilities for programming Dagger: - -* `#Plan`: a complete configuration executable by `dagger up` -* `#FS` to reference filesystem state -* `#Secret` to (securely) reference external secrets -* `#Service` to reference network service endpoints -* `#Stream` to reference byte streams - -### Low-level engine API - -*Import path: [`dagger.io/dagger/engine`](./stdlib/dagger/engine)* - -`engine` is a low-level API for accessing the raw capabilities of the Dagger Engine. Most developers should use the Dagger Core API instead (`dagger.io/dagger`), but experts and framework developers can target the engine API directly for maximum control. - -This API prioritizes robustness, consistency, and feature completeness. It does NOT prioritize developer convenience or leveraging Cue for composition. - -In Europa, `engine` will deprecate the following implicit API: -* Low-level operations defined in `alpha.dagger.io/dagger/op` -* Imperative DSL to assemble Dockerfile-like arrays as Cue arrays -* Convention to embed pipelines in the Cue lattice with the special nested definition `#up` -* Convention to reference filesystem state from the Cue lattice with `@dagger(artifact)` -* Convention to reference external secrets from the Cue lattice with `@dagger(secret)` -* Convention to reference external network endpoints from the Cue lattive with `@dagger(stream)` -* Convention that some operations (specifically `op.#Local`) are meant to be generated at runtime rather than authored manually. - -### Docker API - -*Import path: [`universe.dagger.io/docker`](./universe/docker)* - -The `docker` package is a native Cue API for Docker. You can use it to build, run, push and pull Docker containers directly from Cue. - -The Dagger container API defines the following types: - -* `#Image`: a container image -* `#Run`: run a comand in a container -* `#Push`: upload an image to a repository -* `#Pull`: download an image from a repository -* `#Build`: build an image - -### Examples - -*Import path: [`universe.dagger.io/examples`](https://github.com/shykes/dagger/tree/llb2/europa/universe/examples)* - -This package contains examples of complete Dagger configurations, including the result of following tutorials in the documentations. - -For example, [the todoapp example](https://github.com/shykes/dagger/tree/llb2/europa/universe/examples/todoapp/deploy) corresponds to the [Getting Started tutorial](https://docs.dagger.io/1003/get-started/) - -### More packages - -More packages are being developed under [universe.dagger.io](./universe) - - -## TODO LIST - -* Support native language dev in `docker.#Run` with good DX (Python, Go, Typescript etc.) -* #Scratch: replace with null #FS? -* Coding style. When to use verbs vs. nouns? -* Resolve registry auth special case (buildkit does not support scoping registry auth) -* Easy file injection API (`container.#Image.files` ?) -* Use file injection instead of inline for `#Command.script` (to avoid hitting arg character limits) -* Organize universe packages in sub-categories? -* Are there runtime limitations in…. - * using hidden fields `_foo` as part of the DAG? - * using `if` statements as part of the DAG? - * using inlined Cue expressions as part of the DAG? -* Do we really need CUE definitions? cue/cmd doesn’t need them… This one is 💣🔥, pure speculation. We must pursue the best DX wherever that may lead us! -* Readability of error messages - * At a minimum don’t make it worse! - * Small improvements are good (eg. -* Make sure we don’t make error messages LESS readable -* Add input.params as proposed by Richard -* Combining all container operations under an opinionated universe.dagger.io/docker package: [good or bad idea](https://github.com/dagger/dagger/pull/1117#discussion_r765178454)? -* [Outstanding questions on proxy features](https://github.com/dagger/dagger/pull/1117#discussion_r765211280) -* [Outstanding questions on #Stream and emulating unix pipes with them](https://github.com/dagger/dagger/pull/1117#discussion_r766145864) -* [Outstanding questions on engine.#Pull and information loss](https://github.com/dagger/dagger/pull/1117#discussion_r765219049) -* [Outstanding questions on global registry auth scope in buildkit](https://github.com/dagger/dagger/pull/1117#discussion_r765963051) -* [Outstanding questions on platform key](https://github.com/dagger/dagger/pull/1117#discussion_r766085610) diff --git a/europa/stdlib/.gitignore b/europa/stdlib/.gitignore deleted file mode 100644 index ff8f4176..00000000 --- a/europa/stdlib/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -node_modules -report.xml diff --git a/europa/stdlib/cue.mod/module.cue b/europa/stdlib/cue.mod/module.cue deleted file mode 100644 index b2757079..00000000 --- a/europa/stdlib/cue.mod/module.cue +++ /dev/null @@ -1 +0,0 @@ -module: "dagger.io" diff --git a/europa/universe/cue.mod/pkg/.gitignore b/europa/universe/cue.mod/pkg/.gitignore deleted file mode 100644 index a572e9ee..00000000 --- a/europa/universe/cue.mod/pkg/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# dagger universe -alpha.dagger.io diff --git a/stdlib/dagger/dagger.cue b/stdlib/dagger/dagger.cue index cd2d0c53..25ac9123 100644 --- a/stdlib/dagger/dagger.cue +++ b/stdlib/dagger/dagger.cue @@ -3,7 +3,7 @@ package dagger import ( "alpha.dagger.io/dagger/op" - "alpha.dagger.io/dagger/engine" + "alpha.dagger.io/europa/dagger/engine" ) // An artifact such as source code checkout, container image, binary archive... diff --git a/stdlib/europa/README.md b/stdlib/europa/README.md new file mode 100644 index 00000000..7eca4a6d --- /dev/null +++ b/stdlib/europa/README.md @@ -0,0 +1,59 @@ +# Europa Core packages + +## About this directory + +`stdlib/europa/` holds the development version of the Core packages for the upcoming [Europa release](https://github.com/dagger/dagger/issues/1088). + +Once Europa is released, `stdlib/europa` will become the new `stdlib/` + +## What are Dagger core packages? + +Dagger core packages are CUE packages released alongside the Dagger engine, to allow developers to access its features. + +### Dagger Core API: `dagger.io/dagger` + +*Development import path: `alpha.dagger.io/europa/dagger`* + +The Dagger Core API defines core types and utilities for programming Dagger: + +* `#Plan`: a complete configuration executable by `dagger up` +* `#FS` to reference filesystem state +* `#Secret` to (securely) reference external secrets +* `#Service` to reference network service endpoints +* `#Stream` to reference byte streams + +### Low-level Engine API: `dagger.io/dagger/engine` + +* *Development import path (implemented subset): `alpha.dagger.io/europa/dagger/engine`* +* *Development importa pth (full spec): `alpha.dagger.io/dagger/europa/dagger/engine/spec/engine`* + +`engine` is a low-level API for accessing the raw capabilities of the Dagger Engine. Most developers should use the Dagger Core API instead (`dagger.io/dagger`), but experts and framework developers can target the engine API directly for maximum control. + +This API prioritizes robustness, consistency, and feature completeness. It does NOT prioritize developer convenience or leveraging Cue for composition. + +In Europa, `engine` will deprecate the following implicit API: +* Low-level operations defined in `alpha.dagger.io/dagger/op` +* Imperative DSL to assemble Dockerfile-like arrays as Cue arrays +* Convention to embed pipelines in the Cue lattice with the special nested definition `#up` +* Convention to reference filesystem state from the Cue lattice with `@dagger(artifact)` +* Convention to reference external secrets from the Cue lattice with `@dagger(secret)` +* Convention to reference external network endpoints from the Cue lattive with `@dagger(stream)` +* Convention that some operations (specifically `op.#Local`) are meant to be generated at runtime rather than authored manually. + +## TODO LIST + +* #Scratch: replace with null #FS? +* Resolve registry auth special case (buildkit does not support scoping registry auth) +* Are there runtime limitations in…. + * using hidden fields `_foo` as part of the DAG? + * using `if` statements as part of the DAG? + * using inlined Cue expressions as part of the DAG? +* Readability of error messages + * At a minimum don’t make it worse! + * Small improvements are good (eg. +* Make sure we don’t make error messages LESS readable +* [Outstanding questions on proxy features](https://github.com/dagger/dagger/pull/1117#discussion_r765211280) +* [Outstanding questions on #Stream and emulating unix pipes with them](https://github.com/dagger/dagger/pull/1117#discussion_r766145864) +* [Outstanding questions on engine.#Pull and information loss](https://github.com/dagger/dagger/pull/1117#discussion_r765219049) +* [Outstanding questions on global registry auth scope in buildkit](https://github.com/dagger/dagger/pull/1117#discussion_r765963051) +* [Outstanding questions on platform key](https://github.com/dagger/dagger/pull/1117#discussion_r766085610) diff --git a/stdlib/dagger/engine/image.cue b/stdlib/europa/dagger/engine/image.cue similarity index 93% rename from stdlib/dagger/engine/image.cue rename to stdlib/europa/dagger/engine/image.cue index 5f22bd02..5aa801bd 100644 --- a/stdlib/dagger/engine/image.cue +++ b/stdlib/europa/dagger/engine/image.cue @@ -9,7 +9,7 @@ package engine // - "index.docker.io/dagger:latest@sha256:a89cb097693dd354de598d279c304a1c73ee550fbfff6d9ee515568e0c749cfe" #Ref: string -// Container image config. See [OCI](https://opencontainers.org/). +// Container image config. See [OCI](https://www.opencontainers.org/). // Spec left open on purpose to account for additional fields. // [Image Spec](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/config.go) // [Docker Superset](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/dockerfile2llb/image.go) diff --git a/stdlib/dagger/engine/plan.cue b/stdlib/europa/dagger/engine/plan.cue similarity index 100% rename from stdlib/dagger/engine/plan.cue rename to stdlib/europa/dagger/engine/plan.cue diff --git a/europa/stdlib/dagger/engine/exec.cue b/stdlib/europa/dagger/engine/spec/engine/exec.cue similarity index 100% rename from europa/stdlib/dagger/engine/exec.cue rename to stdlib/europa/dagger/engine/spec/engine/exec.cue diff --git a/europa/stdlib/dagger/engine/fs.cue b/stdlib/europa/dagger/engine/spec/engine/fs.cue similarity index 100% rename from europa/stdlib/dagger/engine/fs.cue rename to stdlib/europa/dagger/engine/spec/engine/fs.cue diff --git a/europa/stdlib/dagger/engine/git.cue b/stdlib/europa/dagger/engine/spec/engine/git.cue similarity index 100% rename from europa/stdlib/dagger/engine/git.cue rename to stdlib/europa/dagger/engine/spec/engine/git.cue diff --git a/europa/stdlib/dagger/engine/image.cue b/stdlib/europa/dagger/engine/spec/engine/image.cue similarity index 97% rename from europa/stdlib/dagger/engine/image.cue rename to stdlib/europa/dagger/engine/spec/engine/image.cue index 3acfeff0..be8c1a37 100644 --- a/europa/stdlib/dagger/engine/image.cue +++ b/stdlib/europa/dagger/engine/spec/engine/image.cue @@ -1,7 +1,7 @@ package engine // Container image config -// See https://opencontainers.org +// See [OCI](https://www.opencontainers.org) #ImageConfig: { env?: [...string] user?: string diff --git a/europa/stdlib/dagger/engine/secret.cue b/stdlib/europa/dagger/engine/spec/engine/secret.cue similarity index 100% rename from europa/stdlib/dagger/engine/secret.cue rename to stdlib/europa/dagger/engine/spec/engine/secret.cue diff --git a/europa/stdlib/dagger/engine/service.cue b/stdlib/europa/dagger/engine/spec/engine/service.cue similarity index 100% rename from europa/stdlib/dagger/engine/service.cue rename to stdlib/europa/dagger/engine/spec/engine/service.cue diff --git a/europa/stdlib/dagger/engine/stream.cue b/stdlib/europa/dagger/engine/spec/engine/stream.cue similarity index 100% rename from europa/stdlib/dagger/engine/stream.cue rename to stdlib/europa/dagger/engine/spec/engine/stream.cue diff --git a/stdlib/europa/dagger/engine/spec/spec.cue b/stdlib/europa/dagger/engine/spec/spec.cue new file mode 100644 index 00000000..3bee3f87 --- /dev/null +++ b/stdlib/europa/dagger/engine/spec/spec.cue @@ -0,0 +1,2 @@ +// Placeholder package, to keep docs generating tool happy. +package spec diff --git a/stdlib/dagger/engine/types.cue b/stdlib/europa/dagger/engine/types.cue similarity index 100% rename from stdlib/dagger/engine/types.cue rename to stdlib/europa/dagger/engine/types.cue diff --git a/europa/stdlib/dagger/plan.cue b/stdlib/europa/dagger/plan.cue similarity index 100% rename from europa/stdlib/dagger/plan.cue rename to stdlib/europa/dagger/plan.cue diff --git a/europa/stdlib/dagger/types.cue b/stdlib/europa/dagger/types.cue similarity index 95% rename from europa/stdlib/dagger/types.cue rename to stdlib/europa/dagger/types.cue index c6b95779..e71790df 100644 --- a/europa/stdlib/dagger/types.cue +++ b/stdlib/europa/dagger/types.cue @@ -1,7 +1,7 @@ package dagger import ( - "dagger.io/dagger/engine" + "alpha.dagger.io/europa/dagger/engine/spec/engine" ) // A reference to a filesystem tree. diff --git a/europa/stdlib/dagger/utils.cue b/stdlib/europa/dagger/utils.cue similarity index 86% rename from europa/stdlib/dagger/utils.cue rename to stdlib/europa/dagger/utils.cue index e90366e6..29adf65b 100644 --- a/europa/stdlib/dagger/utils.cue +++ b/stdlib/europa/dagger/utils.cue @@ -1,7 +1,7 @@ package dagger import ( - "dagger.io/dagger/engine" + "alpha.dagger.io/europa/dagger/engine/spec/engine" ) // Select a subdirectory from a filesystem tree diff --git a/stdlib/stdlib.go b/stdlib/stdlib.go index 4abc6d37..bb69da5e 100644 --- a/stdlib/stdlib.go +++ b/stdlib/stdlib.go @@ -14,12 +14,11 @@ import ( var ( // FS contains the filesystem of the stdlib. - //go:embed **/*.cue **/*/*.cue + //go:embed **/*.cue **/*/*.cue europa/dagger/*.cue europa/dagger/engine/*.cue europa/dagger/engine/spec/*.cue europa/dagger/engine/spec/engine/*.cue FS embed.FS ModuleName = "alpha.dagger.io" - PackageName = fmt.Sprintf("%s/dagger", ModuleName) - EnginePackage = fmt.Sprintf("%s/engine", PackageName) + EnginePackage = fmt.Sprintf("%s/europa/dagger/engine", ModuleName) Path = path.Join("cue.mod", "pkg", ModuleName) lockFilePath = path.Join("cue.mod", "dagger.lock") ) diff --git a/tests/plan/hello-europa/main.cue b/tests/plan/hello-europa/main.cue index 466f34f9..4459013a 100644 --- a/tests/plan/hello-europa/main.cue +++ b/tests/plan/hello-europa/main.cue @@ -1,7 +1,7 @@ package main import ( - "alpha.dagger.io/dagger/engine" + "alpha.dagger.io/europa/dagger/engine" "alpha.dagger.io/os" ) diff --git a/tests/tasks/pull/pull.cue b/tests/tasks/pull/pull.cue index d6a58c7b..67ab1aab 100644 --- a/tests/tasks/pull/pull.cue +++ b/tests/tasks/pull/pull.cue @@ -1,7 +1,7 @@ package main import ( - "alpha.dagger.io/dagger/engine" + "alpha.dagger.io/europa/dagger/engine" ) engine.#Plan & {