aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-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
-rw-r--r--posts/novice_nix:_flake_templates.md229
5 files changed, 627 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>
diff --git a/posts/novice_nix:_flake_templates.md b/posts/novice_nix:_flake_templates.md
new file mode 100644
index 0000000..3b38b46
--- /dev/null
+++ b/posts/novice_nix:_flake_templates.md
@@ -0,0 +1,229 @@
1Flakes are very handy to setup entirely pure,
2project-specific dependencies (not just dependencies, but
3build steps, shell environments and more) in a declarative
4way. Writing Flake expressions can get repetitive though,
5oftentimes, you'd much rather start off with a skeleton.
6Luckily, `nix` already supports templates!
7
8You might already be familiar with `nix flake init`, that
9drops a "default" flake expression into your current working
10directory. If you head over to the manpage:
11
12```
13nix flake init --help
14```
15
16You will read that `nix flake init` creates a flake using
17the "default template". Additionally, you can create a flake
18from a specific template by passing the `-t` flag. Where
19does this default originate from?
20
21## Flake Registries
22
23Quick detour into registries! Registries are a way to alias
24popular flakes using identifiers:
25
26```
27# list a few predefined registries
28$ nix registry list
29. . .
30global flake:nixpkgs github:NixOS/nixpkgs
31global flake:patchelf github:NixOS/patchelf
32global flake:nix-serve github:edolstra/nix-serve
33global flake:templates github:NixOS/templates
34global flake:nickel github:tweag/nickel
35. . .
36
37# you can do
38$ nix flake show nickel
39
40# instead of
41$ nix flake show github:tweag/nickel
42
43# which is short for
44$ nix flake show git+https://github.com/tweag/nickel
45```
46
47You might notice a registry called `templates` aliased to
48`github:NixOS/templates`. Take a peek with `nix flake show`:
49
50```
51$ nix flake show templates
52github:NixOS/templates/79f48a7b822f35c068c5e235da2e9fbd154cecee
53├───defaultTemplate: template: A very basic flake
54└───templates
55 ├───bash-hello: template: An over-engineered Hello World in bash
56 ├───c-hello: template: An over-engineered Hello World in C
57 ├───rust-web-server: template: A Rust web server including a NixOS module
58 ├───simpleContainer: template: A NixOS container running apache-httpd
59 └───trivial: template: A very basic flake
60```
61
62Aha! There is a flake output called `defaultTemplate`. This
63is the template being sourced when you run `nix flake init`.
64Astute readers may conclude the following:
65
66```
67$ nix flake init
68
69# is equivalent to
70$ nix flake init -t templates#defaultTemplate
71
72# is equivalent to
73$ nix flake init -t github:NixOS/templates#defaultTemplate
74
75# which is short for
76$ nix flake init -t git+https://NixOS/templates#defaultTemplate
77```
78
79Similarly, the other templates can be accessed via:
80
81```
82$ nix flake init -t templates#c-hello
83$ nix flake init -t templates#simpleContainer
84# I think you get the drift ...
85```
86
87## Rolling your own templates
88
89Alright, so all we need to do is:
90
91 - create a flake with a `templates` output
92 - populate our template directories with content
93 - (**optionally**) alias our custom templates flake to an
94 identifier using registries, for easier access
95
96Start off by creating a directory to store your templates in
97(we will be converting this to a registry later):
98
99```
100$ mkdir ~/mytemplates
101```
102
103A flake that exposes a "template" as its output looks
104something like this:
105
106```
107# inside ~/mytemplates/flake.nix
108
109{
110 description = "Pepper's flake templates";
111
112 outputs = { self, ... }: {
113 templates = {
114 latex-report = {
115 path = ./latex-report-template;
116 description = "A latex whitepaper project";
117 };
118 rust-hello = {
119 path = ./rust-hello-template;
120 description = "Simple Hello World in Rust";
121 };
122 };
123 };
124}
125```
126
127The `path` attribute to each template is what gets copied
128over when you initialize a flake. Running `nix flake init -t
129.#latex-report` will initialize the current directory with
130the contents of `./latex-report-template` (we are yet to
131populate these directories).
132
133The output of `nix flake show` should be something like:
134
135```
136$ nix flake show
137path:/home/np/code/nix-stuff/template-tests?narHash=sha256-{...}
138└───templates
139 ├───latex-report: template: A latex whitepaper project
140 └───rust-hello: template: Simple Hello World in Rust
141```
142
143Populate your template directories with content, here are my
144template directories for example:
145
146```
147$ tree mytemplates
148mytemplates/
149├── flake.nix
150├── latex-report-template
151│   ├── flake.nix
152│   ├── makefile
153│   └── src
154│   ├── meta.sty
155│   └── report.tex
156└── rust-hello-template
157 ├── Cargo.toml
158 ├── flake.nix
159 └── src
160 └── main.rs
161```
162
163And that's it! Start using your templates with:
164
165```
166$ nix flake init -t ~/mytemplates#rust-hello
167$ tree .
168.
169├── Cargo.toml
170├── flake.nix
171└── src
172 └── main.rs
173```
174
175To avoid writing `~/mytemplates` each time, simply alias it
176to a registry:
177
178```
179# alias it to `biscuits`
180$ nix registry add biscuits ~/mytemplates
181
182# you will see it listed under `user` registries
183$ nix registry list
184. . .
185user flake:biscuits path:/home/np/template-tests
186. . .
187
188$ nix flake init -t biscuits#latex-report
189```
190
191## Extending the official templates
192
193I personally, would like the `biscuits` registry to include
194not just my homemade templates, but also the templates from
195`NixOS/templates` (and maybe a couple of other repositories
196in the wild):
197
198```
199 {
200 description = "Pepper's flake templates";
201
202+ inputs = {
203+ official-templates.url = github:NixOS/templates;
204+ other-templates.url = github:some-other/templates;
205+ };
206
207 outputs = { self, official-templates, other-templates ... }: {
208
209 templates = {
210 latex-report = {
211 path = ./latex-report-template;
212 description = "A latex whitepaper project";
213 };
214 rust-hello = {
215 path = ./rust-hello-template;
216 description = "Simple Hello World in Rust, with overloaded Rust toolchain";
217 };
218 }
219+ // official-templates.templates
220+ // other-templates.templates;
221
222 };
223 }
224```
225
226Running `nix flake show biscuits` will now list templates
227from the `biscuits` registry as well as the ones from
228`NixOS/templates`. Ensure that the names don't collide
229though.
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-25 07:05:56 +0000