Refine README.md a bit (#117)

* Refine README.md a bit * Add firefox invocation * Reflect feedback
2022-12-12 12:56:37 -08:00 · 2022-12-12 12:56:37 -08:00 · fab886cf4d
parent 51a2d0bbae
commit fab886cf4d
1 changed files with 107 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -17,22 +17,22 @@ Harmonic is **pre-release and experimental**. It is not ready for you to use! *P
 Planned support:

 * [x] Multi-user x86_64 Linux with systemd init
-* [ ] Multi-user aarch64 Linux with systemd init
+* [x] Multi-user aarch64 Linux with systemd init
 * [x] Multi-user x86_64 MacOS
    + Note: User deletion is currently unimplemented, you need to use a user with a secure token and `dscl . -delete /Users/_nixbuild*` where `*` is each user number.
 * [x] Multi-user aarch64 MacOS
    + Note: User deletion is currently unimplemented, you need to use a user with a secure token and `dscl . -delete /Users/_nixbuild*` where `*` is each user number.
 * [x] Valve Steam Deck
-* [ ] Single-user x86_64 Linux with systemd init
-* [ ] Single-user aarch64 Linux with systemd init
+* [ ] Single-user x86_64 Linux
+* [ ] Single-user aarch64 Linux
 * [ ] Others...

 ## Installation Differences

-Differing from the current official Nix installer scripts:
+Differing from the current official [Nix](https://github.com/NixOS/nix) installer scripts:

 * Nix is installed with the `nix-command` and `flakes` features enabled in the `nix.conf`
-* Harmonic stores an installation receipt (for uninstalling) at `/nix/receipt.json`
+* Harmonic stores an installation receipt (for uninstalling) at `/nix/receipt.json` as well as a copy of the install binary at `/nix/harmonic`

 ## Motivations

@ -41,16 +41,15 @@ The current Nix installer scripts do an excellent job, however they are difficul
 Our team wishes to experiment with the idea of an installer in a more structured language and see if this is a worthwhile alternative. Along the way, we are also exploring a few other ideas, such as:

 * offering users a chance to review an accurate, calculated install plan
+* having 'planners' which can create appropriate install plans
 * keeping an installation receipt for uninstallation
-* offering users with a failing install the chance to revert
+* offering users with a failing install the chance to do a best-effort revert
 * doing whatever tasks we can in parallel

 So far, our explorations have been quite fruitful, so we wanted to share and keep exploring.

 ## Building

-Harmonic is pre-release and we do not provide binaries at this time.
-
 Since you'll be using Harmonic to install Nix on systems without Nix, the default build is a static binary.

 Build it on a system with Nix:
@ -61,30 +60,117 @@ nix build github:determinatesystems/harmonic

 Then copy the `result/bin/harmonic` to the machine you wish to run it on.

-## Running
+## Installing

-Harmonic must be run as `root`, as it needs to alter the system and cannot elevate privileges without significant complexity.
-
-Install Nix with default options:
+Install Nix with the default planner and options:

 ```bash
-# Linux
-./harmonic install linux-multi
-
-# Mac
-./harmonic install darwin-multi
+./harmonic install
 ```

+> `harmonic` will elevate itself if it is not run as `root` using `sudo`. If you use `doas` or `please` you may need to elevate `harmonic` yourself.
+
 To observe verbose logging, either use `harmonic -v`, this tool [also respects the `RUST_LOG` environment](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives). (Eg `RUST_LOG=harmonic=trace harmonic`).

-Harmonic supports many of the options the current official Nix installer scripts. Review `harmonic --help` for details.
+Harmonic installs Nix by following a *plan* made by a *planner*. Review the available planners:

-# Uninstalling
+```bash
+$ ./harmonic install --help
+Execute an install (possibly using an existing plan)
+
+To pass custom options, select a planner, for example `harmonic install linux-multi --help`
+
+Usage: harmonic install [OPTIONS] [PLAN]
+       harmonic install <COMMAND>
+
+Commands:
+  linux-multi
+          A standard Linux multi-user install
+  darwin-multi
+          A standard MacOS (Darwin) multi-user install
+  steam-deck
+          A specialized install suitable for the Valve Steam Deck console
+  help
+          Print this message or the help of the given subcommand(s)
+# ...
+```
+
+Planners have their own options and defaults, sharing most of them in common:
+
+```bash
+$ ./harmonic install linux-multi --help
+A standard Linux multi-user install
+
+Usage: harmonic install linux-multi [OPTIONS]
+
+Options:
+      --channels <channel>
+          Channel(s) to add [env: HARMONIC_CHANNEL=] [default: nixpkgs=https://nixos.org/channels/nixpkgs-unstable]
+      --no-confirm
+          
+  -v, --verbose...
+          Enable debug logs, -vv for trace
+      --explain
+          
+      --logger <LOGGER>
+          Which logger to use [default: compact] [possible values: compact, full, pretty, json]
+      --modify-profile
+          Modify the user profile to automatically load nix [env: HARMONIC_NO_MODIFY_PROFILE=]
+      --daemon-user-count <DAEMON_USER_COUNT>
+          Number of build users to create [env: HARMONIC_DAEMON_USER_COUNT=] [default: 32]
+      --nix-build-group-name <NIX_BUILD_GROUP_NAME>
+          The Nix build group name [env: HARMONIC_NIX_BUILD_GROUP_NAME=] [default: nixbld]
+      --nix-build-group-id <NIX_BUILD_GROUP_ID>
+          The Nix build group GID [env: HARMONIC_NIX_BUILD_GROUP_ID=] [default: 3000]
+      --nix-build-user-prefix <NIX_BUILD_USER_PREFIX>
+          The Nix build user prefix (user numbers will be postfixed) [env: HARMONIC_NIX_BUILD_USER_PREFIX=] [default: nixbld]
+      --nix-build-user-id-base <NIX_BUILD_USER_ID_BASE>
+          The Nix build user base UID (ascending) [env: HARMONIC_NIX_BUILD_USER_ID_BASE=] [default: 3000]
+      --nix-package-url <NIX_PACKAGE_URL>
+          The Nix package URL [env: HARMONIC_NIX_PACKAGE_URL=] [default: https://releases.nixos.org/nix/nix-2.12.0/nix-2.12.0-x86_64-linux.tar.xz]
+      --extra-conf <EXTRA_CONF>
+          Extra configuration lines for `/etc/nix.conf` [env: HARMONIC_EXTRA_CONF=]
+      --force
+          If Harmonic should forcibly recreate files it finds existing [env: HARMONIC_FORCE=]
+  -h, --help
+          Print help information
+```
+
+Planners can be configured via environment variable, or by the command arguments.
+
+```bash
+$ HARMONIC_DAEMON_USER_COUNT=4 ./harmonic install linux-multi --nix-build-user-id-base 4000 --help
+```
+
+## Uninstalling

 You can remove a Harmonic-installed Nix by running

 ```bash
-./harmonic uninstall
+/nix/harmonic uninstall
 ```

-If you're on Mac and trying to run this over SSH, ensure you enable `root` by running `dsenableroot`, running the uninstall, then running `dsenableroot -d` to disable `root` again.
+## As a library
+
+> We haven't published to [crates.io](https://crates.io/) yet. We plan to for 0.0.1.
+
+Add `harmonic` to your dependencies:
+
+```bash
+cargo add --git https://github.com/DeterminateSystems/harmonic
+```
+
+> **Building a CLI?** Check out the `cli` feature flag for `clap` integration.
+
+Then it's possible to review the documentation:
+
+```bash
+cargo doc --open -p harmonic
+```
+
+Documentation is also available via `nix` build:
+
+```bash
+nix build github:DeterminateSystems/harmonic#harmonic.doc
+firefox result-doc/harmonic/index.html
+```