aboutsummaryrefslogtreecommitdiff
path: root/docs/posts/novice_nix:_flake_templates
diff options
context:
space:
mode:
Diffstat (limited to 'docs/posts/novice_nix:_flake_templates')
-rw-r--r--docs/posts/novice_nix:_flake_templates/index.html221
1 files changed, 221 insertions, 0 deletions
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-26 04:38:30 +0000