From 6155b5e33e9c3df7d4cebef71c26a82da7c4b840 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Sun, 29 Mar 2026 18:47:14 +0200 Subject: [PATCH] docs(posts): announcing Distrobox v2 (#2032) * docs(posts): announcing v2 post Co-authored-by: 89luca89 Co-authored-by: Alessio Biancalana Co-authored-by: Fabrizio Sestito * docs(posts): distrobox next architecture Co-authored-by: 89luca89 Co-authored-by: Alessio Biancalana Co-authored-by: Fabrizio Sestito * docs: fix link to distrobox next architecture --------- Co-authored-by: 89luca89 Co-authored-by: Alessio Biancalana Co-authored-by: Fabrizio Sestito --- docs/posts/announcing_distrobox_next.md | 96 +++++++++++++++ docs/posts/distrobox_next_architecture.md | 144 ++++++++++++++++++++++ docs/posts/posts.md | 2 + 3 files changed, 242 insertions(+) create mode 100644 docs/posts/announcing_distrobox_next.md create mode 100644 docs/posts/distrobox_next_architecture.md diff --git a/docs/posts/announcing_distrobox_next.md b/docs/posts/announcing_distrobox_next.md new file mode 100644 index 00000000..de7dbfb8 --- /dev/null +++ b/docs/posts/announcing_distrobox_next.md @@ -0,0 +1,96 @@ +- [Distrobox](README.md) + - [Announcing the next generation of Distrobox](#announcing-the-next-generation-of-distrobox) + - [Try it now](#try-it-now) + - [Why we rewrote Distrobox](#why-we-rewrote-distrobox) + - [Compatibility](#compatibility) + - [During the transition](#during-the-transition) + - [Contributing](#contributing) + - [The many thanks we have to say](#the-many-thanks-we-have-to-say) + +--- + +# Announcing the next generation of Distrobox + +We're releasing Distrobox v2 to the public as a release candidate. This is a complete rewrite in Go. Distrobox v1 +remains the stable version and we recommend using it in production for now. + +The first objective is to reach feature parity between v2 and v1, at which point we can declare v2 stable. The source +code is available now on [the `next` branch](https://github.com/89luca89/distrobox/tree/next). + +## Try it now + +v2.0.0-rc releases are available on [GitHub](https://github.com/89luca89/distrobox/releases/tag/2.0.0-rc.1). + +You can also build from source on the `next` branch: + +```sh +git clone https://github.com/89luca89/distrobox.git +cd distrobox +git checkout next +make build +sudo make install +``` + +Please test it with your usual workflows and report any issues you find. Your feedback is essential to reach stability +quickly. + +## Why we rewrote Distrobox + +Shell's immediate feedback loop was critical to Distrobox's early success. But as the project matured, we hit its +limits: no proper module system for code reuse, no handy test engine, and patterns that are hard to maintain. We also +want to extend Distrobox to new use cases, which would have required a significant refactor of the existing codebase. + +We chose Go because the core team is confident in it. It's popular with a short learning curve, so the community can +jump in and contribute. It has a solid toolchain and standard library that lets us keep external dependencies to a +minimum. And it's straightforward to build for multiple architectures—important for Distrobox's diverse user base. + +We didn't start this effort to improve performance. But first benchmarks show a sensible performance increase on common +usage scenarios. More data to come. + +## Compatibility + +v2 maintains the same interface for CLI command arguments, manifest files, and configuration files. Your scripts and +`.distrobox` folders will work with v2. + +Existing v1 containers work with v2, except for exported bins and apps—those containers must be recreated. v2 ships as +a single binary, so command-specific executables like `distrobox-enter` and `distrobox-create` no longer exist. Use +`distrobox enter`, `distrobox create`, etc. instead. + +## During the transition + +While v2 reaches feature parity and stability, we're making focused choices. + +We do not accept new features on v1 nor v2 until v2 reaches feature parity with v1 and is declared stable. New features +would slow down that milestone. Bugfixes must be submitted against the `next` branch. We'll decide on backports to v1 +case-by-case. + +Before reporting a bug, check whether it's already fixed in v2. For already open PRs on v1, we'll decide case-by-case +with the authors. For open issues on v1, we ask that you verify whether the issue is present on v2 as well. We +prioritize fixing issues on v2 first. We'll consider backporting critical fixes to v1 if the issue makes Distrobox v1 +unusable or insecure. + +We're releasing v2.0.0-rc versions as we progress. Releases are available on GitHub and are published as needed, with +no fixed cadence. v2 will be declared stable when we can assert it covers all the use cases of v1 without relevant +regressions. + +## Contributing + +All contributions must be sent against the `next` branch. Please read the +[architecture document](distrobox_next_architecture.md) before contributing. + +A working Go installation is required to build and test the project. Refer to the +[official Go documentation](https://go.dev/doc/install) to set up your local environment. + +## The many thanks we have to say + +A project like Distrobox would have gone nowhere without the support of its community. Over the years, we received +contributions from more than 200 developers; these people are first of all enthusiastic Distrobox users, and we cannot +be more grateful for that. + +Some of them are now seeing their code disappear to make room for the rewrite. We want to emphasize that the rewrite +itself wouldn't have been possible without their contributions. Please take a moment to acknowledge the +[Distrobox contributors list](https://github.com/89luca89/distrobox/graphs/contributors) — to them go our warmest +thanks. + +We're excited to see where v2 takes Distrobox, and we hope you are excited, too. Try it out, report bugs, and join the +discussion on [Matrix](https://matrix.to/#/%23distrobox:matrix.org) and [Telegram](https://t.me/distrobox_chat_new) diff --git a/docs/posts/distrobox_next_architecture.md b/docs/posts/distrobox_next_architecture.md new file mode 100644 index 00000000..a161c666 --- /dev/null +++ b/docs/posts/distrobox_next_architecture.md @@ -0,0 +1,144 @@ +- [Distrobox](README.md) + - [Distrobox Go Rewrite: Architecture and Design](#distrobox-go-rewrite-architecture-and-design) + - [Overview](#overview) + - [Directory Structure](#directory-structure) + - [Architecture Layers](#architecture-layers) + - [Dependency Injection Pattern](#dependency-injection-pattern) + - [Configuration System](#configuration-system) + - [Shell Scripts](#shell-scripts) + +--- + +# Distrobox Go Rewrite: Architecture and Design + +This document describes the architecture of the Distrobox Go rewrite, explaining how +different layers interact and the design decisions behind the codebase. It's meant to +help contributors understand the system and know where to make changes. + +## Overview + +The Distrobox Go rewrite is designed with **clear separation of concerns** in mind. +The rewrite followed these principles: + +- CLI layer handles command-line parsing and user interaction; +- Container manager implementations are interchangeable; +- UI components can evolve independently; +- The codebase must remains testable and maintainable; +- Dependencies must be kept at minimum. + +## Directory Structure + +```text +distrobox +├── cmd/distrobox/ +│ └── main.go # Entry point +├── internal/ +│ ├── cli/ # CLI layer (command definitions) +│ │ ├── root.go # Root command with global flags +│ │ ├── create.go, list.go, etc. # Individual commands +│ │ └── helpers.go +│ ├── config/ # Configuration management +│ ├── inside-distrobox/ +│ │ └── assets/ # Embedded shell scripts +├── pkg/ +│ ├── commands/ # Business logic layer +│ │ ├── create.go, list.go, etc. # Command implementations +│ ├── containermanager/ # Container abstraction +│ │ ├── containermanager.go # Interface definitions +│ │ └── providers/ # Implementations +│ │ ├── podman.go +│ │ └── docker.go +│ ├── ui/ # UI components +│ │ ├── progress.go +│ │ ├── printer.go +│ │ └── prompt.go +│ └── manifest/ # Manifest parsing +``` + +## Architecture Layers + +### 1. CLI Layer (`internal/cli/`) + +The CLI layer handles command-line argument parsing, global flag processing, and +command dispatch. It is also responsible for binding the application to the shell's stdin/stdout, +for loading the configuration, and for instantiating the components. + +Among other things, the concerete `ContainerManager` implementation is selected and instantiated in the cli layer. + +### 2. Command Layer (`pkg/commands/`) + +The command layer contains the business logic for each distrobox operation. Commands +are independent of CLI specifics and can be tested and reused independently. + +Commands should be **pure orchestrators**. They coordinate between +the container manager abstraction and UI components, but don't contain low-level +implementation details. + +Each command is implemented by a `Execute` method that takes a context and options struct. + +### 3. Container Manager Layer (`pkg/containermanager/`) + +The container manager is the abstraction over different container runtimes. This design +allows distrobox to work with Docker, Podman, and other container managers without +duplicating logic. + +### 4. UI Layer (`pkg/ui/`) + +The UI layer provides simple components for user interaction and output formatting. +These are instantiated in the CLI layer and passed to commands. + +- **Progress**: Tracks multi-step operations with status indicators +- **Printer**: Formats and displays structured output +- **Prompter**: Gets user confirmation or input + +## Dependency Injection Pattern + +The architecture uses **context-based dependency injection** to pass the container +manager from the root command to all subcommands. + +**Flow:** + +```text +main() + ↓ +LoadConfig() + ↓ +NewRootCommand().Run() + ↓ +beforeAction() [global hooks] + ↓ Creates container manager + ↓ Stores in context + ↓ +Specific command action (e.g., createAction) + ↓ Extracts container manager from context + ↓ Creates UI tools + ↓ Delegates to command layer +``` + +This pattern ensures: + +- Container manager is available to all commands without global state +- UI tools are created fresh for each invocation +- Testing can substitute different implementations via context + +## Configuration System + +Configuration is loaded once at startup in `main()`. Configuration sources (in order of precedence): + +1. Command-line flags +2. Environment variables (prefixed with `DBX_`) +3. Config file (`~/.config/distrobox/distrobox.conf`) +4. Defaults + +This centralized approach makes it easy to understand where values come from and ensures consistency across commands. + +## Shell Scripts + +When a container is created, part of the `Distrobox` application is loaded in the container +as it is meant to be executed inside it: + +- `distrobox-init` serves as the container entrypoint +- `distrobox-export` to expose binaries and applications to the host +- `distrobox-host-exec` to execute host's commands from inside the distrobox + +Such commands are POSIX shell scripts that are included as assets in `internal/inside-distrobox/assets` diff --git a/docs/posts/posts.md b/docs/posts/posts.md index 78ac0de8..c7ce81ff 100644 --- a/docs/posts/posts.md +++ b/docs/posts/posts.md @@ -11,3 +11,5 @@ - [Integrate VSCode and Distrobox](integrate_vscode_distrobox.md) - [Run Libvirt using distrobox](run_libvirt_in_distrobox.md) - [Run latest GNOME and KDE Plasma using distrobox](run_latest_gnome_kde_on_distrobox.md) +- [Announcing the next generation of Distrobox](announcing-distrobox-next-gen.md) +- [Distrobox Next architecture](distrobox-next-architecture.md)