Guides and Recipes overview

[fricklerhandwerk]

This tracking issue is to keep an overview of guides for most common use cases.

• Dependency management with npins (with Home Manager)
• Automatic environments with direnv (with Home Manager)
• Package scaffolding (with nix-init)
• Building a bootable NixOS ISO image
• Running pre-built binaries on NixOS
• Nix post-build hooks #463
• Using a specific package version #490
• Managing secrets (no optimal solution)
• Overview of package customisation #731
• Overview of pinning techniques #907 (no optimal solution)

Guides should complement the tutorials, and should be quite short. They can even duplicate important topics to have a condensed form for quick lookup. Related: #910

A good example is the guide on sharing dependencies with shell.nix. It starts with a very small sample to show the pattern (which requires some proficiency with the Nix language to grasp quickly), and expands on the details below the fold.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-02-22-documentation-team-meeting-notes-110/40145/1

[malteneuss]

Would the following topics make sense as well here?

• remote builders. I cleaned up https://wiki.nixos.org/wiki/Distributed_build but it would benefit from another round of compressing the content and become official.
• Cross-compiling NixosConfigurations. Give some guidance which style of https://discourse.nixos.org/t/recommended-style-to-cross-compile-flake-nixossystems/45305/2 is recommended when. Maybe even offer an alternative explanation to the NixOS manual.
• NixOS tests as part of a flake; a small addition to the existing guide at https://nix.dev/tutorials/nixos/integration-testing-using-virtual-machines.html

[fricklerhandwerk]

@malteneuss absolutely!

I currently have the distributed build scenario at the top of my mind, recently updated the Nix manual on the topic, and would gladly review contributions.

Updating the cross compilation article with something that actually works would also be great.

[vuongpd95]

I have the recent know-how of a full LSP with neovim setup on NixOS 25.05 (with home-manager) without using any neovim package manager (e.g. Vim Plug) or language server binaries manager (e.g. Mason) since they go against NixOS design.

I have faced a lot of difficulties setting everything up but managed to do it in the end. The developer experience is on par with my other system running Ubuntu.

I think it can be helpful for other people but not sure if nix.dev recipes is the right place to host it.

The setup:

• is a single configuration.nix file with inline home-manager neovim extraLuaConfig. It's not broken into multiple files so it's very easy to follow.
• has home-manager wezterm basic configurations inline as well.
• neovim LSP setup with lsp-config and auto-completion setup.
• demo setup for multiple popular language servers (Taliwindcss, Svelte, Vue, TS, PHP, Nix, Bash, Lua, Ruby, Godot) with their own gotchas.

I can break the above setup into multiple recipes.

[fricklerhandwerk]

@vuongpd95 that sounds quite awesome! For the sake of usability and reviewability it would be ideal to add small independent chunks that build on top of each other and lead to what you're describing. Because cleanly setting up home manager is valuable independent of the editor, and so is adding libraries to the module evaluation. And then if using nixvim there should be very little left to do because the details are maintained there. All the tutorial or guide would need to do is pick one (in principle arbitrary) end-to-end story and refer to reference documentation from there.

Ideally of course we would also have a collection of useful examples, but the infrastructure and and contributor documentation for making sure they work as intended isn't in place yet. (There's something in the works at https://ngi.nixos.org but it's not ready to be replicated yet.) So I'd consider that a stretch goal.

Getting any small thing in the direction of the outline merged would be really really good already.