How to expand and test module?

Hello, could anyone give me easy guidance on how I could do the procedure described in the title of this post, preferably with the modern cli (nix flake, nix build, …)?

To make this more clear, let me give you an example:
The minecraft-server module lacks an option to define server operators, so at the moment you have to do it non declarative by editing ops.json. What I would like to do is to add that option (probably services.minecraft-server.operators), somehow test it locally and if it works send a pull request on nixpkgs so it gets merged and thus available to everyone.

Unfortunately I have absolutely no idea how I would do this, it is my first time trying to make a contribution and I cannot really find a guide on how to extend modules. I would prefer to start with best practices, so if experienced members could explain this in easy words for me, I would very much appreciate it.

Thank you in advance!

You’re right, there’s some documentation about contributing to nixpkgs in general, but it’s not really helpful for your case.

The basics are quite simple:

$ git clone
$ cd nixpkgs/nixos
$ nix build -f default.nix system

This basically builds your current NixOS configuration with all the packages and modules from the repository you just cloned. It should create a symlink to the built system called result in the current directory, which you can then explore to ensure that the files were generated as you expect.

It doesn’t enable the system in any way, though. For that, you would need to call ./result/bin/switch-to-configuration. This is basically what nixos-rebuild switch does after it built your system config as well.
However, you can also replace system in the nix build call above by vm. That way, you build a vm that you can then run with qemu to test the result completely separately from you running system.

Once you built and activated/launched your config, you just test the module by checking whether the service is up and whether it was configured as you expect.

If you need to make a lot of iterations, it might make sense to create a tiny configuration and build that instead. So create a file test-config.nix with this content:

{ pkgs, lib, config, ... }: { = {
    enable = true;
    # add more options as needed for your testing

And build it like so:

$ NIXOS_CONFIG=$PWD/test-config.nix nix build -f default.nix system

For some things, like generating files and figuring out how exactly some functions work, it might also make sense to use nix repl:

$ nix repl flake:nixpkgs
warning: future versions of Nix will require using `--file` to load a file
Welcome to Nix 2.15.1. Type :? for help.

Loading installable ''...
Added 19592 variables.
nix-repl> lib.concatLines [ "x = 2;" "y = 3;" "z=x+y;" ]
"x = 2;\ny = 3;\nz=x+y;\n"

This is much quicker than changing files an rebuilding every time. To find out what functions are available, I recommend searching on noogle.

Additionally, you may want to look at the code of other NixOS modules that offer similar functionality as what you want to implement to see how certain things (like adding an additional option) are done.

Hope this helps you get started!

1 Like

Thank you very much! I will try to go through that and tell you how it worked out :slight_smile:

@iFreilicht do you know how I fix this, it occurs when executing the nix build -f default.nix system

error: file ‘nixos-config’ was not found in the Nix search path (add it using $NIX_PATH or -I)

   at «none»:0: (source not available)

I am using NixOS-WSL with a flake setup if that is important.

Ah so that means you’re on windows? I’m not super experienced with that, and I can’t find good docs on NixOS-WSL, either.

What is the path of your configuration.nix? You can export that to NIXOS_CONFIG, that should fix the error you’re seeing. Does NixOS-WSL even use nixos-rebuild?

@iFreilicht yep, nixos-wsl basically does everything like a normal nixos system. Configuration.nix path is /home/shaniag/nixos-config

Simple flake setup with multiple configurations, I just apply changes with sudo nixos-rebuild switch --flake .

I already did this stuff to have nixpkgs in my path, thought there would be something similar for this one:

          { nix = {
              nixPath = [ "nixpkgs=${nixpkgs}" ];

Yes indeed, you can add "nixos-config=/home/shaniag/nixos-config/configuration.nix" to that list. That ensures that <nixos-config> in default.nix will resolve.

@iFreilicht now it gives me the errorthe option home-manager does not exist. I pass that via the flake, so can I somehow tell it to know that or manually pass it?
I also messaged you on Matrix, I think it would be easier than here if you do not mind.