Add second enabling mode

[trueNAHO]

This issue was converted from discussion #2112 with the following messages:

• On Sun Dec 28, 2025 at 6:18 PM CET, @danth wrote:

  Methods could include things like:

  • Code patches
    • Change the source code of the application.
    • Not supported by upstream developers.
    • Examples: gtksourceview, gtk: support NixOS standalone #2107
  • Runtime/asset patches
    • Change data loaded by the application at runtime.
    • Not supported by upstream developers.
    • Examples: GTK, Discord, Firefox GNOME Theme
  • Configuration files
    • Set the theme using provided functionality.
    • Supported by upstream developers.
    • Examples: Rofi, VSCode, various shells
  • Manual setup
    • Requires additional effort from the end user to get working: maybe changing their Nix code, or clicking a theme in a menu.
    • Examples: i3 bars, Blender

  Having this metadata would allow users to select modules that fit their criteria, without turning off autoEnable entirely.

  For example, some users would like to disable code patches because they don't have the resources to compile things locally. Some might want to use only officially supported methods, because these have the least chance to break things.

• On Mon Jan 5, 2026 at 2:22 AM CET, @trueNAHO wrote:

  Add metadata about implementation methods

  Methods could include things like:

  After pondering again on how to generally implement the "second enabling mode" in Home Manager that has been discussed in-depth for the vivid module in bug: vivid: home.sessionVariables and yaml vs scientific notation home-manager#7994, vivid: replace theme content from yaml with json home-manager#7996, and vivid: init #1938, I came up with an upstream solution that coincidentally also reliably solves all modules are enabled by default, and they don't just style my configuration #543.

  Since the conclusion is very related to this proposal, let me elaborate.

  Essentially, all modules are enabled by default, and they don't just style my configuration #543 boils down to upstream inconsistently guarding config with something like config = lib.mkIf cfg.enable. Understandably, since Home Manager currently has over 500 modules, it is easy to eventually miss this during review.

  Fortunately, Stylix happens to generally solve this with its custom module system (/stylix/mk-target.nix) by automatically wrapping modules with lib.mkIf (config.stylix.enable && cfg.enable). Although the custom module system arguably increases code complexity with a small DSL, its indisputable benefit for Stylix is the automatic safeguarding of individual declarations based on options external to the specific module, which would be nearly impossible to consistently and correctly implement manually.

  Considering the sheer amount of Home Manager modules, even Home Manager would benefit from a simple custom module system that merely wraps modules with config = lib.mkIf cfg.enable, thus reliably solving all modules are enabled by default, and they don't just style my configuration #543.

  Extending and generalizing all modules are enabled by default, and they don't just style my configuration #543 and the "second enabling mode" implies the need to distinguish between installing binaries and everything else. Based on the previously mentioned vivid discussions, it is also beneficial to treat environment variable declarations specially. Based on vicinae: move from programs to services home-manager#8313 (comment), it is also beneficial to treat programs and services differently due to performance and security. This would lead to the following feature set (with names subject to change), where services implies arbitrary run time execution, and everything not handled by any previously explained feature falls under etc: packages, files, variables, services, and etc. This could be translated into the following custom module system interface, where features can be globally toggled with a features.${feature}.enable (namespace and name subject to change) option:

  {
    config = {
      packages = /* ... */;
      files = /* ... */;
      variables = /* ... */;
      services = /* ... */;
      etc = /* ... */;
    };
  }

  For reference and context, features.packages corresponds to Home Manager's current home.packages option, files to home.files (and its implicit dependants, like xdg.cacheFile and xdg.configFile), variables to home.sessionVariables, services to something like services or home.activation, and etc to everything previously unmatched.

  Specifically, all modules are enabled by default, and they don't just style my configuration #543 implicitly requests not enabling features.packages.enable, while the "second enabling mode" for the vivid module would be solved by only enabling the programs.vivid.features.variables.enable feature. Beyond that, Stylix would generally benefit from not enabling features.packages.enable.

  Some time during the review cycle of stylix/mk-target: polish, simplify, and extend interface #1721, I rewrote my NixOS configuration to leverage a custom and highly ergonomic module system that has more features than the Stylix module system and has an astonishingly simple, although very involved, implementation. Before upstreaming my work and findings to Stylix and Home Manager, I would like to experiment whether it is possible to refactor the core logic of my custom module system into a library to share between my NixOS and Home Manager repositories. If this ends up being impossible, it might be safe to assume that custom module systems are always project-specific and need to be implemented from scratch every time. For reference, I will probably only have time to look into this in at least a month.

  ---

  Based on the previously proposed Home Manager feature set (packages, files, variables, services, and etc), this proposal could map to that feature set and extend it. Maybe somewhere like stylix.features.${feature}.enable?

  Specifying module feature sets inside /modules/<MODULE>/meta.nix is too vague because /modules/<MODULE>/nixos.nix and /modules/<MODULE>/hm.nix may have different feature sets, meaning it should be defined in /modules/<MODULE>/<PLATFORM>.nix.

  For clarity, the stylix.features.${feature}.enable Stylix feature set can already be implemented by extending the existing Stylix module system without waiting on my module system refactor exploration or the proposed features.${feature}.enable Home Manager implementation.

  • Code patches
    • Change the source code of the application.
    • Not supported by upstream developers.
    • Examples: gtksourceview, gtk: support NixOS standalone #2107

  Would this not correspond to a stylix.features.overlays.enable feature? Following commits eb19696 ("stylix: add overlay module (stylix: add overlay module #1048)") and 581fa67 ("stylix: guard entire overlay declarations (stylix: ensure overlays aren't set when disabled #1088)"), would this not be a stylix.overlays.enable alias? Note that mapping to platform-specific Stylix options likely requires resolving stylix: Make platform-specific options available on all platforms (no-op on unsupported systems) #2078.

  • Runtime/asset patches
    • Change data loaded by the application at runtime.
    • Not supported by upstream developers.
    • Examples: GTK, Discord, Firefox GNOME Theme

  What about calling this feature something like stylix.features.extensions.enable?

  • Configuration files
    • Set the theme using provided functionality.
    • Supported by upstream developers.
    • Examples: Rofi, VSCode, various shells

  I suppose this corresponds to the previously proposed Home Manager feature set and would merely re-expose it under stylix.features.${feature}.enable.

  • Manual setup
    • Requires additional effort from the end user to get working: maybe changing their Nix code, or clicking a theme in a menu.
    • Examples: i3 bars, Blender

  What about calling this feature something like stylix.features.manual.enable?

  Having this metadata would allow users to select modules that fit their criteria, without turning off autoEnable entirely.

  For example, some users would like to disable code patches because they don't have the resources to compile things locally. Some might want to use only officially supported methods, because these have the least chance to break things.

  This proposal is great! Should we elevate this discussion to an issue?

  On a side note, I am using a "feature" concept in my NixOS configuration for flat (no DAG or tree compositions) module composition where host configurations may contain the following:

  # The 'os' namespace is my NixOS namespace, analogous to the 'stylix' namespace.
  os.features = {
    base.enable = true;
    server.enable = true;
  };

• On Tue Jun 2, 2026 at 6:52 PM CEST, @0xda157 wrote:

  Based on the previously proposed Home Manager feature set (packages, files, variables, services, and etc), this proposal could map to that feature set and extend it. Maybe somewhere like stylix.features.${feature}.enable?

  I would prefer instead changing the type of autoEnable to a list of enum. Keeping the autoEnable option as a boolean doesn't really make much more sense in this case, and would seemingly conflict with stylix.features.*.enable under your proposal.

  Should we elevate this discussion to an issue?

  I think we should.

[trueNAHO]

Based on the previously proposed Home Manager feature set (packages, files, variables, services, and etc), this proposal could map to that feature set and extend it. Maybe somewhere like stylix.features.${feature}.enable?

I would prefer instead changing the type of autoEnable to a list of enum. Keeping the autoEnable option as a boolean doesn't really make much more sense in this case, and would seemingly conflict with stylix.features.*.enable under your proposal.

For example, with

mkTarget {
  config = [
    (
      { colors }: {
        home.packages = [pkgs.colors]; # Should require 'colors' AND 'packages' enabled.
        services.colors.enable = true; # Should require 'colors' AND 'services' enabled.
      }
    )

    (
      { fonts }: {
        home.packages = [pkgs.fonts];  # Should require 'fonts' AND 'packages' enabled.
        services.fonts.enable = true;  # Should require 'fonts' AND 'services' enabled.
      }
    )
  ];
}

it should be possible to toggle the colors, fonts, packages, and services functionalities independently, which requires each declaration to somehow be associated with both theming (colors and fonts) and behavior (packages and services) functionalities.

The theming and behavior functionalities could be reasonably permuted in one of the two following ways:

• mkTarget {
    config = {
      packages = [
        (
          { colors }: {
            home.packages = [pkgs.colors]; # Requires 'packages' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            home.packages = [pkgs.fonts];  # Requires 'packages' AND 'fonts' enabled.
          }
        )
      ];
  
      services = [
        (
          { colors }: {
            services.colors.enable = true; # Requires 'services' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            services.fonts.enable = true;  # Requires 'services' AND 'fonts' enabled.
          }
        )
      ];
    };
  }

• mkTarget {
    config = [
      (
        { colors }: {
          packages = {
            home.packages = [pkgs.colors]; # Requires 'colors' AND 'packages' enabled.
          };
  
          services = {
            services.colors.enable = true; # Requires 'colors' AND 'services' enabled.
          };
        }
      )
  
      (
        { fonts }: {
          packages = {
            home.packages = [pkgs.fonts];  # Requires 'fonts' AND 'packages' enabled.
          };
  
          services = {
            services.fonts.enable = true;  # Requires 'fonts' AND 'services' enabled.
          };
        }
      )
    ];
  }

I suppose you want behavior functionalities to be toggled with autoEnable as

mkTarget {
  autoEnable = [
    "packages"
    "services"
  ];
}

instead of

stylix.features = {
  packages.enable = true;
  services.enable = true;
};

IMHO, typed attribute sets are better than string enums.

While my initial proposal focussed on the global stylix.features.${feature}.enable toggles, your enum proposal addresses target-specific toggling. This could be better addressed with typed attribute sets by extending our custom module system to generate target-specific behavior feature toggles under stylix.targets.${target}.features.${feature}.enable.

[0xda157]

Based on the previously proposed Home Manager feature set (packages, files, variables, services, and etc), this proposal could map to that feature set and extend it. Maybe somewhere like stylix.features.${feature}.enable?

I would prefer instead changing the type of autoEnable to a list of enum. Keeping the autoEnable option as a boolean doesn't really make much more sense in this case, and would seemingly conflict with stylix.features.*.enable under your proposal.

For example, with

mkTarget {
  config = [
    (
      { colors }: {
        home.packages = [pkgs.colors]; # Should require 'colors' AND 'packages' enabled.
        services.colors.enable = true; # Should require 'colors' AND 'services' enabled.
      }
    )

    (
      { fonts }: {
        home.packages = [pkgs.fonts];  # Should require 'fonts' AND 'packages' enabled.
        services.fonts.enable = true;  # Should require 'fonts' AND 'services' enabled.
      }
    )
  ];
}

it should be possible to toggle the colors, fonts, packages, and services functionalities independently, which requires each declaration to somehow be associated with both theming (colors and fonts) and behavior (packages and services) functionalities.

The theming and behavior functionalities could be reasonably permuted in one of the two following ways:

* ```
  mkTarget {
    config = {
      packages = [
        (
          { colors }: {
            home.packages = [pkgs.colors]; # Requires 'packages' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            home.packages = [pkgs.fonts];  # Requires 'packages' AND 'fonts' enabled.
          }
        )
      ];
  
      services = [
        (
          { colors }: {
            services.colors.enable = true; # Requires 'services' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            services.fonts.enable = true;  # Requires 'services' AND 'fonts' enabled.
          }
        )
      ];
    };
  }
  ```

* ```
  mkTarget {
    config = [
      (
        { colors }: {
          packages = {
            home.packages = [pkgs.colors]; # Requires 'colors' AND 'packages' enabled.
          };
  
          services = {
            services.colors.enable = true; # Requires 'colors' AND 'services' enabled.
          };
        }
      )
  
      (
        { fonts }: {
          packages = {
            home.packages = [pkgs.fonts];  # Requires 'fonts' AND 'packages' enabled.
          };
  
          services = {
            services.fonts.enable = true;  # Requires 'fonts' AND 'services' enabled.
          };
        }
      )
    ];
  }
  ```

I think grouping in terms of behavior will make more sense when implemented on real targets, although I don't feel particularly strongly on this matter. Also this example is somewhat questionable, wouldn't services require packages to be enabled, as enabling a service usually installs the associated package on nixos/home-manager?

I suppose you want behavior functionalities to be toggled with autoEnable as

mkTarget {
  autoEnable = [
    "packages"
    "services"
  ];
}

not sure where this mkTarget call came from?

While my initial proposal focussed on the global stylix.features.${feature}.enable toggles, your enum proposal addresses target-specific toggling.

Does my proposal address target-specific toggling? I was only considering changing the type of stylix.autoEnable to an enum, nothing about the internal implementation.

---

Regardless, on further consideration I suppose that your proposal would produce better documentation. Let's processed with that for the draft implementation.

[trueNAHO]

Based on the previously proposed Home Manager feature set (packages, files, variables, services, and etc), this proposal could map to that feature set and extend it. Maybe somewhere like stylix.features.${feature}.enable?

I would prefer instead changing the type of autoEnable to a list of enum. Keeping the autoEnable option as a boolean doesn't really make much more sense in this case, and would seemingly conflict with stylix.features.*.enable under your proposal.

For example, with

mkTarget {
  config = [
    (
      { colors }: {
        home.packages = [pkgs.colors]; # Should require 'colors' AND 'packages' enabled.
        services.colors.enable = true; # Should require 'colors' AND 'services' enabled.
      }
    )

    (
      { fonts }: {
        home.packages = [pkgs.fonts];  # Should require 'fonts' AND 'packages' enabled.
        services.fonts.enable = true;  # Should require 'fonts' AND 'services' enabled.
      }
    )
  ];
}

it should be possible to toggle the colors, fonts, packages, and services functionalities independently, which requires each declaration to somehow be associated with both theming (colors and fonts) and behavior (packages and services) functionalities.

The theming and behavior functionalities could be reasonably permuted in one of the two following ways:

• mkTarget {
    config = {
      packages = [
        (
          { colors }: {
            home.packages = [pkgs.colors]; # Requires 'packages' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            home.packages = [pkgs.fonts];  # Requires 'packages' AND 'fonts' enabled.
          }
        )
      ];
  
      services = [
        (
          { colors }: {
            services.colors.enable = true; # Requires 'services' AND 'colors' enabled.
          }
        )
  
        (
          { fonts }: {
            services.fonts.enable = true;  # Requires 'services' AND 'fonts' enabled.
          }
        )
      ];
    };
  }

• mkTarget {
    config = [
      (
        { colors }: {
          packages = {
            home.packages = [pkgs.colors]; # Requires 'colors' AND 'packages' enabled.
          };
  
          services = {
            services.colors.enable = true; # Requires 'colors' AND 'services' enabled.
          };
        }
      )
  
      (
        { fonts }: {
          packages = {
            home.packages = [pkgs.fonts];  # Requires 'fonts' AND 'packages' enabled.
          };
  
          services = {
            services.fonts.enable = true;  # Requires 'fonts' AND 'services' enabled.
          };
        }
      )
    ];
  }

I think grouping in terms of behavior will make more sense when implemented on real targets, although I don't feel particularly strongly on this matter.

Under the assumption that the general ${namespace}.features.${feature}.enable interface becomes widely adopted, grouping by behavior functionalities would better align with ecosystem conventions, while grouping by theming functionalities would make Stylix guards more obvious. Unsure yet which one is better.

Also this example is somewhat questionable, wouldn't services require packages to be enabled, as enabling a service usually installs the associated package on nixos/home-manager?

The assumption is that with upstream support, this would no longer be the case. For example, services would access "${cfg.packages}" without installing it to $PATH, as this should be handled by packages.

Regardless, on further consideration I suppose that your proposal would produce better documentation. Let's processed with that for the draft implementation.

Considering this is a substantial architectural change, I suggest postponing this and #543 to the end of the current roadmap. My main concern is conceptual complexity rather than technical complexity, as the core implementation should be less than 20 LOC.