diff --git a/lessons/option-priorities/eval-force.nix b/lessons/option-priorities/eval-force.nix new file mode 100644 index 0000000..84d8626 --- /dev/null +++ b/lessons/option-priorities/eval-force.nix @@ -0,0 +1,11 @@ +{pkgs}: +( + pkgs.lib.evalModules { + modules = [ + ./options.nix + ./override.nix + ./force.nix + ]; + } +) +.config diff --git a/lessons/option-priorities/eval-override.nix b/lessons/option-priorities/eval-override.nix new file mode 100644 index 0000000..041f26c --- /dev/null +++ b/lessons/option-priorities/eval-override.nix @@ -0,0 +1,10 @@ +{pkgs}: +( + pkgs.lib.evalModules { + modules = [ + ./options.nix + ./override.nix + ]; + } +) +.config diff --git a/lessons/option-priorities/eval.nix b/lessons/option-priorities/eval.nix new file mode 100644 index 0000000..2becc8c --- /dev/null +++ b/lessons/option-priorities/eval.nix @@ -0,0 +1,9 @@ +{pkgs}: +( + pkgs.lib.evalModules { + modules = [ + ./options.nix + ]; + } +) +.config diff --git a/lessons/option-priorities/force.nix b/lessons/option-priorities/force.nix new file mode 100644 index 0000000..ab7a0b1 --- /dev/null +++ b/lessons/option-priorities/force.nix @@ -0,0 +1,5 @@ +{lib, ...}: { + config = { + name = lib.mkForce "A Forced Boat"; + }; +} diff --git a/lessons/option-priorities/lesson.md b/lessons/option-priorities/lesson.md new file mode 100644 index 0000000..8c87e5f --- /dev/null +++ b/lessons/option-priorities/lesson.md @@ -0,0 +1,84 @@ +# Option priorities + +Module options have a *priority*, represented as an integer, which determines the precedence for setting the option to a particular value. +When merging values, the priority with the lowest numeric value will be used. + +When evaluating modules, the `default` attribute in `mkOption` uses `mkOptionDefault` internally to assign a priority of 1500. +There are functions that can be used to set an option definitions priority. +`mkDefault`, generally used with option definitions (i.e. `config`), has a priority of 1000. +`mkForce`, generally used when you really *really* want a value to be used, has a priority of 10. +Additionally, option definitions without a priority use `defaultOverridePriority`, which has a priority of 100. + +You can use `mkOverride` to create your own option priority. +It takes two arguments: an integer as the priority followed by the option value you want to set. +Like so: + +``` nix +config.some-option = mkOverride 42 false; +``` + +Let us take a look at using these priorities and see how they work. +In our `options.nix` file, we have a declaration and definition for the option `name`. +We are using `mkDefault`, which recall has a priority of 1000, to set the value. + +[//]: # (./options.nix) + +Setup an `eval.nix` to evaluate our modules and return the `config` attribute. + +[//]: # (./eval.nix) + +Create a `run.sh` run script to evaluate the `eval.nix` file. + +[//]: # (./run.sh) + +And if we run the script (`./run.sh`), we have our configuration. + +[//]: # (self.eval) + +This is not terribly surprising as we only had a single definition for our option. +There was only a single value that `name` could possibly be. + +So what happens if we introduce another definition for `name`. +In `override.nix` we do exactly that. +Here we are setting the value for `name` directly in `config`, which recall will have a priority of 100. +We expect that this should take precedence over our original definition. + +[//]: # (./override.nix) + +We have a new `eval-override.nix` to evaluate our modules including the new `override.nix`. + +[//]: # (./eval-override.nix) + +A `run-override.sh` run script to evaluate the `eval-override.nix` file. + +[//]: # (./run-override.sh) + +And if we run the script (`./run-override.sh`), we have our configuration. + +[//]: # (self.eval-override) + +Great! +Exactly as we expected. +The lower priority value set in `override.nix` took precedence. + +Let us do it again. +In `force.nix`, we introduce another definition for `name`, but we use `mkForce`. +Recall that `mkForce` has a priority value of 10. +If we merge this with our other two definitions, we expect that it should take precedence. + +[//]: # (./force.nix) + +We have a new `eval-force.nix` to evaluate our modules including the new `force.nix`. + +[//]: # (./eval-force.nix) + +A `run-force.sh` run script to evaluate the `eval-force.nix` file. + +[//]: # (./run-force.sh) + +And if we run the script (`./run-force.sh`), we have our configuration. + +[//]: # (self.eval-force) + +Great! +Again exactly as expected. diff --git a/lessons/option-priorities/options.nix b/lessons/option-priorities/options.nix new file mode 100644 index 0000000..a4eac23 --- /dev/null +++ b/lessons/option-priorities/options.nix @@ -0,0 +1,11 @@ +{lib, ...}: { + options = { + name = lib.mkOption { + type = lib.types.str; + }; + }; + + config = { + name = lib.mkDefault "Boaty McBoatface"; + }; +} diff --git a/lessons/option-priorities/override.nix b/lessons/option-priorities/override.nix new file mode 100644 index 0000000..c46c44f --- /dev/null +++ b/lessons/option-priorities/override.nix @@ -0,0 +1,5 @@ +{lib, ...}: { + config = { + name = "A Boat Overridden"; + }; +} diff --git a/lessons/option-priorities/run-force.sh b/lessons/option-priorities/run-force.sh new file mode 100755 index 0000000..387f850 --- /dev/null +++ b/lessons/option-priorities/run-force.sh @@ -0,0 +1,3 @@ +nix eval -f eval-force.nix \ + --apply 'x: x {pkgs = import {};}' \ + --json | nix run nixpkgs#jq -- -r diff --git a/lessons/option-priorities/run-override.sh b/lessons/option-priorities/run-override.sh new file mode 100755 index 0000000..9d7866f --- /dev/null +++ b/lessons/option-priorities/run-override.sh @@ -0,0 +1,3 @@ +nix eval -f eval-override.nix \ + --apply 'x: x {pkgs = import {};}' \ + --json | nix run nixpkgs#jq -- -r diff --git a/lessons/option-priorities/run.sh b/lessons/option-priorities/run.sh new file mode 100755 index 0000000..d5086db --- /dev/null +++ b/lessons/option-priorities/run.sh @@ -0,0 +1,3 @@ +nix eval -f eval.nix \ + --apply 'x: x {pkgs = import {};}' \ + --json | nix run nixpkgs#jq -- -r diff --git a/site/mkdocs.yml b/site/mkdocs.yml index b4e9d05..c06199d 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -21,6 +21,8 @@ nav: - lessons/basic-types/lesson.md - lessons/composed-types/lesson.md - lessons/submodule-types/lesson.md + - Misc: + - lessons/option-priorities/lesson.md - Future: - lessons/default-behavior/lesson.md - lessons/merging-attrsof/lesson.md