From ad36f9fa0657a5dc234ca6c6762d38cb93f1559c Mon Sep 17 00:00:00 2001 From: Jan Schmitt Date: Fri, 2 Sep 2022 13:48:07 +0200 Subject: [PATCH 1/2] docs: extend documentation * mention prerequisite of nix * explicitly mention implications when using the uninstaller. * mention channel ownership when using nix as a daemon-service. * add additional ways to work with the documentation. * give another example how to run tests --- README.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f7a59e70..2a785637 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ Nix modules for darwin, `/etc/nixos/configuration.nix` for macOS. ## Install +To install nix-darwin, a working installation of [nix](https://github.com/NixOS/nix#installation) is required. + ```bash nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A installer ./result/bin/darwin-installer @@ -30,6 +32,9 @@ nix-channel --update darwin darwin-rebuild changelog ``` +> NOTE: If you are using nix as a daemon service the channel for that will be owned by root. +> Use `sudo -i nix-channel --update darwin` instead. + ## Uninstalling There's also an uninstaller if you don't like the project and want to @@ -40,6 +45,8 @@ nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A uninstalle ./result/bin/darwin-uninstaller ``` +> NOTE: This will also uninstall nix alongside nix-darwin. + ## Example configuration Configuration lives in `~/.nixpkgs/darwin-configuration.nix`. Check out @@ -164,6 +171,16 @@ writing defaults... $ ``` +## Documentation + +Reference documentation of all the options is available here +https://lnl7.github.io/nix-darwin/manual/index.html#sec-options. +This can also be accessed locally using `man 5 configuration.nix`. + +`darwin-help` will open a html version of the manpage in the default browser. + +Furthermore there's `darwin-option` to introspect the settings of a system and it's available options. + ``` $ darwin-option services.activate-system.enable Value: @@ -179,12 +196,6 @@ Description: Whether to activate system at boot time. ``` -## Documentation - -Reference documentation of all the options is available here -https://lnl7.github.io/nix-darwin/manual/index.html#sec-options. -This can also be accessed locally using `man 5 configuration.nix`. - There's also a small wiki https://github.com/LnL7/nix-darwin/wiki about specific topics, like macOS upgrades. @@ -194,6 +205,9 @@ There are basic tests that run sanity checks for some of the modules, you can run them like this: ```bash +> run all tests +nix-build release.nix -A tests +> or just a subset nix-build release.nix -A tests.environment-path ``` @@ -204,7 +218,7 @@ Don't hesitate to contribute modules or open an issue. To build your configuration with local changes you can run this. This flag can also be used to override darwin-config or nixpkgs, for more -information on the `-I` flag look at the nix-build manpage. +information on the `-I` flag look at the nix-build [manpage](https://nixos.org/manual/nix/stable/command-ref/nix-build.html). ```bash darwin-rebuild switch -I darwin=. From a498eb069579719980620657ad7baed8792e62f4 Mon Sep 17 00:00:00 2001 From: Jan Schmitt Date: Fri, 2 Sep 2022 14:34:18 +0200 Subject: [PATCH 2/2] docs: add short introduction closes #68 --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2a785637..dae72911 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,12 @@ Nix modules for darwin, `/etc/nixos/configuration.nix` for macOS. +This project aims to bring the convenience of a declarative system approach to macOS. +Nix-darwin is built up around [Nixpkgs](https://github.com/NixOS/nixpkgs), quite similar to [NixOs](https://nixos.org/). + ## Install -To install nix-darwin, a working installation of [nix](https://github.com/NixOS/nix#installation) is required. +To install nix-darwin, a working installation of [Nix](https://github.com/NixOS/nix#installation) is required. ```bash nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A installer @@ -32,7 +35,7 @@ nix-channel --update darwin darwin-rebuild changelog ``` -> NOTE: If you are using nix as a daemon service the channel for that will be owned by root. +> NOTE: If you are using Nix as a daemon service the channel for that will be owned by root. > Use `sudo -i nix-channel --update darwin` instead. ## Uninstalling @@ -45,7 +48,7 @@ nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A uninstalle ./result/bin/darwin-uninstaller ``` -> NOTE: This will also uninstall nix alongside nix-darwin. +> NOTE: This will also uninstall Nix alongside nix-darwin. ## Example configuration @@ -173,13 +176,13 @@ $ ## Documentation -Reference documentation of all the options is available here -https://lnl7.github.io/nix-darwin/manual/index.html#sec-options. +Reference documentation of all the options is available [here](https://lnl7.github.io/nix-darwin/manual/index.html#sec-options).-- This can also be accessed locally using `man 5 configuration.nix`. -`darwin-help` will open a html version of the manpage in the default browser. +`darwin-help` will open a HTML version of the manpage in the default browser. -Furthermore there's `darwin-option` to introspect the settings of a system and it's available options. +Furthermore there's `darwin-option` to introspect the settings of a system and its available options. +> NOTE: `darwin-option` is only available to non-flake installations. ``` $ darwin-option services.activate-system.enable @@ -205,9 +208,9 @@ There are basic tests that run sanity checks for some of the modules, you can run them like this: ```bash -> run all tests +# run all tests nix-build release.nix -A tests -> or just a subset +# or just a subset nix-build release.nix -A tests.environment-path ```