pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-conventions">
4 <title>Coding conventions</title>
5 <section xml:id="sec-syntax">
6 <title>Syntax</title>
7
8 <itemizedlist>
9 <listitem>
10 <para>
11 Use 2 spaces of indentation per indentation level in Nix expressions, 4
12 spaces in shell scripts.
13 </para>
14 </listitem>
15 <listitem>
16 <para>
17 Do not use tab characters, i.e. configure your editor to use soft tabs.
18 For instance, use <literal>(setq-default indent-tabs-mode nil)</literal>
19 in Emacs. Everybody has different tab settings so it’s asking for
20 trouble.
21 </para>
22 </listitem>
23 <listitem>
24 <para>
25 Use <literal>lowerCamelCase</literal> for variable names, not
26 <literal>UpperCamelCase</literal>. Note, this rule does not apply to
27 package attribute names, which instead follow the rules in
28 <xref linkend="sec-package-naming"/>.
29 </para>
30 </listitem>
31 <listitem>
32 <para>
33 Function calls with attribute set arguments are written as
34<programlisting>
35foo {
36 arg = ...;
37}
38</programlisting>
39 not
40<programlisting>
41foo
42{
43 arg = ...;
44}
45</programlisting>
46 Also fine is
47<programlisting>
48foo { arg = ...; }
49</programlisting>
50 if it's a short call.
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 In attribute sets or lists that span multiple lines, the attribute names
56 or list elements should be aligned:
57<programlisting>
58# A long list.
59list =
60 [ elem1
61 elem2
62 elem3
63 ];
64
65# A long attribute set.
66attrs =
67 { attr1 = short_expr;
68 attr2 =
69 if true then big_expr else big_expr;
70 };
71
72# Alternatively:
73attrs = {
74 attr1 = short_expr;
75 attr2 =
76 if true then big_expr else big_expr;
77};
78</programlisting>
79 </para>
80 </listitem>
81 <listitem>
82 <para>
83 Short lists or attribute sets can be written on one line:
84<programlisting>
85# A short list.
86list = [ elem1 elem2 elem3 ];
87
88# A short set.
89attrs = { x = 1280; y = 1024; };
90</programlisting>
91 </para>
92 </listitem>
93 <listitem>
94 <para>
95 Breaking in the middle of a function argument can give hard-to-read code,
96 like
97<programlisting>
98someFunction { x = 1280;
99 y = 1024; } otherArg
100 yetAnotherArg
101</programlisting>
102 (especially if the argument is very large, spanning multiple lines).
103 </para>
104 <para>
105 Better:
106<programlisting>
107someFunction
108 { x = 1280; y = 1024; }
109 otherArg
110 yetAnotherArg
111</programlisting>
112 or
113<programlisting>
114let res = { x = 1280; y = 1024; };
115in someFunction res otherArg yetAnotherArg
116</programlisting>
117 </para>
118 </listitem>
119 <listitem>
120 <para>
121 The bodies of functions, asserts, and withs are not indented to prevent a
122 lot of superfluous indentation levels, i.e.
123<programlisting>
124{ arg1, arg2 }:
125assert system == "i686-linux";
126stdenv.mkDerivation { ...
127</programlisting>
128 not
129<programlisting>
130{ arg1, arg2 }:
131 assert system == "i686-linux";
132 stdenv.mkDerivation { ...
133</programlisting>
134 </para>
135 </listitem>
136 <listitem>
137 <para>
138 Function formal arguments are written as:
139<programlisting>
140{ arg1, arg2, arg3 }:
141</programlisting>
142 but if they don't fit on one line they're written as:
143<programlisting>
144{ arg1, arg2, arg3
145, arg4, ...
146, # Some comment...
147 argN
148}:
149</programlisting>
150 </para>
151 </listitem>
152 <listitem>
153 <para>
154 Functions should list their expected arguments as precisely as possible.
155 That is, write
156<programlisting>
157{ stdenv, fetchurl, perl }: <replaceable>...</replaceable>
158</programlisting>
159 instead of
160<programlisting>
161args: with args; <replaceable>...</replaceable>
162</programlisting>
163 or
164<programlisting>
165{ stdenv, fetchurl, perl, ... }: <replaceable>...</replaceable>
166</programlisting>
167 </para>
168 <para>
169 For functions that are truly generic in the number of arguments (such as
170 wrappers around <varname>mkDerivation</varname>) that have some required
171 arguments, you should write them using an <literal>@</literal>-pattern:
172<programlisting>
173{ stdenv, doCoverageAnalysis ? false, ... } @ args:
174
175stdenv.mkDerivation (args // {
176 <replaceable>...</replaceable> if doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>
177})
178</programlisting>
179 instead of
180<programlisting>
181args:
182
183args.stdenv.mkDerivation (args // {
184 <replaceable>...</replaceable> if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>
185})
186</programlisting>
187 </para>
188 </listitem>
189 </itemizedlist>
190 </section>
191 <section xml:id="sec-package-naming">
192 <title>Package naming</title>
193
194 <para>
195 In Nixpkgs, there are generally three different names associated with a
196 package:
197 <itemizedlist>
198 <listitem>
199 <para>
200 The <varname>name</varname> attribute of the derivation (excluding the
201 version part). This is what most users see, in particular when using
202 <command>nix-env</command>.
203 </para>
204 </listitem>
205 <listitem>
206 <para>
207 The variable name used for the instantiated package in
208 <filename>all-packages.nix</filename>, and when passing it as a
209 dependency to other functions. Typically this is called the
210 <emphasis>package attribute name</emphasis>. This is what Nix expression
211 authors see. It can also be used when installing using <command>nix-env
212 -iA</command>.
213 </para>
214 </listitem>
215 <listitem>
216 <para>
217 The filename for (the directory containing) the Nix expression.
218 </para>
219 </listitem>
220 </itemizedlist>
221 Most of the time, these are the same. For instance, the package
222 <literal>e2fsprogs</literal> has a <varname>name</varname> attribute
223 <literal>"e2fsprogs-<replaceable>version</replaceable>"</literal>, is bound
224 to the variable name <varname>e2fsprogs</varname> in
225 <filename>all-packages.nix</filename>, and the Nix expression is in
226 <filename>pkgs/os-specific/linux/e2fsprogs/default.nix</filename>.
227 </para>
228
229 <para>
230 There are a few naming guidelines:
231 <itemizedlist>
232 <listitem>
233 <para>
234 Generally, try to stick to the upstream package name.
235 </para>
236 </listitem>
237 <listitem>
238 <para>
239 Don’t use uppercase letters in the <literal>name</literal> attribute
240 — e.g., <literal>"mplayer-1.0rc2"</literal> instead of
241 <literal>"MPlayer-1.0rc2"</literal>.
242 </para>
243 </listitem>
244 <listitem>
245 <para>
246 The version part of the <literal>name</literal> attribute
247 <emphasis>must</emphasis> start with a digit (following a dash) — e.g.,
248 <literal>"hello-0.3.1rc2"</literal>.
249 </para>
250 </listitem>
251 <listitem>
252 <para>
253 If a package is not a release but a commit from a repository, then the
254 version part of the name <emphasis>must</emphasis> be the date of that
255 (fetched) commit. The date must be in <literal>"YYYY-MM-DD"</literal>
256 format. Also append <literal>"unstable"</literal> to the name - e.g.,
257 <literal>"pkgname-unstable-2014-09-23"</literal>.
258 </para>
259 </listitem>
260 <listitem>
261 <para>
262 Dashes in the package name should be preserved in new variable names,
263 rather than converted to underscores or camel cased — e.g.,
264 <varname>http-parser</varname> instead of <varname>http_parser</varname>
265 or <varname>httpParser</varname>. The hyphenated style is preferred in
266 all three package names.
267 </para>
268 </listitem>
269 <listitem>
270 <para>
271 If there are multiple versions of a package, this should be reflected in
272 the variable names in <filename>all-packages.nix</filename>, e.g.
273 <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If
274 there is an obvious “default” version, make an attribute like
275 <literal>json-c = json-c-0-9;</literal>. See also
276 <xref linkend="sec-versioning" />
277 </para>
278 </listitem>
279 </itemizedlist>
280 </para>
281 </section>
282 <section xml:id="sec-organisation">
283 <title>File naming and organisation</title>
284
285 <para>
286 Names of files and directories should be in lowercase, with dashes between
287 words — not in camel case. For instance, it should be
288 <filename>all-packages.nix</filename>, not
289 <filename>allPackages.nix</filename> or
290 <filename>AllPackages.nix</filename>.
291 </para>
292
293 <section xml:id="sec-hierarchy">
294 <title>Hierarchy</title>
295
296 <para>
297 Each package should be stored in its own directory somewhere in the
298 <filename>pkgs/</filename> tree, i.e. in
299 <filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.
300 Below are some rules for picking the right category for a package. Many
301 packages fall under several categories; what matters is the
302 <emphasis>primary</emphasis> purpose of a package. For example, the
303 <literal>libxml2</literal> package builds both a library and some tools;
304 but it’s a library foremost, so it goes under
305 <filename>pkgs/development/libraries</filename>.
306 </para>
307
308 <para>
309 When in doubt, consider refactoring the <filename>pkgs/</filename> tree,
310 e.g. creating new categories or splitting up an existing category.
311 </para>
312
313 <variablelist>
314 <varlistentry>
315 <term>
316 If it’s used to support <emphasis>software development</emphasis>:
317 </term>
318 <listitem>
319 <variablelist>
320 <varlistentry>
321 <term>
322 If it’s a <emphasis>library</emphasis> used by other packages:
323 </term>
324 <listitem>
325 <para>
326 <filename>development/libraries</filename> (e.g.
327 <filename>libxml2</filename>)
328 </para>
329 </listitem>
330 </varlistentry>
331 <varlistentry>
332 <term>
333 If it’s a <emphasis>compiler</emphasis>:
334 </term>
335 <listitem>
336 <para>
337 <filename>development/compilers</filename> (e.g.
338 <filename>gcc</filename>)
339 </para>
340 </listitem>
341 </varlistentry>
342 <varlistentry>
343 <term>
344 If it’s an <emphasis>interpreter</emphasis>:
345 </term>
346 <listitem>
347 <para>
348 <filename>development/interpreters</filename> (e.g.
349 <filename>guile</filename>)
350 </para>
351 </listitem>
352 </varlistentry>
353 <varlistentry>
354 <term>
355 If it’s a (set of) development <emphasis>tool(s)</emphasis>:
356 </term>
357 <listitem>
358 <variablelist>
359 <varlistentry>
360 <term>
361 If it’s a <emphasis>parser generator</emphasis> (including lexers):
362 </term>
363 <listitem>
364 <para>
365 <filename>development/tools/parsing</filename> (e.g.
366 <filename>bison</filename>, <filename>flex</filename>)
367 </para>
368 </listitem>
369 </varlistentry>
370 <varlistentry>
371 <term>
372 If it’s a <emphasis>build manager</emphasis>:
373 </term>
374 <listitem>
375 <para>
376 <filename>development/tools/build-managers</filename> (e.g.
377 <filename>gnumake</filename>)
378 </para>
379 </listitem>
380 </varlistentry>
381 <varlistentry>
382 <term>
383 Else:
384 </term>
385 <listitem>
386 <para>
387 <filename>development/tools/misc</filename> (e.g.
388 <filename>binutils</filename>)
389 </para>
390 </listitem>
391 </varlistentry>
392 </variablelist>
393 </listitem>
394 </varlistentry>
395 <varlistentry>
396 <term>
397 Else:
398 </term>
399 <listitem>
400 <para>
401 <filename>development/misc</filename>
402 </para>
403 </listitem>
404 </varlistentry>
405 </variablelist>
406 </listitem>
407 </varlistentry>
408 <varlistentry>
409 <term>
410 If it’s a (set of) <emphasis>tool(s)</emphasis>:
411 </term>
412 <listitem>
413 <para>
414 (A tool is a relatively small program, especially one intended to be
415 used non-interactively.)
416 </para>
417 <variablelist>
418 <varlistentry>
419 <term>
420 If it’s for <emphasis>networking</emphasis>:
421 </term>
422 <listitem>
423 <para>
424 <filename>tools/networking</filename> (e.g.
425 <filename>wget</filename>)
426 </para>
427 </listitem>
428 </varlistentry>
429 <varlistentry>
430 <term>
431 If it’s for <emphasis>text processing</emphasis>:
432 </term>
433 <listitem>
434 <para>
435 <filename>tools/text</filename> (e.g. <filename>diffutils</filename>)
436 </para>
437 </listitem>
438 </varlistentry>
439 <varlistentry>
440 <term>
441 If it’s a <emphasis>system utility</emphasis>, i.e., something related or essential to the operation of a system:
442 </term>
443 <listitem>
444 <para>
445 <filename>tools/system</filename> (e.g. <filename>cron</filename>)
446 </para>
447 </listitem>
448 </varlistentry>
449 <varlistentry>
450 <term>
451 If it’s an <emphasis>archiver</emphasis> (which may include a compression function):
452 </term>
453 <listitem>
454 <para>
455 <filename>tools/archivers</filename> (e.g. <filename>zip</filename>,
456 <filename>tar</filename>)
457 </para>
458 </listitem>
459 </varlistentry>
460 <varlistentry>
461 <term>
462 If it’s a <emphasis>compression</emphasis> program:
463 </term>
464 <listitem>
465 <para>
466 <filename>tools/compression</filename> (e.g.
467 <filename>gzip</filename>, <filename>bzip2</filename>)
468 </para>
469 </listitem>
470 </varlistentry>
471 <varlistentry>
472 <term>
473 If it’s a <emphasis>security</emphasis>-related program:
474 </term>
475 <listitem>
476 <para>
477 <filename>tools/security</filename> (e.g. <filename>nmap</filename>,
478 <filename>gnupg</filename>)
479 </para>
480 </listitem>
481 </varlistentry>
482 <varlistentry>
483 <term>
484 Else:
485 </term>
486 <listitem>
487 <para>
488 <filename>tools/misc</filename>
489 </para>
490 </listitem>
491 </varlistentry>
492 </variablelist>
493 </listitem>
494 </varlistentry>
495 <varlistentry>
496 <term>
497 If it’s a <emphasis>shell</emphasis>:
498 </term>
499 <listitem>
500 <para>
501 <filename>shells</filename> (e.g. <filename>bash</filename>)
502 </para>
503 </listitem>
504 </varlistentry>
505 <varlistentry>
506 <term>
507 If it’s a <emphasis>server</emphasis>:
508 </term>
509 <listitem>
510 <variablelist>
511 <varlistentry>
512 <term>
513 If it’s a web server:
514 </term>
515 <listitem>
516 <para>
517 <filename>servers/http</filename> (e.g.
518 <filename>apache-httpd</filename>)
519 </para>
520 </listitem>
521 </varlistentry>
522 <varlistentry>
523 <term>
524 If it’s an implementation of the X Windowing System:
525 </term>
526 <listitem>
527 <para>
528 <filename>servers/x11</filename> (e.g. <filename>xorg</filename> —
529 this includes the client libraries and programs)
530 </para>
531 </listitem>
532 </varlistentry>
533 <varlistentry>
534 <term>
535 Else:
536 </term>
537 <listitem>
538 <para>
539 <filename>servers/misc</filename>
540 </para>
541 </listitem>
542 </varlistentry>
543 </variablelist>
544 </listitem>
545 </varlistentry>
546 <varlistentry>
547 <term>
548 If it’s a <emphasis>desktop environment</emphasis>:
549 </term>
550 <listitem>
551 <para>
552 <filename>desktops</filename> (e.g. <filename>kde</filename>,
553 <filename>gnome</filename>, <filename>enlightenment</filename>)
554 </para>
555 </listitem>
556 </varlistentry>
557 <varlistentry>
558 <term>
559 If it’s a <emphasis>window manager</emphasis>:
560 </term>
561 <listitem>
562 <para>
563 <filename>applications/window-managers</filename> (e.g.
564 <filename>awesome</filename>, <filename>stumpwm</filename>)
565 </para>
566 </listitem>
567 </varlistentry>
568 <varlistentry>
569 <term>
570 If it’s an <emphasis>application</emphasis>:
571 </term>
572 <listitem>
573 <para>
574 A (typically large) program with a distinct user interface, primarily
575 used interactively.
576 </para>
577 <variablelist>
578 <varlistentry>
579 <term>
580 If it’s a <emphasis>version management system</emphasis>:
581 </term>
582 <listitem>
583 <para>
584 <filename>applications/version-management</filename> (e.g.
585 <filename>subversion</filename>)
586 </para>
587 </listitem>
588 </varlistentry>
589 <varlistentry>
590 <term>
591 If it’s for <emphasis>video playback / editing</emphasis>:
592 </term>
593 <listitem>
594 <para>
595 <filename>applications/video</filename> (e.g.
596 <filename>vlc</filename>)
597 </para>
598 </listitem>
599 </varlistentry>
600 <varlistentry>
601 <term>
602 If it’s for <emphasis>graphics viewing / editing</emphasis>:
603 </term>
604 <listitem>
605 <para>
606 <filename>applications/graphics</filename> (e.g.
607 <filename>gimp</filename>)
608 </para>
609 </listitem>
610 </varlistentry>
611 <varlistentry>
612 <term>
613 If it’s for <emphasis>networking</emphasis>:
614 </term>
615 <listitem>
616 <variablelist>
617 <varlistentry>
618 <term>
619 If it’s a <emphasis>mailreader</emphasis>:
620 </term>
621 <listitem>
622 <para>
623 <filename>applications/networking/mailreaders</filename> (e.g.
624 <filename>thunderbird</filename>)
625 </para>
626 </listitem>
627 </varlistentry>
628 <varlistentry>
629 <term>
630 If it’s a <emphasis>newsreader</emphasis>:
631 </term>
632 <listitem>
633 <para>
634 <filename>applications/networking/newsreaders</filename> (e.g.
635 <filename>pan</filename>)
636 </para>
637 </listitem>
638 </varlistentry>
639 <varlistentry>
640 <term>
641 If it’s a <emphasis>web browser</emphasis>:
642 </term>
643 <listitem>
644 <para>
645 <filename>applications/networking/browsers</filename> (e.g.
646 <filename>firefox</filename>)
647 </para>
648 </listitem>
649 </varlistentry>
650 <varlistentry>
651 <term>
652 Else:
653 </term>
654 <listitem>
655 <para>
656 <filename>applications/networking/misc</filename>
657 </para>
658 </listitem>
659 </varlistentry>
660 </variablelist>
661 </listitem>
662 </varlistentry>
663 <varlistentry>
664 <term>
665 Else:
666 </term>
667 <listitem>
668 <para>
669 <filename>applications/misc</filename>
670 </para>
671 </listitem>
672 </varlistentry>
673 </variablelist>
674 </listitem>
675 </varlistentry>
676 <varlistentry>
677 <term>
678 If it’s <emphasis>data</emphasis> (i.e., does not have a straight-forward executable semantics):
679 </term>
680 <listitem>
681 <variablelist>
682 <varlistentry>
683 <term>
684 If it’s a <emphasis>font</emphasis>:
685 </term>
686 <listitem>
687 <para>
688 <filename>data/fonts</filename>
689 </para>
690 </listitem>
691 </varlistentry>
692 <varlistentry>
693 <term>
694 If it’s related to <emphasis>SGML/XML processing</emphasis>:
695 </term>
696 <listitem>
697 <variablelist>
698 <varlistentry>
699 <term>
700 If it’s an <emphasis>XML DTD</emphasis>:
701 </term>
702 <listitem>
703 <para>
704 <filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g.
705 <filename>docbook</filename>)
706 </para>
707 </listitem>
708 </varlistentry>
709 <varlistentry>
710 <term>
711 If it’s an <emphasis>XSLT stylesheet</emphasis>:
712 </term>
713 <listitem>
714 <para>
715 (Okay, these are executable...)
716 </para>
717 <para>
718 <filename>data/sgml+xml/stylesheets/xslt</filename> (e.g.
719 <filename>docbook-xsl</filename>)
720 </para>
721 </listitem>
722 </varlistentry>
723 </variablelist>
724 </listitem>
725 </varlistentry>
726 </variablelist>
727 </listitem>
728 </varlistentry>
729 <varlistentry>
730 <term>
731 If it’s a <emphasis>game</emphasis>:
732 </term>
733 <listitem>
734 <para>
735 <filename>games</filename>
736 </para>
737 </listitem>
738 </varlistentry>
739 <varlistentry>
740 <term>
741 Else:
742 </term>
743 <listitem>
744 <para>
745 <filename>misc</filename>
746 </para>
747 </listitem>
748 </varlistentry>
749 </variablelist>
750 </section>
751
752 <section xml:id="sec-versioning">
753 <title>Versioning</title>
754
755 <para>
756 Because every version of a package in Nixpkgs creates a potential
757 maintenance burden, old versions of a package should not be kept unless
758 there is a good reason to do so. For instance, Nixpkgs contains several
759 versions of GCC because other packages don’t build with the latest
760 version of GCC. Other examples are having both the latest stable and latest
761 pre-release version of a package, or to keep several major releases of an
762 application that differ significantly in functionality.
763 </para>
764
765 <para>
766 If there is only one version of a package, its Nix expression should be
767 named <filename>e2fsprogs/default.nix</filename>. If there are multiple
768 versions, this should be reflected in the filename, e.g.
769 <filename>e2fsprogs/1.41.8.nix</filename> and
770 <filename>e2fsprogs/1.41.9.nix</filename>. The version in the filename
771 should leave out unnecessary detail. For instance, if we keep the latest
772 Firefox 2.0.x and 3.5.x versions in Nixpkgs, they should be named
773 <filename>firefox/2.0.nix</filename> and
774 <filename>firefox/3.5.nix</filename>, respectively (which, at a given
775 point, might contain versions <literal>2.0.0.20</literal> and
776 <literal>3.5.4</literal>). If a version requires many auxiliary files, you
777 can use a subdirectory for each version, e.g.
778 <filename>firefox/2.0/default.nix</filename> and
779 <filename>firefox/3.5/default.nix</filename>.
780 </para>
781
782 <para>
783 All versions of a package <emphasis>must</emphasis> be included in
784 <filename>all-packages.nix</filename> to make sure that they evaluate
785 correctly.
786 </para>
787 </section>
788 </section>
789 <section xml:id="sec-sources">
790 <title>Fetching Sources</title>
791
792 <para>
793 There are multiple ways to fetch a package source in nixpkgs. The general
794 guideline is that you should package sources with a high degree of
795 availability. Right now there is only one fetcher which has mirroring
796 support and that is <literal>fetchurl</literal>. Note that you should also
797 prefer protocols which have a corresponding proxy environment variable.
798 </para>
799
800 <para>
801 You can find many source fetch helpers in
802 <literal>pkgs/build-support/fetch*</literal>.
803 </para>
804
805 <para>
806 In the file <literal>pkgs/top-level/all-packages.nix</literal> you can find
807 fetch helpers, these have names on the form <literal>fetchFrom*</literal>.
808 The intention of these are to provide snapshot fetches but using the same
809 api as some of the version controlled fetchers from
810 <literal>pkgs/build-support/</literal>. As an example going from bad to
811 good:
812 <itemizedlist>
813 <listitem>
814 <para>
815 Bad: Uses <literal>git://</literal> which won't be proxied.
816<programlisting>
817src = fetchgit {
818 url = "git://github.com/NixOS/nix.git";
819 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
820 sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
821}
822</programlisting>
823 </para>
824 </listitem>
825 <listitem>
826 <para>
827 Better: This is ok, but an archive fetch will still be faster.
828<programlisting>
829src = fetchgit {
830 url = "https://github.com/NixOS/nix.git";
831 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
832 sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
833}
834</programlisting>
835 </para>
836 </listitem>
837 <listitem>
838 <para>
839 Best: Fetches a snapshot archive and you get the rev you want.
840<programlisting>
841src = fetchFromGitHub {
842 owner = "NixOS";
843 repo = "nix";
844 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
845 sha256 = "04yri911rj9j19qqqn6m82266fl05pz98inasni0vxr1cf1gdgv9";
846}
847</programlisting>
848 </para>
849 </listitem>
850 </itemizedlist>
851 </para>
852 </section>
853 <section xml:id="sec-patches">
854 <title>Patches</title>
855
856 <para>
857 Patches available online should be retrieved using
858 <literal>fetchpatch</literal>.
859 </para>
860
861 <para>
862<programlisting>
863patches = [
864 (fetchpatch {
865 name = "fix-check-for-using-shared-freetype-lib.patch";
866 url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";
867 sha256 = "1f0k043rng7f0rfl9hhb89qzvvksqmkrikmm38p61yfx51l325xr";
868 })
869];
870</programlisting>
871 </para>
872
873 <para>
874 Otherwise, you can add a <literal>.patch</literal> file to the
875 <literal>nixpkgs</literal> repository. In the interest of keeping our
876 maintenance burden to a minimum, only patches that are unique to
877 <literal>nixpkgs</literal> should be added in this way.
878 </para>
879
880 <para>
881<programlisting>
882patches = [ ./0001-changes.patch ];
883</programlisting>
884 </para>
885
886 <para>
887 If you do need to do create this sort of patch file, one way to do so is
888 with git:
889 <orderedlist>
890 <listitem>
891 <para>
892 Move to the root directory of the source code you're patching.
893<screen>
894$ cd the/program/source</screen>
895 </para>
896 </listitem>
897 <listitem>
898 <para>
899 If a git repository is not already present, create one and stage all of
900 the source files.
901<screen>
902$ git init
903$ git add .</screen>
904 </para>
905 </listitem>
906 <listitem>
907 <para>
908 Edit some files to make whatever changes need to be included in the
909 patch.
910 </para>
911 </listitem>
912 <listitem>
913 <para>
914 Use git to create a diff, and pipe the output to a patch file:
915<screen>
916$ git diff > nixpkgs/pkgs/the/package/0001-changes.patch</screen>
917 </para>
918 </listitem>
919 </orderedlist>
920 </para>
921 </section>
922</chapter>