Merge pull request #575 from tjovicic/improve-docs

Improve docs
This commit is contained in:
Andrea Luzzardi 2021-06-07 11:22:29 -07:00 committed by GitHub
commit 29893dcf3d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 53 additions and 31 deletions

View File

@ -19,8 +19,8 @@ don't have to learn a new workflow every time their deployment system changes.
## Learn More
* [Dagger vs. Other Software](docs/vs.md)
* [Dagger Programming Guide](docs/programming.md)
* [Dagger Operator Manual](docs/operator.md)
* [Dagger Programming Guide](docs/guides/programming.md)
* [Dagger Operator Manual](docs/guides/operator.md)
## Download and Install

View File

@ -5,45 +5,45 @@ slug: /programming
# Dagger Programming Guide
## Overview
## Writing your first Dagger plan
1. A developer writes a _plan_ specifying how to deliver their application. Plans are written in the [Cue](https://cuelang.org) data language.
2. Dagger executes plans in isolated _environments_. Each environment has its own configuration and state.
1\. Initialize a Dagger workspace anywhere in your git repository:
## Programming in Cue
`dagger init`
[Cue](https://cuelang.org) is a next-generation data language by Marcel van Lohuizen and the spiritual successor
of GCL, the language used to configure all of Google's infrastructure.
It will create a `.dagger` directory in your current directory with an empty `env` directory inside it:
Cue extends JSON with powerful features:
```bash
.dagger/
└── env
```
- Composition: layering, templating, references
- Correctness: types, schemas
- Developer experience: comments, packages, first-class tooling, builtin functions
- And mucn more.
2\. Create a new environment, for example `staging`:
To get started with Cue, we recommend the following resources:
`dagger new staging`
- [Cuetorials](https://cuetorials.com)
- [Cue playground](https://cuelang.org/play)
```bash
.dagger/
└── env
└── staging
├── plan
└── values.yaml
## Writing your first plan
```
To create a Dagger plan:
3\. Create a new file [Cue](#programming-in-cue) config file in `.dagger/env/staging/plan`, and open it with any text editor or IDE:
1\. Initialize a Dagger workspace anywhere in your git repository.
```bash
.dagger/
└── env
└── staging
├── plan
│   └── staging.cue
└── values.yaml
`dagger init`.
```
2\. Create a new environment.
For example: `dagger new staging`.
3\. Create a new file with the _.cue_ extension in `.dagger/env/staging/plan`, and open it with any text editor or IDE.
For example: `.dagger/env/staging/plan/staging.cue`.
4\. Describe each relay in your plan as a field in the cue configuration.
4\. Describe each [relay](#relays) in your plan as a field in the Cue configuration:
For example:
@ -78,7 +78,7 @@ For more inspiration, see these examples:
5\. Extend your plan with relay definitions from [Dagger
Universe](https://github.com/dagger/dagger/tree/main/stdlib), an encyclopedia of
cue packages curated by the Dagger community.
Cue packages curated by the Dagger community.
6\. If you can't find the relay you need in the Universe, you can simply create your own.
@ -111,8 +111,30 @@ american: #Greeting & {
}
```
## Programming in Cue
[Cue](https://cuelang.org) is a next-generation data language by Marcel van Lohuizen and the spiritual successor
of GCL, the language used to configure all of Google's infrastructure.
Cue extends JSON with powerful features:
- Composition: layering, templating, references
- Correctness: types, schemas
- Developer experience: comments, packages, first-class tooling, builtin functions
- And much more.
To get started with Cue, we recommend the following resources:
- [Cuetorials](https://cuetorials.com)
- [Cue playground](https://cuelang.org/play)
## Concepts
### Overview
1. A developer writes a _plan_ specifying how to deliver their application. Plans are written in the [Cue](https://cuelang.org) data language.
2. Dagger executes plans in isolated _environments_. Each environment has its own configuration and state.
### Plans
A _plan_ specifies, in code, how to deliver a particular application in a particular way.
@ -201,7 +223,7 @@ A relay is typically contained in a [cue definition](https://cuetorials.com/over
For example a relay for a git repository might be defined as `#Repository`.
The processing pipeline is a crucial feature of Dagger. It uses the [LLB](https://github.com/moby/buildkit)
executable format pioneered by the Buildkit project. It allows Dagger components to run
executable format pioneered by the BuildKit project. It allows Dagger components to run
sophisticated pipelines to ingest produce artifacts such as source code, binaries, database exports, etc.
Best of all, LLB pipelines can securely build and run any docker container, effectively making Dagger
scriptable in any language.