docs: add to readme section on how-to install software

[cleeyv]

A few questions and comments arising from this:

• Separate attribute set construction from flake output construction #296

  I only tested with flakes because that's what I'm more familiar with and currently have setup. How much of a priority is testing and documentation of non-flake use cases?

  Is there a good reason that the nixosModule outputs for project services need to be in quotes, like ngipkgs.nixosModules."services.vula"? It seems to break with usual conventions around nix syntax which seems more likely to result in confusion or errors.

• Export all modules and packages in ngipkgs.nixosModules.default

  Perhaps most of the third step could be removed by restructuring things so that all of the nixosModules project outputs are included in the default one? I may dig around and see if I can find a way to implement this.

  In the way I'm proposing to document this there seems to be some minor semantic confusion with the term "modules", especially in the use of ngipkgs.nixosModules.default to import all the packages (which are defined as distinct from modules earlier in the readme). I try to paper over this a bit by referring to the "default packages module for NGIpkgs" (emphasis added) but this is maybe making things worse since it is not referred to this way anywhere else. I don't have concrete ideas yet about if/how this should be improved but thought it was at least worth naming as a potential issue.

• Export packages of a project with their NixOS modules #297

  Currently, the packages associated with a project are not included with the nixosModule for that project. The project services will fail with "package is missing" errors if ngipkgs.nixosModules.default is not also included. This seems like it might be a bug.

[cleeyv]

I only tested with flakes because that's what I'm more familiar with and currently have setup. How much of a priority is testing and documentation of non-flake use cases?

Based on discussion with @fricklerhandwerk (and some examples he drafted and sent on the infra room on matrix) the direct answer to this question is that the documentation should meet the following requirements:

• Documentation of installation on both flake and non-flake systems.
• Both installation methods should be for deployment to a local VM to make it usable regardless of the underlying system details.
• The non-flake installation should use npins.

[lorenzleutgeb]

Is there a good reason that the nixosModule outputs for project services need to be in quotes, like ngipkgs.nixosModules."services.vula"? It seems to break with usual conventions around nix syntax which seems more likely to result in confusion or errors.

Flakes demand that outputs.nixosModules is an attribute set of modules. An attribute set that contains attribute sets (recursively) of modules does not conform with Flakes, will generate warnings and might be incompatible with tooling that depends on this format.

Since one Project may export multiple NixOS modules, using the Project name itself is not a good idea. We opted to use the attribute name path that options in the respective NixOS module are rooted at.

An attribute name which contains dots must be put in quotes to "escape" the dot.

Perhaps most of the third step could be removed by restructuring things so that all of the nixosModules project outputs are included in the default one?

I am against this. The software packaged in NGIpkgs is quite diverse and I don't see why someone using only Vula would want to have an overlay and modules for Rosenpass by default. I am aware that the default overlay currently contains all packages in NGIpkgs, but I would actually like to go the other way here, see also #297 (comment)

Currently, the packages associated with a project are not included with the nixosModule for that project. The project services will fail with "package is missing" errors if ngipkgs.nixosModules.default is not also included. This seems like it might be a bug.

My proposal would not be to pull in all of NGIpkgs but to make it very easy to get an overlay per project and use that.

[fricklerhandwerk]

@cleeyv we also need a note on wiring up the cache so you don't have to build everything yourself.

[lorenzleutgeb]

@cleeyv we also need a note on wiring up the cache so you don't have to build everything yourself.

We could add a module that provides https://github.com/ngi-nix/ngipkgs/blob/main/maintainers/cachix.nix or even make that part of the default module.

[cleeyv]

@fricklerhandwerk I've updated these docs. They are still flakes-only for now until a default.nix for the repo is more stable and tested. As we discussed, I added instructions for deployment to a local VM with QEMU. Since this requires its own configuration.nix for it to be easily used by anyone, I set it up in its own repo at https://github.com/ngi-nix/flakes-ngipkgs

I also still left a second section on installing to an existing NixOS flake. As we discussed, I changed the flake instructions to a single minimal example (based on the Install via Flakes docs for agenix) rather than the more confusing separate steps I had written before.

[fricklerhandwerk]

Suggested change

	git clone -b howto-docs --no-checkout --depth=1 https://github.com/ngi-nix/ngipkgs.git deploy-ngipkgs && # clone an empty version of ngipkgs to a dir called deploy-ngipkgs
	cd deploy-ngipkgs &&
	git checkout howto-docs -- projects && # checkout only the projects directory of ngipkgs
	cp -a projects/. . && # copy contents of the projects directory into the root of deploy-ngipkgs
	rm -rf .git projects default.nix && # cleanup
	git init && git add . # create a new git repo for tracking config changes during deployment
	dir=${1:-deploy-ngipkgs}
	mkdir $dir
	cd $dir
	# TODO: copy all example paths into cwd, get them from the module collection
	# TODO: string-interpolate a list of module names and example paths into flake.nix

[fricklerhandwerk]

You can put this anywhere really, because it's a repo-level helper, not a proper recipe. E.g. //template