Add doc on how to create packages
Signed-off-by: Tihomir Jovicic <tihomir.jovicic.develop@gmail.com>
This commit is contained in:
Tihomir Jovicic
parent
2f2ede4cfc
commit
216686c7ec
134
docs/learn/109-packages.md
Normal file
134
docs/learn/109-packages.md
Normal file
@ -0,0 +1,134 @@
|
|||||||
|
# Dagger 109: creating packages
|
||||||
|
|
||||||
|
This tutorial illustrates how to create new packages, manually distribute them among your applications and contribute to
|
||||||
|
the Dagger stdlib packages.
|
||||||
|
|
||||||
|
## Creating your own package
|
||||||
|
|
||||||
|
### Initializing workspace
|
||||||
|
|
||||||
|
Create an empty directory for your new Dagger workspace:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
mkdir workspace
|
||||||
|
cd workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
As described in the previous tutorials, initialize your Dagger workspace:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dagger init
|
||||||
|
```
|
||||||
|
|
||||||
|
That will create 2 directories: `.dagger` and `cue.mod` where our package will reside:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
.
|
||||||
|
├── cue.mod
|
||||||
|
│ ├── module.cue
|
||||||
|
│ ├── pkg
|
||||||
|
│ └── usr
|
||||||
|
├── .dagger
|
||||||
|
│ └── env
|
||||||
|
```
|
||||||
|
|
||||||
|
### Writing the package
|
||||||
|
|
||||||
|
Now that you've initialized your workspace it's time to write a simple package. Package name usually starts with a
|
||||||
|
domain name (as in Go) followed with a descriptive name. In this example we will use my Github domain name and call our
|
||||||
|
package `echo` because it will print a single line to stdout.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
mkdir -p cue.mod/pkg/github.com/tjovicic/echo
|
||||||
|
```
|
||||||
|
|
||||||
|
Let's write the package logic. It will spin up an alpine container and print out `Hello` to stdout:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
touch cue.mod/pkg/github.com/tjovicic/echo/source.cue
|
||||||
|
```
|
||||||
|
|
||||||
|
```cue title="cue.mod/pkg/github.com/tjovicic/echo/source.cue"
|
||||||
|
package echo
|
||||||
|
|
||||||
|
import (
|
||||||
|
"alpha.dagger.io/alpine"
|
||||||
|
"alpha.dagger.io/os"
|
||||||
|
)
|
||||||
|
|
||||||
|
ctr: os.#Container & {
|
||||||
|
image: alpine.#Image & {
|
||||||
|
package: {
|
||||||
|
bash: "=~5.1"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
command: "echo Hello"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running the package
|
||||||
|
|
||||||
|
Now that you've successfully created a package, let's run it in a new environment. Create a new environment using the
|
||||||
|
new `echo` package.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dagger new staging -p github.com/tjovicic/echo
|
||||||
|
```
|
||||||
|
|
||||||
|
Run it:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dagger up -e staging
|
||||||
|
```
|
||||||
|
|
||||||
|
At the end of the output you should see `Hello` printed out:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
11:09AM INF system | starting buildkit version=v0.8.3
|
||||||
|
WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated
|
||||||
|
WARN[0003] commandConn.CloseRead: commandconn: failed to wait: signal: terminated
|
||||||
|
WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated
|
||||||
|
11:09AM INF ctr | computing
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 0.080 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/main/x86_64/APKINDEX.tar.gz
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 0.612 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/community/x86_64/APKINDEX.tar.gz
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.094 (1/4) Installing ncurses-terminfo-base (6.2_p20210109-r0)
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.149 (2/4) Installing ncurses-libs (6.2_p20210109-r0)
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.273 (3/4) Installing readline (8.1.0-r0)
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.361 (4/4) Installing bash (5.1.0-r0)
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.534 Executing bash-5.1.0-r0.post-install
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.541 Executing busybox-1.32.1-r6.trigger
|
||||||
|
11:09AM INF ctr.#up[0].from | #5 1.554 OK: 8 MiB in 18 packages
|
||||||
|
11:09AM INF ctr | #6 0.110 Hello
|
||||||
|
11:09AM INF ctr | completed duration=5.4s
|
||||||
|
Output Value Description
|
||||||
|
```
|
||||||
|
|
||||||
|
## Manually distributing packages
|
||||||
|
|
||||||
|
You've probably guessed this package isn't tied to just your workspace. You can easily copy/paste it into any number
|
||||||
|
of different workspaces and use it as we've showed above.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
mkdir -p /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo
|
||||||
|
cp ./cue.mod/pkg/github.com/tjovicic/echo/source.cue /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contributing to Dagger stdlib
|
||||||
|
|
||||||
|
Our [stdlib](https://github.com/dagger/dagger/tree/main/stdlib) has many useful packages that you can use.
|
||||||
|
You've probably seen it when you've initialized your workspace:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
.
|
||||||
|
├── cue.mod
|
||||||
|
│ ├── module.cue
|
||||||
|
│ ├── pkg
|
||||||
|
│ │ ├── alpha.dagger.io
|
||||||
|
│ │ └── .gitignore
|
||||||
|
│ └── usr
|
||||||
|
```
|
||||||
|
|
||||||
|
We are still a small community and are constantly looking for new contributors that will work with us improve this
|
||||||
|
amazing project. If you feel like we are missing a package or want to improve an existing one, please start with our
|
||||||
|
[contributing docs](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) and open a PR.
|
||||||
Reference in New Issue
Block a user