cnix

nixram

Summary

nixram is an early-stage attempt to describe related Linux memory-policy choices through one Nix interface. It connects an explicit RAM level with zram or zswap policy, systemd-oomd settings, and selected kernel controls.

The proposition is modest: make the policy easier to inspect and discuss as a whole. The referenced revision contains substantial implementation, documentation, and check definitions, but this CNIX pass did not reproduce a successful build or runtime result.

What it is

  • A Nix flake exporting NixOS, system-manager, and Home Manager modules.
  • A shared table of fourteen RAM-level anchors used by the host modules.
  • A detect-level application that reads the target machine’s memory and prints a level assignment for an operator to review and commit.
  • A public, pre-alpha implementation with detailed rationale and declared evaluation and virtual-machine checks.

The three module outputs do not promise identical scope. NixOS carries the full host-facing interface. The system-manager output targets a narrower non-NixOS use case, while Home Manager covers selected user-session policy.

How it works

The operator selects a level explicitly. Host modules read the corresponding entry from levels.nix and use it to derive defaults across their supported memory-policy surfaces. Hardware detection remains a separate, run-once aid; it does not introduce live machine state into Nix evaluation.

The NixOS module declares zram, zswap, and none modes. Assertions cover several invalid combinations, including zswap without a backing swap device. The repository also contains separate modules for zram, zswap, systemd-oomd, and sysctls, alongside checks intended to exercise evaluation and selected virtual-machine behaviour.

Those definitions are inspectable evidence of intent and implementation. They are not, by themselves, evidence that a particular revision passed in CI or behaved well on a given workload.

How to configure it

The documented shape is to import the module for the target environment, enable nixram, select a level, and then choose the relevant mode and optional policy surfaces. An adopter should first evaluate the exact source revision, run its checks, and review the level table against the intended kernel, hardware, and workload.

System-manager does not support the project’s zram backend. Home Manager is a separate user-session module rather than a substitute for either host module.

The level anchors at the referenced revision are fourteen explicit sizes: 256M, 512M, 1G, 2G, 4G, 6G, 8G, 10G, 12G, 16G, 24G, 32G, 64G, and 128G (see levels.nix). Named options around the core enable, level, and mode surface include the systemd-oomd controls, the zram profile, the zswap profile, and escape-valve hints such as swappinessHint, pageClusterHint, and vfsCachePressureHint (see modules/). The oomd layer is off by default at the 256M anchor (see modules/oomd.nix).

Tutorial

This example uses invented values against the real option interface from the referenced revision. The interface shape below was evaluated with the actual module at the pinned revision using synthetic values only; no system was rebuilt or booted.

# Synthetic example: invented repository and host choices.
{
  inputs.nixram.url = "github:example-org/nixram-demo";
 
  imports = [ inputs.nixram.nixosModules.nixram ];
 
  nixram = {
    enable = true;
    level = "4G";
    mode = "zram";
    oomd.enable = true;
    sysctls.enable = true;
  };
}

The repository also exposes its detection helper through a flake app:

# Synthetic example: public placeholder only.
nix run github:example-org/nixram-demo#detect-level

Treat its output as a proposal to review and commit, not as an ongoing hardware probe.

Evidence and limits

This page is bound to public revision 217de70fa3ede45ce56abfc8fd9b0a1682a72fcf. That tree contains the flake outputs, levels.nix, module implementations, documentation, and declared checks discussed above.

CNIX has not independently established a successful evaluation, build, boot, deployment, performance improvement, or workload result for that revision. The tutorial interface above was evaluated against the real module at that revision with synthetic values: enable, level, mode, and policy toggles pass type checking with no residual assertions. The source also contains policy rationale and historical context; this page does not treat either as measured validation.

The same revision carries the deeper reference the legacy project docs page drew on: the full per-value level table with source marks (docs/levels.md), the tier-by-tier rationale and judgement calls (docs/rationale.md), the option reference (docs/index.md), and the glossary. That legacy /docs.html page is therefore covered by this concept plus its pinned sources, and its route redirects to the technical reference rather than living on as a second copy.

nixram builds on existing Linux and Nix mechanisms rather than replacing them: zram or zswap, systemd-oomd, kernel sysctls, NixOS modules, system-manager, and Home Manager. Its relationship to other Corbet Nix projects is currently a shared design direction, not evidence of runtime integration.