Casaderic Compendivm

Declarative Systems With Nix

Tue, 12 May 2026 00:00:00 +0000

A local development environment is usually a set-and-forget affair (until something breaks, anyway). Mine had accreted for years across two machines and two operating systems, and the state of each was known only to whichever shell history survived last. So I rebuilt the whole thing declaratively with Nix, and I have been enjoying the process far more than I expected to.

My daily drivers are a ThinkPad X1 Carbon Gen 6 running NixOS, and a work MacBook Pro running nix-darwin. Maintaining a single source of truth across Linux and macOS sounds like it ought to be miserable. It isn’t. Installation on the ThinkPad was the barebones CLI installer with no desktop environment, and because Nix does the actual work of resolving and building everything, I had my full toolchain running inside of two hours.

All of my configuration lives on GitHub, split across nix-declarative for the flake, modules and hosts, and home-manager for the earlier standalone setup. The usual caveat applies: I am very much still a Nix novice, and you should not take anything in either repository as best practice just yet.

Much of the appeal of Nix is that it declines to tell you how to structure your system. There is an enormous amount of latitude in how you write your declarations, and the ergonomics of the result are entirely yours to decide. In my flake I define kasada@ramiel for the ThinkPad and kasada@israfel for the Mac, and route both to the same terminal configuration, the same Neovim plugin set, and the same CLI tooling. No divergence/duplication/random exceptions like if [[ "$(uname)" == "Darwin" ]] scattered through a shell profile.

What makes that tractable is not the flake so much as the emergant shape that comes with making flakes usable beyond a single host. Rather than writing one configuration per machine, I write classes of capability and compose them, in three layers: modules declare what exists, profiles group them into classes, and hosts name only their own deviations.

Layer 1: Modules Declare Capabilities

Everything installable is a home-manager module under modules/, grouped by what it is rather than by which machine wants it:

modules
├── browsers
│ ├── default.nix
│ ├── firefox/default.nix
│ └── librewolf/default.nix
├── cloud/default.nix
├── containers/default.nix
├── default.nix
├── editors
│ ├── default.nix
│ └── nvim
│ ├── config/ # init.lua, lua/core, lua/plugins, lazy-lock.json
│ └── default.nix
├── files
│ ├── default.nix
│ └── yazi.nix
├── fonts/default.nix
├── fun/default.nix
├── k8s/default.nix
├── languages
│ ├── default.nix
│ ├── go.nix
│ ├── python3.nix
│ └── rust.nix
├── media/default.nix
├── security/default.nix
├── services
│ ├── default.nix
│ └── syncthing.nix
├── shell
│ ├── bash/default.nix
│ ├── default.nix
│ ├── fish/{abbrs,aliases,default,functions}.nix
│ ├── fzf/default.nix
│ ├── starship/default.nix
│ └── zsh/default.nix
├── terminal
│ ├── default.nix
│ ├── ghostty.nix
│ └── tmux.nix
└── vcs
 ├── default.nix
 ├── ghq.nix
 └── git.nix

Each leaf declares a custom.<path>.enable option and gates its entire config block behind it. The Kubernetes module is representative, and about as simple as they get:

{ config, lib, pkgs, ... }:
let
 cfg = config.custom.k8s;
in
{
 options.custom.k8s.enable = lib.mkEnableOption "Kubernetes tooling";

 config = lib.mkIf cfg.enable {
 home.packages = with pkgs; [
 kubectl kubernetes-helm kustomize k9s kubectx
 stern minikube kubeconform kube-linter conftest
 ];

 programs.fish.shellAbbrs = {
 k = "kubectl";
 kctx = "kubectx";
 kns = "kubens";
 };
 };
}

A module owns more than a package list. It owns the shell abbreviations, the environment variables, the config files, and anything else belonging to that capability. Turning custom.k8s.enable on gets me kubectl and my k abbreviation; turning it off takes both away. There is no half-configured state where the tool is present but the ergonomics around it are missing.

Importing a Module Does Not Enable It

modules/default.nix imports every category, but an import only declares the option. Everything defaults to off:

imports = [
 ./editors ./languages ./terminal ./shell ./fonts ./vcs
 ./k8s ./containers ./browsers ./cloud ./security
 ./media ./fun ./files ./services
];

So “is this capability available?” and “is this capability on?” are answered in different files. Every host evaluates the full registry and chooses from it, which means adding a new module never changes an existing machine. That property is what makes the repository safe to extend on a whim.

Adding Extra Options

A module is free to expose more than a toggle. The Go module takes a second option with a sensible default:

options.custom.languages.go = {
 enable = lib.mkEnableOption "Go ambient env (GOPATH/GOBIN) + optional global toolchain";
 installToolchain = lib.mkOption {
 type = lib.types.bool;
 default = true;
 description = "Install a global Go toolchain as a fallback for use outside project dev-shells.";
 };
};

Anything that enables Go inherits the global toolchain. A machine that would rather get its compiler exclusively from project dev-shells sets installToolchain = false and keeps the GOPATH/GOBIN ambient config regardless. The default serves the common case; the override stays one line, at whichever layer needs it.

Granularity is a per-category decision too. Browsers are individually toggleable, because I genuinely want different browsers on different machines. The shell stack is the opposite fish, zsh and starship are co-installed rather than alternatives, so they share a single custom.shell.enable and each child gates its own config on it. fzf sits in the same directory but kept its own toggle, since it is a distinct thing I might not want. The directory tree suggests a hierarchy; the options need not follow it slavishly.

Layer 2: Profiles Compose Classes

Between the modules and the machines sit profiles, which are the classes I actually compose from. profiles/home/base.nix is the interactive core (what I want on anything I have a home/ dir on), headless boxes included:

custom = {
 editors.nvim.enable = true;
 files.yazi.enable = true;
 shell = {
 enable = true;
 fzf.enable = true;
 };
 terminal.tmux.enable = true;
 vcs = {
 git.enable = true;
 ghq.enable = true;
 };
};

profiles/home/workstation.nix layers on everything that presumes a real personal machine, like a graphical session, dev toolchains, cloud accounts, media, toys:

custom = {
 fonts.enable = true;
 fun.enable = true;
 media.enable = true;
 security.enable = true;
 services.syncthing.enable = true;
 terminal.ghostty.enable = true;
 cloud = {
 aws.enable = true;
 gcp.enable = true;
 oci.enable = true;
 };
 languages = {
 go.enable = true;
 rust.enable = true;
 python3.enable = true;
 };
};

profiles/home/darwin.nix is the exception though. It just holds macOS glue rather than adding some capability (which is a concession that I kind of hate, but it’s the only way to resolve on a non-pure Nix system). Because only Darwin hosts import it, nothing inside needs an isDarwin guard and therefore Linux never evaluates it. This also keeps Darwin-only packages, like per orbstack, off Linux entirely. Platform branching handled by composition instead of conditionals.

Layer 3: Hosts Declare Only Deviations

The payoff is that a host file is nearly empty. Here is the Mac in full:

{ ... }: {
 imports = [
 ../../profiles/home/base.nix
 ../../profiles/home/workstation.nix
 ../../profiles/home/darwin.nix
 ];

 home = {
 username = "kasada";
 homeDirectory = "/Users/kasada";
 };

 # Per-host extras (the base profile already provides the universal set).
 custom = {
 browsers.firefox.enable = true;
 k8s.enable = true;
 containers.enable = true;
 };
}

The ThinkPad is the same file minus the Darwin profile and minus the container work, and my headless box imports base.nix and nothing else:

Host	Role	Profiles	Host-local extras
`israfel`	work MacBook Pro	base, workstation, darwin	firefox, k8s, containers
`ramiel`	ThinkPad, NixOS	base, workstation	firefox
`nixbox`	headless NixOS	base	—

Populating a new machine is therefore a matter of writing five lines of host file and choosing which classes apply. Everything downstream (dotfiles, shell abbreviations, Neovim plugin set, LSP servers, environment variables) arrives assembled. Nothing to remember; perfect for me brain! *smiles*

Resources Worth Bookmarking

The reason any of this is tractable for a newcomer is the tooling the community has built (something, something, we stand on the shoulders of giants, something, something). Nix’s language and module system are not especially forgiving, but the searchable references removed most of the guesswork for me:

NixOS Packages — the official package registry, and the first place to check.
Home Manager Options — indispensable for finding the exact option path for user-level tooling.
MyNixOS — good for browsing options and reading how other people have arranged their configurations.
Nix.dev — the official tutorials, and readable ones at that.

Takeaway

Reproducing an entire OS and development environment from a single Git repository was worth the cost for me, but the reproducibility is only half of it. I did not anticipate what falls out of separating a capability’s definition from its activation: modules describe what a thing is, profiles describe classes of machine, and hosts describe only their own deviations. I think that is the beauty of Nix that those incessent Nix guys on forums always rant and rave about (I suppose I am one now, too). Adding a tool touches one file; standing up a new machine touches one file; it’s so nice. I am still working out how best to factor all of this out, and I still expect to rewrite plenty of it. But declaring what I want and letting the package manager work out how to get there is the right division of labour, and it is difficult to go back to anything else.

Zero-Allocation Logging in Go

Tue, 07 Apr 2026 00:00:00 +0000

Go’s structured logging library (log/slog) is quite the clever piece of standard library code. This is thanks to the processing of log attributes {key:value} with zero heap allocations. And despite the slog.Logger interface (inspired by packages uber-go/zap and rs/zerolog) now long being the go-to idiom for any generic logging use-cases in Go; it is additionally highly-optimized for use in application hot-paths.

Wanting to know exactly how Go achieves this with the the compiler optimizing away unnecessary overhead, I wrote a quick mock logger following the log/slog implementation and analyzed the output assembly via compiler explorer (go.godbolt.org) (thank you Matt Godbolt, sire).

In the following sections, I am going to walk through how the Go compiler avoids common “interface boxing” (allocating variables to the heap when converting to interfaces), fully inlines function calls to save CPU cycles, and passes data between stack frames without copying entire arrays.

Code Setup

Here is a stripped-down look at how a zero-allocation logger takes in attributes. Instead of using a variadic type T set (...any) (which forces Go to box primitives into interfaces on the heap), we define a concrete intAttr struct.

package p

import "fmt"

func myFunction(x int) int {
	log("my msg", newIntAttr("k1", x), newIntAttr("k2", 2))
	return 0
}

//go:noinline
func log(msg string, attrs ...intAttr) {
	fmt.Print(msg)
	for _, attr := range attrs {
		fmt.Print(attr)
	}
}

type intAttr struct {
	key string
	value int
}

func newIntAttr(k string, v int) intAttr {
	return intAttr{
		key: k,
		value: v,
	}
}

(I suggest you follow along using the same code above to fully understand this process).

Your prize for compiling this is a fat block of Plan 9 Assembly. But before we decode the output, let’s first address the weird symbol naming.

Checking Out `command-line-arguments`

If you look at the raw assembly, you’ll see memory locations and function calls prefixed with command-line-arguments, like this:

CALL command-line-arguments.log(SB) or MOVQ DX, command-line-arguments..autotmp_8+40(SP).

Why? In Go’s assembly dialect, the assembler attaches human-readable symbols to memory locations to help the debugger and the Garbage Collector map machine code back to your source file. When you compile a standalone Go file without a properly initialized Go module (like in a compiler explorer sandbox), the compiler assigns it a default package name of command-line-arguments.

The ..autotmp_8 simply means the compiler created a hidden, “automatic temporary” variable on the stack to hold our data. The CPU never sees these names; it only sees the raw memory offsets.

Optimization 1: Function Inlining & Struct Initialization

In our Go code, we call newIntAttr("k1", x) and newIntAttr("k2", 2). You might expect the assembly to set up a stack frame, push arguments, jump to the newIntAttr function, and return a struct.

The Go compiler is much smarter than that. It completely inlines the calls to save CPU cycles.

A Go string is a 16-byte struct (an 8-byte pointer to the text, and an 8-byte length). Our int is 8 bytes. That means each intAttr struct is exactly 24 bytes. Because we pass two of them in our variadic ...intAttr slice, the compiler needs 48 bytes of contiguous memory.

Instead of calling newIntAttr, the compiler manually writes the data directly to the stack, byte by byte:

 // --- Building the first intAttr: newIntAttr("k1", x) ---
 // Grab the pointer to the "k1" string bytes and put it in DX
 LEAQ go:string."k1"(SB), DX 
 // Write the Pointer to SP+40
 MOVQ DX, command-line-arguments..autotmp_8+40(SP) 
 // Write the string Length (2) to SP+48
 MOVQ $2, command-line-arguments..autotmp_8+48(SP) 
 // Write the integer value (x, held in AX) to SP+56
 MOVQ AX, command-line-arguments..autotmp_8+56(SP) 

 // --- Building the second intAttr: newIntAttr("k2", 2) ---
 // Grab the pointer to the "k2" string bytes and put it in DX
 LEAQ go:string."k2"(SB), DX
 // Write the Pointer to SP+64
 MOVQ DX, command-line-arguments..autotmp_8+64(SP)
 // Write the string Length (2) to SP+72
 MOVQ $2, command-line-arguments..autotmp_8+72(SP)
 // Write the integer value (2) to SP+80
 MOVQ $2, command-line-arguments..autotmp_8+80(SP)

Optimization 2: Escape Analysis and the Stack

Notice where it wrote those 48 bytes: +40(SP) up through +80(SP). SP is our Stack Pointer.

If we had passed our attributes as ...any (the standard fmt.Printf approach), the compiler wouldn’t know the size or type of the arguments at compile time. It would be forced to allocate them dynamically on the heap (a process called “boxing”), which requires the Garbage Collector to clean them up later.

Because we used a concrete type (intAttr), the compiler’s Escape Analysis kicked in. It realized this variadic slice never “escapes” the lifecycle of myFunction and log. Therefore, it entirely skips the runtime.newobject heap allocation and safely builds the array directly within myFunction’s local stack space. This is the zero allocation we are looking for!

Optimization 3: The Register-Based Calling Convention

Now that we have a 48-byte backing array on myFunction’s stack, how do we pass it to log? A common misconception is that the whole array is copied into the new function’s stack frame.

Thanks to Go’s modern register-based ABI (Application Binary Interface), arguments are passed to functions via CPU registers whenever possible. Our log function expects two arguments: a string (Pointer, Length) and a slice (Pointer, Length, Capacity).

Right before the CALL to log, the compiler packs these 5 words of data into 5 CPU registers:

Reg	Arg	Value	Assembly Instruction
`AX`	`msg` Ptr	`"my msg"` Addr.	`LEAQ go:string."my msg"(SB), AX`
`BX`	`msg` Len	10	`MOVL $10, BX`
`CX`	`attrs` Ptr	Stack Array Addr.	`LEAQ com...autotmp_8+40(SP), CX`
`DI`	`attrs` Len	2	`MOVL $2, DI`
`SI`	`attrs` Cap	2	`MOVQ DI, SI`

 CALL command-line-arguments.log(SB)

When execution jumps into log, the 48 bytes of array data are left untouched, sitting safely back in myFunction’s stack frame. The log function simply uses the pointer passed in the CX register to reach “up” the stack and read the structs one by one.

Takeaway

By passing a 24-byte slice header in registers rather than copying a whole 48-byte array across stack frames, and by avoiding the heap completely, Go keeps function calls blazingly fast. This combination of inlining, stack allocation, and register-passing is that which makes our log/slog so performant. Lovely, isn’t it?

Casaderic Compendivm

Declarative Systems With Nix

Layer 1: Modules Declare Capabilities

Importing a Module Does Not Enable It

Adding Extra Options

Layer 2: Profiles Compose Classes

Layer 3: Hosts Declare Only Deviations

Resources Worth Bookmarking

Takeaway

Zero-Allocation Logging in Go

Code Setup

Checking Out command-line-arguments

Optimization 1: Function Inlining & Struct Initialization

Optimization 2: Escape Analysis and the Stack

Optimization 3: The Register-Based Calling Convention

Takeaway

Checking Out `command-line-arguments`