From 81272486c225243fff9346f6053d0967482b6913 Mon Sep 17 00:00:00 2001 From: Thanabodee Charoenpiriyakij Date: Sat, 20 Apr 2024 23:34:03 +0700 Subject: [PATCH] chore(sdk/elixir): update documentation * Upgrade `ex_doc` to latest version. * Update documentation on the `Dagger` module. * Remove `getting_started.livemd`, it's quite out-of-date. Signed-off-by: Thanabodee Charoenpiriyakij --- sdk/elixir/getting_started.livemd | 49 ------------------------------- sdk/elixir/lib/dagger.ex | 49 +++++++++++++++++++++++++++++-- sdk/elixir/mix.exs | 3 +- sdk/elixir/mix.lock | 12 ++++---- 4 files changed, 54 insertions(+), 59 deletions(-) delete mode 100644 sdk/elixir/getting_started.livemd diff --git a/sdk/elixir/getting_started.livemd b/sdk/elixir/getting_started.livemd deleted file mode 100644 index fcd20e2ca70..00000000000 --- a/sdk/elixir/getting_started.livemd +++ /dev/null @@ -1,49 +0,0 @@ -# Getting Started with `dagger` - -```elixir -Mix.install([ - {:dagger, path: "."} -]) -``` - -## Before start - -You need to install: - -1. `dagger` binary, you can download in the [Release Page](https://github.com/dagger/dagger/releases). -2. `docker` or `podman`. - -And make sure all commands above presents in `$PATH`. - -## Connecting to Dagger - -Currently, we support only 2 modes: - -1. Session mode with `dagger run`. The benefit of running with this mode is it support rich Terminal User Interface (TUI) by set `_EXPERIMENTAL_DAGGER_INTERACTIVE_TUI=1` -2. Local CLI mode, this mode will start Dagger session and send a request through the session. This mode need to set `_EXPERIMENTAL_DAGGER_CLI_BIN=//dagger`. We'll use this mode in this tutorial. - -```elixir -System.put_env("_EXPERIMENTAL_DAGGER_CLI_BIN", "dagger") -``` - -Use `Dagger.connect/0` to connect to Dagger server: - -```elixir -{:ok, client} = Dagger.connect() -``` - -The result from `Dagger.connect/0` is a tuple of `:ok` with client or `:error` if it cannot connect. - -## Fetching the container and running it - -In this section, we will pull Elixir image from [hex.pm](https://hub.docker.com/r/hexpm/elixir) organization, getting the version from `elixir` binary and print it to standard output. - -After execute the code below, the library will printing out log from Dagger session to the standard output. - -```elixir -client -|> Dagger.Client.container() -|> Dagger.Container.from("hexpm/elixir:1.14.4-erlang-25.3-debian-buster-20230227-slim") -|> Dagger.Container.with_exec(["elixir", "--version"]) -|> Dagger.Container.stdout() -``` diff --git a/sdk/elixir/lib/dagger.ex b/sdk/elixir/lib/dagger.ex index 1e50cc32b80..bbb30565f90 100644 --- a/sdk/elixir/lib/dagger.ex +++ b/sdk/elixir/lib/dagger.ex @@ -2,12 +2,57 @@ defmodule Dagger do @moduledoc """ The [Dagger](https://dagger.io/) SDK for Elixir. - See `getting_start.livemd` for starter point. + ## Prerequisite + + The SDK depends on `docker` and `dagger` commands, please make sure those + commands are presents on your `PATH`. + + ## Getting Started + + Let's try this script below + + Mix.install([:dagger]) + + # 1 + Application.ensure_all_started(:inets) + + # 2 + {:ok, client} = Dagger.connect() + + # 3 + {:ok, output} = + client + |> Dagger.Client.container() + |> Dagger.Container.from("hexpm/elixir:1.14.4-erlang-25.3-debian-buster-20230227-slim") + |> Dagger.Container.with_exec(["elixir", "--version"]) + |> Dagger.Container.stdout() + + IO.puts(output) + + # 4 + Dagger.close(client) + + Here's what script do: + + 1. Start `:inets` application in order to use `:httpc` as a HTTP client. + 2. Connecting to the Dagger Engine with `Dagger.connect/1`. + 3. Create a new container from `hexpm/elixir:1.14.4-erlang-25.3-debian-buster-20230227-slim` + and calling a command `elixir` with flag `--version`, get the standard + output from latest command and printing it to standard output. + 4. Close the connection. """ @doc """ Connecting to Dagger. + When calling this function, it try to connect in ordered: + + 1. Use session from `DAGGER_SESSION_PORT` and `DAGGER_SESSION_TOKEN` shell + environment variables. + 2. If (1) doesn't specified, it will lookup a binary defined in `_EXPERIMENTAL_DAGGER_CLI_BIN` + and start a session. + 3. Download the latest binary from Dagger and start a session. + ## Options #{NimbleOptions.docs(Dagger.Core.Client.connect_schema())} @@ -42,7 +87,7 @@ defmodule Dagger do end @doc """ - Disconnecting Dagger. + Disconnecting the client from Dagger Engine session. """ def close(%Dagger.Client{client: client}) do Dagger.Core.Client.close(client) diff --git a/sdk/elixir/mix.exs b/sdk/elixir/mix.exs index 446e4fab77c..1f0c7ffa961 100644 --- a/sdk/elixir/mix.exs +++ b/sdk/elixir/mix.exs @@ -54,8 +54,7 @@ defmodule Dagger.MixProject do [ source_ref: "v#{@version}", source_url: @source_url, - main: "Dagger", - extras: ["getting_started.livemd"] + main: "Dagger" ] end end diff --git a/sdk/elixir/mix.lock b/sdk/elixir/mix.lock index c02f12adf79..041d785c470 100644 --- a/sdk/elixir/mix.lock +++ b/sdk/elixir/mix.lock @@ -1,13 +1,13 @@ %{ "bunt": {:hex, :bunt, "0.2.1", "e2d4792f7bc0ced7583ab54922808919518d0e57ee162901a16a1b6664ef3b14", [:mix], [], "hexpm", "a330bfb4245239787b15005e66ae6845c9cd524a288f0d141c148b02603777a5"}, "credo": {:hex, :credo, "1.7.0", "6119bee47272e85995598ee04f2ebbed3e947678dee048d10b5feca139435f75", [:mix], [{:bunt, "~> 0.2.1", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2.8", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "6839fcf63d1f0d1c0f450abc8564a57c43d644077ab96f2934563e68b8a769d7"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.31", "a93921cdc6b9b869f519213d5bc79d9e218ba768d7270d46fdcf1c01bacff9e2", [:mix], [], "hexpm", "317d367ee0335ef037a87e46c91a2269fef6306413f731e8ec11fc45a7efd059"}, - "ex_doc": {:hex, :ex_doc, "0.29.4", "6257ecbb20c7396b1fe5accd55b7b0d23f44b6aa18017b415cb4c2b91d997729", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "2c6699a737ae46cb61e4ed012af931b57b699643b24dabe2400a8168414bc4f5"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"}, + "ex_doc": {:hex, :ex_doc, "0.32.1", "21e40f939515373bcdc9cffe65f3b3543f05015ac6c3d01d991874129d173420", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "5142c9db521f106d61ff33250f779807ed2a88620e472ac95dc7d59c380113da"}, "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"}, "jason": {:hex, :jason, "1.4.0", "e855647bc964a44e2f67df589ccf49105ae039d4179db7f6271dfd3843dc27e6", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "79a3791085b2a0f743ca04cec0f7be26443738779d09302e01318f97bdb82121"}, - "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"}, - "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"}, - "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"}, + "makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"}, + "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"}, + "makeup_erlang": {:hex, :makeup_erlang, "0.1.5", "e0ff5a7c708dda34311f7522a8758e23bfcd7d8d8068dc312b5eb41c6fd76eba", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "94d2e986428585a21516d7d7149781480013c56e30c6a233534bedf38867a59a"}, "nimble_options": {:hex, :nimble_options, "1.0.1", "b448018287b22584e91b5fd9c6c0ad717cb4bcdaa457957c8d57770f56625c43", [:mix], [], "hexpm", "078b2927cd9f84555be6386d56e849b0c555025ecccf7afee00ab6a9e6f63837"}, - "nimble_parsec": {:hex, :nimble_parsec, "1.3.0", "9e18a119d9efc3370a3ef2a937bf0b24c088d9c4bf0ba9d7c3751d49d347d035", [:mix], [], "hexpm", "7977f183127a7cbe9346981e2f480dc04c55ffddaef746bd58debd566070eef8"}, + "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"}, }