From b19d35a8f0e0c1ab8c1c6a864e742964b4891d7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Thu, 21 May 2020 09:53:04 +0200 Subject: [PATCH] ad hoc developer environments: review feedback --- .../ad-hoc-developer-environments.rst | 77 ++++++++++++++----- source/tutorials/first-shell.rst | 14 ++-- 2 files changed, 66 insertions(+), 25 deletions(-) diff --git a/source/tutorials/ad-hoc-developer-environments.rst b/source/tutorials/ad-hoc-developer-environments.rst index 96213eed08f..6875792fec0 100644 --- a/source/tutorials/ad-hoc-developer-environments.rst +++ b/source/tutorials/ad-hoc-developer-environments.rst @@ -2,13 +2,35 @@ Ad hoc developer environments ============================= Assuming you have :ref:`Nix installed `, it is able to download packages -and provide a new shell with packages available. +and provide a new **shell environment** with packages available. This is a great way to play with Nix tooling and see some of its potential. -When are such environments useful? ----------------------------------- +What is a shell environment? +---------------------------- + +A hello world example: + +.. code:: shell-session + + $ hello + The program ‘hello’ is currently not installed. + + $ nix-shell -p hello + + [nix-shell:~]$ hello + Hello, world! + + [nix-shell:~]$ exit + exit + + $ hello + The program ‘hello’ is currently not installed. + + +When are shell environments useful? +----------------------------------- Sometimes you'd like **to use a tool, but it's not installed yet**. You don't want to bother installing software, you only want to have it now. @@ -21,11 +43,15 @@ tools** being used and such that it works between all Linux distributions and on Sometimes you'd like **to provide a script that is reproducible**, meaning it will also provide the tooling. + Searching package attribute names --------------------------------- -To search available packages head over to `official package list `_ -or query in your terminal: +What can you put in a shell environment?” + +To start, anything that's in the `official package list `_ can become part of the shell environment. + +You can search the package list using: .. code:: shell-session @@ -36,12 +62,16 @@ or query in your terminal: The first column is the :term:`attribute name` and the second is :term:`package name` and its version. +Once you are comfortable doing this, you can add other things too. +For example, packages of your own or custom shell aliases. + .. note:: Query for searching packages is a regex, so be aware when it comes to special characters. -Ad hoc environments -------------------- + +Ad hoc shell environments +------------------------- Once you have the :term:`attribute name` for packages, you can start a shell: @@ -72,7 +102,7 @@ A quick example using Python and ``$PYTHONPATH``: .. code:: shell-session - $ nix-shell -p 'python38.withPackages (ps: [ ps.django ])' + $ nix-shell -p 'python38.withPackages (packages: [ packages.django ])' ... [nix-shell:~]$ python -c 'import django; print(django)' @@ -83,35 +113,40 @@ We create ad hoc environment with ``$PYTHONPATH`` set and ``python`` available w ``-p`` argument accepts Nix expression, but going into the Nix language is out of scope of this tutorial. -Improving reproducability -------------------------- - -These environments are **really convenient**, but they are **not yet reproducible**. +Towards reproducability +----------------------- If you handed over these commands to another developer, they might get different results. -However the following is entirely reproducible and something you can share between collegues: +These shell environments are **really convenient**, but they are **not yet reproducible**. + +What do we mean by reproducible? No matter when or on what machine you run the command, the result will be the same. +The very same environment will be provided each time. + +The following is entirely reproducible and something you can share between colleagues: .. code:: shell-session $ nix-shell --pure -p git --run "git --version" -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/82b5f87fcc710a99c47c5ffe441589807a8202af.tar.gz + + [nix-shell:~]$ git --version git version 2.25.0 -There are a few things going on here: +There are two things going on here: 1. ``--pure`` flag makes sure that bash environnment from your system is not inherited. That means the only ``git`` is available inside the shell. This is useful for one-liners and scripts that run for example on a CI. While developing however, we'd like to have our editor around and - a bunch of other things. + a bunch of other things so we skip the flag. -2. ``--run`` will execute a command instead of entering shell. This is only a demonstration how to automate things rather than reproducability improvement. - -3. ``-I`` pins nixpkgs revision to an exact git revision, leaving no doubt which version of Nix packages will be used. +2. ``-I`` pins nixpkgs revision to an exact git revision, leaving no doubt which version of Nix packages will be used. Reproducible executables ------------------------ -Finally, we can wrap scripts to provide a reproducible environment that we can commit to a git repository. +Finally, we can wrap scripts to provide a reproducible shell environment that we can commit to a git repository +and share with strangers online. As long as they have Nix installed, they'll be able to execute the script without +worrying about manually installing and later uninstalling dependencies at all. .. code:: python @@ -134,4 +169,6 @@ Going forward .. TODO: reproducible developer environments - When using `nix-shell`, packages are downloaded into `/nix/store`, but never removed. - Once enough disk space accumulates, it's time to `Garbage Collect `_. \ No newline at end of file + Once enough disk space accumulates, it's time to `Garbage Collect `_. + +- See ``man nix-shell`` for more options \ No newline at end of file diff --git a/source/tutorials/first-shell.rst b/source/tutorials/first-shell.rst index 7ea65083f41..8075422fc4f 100644 --- a/source/tutorials/first-shell.rst +++ b/source/tutorials/first-shell.rst @@ -1,8 +1,10 @@ -Your first shell -================ +Ad-hoc developer environments +============================= Nix can create reproducible environments given a declarative -configuration called a Nix expression. Reproducible means you can share +configuration called a Nix expression. + +Reproducible means you can share the configuration with others and guarantee that they are using the same software as you. @@ -28,8 +30,10 @@ in: nix-shell -The command will start downloading the missing packages from the cache. -This may take a few moments. When it is done, you are dropped into a new +The command will start downloading the missing packages from the default binary cache. + + +Once it's' done, you are dropped into a new shell. This shell provides the packages specified in ``shell.nix``. Run ``htop`` to confirm it is present. Quit the program again by hitting