nixos/alsa: reintroduce hardware.alsa.enablePersistence (#373529)

If you set `sound.enable` in your configuration:

  - If you are using Pulseaudio or PipeWire, simply remove that option

  - If you are using ALSA as your only sound system (no sound server), set `hardware.alsa.enable = true` instead

  - If you are not using an external sound server, and want volumes to be persisted across shutdowns, set `hardware.alsa.enablePersistence = true` instead

If you set `sound.enableOSSEmulation` in your configuration:

  - Make sure it is still necessary, as very few applications actually use OSS

  - If necessary, set `hardware.alsa.enableOSSEmulation = true`

  - If necessary, set `boot.kernelModules = [ "snd_pcm_oss" ]`

If you set `sound.extraConfig` in your configuration:

  - If you are using a sound server, like Pulseaudio, JACK or PipeWire, migrate your configuration to that

  - If you are using ALSA as your only sound system, check if you can use the new structured ALSA options `hardware.alsa.defaultDevice`, `hardware.alsa.cardAliases`, `hardware.alsa.controls`, etc.

  - Otherwise, move your configuration directly into `hardware.alsa.config`

  - If you are using another sound server, like Pulseaudio, JACK or PipeWire, migrate your configuration to that

  - If you are not using an external sound server, set `environment.etc."asound.conf".text = yourExtraConfig` instead

If you set `sound.mediaKeys` in your configuration:

  - Preferably switch to handling media keys in your desktop environment/compositor

- The paperless module now has an option for regular automatic export of

  documents data using the integrated document exporter.

- New options for the declarative configuration of the user space part of ALSA have been introduced under [hardware.alsa](options.html#opt-hardware.alsa.enable), including setting the default capture and playback device, defining sound card aliases and volume controls.

  Note: these are intended for users not running a sound server like PulseAudio or PipeWire, but having ALSA as their only sound system.

- Caddy can now be built with plugins by using `caddy.withPlugins`, a `passthru` function that accepts an attribute set as a parameter. The `plugins` argument represents a list of Caddy plugins, with each Caddy plugin being a versioned module. The `hash` argument represents the `vendorHash` of the resulting Caddy source code with the plugins added.

  Example:

      [ "sound" "enableOSSEmulation" ]

      [ "hardware" "alsa" "enableOSSEmulation" ]

    )

    (lib.mkRenamedOptionModule

      [ "sound" "extraConfig" ]

      [ "hardware" "alsa" "config" ])

    (lib.mkRenamedOptionModule [ "sound" "extraConfig" ] [ "hardware" "alsa" "config" ])

  ];

  options.hardware.alsa = {

  };

  config = lib.mkIf cfg.enable {

  options.hardware.alsa.enablePersistence = lib.mkOption {

    type = lib.types.bool;

    defaultText = lib.literalExpression "config.hardware.alsa.enable";

    default = config.hardware.alsa.enable;

    description = ''

      Whether to enable ALSA sound card state saving on shutdown.

      This is generally not necessary if you're using an external sound server.

    '';

  };

  config = lib.mkMerge [

    (lib.mkIf cfg.enable {

      # Disable sound servers enabled by default and,

      # if the user enabled one manually, cause a conflict.

      services.pipewire.enable = false;

    hardware.pulseaudio.enable = false;

      services.pulseaudio.enable = false;

      hardware.alsa.config =

        let

      boot.kernelModules =

        [ ]

      ++ lib.optionals cfg.enableOSSEmulation [ "snd_pcm_oss" "snd_mixer_oss" ]

        ++ lib.optionals cfg.enableOSSEmulation [

          "snd_pcm_oss"

          "snd_mixer_oss"

        ]

        ++ lib.optionals cfg.enableRecorder [ "snd_aloop" ];

      # Assign names to the sound cards

      # Provide alsamixer, aplay, arecord, etc.

      environment.systemPackages = [ pkgs.alsa-utils ];

    })

    (lib.mkIf config.hardware.alsa.enablePersistence {

      # Install udev rules for restoring card settings on boot

      services.udev.extraRules = ''

          # setting changed between the last `store` and now will be lost.

          # To prevent NixOS from starting it in case it has failed we

          # expand the exit codes considered successful

        SuccessExitStatus = [ 0 99 ];

          SuccessExitStatus = [

            0

            99

          ];

          ExecStart = "${alsactl} restore -gU";

          ExecStop = "${alsactl} store -gU";

        };

      };

  };

    })

  ];

  meta.maintainers = with lib.maintainers; [ rnhmjoj ];