From eed5180d875dd0d6230513a7d302f7f87ef13583 Mon Sep 17 00:00:00 2001
From: Steffen Beyer <steffen@beyer.io>
Date: Fri, 29 May 2026 18:11:21 +0200
Subject: [PATCH] docs: Document some differences to Guix

---
 docs/guix_alignment.md | 245 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 245 insertions(+)
 create mode 100644 docs/guix_alignment.md

diff --git a/docs/guix_alignment.md b/docs/guix_alignment.md
new file mode 100644
index 0000000..a280993
--- /dev/null
+++ b/docs/guix_alignment.md
@@ -0,0 +1,245 @@
+ The Guix-like part
+
+ The nearest Fruix equivalent today is:
+
+ 1. install a normal-ish Fruix node
+ 2. put your desired dev tools in the system declaration
+ 3. reconfigure
+ 4. work on the machine
+
+ So conceptually, yes: declare the system, reconfigure it, use it for development.
+
+ For Fruix today, that usually means editing something like:
+
+ - examples/system/self-hosted-dev.scm
+
+ and setting:
+
+ - #:development-packages ...
+ - #:build-packages ...
+
+ then running on the installed node:
+
+ ```sh
+   /usr/local/bin/fruix system reconfigure /path/to/your-system.scm \
+     --system self-hosted-development-operating-system
+ ```
+
+ Where Fruix differs today
+
+ ### 1. Fruix does not yet have the same “just add packages to the normal system profile” feel
+
+ In Guix, you usually think in terms of:
+
+ - “this is my OS”
+ - “these packages are on the system”
+
+ In Fruix right now, the model is more split:
+
+ - runtime system
+ - development profile
+ - build profile
+
+ So instead of “all dev tools are just part of the normal system profile”, Fruix currently prefers:
+
+ - a smaller runtime
+ - a dedicated dev environment
+ - a dedicated build environment
+
+ That’s why the installed node provides helpers like:
+
+ ```sh
+   eval "$( /usr/local/bin/fruix-development-environment )"
+   eval "$( /usr/local/bin/fruix-build-environment )"
+ ```
+
+ So the workflow is still declarative, but it is more profile-structured than Guix’s typical system-packages workflow.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 2. Self-hosting checkout development is still more explicit
+
+ On a Guix machine, it’s common to install Guix and then hack on Guix fairly directly.
+
+ On Fruix today, there are really two layers:
+
+ - the installed node Fruix at /usr/local/bin/fruix
+ - a source checkout Fruix via ./bin/fruix
+
+ Those are related, but not identical.
+
+ - /usr/local/bin/fruix is the bundled node-management CLI
+ - ./bin/fruix is what you use when you are editing Fruix source code in a checkout
+
+ So if you’re changing the Fruix codebase itself, you still want a checkout and usually a prepared builder root.
+
+ That means Fruix self-hosted development works, but it’s not yet as seamless as “the installed tool and the hacked-on source tree are
+ one obvious thing.”
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 3. Fruix still has a bootstrap/builder distinction that Guix largely hides
+
+ Guix feels like:
+
+ - install Guix
+ - use Guix
+
+ Fruix currently still feels more like:
+
+ - plain FreeBSD
+ - fruix-bootstrap
+ - prepared Fruix builder
+ - Fruix checkout
+ - then build/install Fruix systems
+
+ Even on a self-hosted node, checkout-based development still assumes the builder world is prepared enough to run ./bin/fruix.
+
+ So compared to Guix, Fruix still has more visible scaffolding around the build/eval environment.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 4. Package coverage and maturity are still narrower
+
+ In Guix, “add the tools I want” usually means a large package universe is already there.
+
+ In Fruix, the self-hosted dev profile is currently a curated working set, not a fully mature package ecosystem yet.
+
+ It already includes useful things like:
+
+ - clang
+ - gmake
+ - autotools
+ - nodejs
+ - npm
+ - ripgrep
+ - tmux
+ - neovim
+
+ But it’s not yet at the point where “anything I’d expect on a mature distro is just there.”
+ For example, we’ve already noted that some things like git are not yet part of the current packaged development profile.
+
+ So Fruix is currently:
+
+ - good enough for serious development
+ - not yet equivalent to Guix’s package breadth and polish
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 5. Fruix’s package provenance is still more transitional
+
+ Guix packages are broadly “normal Guix packages.”
+
+ Fruix today still has a visible distinction between:
+
+ - host-staged / bootstrap-oriented FreeBSD packages
+ - newer native-built pieces
+ - curated FreeBSD base/runtime artifacts
+
+ That means the current system works, but under the hood it is still more transitional than Guix’s unified model.
+
+ You can absolutely develop on it, but Fruix is still on the path toward:
+ - one cleaner package model
+ - native-first defaults
+ - less bootstrap/history leakage in how users think about packages
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 6. Installation and lifecycle are real, but not yet as polished as Guix’s normal story
+
+ Guix has a much more established “install once, reconfigure forever” feel.
+
+ Fruix now has a real installed-node lifecycle:
+
+ - status
+ - reconfigure
+ - switch
+ - rollback
+
+ and that is working on real booted nodes.
+
+ But the broader story is still uneven:
+
+ - node-local lifecycle is in decent shape
+ - deploy still needs more hardening
+ - upgrade is intentionally deferred pending pin/ownership design
+
+ So Fruix is already useful for self-hosting, but not yet at Guix’s level of end-to-end lifecycle maturity.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ ### 7. Fruix is stricter/more explicit about privileged system assembly
+
+ This is more architectural than user-facing, but it matters.
+
+ Fruix now has an explicit privileged assembly policy for things like:
+
+ - image creation
+ - install to raw files
+ - block-device installs
+
+ with metadata and helper-script boundaries.
+
+ Guix doesn’t really expose this in the same way.
+
+ So Fruix is currently more explicit about the dangerous parts of installation/media assembly, which is good, but also makes the system
+ feel less “just do the obvious thing” than Guix in some spots.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ So what is the practical difference in one sentence?
+
+ Guix today is closer to:
+
+ │ “install normal Guix, add packages to your OS config, reconfigure, done.”
+
+ Fruix today is closer to:
+
+ │ “install a self-hosted Fruix node, declare dev/build profiles in the system config, reconfigure, and use the provided dev/build
+ │ environments — while checkout-based Fruix hacking still has a somewhat explicit builder/checkout workflow.”
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ Is that bad?
+
+ Not really — just less finished.
+
+ In some ways Fruix’s current split is actually useful:
+
+ - runtime stays smaller
+ - development environment is explicit
+ - build environment is explicit
+ - native/base work has a clearer boundary
+
+ That’s good for system integrity and reproducibility.
+
+ But from a human UX point of view, it’s still not yet as simple as Guix’s ‘normal system plus packages’ mental model.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ My honest assessment
+
+ If your standard is:
+
+ │ “Can I install Fruix, declare my development tools, reconfigure, and use it as a self-hosted Fruix development machine?”
+
+ then yes.
+
+ If your standard is:
+
+ │ “Is this now as simple and mature as doing the same thing on Guix?”
+
+ then not yet.
+
+ ────────────────────────────────────────────────────────────────────────────────
+
+ The shortest summary
+
+ Fruix currently differs from Guix in these main ways:
+
+ - dev tools live in explicit dev/build profiles, not just one normal system package set
+ - hacking on Fruix itself still distinguishes installed-node Fruix from checkout Fruix
+ - self-hosted source development still assumes a prepared builder environment
+ - package coverage is still curated and incomplete
+ - install/lifecycle is working but not fully polished
+ - some package/build plumbing is still transitional