diff --git a/docs/current_docs/quickstart/428201-custom-function.mdx b/docs/current_docs/quickstart/428201-custom-function.mdx index a75455ec475..3b8bc402e53 100644 --- a/docs/current_docs/quickstart/428201-custom-function.mdx +++ b/docs/current_docs/quickstart/428201-custom-function.mdx @@ -12,16 +12,14 @@ import TabItem from "@theme/TabItem"; So far, you've been calling individual Dagger Functions using the Dagger CLI. But what if you want to combine multiple Dagger Function calls? -One option is, of course, to stitch together calls using the CLI and a shell script or a Makefile However, this approach is not recommended, because you will typically end up with long and unwieldy CLI commands and shell scripting "glue" that is hard to debug and maintain. +One option is to stitch together calls using the CLI and a shell script or a Makefile However, this approach is not recommended, because you will typically end up with long and unwieldy CLI commands and shell scripting "glue" that is hard to debug and maintain. -A better approach is to create a programmable Dagger Module, which can then call other Dagger Modules and Dagger Functions to achieve the required results. Creating your own Dagger Module enables you to transform your workflows into structured, discrete and composable units with clear inputs and outputs, with all the benefits of using a native programming language. +A better approach is to create one or more Dagger Function(s), which can then call other Dagger Functions to achieve the required results. Creating your own Dagger Function(s) enables you to transform your workflows into structured, discrete and composable units with clear inputs and outputs, with all the benefits of using a native programming language. -By creating your own Dagger Module and installing other modules into it, you can express more complex workflows and operations by reusing modules created by others and connecting them together using the programming language you're most comfortable with. - -To see this in action, create a custom Dagger Module that uses two other Dagger Modules to build your project, add it to a custom container image of your choice, and publish the result to a registry. +To see this in action, create a custom Dagger Function that uses two other Dagger modules to build your project, add it to a custom container image of your choice, and publish the result to a registry. :::note -The steps below assume that you have already [Daggerized the example Go project repository](./822194-daggerize.mdx) by initializing a new Dagger Module and installing the Go builder module as a dependency. If not, complete those steps before proceeding. +The steps below assume that you have already [Daggerized the example Go project repository](./822194-daggerize.mdx) by initializing a new Dagger module and installing the Go builder module as a dependency. If not, complete those steps before proceeding. ::: ### Bootstrap a module template diff --git a/docs/current_docs/quickstart/481052-conclusion.mdx b/docs/current_docs/quickstart/481052-conclusion.mdx index 080e42a8d40..b4c13de1e80 100644 --- a/docs/current_docs/quickstart/481052-conclusion.mdx +++ b/docs/current_docs/quickstart/481052-conclusion.mdx @@ -8,7 +8,7 @@ title: "Conclusion" ## Conclusion -Over the last few pages, this quickstart has walked you through the basics of using Dagger Functions and Dagger Modules. It introduced you to the Dagger CLI and the `dagger call` command, and demonstrated how to use it to call and chain functions together. It also showed you how to create and package a custom Dagger module. +Over the last few pages, this quickstart has walked you through the basics of using Dagger Functions. It introduced you to the Dagger CLI and the `dagger call` command, and demonstrated how to use it to call and chain functions together. It also showed you how to create a custom Dagger Function. Continue your journey with Dagger by visiting the links below: diff --git a/docs/current_docs/quickstart/562821-hello.mdx b/docs/current_docs/quickstart/562821-hello.mdx index 9ebe4b1eeb1..2f1d3851e22 100644 --- a/docs/current_docs/quickstart/562821-hello.mdx +++ b/docs/current_docs/quickstart/562821-hello.mdx @@ -33,8 +33,95 @@ As you can see, Dagger loaded a module directly from its GitHub repository, and If you [inspect the source code of the module](https://github.com/shykes/daggerverse/blob/main/hello/main.go), you'll see a `Hello()` function, written in Go, which prepares a message and returns it as a string. -Note that the function supports arguments - we'll get to that later. - :::info When using `dagger call`, all names (functions, arguments, fields, etc) are converted into a shell-friendly "kebab-case" style. This is why the function named `Hello()` is invoked as `dagger call hello`. ::: + +### List available function arguments + +Dagger Functions, just like regular functions, can accept arguments. Appending the `--help` flag to a `dagger call` command will display a context-sensitive list of supported arguments and sub-commands. + +Inspect the arguments of the `hello` function you called earlier: + +```shell +dagger -m github.com/shykes/daggerverse/hello@v0.1.2 call hello --help +``` + +You should see output that looks like this: + +```shell +Say hello to the world! + +Usage: + dagger call hello [flags] + +Flags: + --figlet-container Container Optional container for running the figlet tool + --giant Encode the message in giant multi-character letters + --greeting string An optional greeting (default is "hello") + --name string An optional name (default is "world") + --shout Make the message uppercase, and add more exclamation + points +``` + +### Call a function with arguments + +Let's pass two string arguments to the `hello` function, from the list above: + +```shell +dagger -m github.com/shykes/daggerverse/hello@v0.1.2 call hello --greeting=bonjour --name=daggernaut +``` + +You should see the following output: + +```shell +bonjour, daggernaut! +``` + +### Use complex types as arguments + +In addition to basic types (string, boolean, integer, array...), Dagger also defines powerful core types which functions can use as arguments: `Directory`, `File`, `Container`, `Service`, `Secret` and others. + +You'll see this in action as you continue through the quickstart, but here's a quick example that demonstrates passing a `Directory` type as argument to a Dagger Function: + +```shell +dagger -m github.com/vikram-dagger/daggerverse/fileutils call tree --dir='https://github.com/dagger/dagger#main:cmd/dagger' +``` + +Here, the `Tree()` function accepts a `Directory` as argument and returns a tree representation of that directory. The directory could be a local directory, or a remote Git reference. In this example, the directory is the `cmd/dagger` sub-directory of Dagger's open-source GitHub repository. + +You should see the following output, which should be the same file listing as [this GitHub page](https://github.com/dagger/dagger/tree/main/cmd/dagger): + +```shell +. +├── call.go +├── cloud.go +├── config.go +├── debug.go +├── engine.go +├── exec_nonunix.go +├── exec_unix.go +├── flags.go +├── functions.go +├── gen.go +├── licenses.go +├── listen.go +├── log.go +├── main.go +├── module.go +├── module_test.go +├── query.go +├── run.go +├── session.go +├── shell.go +├── shell_nounix.go +├── shell_unix.go +├── version.go +└── watch.go + +0 directories, 24 files +``` + +:::tip +All of Dagger's core types, such as `Directory`, `File`, `Container`, `Service`, `Secret`, can be used as arguments by Dagger Functions. These core types are not merely strings referencing local or remote resources; they are actual representations of the corresponding resource states, managed by the Dagger Engine, and passed to and between Dagger Functions like other variables. This feature makes it easy to assemble complex pipelines where container state flows from function to function, in just a few lines of code. +::: diff --git a/docs/current_docs/quickstart/822194-daggerize.mdx b/docs/current_docs/quickstart/822194-daggerize.mdx index 7d8d8f8e0af..80615d3a1a1 100644 --- a/docs/current_docs/quickstart/822194-daggerize.mdx +++ b/docs/current_docs/quickstart/822194-daggerize.mdx @@ -14,8 +14,8 @@ So far, you've learned the basics of calling Dagger Functions. The next step is Here are the basic steps to Daggerizing an existing project: -1. Initialize a new Dagger Module with `dagger init` -2. Install other useful Dagger Modules as dependencies with `dagger install` +1. Initialize a new Dagger module with `dagger init` +2. Install other useful Dagger modules from the [Daggerverse](./183917-daggerverse.mdx) as dependencies with `dagger install` 3. Call useful Dagger Functions with `dagger call` 4. Add useful `dagger call` commands to existing scripts and CI configuration @@ -49,7 +49,7 @@ You should see the following: ```json { "name": "example", - "engineVersion": "v0.10.1" + "engineVersion": "v0.11.1" } ``` @@ -64,14 +64,12 @@ git add dagger.json git commit -m 'dagger init' ``` -Congratulations! Your repository is now a Dagger Module. - ### Install a dependency -Now that your project is a Dagger Module, you can install other modules into it, as dependencies. A dependency is just a Dagger Module installed into another. As an example, install the `hello` module from earlier: +Now that your project has a Dagger module, you can install other modules into it, as dependencies. A dependency is just a Dagger module installed into another. Since the project is a Go project, install the Go builder module from earlier as a dependency: ```shell -dagger install github.com/shykes/daggerverse/hello@v0.1.2 +dagger install github.com/kpenfound/dagger-modules/golang@v0.1.8 ``` Once the command completes, look at the `dagger.json` file again. You should see that a new dependency has been added, similar to that shown below: @@ -79,15 +77,13 @@ Once the command completes, look at the `dagger.json` file again. You should see ```json { "name": "example", - "sdk": "go", "dependencies": [ { - "name": "hello", - "source": "github.com/shykes/daggerverse/hello@3d608cb5e6b4b18036a471400bc4e6c753f229d7" + "name": "golang", + "source": "github.com/kpenfound/dagger-modules/golang@8d662e001caf8c16253226d0d456f2f0f374f009" } ], - "source": "dagger", - "engineVersion": "v0.10.1" + "engineVersion": "v0.11.1" } ``` @@ -99,44 +95,7 @@ Go ahead and commit this change as well: ```shell git add dagger.json -git commit -m 'dagger install github.com/shykes/daggerverse/hello' -``` - -### Use the installed module - -Now that your module has its first dependency installed, you can start using it! To do so, simply refer to it by its short name - in this case, `hello`. - -List available functions: - -```shell -dagger -m hello functions -``` - -You should see a familiar result: - -``` -Name Description -hello Say hello to the world! -``` - -Call a function: - -```shell -dagger -m hello call hello -``` - -Again, the output should be familiar: - -``` -hello, world! -``` - -### Daggerize a Go build - -The `hello` module is a good example to start with, but it doesn't have any functions to work with a Go project. To Daggerize the Go build for this example project, install the Go builder module from a previous section as another dependency: - -```shell -dagger install github.com/kpenfound/dagger-modules/golang@v0.1.8 +git commit -m 'Added Go builder module' ``` Then, call the `BuildContainer()` function from the Go builder module to build the project and publish a container image with the built binary: @@ -168,4 +127,4 @@ You should see the following output: Hello, world! ``` -Your project is slowly becoming more and more Daggerized...you're now able to build it, containerize it and publish it, all with a single Dagger Function call. If you like, you can integrate this call into your existing shell scripts, or perhaps a Makefile. Or, you can create a custom Dagger Module, which enables you to connect one or more Dagger Functions together in portable, expressive workflows with all the benefits of a native programming language. +Your project is slowly becoming more and more Daggerized...you're now able to build it, containerize it and publish it, all with a single Dagger Function call. If you like, you can integrate this call into your existing shell scripts, or perhaps a Makefile. Or, you can create a custom Dagger module, which enables you to connect one or more Dagger Functions together in portable, expressive workflows with all the benefits of a native programming language. diff --git a/docs/current_docs/quickstart/853930-directories.mdx b/docs/current_docs/quickstart/853930-directories.mdx index e87ea0a7d22..81585fa538d 100644 --- a/docs/current_docs/quickstart/853930-directories.mdx +++ b/docs/current_docs/quickstart/853930-directories.mdx @@ -6,7 +6,6 @@ title: "Build a binary with a function" # Quickstart - ## Build a binary with a function Not only can functions use Dagger's core types in their arguments; they can use them in their return value as well. @@ -21,7 +20,7 @@ Try calling this Go builder Dagger Function, which builds the Dagger CLI: dagger -m github.com/kpenfound/dagger-modules/golang@v0.1.10 call build --source=https://github.com/dagger/dagger --args=./cmd/dagger --os=$(uname -s | awk '{print tolower($0)}') ``` -This function takes a `source` argument of type `Directory`. Similar to how the CLI can pass a `Container` from a remote OCI address, it can also pass a `Directory` from a local path or remote Git address. Here, you're passing the address of Dagger's open-source repository. +This function takes a `project` argument of type `Directory`. Here, you're passing the address of Dagger's open-source repository. It also takes an `args` argument, which is a list of strings representing the arguments to be passed to the `go build` command. :::note By default, the Go builder Dagger Function builds a binary based on information derived from the runtime container. Since the runtime container uses Linux, this usually means that the compiled binary will be a `linux/amd64` binary. This can be overridden by passing additional `--os` and `--arch` arguments to the Go builder Dagger Function. The previous example uses `uname` to dynamically derive the host operating system type, and passes that to the Dagger Function via the `--os` argument. @@ -84,7 +83,7 @@ dagger (registry.dagger.io/engine) linux/amd64 ``` :::tip -As you've seen in the previous examples, Dagger modules can contain one or more functions, each with different arguments and return values. You can list all the functions available in a module with the `dagger functions` command, or append `--help` to any `dagger call` command to see a context-sensitive list of supported arguments and sub-commands. Try it with the Go builder module: +As you've seen in the previous examples, Dagger modules can contain one or more Dagger Functions, each with different arguments and return values. You can list all the functions available in a module with the `dagger functions` command, or append `--help` to any `dagger call` command to see a context-sensitive list of supported arguments and sub-commands. Try it with the Go builder module: ```shell dagger -m github.com/kpenfound/dagger-modules/golang@v0.1.10 functions diff --git a/docs/current_docs/quickstart/883939-containers.mdx b/docs/current_docs/quickstart/883939-containers.mdx index 87f5463c8ac..0245dc24436 100644 --- a/docs/current_docs/quickstart/883939-containers.mdx +++ b/docs/current_docs/quickstart/883939-containers.mdx @@ -15,12 +15,12 @@ Just as you can chain and return `Directory` types, you can also chain and retur Try calling this function: ```shell -dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call container --packages=cowsay +dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call container --packages=python3 ``` This Wolfi container builder module exposes a `Container()` function that returns a base Wolfi container image, and accepts arguments to additional packages in the base image; -You can use this function to build and return a Wolfi container image containing specific packages - in this example, the `cowsay` package. You should see the container being built and the packages being added, as shown below: +You can use this function to build and return a Wolfi container image containing specific packages - in this example, the `python3` package. You should see the container being built and the packages being added, as shown below: ``` Container evaluated. Use "dagger call base with-package container --help" to see available sub-commands. @@ -35,7 +35,8 @@ One of the most interesting `Container` functions is `Terminal()`, which can be To see this in action, call the previous function again, this time chaining an additional function call to `Terminal()` on the returned `Container`: ```shell -dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call container --packages=cowsay terminal +dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call \ + container --packages=python3 terminal ``` This revised command builds the container image and then drops you into an interactive terminal, allowing you to directly execute commands in the running container. @@ -43,20 +44,13 @@ This revised command builds the container image and then drops you into an inter Verify this by executing the following command: ```shell -cowsay "dagger" +python3 -c "print('Hello from Dagger')" ``` -You should see output similar to the following: +You should see the following output: -``` - ________ -< dagger > - -------- - \ ^__^ - \ (oo)\_______ - (__)\ )\/\ - ||----w | - || || +```shell +Hello from Dagger ``` :::caution @@ -65,43 +59,46 @@ While most terminal programs such as `htop` or `vim` work with `dagger ... termi ### Execute commands in the container -The `Container` type has a `WithExec()` function, which returns the container after executing a specific command inside it. So, you could achieve the same result as before (although non-interactively) by chaining a function call to `withExec()` on the `Container` returned previously, as shown in the following command: +The `Container` type has a `WithExec()` function, which returns the container after executing a specific command inside it. So, you could achieve the same result as before (although non-interactively) by chaining function calls to `WithExec()` and `Stdout()` on the `Container` returned previously, as shown in the following command: + +```shell +dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call \ + container --packages=python3 \ + with-exec --args=python3,-c,"print('Hello from Dagger')" \ + stdout +``` + +You should see the following output: ```shell -dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call container --packages=cowsay with-exec --args cowsay,dagger stdout +Hello from Dagger ``` ### Publish the container image to a registry -The `Container` type also has a `Publish()` function, which publishes the container to a registry. To see this in action, call the previous function again, this time chaining an additional function call to `Publish()` on the returned `Container`: +The `Container` type also makes a number of other functions available. To see some of these in action, call the previous function again, chaining additional function calls to `WithEntrypoint()` and `Publish()` on the returned `Container` to set the container entrypoint command and publish it to a registry: ```shell -dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 \ - call container --packages=cowsay \ - publish --address ttl.sh/dagger-cowsay-$RANDOM +dagger -m github.com/shykes/daggerverse/wolfi@v0.1.2 call \ + container --packages=python3 \ + with-entrypoint --args=python3,-c,"print('Hello from Dagger')" \ + publish --address ttl.sh/dagger-$RANDOM ``` The output will be a container image reference on the [ttl.sh container registry](https://ttl.sh), as shown below: -``` -ttl.sh/dagger-cowsay-10939@sha256:57c15999fdc59df452161f648aaa9b9a1ea9dbda710a0a0242f509966a286b4b +```shell +ttl.sh/dagger-10939@sha256:57c15999fdc59df452161f648aaa9b9a1ea9dbda710a0a0242f509966a286b4b ``` Test the container image using the command below (remember to update the image reference based on the function output): ```shell -docker run --rm -it ttl.sh/dagger-cowsay-10939 cowsay "dagger" +docker run --rm ttl.sh/dagger-10939 ``` -You should see the output below: +You should see the following output: -``` - ________ -< dagger > - -------- - \ ^__^ - \ (oo)\_______ - (__)\ )\/\ - ||----w | - || || +```shell +Hello from Dagger ``` diff --git a/docs/current_docs/quickstart/snippets/create/go/main.go b/docs/current_docs/quickstart/snippets/create/go/main.go index 035204fb5a6..f7751c52a76 100644 --- a/docs/current_docs/quickstart/snippets/create/go/main.go +++ b/docs/current_docs/quickstart/snippets/create/go/main.go @@ -10,11 +10,26 @@ import ( type Example struct{} // Build and publish a project using a Wolfi container -func (m *Example) BuildAndPublish(ctx context.Context, buildSrc *Directory, buildArgs []string) (string, error) { +func (m *Example) BuildAndPublish( + ctx context.Context, + buildSrc *Directory, + buildArgs []string, +) (string, error) { ctr := dag.Wolfi().Container() return dag. Golang(). - BuildContainer(GolangBuildContainerOpts{Source: buildSrc, Args: buildArgs, Base: ctr}). - Publish(ctx, fmt.Sprintf("ttl.sh/my-hello-container-%.0f", math.Floor(rand.Float64()*10000000))) //#nosec + BuildContainer( + GolangBuildContainerOpts{ + Source: buildSrc, + Args: buildArgs, + Base: ctr, + }). + Publish( + ctx, + fmt.Sprintf( + "ttl.sh/my-hello-container-%.0f", + math.Floor(rand.Float64()*10000000), + ), + ) //#nosec } diff --git a/docs/sidebars.ts b/docs/sidebars.ts index f2c7038c73c..6e5b88cc4fa 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -21,7 +21,6 @@ module.exports = { "items": [ "quickstart/cli", "quickstart/hello", - "quickstart/arguments", "quickstart/directories", "quickstart/containers", "quickstart/daggerize",