From 81617d94cd81916b4dc2e13d9c952f629e6b81a6 Mon Sep 17 00:00:00 2001 From: worktheclock <85885287+worktheclock@users.noreply.github.com> Date: Wed, 4 May 2022 13:32:17 +0200 Subject: [PATCH 1/7] Declarative reproducible developer environments RITZA language edit. --- ...and-reproducible-developer-environments.md | 55 ++++++++----------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index dfa3aed..9c40a8b 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -2,27 +2,24 @@ # Declarative and reproducible developer environments -In the {ref}`ad-hoc-envs` tutorial we looked at providing shell -environments for when we need a quick'n'dirty way of getting hold -of some tools. +In the {ref}`ad-hoc-envs` tutorial we looked at providing shell environments for when we need a quick 'n dirty way of getting hold of some tools. -In this tutorial we'll take a look how to create {term}`reproducible` -shell environments given a declarative configuration file called a Nix expression. +In this tutorial, we'll take a look how to create {term}`reproducible` shell environments given a declarative configuration file called a Nix expression. -## When are declarative shell environments useful? +## When is a declarative shell environment useful? -This is the quickest approach to getting started with Nix: +A declarative shell environment is the quickest approach to getting started with Nix: -- use single command to invoke it via `nix-shell` -- it works across different operating systems (Linux / MacOS) -- you share the exact same environment with all developers +- Use a single command to invoke it via `nix-shell`. +- It works across different operating systems (Linux / MacOS). +- Share the exact same environment with all developers. Developer environments allow you to: -- provide CLI tools, such as `psql`, `jq`, `tmux`, etc -- provide developer libraries, such as `zlib`, `openssl`, etc -- set shell environment variables -- execute bash during environment activation +- Provide CLI tools, such as `psql`, `jq`, `tmux`, etc. +- Provide developer libraries, such as `zlib`, `openssl`, etc. +- Set shell environment variables. +- Execute bash during environment activation. ## Getting started @@ -41,11 +38,11 @@ pkgs.mkShell { ``` :::{note} -To understand the first line, read through {ref}`pinning nixpkgs tutorial `. +To understand the first line, read our tutorial on {ref}`pinning Nixpkgs`. ::: -We import `nixpkgs` and make a shell with `which` and `htop` available in `$PATH`. -`zlib` provides libraries and headers in case we're compiling something against it. +We import `nixpkgs` and make a shell with `which` and `htop` available in `$PATH`. We use `zlib` to provide libraries and headers in case we're compiling something against it. + To enter the environment: ```shell-session @@ -57,16 +54,13 @@ copying path '/nix/store/072a6x7rwv5f8wr6f5s1rq8nnm767cfp-htop-2.2.0' from 'http [nix-shell:~]$ ``` -The command will start downloading the missing packages from the binary cache. +This command will start downloading the missing packages from the binary cache. -Once it's done, you are dropped into a new -shell. This shell provides the packages specified in `shell.nix`. +Once the download is done, you are dropped into a new shell. This shell provides the packages specified in `shell.nix`. -Run `htop` to confirm that it is present. Quit the program by hitting -`q`. +Run `htop` to confirm that it is present. Quit the program by hitting `q`. -Now, try `which htop` to check where the `htop` command is on disk. -You should see something similar to this: +Now try `which htop` to check where the `htop` command is on disk. You should see something similar to this: ```shell-session [nix-shell:~]$ which htop @@ -110,11 +104,9 @@ world ## `direnv`: Automatically activating the environment on directory change -Besides activating the environment for each project, every time you change -`shell.nix` you need to re-enter the shell. +Besides activating the environment for each project, every time you change `shell.nix` you need to re-enter the shell. -You can use `direnv` to automate this process for you, with the downside that each developer needs -to install it globally. +You can use `direnv` to automate this process for you, with the downside that each developer needs to install it globally. ### Setting up `direnv` @@ -127,7 +119,7 @@ At the top-level of your project run: $ 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. +The next time you launch your terminal and enter the top-level of your project, `direnv` will check for changes. ```shell-session $ cd myproject @@ -138,6 +130,5 @@ hello ## Next steps -- {ref}`pinning-nixpkgs` to see different ways to import nixpkgs -- To quickly set up a Nix project read through - [Getting started Nix template](https://github.com/nix-dot-dev/getting-started-nix-template). +- Take a look at our {ref}`pinning Nixpkgs` tutorial to see different ways to import Nixpkgs. +- To quickly set up a Nix project, read [Getting started Nix template](https://github.com/nix-dot-dev/getting-started-nix-template). From 1476d086341f4ed264289223f8b627202fb4ab0f Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 11:37:16 -0500 Subject: [PATCH 2/7] add more contextual info to introduction --- .../declarative-and-reproducible-developer-environments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index 9c40a8b..1a48b91 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -2,9 +2,9 @@ # Declarative and reproducible developer environments -In the {ref}`ad-hoc-envs` tutorial we looked at providing shell environments for when we need a quick 'n dirty way of getting hold of some tools. +In the {ref}`ad-hoc-envs` tutorial, we looked at imperatively creating shell environments using `nix-shell -p`, for when we need a quick way to access some tools without having to install them globally. We also saw how to execute that command with a specific nixpkgs git commit as an argument, to recreate the same environment used previously. -In this tutorial, we'll take a look how to create {term}`reproducible` shell environments given a declarative configuration file called a Nix expression. +In this tutorial, we'll see how to *declaratively* create {term}`reproducible` shell environments using a configuration file called a Nix expression. ## When is a declarative shell environment useful? From c899dd4b5cd736fa1065dc2e13d43f6470c60039 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 11:39:05 -0500 Subject: [PATCH 3/7] actually explain why declarative environments are useful --- ...e-and-reproducible-developer-environments.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index 1a48b91..532c778 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -6,20 +6,15 @@ In the {ref}`ad-hoc-envs` tutorial, we looked at imperatively creating shell env In this tutorial, we'll see how to *declaratively* create {term}`reproducible` shell environments using a configuration file called a Nix expression. -## When is a declarative shell environment useful? +## When are declarative shell environments useful? -A declarative shell environment is the quickest approach to getting started with Nix: +Both methods of creating development shell environments allow you to provide CLI tools like `psql`, `jq`, and `tmux`, as well as developer libraries like `zlib` and `openssl`. However, only the *declarative* approach allows you to -- Use a single command to invoke it via `nix-shell`. -- It works across different operating systems (Linux / MacOS). -- Share the exact same environment with all developers. +- automatically set shell environment variables, +- execute bash commands during environment activation, and +- share the exact same environment with other developers. -Developer environments allow you to: - -- Provide CLI tools, such as `psql`, `jq`, `tmux`, etc. -- Provide developer libraries, such as `zlib`, `openssl`, etc. -- Set shell environment variables. -- Execute bash during environment activation. +In addition to these, declaring development environments in Nix expression files enables you to use all the source code workflows you're used to, like committing that file to version control, using code analysis tools, and so on. ## Getting started From 9448dd1d0ea6a13e238595b3a03a9f32b212ad73 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 11:42:49 -0500 Subject: [PATCH 4/7] reword some parts of the getting started section. some bikeshedding --- ...rative-and-reproducible-developer-environments.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index 532c778..f8972ae 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -18,7 +18,7 @@ In addition to these, declaring development environments in Nix expression files ## Getting started -At the top-level of your project create `shell.nix` with the following contents: +At the top-level of your project, create `shell.nix` with the following contents: ```nix { pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz") {} }: @@ -33,12 +33,12 @@ pkgs.mkShell { ``` :::{note} -To understand the first line, read our tutorial on {ref}`pinning Nixpkgs`. +To better understand the first line, read through the tutorial on {ref}`pinning nixpkgs `. ::: -We import `nixpkgs` and make a shell with `which` and `htop` available in `$PATH`. We use `zlib` to provide libraries and headers in case we're compiling something against it. +This expression imports `nixpkgs`, then creates a shell with `which` and `htop` available in `$PATH`. `zlib` is also added, to provide some common libraries and headers in case we need to compile something against it. -To enter the environment: +To enter the environment, run `nix-shell` in the same directory as `shell.nix`: ```shell-session $ nix-shell @@ -51,11 +51,11 @@ copying path '/nix/store/072a6x7rwv5f8wr6f5s1rq8nnm767cfp-htop-2.2.0' from 'http This command will start downloading the missing packages from the binary cache. -Once the download is done, you are dropped into a new shell. This shell provides the packages specified in `shell.nix`. +Once the download completes, you are dropped into a new shell, which provides the packages specified in `shell.nix`. Run `htop` to confirm that it is present. Quit the program by hitting `q`. -Now try `which htop` to check where the `htop` command is on disk. You should see something similar to this: +Now try `which htop` to check where the `htop` executable is stored in the filesystem. You should see something similar to this: ```shell-session [nix-shell:~]$ which htop From 0ee2bc6371883fa704023ce229027c2edb15f85b Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 11:47:20 -0500 Subject: [PATCH 5/7] add motivation & clarification to environment customization section --- .../declarative-and-reproducible-developer-environments.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index f8972ae..e4924f1 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -64,7 +64,8 @@ Now try `which htop` to check where the `htop` executable is stored in the files ## Customizing your developer environment -Given the following `shell.nix`: +We may want to run some commands whenever we enter the environment, for example echoing a message to the console. We may also want to set some variables that are only present within the environment. +To accomplish these, we can modify the `shell.nix` from the previous section like so: ```nix { pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz") {} }: @@ -94,7 +95,7 @@ hello world ``` -- The `shellHook` section allows you to execute bash while entering the shell environment. +- The `shellHook` section allows you to execute bash commands while entering the shell environment. - Any attributes passed to `mkShell` function are available once the shell environment is active. ## `direnv`: Automatically activating the environment on directory change From 26e61307adfcd8cf2c3de3d2bfd37cd25b5c1459 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 11:53:58 -0500 Subject: [PATCH 6/7] reword parts of direnv section --- ...declarative-and-reproducible-developer-environments.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index e4924f1..ac3c61e 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -100,22 +100,22 @@ world ## `direnv`: Automatically activating the environment on directory change -Besides activating the environment for each project, every time you change `shell.nix` you need to re-enter the shell. +In addition to manually activating the environment for each project, you need to re-enter the shell every time you change `shell.nix`. -You can use `direnv` to automate this process for you, with the downside that each developer needs to install it globally. +You can use `direnv` to automate this process for you, with the tradeoff that each developer using the environment needs to install it globally. ### Setting up `direnv` 1. [Install nix-direnv with your package manager or from source](https://github.com/nix-community/nix-direnv) 2. [Hook it into your shell](https://direnv.net/docs/hook.html) -At the top-level of your project run: +From the top-level directory of your project run: ```shell-session $ echo "use nix" > .envrc && direnv allow ``` -The next time you launch your terminal and enter the top-level of your project, `direnv` will check for changes. +The next time you launch your terminal and enter the top-level directory of your project, `direnv` will check for changes to the `shell.nix` file. ```shell-session $ cd myproject From f8b9cae27b5aebc16e8997556bf4135d505705a5 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 27 Jun 2023 12:36:54 -0500 Subject: [PATCH 7/7] fix reference link --- .../declarative-and-reproducible-developer-environments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md index ac3c61e..011665d 100644 --- a/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md +++ b/source/tutorials/first-steps/declarative-and-reproducible-developer-environments.md @@ -126,5 +126,5 @@ hello ## Next steps -- Take a look at our {ref}`pinning Nixpkgs` tutorial to see different ways to import Nixpkgs. +- Take a look at our {ref}`pinning-nixpkgs` tutorial to see different ways to import Nixpkgs. - To quickly set up a Nix project, read [Getting started Nix template](https://github.com/nix-dot-dev/getting-started-nix-template).