Development

Extending NixOS A unique syntax is used to express all system, hardware, computer and service configurations. This syntax helps for reading and writing new configuration files. It is coming with some extra strategies defined in NixPkgs which are used to merge and evaluate all configuration files. A configuration file is the same as your own computer configuration. Usual configuration file {config, modulesPath, pkgs, ...}: let inherit (pkgs.lib) mkOption mkIf mkThenElse types; cfg = config.services.locate; locatedb = "/var/cache/locatedb"; logfile = "/var/log/updatedb"; cmd = "root updatedb --localuser=nobody --output=${locatedb} > ${logfile}"; in { imports = [ (modulesPath + /services/scheduling/cron.nix) ]; options = { services.locate = { enable = mkOption { default = false; example = true; type = types.bool; description = '' If enabled, NixOS will periodically update the database of files used by the locate command. ''; }; period = mkOption { default = "15 02 * * *"; type = types.uniq type.string; description = '' This option defines (in the format used by cron) when the locate database is updated. The default is to update at 02:15 (at night) every day. ''; }; }; }; config = mkIf cfg.enable { services.cron = { systemCronJobs = mkThenElse { thenPart = "${cfg.period} root ${cmd}"; elsePart = ""; }; }; }; } shows the configuration file for the locate service which uses cron to update the database at some dates which can be defined by the user. This nix expression is coming from upstart-jobs/cron/locate.nix. It shows a simple example of a service that can be either distributed on many computer that are using the same configuration or to shared with the community. This file is divided in two with the interface and the implementation. Both the interface and the implementation declare a configuration set. This line declares the arguments of the configuration file. You can omit this line if there is no reference to pkgs and config inside the configuration file. The argument pkgs refers to NixPkgs and allow you to access all attributes contained inside it. In this example pkgs is used to retrieve common functions to ease the writing of configuration files like mkOption, mkIf and mkThenElse. The argument config corresponds to the whole NixOS configuration. This is a set which is build by merging all configuration files imported to set up the system. Thus all options declared are contained inside this variable. In this example config is used to retrieve the status of the enable flag. The important point of this argument is that it contains either the result of the merge of different settings or the default value, therefore you cannot assume that is always false because it may have been defined in another configuration file. This line is used to import a functions that are useful for writing this configuration file. The variable options is a configuration set which is only used to declare options with the function mkOption imported from pkgs/lib/default.nix. Options may contained any attribute but only the following have a special meaning: default, example, description, merge and apply. The merge attribute is used to merge all values defined in all configuration files and this function return a value which has the same type as the default value. If the merge function is not defined, then a default function (pkgs.lib.mergeDefaultOption) is used to merge values. The merge attribute is a function which expect two arguments: the location of the option and the list of values which have to be merged. The apply attribute is a function used to process the option. Thus the value return by would be the result of the apply function called with either the default value or the result of the merge function. This line is a common trick used to reduce the amount of writing. In this case cfg is just a sugar over This line is used to declare a special IF statement. If you had put a usual IF statement here, with the same condition, then you will get an infinite loop. The reason is that your condition ask for the value of the option but in order to get this value you have to evaluate all configuration sets including the configuration set contained inside your file. To remove this extra complexity, mkIf has been introduced to get rid of possible infinite loop and to factor your writing. The attribute imports contains a list of other module location. These modules should provide option declarations for the current module in order to be evaluated safely. When a dependence on a NixOS module has to be made, then you should use the argument modulesPath to prefix the location of your NixOS repository. The attribute config, which should not be confused with the argument of the same name, contains a set of option definitions defined by this module. When there is neither imports nor options, then this attribute set can be return without any enclosing. This feature allow you to write your configuration.nix as a module which does not contains any option declarations. As mkIf does not need any then part or else part, then you can specify one on each option definition with the function mkThenElse. To avoid a lot of mkThenElse with empty else part, a sugar has been added to infer the corresponding empty-value of your option when the function mkThenElse is not used. If your then part and else part are identical, then you should use the function mkAlways to ignore the condition. If you need to add another condition, then you can add mkIf to on the appropriate location. Thus the then part will only be used if all conditions declared with mkIf are satisfied.