diff options
author | Jade Lovelace <lix@jade.fyi> | 2024-05-05 15:32:20 -0700 |
---|---|---|
committer | Jade Lovelace <lix@jade.fyi> | 2024-05-05 16:11:01 -0700 |
commit | 748d8310fa7e044ad4c950ff38e31309ea3f606d (patch) | |
tree | 4a097ffd7a05e17f7b4a55660abff765e0346e11 /doc/manual/src/advanced-topics | |
parent | a3d4aca83691eb4bcbc2d3b20b559dbd59f02887 (diff) |
Fix the pages in the manual for Lix
This doesn't comprehensively fix everything outdated in the manual, or
make the manual greatly better, but it does note down where at least
jade noticed it was wrong, and it does fix all the instances of
referencing Nix to conform to the style guide to the best of our
ability.
A lot of things have been commented out for being wrong, and there are
three types of FIXME introduced:
- FIXME(Lix): generically Lix needs to fix it
- FIXME(Qyriad): re https://git.lix.systems/lix-project/lix/issues/215
- FIXME(meson): docs got outdated by meson changes and need rewriting
I did fix a bunch of it that I could, but there could certainly be
mistakes and this is definitely just an incremental improvement.
Fixes: https://git.lix.systems/lix-project/lix/issues/266
Change-Id: I5993c4603d7f026a887089fce77db08394362135
Diffstat (limited to 'doc/manual/src/advanced-topics')
-rw-r--r-- | doc/manual/src/advanced-topics/cores-vs-jobs.md | 4 | ||||
-rw-r--r-- | doc/manual/src/advanced-topics/diff-hook.md | 14 | ||||
-rw-r--r-- | doc/manual/src/advanced-topics/distributed-builds.md | 19 | ||||
-rw-r--r-- | doc/manual/src/advanced-topics/post-build-hook.md | 6 |
4 files changed, 23 insertions, 20 deletions
diff --git a/doc/manual/src/advanced-topics/cores-vs-jobs.md b/doc/manual/src/advanced-topics/cores-vs-jobs.md index 9e91ab9c7..5a2e2ab0e 100644 --- a/doc/manual/src/advanced-topics/cores-vs-jobs.md +++ b/doc/manual/src/advanced-topics/cores-vs-jobs.md @@ -1,13 +1,13 @@ # Tuning Cores and Jobs -Nix has two relevant settings with regards to how your CPU cores will +Lix has two relevant settings with regards to how your CPU cores will be utilized: `cores` and `max-jobs`. This chapter will talk about what they are, how they interact, and their configuration trade-offs. - `max-jobs`\ Dictates how many separate derivations will be built at the same time. If you set this to zero, the local machine will do no - builds. Nix will still substitute from binary caches, and build + builds. Lix will still substitute from binary caches, and build remotely if remote builders are configured. - `cores`\ diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md index 6e5834a15..367de6d6d 100644 --- a/doc/manual/src/advanced-topics/diff-hook.md +++ b/doc/manual/src/advanced-topics/diff-hook.md @@ -1,6 +1,6 @@ # Verifying Build Reproducibility -You can use Nix's `diff-hook` setting to compare build results. Note +You can use Lix's `diff-hook` setting to compare build results. Note that this hook is only executed if the results differ; it is not used for determining if the results are the same. @@ -44,7 +44,7 @@ built. Verify a path which already exists in the Nix store by passing `--check` to the build command. -If the build passes and is deterministic, Nix will exit with a status +If the build passes and is deterministic, Lix will exit with a status code of 0: ```console @@ -59,7 +59,7 @@ checking outputs of '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'... /nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable ``` -If the build is not deterministic, Nix will exit with a status code of +If the build is not deterministic, Lix will exit with a status code of 1: ```console @@ -75,7 +75,7 @@ error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs ``` -In the Nix daemon's log, we will now see: +In the Lix daemon's log, we will now see: ``` For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv: @@ -85,7 +85,7 @@ For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv: > 30204 ``` -Using `--check` with `--keep-failed` will cause Nix to keep the second +Using `--check` with `--keep-failed` will cause Lix to keep the second build's output in a special, `.check` path: ```console @@ -98,7 +98,7 @@ from '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check' ``` In particular, notice the -`/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check` output. Nix +`/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check` output. Lix has copied the build results to that directory where you can examine it. > []{#check-dirs-are-unregistered} **Note** @@ -114,7 +114,7 @@ has copied the build results to that directory where you can examine it. > build was not deterministic and also a check path does not exist. `--check` is only usable if the derivation has been built on the system -already. If the derivation has not been built Nix will fail with the +already. If the derivation has not been built Lix will fail with the error: error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md index 73a113d35..80443b53e 100644 --- a/doc/manual/src/advanced-topics/distributed-builds.md +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -1,10 +1,10 @@ # Remote Builds -Nix supports remote builds, where a local Nix installation can forward +Lix supports remote builds, where a local Lix installation can forward Nix builds to other machines. This allows multiple builds to be -performed in parallel and allows Nix to perform multi-platform builds in +performed in parallel and allows Lix to perform multi-platform builds in a semi-transparent way. For instance, if you perform a build for a -`x86_64-darwin` on an `i686-linux` machine, Nix can automatically +`x86_64-darwin` on an `i686-linux` machine, Lix can automatically forward the build to a `x86_64-darwin` machine, if available. To forward a build to a remote machine, it’s required that the remote @@ -38,12 +38,15 @@ contains Nix. > **Warning** > -> If you are building via the Nix daemon, it is the Nix daemon user account (that is, `root`) that should have SSH access to a user (not necessarily `root`) on the remote machine. +> If you are building via the Lix daemon (default on Linux and macOS), it is the Lix daemon user account (that is, `root`) that should have SSH access to a user (not necessarily `root`) on the remote machine. +> +> Furthermore, `root` needs to have the public host keys for the remote system in its `.ssh/known_hosts`. +> To add them to `known_hosts` for root, do `ssh-keyscan USER@HOST | sudo tee -a ~root/.ssh/known_hosts`. > > If you can’t or don’t want to configure `root` to be able to access the remote machine, you can use a private Nix store instead by passing e.g. `--store ~/my-nix` when running a Nix command from the local machine. The list of remote machines can be specified on the command line or in -the Nix configuration file. The former is convenient for testing. For +the Lix configuration file. The former is convenient for testing. For example, the following command allows you to build a derivation for `x86_64-darwin` on a Linux machine: @@ -84,17 +87,17 @@ default, set it to `-`. 3. The SSH identity file to be used to log in to the remote machine. If omitted, SSH will use its regular identities. -4. The maximum number of builds that Nix will execute in parallel on +4. The maximum number of builds that Lix will execute in parallel on the machine. Typically this should be equal to the number of CPU cores. For instance, the machine `itchy` in the example will execute up to 8 builds in parallel. 5. The “speed factor”, indicating the relative speed of the machine. If - there are multiple machines of the right type, Nix will prefer the + there are multiple machines of the right type, Lix will prefer the fastest, taking load into account. 6. A comma-separated list of *supported features*. If a derivation has - the `requiredSystemFeatures` attribute, then Nix will only perform + the `requiredSystemFeatures` attribute, then Lix will only perform the derivation on a machine that has the specified features. For instance, the attribute diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md index a251dec48..508d945ae 100644 --- a/doc/manual/src/advanced-topics/post-build-hook.md +++ b/doc/manual/src/advanced-topics/post-build-hook.md @@ -8,7 +8,7 @@ simple and working example, but it is not suitable for all use cases. The post build hook program runs after each executed build, and blocks the build loop. The build loop exits if the hook program fails. -Concretely, this implementation will make Nix slow or unusable when the +Concretely, this implementation will make Lix slow or unusable when the internet is slow or unreliable. A more advanced implementation might pass the store paths to a @@ -76,7 +76,7 @@ Then make sure the hook program is executable by the `root` user: # chmod +x /etc/nix/upload-to-cache.sh ``` -# Updating Nix Configuration +# Updating Lix Configuration Edit `/etc/nix/nix.conf` to run our hook, by adding the following configuration snippet at the end: @@ -119,7 +119,7 @@ warning: you did not specify '--add-root'; the result might be removed by the ga # Conclusion -We now have a Nix installation configured to automatically sign and +We now have a Lix installation configured to automatically sign and upload every local build to a remote binary cache. Before deploying this to production, be sure to consider the |