From ac06c07360d02ffd32579db6c1d735f27f394080 Mon Sep 17 00:00:00 2001 From: Yuki Langley Date: Tue, 8 Nov 2022 17:37:41 +0100 Subject: [PATCH] Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. --- source/faq.md | 26 +++---- source/reference/pinning-nixpkgs.md | 23 ++++-- source/tutorials/cross-compilation.md | 4 +- ...and-reproducible-developer-environments.md | 4 +- .../deploying-nixos-using-terraform.md | 26 +++---- source/tutorials/dev-environment.md | 10 +-- source/tutorials/install-nix.md | 24 +++---- .../installing-nixos-on-a-raspberry-pi.md | 11 +-- source/tutorials/nix-language.md | 72 +++++++------------ ...towards-reproducibility-pinning-nixpkgs.md | 9 +-- 10 files changed, 102 insertions(+), 107 deletions(-) diff --git a/source/faq.md b/source/faq.md index 1f0d90b..8f5e4e9 100644 --- a/source/faq.md +++ b/source/faq.md @@ -30,7 +30,7 @@ nix = { Using `Nix`: -```bash +```shell-session $ echo "trusted-binary-caches = https://hydra.snabb.co" >> /etc/nix/nix.conf $ nix-build helpers/bench.nix --option extra-binary-caches https://hydra.snabb.co ``` @@ -43,7 +43,7 @@ The default timeout for that is 1 hour as of writing. To wipe all cache-lookup-caches: -```bash +```shell-session $ rm $HOME/.cache/nix/binary-cache-v*.sqlite* ``` @@ -54,14 +54,14 @@ cache timeout. Try: -```bash +```shell-session $ sqlite3 /nix/var/nix/db/db.sqlite "pragma integrity_check" ``` Which will print the errors in the database. If the errors are due to missing references, the following may work: -```bash +```shell-session $ mv /nix/var/nix/db/db.sqlite /nix/var/nix/db/db.sqlite-bkp $ sqlite3 /nix/var/nix/db/db.sqlite-bkp ".dump" | sqlite3 /nix/var/nix/db/db.sqlite ``` @@ -77,17 +77,19 @@ to use older Nix. The solution is to dump the db and use old Nix version to initialize it: -``` -/path/to/nix/unstable/bin/nix-store --dump-db > /tmp/db.dump -mv /nix/var/nix/db /nix/var/nix/db.toonew -mkdir /nix/var/nix/db -nix-store --init (this is the old nix-store) -nix-store --load-db < /tmp/db.dump +```shell-session +$ /path/to/nix/unstable/bin/nix-store --dump-db > /tmp/db.dump +$ mv /nix/var/nix/db /nix/var/nix/db.toonew +$ mkdir /nix/var/nix/db +$ nix-store --init # this is the old nix-store +$ nix-store --load-db < /tmp/db.dump ``` ### How to build reverse dependencies of a package? -`nix-shell -p nixpkgs-review --run "nixpkgs-review wip"` +```shell-session +$ nix-shell -p nixpkgs-review --run "nixpkgs-review wip" +``` ### I'm getting: writing to file: Connection reset by peer @@ -125,7 +127,7 @@ Yes. Apply following patch: -``` +```diff diff --git a/nixos/lib/test-driver/test-driver.pl b/nixos/lib/test-driver/test-driver.pl index 8ad0d67..838fbdd 100644 --- a/nixos/lib/test-driver/test-driver.pl diff --git a/source/reference/pinning-nixpkgs.md b/source/reference/pinning-nixpkgs.md index e252037..bcfb68d 100644 --- a/source/reference/pinning-nixpkgs.md +++ b/source/reference/pinning-nixpkgs.md @@ -18,18 +18,29 @@ Different ways: ## Examples -- `nix-build -I ~/dev` +- ```shell-session + $ nix-build -I ~/dev + ``` -- `nix-build -I nixpkgs=http://nixos.org/channels/nixos-21.05/nixexprs.tar.xz` +- ```shell-session + $ nix-build -I nixpkgs=http://nixos.org/channels/nixos-21.05/nixexprs.tar.xz` + ``` -- `NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-21.05/nixexprs.tar.xz nix-build ...` +- ```shell-session + $ NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-21.05/nixexprs.tar.xz nix-build ...` + ``` - Using just Nix: - ``` + ```nix let pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-21.05.tar.gz") {}; - in pkgs.stdenv.mkDerivation { … } + in pkgs.stdenv.mkDerivation { ... } ``` -- To make ad-hoc environment available on NixOS: `nix.nixPath = [ ("nixpkgs=" + toString pkgs.path) ];` +- To make ad-hoc environment available on NixOS: + ```nix + { + nix.nixPath = [ ("nixpkgs=" + toString pkgs.path) ]; + } + ``` diff --git a/source/tutorials/cross-compilation.md b/source/tutorials/cross-compilation.md index ab92c27..6ea31f1 100644 --- a/source/tutorials/cross-compilation.md +++ b/source/tutorials/cross-compilation.md @@ -125,7 +125,7 @@ They usually do not match the corresponding platform config string. You can retrieve the platform string from `pkgsCross..stdenv.hostPlatform.config`: -``` +```shell-session nix-repl> pkgsCross.aarch64-multiplatform.stdenv.hostPlatform.config "aarch64-unknown-linux-gnu" ``` @@ -271,7 +271,7 @@ pkgs.pkgsStatic.callPackage ({ mkShell, zlib, pkg-config, file }: mkShell { And `hello.c`: -```c +```{code-block} c hello.c #include int main (void) diff --git a/source/tutorials/declarative-and-reproducible-developer-environments.md b/source/tutorials/declarative-and-reproducible-developer-environments.md index 5b51ffa..51300f8 100644 --- a/source/tutorials/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/declarative-and-reproducible-developer-environments.md @@ -123,8 +123,8 @@ to install it globally. At the top-level of your project run: -``` -echo "use nix" > .envrc && direnv allow +```shell-session +$ echo "use nix" > .envrc && direnv allow ``` The next time your launch your terminal and enter the top-level of your project direnv will check for changes. diff --git a/source/tutorials/deploying-nixos-using-terraform.md b/source/tutorials/deploying-nixos-using-terraform.md index f74c735..f1b5de5 100644 --- a/source/tutorials/deploying-nixos-using-terraform.md +++ b/source/tutorials/deploying-nixos-using-terraform.md @@ -19,14 +19,14 @@ We'll look at how to boot a NixOS machine and how to deploy the incremental chan 1. Start by providing the terraform executable: -```shell -nix-shell -p terraform +```shell-session +$ nix-shell -p terraform ``` 2. We are using [Terraform Cloud](https://app.terraform.io) as a [state/locking backend](https://www.terraform.io/docs/state/purpose.html): -```shell -terraform login +```shell-session +$ terraform login ``` 3. Make sure to [create an organization](https://app.terraform.io/app/organizations/new) like `myorganization` in your Terraform Cloud account. @@ -34,7 +34,7 @@ terraform login 5. Inside your workspace, under `Settings` / `General` change Execution Mode to `Local`. 6. Inside a new directory create a `main.tf` file with the following contents. This will start an AWS instance with the NixOS image using one SSH keypair and an SSH security group: -``` +```terraform terraform { backend "remote" { organization = "myorganization" @@ -103,7 +103,7 @@ output "public_dns" { The only NixOS specific snippet is: -``` +```terraform module "nixos_image" { source = "git::https://github.com/tweag/terraform-nixos.git/aws_image_nixos?ref=5f5a0408b299874d6a29d1271e9bffeee4c9ca71" release = "20.09" @@ -118,9 +118,9 @@ so that `aws_instance` resource can reference the AMI in [instance_type](https:/ 5. Make sure to [configure AWS credentials](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication). 6. Applying the Terraform configuration should get you a running NixOS: -```shell -terraform init -terraform apply +```shell-session +$ terraform init +$ terraform apply ``` ## Deploying NixOS changes @@ -140,7 +140,7 @@ the latest NixOS configuration and apply those changes to your instance. 2. Append the following snippet to your `main.tf`: -``` +```terraform module "deploy_nixos" { source = "git::https://github.com/tweag/terraform-nixos.git//deploy_nixos?ref=5f5a0408b299874d6a29d1271e9bffeee4c9ca71" nixos_config = "${path.module}/configuration.nix" @@ -152,9 +152,9 @@ module "deploy_nixos" { 3. Deploy: -```shell -terraform init -terraform apply +```shell-session +$ terraform init +$ terraform apply ``` ## Caveats diff --git a/source/tutorials/dev-environment.md b/source/tutorials/dev-environment.md index f681e9a..4892002 100644 --- a/source/tutorials/dev-environment.md +++ b/source/tutorials/dev-environment.md @@ -54,17 +54,17 @@ setup( Now build the package with: -```{code-block} bash test_nix_build.sh -nix-build +```shell-session +$ nix-build ``` This will create a symbolic link `result` to our package's path in the Nix store, which looks like `/nix/store/6i4l781jwk5vbia8as32637207kgkllj-myapp-0.1`. Look around to see what's inside. You may notice we can run the application from the package like this: `./result/bin/myapp`. But we can also use the `default.nix` as a shell environment to get the same result: -```bash -nix-shell default.nix -python myapp.py +```shell-session +$ nix-shell default.nix +$ python myapp.py ``` In this context, Nix takes on the role that you would otherwise use pip or virtualenv for. Nix installs required dependencies and separates the environment from others on your system. diff --git a/source/tutorials/install-nix.md b/source/tutorials/install-nix.md index 0a1afc3..1afbb97 100644 --- a/source/tutorials/install-nix.md +++ b/source/tutorials/install-nix.md @@ -6,8 +6,8 @@ Install Nix via the recommended [multi-user installation](https://nixos.org/manual/nix/stable/installation/multi-user.html): -```bash -sh <(curl -L https://nixos.org/nix/install) --daemon +```shell-session +$ sh <(curl -L https://nixos.org/nix/install) --daemon ``` :::{note} @@ -18,8 +18,8 @@ For security you may want to [verify the installation script] using GPG signatur Install Nix via the recommended [multi-user installation](https://nixos.org/manual/nix/stable/installation/multi-user.html): -```bash -sh <(curl -L https://nixos.org/nix/install) +```shell-session +$ sh <(curl -L https://nixos.org/nix/install) ``` :::{note} @@ -30,8 +30,8 @@ For security you may want to [verify the installation script] using GPG signatur Install Nix via the recommended [single-user installation](https://nixos.org/manual/nix/stable/installation/single-user.html): -```bash -sh <(curl -L https://nixos.org/nix/install) --no-daemon +```shell-session +$ sh <(curl -L https://nixos.org/nix/install) --no-daemon ``` :::{note} @@ -42,31 +42,31 @@ For security you may want to [verify the installation script] using GPG signatur Start a Docker shell with Nix: -```bash +```shell-session $ docker run -it nixos/nix ``` Or start a Docker shell with Nix exposing a `workdir` directory: -```bash +```shell-session $ mkdir workdir $ docker run -it -v $(pwd)/workdir:/workdir nixos/nix ``` The `workdir` example from above can be also used to start hacking on Nixpkgs: -```bash +```shell-session $ git clone git@github.com:NixOS/nixpkgs $ docker run -it -v $(pwd)/nixpkgs:/nixpkgs nixos/nix -docker> nix-build -I nixpkgs=/nixpkgs -A hello -docker> find ./result # this symlink points to the build package +bash-5.1# nix-build -I nixpkgs=/nixpkgs -A hello +bash-5.1# find ./result # this symlink points to the build package ``` ## Verify installation Check the installation by opening **a new terminal** and typing: -```bash +```shell-session $ nix --version nix (Nix) 2.11.0 ``` diff --git a/source/tutorials/installing-nixos-on-a-raspberry-pi.md b/source/tutorials/installing-nixos-on-a-raspberry-pi.md index 909d221..39a59a1 100644 --- a/source/tutorials/installing-nixos-on-a-raspberry-pi.md +++ b/source/tutorials/installing-nixos-on-a-raspberry-pi.md @@ -33,9 +33,10 @@ Prepare the AArch64 image on your laptop: ```shell-session $ nix-shell -p wget zstd -$ wget https://hydra.nixos.org/build/160738647/download/1/nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img.zst -$ unzstd -d nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img.zst -$ dmesg --follow + +[nix-shell:~]$ wget https://hydra.nixos.org/build/160738647/download/1/nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img.zst +[nix-shell:~]$ unzstd -d nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img.zst +[nix-shell:~]$ dmesg --follow ``` :::{note} @@ -51,8 +52,8 @@ Press `ctrl-c` to stop `dmesg --follow`. Copy NixOS to your SD card by replacing `sdX` with the name of your device: -```shell-session -sudo dd if=nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img of=/dev/sdX bs=4096 conv=fsync status=progress +```console +[nix-shell:~]$ sudo dd if=nixos-sd-image-22.05pre335501.c71f061c68b-aarch64-linux.img of=/dev/sdX bs=4096 conv=fsync status=progress ``` Once that command exits, **move the SD card into your Raspberry Pi and power it on**. diff --git a/source/tutorials/nix-language.md b/source/tutorials/nix-language.md index 2e6fb22..f050128 100644 --- a/source/tutorials/nix-language.md +++ b/source/tutorials/nix-language.md @@ -100,18 +100,14 @@ The following example is a Nix expression adding two numbers: Use [`nix repl`][nix-repl] to evaluate Nix expressions interactively (by typing them on the command line): -```console -nix repl -``` +```shell-session +$ nix repl +Welcome to Nix 2.5.1. Type :? for help. - Welcome to Nix 2.5.1. Type :? for help. - -```console nix-repl> 1 + 2 +3 ``` - 3 - :::{note} The Nix language by default uses lazy evaluation, and will only compute values when needed. @@ -120,19 +116,13 @@ If your output does not match the example, try prepending `:p` to the input expr Example: -```console +```shell-session nix-repl> { a.b.c = 1; } -``` +{ a = { ... }; } - { a = { ... }; } - - -```console nix-repl> :p { a.b.c = 1; } +{ a = { b = { c = 1; }; }; } ``` - - { a = { b = { c = 1; }; }; } - ::: [nix-repl]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl.html @@ -141,25 +131,22 @@ nix-repl> :p { a.b.c = 1; } Use [`nix-instantiate --eval`][nix-instantiate] to evaluate the expression in a Nix file. -```console -echo 1 + 2 > file.nix - -nix-instantiate --eval file.nix +```shell-session +$ echo 1 + 2 > file.nix +$ nix-instantiate --eval file.nix +3 ``` - 3 -
Detailed explanation The first command writes `1 + 2` to a file `file.nix` in the current directory. The contents of `file.nix` are now `1 + 2`, which you can check with -```console -cat file.nix +```shell-session +$ cat file.nix +1 + 2 ``` - 1 + 2 - The second command runs `nix-instantiate` with the `--eval` option on `file.nix`, which reads the file and evaluates the contained Nix expression. The resulting value is printed as output. @@ -171,13 +158,11 @@ If `--eval` is omitted, `nix-instantiate` expects the expression in the given fi :::{note} `nix-instantiate --eval` will evaluate `default.nix` if no file name is specified. -```console -echo 1 + 2 > default.nix - -nix-instantiate --eval +```shell-session +$ echo 1 + 2 > default.nix +$ nix-instantiate --eval +3 ``` - - 3 ::: :::{note} @@ -188,23 +173,18 @@ If your output does not match the example, try adding the `--strict` option to ` Example: -```console -echo "{ a.b.c = 1; }" > file.nix - -nix-instantiate --eval file.nix +```shell-session +$ echo "{ a.b.c = 1; }" > file.nix +$ nix-instantiate --eval file.nix +{ a = ; } ``` - { a = ; } - - -```console -echo "{ a.b.c = 1; }" > file.nix - -nix-instantiate --eval --strict file.nix +```shell-session +$ echo "{ a.b.c = 1; }" > file.nix +$ nix-instantiate --eval --strict file.nix +{ a = { b = { c = 1; }; }; } ``` - { a = { b = { c = 1; }; }; } - ::: [nix-instantiate]: https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html diff --git a/source/tutorials/towards-reproducibility-pinning-nixpkgs.md b/source/tutorials/towards-reproducibility-pinning-nixpkgs.md index cbd3947..455b394 100644 --- a/source/tutorials/towards-reproducibility-pinning-nixpkgs.md +++ b/source/tutorials/towards-reproducibility-pinning-nixpkgs.md @@ -42,7 +42,7 @@ If you'd like a bit more automation around bumping dependencies, including Nixpk [niv](https://github.com/nmattia/niv/) is made for exactly that. Niv itself is available in `nixpkgs` so using it is simple: -``` +```shell-session $ nix-shell -p niv --run "niv init" ``` @@ -53,15 +53,16 @@ By default, `niv` will use the **latest stable** NixOS release. However, you sho You can see which version `niv` is tracking as follows: -``` +```shell-session $ niv show ``` And you can change the tracking branch to the one you want like this: -``` +```shell-session $ niv modify nixpkgs --branch nixos-21.05 ``` + You can use the generated `nix/sources.nix` with a top-level `default.nix`: ```nix @@ -74,7 +75,7 @@ You can use the generated `nix/sources.nix` with a top-level `default.nix`: And you can update all the dependencies by running: -``` +```shell-session $ nix-shell -p niv --run "niv update" ```