From cad8957eabcbf73062226d28366fd446c15c8737 Mon Sep 17 00:00:00 2001 From: Thomas Strobel Date: Sat, 20 Feb 2016 01:47:01 +0100 Subject: Add the tool "nixos-typecheck" that can check an option declaration to: - Enforce that an option declaration has a "defaultText" if and only if the type of the option derives from "package", "packageSet" or "nixpkgsConfig" and if a "default" attribute is defined. - Enforce that the value of the "example" attribute is wrapped with "literalExample" if the type of the option derives from "package", "packageSet" or "nixpkgsConfig". - Warn if a "defaultText" is defined in an option declaration if the type of the option does not derive from "package", "packageSet" or "nixpkgsConfig". - Warn if no "type" is defined in an option declaration. --- nixos/doc/manual/default.nix | 6 +- .../doc/manual/development/option-declarations.xml | 106 ++++++++++++++++++++- 2 files changed, 108 insertions(+), 4 deletions(-) (limited to 'nixos/doc/manual') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 4ce6ea1c1118..ea8601497361 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -1,4 +1,4 @@ -{ pkgs, options, version, revision, extraSources ? [] }: +{ pkgs, options, internalModule, version, revision, extraSources ? [] }: with pkgs; with pkgs.lib; @@ -6,8 +6,10 @@ with pkgs.lib; let # Remove invisible and internal options. - optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList options); + optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList internalModule options); + # INFO: Please add 'defaultText' or 'literalExample' to the option + # definition to avoid this substitution! # Replace functions by the string substFunction = x: if builtins.isAttrs x then mapAttrs (name: substFunction) x diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml index ea5d1241876e..08bde4a275d9 100644 --- a/nixos/doc/manual/development/option-declarations.xml +++ b/nixos/doc/manual/development/option-declarations.xml @@ -8,7 +8,7 @@ An option declaration specifies the name, type and description of a NixOS configuration option. It is illegal to define an option -that hasn’t been declared in any module. A option declaration +that has not been declared in any module. A option declaration generally looks like this: @@ -145,6 +145,108 @@ options = { You can also create new types using the function mkOptionType. See -lib/types.nix in Nixpkgs for details. +lib/types.nix in Nixpkgs for details. + +An option declaration must follow the following rules: + + + + A defaultText must be defined if and only if the type of the option + derives from package, packageSet or nixpkgsConfig + , and if and only if a default attribute is defined and if and only if + the value of the default attribute is not the default of the type of the + option declaration. + + For example, a defaultText must be defined for + +type = types.listOf types.package; +default = [ pkgs.foo; ]; +defaultText = "[ pkgs.foo; ]"; +. + + But no defaultText must be defined for + +type = types.listOf types.package; +default = []; +, + as [] is the default of types.listOf types.package. + + + + + A defaultText can be defined if the type of the option derives from + path and if a default attribute is defined. + + + + The value of the example attribute must be wrapped with + literalExample if the type of the option derives from package, + packageSet or nixpkgsConfig. + + + + The value of defaultText and literalExample must + be a string which contains a valid nix expression. The nix expression has to evaluate in + {pkgs}: value. + For example: + + + A defaultText could, e.g., be: + +type = types.package; +default = pkgs.foo; +defaultText = "pkgs.foo"; + + But not defaultText = "pkgs.foo;";, as that + corresponds to {pkgs}: pkgs.foo;, which is an + invalid nix expression due to the ending with ;. + + + + A literalExample could be used as, e.g.: + +type = types.path; +example = literalExample "\"\${pkgs.bar}/bin/bar\""; + + But not literalExample "\${pkgs.bar}/bin/bar";, as that corresponds + to {pkgs}: ${pkgs.bar}/bin/bar, which is an invalid nix expression + as the path is not a string anymore. + + + + + + The type attribute must be defined for every option declaration. + + + + +NixOS ships the tool nixos-typecheck that can check an option declaration to: + + + + + Enforce that an option declaration has a defaultText if and only if the + type of the option derives from package, packageSet or + nixpkgsConfig and if a default attribute is defined. + + + + Enforce that the value of the example attribute is wrapped with + literalExample if the type of the option derives from package, + packageSet or nixpkgsConfig. + + + + Warn if a defaultText is defined in an option declaration if the type of + the option does not derive from package, packageSet or + nixpkgsConfig. + + + + Warn if no type is defined in an option declaration. + + + -- cgit 1.4.1