From f1960ae496e861512f36813a9939bfa17fbacfe1 Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Fri, 24 Jan 2025 16:36:37 +0100 Subject: [PATCH] docs: update notes on interactive debugging Signed-off-by: AtomicFS --- cmd/firmware-action/main.go | 2 +- docs/src/SUMMARY.md | 2 +- .../get_started/get_started.md | 2 +- docs/src/firmware-action/interactive.md | 54 ++++++++++++------- 4 files changed, 39 insertions(+), 21 deletions(-) diff --git a/cmd/firmware-action/main.go b/cmd/firmware-action/main.go index 20f8e2a9..8db17856 100644 --- a/cmd/firmware-action/main.go +++ b/cmd/firmware-action/main.go @@ -47,7 +47,7 @@ var CLI struct { Build struct { Target string `required:"" help:"Select which target to build, use ID from configuration file"` Recursive bool `help:"Build recursively with all dependencies and payloads"` - } `cmd:"build" help:"Build a target defined in configuration file"` + } `cmd:"build" help:"Build a target defined in configuration file. For interactive debugging preface the command with 'dagger run --interactive', for example 'dagger run --interactive $(which firmware-action) build --config=...'. To install dagger follow instructions at https://dagger.io/"` GenerateConfig struct{} `cmd:"generate-config" help:"Generate empty configuration file"` Version struct{} `cmd:"version" help:"Print version and exit"` diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 4a187028..b41493f7 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -14,7 +14,7 @@ - [Get firmware-action](firmware-action/get_started/04_get_firmware_action.md) - [Run firmware-action locally](firmware-action/get_started/05_run_firmware_action.md) - [Run firmware-action in CI](firmware-action/get_started/06_run_in_ci.md) - - [Interactive mode](firmware-action/interactive.md) + - [Interactive debugging](firmware-action/interactive.md) - [TLDR; Usage](firmware-action/usage.md) - [Local system](firmware-action/usage_local.md) - [GitHub CI](firmware-action/usage_github.md) diff --git a/docs/src/firmware-action/get_started/get_started.md b/docs/src/firmware-action/get_started/get_started.md index 9c0d59e1..ed2c7646 100644 --- a/docs/src/firmware-action/get_started/get_started.md +++ b/docs/src/firmware-action/get_started/get_started.md @@ -15,5 +15,5 @@ The code from this example is available in [firmware-action-example](https://git - installed [Docker](https://wiki.archlinux.org/title/Docker) - installed git +- installed [dagger](https://docs.dagger.io/install) (optional, needed for interactive debugging) - installed [taskfile](https://taskfile.dev/) (optional) - diff --git a/docs/src/firmware-action/interactive.md b/docs/src/firmware-action/interactive.md index 0ec89bde..f5651dca 100644 --- a/docs/src/firmware-action/interactive.md +++ b/docs/src/firmware-action/interactive.md @@ -1,35 +1,53 @@ -# Interactive mode +# Interactive debugging ```admonish note title="A little bit of backstory" -While I was playing around with firmware-action I found early on that debugging what is going on inside the docker container is rather lengthy and annoying process. This was the moment when the idea of some interactive option was born. +While I was playing around with `firmware-action` I found early on that debugging what is going on inside the docker container is rather lengthy and annoying process. This was the moment when the idea of some interactive option was born. ``` -```admonish bug title="Issue [#269](https://github.com/9elements/firmware-action/issues/269)" +```admonish done collapsible=true title="Dropping the SSH feature in favor of Dagger build-in debugging" Dagger [since v0.12](https://dagger.io/blog/dagger-0-12) supports new built-in interactive debugging. -We are already planning to re-write `firmware-action` to use this new feature instead of the `ssh` solution we are currently using. For more details see issue [269](https://github.com/9elements/firmware-action/issues/269). -``` +~~We are already planning to re-write `firmware-action` to use this new feature instead of the `ssh` solution we are currently using. For more details see issue [269](https://github.com/9elements/firmware-action/issues/269).~~ + +**UPDATE:** It is possible now to use the new and shiny feature of dagger for interactive debugging! As a result we have dropped the SSH feature. -On build failure open `ssh` server in the container and let user connect into it to debug the problem. To enable this feature user has to pass argument `--interactive`. User can ssh into the container with a randomly generated password. +Related: +- Issue [#269](https://github.com/9elements/firmware-action/issues/269) +- Pull Request [#522](https://github.com/9elements/firmware-action/pull/522) -The container will keep running until user presses `ENTER` key in the terminal with firmware-action running. +Supplementary dagger documentation: +- Blog post [Dagger 0.12: interactive debugging](https://dagger.io/blog/dagger-0-12) +- Documentation for [Interactive Debugging](https://docs.dagger.io/features/debugging) +- Documentation for [Custom applications](https://docs.dagger.io/api/sdk/#custom-applications) +- Documentation for [Interactive Terminal](https://docs.dagger.io/api/terminal/) +``` +To leverage the use of interactive debugging, you have to install [dagger CLI](https://docs.dagger.io/install). -```admonish attention -The container is launched in the interactive mode before the failed command was started. +Then when using `firmware-action`, simply prepend the command with `dagger run --interactive`. -This reverting behavior is out of technical necessity. +Instead of: +```bash +firmware-action build --config=firmware-action.json --target=coreboot-example +``` + Execute this: +```bash +dagger run --interactive firmware-action build --config=firmware-action.json --target=coreboot-example ``` -```admonish note -The containers in dagger (at the time of writing) are single-use non-interactive containers. Dagger has a pipeline (command queue for each container) which starts executing only when specific functions such as [Sync()](https://pkg.go.dev/dagger.io/dagger#Container.Sync) are called which trigger evaluation of the pipeline inside the container. - -To start a `ssh` service and wait for user to log-in, the container has to be converted into a [service](https://pkg.go.dev/dagger.io/dagger#Container.AsService) which also forces evaluation of the pipeline. And if any of the commands should fail, it would fail to start the `service` container. +If you are using `Taskfile` to abstract away some of the complexity that comes with larger projects, simply prepend the whole `Taskfile` command. -As a workaround, when the evaluation of pipeline fails in the container, the container from previous step is converted into a `service` container with everything as it was just before the failing command was executed. In essence, when you connect, you end up in pristine environment. +Instead of: +```bash +task build:coreboot-example +``` -~~~go -{{#include ../../../cmd/firmware-action/container/ssh.go:ContainerAsService}} -~~~ + Execute this: +```bash +dagger run --interactive task build:coreboot-example ``` + +On build failure you will be dropped into the container and can debug the problem. + +To exit the container run command `exit` or press `CTRL+D`.