dream2nix Documentation

dream2nix is a modular framework designed to automate reproducible packaging across various language ecosystems. Its primary goal is to provide a standardized, generic, and customizable framework for automated packaging solutions (often referred to as '2nix' solutions), aiming to reduce the effort required to develop new converters and simplify package updates.

Key Goals:

• Modularity and Customizability
• Maintainability and code de-duplication
• Common UI across different 2nix solutions
• Exploration and adoption of new Nix features
• Simplified updating of packages

In standard nixpkgs, changing package options often requires chaining multiple overrideAttrs and override functions. In dream2nix, you can use the module system to declare a package as a module, allowing you to set options (like flags) and the package name directly within a single attribute set. This avoids complex function chaining and makes the configuration more declarative.

Instead of chaining overrides, you can use imports to bring in the package definition and then set specific attributes like name or flags directly.

{
  htop-mod = {
    imports = [./htop.nix];
    name = lib.mkForce "htop-mod";
    flags.sensorsSupport = false;
  };
}

The dream2nix v1 API is designed around three distinct levels of users, each with different responsibilities and interaction patterns with the tool:

1. Integration Maintainers (Level 1): Users responsible for maintaining language2nix integrations (the logic that converts a specific language's ecosystem into Nix expressions).
2. Package Maintainers (Level 2): Users who utilize dream2nix to generate and maintain Nix derivations for specific software packages.
3. Consumers (Level 3): End-users who use and customize the packages that were produced via the dream2nix workflow.

The mkDerivation-mixin is a package module based on the mkDerivation builder from nixpkgs. It is functionally equivalent to the standard dream2nix mkDerivation module, with one key difference in configuration structure: all options are declared at the top-level of the module instead of being nested under a mkDerivation.[...] attribute set.

Use this mixin when you prefer a flatter configuration structure for your package definitions.

Unlike mkDerivation in nixpkgs, which may silently ignore invalid options or incorrect types, dream2nix modules provide strict validation:

• Type Safety: If you provide a value of the wrong type (e.g., a string instead of a boolean for dontPatch), dream2nix raises an informative type error.
• Typo Detection: If you misspell an option name (e.g., nativBuildInputs instead of nativeBuildInputs), dream2nix raises an error stating that the option does not exist, rather than building with the error silently ignored.

In previous versions, integrating existing lang2nix solutions into dream2nix was difficult due to strict standards imposed by the project. The v1 API removes most of these restrictions to simplify integration.

Depending on your requirements, you can integrate tools using either pure or impure methods:

• Pure integration: Use integrate lang2nix tool (pure) (see ../v1-api/integrating/integrate-lang2nix-pure.md).
• Impure integration: Use integrate lang2nix tool (impure) (see ../v1-api/integrating/integrate-lang2nix-impure.md).

The package-func module provides an interface for integrating standard Nix derivation builder functions (such as mkDerivation, buildPythonPackage, etc.) into the dream2nix workflow.

To use it, you provide the builder function in package-func.func and its corresponding arguments in package-func.args. The module then wraps the result into a package exposed under config.public, while making the raw result available via package-func.result.