mirror/nix-book
1
0
Fork 0
mirror of https://codeberg.org/mhwombat/nix-book.git synced 2025-12-26 16:24:56 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

restructured repo

Browse source
This commit is contained in:
Amy de Buitléir 2023-06-13 20:33:24 +01:00
parent bea4055fc9
commit 285f60104b
22 changed files with 167 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

217
index.html
View file

@ -110,8 +110,9 @@ pre.pygments .tok-il { color: #FF6600 } /* Literal.Number.Integer.Long */
<li><a href="#_the_hello_flake_repo">3. The hello-flake repo</a></li>
<li><a href="#_flake_structure">4. Flake structure</a>
<ul class="sectlevel2">
<li><a href="#_inputs">4.1. Inputs</a></li>
<li><a href="#_outputs">4.2. Outputs</a></li>
<li><a href="#_description">4.1. Description</a></li>
<li><a href="#_inputs">4.2. Inputs</a></li>
<li><a href="#_outputs">4.3. Outputs</a></li>
</ul>
</li>
<li><a href="#_a_generic_flake">5. A generic flake</a></li>
@ -124,22 +125,27 @@ pre.pygments .tok-il { color: #FF6600 } /* Literal.Number.Integer.Long */
<li><a href="#_this_all_seems_like_a_hassle">7.4. This all seems like a hassle!</a></li>
</ul>
</li>
<li><a href="#_a_new_flake_from_scratch_python">8. A new flake from scratch (Python)</a></li>
<li><a href="#_a_new_flake_from_scratch_python">8. A new flake from scratch (Python)</a>
<ul class="sectlevel2">
<li><a href="#_a_simple_python_program">8.1. A simple Python program</a></li>
<li><a href="#_a_python_builder">8.2. A Python builder</a></li>
<li><a href="#_the_nix_flake">8.3. The Nix flake</a></li>
</ul>
</li>
<li><a href="#_nix_shell_recipes">9. Nix shell recipes</a>
<ul class="sectlevel2">
<li><a href="#_shell_with_access_to_a_package_from_the_nixpkgsnixos_repo">9.1. Shell with access to a package from the Nixpkgs/NixOS repo</a></li>
<li><a href="#_shell_with_access_to_a_package_defined_in_a_remote_git_repo">9.2. Shell with access to a package defined in a remote git repo</a></li>
<li><a href="#_shell_with_access_to_a_flake">9.3. Shell with access to a flake</a></li>
<li><a href="#_shell_with_access_to_a_specific_revision_of_a_flake">9.4. Shell with access to a specific revision of a flake</a></li>
<li><a href="#_shell_with_access_to_a_haskell_package_on_your_local_computer">9.5. Shell with access to a Haskell package on your local computer</a></li>
<li><a href="#_shell_with_access_to_a_haskell_package_on_your_local_computer_with_interdependencies">9.6. Shell with access to a Haskell package on your local computer, with interdependencies</a></li>
<li><a href="#_shell_with_an_environment_variable_set">9.7. Shell with an environment variable set</a></li>
<li><a href="#_shell_with_access_to_a_specific_revision_of_a_flake">9.3. Shell with access to a specific revision of a flake</a></li>
<li><a href="#_shell_with_access_to_a_haskell_package_on_your_local_computer">9.4. Shell with access to a Haskell package on your local computer</a></li>
<li><a href="#_shell_with_access_to_a_haskell_package_on_your_local_computer_with_interdependencies">9.5. Shell with access to a Haskell package on your local computer, with interdependencies</a></li>
<li><a href="#_shell_with_an_environment_variable_set">9.6. Shell with an environment variable set</a></li>
</ul>
</li>
<li><a href="#_nix_shell_shebangs">10. Nix-shell shebangs</a>
<ul class="sectlevel2">
<li><a href="#_a_bash_script_depending_on_a_package_in_the_nixpkgs_repo">10.1. A Bash script depending on a package in the nixpkgs repo.</a></li>
<li><a href="#_a_python_script_depending_on_a_package_in_the_nixpkgs_repo">10.2. A Python script depending on a package in the nixpkgs repo.</a></li>
<li><a href="#_a_bash_script_depending_on_a_package_in_the_nixpkgs_repo_2">10.2. A Bash script depending on a package in the nixpkgs repo.</a></li>
</ul>
</li>
</ul>
@ -467,12 +473,12 @@ Nix<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footno
uses. We’ll look at this in more detail shortly. For now, I’d like to
focus on the inputs section.</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">inputs = {
nixpkgs.url = "github:NixOS/nixpkgs";
flake-utils.url = "github:numtide/flake-utils";
};</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix"><span></span><span class="tok-ss">inputs =</span> <span class="tok-p">{</span>
nixpkgs<span class="tok-o">.</span><span class="tok-ss">url =</span> <span class="tok-s2">&quot;github:NixOS/nixpkgs&quot;</span><span class="tok-p">;</span>
flake-utils<span class="tok-o">.</span><span class="tok-ss">url =</span> <span class="tok-s2">&quot;github:numtide/flake-utils&quot;</span><span class="tok-p">;</span>
<span class="tok-p">};</span></code></pre>
</div>
</div>
<div class="paragraph">
@ -528,7 +534,8 @@ flakes. The important thing to note is that the <code>hello-flake</code> package
&quot;inputs&quot;: {
&quot;flake-utils&quot;: &quot;flake-utils&quot;,
&quot;nixpkgs&quot;: &quot;nixpkgs&quot;
}</code></pre>
}
. . .</code></pre>
</div>
</div>
<div class="paragraph">
@ -553,24 +560,27 @@ benefit of using flakes.</p>
<div class="paragraph">
<p>The basic structure of a flake is shown below.</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">{
description = ... # package description
inputs = ... # dependencies
outputs = ... # what the flake producesgo
nixConfig = ... # advanced configuration options
}</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix">{
description = <em>package description</em>
inputs = <em>dependencies</em>
outputs = <em>what the flake produces</em>
nixConfig = <em>advanced configuration options</em>
}</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="_description">4.1. Description</h3>
<div class="paragraph">
<p>The <code>description</code> part is self-explanatory; it’s just a string. You
probably won’t need <code>nixConfig</code> unless you’re doing something fancy. I’m
going to focus on what goes into the <code>inputs</code> and <code>outputs</code> sections,
and highlight some of the things I found confusing when I began using flakes.</p>
</div>
</div>
<div class="sect2">
<h3 id="_inputs">4.1. Inputs</h3>
<h3 id="_inputs">4.2. Inputs</h3>
<div class="paragraph">
<p>This section specifies the dependencies of a flake. It’s an <em>attribute
set</em>; it maps keys to values.</p>
@ -595,28 +605,28 @@ This commonly takes the following form.</p>
which is a large Git repository of programs and libraries that are
pre-packaged for Nix. We can write that as</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix">nixpkgs.url = "github:NixOS/nixpkgs/nixos-<em>version</em>";</code></pre>
</div>
</div>
<div class="paragraph">
<p>where <code>NN.MM</code> is replaced with the version number that you used to build
<p>where <em>version</em> is replaced with the version number that you used to build
the package, e.g. <code>22.11</code>. Information about the latest nixpkgs releases
is available at <a href="https://status.nixos.org/" class="bare">https://status.nixos.org/</a>. You can also write the entry
without the version number</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix"><span></span>nixpkgs<span class="tok-o">.</span><span class="tok-ss">url =</span> <span class="tok-s2">&quot;github:NixOS/nixpkgs/nixos&quot;</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>or more simply,</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">nixpkgs.url = "nixpkgs";</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix"><span></span>nixpkgs<span class="tok-o">.</span><span class="tok-ss">url =</span> <span class="tok-s2">&quot;nixpkgs&quot;</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
@ -666,21 +676,21 @@ Reference Manual</a>.</p>
<p>Although you probably won’t need to use it, there is another syntax for
flake references that you might encounter. This example</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">inputs.import-cargo = {
type = "github";
owner = "edolstra";
repo = "import-cargo";
};</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix"><span></span>inputs<span class="tok-o">.</span><span class="tok-nb">import</span><span class="tok-ss">-cargo =</span> <span class="tok-p">{</span>
<span class="tok-ss">type =</span> <span class="tok-s2">&quot;github&quot;</span><span class="tok-p">;</span>
<span class="tok-ss">owner =</span> <span class="tok-s2">&quot;edolstra&quot;</span><span class="tok-p">;</span>
<span class="tok-ss">repo =</span> <span class="tok-s2">&quot;import-cargo&quot;</span><span class="tok-p">;</span>
<span class="tok-p">};</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>is equivalent to</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">inputs.import-cargo.url = "github:edolstra/import-cargo";</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix"><span></span>inputs<span class="tok-o">.</span><span class="tok-nb">import</span><span class="tok-err">-</span>cargo<span class="tok-o">.</span><span class="tok-ss">url =</span> <span class="tok-s2">&quot;github:edolstra/import-cargo&quot;</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</td>
@ -694,7 +704,7 @@ input.</p>
</div>
</div>
<div class="sect2">
<h3 id="_outputs">4.2. Outputs</h3>
<h3 id="_outputs">4.3. Outputs</h3>
<div class="paragraph">
<p>This section is a function that essentially returns the recipe for
building the flake.</p>
@ -704,11 +714,11 @@ building the flake.</p>
list them as parameters. This example references the <code>import-cargo</code>
dependency defined in the previous example.</p>
</div>
<div class="literalblock">
<div class="listingblock">
<div class="content">
<pre class="nowrap">outputs = { self, nixpkgs, import-cargo }: {
<mark>... outputs ...</mark>
};</pre>
<pre class="pygments highlight nowrap"><code data-lang="nix">outputs = { self, nixpkgs, import-cargo }: {
<mark><em>definitions for outputs</em></mark>
};</code></pre>
</div>
</div>
<div class="paragraph">
@ -737,7 +747,7 @@ writing your own flakes. I’ll explain the example in some detail.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="nowrap">{
<pre class="pygments highlight nowrap"><code>{
description = "<mark><em>brief package description</em></mark>";
inputs = {
@ -770,7 +780,7 @@ writing your own flakes. I’ll explain the example in some detail.</p>
};
}
);
}</pre>
}</code></pre>
</div>
</div>
<div class="paragraph">
@ -852,6 +862,7 @@ If you compare this flake definition to the colour-coded template
presented in the previous section, most of it should look familiar.</p>
</div>
<div class="literalblock">
<div class="title">flake.nix</div>
<div class="content">
<pre class="nowrap">{
description = "a very simple and friendly flake";
@ -1167,7 +1178,14 @@ cowsay <span class="tok-s2">&quot;Hello from your flake!&quot;</span></code></pr
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ ./hello-flake
./hello-flake: line 3: cowsay: command not found</pre>
________________________
&lt; Hello from your flake! &gt;
------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||</pre>
</div>
</div>
<div class="paragraph">
@ -1312,7 +1330,7 @@ don’t need to <code>git push</code> the changes until we’re ready to share t
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ git commit hello-flake flake.nix -m 'added bovine feature'
[main 8c8f6c7] added bovine feature
[main 746a121] added bovine feature
2 files changed, 7 insertions(+), 1 deletion(-)
$ nix run
________________________
@ -1417,6 +1435,8 @@ $ git init
Initialized empty Git repository in /home/amy/codeberg/nix-book/source/python-flake/hello-python/.git/</pre>
</div>
</div>
<div class="sect2">
<h3 id="_a_simple_python_program">8.1. A simple Python program</h3>
<div class="paragraph">
<p>Next, we’ll create a simple Python program.</p>
</div>
@ -1490,6 +1510,9 @@ $ python hello.py
Hello from inside a Python program built with a Nix flake!</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_a_python_builder">8.2. A Python builder</h3>
<div class="paragraph">
<p>Next, create a Python script to build the package. We’ll use Python’s
setuptools, but you can use other build tools. For more information on
@ -1565,6 +1588,9 @@ twice. Alternatively, we could have done <code>exit</code> followed by the
<div class="paragraph">
<p>After a lot of output messages, the build succeeds.</p>
</div>
</div>
<div class="sect2">
<h3 id="_the_nix_flake">8.3. The Nix flake</h3>
<div class="paragraph">
<p>Now we should write <code>flake.nix</code>. We already know how to write most of
the flake from the examples we did earlier. The two parts that will be
@ -1760,7 +1786,7 @@ repo, and commit all important files.</p>
<div class="content">
<pre class="nowrap">$ git add flake.lock
$ git commit -a -m 'initial commit'
[master (root-commit) a98ed14] initial commit
[master (root-commit) b139782] initial commit
4 files changed, 127 insertions(+)
create mode 100644 flake.lock
create mode 100644 flake.nix
@ -1795,6 +1821,7 @@ Python flake.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_nix_shell_recipes">9. Nix shell recipes</h2>
<div class="sectionbody">
@ -1805,6 +1832,7 @@ Python flake.</p>
cowsay.</p>
</div>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
@ -1828,12 +1856,9 @@ mkShell <span class="tok-p">{</span>
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ nix-shell
error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
$ hello
bash: line 19: hello: command not found
Hello, world!
$ cowsay "moo"
bash: line 22: cowsay: command not found
_____
&lt; moo &gt;
-----
@ -1851,6 +1876,7 @@ bash: line 22: cowsay: command not found
<div class="sect2">
<h3 id="_shell_with_access_to_a_package_defined_in_a_remote_git_repo">9.2. Shell with access to a package defined in a remote git repo</h3>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
@ -1880,57 +1906,15 @@ mkShell <span class="tok-p">{</span>
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ nix-shell
error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
$ hello-nix
bash: line 48: hello-nix: command not found
Hello from your nix package!</pre>
$ hello
Hello, world!</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_shell_with_access_to_a_flake">9.3. Shell with access to a flake</h3>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span></pre></div></td><td class="code"><pre><span></span><span class="tok-k">with</span> <span class="tok-p">(</span><span class="tok-nb">import</span> <span class="tok-l">&lt;nixpkgs&gt;</span> <span class="tok-p">{});</span>
<span class="tok-k">let</span>
<span class="tok-ss">hello =</span> <span class="tok-p">(</span><span class="tok-nb">builtins</span><span class="tok-o">.</span>getFlake <span class="tok-l">git+https://codeberg.org/mhwombat/hello-flake</span><span class="tok-p">)</span><span class="tok-o">.</span>packages<span class="tok-o">.</span><span class="tok-err">$</span><span class="tok-p">{</span><span class="tok-nb">builtins</span><span class="tok-o">.</span>currentSystem<span class="tok-p">}</span><span class="tok-o">.</span>default<span class="tok-p">;</span>
<span class="tok-c1"># For older flakes, you might need an expression like this...</span>
<span class="tok-c1"># hello = (builtins.getFlake git+https://codeberg.org/mhwombat/hello-flake).defaultPackage.${builtins.currentSystem};</span>
<span class="tok-k">in</span>
mkShell <span class="tok-p">{</span>
<span class="tok-ss">buildInputs =</span> <span class="tok-p">[</span>
hello
<span class="tok-p">];</span>
<span class="tok-p">}</span>
</pre></td></tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here’s a demonstration using the shell.</p>
</div>
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ nix-shell
error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
$ hello-flake
bash: line 65: hello-flake: command not found
Hello from your flake!</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_shell_with_access_to_a_specific_revision_of_a_flake">9.4. Shell with access to a specific revision of a flake</h3>
<h3 id="_shell_with_access_to_a_specific_revision_of_a_flake">9.3. Shell with access to a specific revision of a flake</h3>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
@ -1958,20 +1942,19 @@ mkShell <span class="tok-p">{</span>
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ nix-shell
error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
$ hello-flake
bash: line 82: hello-flake: command not found
Hello from your flake!</pre>
$ hello
Hello, world!</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_shell_with_access_to_a_haskell_package_on_your_local_computer">9.5. Shell with access to a Haskell package on your local computer</h3>
<h3 id="_shell_with_access_to_a_haskell_package_on_your_local_computer">9.4. Shell with access to a Haskell package on your local computer</h3>
<div class="paragraph">
<p>This shell provides access to three Haskell packages that are on my hard
drive.</p>
</div>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
@ -2005,12 +1988,13 @@ mkShell <span class="tok-p">{</span>
</div>
</div>
<div class="sect2">
<h3 id="_shell_with_access_to_a_haskell_package_on_your_local_computer_with_interdependencies">9.6. Shell with access to a Haskell package on your local computer, with interdependencies</h3>
<h3 id="_shell_with_access_to_a_haskell_package_on_your_local_computer_with_interdependencies">9.5. Shell with access to a Haskell package on your local computer, with interdependencies</h3>
<div class="paragraph">
<p>This shell provides access to four Haskell packages that are on my hard
drive. The fourth package depends on the first three to build.</p>
</div>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
@ -2054,11 +2038,12 @@ mkShell <span class="tok-p">{</span>
</div>
</div>
<div class="sect2">
<h3 id="_shell_with_an_environment_variable_set">9.7. Shell with an environment variable set</h3>
<h3 id="_shell_with_an_environment_variable_set">9.6. Shell with an environment variable set</h3>
<div class="paragraph">
<p>This shell has the environment variable FOO set to &#8220;bar&#8221;</p>
</div>
<div class="listingblock">
<div class="title">shell.nix</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="nix"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
@ -2080,10 +2065,8 @@ mkShell <span class="tok-p">{</span>
<div class="literalblock">
<div class="content">
<pre class="nowrap">$ nix-shell
error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
$ echo $FOO
bar</pre>
$ echo "FOO=$FOO"
FOO=bar</pre>
</div>
</div>
</div>
@ -2105,10 +2088,8 @@ interpreter and any dependencies. Here are some examples.</p>
</div>
<div class="sect2">
<h3 id="_a_bash_script_depending_on_a_package_in_the_nixpkgs_repo">10.1. A Bash script depending on a package in the nixpkgs repo.</h3>
<div class="paragraph">
<p>Script:</p>
</div>
<div class="listingblock">
<div class="title">Script</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="bash"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
@ -2118,10 +2099,8 @@ cowsay <span class="tok-s2">&quot;Pretty cool, huh?&quot;</span>
</pre></td></tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Output:</p>
</div>
<div class="literalblock">
<div class="title">Output</div>
<div class="content">
<pre class="nowrap"> ___________________
&lt; Pretty cool, huh? &gt;
@ -2135,11 +2114,9 @@ cowsay <span class="tok-s2">&quot;Pretty cool, huh?&quot;</span>
</div>
</div>
<div class="sect2">
<h3 id="_a_python_script_depending_on_a_package_in_the_nixpkgs_repo">10.2. A Python script depending on a package in the nixpkgs repo.</h3>
<div class="paragraph">
<p>Script:</p>
</div>
<h3 id="_a_bash_script_depending_on_a_package_in_the_nixpkgs_repo_2">10.2. A Bash script depending on a package in the nixpkgs repo.</h3>
<div class="listingblock">
<div class="title">Script</div>
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="bash"><table class="linenotable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
@ -2165,10 +2142,8 @@ print<span class="tok-o">(</span><span class="tok-s1">&#39;sanitized: &#39;</spa
</pre></td></tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Output:</p>
</div>
<div class="literalblock">
<div class="title">Output</div>
<div class="content">
<pre class="nowrap">original: &lt;span style="font-weight:bold"&gt;some text&lt;/span&gt;
sanitized: &lt;strong&gt;some text&lt;/strong&gt;</pre>

20
source/book.adoc
View file

@ -8,22 +8,22 @@
:!prewrap:
:icons: font
include::intro/main.adoc[]
include::intro/main.adoc[leveloffset=+1]
include::hello-flake/main-generated.adoc[]
include::hello-flake/main-generated.adoc[leveloffset=+1]
include::hello-flake-repo/main-generated.adoc[]
include::hello-flake-repo/main-generated.adoc[leveloffset=+1]
include::flake-structure/main.adoc[]
include::flake-structure/main.adoc[leveloffset=+1]
include::generic-flake/main.adoc[]
include::generic-flake/main.adoc[leveloffset=+1]
include::hello-flake-return/main.adoc[]
include::hello-flake-return/main.adoc[leveloffset=+1]
include::modify-hello-flake/main-generated.adoc[]
include::modify-hello-flake/main-generated.adoc[leveloffset=+1]
include::python-flake/main-generated.adoc[]
include::python-flake/main-generated.adoc[leveloffset=+1]
include::shell-recipes/main-generated.adoc[]
include::shell-recipes/main.adoc[leveloffset=+1]
include::shebangs/main-generated.adoc[]
include::shebangs/main.adoc[leveloffset=+1]

32
source/flake-structure/main.adoc
View file

@ -1,22 +1,25 @@
== Flake structure
= Flake structure
The basic structure of a flake is shown below.
[source,nix,subs=quotes]
....
{
description = ... # package description
inputs = ... # dependencies
outputs = ... # what the flake producesgo
nixConfig = ... # advanced configuration options
description = _package description_
inputs = _dependencies_
outputs = _what the flake produces_
nixConfig = _advanced configuration options_
}
....
== Description
The `description` part is self-explanatory; it’s just a string. You
probably won’t need `nixConfig` unless you’re doing something fancy. I’m
going to focus on what goes into the `inputs` and `outputs` sections,
and highlight some of the things I found confusing when I began using flakes.
=== Inputs
== Inputs
This section specifies the dependencies of a flake. It’s an _attribute
set_; it maps keys to values.
@ -37,21 +40,24 @@ As a first example of a flake reference, all (almost all?) flakes depend on "`ni
which is a large Git repository of programs and libraries that are
pre-packaged for Nix. We can write that as
[source,nix,subs=quotes]
....
nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
nixpkgs.url = "github:NixOS/nixpkgs/nixos-__version__";
....
where `NN.MM` is replaced with the version number that you used to build
where _version_ is replaced with the version number that you used to build
the package, e.g. `22.11`. Information about the latest nixpkgs releases
is available at https://status.nixos.org/. You can also write the entry
without the version number
[source,nix]
....
nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
nixpkgs.url = "github:NixOS/nixpkgs/nixos";
....
or more simply,
[source,nix]
....
nixpkgs.url = "nixpkgs";
....
@ -83,6 +89,7 @@ Reference Manual].
Although you probably won’t need to use it, there is another syntax for
flake references that you might encounter. This example
[source,nix]
....
inputs.import-cargo = {
type = "github";
@ -93,6 +100,7 @@ inputs.import-cargo = {
is equivalent to
[source,nix]
....
inputs.import-cargo.url = "github:edolstra/import-cargo";
....
@ -102,7 +110,7 @@ Each of the `inputs` is fetched, evaluated and passed to the `outputs`
function as a set of attributes with the same name as the corresponding
input.
=== Outputs
== Outputs
This section is a function that essentially returns the recipe for
building the flake.
@ -111,10 +119,10 @@ We said above that `inputs` are passed to the `outputs`, so we need to
list them as parameters. This example references the `import-cargo`
dependency defined in the previous example.
[subs=quotes]
[source,nix,subs=quotes]
....
outputs = { self, nixpkgs, import-cargo }: {
#... outputs ...#
#_definitions for outputs_#
};
....

4
source/generic-flake/main.adoc
View file

@ -1,4 +1,4 @@
== A generic flake
= A generic flake
The previous section presented a very high-level view of flakes,
focusing on the basic structure. In this section, we will add a bit more
@ -9,7 +9,7 @@ functional language. As with most programming languages, there are many
ways to achieve the same result. Below is an example you can follow when
writing your own flakes. I’ll explain the example in some detail.
[subs=quotes]
[source,subs=quotes]
----
{
description = "#_brief package description_#";

4
source/hello-flake-repo/main.adoc0
View file

@ -1,4 +1,4 @@
== The hello-flake repo
= The hello-flake repo
Let’s clone the repository and see how the flake is defined.
@ -50,6 +50,7 @@ https://nixos.org/guides/nix-language.html[Nix language basics].]. Yes,
uses. We’ll look at this in more detail shortly. For now, I’d like to
focus on the inputs section.
[source,nix]
....
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs";
@ -70,6 +71,7 @@ Finally, let’s look at `flake.lock`, or rather, just part of it.
.flake.lock
....
$# head -n 40 flake.lock
. . .
....
If `flake.nix` seemed intimidating, then this file looks like an

4
source/hello-flake-return/main.adoc
View file

@ -1,4 +1,4 @@
== Another look at hello-flake
= Another look at hello-flake
Now that we have a better understanding of the structure of `flake.nix`,
let’s have a look at the one we saw earlier, in the `hello-flake` repo.
@ -6,6 +6,7 @@ If you compare this flake definition to the colour-coded template
presented in the previous section, most of it should look familiar.
[subs=quotes]
.flake.nix
....
{
description = "a very simple and friendly flake";
@ -47,6 +48,7 @@ additional development tools.
Now let’s look at the section I labeled `SOME UNFAMILIAR STUFF` and
see what it does.
[subs=quotes]
....
packages = rec {
hello = pkgs.stdenv.mkDerivation rec { ❶

2
source/hello-flake/main.adoc0
View file

@ -1,4 +1,4 @@
== Hello, flake!
= Hello, flake!
Before learning to write Nix flakes, let’s learn how to use them. I’ve
created a simple example of a flake in this git

8
source/intro/main.adoc
View file

@ -1,6 +1,6 @@
== Introduction
= Introduction
=== Why Nix?
== Why Nix?
If you’ve opened this PDF, you already have your own motivation for
learning Nix. Here’s how it helps me. As a researcher, I tend to work on
@ -28,7 +28,7 @@ any dependencies. It automatically tracks the version of each dependency
so that it can replicate the environment wherever and whenever it’s
needed.
=== Why _flakes_?
== Why _flakes_?
Flakes are labeled as an experimental feature, so it might seem safer to
avoid them. However, they have been in use for years, and there is
@ -37,7 +37,7 @@ easier to understand, and offer more features than the traditional Nix
approach. After weighing the pros and cons, I feel it’s better to learn
and use flakes; and this seems to be the general consensus.
=== Prerequisites
== Prerequisites
To follow along with the examples in this book, you will need access to a computer
or (virtual machine) with Nix installed and _flakes enabled_.

10
source/modify-hello-flake/main.adoc0
View file

@ -1,6 +1,6 @@
== Modifying the flake
= Modifying the flake
=== The Nix development shell
== The Nix development shell
Let’s make a simple modification to the script. This will give you an
opportunity to check your understanding of flakes.
@ -79,7 +79,7 @@ first if needed. Specifically, it runs the version in the Nix store, not
the version in `result`.
|===
=== Introducing a dependency
== Introducing a dependency
Now we’re ready to make the flake a little more interesting.
Instead of using the `echo` command in the script, we can use the Linux `cowsay`
@ -165,7 +165,7 @@ $ git commit hello-flake flake.nix -m 'added bovine feature'
$ nix run
....
=== Development workflows
== Development workflows
If you’re getting confused about when to use the different commands,
it’s because there’s more than one way to use Nix. I tend to think of it
@ -203,7 +203,7 @@ executable depends on the development tools – It probably isn’t
I generally only use `nix build` if I just want to build the package but
not execute anything (perhaps it’s just a library).
=== This all seems like a hassle!
== This all seems like a hassle!
It is a bit annoying to modify `flake.nix` and ether rebuild or reload
the development environment every time you need another tool. However,

8
source/python-flake/main.adoc0
View file

@ -1,4 +1,4 @@
== A new flake from scratch (Python)
= A new flake from scratch (Python)
At last we are ready to create a flake from scratch! Start with an empty
directory and create a git repository.
@ -9,6 +9,8 @@ $ cd hello-python
$ git init
....
== A simple Python program
Next, we’ll create a simple Python program.
////
@ -57,6 +59,8 @@ $# nix-shell -p python3 --command sh
$ python hello.py
....
== A Python builder
Next, create a Python script to build the package. We’ll use Python’s
setuptools, but you can use other build tools. For more information on
setuptools, see the
@ -106,6 +110,8 @@ $# python -m build > /dev/null 2>&1
After a lot of output messages, the build succeeds.
== The Nix flake
Now we should write `flake.nix`. We already know how to write most of
the flake from the examples we did earlier. The two parts that will be
different are the development shell and the package builder.

3
source/shebangs/bash-with-nixpkg.sh
View file

@ -1,3 +0,0 @@
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p cowsay
cowsay "Pretty cool, huh?"

32
source/shebangs/main.adoc0 → source/shebangs/main.adoc
View file

@ -1,4 +1,4 @@
== Nix-shell shebangs
= Nix-shell shebangs
You can use `nix-shell` to run scripts in arbitrary languages, providing
the necessary dependencies. This is particularly convenient for
@ -9,32 +9,6 @@ The script should start with two "`shebang`" (`#!`) commands. The first
should invoke `nix-shell`. The second should declares the scrpt
interpreter and any dependencies. Here are some examples.
=== A Bash script depending on a package in the nixpkgs repo.
include::bash-with-nix-pkg/main-generated.adoc[leveloffset=+1]
Script:
[source,bash,linenums]
....
include::bash-with-nixpkg.sh[]
....
Output:
....
$# ./bash-with-nixpkg.sh
....
=== A Python script depending on a package in the nixpkgs repo.
Script:
[source,bash,linenums]
....
include::python-with-nixpkg.sh[]
....
Output:
....
$# ./python-with-nixpkg.sh
....
include::python-with-nix-pkg/main-generated.adoc[leveloffset=+1]

11
source/shebangs/python-with-nixpkg.sh
View file

@ -1,11 +0,0 @@
#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python3Packages.html-sanitizer
from html_sanitizer import Sanitizer
sanitizer = Sanitizer() # default configuration
original='<span style="font-weight:bold">some text</span>'
print('original: ', original)
sanitized=sanitizer.sanitize(original)
print('sanitized: ', sanitized)

13
source/shell-recipes/main.adoc Normal file
View file

@ -0,0 +1,13 @@
= Nix shell recipes
include::shell-with-nixpkgs/main-generated.adoc[leveloffset=+1]
include::shell-with-git-nix-pkg/main-generated.adoc[leveloffset=+1]
include::shell-with-flake-rev/main-generated.adoc[leveloffset=+1]
include::shell-haskell-local/main-generated.adoc[leveloffset=+1]
include::shell-haskell-local-deps/main-generated.adoc[leveloffset=+1]
include::shell-with-env-var/main-generated.adoc[leveloffset=+1]

112
source/shell-recipes/main.adoc0
View file

@ -1,112 +0,0 @@
== Nix shell recipes
=== Shell with access to a package from the Nixpkgs/NixOS repo
This shell provides access to two packages from nixpkgs: hello and
cowsay.
[source,nix,linenums]
....
include::0100-shell-with-nixpkgs.nix[]
....
Here’s a demonstration using the shell.
....
$ nix-shell
$ hello
Hello, world!
$ cowsay "moo"
_____
< moo >
-----
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
....
The command-line equivalent would be `nix-shell -p hello cowsay`
=== Shell with access to a package defined in a remote git repo
[source,nix,linenums]
....
include::0150-shell-with-git-nix-pkg.nix[]
....
Here’s a demonstration using the shell.
....
$ nix-shell
$ hello-nix
Hello from your nix package!
....
=== Shell with access to a flake
[source,nix,linenums]
....
include::0200-shell-with-flake.nix[]
....
Here’s a demonstration using the shell.
....
$ nix-shell
$ hello-flake
Hello from your flake!
....
=== Shell with access to a specific revision of a flake
[source,nix,linenums]
....
include::0250-shell-with-flake-rev.nix[]
....
Here’s a demonstration using the shell.
....
$ nix-shell
$ hello-flake
Hello from your flake!
....
=== Shell with access to a Haskell package on your local computer
This shell provides access to three Haskell packages that are on my hard
drive.
[source,nix,linenums]
....
include::0300-shell-haskell-local.nix[]
....
=== Shell with access to a Haskell package on your local computer, with interdependencies
This shell provides access to four Haskell packages that are on my hard
drive. The fourth package depends on the first three to build.
[source,nix,linenums]
....
include::0350-shell-haskell-local-deps.nix[]
....
=== Shell with an environment variable set
This shell has the environment variable FOO set to "`bar`"
[source,nix,linenums]
....
include::0400-shell-with-env-var.nix[]
....
Here’s a demonstration using the shell.
....
$ nix-shell
$ echo $FOO
bar
....

0
source/shell-recipes/0350-shell-haskell-local-deps.nix → source/shell-recipes/shell-haskell-local-deps/shell.nix
View file

0
source/shell-recipes/0300-shell-haskell-local.nix → source/shell-recipes/shell-haskell-local/shell.nix
View file

0
source/shell-recipes/0400-shell-with-env-var.nix → source/shell-recipes/shell-with-env-var/shell.nix
View file

0
source/shell-recipes/0250-shell-with-flake-rev.nix → source/shell-recipes/shell-with-flake-rev/shell.nix
View file

0
source/shell-recipes/0200-shell-with-flake.nix → source/shell-recipes/shell-with-flake/shell.nix
View file

0
source/shell-recipes/0150-shell-with-git-nix-pkg.nix → source/shell-recipes/shell-with-git-nix-pkg/shell.nix
View file

0
source/shell-recipes/0100-shell-with-nixpkgs.nix → source/shell-recipes/shell-with-nixpkgs/shell.nix
View file