nixpkgs/nixos/maintainers/option-usages.nix

{ configuration ? import ../lib/from-env.nix "NIXOS_CONFIG" <nixos-config>

# provide an option name, as a string literal.
, testOption ? null

# provide a list of option names, as string literals.
, testOptions ? [ ]
}:

# This file is made to be used as follow:
#
#   $ nix-instantiate ./option-usages.nix --argstr testOption service.xserver.enable -A txtContent --eval
#
# or
#
#   $ nix-build ./option-usages.nix --argstr testOption service.xserver.enable -A txt -o service.xserver.enable._txt
#
# Other targets exists such as `dotContent`, `dot`, and `pdf`.  If you are
# looking for the option usage of multiple options, you can provide a list
# as argument.
#
#   $ nix-build ./option-usages.nix --arg testOptions \
#      '["boot.loader.gummiboot.enable" "boot.loader.gummiboot.timeout"]' \
#      -A txt -o gummiboot.list
#
# Note, this script is slow as it has to evaluate all options of the system
# once per queried option.
#
# This nix expression works by doing a first evaluation, which evaluates the
# result of every option.
#
# Then, for each queried option, we evaluate the NixOS modules a second
# time, except that we replace the `config` argument of all the modules with
# the result of the original evaluation, except for the tested option which
# value is replaced by a `throw` statement which is caught by the `tryEval`
# evaluation of each option value.
#
# We then compare the result of the evaluation of the original module, with
# the result of the second evaluation, and consider that the new failures are
# caused by our mutation of the `config` argument.
#
# Doing so returns all option results which are directly using the
# tested option result.

with import ../../lib;

let

  evalFun = {
    specialArgs ? {}
  }: import ../lib/eval-config.nix {
       modules = [ configuration ];
       inherit specialArgs;
     };

  eval = evalFun {};
  inherit (eval) pkgs;

  excludedTestOptions = [
    # We cannot evluate _module.args, as it is used during the computation
    # of the modules list.
    "_module.args"

    # For some reasons which we yet have to investigate, some options cannot
    # be replaced by a throw without causing a non-catchable failure.
    "networking.bonds"
    "networking.bridges"
    "networking.interfaces"
    "networking.macvlans"
    "networking.sits"
    "networking.vlans"
    "services.openssh.startWhenNeeded"
  ];

  # for some reasons which we yet have to investigate, some options are
  # time-consuming to compute, thus we filter them out at the moment.
  excludedOptions = [
    "boot.systemd.services"
    "systemd.services"
    "kde.extraPackages"
  ];
  excludeOptions = list:
    filter (opt: !(elem (showOption opt.loc) excludedOptions)) list;


  reportNewFailures = old: new:
    let
      filterChanges =
        filter ({fst, snd}:
          !(fst.success -> snd.success)
        );

      keepNames =
        map ({fst, snd}:
          /* assert fst.name == snd.name; */ snd.name
        );

      # Use  tryEval (strict ...)  to know if there is any failure while
      # evaluating the option value.
      #
      # Note, the `strict` function is not strict enough, but using toXML
      # builtins multiply by 4 the memory usage and the time used to compute
      # each options.
      tryCollectOptions = moduleResult:
        forEach (excludeOptions (collect isOption moduleResult)) (opt:
          { name = showOption opt.loc; } // builtins.tryEval (strict opt.value));
     in
       keepNames (
         filterChanges (
           zipLists (tryCollectOptions old) (tryCollectOptions new)
         )
       );


  # Create a list of modules where each module contains only one failling
  # options.
  introspectionModules =
    let
      setIntrospection = opt: rec {
        name = showOption opt.loc;
        path = opt.loc;
        config = setAttrByPath path
          (throw "Usage introspection of '${name}' by forced failure.");
      };
    in
      map setIntrospection (collect isOption eval.options);

  overrideConfig = thrower:
    recursiveUpdateUntil (path: old: new:
      path == thrower.path
    ) eval.config thrower.config;


  graph =
    map (thrower: {
      option = thrower.name;
      usedBy = assert __trace "Investigate ${thrower.name}" true;
        reportNewFailures eval.options (evalFun {
          specialArgs = {
            config = overrideConfig thrower;
          };
        }).options;
    }) introspectionModules;

  displayOptionsGraph =
     let
       checkList =
         if testOption != null then [ testOption ]
         else testOptions;
       checkAll = checkList == [];
     in
       flip filter graph ({option, ...}:
         (checkAll || elem option checkList)
         && !(elem option excludedTestOptions)
       );

  graphToDot = graph: ''
    digraph "Option Usages" {
      ${concatMapStrings ({option, usedBy}:
          concatMapStrings (user: ''
            "${option}" -> "${user}"''
          ) usedBy
        ) displayOptionsGraph}
    }
  '';

  graphToText = graph:
    concatMapStrings ({usedBy, ...}:
        concatMapStrings (user: ''
          ${user}
        '') usedBy
      ) displayOptionsGraph;

in

rec {
  dotContent = graphToDot graph;
  dot = pkgs.writeTextFile {
    name = "option_usages.dot";
    text = dotContent;
  };

  pdf = pkgs.texFunctions.dot2pdf {
    dotGraph = dot;
  };

  txtContent = graphToText graph;
  txt = pkgs.writeTextFile {
    name = "option_usages.txt";
    text = txtContent;
  };
}