aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAkshay <[email protected]>2021-10-05 17:51:58 +0100
committerAkshay <[email protected]>2021-10-05 17:51:58 +0100
commit89b779f6bfbd476d5302e740a4ad3263a15a8974 (patch)
tree8fa93e8c01a28b879f76190688d106653d55440f /docs
parent938c4648b102975cd73f82457544ec7dc0318bfa (diff)
new post: "Novice Nix: Flake Templates"
Diffstat (limited to 'docs')
-rw-r--r--docs/index.html16
-rw-r--r--docs/index.xml152
-rw-r--r--docs/posts/index.html17
-rw-r--r--docs/posts/novice_nix:_flake_templates/index.html221
4 files changed, 398 insertions, 8 deletions
diff --git a/docs/index.html b/docs/index.html
index c314061..d8fd844 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -42,15 +42,15 @@
42 <tr> 42 <tr>
43 <td class=table-post> 43 <td class=table-post>
44 <div class="date"> 44 <div class="date">
45 11/04 — 2021 45 05/10 — 2021
46 </div> 46 </div>
47 <a href="/posts/SDL2_devlog" class="post-link"> 47 <a href="/posts/novice_nix:_flake_templates" class="post-link">
48 <span class="post-link">SDL2 Devlog</span> 48 <span class="post-link">Novice Nix: Flake Templates</span>
49 </a> 49 </a>
50 </td> 50 </td>
51 <td class=table-stats> 51 <td class=table-stats>
52 <span class="stats-number"> 52 <span class="stats-number">
53 10.0 53 5.5
54 </span> 54 </span>
55 <span class=stats-unit>min</span> 55 <span class=stats-unit>min</span>
56 </td> 56 </td>
@@ -59,15 +59,15 @@
59 <tr> 59 <tr>
60 <td class=table-post> 60 <td class=table-post>
61 <div class="date"> 61 <div class="date">
62 17/10 — 2020 62 11/04 — 2021
63 </div> 63 </div>
64 <a href="/posts/self-hosting_git" class="post-link"> 64 <a href="/posts/SDL2_devlog" class="post-link">
65 <span class="post-link">Self-hosting Git</span> 65 <span class="post-link">SDL2 Devlog</span>
66 </a> 66 </a>
67 </td> 67 </td>
68 <td class=table-stats> 68 <td class=table-stats>
69 <span class="stats-number"> 69 <span class="stats-number">
70 5.4 70 10.0
71 </span> 71 </span>
72 <span class=stats-unit>min</span> 72 <span class=stats-unit>min</span>
73 </td> 73 </td>
diff --git a/docs/index.xml b/docs/index.xml
index 06bbc87..d45ba57 100644
--- a/docs/index.xml
+++ b/docs/index.xml
@@ -12,6 +12,158 @@
12 <language>en-us</language> 12 <language>en-us</language>
13 <copyright>Creative Commons BY-NC-SA 4.0</copyright> 13 <copyright>Creative Commons BY-NC-SA 4.0</copyright>
14 <item> 14 <item>
15<title>Novice Nix: Flake Templates</title>
16<description>&lt;p&gt;Flakes are very handy to setup entirely pure, project-specific dependencies (not just dependencies, but build steps, shell environments and more) in a declarative way. Writing Flake expressions can get repetitive though, oftentimes, you’d much rather start off with a skeleton. Luckily, &lt;code&gt;nix&lt;/code&gt; already supports templates!&lt;/p&gt;
17&lt;p&gt;You might already be familiar with &lt;code&gt;nix flake init&lt;/code&gt;, that drops a “default” flake expression into your current working directory. If you head over to the manpage:&lt;/p&gt;
18&lt;pre&gt;&lt;code&gt;nix flake init --help&lt;/code&gt;&lt;/pre&gt;
19&lt;p&gt;You will read that &lt;code&gt;nix flake init&lt;/code&gt; creates a flake using the “default template”. Additionally, you can create a flake from a specific template by passing the &lt;code&gt;-t&lt;/code&gt; flag. Where does this default originate from?&lt;/p&gt;
20&lt;h2 id="flake-registries"&gt;Flake Registries&lt;/h2&gt;
21&lt;p&gt;Quick detour into registries! Registries are a way to alias popular flakes using identifiers:&lt;/p&gt;
22&lt;pre&gt;&lt;code&gt;# list a few predefined registries
23$ nix registry list
24. . .
25global flake:nixpkgs github:NixOS/nixpkgs
26global flake:patchelf github:NixOS/patchelf
27global flake:nix-serve github:edolstra/nix-serve
28global flake:templates github:NixOS/templates
29global flake:nickel github:tweag/nickel
30. . .
31
32# you can do
33$ nix flake show nickel
34
35# instead of
36$ nix flake show github:tweag/nickel
37
38# which is short for
39$ nix flake show git+https://github.com/tweag/nickel&lt;/code&gt;&lt;/pre&gt;
40&lt;p&gt;You might notice a registry called &lt;code&gt;templates&lt;/code&gt; aliased to &lt;code&gt;github:NixOS/templates&lt;/code&gt;. Take a peek with &lt;code&gt;nix flake show&lt;/code&gt;:&lt;/p&gt;
41&lt;pre&gt;&lt;code&gt;$ nix flake show templates
42github:NixOS/templates/79f48a7b822f35c068c5e235da2e9fbd154cecee
43├───defaultTemplate: template: A very basic flake
44└───templates
45 ├───bash-hello: template: An over-engineered Hello World in bash
46 ├───c-hello: template: An over-engineered Hello World in C
47 ├───rust-web-server: template: A Rust web server including a NixOS module
48 ├───simpleContainer: template: A NixOS container running apache-httpd
49 └───trivial: template: A very basic flake&lt;/code&gt;&lt;/pre&gt;
50&lt;p&gt;Aha! There is a flake output called &lt;code&gt;defaultTemplate&lt;/code&gt;. This is the template being sourced when you run &lt;code&gt;nix flake init&lt;/code&gt;. Astute readers may conclude the following:&lt;/p&gt;
51&lt;pre&gt;&lt;code&gt;$ nix flake init
52
53# is equivalent to
54$ nix flake init -t templates#defaultTemplate
55
56# is equivalent to
57$ nix flake init -t github:NixOS/templates#defaultTemplate
58
59# which is short for
60$ nix flake init -t git+https://NixOS/templates#defaultTemplate&lt;/code&gt;&lt;/pre&gt;
61&lt;p&gt;Similarly, the other templates can be accessed via:&lt;/p&gt;
62&lt;pre&gt;&lt;code&gt;$ nix flake init -t templates#c-hello
63$ nix flake init -t templates#simpleContainer
64# I think you get the drift ...&lt;/code&gt;&lt;/pre&gt;
65&lt;h2 id="rolling-your-own-templates"&gt;Rolling your own templates&lt;/h2&gt;
66&lt;p&gt;Alright, so all we need to do is:&lt;/p&gt;
67&lt;ul&gt;
68&lt;li&gt;create a flake with a &lt;code&gt;templates&lt;/code&gt; output&lt;/li&gt;
69&lt;li&gt;populate our template directories with content&lt;/li&gt;
70&lt;li&gt;(&lt;strong&gt;optionally&lt;/strong&gt;) alias our custom templates flake to an identifier using registries, for easier access&lt;/li&gt;
71&lt;/ul&gt;
72&lt;p&gt;Start off by creating a directory to store your templates in (we will be converting this to a registry later):&lt;/p&gt;
73&lt;pre&gt;&lt;code&gt;$ mkdir ~/mytemplates&lt;/code&gt;&lt;/pre&gt;
74&lt;p&gt;A flake that exposes a “template” as its output looks something like this:&lt;/p&gt;
75&lt;pre&gt;&lt;code&gt;# inside ~/mytemplates/flake.nix
76
77{
78 description = &amp;quot;Pepper&amp;#39;s flake templates&amp;quot;;
79
80 outputs = { self, ... }: {
81 templates = {
82 latex-report = {
83 path = ./latex-report-template;
84 description = &amp;quot;A latex whitepaper project&amp;quot;;
85 };
86 rust-hello = {
87 path = ./rust-hello-template;
88 description = &amp;quot;Simple Hello World in Rust&amp;quot;;
89 };
90 };
91 };
92}&lt;/code&gt;&lt;/pre&gt;
93&lt;p&gt;The &lt;code&gt;path&lt;/code&gt; attribute to each template is what gets copied over when you initialize a flake. Running &lt;code&gt;nix flake init -t .#latex-report&lt;/code&gt; will initialize the current directory with the contents of &lt;code&gt;./latex-report-template&lt;/code&gt; (we are yet to populate these directories).&lt;/p&gt;
94&lt;p&gt;The output of &lt;code&gt;nix flake show&lt;/code&gt; should be something like:&lt;/p&gt;
95&lt;pre&gt;&lt;code&gt;$ nix flake show
96path:/home/np/code/nix-stuff/template-tests?narHash=sha256-{...}
97└───templates
98 ├───latex-report: template: A latex whitepaper project
99 └───rust-hello: template: Simple Hello World in Rust&lt;/code&gt;&lt;/pre&gt;
100&lt;p&gt;Populate your template directories with content, here are my template directories for example:&lt;/p&gt;
101&lt;pre&gt;&lt;code&gt;$ tree mytemplates
102mytemplates/
103├── flake.nix
104├── latex-report-template
105│   ├── flake.nix
106│   ├── makefile
107│   └── src
108│   ├── meta.sty
109│   └── report.tex
110└── rust-hello-template
111 ├── Cargo.toml
112 ├── flake.nix
113 └── src
114 └── main.rs&lt;/code&gt;&lt;/pre&gt;
115&lt;p&gt;And that’s it! Start using your templates with:&lt;/p&gt;
116&lt;pre&gt;&lt;code&gt;$ nix flake init -t ~/mytemplates#rust-hello
117$ tree .
118.
119├── Cargo.toml
120├── flake.nix
121└── src
122 └── main.rs&lt;/code&gt;&lt;/pre&gt;
123&lt;p&gt;To avoid writing &lt;code&gt;~/mytemplates&lt;/code&gt; each time, simply alias it to a registry:&lt;/p&gt;
124&lt;pre&gt;&lt;code&gt;# alias it to `biscuits`
125$ nix registry add biscuits ~/mytemplates
126
127# you will see it listed under `user` registries
128$ nix registry list
129. . .
130user flake:biscuits path:/home/np/template-tests
131. . .
132
133$ nix flake init -t biscuits#latex-report&lt;/code&gt;&lt;/pre&gt;
134&lt;h2 id="extending-the-official-templates"&gt;Extending the official templates&lt;/h2&gt;
135&lt;p&gt;I personally, would like the &lt;code&gt;biscuits&lt;/code&gt; registry to include not just my homemade templates, but also the templates from &lt;code&gt;NixOS/templates&lt;/code&gt; (and maybe a couple of other repositories in the wild):&lt;/p&gt;
136&lt;pre&gt;&lt;code&gt; {
137 description = &amp;quot;Pepper&amp;#39;s flake templates&amp;quot;;
138
139+ inputs = {
140+ official-templates.url = github:NixOS/templates;
141+ other-templates.url = github:some-other/templates;
142+ };
143
144 outputs = { self, official-templates, other-templates ... }: {
145
146 templates = {
147 latex-report = {
148 path = ./latex-report-template;
149 description = &amp;quot;A latex whitepaper project&amp;quot;;
150 };
151 rust-hello = {
152 path = ./rust-hello-template;
153 description = &amp;quot;Simple Hello World in Rust, with overloaded Rust toolchain&amp;quot;;
154 };
155 }
156+ // official-templates.templates
157+ // other-templates.templates;
158
159 };
160 }&lt;/code&gt;&lt;/pre&gt;
161&lt;p&gt;Running &lt;code&gt;nix flake show biscuits&lt;/code&gt; will now list templates from the &lt;code&gt;biscuits&lt;/code&gt; registry as well as the ones from &lt;code&gt;NixOS/templates&lt;/code&gt;. Ensure that the names don’t collide though.&lt;/p&gt;</description>
162<link>https://peppe.rs/posts/novice_nix:_flake_templates/</link>
163<pubDate>Tue, 05 Oct 2021 16:49:00 +0000</pubDate>
164<guid>https://peppe.rs/posts/novice_nix:_flake_templates/</guid>
165</item>
166<item>
15<title>SDL2 Devlog</title> 167<title>SDL2 Devlog</title>
16<description>&lt;p&gt;I have been working on an editor for the &lt;a href="https://git.peppe.rs/graphics/obi/about"&gt;One Bit Image&lt;/a&gt; file format in Rust and SDL2. This entry in my blog follows my progress on the editor. The days are listed in reverse chronological order, begin from the bottom, if this is your first time on this page.&lt;/p&gt; 168<description>&lt;p&gt;I have been working on an editor for the &lt;a href="https://git.peppe.rs/graphics/obi/about"&gt;One Bit Image&lt;/a&gt; file format in Rust and SDL2. This entry in my blog follows my progress on the editor. The days are listed in reverse chronological order, begin from the bottom, if this is your first time on this page.&lt;/p&gt;
17&lt;h3 id="day-20"&gt;Day 20&lt;/h3&gt; 169&lt;h3 id="day-20"&gt;Day 20&lt;/h3&gt;
diff --git a/docs/posts/index.html b/docs/posts/index.html
index dc13873..d15342d 100644
--- a/docs/posts/index.html
+++ b/docs/posts/index.html
@@ -27,6 +27,23 @@
27 <tr> 27 <tr>
28 <td class=table-post> 28 <td class=table-post>
29 <div class="date"> 29 <div class="date">
30 05/10 — 2021
31 </div>
32 <a href="/posts/novice_nix:_flake_templates" class="post-link">
33 <span class="post-link">Novice Nix: Flake Templates</span>
34 </a>
35 </td>
36 <td class=table-stats>
37 <span class="stats-number">
38 5.5
39 </span>
40 <span class=stats-unit>min</span>
41 </td>
42 </tr>
43
44 <tr>
45 <td class=table-post>
46 <div class="date">
30 11/04 — 2021 47 11/04 — 2021
31 </div> 48 </div>
32 <a href="/posts/SDL2_devlog" class="post-link"> 49 <a href="/posts/SDL2_devlog" class="post-link">
diff --git a/docs/posts/novice_nix:_flake_templates/index.html b/docs/posts/novice_nix:_flake_templates/index.html
new file mode 100644
index 0000000..f71c13a
--- /dev/null
+++ b/docs/posts/novice_nix:_flake_templates/index.html
@@ -0,0 +1,221 @@
1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <link rel="stylesheet" href="/style.css">
5 <link rel="stylesheet" href="/syntax.css">
6 <meta charset="UTF-8">
7 <meta name="viewport" content="initial-scale=1">
8 <meta content="#ffffff" name="theme-color">
9 <meta name="HandheldFriendly" content="true">
10 <meta property="og:title" content="Novice Nix: Flake Templates">
11 <meta property="og:type" content="website">
12 <meta property="og:description" content="a static site {for, by, about} me ">
13 <meta property="og:url" content="https://peppe.rs">
14 <link rel="icon" type="image/x-icon" href="/favicon.png">
15 <title>Novice Nix: Flake Templates · peppe.rs</title>
16 <body>
17 <div class="posts">
18 <div class="post">
19 <a href="/" class="post-end-link">Home</a>
20 <span>/</span>
21 <a href="/posts" class="post-end-link">Posts</a>
22 <span>/</span>
23 <a class="post-end-link">Novice Nix: Flake Templates</a>
24 <a class="stats post-end-link" href="https://git.peppe.rs/web/site/plain/posts/novice_nix:_flake_templates.md
25">View Raw</a>
26 <div class="separator"></div>
27 <div class="date">
28 05/10 — 2021
29 <div class="stats">
30 <span class="stats-number">
31 91.51
32 </span>
33 <span class="stats-unit">cm</span>
34 &nbsp
35 <span class="stats-number">
36 5.5
37 </span>
38 <span class="stats-unit">min</span>
39 </div>
40 </div>
41 <h1>
42 Novice Nix: Flake Templates
43 </h1>
44 <div class="post-text">
45 <p>Flakes are very handy to setup entirely pure, project-specific dependencies (not just dependencies, but build steps, shell environments and more) in a declarative way. Writing Flake expressions can get repetitive though, oftentimes, you’d much rather start off with a skeleton. Luckily, <code>nix</code> already supports templates!</p>
46<p>You might already be familiar with <code>nix flake init</code>, that drops a “default” flake expression into your current working directory. If you head over to the manpage:</p>
47<pre><code>nix flake init --help</code></pre>
48<p>You will read that <code>nix flake init</code> creates a flake using the “default template”. Additionally, you can create a flake from a specific template by passing the <code>-t</code> flag. Where does this default originate from?</p>
49<h2 id="flake-registries">Flake Registries</h2>
50<p>Quick detour into registries! Registries are a way to alias popular flakes using identifiers:</p>
51<pre><code># list a few predefined registries
52$ nix registry list
53. . .
54global flake:nixpkgs github:NixOS/nixpkgs
55global flake:patchelf github:NixOS/patchelf
56global flake:nix-serve github:edolstra/nix-serve
57global flake:templates github:NixOS/templates
58global flake:nickel github:tweag/nickel
59. . .
60
61# you can do
62$ nix flake show nickel
63
64# instead of
65$ nix flake show github:tweag/nickel
66
67# which is short for
68$ nix flake show git+https://github.com/tweag/nickel</code></pre>
69<p>You might notice a registry called <code>templates</code> aliased to <code>github:NixOS/templates</code>. Take a peek with <code>nix flake show</code>:</p>
70<pre><code>$ nix flake show templates
71github:NixOS/templates/79f48a7b822f35c068c5e235da2e9fbd154cecee
72├───defaultTemplate: template: A very basic flake
73└───templates
74 ├───bash-hello: template: An over-engineered Hello World in bash
75 ├───c-hello: template: An over-engineered Hello World in C
76 ├───rust-web-server: template: A Rust web server including a NixOS module
77 ├───simpleContainer: template: A NixOS container running apache-httpd
78 └───trivial: template: A very basic flake</code></pre>
79<p>Aha! There is a flake output called <code>defaultTemplate</code>. This is the template being sourced when you run <code>nix flake init</code>. Astute readers may conclude the following:</p>
80<pre><code>$ nix flake init
81
82# is equivalent to
83$ nix flake init -t templates#defaultTemplate
84
85# is equivalent to
86$ nix flake init -t github:NixOS/templates#defaultTemplate
87
88# which is short for
89$ nix flake init -t git+https://NixOS/templates#defaultTemplate</code></pre>
90<p>Similarly, the other templates can be accessed via:</p>
91<pre><code>$ nix flake init -t templates#c-hello
92$ nix flake init -t templates#simpleContainer
93# I think you get the drift ...</code></pre>
94<h2 id="rolling-your-own-templates">Rolling your own templates</h2>
95<p>Alright, so all we need to do is:</p>
96<ul>
97<li>create a flake with a <code>templates</code> output</li>
98<li>populate our template directories with content</li>
99<li>(<strong>optionally</strong>) alias our custom templates flake to an identifier using registries, for easier access</li>
100</ul>
101<p>Start off by creating a directory to store your templates in (we will be converting this to a registry later):</p>
102<pre><code>$ mkdir ~/mytemplates</code></pre>
103<p>A flake that exposes a “template” as its output looks something like this:</p>
104<pre><code># inside ~/mytemplates/flake.nix
105
106{
107 description = &quot;Pepper&#39;s flake templates&quot;;
108
109 outputs = { self, ... }: {
110 templates = {
111 latex-report = {
112 path = ./latex-report-template;
113 description = &quot;A latex whitepaper project&quot;;
114 };
115 rust-hello = {
116 path = ./rust-hello-template;
117 description = &quot;Simple Hello World in Rust&quot;;
118 };
119 };
120 };
121}</code></pre>
122<p>The <code>path</code> attribute to each template is what gets copied over when you initialize a flake. Running <code>nix flake init -t .#latex-report</code> will initialize the current directory with the contents of <code>./latex-report-template</code> (we are yet to populate these directories).</p>
123<p>The output of <code>nix flake show</code> should be something like:</p>
124<pre><code>$ nix flake show
125path:/home/np/code/nix-stuff/template-tests?narHash=sha256-{...}
126└───templates
127 ├───latex-report: template: A latex whitepaper project
128 └───rust-hello: template: Simple Hello World in Rust</code></pre>
129<p>Populate your template directories with content, here are my template directories for example:</p>
130<pre><code>$ tree mytemplates
131mytemplates/
132├── flake.nix
133├── latex-report-template
134│   ├── flake.nix
135│   ├── makefile
136│   └── src
137│   ├── meta.sty
138│   └── report.tex
139└── rust-hello-template
140 ├── Cargo.toml
141 ├── flake.nix
142 └── src
143 └── main.rs</code></pre>
144<p>And that’s it! Start using your templates with:</p>
145<pre><code>$ nix flake init -t ~/mytemplates#rust-hello
146$ tree .
147.
148├── Cargo.toml
149├── flake.nix
150└── src
151 └── main.rs</code></pre>
152<p>To avoid writing <code>~/mytemplates</code> each time, simply alias it to a registry:</p>
153<pre><code># alias it to `biscuits`
154$ nix registry add biscuits ~/mytemplates
155
156# you will see it listed under `user` registries
157$ nix registry list
158. . .
159user flake:biscuits path:/home/np/template-tests
160. . .
161
162$ nix flake init -t biscuits#latex-report</code></pre>
163<h2 id="extending-the-official-templates">Extending the official templates</h2>
164<p>I personally, would like the <code>biscuits</code> registry to include not just my homemade templates, but also the templates from <code>NixOS/templates</code> (and maybe a couple of other repositories in the wild):</p>
165<pre><code> {
166 description = &quot;Pepper&#39;s flake templates&quot;;
167
168+ inputs = {
169+ official-templates.url = github:NixOS/templates;
170+ other-templates.url = github:some-other/templates;
171+ };
172
173 outputs = { self, official-templates, other-templates ... }: {
174
175 templates = {
176 latex-report = {
177 path = ./latex-report-template;
178 description = &quot;A latex whitepaper project&quot;;
179 };
180 rust-hello = {
181 path = ./rust-hello-template;
182 description = &quot;Simple Hello World in Rust, with overloaded Rust toolchain&quot;;
183 };
184 }
185+ // official-templates.templates
186+ // other-templates.templates;
187
188 };
189 }</code></pre>
190<p>Running <code>nix flake show biscuits</code> will now list templates from the <code>biscuits</code> registry as well as the ones from <code>NixOS/templates</code>. Ensure that the names don’t collide though.</p>
191
192 </div>
193
194 <div class="intro">
195 Hi.
196 <div class="hot-links">
197 <a href="https://peppe.rs/index.xml" class="feed-button">Subscribe</a>
198 <a href="https://liberapay.com/nerdypepper/donate" class="donate-button">Donate</a>
199 </div>
200 <p>I'm Akshay, I go by nerd or nerdypepper on the internet.</p>
201 <p>
202 I am a compsci undergrad, Rust programmer and an enthusiastic Vimmer.
203 I write <a href="https://git.peppe.rs">open-source stuff</a> to pass time.
204 I also design fonts:
205 <a href="https://git.peppe.rs/fonts/scientifica">scientifica</a>,
206 <a href="https://git.peppe.rs/fonts/curie">curie</a>.
207 </p>
208 <p>Send me a mail at [email protected] or a message at [email protected].</p>
209 </div>
210
211 <a href="/" class="post-end-link">Home</a>
212 <span>/</span>
213 <a href="/posts" class="post-end-link">Posts</a>
214 <span>/</span>
215 <a class="post-end-link">Novice Nix: Flake Templates</a>
216 <a class="stats post-end-link" href="https://git.peppe.rs/web/site/plain/posts/novice_nix:_flake_templates.md
217">View Raw</a>
218 </div>
219 </div>
220 </body>
221</html>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-25 06:43:36 +0000