Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Integrate nix.dev tutorials as a flake
- Loading branch information
Showing
7 changed files
with
98 additions
and
145 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,6 +10,8 @@ | |
|
|
||
| /nix/manual/ | ||
|
|
||
| /nix-dev/ | ||
|
|
||
| /images/screenshots/nixos-*-small.png | ||
|
|
||
| /build/ | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| #! /usr/bin/env bash | ||
|
|
||
| set -e | ||
|
|
||
| inDir="$1" | ||
| outDir="$2" | ||
| title="$3" | ||
| menu="$4" | ||
| source="$5" | ||
|
|
||
| outDirTmp="${outDir}.tmp" | ||
| rm -rf "$outDirTmp" | ||
| mkdir -p "$outDirTmp" | ||
|
|
||
| [[ -d $inDir ]] | ||
|
|
||
| (cd $inDir && find -type f -print) | while read fn; do | ||
| echo "$fn" | ||
| if [[ $fn =~ epub ]]; then | ||
| true | ||
| elif [[ "$fn" =~ .html$ ]]; then | ||
| mkdir -p $(dirname $outDirTmp/$fn) | ||
| xmlstarlet fo -H -R "$inDir/$fn" \ | ||
| | xmlstarlet ed -d "//a[@class='headerlink']" \ | ||
| | xmlstarlet sel -t -c "//div[@class='section']" \ | ||
| > "$outDirTmp/$fn.in" | ||
| root=$(realpath --relative-to="$(pwd)" "$outDirTmp/$fn" | sed -e 's|[^/]||g' -e 's|/|../|g') | ||
| else | ||
| mkdir -p "$(dirname "$outDirTmp/$fn")" | ||
| cp -f "$inDir/$fn" "$outDirTmp/$fn" | ||
| fi | ||
| done | ||
|
|
||
| rm -rf "$outDir" # FIXME: not atomic | ||
| mv "$outDirTmp" "$outDir" |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,130 +1,5 @@ | ||
| [% WRAPPER layout.tt title="Ad hoc developer environments" %] | ||
|
|
||
| <h1>Ad hoc developer environments</h1> | ||
|
|
||
| <p>Assuming you have <a href="[%root%]guides/install-nix.html">Nix installed</a>, it is able to download packages and provide a new <strong>shell environment</strong> with packages available.</p> | ||
|
|
||
| <p>This is a great way to play with Nix tooling and see some of its potential.</p> | ||
|
|
||
| <h2>What is a shell environment?</h2> | ||
|
|
||
| <p>A hello world example:</p> | ||
| <pre>$ 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. | ||
| </pre> | ||
|
|
||
| <h2>When are shell environments useful?</h2> | ||
|
|
||
| <p>Sometimes you’d like <strong>to use a tool, but it’s not installed yet</strong>. You don’t want to bother installing software, you only want to have it now.</p> | ||
|
|
||
| <p>Sometimes you’d like <strong>to try a tool for a few minutes</strong>. For example, there’s a new shiny tool for writing presentation slides.</p> | ||
|
|
||
| <p>Sometimes you’d like <strong>to give someone a one-liner also with instructions how to install tools</strong> being used and such that it works between all Linux distributions and on MacOS.</p> | ||
|
|
||
| <p>Sometimes you’d like <strong>to provide a script that is reproducible</strong>, meaning it will also provide the tooling.</p> | ||
|
|
||
| <h2>Searching package attribute names</h2> | ||
|
|
||
| <p>What can you put in a shell environment?”</p> | ||
|
|
||
| <p>To start, anything that’s in the <a href="https://nixos.org/nixos/packages.html">official package list</a> can become part of the shell environment.</p> | ||
|
|
||
| <p>You can search the package list using:</p> | ||
|
|
||
| <pre>$ nix-env -qaP git | ||
| gitAndTools.gitFull git-2.25.0 | ||
| gitMinimal git-2.25.0 | ||
| </pre> | ||
|
|
||
| <p>The first column is the <em>attribute name</em> and the second is <em>package name</em> and its version.</p> | ||
|
|
||
| <p>Once you are comfortable doing this, you can add other things too. For example, packages of your own or custom shell aliases.</p> | ||
|
|
||
| <p><strong>Note:</strong> Query for searching packages is a regex, so be aware when it comes to special characters.</p> | ||
|
|
||
| <h2>Ad hoc shell environments</h2> | ||
|
|
||
| <p>Once you have the attribute name for packages, you can start a shell:</p> | ||
|
|
||
| <pre>$ 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 | ||
| </pre> | ||
|
|
||
| <p>Press <code>CTRL-D</code> to exit the shell and those packages won’t be available anymore.</p> | ||
|
|
||
| <h2>Beyond tooling: Python libraries</h2> | ||
|
|
||
| <p><code>nix-shell</code> provides a bunch of other bash variables from packages specified.</p> | ||
|
|
||
| <p>A quick example using Python and <code>$PYTHONPATH</code>:</p> | ||
|
|
||
| <pre>$ nix-shell -p 'python38.withPackages (packages: [ packages.django ])' | ||
| ... | ||
|
|
||
| [nix-shell:~]$ python -c 'import django; print(django)' | ||
| <module 'django' from '/nix/store/c8ipxqsgh8xd6zmwb026lldsgr7hi315-python3-3.8.1-env/lib/python3.8/site-packages/django/__init__.py'> | ||
| </pre> | ||
|
|
||
| <p>We create ad hoc environment with <code>$PYTHONPATH</code> set and <code>python</code> available with <code>django</code> package as well.</p> | ||
|
|
||
| <p><code>-p</code> argument accepts Nix expression, but going into the Nix language is out of scope of this tutorial.</p> | ||
|
|
||
| <h2>Towards reproducibility</h2> | ||
|
|
||
| <p>If you handed over these commands to another developer, they might get different results.</p> | ||
|
|
||
| <p>These shell environments are <strong>really convenient</strong>, but they are <strong>not yet reproducible</strong>.</p> | ||
|
|
||
| <p>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.</p> | ||
|
|
||
| <p>The following is entirely reproducible and something you can share between colleagues:</p> | ||
|
|
||
| <pre>$ 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 | ||
| </pre> | ||
|
|
||
| <p>There are two things going on here:</p> | ||
|
|
||
| <ol> | ||
| <li><p><code>--pure</code> flag makes sure that bash environnment from your system is not inherited. That means the only <code>git</code> 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.</p></li> | ||
| <li><p><code>-I</code> pins nixpkgs revision to an exact git revision, leaving no doubt which version of Nix packages will be used.</p></li> | ||
| </ol> | ||
|
|
||
| <h2>Reproducible executables</h2> | ||
|
|
||
| <p>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.</p> | ||
| <pre>#! /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) | ||
| </pre> | ||
|
|
||
| <p>This is essentially the same example as in previous section, but this time declaratively source controlled!</p> | ||
| [% INSERT "nix-dev/ad-hoc-developer-environments.html.in" %] | ||
|
|
||
| [% END %] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,5 @@ | ||
| [% WRAPPER layout.tt title="Install Nix" %] | ||
|
|
||
| <h1>Install Nix</h1> | ||
|
|
||
| <p>Install Nix on <strong>any Linux distribution</strong>, <strong>MacOS</strong> and <strong>Windows (via WSL)</strong> via the recommended <a class="reference external" href="https://nixos.org/nix/manual/#chap-installation">multi-user installation</a>:</p> | ||
|
|
||
| <pre>sh <(curl -L https://nixos.org/nix/install) --daemon | ||
| </pre> | ||
|
|
||
| <p><strong>Note:</strong> For security you may want to <a href="https://nixos.org/download.html#nix-verify-installation">verify installation script</a> using GPG signatures.</p> | ||
|
|
||
| <h2>Verify installation</h2> | ||
|
|
||
| <p>Check that the installation was successful:</p> | ||
|
|
||
| <pre>$ nix-env --version | ||
| nix-env (Nix) 2.3.4 | ||
| </pre> | ||
| [% INSERT "nix-dev/install-nix.html.in" %] | ||
|
|
||
| [% END %] |