Cross-compilation support, broken into small incremental commits

[randomizedcoder]

Hey @nvmd! 👋

First off — really awesome to see the progress you've been making since issue #154! The ffmpeg-8 addition, the refactor-linux branch work, the firmware sources extraction, and the cross-compilation support you've already started building out — all great stuff. It's clear you've been thinking hard about the right architecture, and it shows. Thanks for being so welcoming about merging these changes back!

What's in this PR

As we discussed in #154, I've taken the big cross-compile branch and broken it up into 17 small, incremental commits that (hopefully!) each make sense on their own and step-by-step build towards the full cross-compilation solution. The idea is that you can review each commit individually, and at every step the repo should be in a coherent state.

Here's the rough progression:

1. Formatting — nixfmt-rfc-style applied first, so it doesn't pollute later diffs
2. Logo + docs — the RPi logo images, ffmpeg docs
3. FFmpeg cleanup — remove deprecated ffmpeg 4/6, add mkFfmpegRpi helper
4. Pisugar-3 refactor + sysctl module
5. Kernel/firmware refactoring (commits 6a–6e) — this is the big architectural piece, done incrementally
6. Overlay + module registries
7. Dev-shells + tooling (Makefile, etc.)
8. Board module compatibility — dual pkgs.* + nixos-raspberrypi.packages support
9. Cross-compilation infrastructure — the main event!
10. Flake.nix refactor — wiring it all together
11. Documentation — cross-compilation guide, README updates

Kernel/firmware organization — two approaches

This is probably the most important architectural decision in the PR, so I wanted to walk through the thinking. When looking at how to organize kernel versions, firmware, and their relationships, we considered two approaches:

Your current approach (modular/hierarchical)

This is what's on develop and refactor-linux today — kernel data is split across multiple files in a directory structure:

• pkgs/linux-rpi/{package.nix, kernels.nix, linux-sources.nix, linux-patches.nix} (4 files)
• overlays/firmware-sources.nix (separate firmware version list)
• Overlay ordering is implicit in flake.nix
• ~13 total files, ~963 lines

Our proposed approach (data-driven/consolidated)

Instead of a directory hierarchy, we encode the kernel/firmware relationships as explicit data tables:

• kernelMatrix in vendor-kernel.nix — a single table mapping every kernel version to its supported board models. Adding a new kernel = adding one row.
• bundleSpecs in linux-and-firmware.nix — explicitly pairs each kernel with its matching firmware. The relationships are visible at a glance.
• firmwareVersions / wirelessFirmwareVersions in vendor-firmware.nix — structured attrsets with mkFirmware/mkWirelessFirmware constructors instead of procedural definitions.
• commonFixupStructuredConfig + mkFixupStructuredConfig in kernels.nix — deduplicates kernel config fixups that were previously repeated across every kernel definition.
• overlays/default.nix — explicit overlay registry with documented ordering (cross-fixes → pkgs → bootloader → vendor-kernel → vendor-firmware → kernel-and-firmware → vendor-pkgs).
• pkgs/linux-rpi.nix — single consolidated file instead of the directory
• ~9 total files, ~800 lines

Comparison

Criterion	Your approach (modular)	Our proposal (data-driven)
Files to touch for new kernel	4	3
Files to touch for new firmware	2–3	2
Total files / lines	~13 / ~963	~9 / ~800
Code deduplication	Good	Better (commonFixupStructuredConfig)
Discoverability	Data scattered across files	Co-located in data tables
Overlay ordering	Implicit in flake.nix	Explicit + documented in overlays/default.nix
Cross-compile readiness	Needs additions	cross-fixes overlay built-in, first in chain
Self-documenting	Minimal	Data tables show version↔board↔firmware relationships

Why we recommend the data-driven approach

The key insight is that kernel/firmware management is fundamentally a data problem — you have a matrix of versions × boards × firmware pairings. Encoding this as explicit data tables (rather than spreading it across a directory hierarchy) makes the relationships visible at a glance and reduces the number of places you need to touch when adding new versions.

It also makes the overlay ordering explicit and documented, which is especially important for cross-compilation where cross-fixes must come first in the chain.

The commits 6a–6e introduce this incrementally so you can see exactly what each step changes:

• 6a: Consolidates pkgs/linux-rpi/ directory back to single pkgs/linux-rpi.nix
• 6b: Extracts commonFixupStructuredConfig helper
• 6c: Data-driven firmware versions
• 6d: Data-driven vendor-kernel with kernelMatrix
• 6e: Data-driven linux-and-firmware with bundleSpecs

Regarding commonFixupStructuredConfig

I totally hear your point from #154 about potentially auto-generating fixups in the future. The commonFixupStructuredConfig helper is designed to be easy to replace — if you build a generator tool later, you'd just swap out the data it produces. The helper is really just factoring out the duplication that exists today, not locking in any particular approach.

Board module compatibility

The board modules now support both access patterns:

• pkgs.* via overlays (needed for cross-compilation to work)
• nixos-raspberrypi.packages as fallback (backward compatibility)

This is done with: { nixos-raspberrypi ? null, self ? nixos-raspberrypi, lib, pkgs, ... }:

Testing

The cross-compilation has been tested building installer images from x86_64:

nix build .#installerImagesCross.x86_64-linux.rpi5
nix build .#packages.x86_64-linux.linux_rpi5

AI assistance (Claude) was used for code organization, formatting, and drafting this PR — but the architectural decisions, Nix patterns, and cross-compilation approach are all human-designed and tested on real hardware.

How to review

I'd suggest reviewing commit-by-commit (the GitHub "Commits" tab works well for this). Each commit message explains what it does and why. If any particular commit doesn't make sense or you'd prefer a different approach, happy to rework it!

Also totally fine if you want to cherry-pick just some of these commits, or if you'd prefer I split this into multiple smaller PRs (e.g., formatting + ffmpeg cleanup as one, kernel refactoring as another, cross-compilation as a third). Whatever works best for your workflow! 🙂

Closes #154

🤖 Generated with Claude Code

[ivanoovii]

Hi! Thanks for this great PR! I've already used it to create installers for my RPi4 and 5. However, what I find rather inconvenient is that I have to clone the repo to change custom-user-config, since it is defined in in the let block in installers/default.nix. I've created an issue #170 which describes this problem in the original codebase, but because this PR might be merged soon, maybe we also should discuss exposing the config here.

[blaggacao]

@randomizedcoder To help ensure there's no misunderstanding waiting to be discovered, I had read:

I've scrolled through all of it. I would carefully say, that it would make sense to potentially accept all of it, but definitely in several PRs [PRs not commits].

That's also what I would expect as a maintainer to be able to review one change at a time.

@nvmd Don't know, maybe formatting first (at some checkpoint that is suitable to you) is a better approach since these AI tools seem to always be eager to format each commit and it might be hard to separate this out (or teach the agent to not touch formatting) 🤷 - not sure though.

[nvmd]

@randomizedcoder To help ensure there's no misunderstanding waiting to be discovered, I had read:

I've scrolled through all of it. I would carefully say, that it would make sense to potentially accept all of it, but definitely in several PRs [PRs not commits].

That's also what I would expect as a maintainer to be able to review one change at a time.

Thanks @blaggacao for noticing that. I guess I got overwhelmed while reviewing the PR, so that I've forgotten to bring this to the attention.

@randomizedcoder thank you for splitting this into the commits! It's also very important that those will be also split across multiple PRs, like we discussed earlier, so that we could review and accept them independently and incrementally.

As for the for formatting, I'm not yet sure how to deal with it.
I guess we should stick with the code style used in the community at large (and nixpkgs) at some point (even though I personally don't like the RFC formatting for several reasons).

On the other hand doing a global reformatting will somewhat obscure with git history, especially in the short term. To mitigate them, I would prefer the gradual approach of integrating the meaningful changes with the formatting updates. As far as starting on the so to say, function level, for example.

That can be, however, quite labor-intensive: "as simple as" adding only the selected portion of the file to the commit after the reformat for the humans, but probably more complicated to "tame" the AI agent to do that right.
However, I wouldn't want to sacrifice the tokens spent by the AI at the expense of maintainers (being human or AI) in the future.

The resolution being for now, let the formatting be the separate PR that we'll discuss after we're done with the meaningful changes.

[nvmd]

For the @randomizedcoder and the Claude Code concerning linux/firmware approach: I don't think the lists of kernel and firmware sources will go away because they help separate the concerns better. More precisely the logic of generating and organizing derivations from the data being the sources for such derivations.