···

       
1
       
 
       
*.chapter.xml

     

       
2
       
 
       
*.section.xml

     

       
3
       
 
       
.version

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
4
       
 
       
out

     

       
5
       
-
       
manual-full.xml

     

       
6
       
-
       
highlightjs

     

       
7
       
-
       
functions/library/locations.xml

     

···

       
1
       
 
       
*.chapter.xml

     

       
2
       
 
       
*.section.xml

     

       
3
       
 
       
.version

     

       
4
       
+
       
functions/library/generated

     

       
5
       
+
       
functions/library/locations.xml

     

       
6
       
+
       
highlightjs

     

       
7
       
+
       
manual-full.xml

     

       
8
       
 
       
out

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
197
       
 
       
  <title>Package naming</title>

     

       
198
       
 
       


     

       
199
       
 
       
  <para>

     

       
200
       
-
       
    The key words

     

       
201
       
-
       
    <emphasis>must</emphasis>,

     

       
202
       
-
       
    <emphasis>must not</emphasis>,

     

       
203
       
-
       
    <emphasis>required</emphasis>,

     

       
204
       
-
       
    <emphasis>shall</emphasis>,

     

       
205
       
-
       
    <emphasis>shall not</emphasis>,

     

       
206
       
-
       
    <emphasis>should</emphasis>,

     

       
207
       
-
       
    <emphasis>should not</emphasis>,

     

       
208
       
-
       
    <emphasis>recommended</emphasis>,

     

       
209
       
-
       
    <emphasis>may</emphasis>,

     

       
210
       
-
       
    and <emphasis>optional</emphasis> in this section

     

       
211
       
-
       
    are to be interpreted as described in

     

       
212
       
-
       
    <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>.

     

       
213
       
-
       
    Only <emphasis>emphasized</emphasis> words are to be interpreted in this way.

     

       
214
       
 
       
  </para>

     

       
215
       
 
       


     

       
216
       
 
       
  <para>

     
···

       
253
       
 
       
   <itemizedlist>

     

       
254
       
 
       
    <listitem>

     

       
255
       
 
       
     <para>

     

       
256
       
-
       
       The <literal>name</literal> attribute <emphasis>should</emphasis>

     

       
257
       
-
       
       be identical to the upstream package name.

     

       
258
       
 
       
     </para>

     

       
259
       
 
       
    </listitem>

     

       
260
       
 
       
    <listitem>

     

       
261
       
 
       
     <para>

     

       
262
       
-
       
       The <literal>name</literal> attribute <emphasis>must not</emphasis>

     

       
263
       
-
       
       contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>

     

       
264
       
-
       
       instead of <literal>"MPlayer-1.0rc2"</literal>.

     

       
265
       
 
       
     </para>

     

       
266
       
 
       
    </listitem>

     

       
267
       
 
       
    <listitem>

     
···

       
275
       
 
       
     <para>

     

       
276
       
 
       
      If a package is not a release but a commit from a repository, then the

     

       
277
       
 
       
      version part of the name <emphasis>must</emphasis> be the date of that

     

       
278
       
-
       
      (fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal>

     

       
279
       
-
       
      format. Also append <literal>"unstable"</literal> to the name - e.g.,

     

       
0
       
 
       

     

       
280
       
 
       
      <literal>"pkgname-unstable-2014-09-23"</literal>.

     

       
281
       
 
       
     </para>

     

       
282
       
 
       
    </listitem>

     

       
283
       
 
       
    <listitem>

     

       
284
       
 
       
     <para>

     

       
285
       
-
       
      Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names,

     

       
286
       
-
       
      rather than converted to underscores or camel cased — e.g.,

     

       
287
       
-
       
      <varname>http-parser</varname> instead of <varname>http_parser</varname>

     

       
288
       
-
       
      or <varname>httpParser</varname>. The hyphenated style is preferred in

     

       
289
       
-
       
      all three package names.

     

       
290
       
 
       
     </para>

     

       
291
       
 
       
    </listitem>

     

       
292
       
 
       
    <listitem>

     

       
293
       
 
       
     <para>

     

       
294
       
-
       
      If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in

     

       
295
       
-
       
      the variable names in <filename>all-packages.nix</filename>, e.g.

     

       
296
       
-
       
      <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If

     

       
297
       
-
       
      there is an obvious “default” version, make an attribute like

     

       
298
       
-
       
      <literal>json-c = json-c-0-9;</literal>. See also

     

       
299
       
-
       
      <xref linkend="sec-versioning" />

     

       
300
       
 
       
     </para>

     

       
301
       
 
       
    </listitem>

     

       
302
       
 
       
   </itemizedlist>

     
···

       
814
       
 
       


     

       
815
       
 
       
  <para>

     

       
816
       
 
       
   There are multiple ways to fetch a package source in nixpkgs. The general

     

       
817
       
-
       
   guideline is that you should package reproducible sources with a high degree of

     

       
818
       
-
       
   availability. Right now there is only one fetcher which has mirroring

     

       
819
       
 
       
   support and that is <literal>fetchurl</literal>. Note that you should also

     

       
820
       
 
       
   prefer protocols which have a corresponding proxy environment variable.

     

       
821
       
 
       
  </para>

     
···

       
869
       
 
       
}

     

       
870
       
 
       
</programlisting>

     

       
871
       
 
       
      Find the value to put as <literal>sha256</literal> by running

     

       
872
       
-
       
      <literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal>

     

       
873
       
-
       
      or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
874
       
 
       
     </para>

     

       
875
       
 
       
    </listitem>

     

       
876
       
 
       
   </itemizedlist>

     
···

       
953
       
 
       
     would be replace hash with a fake one and rebuild. Nix build will fail and

     

       
954
       
 
       
     error message will contain desired hash.

     

       
955
       
 
       
    </para>

     

       
956
       
-
       
    <warning><para>This method has security problems. Check below for details.</para></warning>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
957
       
 
       
   </listitem>

     

       
958
       
 
       
  </orderedlist>

     

       
959
       
 
       


     

       
960
       
 
       
  <section xml:id="sec-source-hashes-security">

     

       
961
       
 
       
   <title>Obtaining hashes securely</title>

     

       
0
       
 
       

     

       
962
       
 
       
   <para>

     

       
963
       
-
       
    Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching

     

       
964
       
-
       
    source you can fetch malware, and instead of source hash you get hash of malware. Here are

     

       
965
       
-
       
    security considerations for this scenario:

     

       
966
       
 
       
   </para>

     

       
0
       
 
       

     

       
967
       
 
       
   <itemizedlist>

     

       
968
       
 
       
    <listitem>

     

       
969
       
 
       
     <para>

     
···

       
972
       
 
       
    </listitem>

     

       
973
       
 
       
    <listitem>

     

       
974
       
 
       
     <para>

     

       
975
       
-
       
      hashes from upstream (in method 3) should be obtained via secure protocol;

     

       
0
       
 
       

     

       
976
       
 
       
     </para>

     

       
977
       
 
       
    </listitem>

     

       
978
       
 
       
    <listitem>

     
···

       
982
       
 
       
    </listitem>

     

       
983
       
 
       
    <listitem>

     

       
984
       
 
       
     <para>

     

       
985
       
-
       
      <literal>https://</literal> URLs are not secure in method 5. When obtaining hashes

     

       
986
       
-
       
      with fake hash method, TLS checks are disabled. So

     

       
987
       
-
       
      refetch source hash from several different networks to exclude MITM scenario.

     

       
988
       
-
       
      Alternatively, use fake hash method to make Nix error, but instead of extracting

     

       
989
       
-
       
      hash from error, extract <literal>https://</literal> URL and prefetch it

     

       
990
       
-
       
      with method 1.

     

       
991
       
 
       
     </para>

     

       
992
       
 
       
    </listitem>

     

       
993
       
 
       
   </itemizedlist>

     

···

       
197
       
 
       
  <title>Package naming</title>

     

       
198
       
 
       


     

       
199
       
 
       
  <para>

     

       
200
       
+
       
   The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>,

     

       
201
       
+
       
   <emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall

     

       
202
       
+
       
   not</emphasis>, <emphasis>should</emphasis>, <emphasis>should

     

       
203
       
+
       
   not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>,

     

       
204
       
+
       
   and <emphasis>optional</emphasis> in this section are to be interpreted as

     

       
205
       
+
       
   described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC

     

       
206
       
+
       
   2119</link>. Only <emphasis>emphasized</emphasis> words are to be

     

       
207
       
+
       
   interpreted in this way.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
208
       
 
       
  </para>

     

       
209
       
 
       


     

       
210
       
 
       
  <para>

     
···

       
247
       
 
       
   <itemizedlist>

     

       
248
       
 
       
    <listitem>

     

       
249
       
 
       
     <para>

     

       
250
       
+
       
      The <literal>name</literal> attribute <emphasis>should</emphasis> be

     

       
251
       
+
       
      identical to the upstream package name.

     

       
252
       
 
       
     </para>

     

       
253
       
 
       
    </listitem>

     

       
254
       
 
       
    <listitem>

     

       
255
       
 
       
     <para>

     

       
256
       
+
       
      The <literal>name</literal> attribute <emphasis>must not</emphasis>

     

       
257
       
+
       
      contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>

     

       
258
       
+
       
      instead of <literal>"MPlayer-1.0rc2"</literal>.

     

       
259
       
 
       
     </para>

     

       
260
       
 
       
    </listitem>

     

       
261
       
 
       
    <listitem>

     
···

       
269
       
 
       
     <para>

     

       
270
       
 
       
      If a package is not a release but a commit from a repository, then the

     

       
271
       
 
       
      version part of the name <emphasis>must</emphasis> be the date of that

     

       
272
       
+
       
      (fetched) commit. The date <emphasis>must</emphasis> be in

     

       
273
       
+
       
      <literal>"YYYY-MM-DD"</literal> format. Also append

     

       
274
       
+
       
      <literal>"unstable"</literal> to the name - e.g.,

     

       
275
       
 
       
      <literal>"pkgname-unstable-2014-09-23"</literal>.

     

       
276
       
 
       
     </para>

     

       
277
       
 
       
    </listitem>

     

       
278
       
 
       
    <listitem>

     

       
279
       
 
       
     <para>

     

       
280
       
+
       
      Dashes in the package name <emphasis>should</emphasis> be preserved in

     

       
281
       
+
       
      new variable names, rather than converted to underscores or camel cased

     

       
282
       
+
       
      — e.g., <varname>http-parser</varname> instead of

     

       
283
       
+
       
      <varname>http_parser</varname> or <varname>httpParser</varname>. The

     

       
284
       
+
       
      hyphenated style is preferred in all three package names.

     

       
285
       
 
       
     </para>

     

       
286
       
 
       
    </listitem>

     

       
287
       
 
       
    <listitem>

     

       
288
       
 
       
     <para>

     

       
289
       
+
       
      If there are multiple versions of a package, this

     

       
290
       
+
       
      <emphasis>should</emphasis> be reflected in the variable names in

     

       
291
       
+
       
      <filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname>

     

       
292
       
+
       
      and <varname>json-c-0-11</varname>. If there is an obvious “default”

     

       
293
       
+
       
      version, make an attribute like <literal>json-c = json-c-0-9;</literal>.

     

       
294
       
+
       
      See also <xref linkend="sec-versioning" />

     

       
295
       
 
       
     </para>

     

       
296
       
 
       
    </listitem>

     

       
297
       
 
       
   </itemizedlist>

     
···

       
809
       
 
       


     

       
810
       
 
       
  <para>

     

       
811
       
 
       
   There are multiple ways to fetch a package source in nixpkgs. The general

     

       
812
       
+
       
   guideline is that you should package reproducible sources with a high degree

     

       
813
       
+
       
   of availability. Right now there is only one fetcher which has mirroring

     

       
814
       
 
       
   support and that is <literal>fetchurl</literal>. Note that you should also

     

       
815
       
 
       
   prefer protocols which have a corresponding proxy environment variable.

     

       
816
       
 
       
  </para>

     
···

       
864
       
 
       
}

     

       
865
       
 
       
</programlisting>

     

       
866
       
 
       
      Find the value to put as <literal>sha256</literal> by running

     

       
867
       
+
       
      <literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c

     

       
868
       
+
       
      nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS

     

       
869
       
+
       
      nix</literal> or <literal>nix-prefetch-url --unpack

     

       
870
       
+
       
      https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.

     

       
871
       
 
       
     </para>

     

       
872
       
 
       
    </listitem>

     

       
873
       
 
       
   </itemizedlist>

     
···

       
950
       
 
       
     would be replace hash with a fake one and rebuild. Nix build will fail and

     

       
951
       
 
       
     error message will contain desired hash.

     

       
952
       
 
       
    </para>

     

       
953
       
+
       
    <warning>

     

       
954
       
+
       
     <para>

     

       
955
       
+
       
      This method has security problems. Check below for details.

     

       
956
       
+
       
     </para>

     

       
957
       
+
       
    </warning>

     

       
958
       
 
       
   </listitem>

     

       
959
       
 
       
  </orderedlist>

     

       
960
       
 
       


     

       
961
       
 
       
  <section xml:id="sec-source-hashes-security">

     

       
962
       
 
       
   <title>Obtaining hashes securely</title>

     

       
963
       
+
       


     

       
964
       
 
       
   <para>

     

       
965
       
+
       
    Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead

     

       
966
       
+
       
    of fetching source you can fetch malware, and instead of source hash you

     

       
967
       
+
       
    get hash of malware. Here are security considerations for this scenario:

     

       
968
       
 
       
   </para>

     

       
969
       
+
       


     

       
970
       
 
       
   <itemizedlist>

     

       
971
       
 
       
    <listitem>

     

       
972
       
 
       
     <para>

     
···

       
975
       
 
       
    </listitem>

     

       
976
       
 
       
    <listitem>

     

       
977
       
 
       
     <para>

     

       
978
       
+
       
      hashes from upstream (in method 3) should be obtained via secure

     

       
979
       
+
       
      protocol;

     

       
980
       
 
       
     </para>

     

       
981
       
 
       
    </listitem>

     

       
982
       
 
       
    <listitem>

     
···

       
986
       
 
       
    </listitem>

     

       
987
       
 
       
    <listitem>

     

       
988
       
 
       
     <para>

     

       
989
       
+
       
      <literal>https://</literal> URLs are not secure in method 5. When

     

       
990
       
+
       
      obtaining hashes with fake hash method, TLS checks are disabled. So

     

       
991
       
+
       
      refetch source hash from several different networks to exclude MITM

     

       
992
       
+
       
      scenario. Alternatively, use fake hash method to make Nix error, but

     

       
993
       
+
       
      instead of extracting hash from error, extract

     

       
994
       
+
       
      <literal>https://</literal> URL and prefetch it with method 1.

     

       
995
       
 
       
     </para>

     

       
996
       
 
       
    </listitem>

     

       
997
       
 
       
   </itemizedlist>

     

···

       
132
       
 
       
  </itemizedlist>

     

       
133
       
 
       


     

       
134
       
 
       
  <para>

     

       
135
       
-
       
   The difference between a package being unsupported on some system and

     

       
136
       
-
       
   being broken is admittedly a bit fuzzy. If a program

     

       
137
       
-
       
   <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the

     

       
138
       
-
       
   platform should be included in <literal>meta.platforms</literal>, but marked

     

       
139
       
-
       
   as broken with e.g. <literal>meta.broken =

     

       
140
       
-
       
   !hostPlatform.isWindows</literal>. Of course, this begs the question of what

     

       
141
       
-
       
   "ought" means exactly. That is left to the package maintainer.

     

       
142
       
 
       
  </para>

     

       
143
       
 
       
 </section>

     

       
144
       
 
       
 <section xml:id="sec-allow-unfree">

     
···

       
175
       
 
       
</programlisting>

     

       
176
       
 
       
    </para>

     

       
177
       
 
       
    <para>

     

       
178
       
-
       
     For a more useful example, try the following. This configuration

     

       
179
       
-
       
     only allows unfree packages named flash player and visual studio

     

       
180
       
-
       
     code:

     

       
181
       
 
       
<programlisting>

     

       
182
       
 
       
{

     

       
183
       
 
       
  allowUnfreePredicate = (pkg: builtins.elem

     

···

       
132
       
 
       
  </itemizedlist>

     

       
133
       
 
       


     

       
134
       
 
       
  <para>

     

       
135
       
+
       
   The difference between a package being unsupported on some system and being

     

       
136
       
+
       
   broken is admittedly a bit fuzzy. If a program <emphasis>ought</emphasis> to

     

       
137
       
+
       
   work on a certain platform, but doesn't, the platform should be included in

     

       
138
       
+
       
   <literal>meta.platforms</literal>, but marked as broken with e.g.

     

       
139
       
+
       
   <literal>meta.broken = !hostPlatform.isWindows</literal>. Of course, this

     

       
140
       
+
       
   begs the question of what "ought" means exactly. That is left to the package

     

       
141
       
+
       
   maintainer.

     

       
142
       
 
       
  </para>

     

       
143
       
 
       
 </section>

     

       
144
       
 
       
 <section xml:id="sec-allow-unfree">

     
···

       
175
       
 
       
</programlisting>

     

       
176
       
 
       
    </para>

     

       
177
       
 
       
    <para>

     

       
178
       
+
       
     For a more useful example, try the following. This configuration only

     

       
179
       
+
       
     allows unfree packages named flash player and visual studio code:

     

       
0
       
 
       

     

       
180
       
 
       
<programlisting>

     

       
181
       
 
       
{

     

       
182
       
 
       
  allowUnfreePredicate = (pkg: builtins.elem

     

···

       
6
       
 
       
  <title>Introduction</title>

     

       
7
       
 
       


     

       
8
       
 
       
  <para>

     

       
9
       
-
       
   "Cross-compilation" means compiling a program on one machine for another type

     

       
10
       
-
       
   of machine. For example, a typical use of cross-compilation is to compile

     

       
11
       
-
       
   programs for embedded devices. These devices often don't have the computing

     

       
12
       
-
       
   power and memory to compile their own programs. One might think that

     

       
13
       
-
       
   cross-compilation is a fairly niche concern. However, there are significant

     

       
14
       
-
       
   advantages to rigorously distinguishing between build-time and run-time

     

       
15
       
-
       
   environments! This applies even when one is developing and deploying on the

     

       
16
       
-
       
   same machine. Nixpkgs is increasingly adopting the opinion that packages

     

       
17
       
-
       
   should be written with cross-compilation in mind, and nixpkgs should evaluate

     

       
18
       
-
       
   in a similar way (by minimizing cross-compilation-specific special cases)

     

       
19
       
-
       
   whether or not one is cross-compiling.

     

       
20
       
 
       
  </para>

     

       
21
       
 
       


     

       
22
       
 
       
  <para>

     
···

       
34
       
 
       
   <title>Platform parameters</title>

     

       
35
       
 
       


     

       
36
       
 
       
   <para>

     

       
37
       
-
       
     Nixpkgs follows the <link

     

       
0
       
 
       

     

       
38
       
 
       
     xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions

     

       
39
       
-
       
     of GNU autoconf</link>. We distinguish between 3 types of platforms when

     

       
40
       
-
       
     building a derivation: <wordasword>build</wordasword>,

     

       
41
       
-
       
     <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In

     

       
42
       
-
       
     summary, <wordasword>build</wordasword> is the platform on which a package

     

       
43
       
-
       
     is being built, <wordasword>host</wordasword> is the platform on which it

     

       
44
       
-
       
     will run. The third attribute, <wordasword>target</wordasword>, is relevant

     

       
45
       
-
       
     only for certain specific compilers and build tools.

     

       
46
       
 
       
   </para>

     

       
47
       
 
       


     

       
48
       
 
       
   <para>

     
···

       
95
       
 
       
       The build process of certain compilers is written in such a way that the

     

       
96
       
 
       
       compiler resulting from a single build can itself only produce binaries

     

       
97
       
 
       
       for a single platform. The task of specifying this single "target

     

       
98
       
-
       
       platform" is thus pushed to build time of the compiler. The root cause of

     

       
99
       
-
       
       this is that the compiler (which will be run on the host) and the standard

     

       
100
       
-
       
       library/runtime (which will be run on the target) are built by a single

     

       
101
       
-
       
       build process.

     

       
102
       
 
       
      </para>

     

       
103
       
 
       
      <para>

     

       
104
       
 
       
       There is no fundamental need to think about a single target ahead of

     
···

       
136
       
 
       
       This is a two-component shorthand for the platform. Examples of this

     

       
137
       
 
       
       would be "x86_64-darwin" and "i686-linux"; see

     

       
138
       
 
       
       <literal>lib.systems.doubles</literal> for more. The first component

     

       
139
       
-
       
       corresponds to the CPU architecture of the platform and the second to the

     

       
140
       
-
       
       operating system of the platform (<literal>[cpu]-[os]</literal>). This

     

       
141
       
-
       
       format has built-in support in Nix, such as the

     

       
142
       
 
       
       <varname>builtins.currentSystem</varname> impure string.

     

       
143
       
 
       
      </para>

     

       
144
       
 
       
     </listitem>

     
···

       
149
       
 
       
     </term>

     

       
150
       
 
       
     <listitem>

     

       
151
       
 
       
      <para>

     

       
152
       
-
       
       This is a 3- or 4- component shorthand for the platform. Examples of this

     

       
153
       
-
       
       would be <literal>x86_64-unknown-linux-gnu</literal> and

     

       
154
       
 
       
       <literal>aarch64-apple-darwin14</literal>. This is a standard format

     

       
155
       
 
       
       called the "LLVM target triple", as they are pioneered by LLVM. In the

     

       
156
       
 
       
       4-part form, this corresponds to

     

       
157
       
 
       
       <literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly

     

       
158
       
-
       
       more informative than the "Nix host double", as the previous format could

     

       
159
       
-
       
       analogously be termed. This needs a better name than

     

       
160
       
 
       
       <varname>config</varname>!

     

       
161
       
 
       
      </para>

     

       
162
       
 
       
     </listitem>

     
···

       
167
       
 
       
     </term>

     

       
168
       
 
       
     <listitem>

     

       
169
       
 
       
      <para>

     

       
170
       
-
       
       This is a Nix representation of a parsed LLVM target triple

     

       
171
       
-
       
       with white-listed components. This can be specified directly,

     

       
172
       
-
       
       or actually parsed from the <varname>config</varname>. See

     

       
173
       
-
       
       <literal>lib.systems.parse</literal> for the exact

     

       
174
       
-
       
       representation.

     

       
175
       
 
       
      </para>

     

       
176
       
 
       
     </listitem>

     

       
177
       
 
       
    </varlistentry>

     
···

       
253
       
 
       
   <para>

     

       
254
       
 
       
    Some examples will make this clearer. If a package is being built with a

     

       
255
       
 
       
    <literal>(build, host, target)</literal> platform triple of <literal>(foo,

     

       
256
       
-
       
    bar, bar)</literal>, then its build-time dependencies would have a triple of

     

       
257
       
-
       
    <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis>

     

       
258
       
-
       
    build-time dependencies would have a triple of <literal>(foo, foo,

     

       
259
       
-
       
    foo)</literal>. In other words, it should take two "rounds" of following

     

       
260
       
-
       
    build-time dependency edges before one reaches a fixed point where, by the

     

       
261
       
-
       
    sliding window principle, the platform triple no longer changes. Indeed,

     

       
262
       
-
       
    this happens with cross-compilation, where only rounds of native

     

       
263
       
-
       
    dependencies starting with the second necessarily coincide with native

     

       
264
       
-
       
    packages.

     

       
265
       
 
       
   </para>

     

       
266
       
 
       


     

       
267
       
 
       
   <note>

     
···

       
273
       
 
       
   </note>

     

       
274
       
 
       


     

       
275
       
 
       
   <para>

     

       
276
       
-
       
    How does this work in practice? Nixpkgs is now structured so that build-time

     

       
277
       
-
       
    dependencies are taken from <varname>buildPackages</varname>, whereas

     

       
278
       
-
       
    run-time dependencies are taken from the top level attribute set. For

     

       
279
       
-
       
    example, <varname>buildPackages.gcc</varname> should be used at build-time,

     

       
280
       
-
       
    while <varname>gcc</varname> should be used at run-time. Now, for most of

     

       
281
       
-
       
    Nixpkgs's history, there was no <varname>buildPackages</varname>, and most

     

       
282
       
-
       
    packages have not been refactored to use it explicitly. Instead, one can use

     

       
283
       
-
       
    the six (<emphasis>gasp</emphasis>) attributes used for specifying

     

       
284
       
-
       
    dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>. We

     

       
285
       
-
       
    "splice" together the run-time and build-time package sets with

     

       
286
       
-
       
    <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for

     

       
287
       
-
       
    each of four attributes pulls the right derivation out. This splicing can be

     

       
288
       
-
       
    skipped when not cross-compiling as the package sets are the same, but is a

     

       
289
       
-
       
    bit slow for cross-compiling. Because of this, a best-of-both-worlds

     

       
290
       
-
       
    solution is in the works with no splicing or explicit access of

     

       
291
       
-
       
    <varname>buildPackages</varname> needed. For now, feel free to use either

     

       
292
       
-
       
    method.

     

       
0
       
 
       

     

       
293
       
 
       
   </para>

     

       
294
       
 
       


     

       
295
       
 
       
   <note>

     
···

       
311
       
 
       
    should be answered here. Ideally, the information above is exhaustive, so

     

       
312
       
 
       
    this section cannot provide any new information, but it is ludicrous and

     

       
313
       
 
       
    cruel to expect everyone to spend effort working through the interaction of

     

       
314
       
-
       
    many features just to figure out the same answer to the same common problem.

     

       
315
       
-
       
    Feel free to add to this list!

     

       
316
       
 
       
   </para>

     

       
317
       
 
       


     

       
318
       
 
       
   <qandaset>

     
···

       
434
       
 
       
   build plan or package set. A simple "build vs deploy" dichotomy is adequate:

     

       
435
       
 
       
   the sliding window principle described in the previous section shows how to

     

       
436
       
 
       
   interpolate between the these two "end points" to get the 3 platform triple

     

       
437
       
-
       
   for each bootstrapping stage. That means for any package a given package set,

     

       
438
       
-
       
   even those not bound on the top level but only reachable via dependencies or

     

       
439
       
-
       
   <varname>buildPackages</varname>, the three platforms will be defined as one

     

       
440
       
-
       
   of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the

     

       
441
       
-
       
   former replacing the latter as one traverses build-time dependencies. A last

     

       
442
       
-
       
   simple difference is that <varname>crossSystem</varname> should be null when

     

       
443
       
-
       
   one doesn't want to cross-compile, while the <varname>*Platform</varname>s

     

       
444
       
-
       
   are always non-null. <varname>localSystem</varname> is always non-null.

     

       
0
       
 
       

     

       
445
       
 
       
  </para>

     

       
446
       
 
       
 </section>

     

       
447
       
 
       
<!--============================================================-->

     
···

       
455
       
 
       
  <note>

     

       
456
       
 
       
   <para>

     

       
457
       
 
       
    If one explores Nixpkgs, they will see derivations with names like

     

       
458
       
-
       
    <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is a

     

       
459
       
-
       
    holdover from before we properly distinguished between the host and target

     

       
460
       
-
       
    platforms—the derivation with "Cross" in the name covered the <literal>build

     

       
461
       
-
       
    = host != target</literal> case, while the other covered the <literal>host =

     

       
462
       
-
       
    target</literal>, with build platform the same or not based on whether one

     

       
463
       
-
       
    was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>.

     

       
464
       
-
       
    This ugliness will disappear soon.

     

       
465
       
 
       
   </para>

     

       
466
       
 
       
  </note>

     

       
467
       
 
       
 </section>

     

···

       
6
       
 
       
  <title>Introduction</title>

     

       
7
       
 
       


     

       
8
       
 
       
  <para>

     

       
9
       
+
       
   "Cross-compilation" means compiling a program on one machine for another

     

       
10
       
+
       
   type of machine. For example, a typical use of cross-compilation is to

     

       
11
       
+
       
   compile programs for embedded devices. These devices often don't have the

     

       
12
       
+
       
   computing power and memory to compile their own programs. One might think

     

       
13
       
+
       
   that cross-compilation is a fairly niche concern. However, there are

     

       
14
       
+
       
   significant advantages to rigorously distinguishing between build-time and

     

       
15
       
+
       
   run-time environments! This applies even when one is developing and

     

       
16
       
+
       
   deploying on the same machine. Nixpkgs is increasingly adopting the opinion

     

       
17
       
+
       
   that packages should be written with cross-compilation in mind, and nixpkgs

     

       
18
       
+
       
   should evaluate in a similar way (by minimizing cross-compilation-specific

     

       
19
       
+
       
   special cases) whether or not one is cross-compiling.

     

       
20
       
 
       
  </para>

     

       
21
       
 
       


     

       
22
       
 
       
  <para>

     
···

       
34
       
 
       
   <title>Platform parameters</title>

     

       
35
       
 
       


     

       
36
       
 
       
   <para>

     

       
37
       
+
       
    Nixpkgs follows the

     

       
38
       
+
       
    <link

     

       
39
       
 
       
     xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions

     

       
40
       
+
       
    of GNU autoconf</link>. We distinguish between 3 types of platforms when

     

       
41
       
+
       
    building a derivation: <wordasword>build</wordasword>,

     

       
42
       
+
       
    <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In

     

       
43
       
+
       
    summary, <wordasword>build</wordasword> is the platform on which a package

     

       
44
       
+
       
    is being built, <wordasword>host</wordasword> is the platform on which it

     

       
45
       
+
       
    will run. The third attribute, <wordasword>target</wordasword>, is relevant

     

       
46
       
+
       
    only for certain specific compilers and build tools.

     

       
47
       
 
       
   </para>

     

       
48
       
 
       


     

       
49
       
 
       
   <para>

     
···

       
96
       
 
       
       The build process of certain compilers is written in such a way that the

     

       
97
       
 
       
       compiler resulting from a single build can itself only produce binaries

     

       
98
       
 
       
       for a single platform. The task of specifying this single "target

     

       
99
       
+
       
       platform" is thus pushed to build time of the compiler. The root cause

     

       
100
       
+
       
       of this is that the compiler (which will be run on the host) and the

     

       
101
       
+
       
       standard library/runtime (which will be run on the target) are built by

     

       
102
       
+
       
       a single build process.

     

       
103
       
 
       
      </para>

     

       
104
       
 
       
      <para>

     

       
105
       
 
       
       There is no fundamental need to think about a single target ahead of

     
···

       
137
       
 
       
       This is a two-component shorthand for the platform. Examples of this

     

       
138
       
 
       
       would be "x86_64-darwin" and "i686-linux"; see

     

       
139
       
 
       
       <literal>lib.systems.doubles</literal> for more. The first component

     

       
140
       
+
       
       corresponds to the CPU architecture of the platform and the second to

     

       
141
       
+
       
       the operating system of the platform (<literal>[cpu]-[os]</literal>).

     

       
142
       
+
       
       This format has built-in support in Nix, such as the

     

       
143
       
 
       
       <varname>builtins.currentSystem</varname> impure string.

     

       
144
       
 
       
      </para>

     

       
145
       
 
       
     </listitem>

     
···

       
150
       
 
       
     </term>

     

       
151
       
 
       
     <listitem>

     

       
152
       
 
       
      <para>

     

       
153
       
+
       
       This is a 3- or 4- component shorthand for the platform. Examples of

     

       
154
       
+
       
       this would be <literal>x86_64-unknown-linux-gnu</literal> and

     

       
155
       
 
       
       <literal>aarch64-apple-darwin14</literal>. This is a standard format

     

       
156
       
 
       
       called the "LLVM target triple", as they are pioneered by LLVM. In the

     

       
157
       
 
       
       4-part form, this corresponds to

     

       
158
       
 
       
       <literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly

     

       
159
       
+
       
       more informative than the "Nix host double", as the previous format

     

       
160
       
+
       
       could analogously be termed. This needs a better name than

     

       
161
       
 
       
       <varname>config</varname>!

     

       
162
       
 
       
      </para>

     

       
163
       
 
       
     </listitem>

     
···

       
168
       
 
       
     </term>

     

       
169
       
 
       
     <listitem>

     

       
170
       
 
       
      <para>

     

       
171
       
+
       
       This is a Nix representation of a parsed LLVM target triple with

     

       
172
       
+
       
       white-listed components. This can be specified directly, or actually

     

       
173
       
+
       
       parsed from the <varname>config</varname>. See

     

       
174
       
+
       
       <literal>lib.systems.parse</literal> for the exact representation.

     

       
0
       
 
       

     

       
175
       
 
       
      </para>

     

       
176
       
 
       
     </listitem>

     

       
177
       
 
       
    </varlistentry>

     
···

       
253
       
 
       
   <para>

     

       
254
       
 
       
    Some examples will make this clearer. If a package is being built with a

     

       
255
       
 
       
    <literal>(build, host, target)</literal> platform triple of <literal>(foo,

     

       
256
       
+
       
    bar, bar)</literal>, then its build-time dependencies would have a triple

     

       
257
       
+
       
    of <literal>(foo, foo, bar)</literal>, and <emphasis>those

     

       
258
       
+
       
    packages'</emphasis> build-time dependencies would have a triple of

     

       
259
       
+
       
    <literal>(foo, foo, foo)</literal>. In other words, it should take two

     

       
260
       
+
       
    "rounds" of following build-time dependency edges before one reaches a

     

       
261
       
+
       
    fixed point where, by the sliding window principle, the platform triple no

     

       
262
       
+
       
    longer changes. Indeed, this happens with cross-compilation, where only

     

       
263
       
+
       
    rounds of native dependencies starting with the second necessarily coincide

     

       
264
       
+
       
    with native packages.

     

       
265
       
 
       
   </para>

     

       
266
       
 
       


     

       
267
       
 
       
   <note>

     
···

       
273
       
 
       
   </note>

     

       
274
       
 
       


     

       
275
       
 
       
   <para>

     

       
276
       
+
       
    How does this work in practice? Nixpkgs is now structured so that

     

       
277
       
+
       
    build-time dependencies are taken from <varname>buildPackages</varname>,

     

       
278
       
+
       
    whereas run-time dependencies are taken from the top level attribute set.

     

       
279
       
+
       
    For example, <varname>buildPackages.gcc</varname> should be used at

     

       
280
       
+
       
    build-time, while <varname>gcc</varname> should be used at run-time. Now,

     

       
281
       
+
       
    for most of Nixpkgs's history, there was no

     

       
282
       
+
       
    <varname>buildPackages</varname>, and most packages have not been

     

       
283
       
+
       
    refactored to use it explicitly. Instead, one can use the six

     

       
284
       
+
       
    (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as

     

       
285
       
+
       
    documented in <xref linkend="ssec-stdenv-dependencies"/>. We "splice"

     

       
286
       
+
       
    together the run-time and build-time package sets with

     

       
287
       
+
       
    <varname>callPackage</varname>, and then <varname>mkDerivation</varname>

     

       
288
       
+
       
    for each of four attributes pulls the right derivation out. This splicing

     

       
289
       
+
       
    can be skipped when not cross-compiling as the package sets are the same,

     

       
290
       
+
       
    but is a bit slow for cross-compiling. Because of this, a

     

       
291
       
+
       
    best-of-both-worlds solution is in the works with no splicing or explicit

     

       
292
       
+
       
    access of <varname>buildPackages</varname> needed. For now, feel free to

     

       
293
       
+
       
    use either method.

     

       
294
       
 
       
   </para>

     

       
295
       
 
       


     

       
296
       
 
       
   <note>

     
···

       
312
       
 
       
    should be answered here. Ideally, the information above is exhaustive, so

     

       
313
       
 
       
    this section cannot provide any new information, but it is ludicrous and

     

       
314
       
 
       
    cruel to expect everyone to spend effort working through the interaction of

     

       
315
       
+
       
    many features just to figure out the same answer to the same common

     

       
316
       
+
       
    problem. Feel free to add to this list!

     

       
317
       
 
       
   </para>

     

       
318
       
 
       


     

       
319
       
 
       
   <qandaset>

     
···

       
435
       
 
       
   build plan or package set. A simple "build vs deploy" dichotomy is adequate:

     

       
436
       
 
       
   the sliding window principle described in the previous section shows how to

     

       
437
       
 
       
   interpolate between the these two "end points" to get the 3 platform triple

     

       
438
       
+
       
   for each bootstrapping stage. That means for any package a given package

     

       
439
       
+
       
   set, even those not bound on the top level but only reachable via

     

       
440
       
+
       
   dependencies or <varname>buildPackages</varname>, the three platforms will

     

       
441
       
+
       
   be defined as one of <varname>localSystem</varname> or

     

       
442
       
+
       
   <varname>crossSystem</varname>, with the former replacing the latter as one

     

       
443
       
+
       
   traverses build-time dependencies. A last simple difference is that

     

       
444
       
+
       
   <varname>crossSystem</varname> should be null when one doesn't want to

     

       
445
       
+
       
   cross-compile, while the <varname>*Platform</varname>s are always non-null.

     

       
446
       
+
       
   <varname>localSystem</varname> is always non-null.

     

       
447
       
 
       
  </para>

     

       
448
       
 
       
 </section>

     

       
449
       
 
       
<!--============================================================-->

     
···

       
457
       
 
       
  <note>

     

       
458
       
 
       
   <para>

     

       
459
       
 
       
    If one explores Nixpkgs, they will see derivations with names like

     

       
460
       
+
       
    <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is

     

       
461
       
+
       
    a holdover from before we properly distinguished between the host and

     

       
462
       
+
       
    target platforms—the derivation with "Cross" in the name covered the

     

       
463
       
+
       
    <literal>build = host != target</literal> case, while the other covered the

     

       
464
       
+
       
    <literal>host = target</literal>, with build platform the same or not based

     

       
465
       
+
       
    on whether one was using its <literal>.nativeDrv</literal> or

     

       
466
       
+
       
    <literal>.crossDrv</literal>. This ugliness will disappear soon.

     

       
467
       
 
       
   </para>

     

       
468
       
 
       
  </note>

     

       
469
       
 
       
 </section>

     

···

       
5
       
 
       
 <title>pkgs.appimageTools</title>

     

       
6
       
 
       


     

       
7
       
 
       
 <para>

     

       
8
       
-
       
   <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping

     

       
9
       
-
       
   <link xlink:href="https://appimage.org/">AppImage</link> files.

     

       
10
       
-
       


     

       
11
       
-
       
   They are meant to be used if traditional packaging from source is infeasible, or it would take too long.

     

       
12
       
-
       
   To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well.

     

       
13
       
 
       
 </para>

     

       
14
       
 
       


     

       
15
       
 
       
 <warning>

     
···

       
19
       
 
       
  </para>

     

       
20
       
 
       
 </warning>

     

       
21
       
 
       


     

       
22
       
-
       


     

       
23
       
 
       
 <section xml:id="ssec-pkgs-appimageTools-formats">

     

       
24
       
 
       
  <title>AppImage formats</title>

     

       
25
       
 
       


     

       
26
       
 
       
  <para>

     

       
27
       
 
       
   There are different formats for AppImages, see

     

       
28
       
-
       
   <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details.

     

       
0
       
 
       

     

       
29
       
 
       
  </para>

     

       
30
       
 
       


     

       
31
       
 
       
  <itemizedlist>

     
···

       
34
       
 
       
     Type 1 images are ISO 9660 files that are also ELF executables.

     

       
35
       
 
       
    </para>

     

       
36
       
 
       
   </listitem>

     

       
37
       
-
       


     

       
38
       
 
       
   <listitem>

     

       
39
       
 
       
    <para>

     

       
40
       
 
       
     Type 2 images are ELF executables with an appended filesystem.

     
···

       
46
       
 
       
   They can be told apart with <command>file -k</command>:

     

       
47
       
 
       
  </para>

     

       
48
       
 
       


     

       
49
       
-
       
  <screen>

     

       
50
       
 
       
<prompt>$ </prompt>file -k type1.AppImage

     

       
51
       
 
       
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,

     

       
52
       
 
       
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data

     
···

       
56
       
 
       
  </screen>

     

       
57
       
 
       


     

       
58
       
 
       
  <para>

     

       
59
       
-
       
   Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not.

     

       
0
       
 
       

     

       
60
       
 
       
  </para>

     

       
61
       
 
       
 </section>

     

       
62
       
 
       


     
···

       
64
       
 
       
  <title>Wrapping</title>

     

       
65
       
 
       


     

       
66
       
 
       
  <para>

     

       
67
       
-
       
    Depending on the type of AppImage you're wrapping, you'll have to use

     

       
68
       
-
       
    <varname>wrapType1</varname> or <varname>wrapType2</varname>.

     

       
69
       
 
       
  </para>

     

       
70
       
 
       


     

       
71
       
-
       


     

       
72
       
-
       
  <programlisting>

     

       
73
       
 
       
appimageTools.wrapType2 { # or wrapType1

     

       
74
       
 
       
  name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />

     

       
75
       
 
       
  src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />

     
···

       
79
       
 
       
  extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />

     

       
80
       
 
       
}</programlisting>

     

       
81
       
 
       


     

       
82
       
-
       


     

       
83
       
 
       
  <calloutlist>

     

       
84
       
 
       
   <callout arearefs='ex-appimageTools-wrapping-1'>

     

       
85
       
 
       
    <para>

     
···

       
93
       
 
       
   </callout>

     

       
94
       
 
       
   <callout arearefs='ex-appimageTools-wrapping-2'>

     

       
95
       
 
       
    <para>

     

       
96
       
-
       
      <varname>extraPkgs</varname> allows you to pass a function to include additional packages

     

       
97
       
-
       
      inside the FHS environment your AppImage is going to run in.

     

       
98
       
-
       


     

       
99
       
-
       
      There are a few ways to learn which dependencies an application needs:

     

       
100
       
-
       


     

       
101
       
-
       
      <itemizedlist>

     

       
102
       
-
       
       <listitem>

     

       
103
       
-
       
        <para>

     

       
104
       
-
       
         Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables.

     

       
105
       
-
       
         This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.

     

       
106
       
-
       
        </para>

     

       
107
       
-
       
       </listitem>

     

       
108
       
-
       


     

       
109
       
-
       
       <listitem>

     

       
110
       
-
       
        <para>

     

       
111
       
-
       
         Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found.

     

       
112
       
-
       
        </para>

     

       
113
       
-
       
       </listitem>

     

       
114
       
-
       
      </itemizedlist>

     

       
115
       
-
       


     

       
116
       
 
       
    </para>

     

       
117
       
 
       
   </callout>

     

       
118
       
 
       
  </calloutlist>

     

       
119
       
-
       


     

       
120
       
 
       
 </section>

     

       
121
       
 
       
</section>

     

···

       
5
       
 
       
 <title>pkgs.appimageTools</title>

     

       
6
       
 
       


     

       
7
       
 
       
 <para>

     

       
8
       
+
       
  <varname>pkgs.appimageTools</varname> is a set of functions for extracting

     

       
9
       
+
       
  and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files.

     

       
10
       
+
       
  They are meant to be used if traditional packaging from source is infeasible,

     

       
11
       
+
       
  or it would take too long. To quickly run an AppImage file,

     

       
12
       
+
       
  <literal>pkgs.appimage-run</literal> can be used as well.

     

       
13
       
 
       
 </para>

     

       
14
       
 
       


     

       
15
       
 
       
 <warning>

     
···

       
19
       
 
       
  </para>

     

       
20
       
 
       
 </warning>

     

       
21
       
 
       


     

       
0
       
 
       

     

       
22
       
 
       
 <section xml:id="ssec-pkgs-appimageTools-formats">

     

       
23
       
 
       
  <title>AppImage formats</title>

     

       
24
       
 
       


     

       
25
       
 
       
  <para>

     

       
26
       
 
       
   There are different formats for AppImages, see

     

       
27
       
+
       
   <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the

     

       
28
       
+
       
   specification</link> for details.

     

       
29
       
 
       
  </para>

     

       
30
       
 
       


     

       
31
       
 
       
  <itemizedlist>

     
···

       
34
       
 
       
     Type 1 images are ISO 9660 files that are also ELF executables.

     

       
35
       
 
       
    </para>

     

       
36
       
 
       
   </listitem>

     

       
0
       
 
       

     

       
37
       
 
       
   <listitem>

     

       
38
       
 
       
    <para>

     

       
39
       
 
       
     Type 2 images are ELF executables with an appended filesystem.

     
···

       
45
       
 
       
   They can be told apart with <command>file -k</command>:

     

       
46
       
 
       
  </para>

     

       
47
       
 
       


     

       
48
       
+
       
<screen>

     

       
49
       
 
       
<prompt>$ </prompt>file -k type1.AppImage

     

       
50
       
 
       
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,

     

       
51
       
 
       
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data

     
···

       
55
       
 
       
  </screen>

     

       
56
       
 
       


     

       
57
       
 
       
  <para>

     

       
58
       
+
       
   Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM

     

       
59
       
+
       
   filesystem</literal>, and the type 2 AppImage is not.

     

       
60
       
 
       
  </para>

     

       
61
       
 
       
 </section>

     

       
62
       
 
       


     
···

       
64
       
 
       
  <title>Wrapping</title>

     

       
65
       
 
       


     

       
66
       
 
       
  <para>

     

       
67
       
+
       
   Depending on the type of AppImage you're wrapping, you'll have to use

     

       
68
       
+
       
   <varname>wrapType1</varname> or <varname>wrapType2</varname>.

     

       
69
       
 
       
  </para>

     

       
70
       
 
       


     

       
71
       
+
       
<programlisting>

     

       
0
       
 
       

     

       
72
       
 
       
appimageTools.wrapType2 { # or wrapType1

     

       
73
       
 
       
  name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />

     

       
74
       
 
       
  src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />

     
···

       
78
       
 
       
  extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />

     

       
79
       
 
       
}</programlisting>

     

       
80
       
 
       


     

       
0
       
 
       

     

       
81
       
 
       
  <calloutlist>

     

       
82
       
 
       
   <callout arearefs='ex-appimageTools-wrapping-1'>

     

       
83
       
 
       
    <para>

     
···

       
91
       
 
       
   </callout>

     

       
92
       
 
       
   <callout arearefs='ex-appimageTools-wrapping-2'>

     

       
93
       
 
       
    <para>

     

       
94
       
+
       
     <varname>extraPkgs</varname> allows you to pass a function to include

     

       
95
       
+
       
     additional packages inside the FHS environment your AppImage is going to

     

       
96
       
+
       
     run in. There are a few ways to learn which dependencies an application

     

       
97
       
+
       
     needs:

     

       
98
       
+
       
     <itemizedlist>

     

       
99
       
+
       
      <listitem>

     

       
100
       
+
       
       <para>

     

       
101
       
+
       
        Looking through the extracted AppImage files, reading its scripts and

     

       
102
       
+
       
        running <command>patchelf</command> and <command>ldd</command> on its

     

       
103
       
+
       
        executables. This can also be done in <command>appimage-run</command>,

     

       
104
       
+
       
        by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.

     

       
105
       
+
       
       </para>

     

       
106
       
+
       
      </listitem>

     

       
107
       
+
       
      <listitem>

     

       
108
       
+
       
       <para>

     

       
109
       
+
       
        Running <command>strace -vfefile</command> on the wrapped executable,

     

       
110
       
+
       
        looking for libraries that can't be found.

     

       
111
       
+
       
       </para>

     

       
112
       
+
       
      </listitem>

     

       
113
       
+
       
     </itemizedlist>

     

       
114
       
 
       
    </para>

     

       
115
       
 
       
   </callout>

     

       
116
       
 
       
  </calloutlist>

     

       
0
       
 
       

     

       
117
       
 
       
 </section>

     

       
118
       
 
       
</section>

     

···

       
24
       
 
       


     

       
25
       
 
       
  <para>

     

       
26
       
 
       
   This function is analogous to the <command>docker build</command> command,

     

       
27
       
-
       
   in that it can be used to build a Docker-compatible repository tarball containing

     

       
28
       
-
       
   a single image with one or multiple layers. As such, the result is suitable

     

       
29
       
-
       
   for being loaded in Docker with <command>docker load</command>.

     

       
30
       
 
       
  </para>

     

       
31
       
 
       


     

       
32
       
 
       
  <para>

     
···

       
190
       
 
       
    By default <function>buildImage</function> will use a static date of one

     

       
191
       
 
       
    second past the UNIX Epoch. This allows <function>buildImage</function> to

     

       
192
       
 
       
    produce binary reproducible images. When listing images with

     

       
193
       
-
       
    <command>docker images</command>, the newly created images will be

     

       
194
       
-
       
    listed like this:

     

       
195
       
 
       
   </para>

     

       
196
       
 
       
<screen><![CDATA[

     

       
197
       
 
       
$ docker images

     
···

       
402
       
 
       


     

       
403
       
 
       
  <para>

     

       
404
       
 
       
   This function is analogous to the <command>docker pull</command> command, in

     

       
405
       
-
       
   that it can be used to pull a Docker image from a Docker registry. By default

     

       
406
       
-
       
   <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull

     

       
407
       
-
       
   images.

     

       
408
       
 
       
  </para>

     

       
409
       
 
       


     

       
410
       
 
       
  <para>

     
···

       
484
       
 
       


     

       
485
       
 
       
  <para>

     

       
486
       
 
       
   This function is analogous to the <command>docker export</command> command,

     

       
487
       
-
       
   in that it can be used to flatten a Docker image that contains multiple layers. It

     

       
488
       
-
       
   is in fact the result of the merge of all the layers of the image. As such,

     

       
489
       
-
       
   the result is suitable for being imported in Docker with <command>docker

     

       
490
       
-
       
   import</command>.

     

       
491
       
 
       
  </para>

     

       
492
       
 
       


     

       
493
       
 
       
  <note>

     

···

       
24
       
 
       


     

       
25
       
 
       
  <para>

     

       
26
       
 
       
   This function is analogous to the <command>docker build</command> command,

     

       
27
       
+
       
   in that it can be used to build a Docker-compatible repository tarball

     

       
28
       
+
       
   containing a single image with one or multiple layers. As such, the result

     

       
29
       
+
       
   is suitable for being loaded in Docker with <command>docker load</command>.

     

       
30
       
 
       
  </para>

     

       
31
       
 
       


     

       
32
       
 
       
  <para>

     
···

       
190
       
 
       
    By default <function>buildImage</function> will use a static date of one

     

       
191
       
 
       
    second past the UNIX Epoch. This allows <function>buildImage</function> to

     

       
192
       
 
       
    produce binary reproducible images. When listing images with

     

       
193
       
+
       
    <command>docker images</command>, the newly created images will be listed

     

       
194
       
+
       
    like this:

     

       
195
       
 
       
   </para>

     

       
196
       
 
       
<screen><![CDATA[

     

       
197
       
 
       
$ docker images

     
···

       
402
       
 
       


     

       
403
       
 
       
  <para>

     

       
404
       
 
       
   This function is analogous to the <command>docker pull</command> command, in

     

       
405
       
+
       
   that it can be used to pull a Docker image from a Docker registry. By

     

       
406
       
+
       
   default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used

     

       
407
       
+
       
   to pull images.

     

       
408
       
 
       
  </para>

     

       
409
       
 
       


     

       
410
       
 
       
  <para>

     
···

       
484
       
 
       


     

       
485
       
 
       
  <para>

     

       
486
       
 
       
   This function is analogous to the <command>docker export</command> command,

     

       
487
       
+
       
   in that it can be used to flatten a Docker image that contains multiple

     

       
488
       
+
       
   layers. It is in fact the result of the merge of all the layers of the

     

       
489
       
+
       
   image. As such, the result is suitable for being imported in Docker with

     

       
490
       
+
       
   <command>docker import</command>.

     

       
491
       
 
       
  </para>

     

       
492
       
 
       


     

       
493
       
 
       
  <note>

     

···

       
5
       
 
       
 <title>Fetcher functions</title>

     

       
6
       
 
       


     

       
7
       
 
       
 <para>

     

       
8
       
-
       
   When using Nix, you will frequently need to download source code

     

       
9
       
-
       
   and other files from the internet. Nixpkgs comes with a few helper

     

       
10
       
-
       
   functions that allow you to fetch fixed-output derivations in a

     

       
11
       
-
       
   structured way.

     

       
12
       
 
       
 </para>

     

       
13
       
 
       


     

       
14
       
 
       
 <para>

     

       
15
       
-
       
   The two fetcher primitives are <function>fetchurl</function> and

     

       
16
       
-
       
   <function>fetchzip</function>. Both of these have two required

     

       
17
       
-
       
   arguments, a URL and a hash. The hash is typically

     

       
18
       
-
       
   <literal>sha256</literal>, although many more hash algorithms are

     

       
19
       
-
       
   supported. Nixpkgs contributors are currently recommended to use

     

       
20
       
-
       
   <literal>sha256</literal>. This hash will be used by Nix to

     

       
21
       
-
       
   identify your source. A typical usage of fetchurl is provided

     

       
22
       
-
       
   below.

     

       
23
       
 
       
 </para>

     

       
24
       
 
       


     

       
25
       
-
       
 <programlisting><![CDATA[

     

       
26
       
 
       
{ stdenv, fetchurl }:

     

       
27
       
 
       


     

       
28
       
 
       
stdenv.mkDerivation {

     
···

       
35
       
 
       
]]></programlisting>

     

       
36
       
 
       


     

       
37
       
 
       
 <para>

     

       
38
       
-
       
   The main difference between <function>fetchurl</function> and

     

       
39
       
-
       
   <function>fetchzip</function> is in how they store the contents.

     

       
40
       
-
       
   <function>fetchurl</function> will store the unaltered contents of

     

       
41
       
-
       
   the URL within the Nix store. <function>fetchzip</function> on the

     

       
42
       
-
       
   other hand will decompress the archive for you, making files and

     

       
43
       
-
       
   directories directly accessible in the future.

     

       
44
       
-
       
   <function>fetchzip</function> can only be used with archives.

     

       
45
       
-
       
   Despite the name, <function>fetchzip</function> is not limited to

     

       
46
       
-
       
   .zip files and can also be used with any tarball.

     

       
47
       
 
       
 </para>

     

       
48
       
 
       


     

       
49
       
 
       
 <para>

     

       
50
       
-
       
   <function>fetchpatch</function> works very similarly to

     

       
51
       
-
       
   <function>fetchurl</function> with the same arguments expected. It

     

       
52
       
-
       
   expects patch files as a source and and performs normalization on

     

       
53
       
-
       
   them before computing the checksum. For example it will remove

     

       
54
       
-
       
   comments or other unstable parts that are sometimes added by

     

       
55
       
-
       
   version control systems and can change over time.

     

       
56
       
 
       
 </para>

     

       
57
       
 
       


     

       
58
       
 
       
 <para>

     

       
59
       
-
       
   Other fetcher functions allow you to add source code directly from

     

       
60
       
-
       
   a VCS such as subversion or git. These are mostly straightforward

     

       
61
       
-
       
   names based on the name of the command used with the VCS system.

     

       
62
       
-
       
   Because they give you a working repository, they act most like

     

       
63
       
-
       
   <function>fetchzip</function>.

     

       
64
       
 
       
 </para>

     

       
65
       
 
       


     

       
66
       
 
       
 <variablelist>

     

       
67
       
-
       
   <varlistentry>

     

       
68
       
-
       
     <term>

     

       
69
       
-
       
      <literal>fetchsvn</literal>

     

       
70
       
-
       
     </term>

     

       
71
       
-
       
     <listitem>

     

       
72
       
-
       
      <para>

     

       
73
       
-
       
       Used with Subversion. Expects <literal>url</literal> to a

     

       
74
       
-
       
       Subversion directory, <literal>rev</literal>, and

     

       
75
       
-
       
       <literal>sha256</literal>.

     

       
76
       
-
       
      </para>

     

       
77
       
-
       
     </listitem>

     

       
78
       
-
       
   </varlistentry>

     

       
79
       
-
       
   <varlistentry>

     

       
80
       
-
       
     <term>

     

       
81
       
-
       
      <literal>fetchgit</literal>

     

       
82
       
-
       
     </term>

     

       
83
       
-
       
     <listitem>

     

       
84
       
-
       
      <para>

     

       
85
       
-
       
       Used with Git. Expects <literal>url</literal> to a Git repo,

     

       
86
       
-
       
       <literal>rev</literal>, and <literal>sha256</literal>.

     

       
87
       
-
       
       <literal>rev</literal> in this case can be full the git commit

     

       
88
       
-
       
       id (SHA1 hash) or a tag name like

     

       
89
       
-
       
       <literal>refs/tags/v1.0</literal>.

     

       
90
       
-
       
      </para>

     

       
91
       
-
       
     </listitem>

     

       
92
       
-
       
   </varlistentry>

     

       
93
       
-
       
   <varlistentry>

     

       
94
       
-
       
     <term>

     

       
95
       
-
       
      <literal>fetchfossil</literal>

     

       
96
       
-
       
     </term>

     

       
97
       
-
       
     <listitem>

     

       
98
       
-
       
      <para>

     

       
99
       
-
       
       Used with Fossil. Expects <literal>url</literal> to a Fossil

     

       
100
       
-
       
       archive, <literal>rev</literal>, and <literal>sha256</literal>.

     

       
101
       
-
       
      </para>

     

       
102
       
-
       
     </listitem>

     

       
103
       
-
       
   </varlistentry>

     

       
104
       
-
       
   <varlistentry>

     

       
105
       
-
       
     <term>

     

       
106
       
-
       
      <literal>fetchcvs</literal>

     

       
107
       
-
       
     </term>

     

       
108
       
-
       
     <listitem>

     

       
109
       
-
       
      <para>

     

       
110
       
-
       
       Used with CVS. Expects <literal>cvsRoot</literal>,

     

       
111
       
-
       
       <literal>tag</literal>, and <literal>sha256</literal>.

     

       
112
       
-
       
      </para>

     

       
113
       
-
       
     </listitem>

     

       
114
       
-
       
   </varlistentry>

     

       
115
       
-
       
   <varlistentry>

     

       
116
       
-
       
     <term>

     

       
117
       
-
       
      <literal>fetchhg</literal>

     

       
118
       
-
       
     </term>

     

       
119
       
-
       
     <listitem>

     

       
120
       
-
       
      <para>

     

       
121
       
-
       
       Used with Mercurial. Expects <literal>url</literal>,

     

       
122
       
-
       
       <literal>rev</literal>, and <literal>sha256</literal>.

     

       
123
       
-
       
      </para>

     

       
124
       
-
       
     </listitem>

     

       
125
       
-
       
   </varlistentry>

     

       
126
       
 
       
 </variablelist>

     

       
127
       
 
       


     

       
128
       
 
       
 <para>

     

       
129
       
-
       
   A number of fetcher functions wrap part of

     

       
130
       
-
       
   <function>fetchurl</function> and <function>fetchzip</function>.

     

       
131
       
-
       
   They are mainly convenience functions intended for commonly used

     

       
132
       
-
       
   destinations of source code in Nixpkgs. These wrapper fetchers are

     

       
133
       
-
       
   listed below.

     

       
134
       
 
       
 </para>

     

       
135
       
 
       


     

       
136
       
 
       
 <variablelist>

     

       
137
       
-
       
   <varlistentry>

     

       
138
       
-
       
     <term>

     

       
139
       
-
       
      <literal>fetchFromGitHub</literal>

     

       
140
       
-
       
     </term>

     

       
141
       
-
       
     <listitem>

     

       
142
       
-
       
      <para>

     

       
143
       
-
       
        <function>fetchFromGitHub</function> expects four arguments.

     

       
144
       
-
       
        <literal>owner</literal> is a string corresponding to the

     

       
145
       
-
       
        GitHub user or organization that controls this repository.

     

       
146
       
-
       
        <literal>repo</literal> corresponds to the name of the

     

       
147
       
-
       
        software repository. These are located at the top of every

     

       
148
       
-
       
        GitHub HTML page as

     

       
149
       
-
       
        <literal>owner</literal>/<literal>repo</literal>.

     

       
150
       
-
       
        <literal>rev</literal> corresponds to the Git commit hash or

     

       
151
       
-
       
        tag (e.g <literal>v1.0</literal>) that will be downloaded from

     

       
152
       
-
       
        Git. Finally, <literal>sha256</literal> corresponds to the

     

       
153
       
-
       
        hash of the extracted directory. Again, other hash algorithms

     

       
154
       
-
       
        are also available but <literal>sha256</literal> is currently

     

       
155
       
-
       
        preferred.

     

       
156
       
-
       
      </para>

     

       
157
       
-
       
     </listitem>

     

       
158
       
-
       
   </varlistentry>

     

       
159
       
-
       
   <varlistentry>

     

       
160
       
-
       
     <term>

     

       
161
       
-
       
      <literal>fetchFromGitLab</literal>

     

       
162
       
-
       
     </term>

     

       
163
       
-
       
     <listitem>

     

       
164
       
-
       
      <para>

     

       
165
       
-
       
       This is used with GitLab repositories. The arguments expected

     

       
166
       
-
       
       are very similar to fetchFromGitHub above.

     

       
167
       
-
       
      </para>

     

       
168
       
-
       
     </listitem>

     

       
169
       
-
       
   </varlistentry>

     

       
170
       
-
       
   <varlistentry>

     

       
171
       
-
       
     <term>

     

       
172
       
-
       
      <literal>fetchFromBitbucket</literal>

     

       
173
       
-
       
     </term>

     

       
174
       
-
       
     <listitem>

     

       
175
       
-
       
      <para>

     

       
176
       
-
       
       This is used with BitBucket repositories. The arguments expected

     

       
177
       
-
       
       are very similar to fetchFromGitHub above.

     

       
178
       
-
       
      </para>

     

       
179
       
-
       
     </listitem>

     

       
180
       
-
       
   </varlistentry>

     

       
181
       
-
       
   <varlistentry>

     

       
182
       
-
       
     <term>

     

       
183
       
-
       
      <literal>fetchFromSavannah</literal>

     

       
184
       
-
       
     </term>

     

       
185
       
-
       
     <listitem>

     

       
186
       
-
       
      <para>

     

       
187
       
-
       
       This is used with Savannah repositories. The arguments expected

     

       
188
       
-
       
       are very similar to fetchFromGitHub above.

     

       
189
       
-
       
      </para>

     

       
190
       
-
       
     </listitem>

     

       
191
       
-
       
   </varlistentry>

     

       
192
       
-
       
   <varlistentry>

     

       
193
       
-
       
     <term>

     

       
194
       
-
       
      <literal>fetchFromRepoOrCz</literal>

     

       
195
       
-
       
     </term>

     

       
196
       
-
       
     <listitem>

     

       
197
       
-
       
      <para>

     

       
198
       
-
       
       This is used with repo.or.cz repositories. The arguments

     

       
199
       
-
       
       expected are very similar to fetchFromGitHub above.

     

       
200
       
-
       
      </para>

     

       
201
       
-
       
     </listitem>

     

       
202
       
-
       
   </varlistentry>

     

       
203
       
 
       
 </variablelist>

     

       
204
       
-
       


     

       
205
       
-
       


     

       
206
       
 
       
</section>

     

···

       
5
       
 
       
 <title>Fetcher functions</title>

     

       
6
       
 
       


     

       
7
       
 
       
 <para>

     

       
8
       
+
       
  When using Nix, you will frequently need to download source code and other

     

       
9
       
+
       
  files from the internet. Nixpkgs comes with a few helper functions that allow

     

       
10
       
+
       
  you to fetch fixed-output derivations in a structured way.

     

       
0
       
 
       

     

       
11
       
 
       
 </para>

     

       
12
       
 
       


     

       
13
       
 
       
 <para>

     

       
14
       
+
       
  The two fetcher primitives are <function>fetchurl</function> and

     

       
15
       
+
       
  <function>fetchzip</function>. Both of these have two required arguments, a

     

       
16
       
+
       
  URL and a hash. The hash is typically <literal>sha256</literal>, although

     

       
17
       
+
       
  many more hash algorithms are supported. Nixpkgs contributors are currently

     

       
18
       
+
       
  recommended to use <literal>sha256</literal>. This hash will be used by Nix

     

       
19
       
+
       
  to identify your source. A typical usage of fetchurl is provided below.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
20
       
 
       
 </para>

     

       
21
       
 
       


     

       
22
       
+
       
<programlisting><![CDATA[

     

       
23
       
 
       
{ stdenv, fetchurl }:

     

       
24
       
 
       


     

       
25
       
 
       
stdenv.mkDerivation {

     
···

       
32
       
 
       
]]></programlisting>

     

       
33
       
 
       


     

       
34
       
 
       
 <para>

     

       
35
       
+
       
  The main difference between <function>fetchurl</function> and

     

       
36
       
+
       
  <function>fetchzip</function> is in how they store the contents.

     

       
37
       
+
       
  <function>fetchurl</function> will store the unaltered contents of the URL

     

       
38
       
+
       
  within the Nix store. <function>fetchzip</function> on the other hand will

     

       
39
       
+
       
  decompress the archive for you, making files and directories directly

     

       
40
       
+
       
  accessible in the future. <function>fetchzip</function> can only be used with

     

       
41
       
+
       
  archives. Despite the name, <function>fetchzip</function> is not limited to

     

       
42
       
+
       
  .zip files and can also be used with any tarball.

     

       
0
       
 
       

     

       
43
       
 
       
 </para>

     

       
44
       
 
       


     

       
45
       
 
       
 <para>

     

       
46
       
+
       
  <function>fetchpatch</function> works very similarly to

     

       
47
       
+
       
  <function>fetchurl</function> with the same arguments expected. It expects

     

       
48
       
+
       
  patch files as a source and and performs normalization on them before

     

       
49
       
+
       
  computing the checksum. For example it will remove comments or other unstable

     

       
50
       
+
       
  parts that are sometimes added by version control systems and can change over

     

       
51
       
+
       
  time.

     

       
52
       
 
       
 </para>

     

       
53
       
 
       


     

       
54
       
 
       
 <para>

     

       
55
       
+
       
  Other fetcher functions allow you to add source code directly from a VCS such

     

       
56
       
+
       
  as subversion or git. These are mostly straightforward names based on the

     

       
57
       
+
       
  name of the command used with the VCS system. Because they give you a working

     

       
58
       
+
       
  repository, they act most like <function>fetchzip</function>.

     

       
0
       
 
       

     

       
59
       
 
       
 </para>

     

       
60
       
 
       


     

       
61
       
 
       
 <variablelist>

     

       
62
       
+
       
  <varlistentry>

     

       
63
       
+
       
   <term>

     

       
64
       
+
       
    <literal>fetchsvn</literal>

     

       
65
       
+
       
   </term>

     

       
66
       
+
       
   <listitem>

     

       
67
       
+
       
    <para>

     

       
68
       
+
       
     Used with Subversion. Expects <literal>url</literal> to a Subversion

     

       
69
       
+
       
     directory, <literal>rev</literal>, and <literal>sha256</literal>.

     

       
70
       
+
       
    </para>

     

       
71
       
+
       
   </listitem>

     

       
72
       
+
       
  </varlistentry>

     

       
73
       
+
       
  <varlistentry>

     

       
74
       
+
       
   <term>

     

       
75
       
+
       
    <literal>fetchgit</literal>

     

       
76
       
+
       
   </term>

     

       
77
       
+
       
   <listitem>

     

       
78
       
+
       
    <para>

     

       
79
       
+
       
     Used with Git. Expects <literal>url</literal> to a Git repo,

     

       
80
       
+
       
     <literal>rev</literal>, and <literal>sha256</literal>.

     

       
81
       
+
       
     <literal>rev</literal> in this case can be full the git commit id (SHA1

     

       
82
       
+
       
     hash) or a tag name like <literal>refs/tags/v1.0</literal>.

     

       
83
       
+
       
    </para>

     

       
84
       
+
       
   </listitem>

     

       
85
       
+
       
  </varlistentry>

     

       
86
       
+
       
  <varlistentry>

     

       
87
       
+
       
   <term>

     

       
88
       
+
       
    <literal>fetchfossil</literal>

     

       
89
       
+
       
   </term>

     

       
90
       
+
       
   <listitem>

     

       
91
       
+
       
    <para>

     

       
92
       
+
       
     Used with Fossil. Expects <literal>url</literal> to a Fossil archive,

     

       
93
       
+
       
     <literal>rev</literal>, and <literal>sha256</literal>.

     

       
94
       
+
       
    </para>

     

       
95
       
+
       
   </listitem>

     

       
96
       
+
       
  </varlistentry>

     

       
97
       
+
       
  <varlistentry>

     

       
98
       
+
       
   <term>

     

       
99
       
+
       
    <literal>fetchcvs</literal>

     

       
100
       
+
       
   </term>

     

       
101
       
+
       
   <listitem>

     

       
102
       
+
       
    <para>

     

       
103
       
+
       
     Used with CVS. Expects <literal>cvsRoot</literal>, <literal>tag</literal>,

     

       
104
       
+
       
     and <literal>sha256</literal>.

     

       
105
       
+
       
    </para>

     

       
106
       
+
       
   </listitem>

     

       
107
       
+
       
  </varlistentry>

     

       
108
       
+
       
  <varlistentry>

     

       
109
       
+
       
   <term>

     

       
110
       
+
       
    <literal>fetchhg</literal>

     

       
111
       
+
       
   </term>

     

       
112
       
+
       
   <listitem>

     

       
113
       
+
       
    <para>

     

       
114
       
+
       
     Used with Mercurial. Expects <literal>url</literal>,

     

       
115
       
+
       
     <literal>rev</literal>, and <literal>sha256</literal>.

     

       
116
       
+
       
    </para>

     

       
117
       
+
       
   </listitem>

     

       
118
       
+
       
  </varlistentry>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
119
       
 
       
 </variablelist>

     

       
120
       
 
       


     

       
121
       
 
       
 <para>

     

       
122
       
+
       
  A number of fetcher functions wrap part of <function>fetchurl</function> and

     

       
123
       
+
       
  <function>fetchzip</function>. They are mainly convenience functions intended

     

       
124
       
+
       
  for commonly used destinations of source code in Nixpkgs. These wrapper

     

       
125
       
+
       
  fetchers are listed below.

     

       
0
       
 
       

     

       
126
       
 
       
 </para>

     

       
127
       
 
       


     

       
128
       
 
       
 <variablelist>

     

       
129
       
+
       
  <varlistentry>

     

       
130
       
+
       
   <term>

     

       
131
       
+
       
    <literal>fetchFromGitHub</literal>

     

       
132
       
+
       
   </term>

     

       
133
       
+
       
   <listitem>

     

       
134
       
+
       
    <para>

     

       
135
       
+
       
     <function>fetchFromGitHub</function> expects four arguments.

     

       
136
       
+
       
     <literal>owner</literal> is a string corresponding to the GitHub user or

     

       
137
       
+
       
     organization that controls this repository. <literal>repo</literal>

     

       
138
       
+
       
     corresponds to the name of the software repository. These are located at

     

       
139
       
+
       
     the top of every GitHub HTML page as

     

       
140
       
+
       
     <literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal>

     

       
141
       
+
       
     corresponds to the Git commit hash or tag (e.g <literal>v1.0</literal>)

     

       
142
       
+
       
     that will be downloaded from Git. Finally, <literal>sha256</literal>

     

       
143
       
+
       
     corresponds to the hash of the extracted directory. Again, other hash

     

       
144
       
+
       
     algorithms are also available but <literal>sha256</literal> is currently

     

       
145
       
+
       
     preferred.

     

       
146
       
+
       
    </para>

     

       
147
       
+
       
   </listitem>

     

       
148
       
+
       
  </varlistentry>

     

       
149
       
+
       
  <varlistentry>

     

       
150
       
+
       
   <term>

     

       
151
       
+
       
    <literal>fetchFromGitLab</literal>

     

       
152
       
+
       
   </term>

     

       
153
       
+
       
   <listitem>

     

       
154
       
+
       
    <para>

     

       
155
       
+
       
     This is used with GitLab repositories. The arguments expected are very

     

       
156
       
+
       
     similar to fetchFromGitHub above.

     

       
157
       
+
       
    </para>

     

       
158
       
+
       
   </listitem>

     

       
159
       
+
       
  </varlistentry>

     

       
160
       
+
       
  <varlistentry>

     

       
161
       
+
       
   <term>

     

       
162
       
+
       
    <literal>fetchFromBitbucket</literal>

     

       
163
       
+
       
   </term>

     

       
164
       
+
       
   <listitem>

     

       
165
       
+
       
    <para>

     

       
166
       
+
       
     This is used with BitBucket repositories. The arguments expected are very

     

       
167
       
+
       
     similar to fetchFromGitHub above.

     

       
168
       
+
       
    </para>

     

       
169
       
+
       
   </listitem>

     

       
170
       
+
       
  </varlistentry>

     

       
171
       
+
       
  <varlistentry>

     

       
172
       
+
       
   <term>

     

       
173
       
+
       
    <literal>fetchFromSavannah</literal>

     

       
174
       
+
       
   </term>

     

       
175
       
+
       
   <listitem>

     

       
176
       
+
       
    <para>

     

       
177
       
+
       
     This is used with Savannah repositories. The arguments expected are very

     

       
178
       
+
       
     similar to fetchFromGitHub above.

     

       
179
       
+
       
    </para>

     

       
180
       
+
       
   </listitem>

     

       
181
       
+
       
  </varlistentry>

     

       
182
       
+
       
  <varlistentry>

     

       
183
       
+
       
   <term>

     

       
184
       
+
       
    <literal>fetchFromRepoOrCz</literal>

     

       
185
       
+
       
   </term>

     

       
186
       
+
       
   <listitem>

     

       
187
       
+
       
    <para>

     

       
188
       
+
       
     This is used with repo.or.cz repositories. The arguments expected are very

     

       
189
       
+
       
     similar to fetchFromGitHub above.

     

       
190
       
+
       
    </para>

     

       
191
       
+
       
   </listitem>

     

       
192
       
+
       
  </varlistentry>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
193
       
 
       
 </variablelist>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
194
       
 
       
</section>

     

···

       
13
       
 
       


     

       
14
       
 
       
 <xi:include href="./library/attrsets.xml" />

     

       
15
       
 
       


     

       
16
       
-
       
 <!-- These docs are generated via nixdoc. To add another generated

     

       
17
       
 
       
      library function file to this list, the file

     

       
18
       
 
       
      `lib-function-docs.nix` must also be updated. -->

     

       
0
       
 
       

     

       
19
       
 
       
 <xi:include href="./library/generated/strings.xml" />

     

       
0
       
 
       

     

       
20
       
 
       
 <xi:include href="./library/generated/trivial.xml" />

     

       
0
       
 
       

     

       
21
       
 
       
 <xi:include href="./library/generated/lists.xml" />

     

       
0
       
 
       

     

       
22
       
 
       
 <xi:include href="./library/generated/debug.xml" />

     

       
0
       
 
       

     

       
23
       
 
       
 <xi:include href="./library/generated/options.xml" />

     

       
24
       
 
       
</section>

     

···

       
13
       
 
       


     

       
14
       
 
       
 <xi:include href="./library/attrsets.xml" />

     

       
15
       
 
       


     

       
16
       
+
       
<!-- These docs are generated via nixdoc. To add another generated

     

       
17
       
 
       
      library function file to this list, the file

     

       
18
       
 
       
      `lib-function-docs.nix` must also be updated. -->

     

       
19
       
+
       


     

       
20
       
 
       
 <xi:include href="./library/generated/strings.xml" />

     

       
21
       
+
       


     

       
22
       
 
       
 <xi:include href="./library/generated/trivial.xml" />

     

       
23
       
+
       


     

       
24
       
 
       
 <xi:include href="./library/generated/lists.xml" />

     

       
25
       
+
       


     

       
26
       
 
       
 <xi:include href="./library/generated/debug.xml" />

     

       
27
       
+
       


     

       
28
       
 
       
 <xi:include href="./library/generated/options.xml" />

     

       
29
       
 
       
</section>

     

···

       
14
       
 
       
  <title>Usage</title>

     

       
15
       
 
       


     

       
16
       
 
       
  <para>

     

       
17
       
-
       
  <literal>pkgs.nix-gitignore</literal> exports a number of functions, but

     

       
18
       
-
       
  you'll most likely need either <literal>gitignoreSource</literal> or

     

       
19
       
-
       
  <literal>gitignoreSourcePure</literal>. As their first argument, they both

     

       
20
       
-
       
  accept either 1. a file with gitignore lines or 2. a string

     

       
21
       
-
       
  with gitignore lines, or 3. a list of either of the two. They will be

     

       
22
       
-
       
  concatenated into a single big string.

     

       
23
       
 
       
  </para>

     

       
24
       
 
       


     

       
25
       
-
       
  <programlisting><![CDATA[

     

       
26
       
 
       
{ pkgs ? import <nixpkgs> {} }:

     

       
27
       
 
       


     

       
28
       
 
       
 nix-gitignore.gitignoreSource [] ./source

     
···

       
40
       
 
       
  ]]></programlisting>

     

       
41
       
 
       


     

       
42
       
 
       
  <para>

     

       
43
       
-
       
  These functions are derived from the <literal>Filter</literal> functions

     

       
44
       
-
       
  by setting the first filter argument to <literal>(_: _: true)</literal>:

     

       
45
       
 
       
  </para>

     

       
46
       
 
       


     

       
47
       
-
       
  <programlisting><![CDATA[

     

       
48
       
 
       
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);

     

       
49
       
 
       
gitignoreSource = gitignoreFilterSource (_: _: true);

     

       
50
       
 
       
  ]]></programlisting>

     

       
51
       
 
       


     

       
52
       
 
       
  <para>

     

       
53
       
-
       
  Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
54
       
 
       
  </para>

     

       
55
       
 
       


     

       
56
       
 
       
  <para>

     

       
57
       
-
       
  If you want to make your own filter from scratch, you may use

     

       
58
       
-
       
 </para>

     

       
59
       
 
       


     

       
60
       
-
       
  <programlisting><![CDATA[

     

       
61
       
 
       
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;

     

       
62
       
 
       
  ]]></programlisting>

     

       
63
       
 
       
 </section>

     
···

       
66
       
 
       
  <title>gitignore files in subdirectories</title>

     

       
67
       
 
       


     

       
68
       
 
       
  <para>

     

       
69
       
-
       
  If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:

     

       
70
       
-
       
 </para>

     

       
0
       
 
       

     

       
71
       
 
       


     

       
72
       
-
       
  <programlisting><![CDATA[

     

       
73
       
 
       
gitignoreFilterRecursiveSource = filter: patterns: root:

     

       
74
       
 
       
# OR

     

       
75
       
 
       
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);

     

···

       
14
       
 
       
  <title>Usage</title>

     

       
15
       
 
       


     

       
16
       
 
       
  <para>

     

       
17
       
+
       
   <literal>pkgs.nix-gitignore</literal> exports a number of functions, but

     

       
18
       
+
       
   you'll most likely need either <literal>gitignoreSource</literal> or

     

       
19
       
+
       
   <literal>gitignoreSourcePure</literal>. As their first argument, they both

     

       
20
       
+
       
   accept either 1. a file with gitignore lines or 2. a string with gitignore

     

       
21
       
+
       
   lines, or 3. a list of either of the two. They will be concatenated into a

     

       
22
       
+
       
   single big string.

     

       
23
       
 
       
  </para>

     

       
24
       
 
       


     

       
25
       
+
       
<programlisting><![CDATA[

     

       
26
       
 
       
{ pkgs ? import <nixpkgs> {} }:

     

       
27
       
 
       


     

       
28
       
 
       
 nix-gitignore.gitignoreSource [] ./source

     
···

       
40
       
 
       
  ]]></programlisting>

     

       
41
       
 
       


     

       
42
       
 
       
  <para>

     

       
43
       
+
       
   These functions are derived from the <literal>Filter</literal> functions by

     

       
44
       
+
       
   setting the first filter argument to <literal>(_: _: true)</literal>:

     

       
45
       
 
       
  </para>

     

       
46
       
 
       


     

       
47
       
+
       
<programlisting><![CDATA[

     

       
48
       
 
       
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);

     

       
49
       
 
       
gitignoreSource = gitignoreFilterSource (_: _: true);

     

       
50
       
 
       
  ]]></programlisting>

     

       
51
       
 
       


     

       
52
       
 
       
  <para>

     

       
53
       
+
       
   Those filter functions accept the same arguments the

     

       
54
       
+
       
   <literal>builtins.filterSource</literal> function would pass to its filters,

     

       
55
       
+
       
   thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be

     

       
56
       
+
       
   extensionally equivalent to <literal>filterSource</literal>. The file is

     

       
57
       
+
       
   blacklisted iff it's blacklisted by either your filter or the

     

       
58
       
+
       
   gitignoreFilter.

     

       
59
       
 
       
  </para>

     

       
60
       
 
       


     

       
61
       
 
       
  <para>

     

       
62
       
+
       
   If you want to make your own filter from scratch, you may use

     

       
63
       
+
       
  </para>

     

       
64
       
 
       


     

       
65
       
+
       
<programlisting><![CDATA[

     

       
66
       
 
       
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;

     

       
67
       
 
       
  ]]></programlisting>

     

       
68
       
 
       
 </section>

     
···

       
71
       
 
       
  <title>gitignore files in subdirectories</title>

     

       
72
       
 
       


     

       
73
       
 
       
  <para>

     

       
74
       
+
       
   If you wish to use a filter that would search for .gitignore files in

     

       
75
       
+
       
   subdirectories, just like git does by default, use this function:

     

       
76
       
+
       
  </para>

     

       
77
       
 
       


     

       
78
       
+
       
<programlisting><![CDATA[

     

       
79
       
 
       
gitignoreFilterRecursiveSource = filter: patterns: root:

     

       
80
       
 
       
# OR

     

       
81
       
 
       
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);

     

···

       
7
       
 
       
 <para>

     

       
8
       
 
       
  <function>prefer-remote-fetch</function> is an overlay that download sources

     

       
9
       
 
       
  on remote builder. This is useful when the evaluating machine has a slow

     

       
10
       
-
       
  upload while the builder can fetch faster directly from the source.

     

       
11
       
-
       
  To use it, put the following snippet as a new overlay:

     

       
12
       
-
       
  <programlisting>

     

       
13
       
 
       
    self: super:

     

       
14
       
 
       
      (super.prefer-remote-fetch self super)

     

       
15
       
 
       
  </programlisting>

     

       
16
       
-
       


     

       
17
       
-
       
  A full configuration example for that sets the overlay up for your own account,

     

       
18
       
-
       
  could look like this

     

       
19
       
-
       


     

       
20
       
-
       
  <programlisting>

     

       
21
       
 
       
    $ mkdir ~/.config/nixpkgs/overlays/

     

       
22
       
 
       
    $ cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF

     

       
23
       
 
       
      self: super: super.prefer-remote-fetch self super

     

···

       
7
       
 
       
 <para>

     

       
8
       
 
       
  <function>prefer-remote-fetch</function> is an overlay that download sources

     

       
9
       
 
       
  on remote builder. This is useful when the evaluating machine has a slow

     

       
10
       
+
       
  upload while the builder can fetch faster directly from the source. To use

     

       
11
       
+
       
  it, put the following snippet as a new overlay:

     

       
12
       
+
       
<programlisting>

     

       
13
       
 
       
    self: super:

     

       
14
       
 
       
      (super.prefer-remote-fetch self super)

     

       
15
       
 
       
  </programlisting>

     

       
16
       
+
       
  A full configuration example for that sets the overlay up for your own

     

       
17
       
+
       
  account, could look like this

     

       
18
       
+
       
<programlisting>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
19
       
 
       
    $ mkdir ~/.config/nixpkgs/overlays/

     

       
20
       
 
       
    $ cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF

     

       
21
       
 
       
      self: super: super.prefer-remote-fetch self super

     

···

       
5
       
 
       
 <title>Trivial builders</title>

     

       
6
       
 
       


     

       
7
       
 
       
 <para>

     

       
8
       
-
       
   Nixpkgs provides a couple of functions that help with building

     

       
9
       
-
       
   derivations. The most important one,

     

       
10
       
-
       
   <function>stdenv.mkDerivation</function>, has already been

     

       
11
       
-
       
   documented above. The following functions wrap

     

       
12
       
-
       
   <function>stdenv.mkDerivation</function>, making it easier to use

     

       
13
       
-
       
   in certain cases.

     

       
14
       
 
       
 </para>

     

       
15
       
 
       


     

       
16
       
 
       
 <variablelist>

     
···

       
19
       
 
       
    <literal>runCommand</literal>

     

       
20
       
 
       
   </term>

     

       
21
       
 
       
   <listitem>

     

       
22
       
-
       
     <para>

     

       
23
       
-
       
       This takes three arguments, <literal>name</literal>,

     

       
24
       
-
       
       <literal>env</literal>, and <literal>buildCommand</literal>.

     

       
25
       
-
       
       <literal>name</literal> is just the name that Nix will append

     

       
26
       
-
       
       to the store path in the same way that

     

       
27
       
-
       
       <literal>stdenv.mkDerivation</literal> uses its

     

       
28
       
-
       
       <literal>name</literal> attribute. <literal>env</literal> is an

     

       
29
       
-
       
       attribute set specifying environment variables that will be set

     

       
30
       
-
       
       for this derivation. These attributes are then passed to the

     

       
31
       
-
       
       wrapped <literal>stdenv.mkDerivation</literal>.

     

       
32
       
-
       
       <literal>buildCommand</literal> specifies the commands that

     

       
33
       
-
       
       will be run to create this derivation. Note that you will need

     

       
34
       
-
       
       to create <literal>$out</literal> for Nix to register the

     

       
35
       
-
       
       command as successful.

     

       
36
       
-
       
     </para>

     

       
37
       
-
       
     <para>

     

       
38
       
-
       
       An example of using <literal>runCommand</literal> is provided

     

       
39
       
-
       
       below.

     

       
40
       
-
       
     </para>

     

       
41
       
-
       
     <programlisting>

     

       
42
       
 
       
       (import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''

     

       
43
       
 
       
         echo My example command is running

     

       
44
       
 
       


     
···

       
65
       
 
       
    <literal>runCommandCC</literal>

     

       
66
       
 
       
   </term>

     

       
67
       
 
       
   <listitem>

     

       
68
       
-
       
     <para>

     

       
69
       
-
       
       This works just like <literal>runCommand</literal>. The only

     

       
70
       
-
       
       difference is that it also provides a C compiler in

     

       
71
       
-
       
       <literal>buildCommand</literal>’s environment. To minimize your

     

       
72
       
-
       
       dependencies, you should only use this if you are sure you will

     

       
73
       
-
       
       need a C compiler as part of running your command.

     

       
74
       
 
       
    </para>

     

       
75
       
 
       
   </listitem>

     

       
76
       
 
       
  </varlistentry>

     

       
77
       
 
       
  <varlistentry>

     

       
78
       
 
       
   <term>

     

       
79
       
-
       
    <literal>writeTextFile</literal>, <literal>writeText</literal>,

     

       
80
       
-
       
    <literal>writeTextDir</literal>, <literal>writeScript</literal>,

     

       
81
       
-
       
    <literal>writeScriptBin</literal>

     

       
82
       
 
       
   </term>

     

       
83
       
 
       
   <listitem>

     

       
84
       
-
       
     <para>

     

       
85
       
-
       
       These functions write <literal>text</literal> to the Nix store.

     

       
86
       
-
       
       This is useful for creating scripts from Nix expressions.

     

       
87
       
-
       
       <literal>writeTextFile</literal> takes an attribute set and

     

       
88
       
-
       
       expects two arguments, <literal>name</literal> and

     

       
89
       
-
       
       <literal>text</literal>. <literal>name</literal> corresponds to

     

       
90
       
-
       
       the name used in the Nix store path. <literal>text</literal>

     

       
91
       
-
       
       will be the contents of the file. You can also set

     

       
92
       
-
       
       <literal>executable</literal> to true to make this file have

     

       
93
       
-
       
       the executable bit set.

     

       
94
       
-
       
     </para>

     

       
95
       
-
       
     <para>

     

       
96
       
-
       
       Many more commands wrap <literal>writeTextFile</literal>

     

       
97
       
-
       
       including <literal>writeText</literal>,

     

       
98
       
-
       
       <literal>writeTextDir</literal>,

     

       
99
       
-
       
       <literal>writeScript</literal>, and

     

       
100
       
-
       
       <literal>writeScriptBin</literal>. These are convenience

     

       
101
       
-
       
       functions over <literal>writeTextFile</literal>.

     

       
102
       
-
       
     </para>

     

       
103
       
 
       
   </listitem>

     

       
104
       
 
       
  </varlistentry>

     

       
105
       
 
       
  <varlistentry>

     
···

       
109
       
 
       
   <listitem>

     

       
110
       
 
       
    <para>

     

       
111
       
 
       
     This can be used to put many derivations into the same directory

     

       
112
       
-
       
     structure. It works by creating a new derivation and adding

     

       
113
       
-
       
     symlinks to each of the paths listed. It expects two arguments,

     

       
114
       
 
       
     <literal>name</literal>, and <literal>paths</literal>.

     

       
115
       
-
       
     <literal>name</literal> is the name used in the Nix store path

     

       
116
       
-
       
     for the created derivation. <literal>paths</literal> is a list of

     

       
117
       
-
       
     paths that will be symlinked. These paths can be to Nix store

     

       
118
       
-
       
     derivations or any other subdirectory contained within.

     

       
119
       
 
       
    </para>

     

       
120
       
 
       
   </listitem>

     

       
121
       
 
       
  </varlistentry>

     

       
122
       
 
       
 </variablelist>

     

       
123
       
-
       


     

       
124
       
 
       
</section>