Nix RFC Process

RFC 0108 proposes replacing the legacy nixos-container subsystem with a new implementation based on systemd-nspawn(5) and systemd-networkd(8).

Key improvements include:

• Reliable Networking: Uses systemd-networkd to ensure network uplinks are available immediately during container boot, preventing services (like nextcloud-setup.service or clamav) from hanging due to missing connectivity.
• Standardized Configuration: Moves away from ad-hoc CLI flags in favor of using native .nspawn units defined via Nix expressions. This allows for easier overrides and support for advanced features like IPVLAN.
• Improved Tooling: Replaces the custom Perl-based nixos-container.pl with a Python implementation and leverages machinectl(1) for standard operations like starting, stopping, and logging into containers.

The Nixpkgs and NixOS documentation is transitioning from Docbook to CommonMark (a flavor of Markdown). This change aims to make documentation easier to write, maintain, and contribute to by using a widely recognized format.

Key requirements for the new documentation website include:

• An easy-to-find "Edit on GitHub" button.
• A high-quality search engine.
• Syntax highlighting for all code blocks.
• A separate page per chapter (moving away from monolithic pages).
• A sidebar table of contents for each chapter.
• Distinctive styling for warning and info boxes.
• Customizable HTML and CSS templates.

The Final Comment Period (FCP) is a formal 10-calendar-day window (ensuring at least 5 business days) used to finalize an RFC decision.

• Trigger: It is called by the Shepherd Team after ample discussion has occurred and tradeoffs have been addressed.
• Motion: Before entering FCP, the Shepherd Team must propose a motion (accept or reject) and all Shepherd Team members must sign off on the motion.
• Purpose: To allow stakeholders to lodge final objections or push back if they believe the FCP was called prematurely.
• Outcome: If substantial new arguments are raised during FCP, the period can be canceled and the RFC returned to development. Otherwise, the Steering Committee will either merge the RFC into accepted or close the PR.

Bootspec is a machine-parsable intermediate representation (IR) that defines a NixOS Generation as a set of memoized facts about a system's closure.

It acts as a stable bridge between the NixOS system definition and bootloader management tools. Instead of bootloader backends (like systemd-boot or grub) having to manually inspect the filesystem or profile directories to discover boot information, they consume the Bootspec definition to generate bootloader entries (e.g., files in /boot/loader/entries/ or grub.cfg).

This approach allows for:

• Uniform feature support: Making it easier to implement features like Initrd Secrets, Multiple Profiles, and Specialisations across different bootloaders.
• Externalized management: Enabling users to implement custom bootloader tools or enterprise-grade policies (like centralized SecureBoot signing) without patching Nixpkgs or NixOS.

In a function application chain, the first element is the function and the rest are arguments.

• Single Line: As many arguments as possible are fitted onto the first line.
• Expansion: If the line length limit is reached, the first argument not fitting on the first line starts a new line with indentation, and all subsequent arguments also start on their own lines.
• Parentheses: If the last argument is parenthesized, the parentheses are typically absorbed while the body is put on a new line with indentation (unless the body is a simple, absorbable term).

# All arguments fit onto the first line
function arg1 arg2

# Line length limit reached
function arg1 arg2 arg3
  arg4
  arg5

# Last argument is a multiline expression
function arg1 {
  more = "things";
}

While the specific toolchain is at the discretion of implementers, the following guidelines apply to the use of CommonMark extensions to ensure interoperability and ease of switching between toolchains:

• Keep extensions minimal: The goal is to remain close to standard CommonMark to facilitate switching generators.
• Acceptable extensions:
  • Tables (as they are infrequent and easy to convert manually).
  • YAML frontmatter for metadata (widely supported by most toolchains).
• Required extensions: Support for defining references between sections is essential for navigation.
• Avoid HTML elements: Do not use HTML <span> or block elements directly in the documentation source, as this complicates generating non-HTML formats like man pages or epub.

Both RFC 0062 and RFC 0017 aim to implement content-addressed paths, but they differ in scope:

• RFC 0017: Proposes a fundamental change to the base model of Nix.
• RFC 0062: Proposes minimal changes to allow a content-addressed model to live in parallel with the current model. This is intended as an incremental approach that will eventually be subsumed by RFC 0017.

The RFC defines two distinct types of comments to improve code clarity and tooling support:

1. doc-comment: A structured comment (using the /** */ syntax) intended to document the code's interface (functions, types, modules). These are designed to be parsed by tools for rendering API documentation.
2. implementation comment: A free-form comment (using standard # or /* */ syntax) used to explain internal design concerns or implementation details that are not part of the public interface.

The pkgs/by-name directory structure introduces several trade-offs that developers should be aware of:

• Scope Limitation: This structure is only applicable to top-level packages using callPackage. It cannot be used for nested packages like python3Packages.requests or those defined via haskellPackages.callPackage.
• Code Ownership: It is no longer possible to use GitHub CODEOWNERS for category-based directories.
• Loss of Categorization: The existing categorization of packages is lost, though proponents argue that categorization was often incomplete or inconvenient.
• Broken Builtins: The use of this structure breaks builtins.unsafeGetAttrPos "name" pkgs. The project has decided that attribute position information is not part of the stable public interface and is inherently unreliable.

Nixpkgs provides experimental support for musl as an alternative to the standard glibc implementation when targeting Linux platforms. This support is treated similarly to adding a new architecture (like Aarch64 or RISC-V).

Key Characteristics

• Experimental: The support is considered experimental and may have limited compatibility compared to x86_64-unknown-linux-gnu.
• Scope: Currently focuses primarily on non-GUI packages due to dependencies like systemd that are not fully portable to musl environments.
• Linking: While musl is often used for static linking, current Nixpkgs support prefers dynamic linking and shared libraries.
• Implementation: Includes musl-based bootstrap, a native musl building stdenv, and a cross-musl stdenv.