diff --git a/source/glossary.rst b/source/glossary.rst new file mode 100644 index 00000000000..a8c120bf324 --- /dev/null +++ b/source/glossary.rst @@ -0,0 +1,10 @@ +Glossary +======== + +.. glossary:: + + attribute name + TODO + + package name + TODO \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index d3f97e62ee5..b2f8e28fde8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -23,3 +23,4 @@ Table of Contents recommended-reading.rst faq.rst influences.rst + glossary.rst diff --git a/source/tutorials/ad-hoc-developer-environments.rst b/source/tutorials/ad-hoc-developer-environments.rst new file mode 100644 index 00000000000..6875792fec0 --- /dev/null +++ b/source/tutorials/ad-hoc-developer-environments.rst @@ -0,0 +1,174 @@ +Ad hoc developer environments +============================= + +Assuming you have :ref:`Nix installed `, it is able to download packages +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. + + +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. + +Sometimes you'd like **to try a tool for a few minutes**. For example, there's a new shiny +tool for writing presentation slides. + +Sometimes you'd like **to give someone a one-liner also with instructions how to install +tools** being used and such that it works between all Linux distributions and on MacOS. + +Sometimes you'd like **to provide a script that is reproducible**, meaning it will also provide the tooling. + + +Searching package attribute names +--------------------------------- + +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 + + $ nix-env -qaP git + gitAndTools.gitFull git-2.25.0 + gitMinimal git-2.25.0 + + +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 shell environments +------------------------- + +Once you have the :term:`attribute name` for packages, you can start a shell: + +.. code:: shell-session + + $ nix-shell -p git vim nano joe + these paths will be fetched (44.16 MiB download, 236.37 MiB unpacked): + ... + /nix/store/fsn35pc8njnimgn2sn26dlsyxya1wssb-vim-8.2.0013 + /nix/store/wdqjszpr5dlys53d79fym6rv9vyyz29h-joe-4.6 + /nix/store/hx63qkip16i4wifaqgxwrrmxj4az53h1-git-2.25.0 + + [nix-shell:~]$ git --version + git version 2.25.0 + + [nix-shell:~]$ which git + /nix/store/hx63qkip16i4wifaqgxwrrmxj4az53h1-git-2.25.0/bin/git + +Press ``CTRL-D`` to exit the shell and those packages won't be available anymore. + + +Beyond tooling: Python libraries +-------------------------------- + +``nix-shell`` provides a bunch of other bash variables from packages specified. + +A quick example using Python and ``$PYTHONPATH``: + +.. code:: shell-session + + $ nix-shell -p 'python38.withPackages (packages: [ packages.django ])' + ... + + [nix-shell:~]$ python -c 'import django; print(django)' + + +We create ad hoc environment with ``$PYTHONPATH`` set and ``python`` available with ``django`` package as well. + +``-p`` argument accepts Nix expression, but going into the Nix language is out of scope of this tutorial. + + +Towards reproducability +----------------------- + +If you handed over these commands to another developer, they might get different results. + +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 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 so we skip the flag. + +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 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 + + #! /usr/bin/env nix-shell + #! nix-shell --pure -i python -p "python38.withPackages (ps: [ ps.django ])" + #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/82b5f87fcc710a99c47c5ffe441589807a8202af.tar.gz + + import django + + print(django) + +This is essentially the same example as in previous section, but this time declaratively source controlled! + + +Going forward +------------- + +.. - Where are these packages coming from? TODO: channels and pinning nixpkgs + +.. 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 `_. + +- 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 diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index f8a705e0de6..d054bc85028 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -5,6 +5,7 @@ Tutorials :glob: install-nix.rst + ad-hoc-developer-environments.rst first-shell.rst dev-environment.rst contributing.rst diff --git a/source/tutorials/install-nix.rst b/source/tutorials/install-nix.rst index 3c982f500f8..3d0513e2f33 100644 --- a/source/tutorials/install-nix.rst +++ b/source/tutorials/install-nix.rst @@ -1,3 +1,5 @@ +.. _install-nix: + Install Nix ===========