From 9b76c3bff5999eb24918157eb8f5c41da0540545 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 19 Apr 2024 16:06:32 +0200
Subject: doc: move note on configuring Nixpkgs in NixOS to the NixOS manual
 (#304307)

that NixOS manual section talks a lot about Nixpkgs package
configuration, which really should not be there but rather in the
Nixpkgs manual itself. but this is a rabbit hole for another time.

Co-authored-by: Dominic Mills <dominic.millz27@gmail.com>
---
 .../configuration/customizing-packages.section.md  | 30 +++++++++++++++++++---
 1 file changed, 26 insertions(+), 4 deletions(-)

(limited to 'nixos/doc/manual')

diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md
index a524ef266eaf..074932b3f110 100644
--- a/nixos/doc/manual/configuration/customizing-packages.section.md
+++ b/nixos/doc/manual/configuration/customizing-packages.section.md
@@ -1,11 +1,33 @@
 # Customising Packages {#sec-customising-packages}
 
-Some packages in Nixpkgs have options to enable or disable optional
-functionality or change other aspects of the package.
+The Nixpkgs configuration for a NixOS system is set by the {option}`nixpkgs.config` option.
+
+::::{.example}
+# Globally allow unfree packages
+
+```nix
+{
+  nixpkgs.config = {
+    allowUnfree = true;
+  };
+}
+```
+
+:::{.note}
+This only allows unfree software in the given NixOS configuration.
+For users invoking Nix commands such as [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build), Nixpkgs is configured independently.
+See the [Nixpkgs manual section on global configuration](https://nixos.org/manual/nixpkgs/unstable/#chap-packageconfig) for details.
+:::
+::::
+
+<!-- TODO(@fricklerhandwerk)
+all of the following should go to the Nixpkgs manual, it has nothing to do with NixOS
+-->
+
+Some packages in Nixpkgs have options to enable or disable optional functionality, or change other aspects of the package.
 
 ::: {.warning}
-Unfortunately, Nixpkgs currently lacks a way to query available
-configuration options.
+Unfortunately, Nixpkgs currently lacks a way to query available package configuration options.
 :::
 
 ::: {.note}
-- 
cgit v1.2.3