Is there documentation for nixpkgs.lib.nixosSystem?

Help
1

The last couple of days I’ve been dabbling in NixOS. I’ve arrived at this flake which specifies a “minimal base” system and also a separate system that is specific to a certain machine I have that has a static IP for one of its network interfaces.

At some point, I discovered that I can spin these systems up in a VM by running:

nix run .#nixosConfigurations.base.config.system.build.vm

I don’t remember how I discovered that, I think it may have been from asking an LLM what the Flake equivalent to the command described here is.

I’d like to learn more about this as it seems like a super useful capability, but I can’t find any information about it online. In fact, I can’t find any documentation for nixosSystem in the nixpkgs manual at all. This latter detail surprised me, because there seems to be a doc-comment on the definition, but perhaps it’s related to the statement in the comment above which says nixosSystem isn’t part of the nixpkgs library but rather the flake…

So, does any documentation exist? Or am I best off just diving into the code in nixpkgs to understand how this thing works and if it can be adapted to more usecases?

1 Like
2

That’s the way to go, unfortunately. FWIW, it’s the system derivation. I use it to make nix run boot up the VM: tlaternet-server/flake.nix at master - tlaternet/tlaternet-server - Forgejo: Beyond coding. We Forge.

YSK that you can configure the VM settings set by the startup script (memory size, networking, etc.) with virtualisation.vmVariant.

It’s an incredibly powerful tool, if you know how to configure your qemus it gets even better. Feel free to ask if you need a hand, I’ve gotten to the point of spinning up pretty convincing staging environments with it.

3

Cool, thanks, I did eventually find the virtualisation.* options (it also took me a while to figure out I needed to import ${modulesPath}/virtualisation/qemu-vm.nix - eventually I realised this by just searching all of GitHub for uses of virtualisation.forwardPorts and using what I found as examples).

And yes, this does seem extremely powerful. At my work I have an internal document listing all the different tools I know about that wrap QEMU. This is a particularly unique and interesting one! I should add the stuff about NixOS and publish that document…

1 Like
4

No docs exist because this is a flakes-specific function, and flakes are underdocumented.

By the way, you could also discover this by checking the code for nixos-rebuild build-vm: