From 894dca0590a034921d86855703b4b6c02625081f Mon Sep 17 00:00:00 2001 From: Luc Perkins Date: Fri, 24 May 2024 14:33:37 -0300 Subject: [PATCH] Document config settings in README --- .github/workflows/ci.yml | 86 ++++++++++++++++++++++++++++++++++ README.md | 77 ++++++++++++++++++++++++++++++ src/cli/arg/instrumentation.rs | 4 +- src/cli/subcommand/install.rs | 3 ++ src/settings.rs | 8 ++-- 5 files changed, 172 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5e968531e..989df6756 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,6 +18,9 @@ jobs: build-aarch64-linux: uses: ./.github/workflows/build-aarch64-linux.yml + + build-aarch64-darwin: + uses: ./.github/workflows/build-aarch64-darwin.yml lints: name: Lints @@ -462,3 +465,86 @@ jobs: echo "/nix exists" exit 1 fi + + run-aarch64-darwin: + name: Run aarch64 Darwin + runs-on: macos-latest-xlarge + needs: [lints, build-aarch64-darwin] + permissions: + id-token: "write" + contents: "read" + steps: + - uses: actions/checkout@v3 + - name: Restore Github cache artifacts + uses: actions/cache/restore@v3 + with: + path: nix-installer + key: aarch64-darwin-artifacts-${{ github.sha }} + - name: Move & set executable + run: | + mkdir install-root + cp nix-installer.sh install-root/nix-installer.sh + mv ./nix-installer install-root/nix-installer-aarch64-darwin + chmod +x install-root/nix-installer-aarch64-darwin install-root/nix-installer.sh + - run: brew install fish coreutils + - name: Initial install + uses: DeterminateSystems/nix-installer-action@main + with: + flakehub: true + local-root: install-root/ + logger: pretty + log-directives: nix_installer=debug + backtrace: full + github-token: ${{ secrets.GITHUB_TOKEN }} + extra-conf: | + trusted-users = root runner + - name: Initial uninstall (without a `nix run` first) + run: sudo -E /nix/nix-installer uninstall + env: + NIX_INSTALLER_NO_CONFIRM: true + NIX_INSTALLER_LOGGER: pretty + NIX_INSTALLER_LOG_DIRECTIVES: nix_installer=debug + RUST_BACKTRACE: full + - name: Repeated install + uses: DeterminateSystems/nix-installer-action@main + with: + flakehub: true + local-root: install-root/ + logger: pretty + log-directives: nix_installer=debug + backtrace: full + github-token: ${{ secrets.GITHUB_TOKEN }} + extra-conf: trusted-users = root runner + - name: echo $PATH + run: echo $PATH + - name: Test `nix` with `$GITHUB_PATH` + if: success() || failure() + run: | + nix run nixpkgs#hello + nix profile install nixpkgs#hello + hello + nix store gc + nix run nixpkgs#hello + - name: Test bash + run: nix-instantiate -E 'builtins.currentTime' --eval + if: success() || failure() + shell: bash --login {0} + - name: Test sh + run: nix-instantiate -E 'builtins.currentTime' --eval + if: success() || failure() + shell: sh -l {0} + - name: Test zsh + run: nix-instantiate -E 'builtins.currentTime' --eval + if: success() || failure() + shell: zsh --login --interactive {0} + - name: Test fish + run: nix-instantiate -E 'builtins.currentTime' --eval + if: success() || failure() + shell: fish --login {0} + - name: Repeated uninstall + run: sudo -E /nix/nix-installer uninstall + env: + NIX_INSTALLER_NO_CONFIRM: true + NIX_INSTALLER_LOGGER: pretty + NIX_INSTALLER_LOG_DIRECTIVES: nix_installer=debug + RUST_BACKTRACE: full diff --git a/README.md b/README.md index d6a0a8d15..96e443510 100644 --- a/README.md +++ b/README.md @@ -469,6 +469,83 @@ The Determinate Nix installer has numerous advantages: It has been wonderful to collaborate with other participants in the Nix Installer Working Group and members of the broader community. The working group maintains a [foundation owned fork of the installer](https://github.com/nixos/experimental-nix-installer/). +## Installer settings + +The Determinate Nix Installer provides a variety of configuration settings, some [general](#general-settings) and some on a per-command basis. +All settings are available via flags or via `NIX_INSTALLER_*` environment variables. + +### General settings + +These settings are available for all commands. + +| Flag(s) | Description | Default (if any) | Environment variable | +|--------------------------|----------------------------------------------------|------------------|--------------------------------------| +| `--log-directives` | Tracing directives delimited by comma | | `NIX_INSTALLER_LOG_DIRECTIVES` | +| `--logger` | Which logger to use (options are `compact`, `full`, `pretty`, and `json`) | `compact` | `NIX_INSTALLER_LOGGER` | +| `--verbose` | Enable debug logs, (`-vv` for trace) | `false` | `NIX_INSTALLER_VERBOSITY` | + +### Installation (`nix-installer install`) + +| Flag(s) | Description | Default (if any) | Environment variable | +|--------------------------|----------------------------------------------------|------------------|--------------------------------------| +| `--diagnostic-attribution` | Relate the install diagnostic to a specific value | | `NIX_INSTALLER_DIAGNOSTIC_ATTRIBUTION` | +| `--diagnostic-endpoint` | The URL or file path for an installation diagnostic to be sent | `https://install.determinate.systems/nix/diagnostic` | `NIX_INSTALLER_DIAGNOSTIC_ENDPOINT` | +| `--explain` | Provide an explanation of the changes the installation process will make to your system | `false` | `NIX_INSTALLER_EXPLAIN` | +| `--extra-conf` | Extra configuration lines for `/etc/nix.conf` | | `NIX_INSTALLER_EXTRA_CONF` | +| `--force` | If `nix-installer` should forcibly recreate files it finds existing | `false` | `NIX_INSTALLER_FORCE` | +| `--init` | Which init system to configure (if `--init none` Nix will be root-only) | `launchd` (macOS), `systemd` (Linux) | `NIX_INSTALLER_INIT` | +| `--nix-build-group-id` | The Nix build group GID | `30000` | `NIX_INSTALLER_NIX_BUILD_GROUP_ID` | +| `--nix-build-group-name` | The Nix build group name | `nixbld` | `NIX_INSTALLER_NIX_BUILD_GROUP_NAME` | +| `--nix-build-user-count` | The number of build users to create | `32` | `NIX_INSTALLER_NIX_BUILD_USER_COUNT` | +| `--nix-build-user-id-base` | The Nix build user base UID (ascending) | `300` (macOS), `30000` (Linux) | `NIX_INSTALLER_NIX_BUILD_USER_ID_BASE` | +| `--nix-build-user-prefix` | The Nix build user prefix (user numbers will be postfixed) | `_nixbld` (macOS), `nixbld` (Linux) | `NIX_INSTALLER_NIX_BUILD_USER_PREFIX` | +| `--nix-package-url` | The Nix package URL | | `NIX_INSTALLER_NIX_PACKAGE_URL` | +| `--no-confirm` | Run installation without requiring explicit user confirmation | `false` | `NIX_INSTALLER_NO_CONFIRM` | +| `--no-modify-profile` | Modify the user profile to automatically load Nix. | `true` | `NIX_INSTALLER_MODIFY_PROFILE` | +| `--proxy` | The proxy to use (if any); valid proxy bases are `https://$URL`, `http://$URL` and `socks5://$URL` | | `NIX_INSTALLER_PROXY` | +| `--ssl-cert-file` | An SSL cert to use (if any); used for fetching Nix and sets `ssl-cert-file` in `/etc/nix/nix.conf` | | `NIX_INSTALLER_SSL_CERT_FILE` | +| `--no-start-daemon` | Start the daemon (if not `--init none`) | `true` | `NIX_INSTALLER_START_DAEMON` | + +You can also specify a planner with the first argument: + +```shell +nix-installer install +``` + +Alternatively, you can use the `NIX_INSTALLER_PLAN` environment variable: + +```shell +NIX_INSTALLER_PLAN= nix-installer install +``` + +### Uninstalling (`nix-installer uninstall`) + +| Flag(s) | Description | Default (if any) | Environment variable | +|--------------------------|----------------------------------------------------|------------------|--------------------------------------| +| `--explain` | Provide an explanation of the changes the installation process will make to your system | `false` | `NIX_INSTALLER_EXPLAIN` | +| `--no-confirm` | Run installation without requiring explicit user confirmation | `false` | `NIX_INSTALLER_NO_CONFIRM` | + +You can also specify an installation receipt as the first argument (the default is `/nix/receipt.json`): + +```shell +nix-installer uninstall /path/to/receipt.json +``` + +### Planning (`nix-installer plan`) + +| Flag(s) | Description | Default (if any) | Environment variable | +|--------------------------|----------------------------------------------------|------------------|--------------------------------------| +| `--out-file` | Where to write the generated plan (in JSON format) | `/dev/stdout` | `NIX_INSTALLER_PLAN_OUT_FILE` | + +### Repairing (`nix-installer repair`) + +| Flag(s) | Description | Default (if any) | Environment variable | +|--------------------------|----------------------------------------------------|------------------|--------------------------------------| +| `--no-confirm` | Run installation without requiring explicit user confirmation | `false` | `NIX_INSTALLER_NO_CONFIRM` | + +### Self-test (`nix-installer self-test`) + +`nix-installer self-test` only takes [general settings](#general-settings). ## Diagnostics diff --git a/src/cli/arg/instrumentation.rs b/src/cli/arg/instrumentation.rs index d4ecf652a..085eb8df1 100644 --- a/src/cli/arg/instrumentation.rs +++ b/src/cli/arg/instrumentation.rs @@ -32,10 +32,10 @@ pub struct Instrumentation { /// Enable debug logs, -vv for trace #[clap(short = 'v', env = "NIX_INSTALLER_VERBOSITY", long, action = clap::ArgAction::Count, global = true)] pub verbose: u8, - /// Which logger to use + /// Which logger to use (options are `compact`, `full`, `pretty`, and `json`) #[clap(long, env = "NIX_INSTALLER_LOGGER", default_value_t = Default::default(), global = true)] pub logger: Logger, - /// Tracing directives + /// Tracing directives delimited by comma /// /// See https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives #[clap(long = "log-directive", global = true, env = "NIX_INSTALLER_LOG_DIRECTIVES", value_delimiter = ',', num_args = 0..)] diff --git a/src/cli/subcommand/install.rs b/src/cli/subcommand/install.rs index a72c05b4a..9b18436c6 100644 --- a/src/cli/subcommand/install.rs +++ b/src/cli/subcommand/install.rs @@ -40,6 +40,7 @@ Some planners have additional options which can be set from the planner's subcom #[derive(Debug, Parser)] #[command(args_conflicts_with_subcommands = true)] pub struct Install { + /// Run installation without requiring explicit user confirmation #[clap( long, env = "NIX_INSTALLER_NO_CONFIRM", @@ -52,6 +53,7 @@ pub struct Install { #[clap(flatten)] pub settings: CommonSettings, + /// Provide an explanation of the changes the installation process will make to your system #[clap( long, env = "NIX_INSTALLER_EXPLAIN", @@ -61,6 +63,7 @@ pub struct Install { )] pub explain: bool, + /// A path to a non-default installer plan #[clap(env = "NIX_INSTALLER_PLAN")] pub plan: Option, diff --git a/src/settings.rs b/src/settings.rs index 444d4b09e..329183072 100644 --- a/src/settings.rs +++ b/src/settings.rs @@ -50,7 +50,7 @@ Settings which only apply to certain [`Planner`](crate::planner::Planner)s shoul #[derive(Debug, serde::Deserialize, serde::Serialize, Clone)] #[cfg_attr(feature = "cli", derive(clap::Parser))] pub struct CommonSettings { - /// Modify the user profile to automatically load nix + /// Modify the user profile to automatically load Nix #[cfg_attr( feature = "cli", clap( @@ -102,7 +102,7 @@ pub struct CommonSettings { )] pub nix_build_user_prefix: String, - /// Number of build users to create + /// The number of build users to create #[cfg_attr( feature = "cli", clap( @@ -139,11 +139,11 @@ pub struct CommonSettings { )] pub nix_package_url: Option, - /// The proxy to use (if any), valid proxy bases are `https://$URL`, `http://$URL` and `socks5://$URL` + /// The proxy to use (if any); valid proxy bases are `https://$URL`, `http://$URL` and `socks5://$URL` #[cfg_attr(feature = "cli", clap(long, env = "NIX_INSTALLER_PROXY"))] pub proxy: Option, - /// An SSL cert to use (if any), used for fetching Nix and sets `ssl-cert-file` in `/etc/nix/nix.conf` + /// An SSL cert to use (if any); used for fetching Nix and sets `ssl-cert-file` in `/etc/nix/nix.conf` #[cfg_attr(feature = "cli", clap(long, env = "NIX_INSTALLER_SSL_CERT_FILE"))] pub ssl_cert_file: Option,