pyrox.dev
1
2<chapter xmlns="http://docbook.org/ns/docbook"
3 xmlns:xlink="http://www.w3.org/1999/xlink"
4 xml:id="chap-language-support">
5
6<title>Support for specific programming languages</title>
7
8<para>The <link linkend="chap-stdenv">standard build
9environment</link> makes it easy to build typical Autotools-based
10packages with very little code. Any other kind of package can be
11accomodated by overriding the appropriate phases of
12<literal>stdenv</literal>. However, there are specialised functions
13in Nixpkgs to easily build packages for other programming languages,
14such as Perl or Haskell. These are described in this chapter.</para>
15
16
17<section xml:id="sec-language-perl"><title>Perl</title>
18
19<para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
20a generic package builder function for any Perl package that has a
21standard <varname>Makefile.PL</varname>. It’s implemented in <link
22xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.</para>
23
24<para>Perl packages from CPAN are defined in <link
25xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,
26rather than <filename>pkgs/all-packages.nix</filename>. Most Perl
27packages are so straight-forward to build that they are defined here
28directly, rather than having a separate function for each package
29called from <filename>perl-packages.nix</filename>. However, more
30complicated packages should be put in a separate file, typically in
31<filename>pkgs/development/perl-modules</filename>. Here is an
32example of the former:
33
34<programlisting>
35ClassC3 = buildPerlPackage rec {
36 name = "Class-C3-0.21";
37 src = fetchurl {
38 url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
39 sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
40 };
41};
42</programlisting>
43
44Note the use of <literal>mirror://cpan/</literal>, and the
45<literal>${name}</literal> in the URL definition to ensure that the
46name attribute is consistent with the source that we’re actually
47downloading. Perl packages are made available in
48<filename>all-packages.nix</filename> through the variable
49<varname>perlPackages</varname>. For instance, if you have a package
50that needs <varname>ClassC3</varname>, you would typically write
51
52<programlisting>
53foo = import ../path/to/foo.nix {
54 inherit stdenv fetchurl ...;
55 inherit (perlPackages) ClassC3;
56};
57</programlisting>
58
59in <filename>all-packages.nix</filename>. You can test building a
60Perl package as follows:
61
62<screen>
63$ nix-build -A perlPackages.ClassC3
64</screen>
65
66<varname>buildPerlPackage</varname> adds <literal>perl-</literal> to
67the start of the name attribute, so the package above is actually
68called <literal>perl-Class-C3-0.21</literal>. So to install it, you
69can say:
70
71<screen>
72$ nix-env -i perl-Class-C3
73</screen>
74
75(Of course you can also install using the attribute name:
76<literal>nix-env -i -A perlPackages.ClassC3</literal>.)</para>
77
78<para>So what does <varname>buildPerlPackage</varname> do? It does
79the following:
80
81<orderedlist>
82
83 <listitem><para>In the configure phase, it calls <literal>perl
84 Makefile.PL</literal> to generate a Makefile. You can set the
85 variable <varname>makeMakerFlags</varname> to pass flags to
86 <filename>Makefile.PL</filename></para></listitem>
87
88 <listitem><para>It adds the contents of the <envar>PERL5LIB</envar>
89 environment variable to <literal>#! .../bin/perl</literal> line of
90 Perl scripts as <literal>-I<replaceable>dir</replaceable></literal>
91 flags. This ensures that a script can find its
92 dependencies.</para></listitem>
93
94 <listitem><para>In the fixup phase, it writes the propagated build
95 inputs (<varname>propagatedBuildInputs</varname>) to the file
96 <filename>$out/nix-support/propagated-user-env-packages</filename>.
97 <command>nix-env</command> recursively installs all packages listed
98 in this file when you install a package that has it. This ensures
99 that a Perl package can find its dependencies.</para></listitem>
100
101</orderedlist>
102
103</para>
104
105<para><varname>buildPerlPackage</varname> is built on top of
106<varname>stdenv</varname>, so everything can be customised in the
107usual way. For instance, the <literal>BerkeleyDB</literal> module has
108a <varname>preConfigure</varname> hook to generate a configuration
109file used by <filename>Makefile.PL</filename>:
110
111<programlisting>
112{ buildPerlPackage, fetchurl, db }:
113
114buildPerlPackage rec {
115 name = "BerkeleyDB-0.36";
116
117 src = fetchurl {
118 url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
119 sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
120 };
121
122 preConfigure = ''
123 echo "LIB = ${db}/lib" > config.in
124 echo "INCLUDE = ${db}/include" >> config.in
125 '';
126}
127</programlisting>
128
129</para>
130
131<para>Dependencies on other Perl packages can be specified in the
132<varname>buildInputs</varname> and
133<varname>propagatedBuildInputs</varname> attributes. If something is
134exclusively a build-time dependency, use
135<varname>buildInputs</varname>; if it’s (also) a runtime dependency,
136use <varname>propagatedBuildInputs</varname>. For instance, this
137builds a Perl module that has runtime dependencies on a bunch of other
138modules:
139
140<programlisting>
141ClassC3Componentised = buildPerlPackage rec {
142 name = "Class-C3-Componentised-1.0004";
143 src = fetchurl {
144 url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
145 sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
146 };
147 propagatedBuildInputs = [
148 ClassC3 ClassInspector TestException MROCompat
149 ];
150};
151</programlisting>
152
153</para>
154
155<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title>
156
157<para>Nix expressions for Perl packages can be generated (almost)
158automatically from CPAN. This is done by the program
159<command>nix-generate-from-cpan</command>, which can be installed
160as follows:</para>
161
162<screen>
163$ nix-env -i nix-generate-from-cpan
164</screen>
165
166<para>This program takes a Perl module name, looks it up on CPAN,
167fetches and unpacks the corresponding package, and prints a Nix
168expression on standard output. For example:
169
170<screen>
171$ nix-generate-from-cpan XML::Simple
172 XMLSimple = buildPerlPackage {
173 name = "XML-Simple-2.20";
174 src = fetchurl {
175 url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
176 sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
177 };
178 propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
179 meta = {
180 description = "Easily read/write XML (esp config files)";
181 license = "perl";
182 };
183 };
184</screen>
185
186The output can be pasted into
187<filename>pkgs/top-level/perl-packages.nix</filename> or wherever else
188you need it.</para>
189
190</section>
191
192</section>
193
194
195<section xml:id="sec-python"><title>Python</title>
196
197<para>
198 Currently supported interpreters are <varname>python26</varname>, <varname>python27</varname>,
199 <varname>python32</varname>, <varname>python33</varname>, <varname>python34</varname>
200 and <varname>pypy</varname>.
201</para>
202
203<para>
204 <varname>python</varname> is an alias of <varname>python27</varname> and <varname>python3</varname> is an alias of <varname>python34</varname>.
205</para>
206
207<para>
208 <varname>python26</varname> and <varname>python27</varname> do not include modules that require
209 external dependencies (to reduce dependency bloat). Following modules need to be added as
210 <varname>buildInput</varname> explicitly:
211</para>
212
213<itemizedlist>
214 <listitem><para><varname>python.modules.bsddb</varname></para></listitem>
215 <listitem><para><varname>python.modules.curses</varname></para></listitem>
216 <listitem><para><varname>python.modules.curses_panel</varname></para></listitem>
217 <listitem><para><varname>python.modules.crypt</varname></para></listitem>
218 <listitem><para><varname>python.modules.gdbm</varname></para></listitem>
219 <listitem><para><varname>python.modules.sqlite3</varname></para></listitem>
220 <listitem><para><varname>python.modules.tkinter</varname></para></listitem>
221 <listitem><para><varname>python.modules.readline</varname></para></listitem>
222</itemizedlist>
223
224<para>For convenience <varname>python27Full</varname> and <varname>python26Full</varname>
225are provided with all modules included.</para>
226
227<para>
228 Python packages that
229 use <link xlink:href="http://pypi.python.org/pypi/setuptools/"><literal>setuptools</literal></link> or <literal>distutils</literal>,
230 can be built using the <varname>buildPythonPackage</varname> function as documented below.
231</para>
232
233<para>
234 All packages depending on any Python interpreter get appended <varname>$out/${python.libPrefix}/site-packages</varname>
235 to <literal>$PYTHONPATH</literal> if such directory exists.
236</para>
237
238<variablelist>
239 <title>
240 Useful attributes on interpreters packages:
241 </title>
242
243 <varlistentry>
244 <term><varname>libPrefix</varname></term>
245 <listitem><para>
246 Name of the folder in <literal>${python}/lib/</literal> for corresponding interpreter.
247 </para></listitem>
248 </varlistentry>
249
250 <varlistentry>
251 <term><varname>interpreter</varname></term>
252 <listitem><para>
253 Alias for <literal>${python}/bin/${executable}.</literal>
254 </para></listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term><varname>buildEnv</varname></term>
259 <listitem><para>
260 Function to build python interpreter environments with extra packages bundled together.
261 See <xref linkend="ssec-python-build-env" /> for usage and documentation.
262 </para></listitem>
263 </varlistentry>
264
265 <varlistentry>
266 <term><varname>sitePackages</varname></term>
267 <listitem><para>
268 Alias for <literal>lib/${libPrefix}/site-packages</literal>.
269 </para></listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><varname>executable</varname></term>
274 <listitem><para>
275 Name of the interpreter executable, ie <literal>python3.4</literal>.
276 </para></listitem>
277 </varlistentry>
278
279</variablelist>
280<section xml:id="ssec-build-python-package"><title><varname>buildPythonPackage</varname> function</title>
281
282 <para>
283 The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
284 <filename>pkgs/development/python-modules/generic/default.nix</filename></link>.
285 Example usage:
286
287<programlisting language="nix">
288twisted = buildPythonPackage {
289 name = "twisted-8.1.0";
290
291 src = pkgs.fetchurl {
292 url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
293 sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
294 };
295
296 propagatedBuildInputs = [ self.ZopeInterface ];
297
298 meta = {
299 homepage = http://twistedmatrix.com/;
300 description = "Twisted, an event-driven networking engine written in Python";
301 license = stdenv.lib.licenses.mit;
302 };
303};
304</programlisting>
305
306 Most of Python packages that use <varname>buildPythonPackage</varname> are defined
307 in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
308 and generated for each python interpreter separately into attribute sets <varname>python26Packages</varname>,
309 <varname>python27Packages</varname>, <varname>python32Packages</varname>, <varname>python33Packages</varname>,
310 <varname>python34Packages</varname> and <varname>pypyPackages</varname>.
311 </para>
312
313 <para>
314 <function>buildPythonPackage</function> mainly does four things:
315
316 <orderedlist>
317 <listitem><para>
318 In the <varname>configurePhase</varname>, it patches
319 <literal>setup.py</literal> to always include setuptools before
320 distutils for monkeypatching machinery to take place.
321 </para></listitem>
322
323 <listitem><para>
324 In the <varname>buildPhase</varname>, it calls
325 <literal>${python.interpreter} setup.py build ...</literal>
326 </para></listitem>
327
328 <listitem><para>
329 In the <varname>installPhase</varname>, it calls
330 <literal>${python.interpreter} setup.py install ...</literal>
331 </para></listitem>
332
333 <listitem><para>
334 In the <varname>postFixup</varname> phase, <literal>wrapPythonPrograms</literal>
335 bash function is called to wrap all programs in <filename>$out/bin/*</filename>
336 directory to include <literal>$PYTHONPATH</literal> and <literal>$PATH</literal>
337 environment variables.
338 </para></listitem>
339 </orderedlist>
340 </para>
341
342 <para>By default <varname>doCheck = true</varname> is set and tests are run with
343 <literal>${python.interpreter} setup.py test</literal> command in <varname>checkPhase</varname>.</para>
344
345 <para>
346 As in Perl, dependencies on other Python packages can be specified in the
347 <varname>buildInputs</varname> and
348 <varname>propagatedBuildInputs</varname> attributes. If something is
349 exclusively a build-time dependency, use
350 <varname>buildInputs</varname>; if it’s (also) a runtime dependency,
351 use <varname>propagatedBuildInputs</varname>.
352 </para>
353
354 <para>
355 By default <varname>meta.platforms</varname> is set to the same value
356 as the interpreter unless overriden otherwise.
357 </para>
358
359 <variablelist>
360 <title>
361 <varname>buildPythonPackage</varname> parameters
362 (all parameters from <varname>mkDerivation</varname> function are still supported)
363 </title>
364
365 <varlistentry>
366 <term><varname>namePrefix</varname></term>
367 <listitem><para>
368 Prepended text to <varname>${name}</varname> parameter.
369 Defaults to <literal>"python3.3-"</literal> for Python 3.3, etc. Set it to
370 <literal>""</literal>
371 if you're packaging an application or a command line tool.
372 </para></listitem>
373 </varlistentry>
374
375 <varlistentry>
376 <term><varname>disabled</varname></term>
377 <listitem><para>
378 If <varname>true</varname>, package is not build for
379 particular python interpreter version. Grep around
380 <filename>pkgs/top-level/python-packages.nix</filename>
381 for examples.
382 </para></listitem>
383 </varlistentry>
384
385 <varlistentry>
386 <term><varname>setupPyInstallFlags</varname></term>
387 <listitem><para>
388 List of flags passed to <command>setup.py install</command> command.
389 </para></listitem>
390 </varlistentry>
391
392 <varlistentry>
393 <term><varname>setupPyBuildFlags</varname></term>
394 <listitem><para>
395 List of flags passed to <command>setup.py build</command> command.
396 </para></listitem>
397 </varlistentry>
398
399 <varlistentry>
400 <term><varname>pythonPath</varname></term>
401 <listitem><para>
402 List of packages to be added into <literal>$PYTHONPATH</literal>.
403 Packages in <varname>pythonPath</varname> are not propagated into user environment
404 (contrary to <varname>propagatedBuildInputs</varname>).
405 </para></listitem>
406 </varlistentry>
407
408 <varlistentry>
409 <term><varname>preShellHook</varname></term>
410 <listitem><para>
411 Hook to execute commands before <varname>shellHook</varname>.
412 </para></listitem>
413 </varlistentry>
414
415 <varlistentry>
416 <term><varname>postShellHook</varname></term>
417 <listitem><para>
418 Hook to execute commands after <varname>shellHook</varname>.
419 </para></listitem>
420 </varlistentry>
421
422 <varlistentry>
423 <term><varname>distutilsExtraCfg</varname></term>
424 <listitem><para>
425 Extra lines passed to <varname>[easy_install]</varname> section of
426 <filename>distutils.cfg</filename> (acts as global setup.cfg
427 configuration).
428 </para></listitem>
429 </varlistentry>
430
431 <varlistentry>
432 <term><varname>makeWrapperArgs</varname></term>
433 <listitem><para>
434 A list of strings. Arguments to be passed to
435 <varname>makeWrapper</varname>, which wraps generated binaries. By
436 default, the arguments to <varname>makeWrapper</varname> set
437 <varname>PATH</varname> and <varname>PYTHONPATH</varname> environment
438 variables before calling the binary. Additional arguments here can
439 allow a developer to set environment variables which will be
440 available when the binary is run. For example,
441 <varname>makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]</varname>.
442 </para></listitem>
443 </varlistentry>
444
445 </variablelist>
446
447</section>
448
449<section xml:id="ssec-python-build-env"><title><function>python.buildEnv</function> function</title>
450 <para>
451 Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
452
453<programlisting language="nix">
454<![CDATA[with import <nixpkgs> {};
455
456python.buildEnv.override {
457 extraLibs = [ pkgs.pythonPackages.pyramid ];
458 ignoreCollisions = true;
459}]]>
460</programlisting>
461
462 Running <command>nix-build</command> will create
463 <filename>/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename>
464 with wrapped binaries in <filename>bin/</filename>.
465 </para>
466
467 <para>
468 You can also use <varname>env</varname> attribute to create local
469 environments with needed packages installed (somewhat comparable to
470 <literal>virtualenv</literal>). For example, with the following
471 <filename>shell.nix</filename>:
472
473<programlisting language="nix">
474<![CDATA[with import <nixpkgs> {};
475
476(python3.buildEnv.override {
477 extraLibs = with python3Packages;
478 [ numpy
479 requests
480 ];
481}).env]]>
482</programlisting>
483
484 Running <command>nix-shell</command> will drop you into a shell where
485 <command>python</command> will have specified packages in its path.
486 </para>
487
488 <variablelist>
489 <title>
490 <function>python.buildEnv</function> arguments
491 </title>
492
493 <varlistentry>
494 <term><varname>extraLibs</varname></term>
495 <listitem><para>
496 List of packages installed inside the environment.
497 </para></listitem>
498 </varlistentry>
499
500 <varlistentry>
501 <term><varname>postBuild</varname></term>
502 <listitem><para>
503 Shell command executed after the build of environment.
504 </para></listitem>
505 </varlistentry>
506
507 <varlistentry>
508 <term><varname>ignoreCollisions</varname></term>
509 <listitem><para>
510 Ignore file collisions inside the environment (default is <varname>false</varname>).
511 </para></listitem>
512 </varlistentry>
513 </variablelist>
514</section>
515
516<section xml:id="ssec-python-tools"><title>Tools</title>
517
518<para>Packages inside nixpkgs are written by hand. However many tools
519exist in community to help save time. No tool is preferred at the moment.
520</para>
521
522<itemizedlist>
523
524 <listitem><para>
525 <link xlink:href="https://github.com/proger/python2nix">python2nix</link>
526 by Vladimir Kirillov
527 </para></listitem>
528
529 <listitem><para>
530 <link xlink:href="https://github.com/garbas/pypi2nix">pypi2nix</link>
531 by Rok Garbas
532 </para></listitem>
533
534 <listitem><para>
535 <link xlink:href="https://github.com/offlinehacker/pypi2nix">pypi2nix</link>
536 by Jaka Hudoklin
537 </para></listitem>
538
539</itemizedlist>
540
541</section>
542
543<section xml:id="ssec-python-development"><title>Development</title>
544
545 <para>
546 To develop Python packages <function>buildPythonPackage</function> has
547 additional logic inside <varname>shellPhase</varname> to run
548 <command>${python.interpreter} setup.py develop</command> for the package.
549 </para>
550
551 <warning><para><varname>shellPhase</varname> is executed only if <filename>setup.py</filename>
552 exists.</para></warning>
553
554 <para>
555 Given a <filename>default.nix</filename>:
556
557<programlisting language="nix">
558<![CDATA[with import <nixpkgs> {};
559
560buildPythonPackage {
561 name = "myproject";
562
563 buildInputs = with pkgs.pythonPackages; [ pyramid ];
564
565 src = ./.;
566}]]>
567</programlisting>
568
569 Running <command>nix-shell</command> with no arguments should give you
570 the environment in which the package would be build with
571 <command>nix-build</command>.
572 </para>
573
574 <para>
575 Shortcut to setup environments with C headers/libraries and python packages:
576
577 <programlisting language="bash">$ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting>
578 </para>
579
580 <note><para>
581 There is a boolean value <varname>lib.inNixShell</varname> set to
582 <varname>true</varname> if nix-shell is invoked.
583 </para></note>
584
585</section>
586
587<section xml:id="ssec-python-faq"><title>FAQ</title>
588
589<variablelist>
590
591 <varlistentry>
592 <term>How to solve circular dependencies?</term>
593 <listitem><para>
594 If you have packages <varname>A</varname> and <varname>B</varname> that
595 depend on each other, when packaging <varname>B</varname> override package
596 <varname>A</varname> not to depend on <varname>B</varname> as input
597 (and also the other way around).
598 </para></listitem>
599 </varlistentry>
600
601 <varlistentry>
602 <term><varname>install_data / data_files</varname> problems resulting into <literal>error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied</literal></term>
603 <listitem><para>
604 <link xlink:href="https://bitbucket.org/pypa/setuptools/issue/130/install_data-doesnt-respect-prefix">
605 Known bug in setuptools <varname>install_data</varname> does not respect --prefix</link>. Example of
606 such package using the feature is <filename>pkgs/tools/X11/xpra/default.nix</filename>. As workaround
607 install it as an extra <varname>preInstall</varname> step:
608
609 <programlisting>${python.interpreter} setup.py install_data --install-dir=$out --root=$out
610sed -i '/ = data_files/d' setup.py</programlisting>
611 </para></listitem>
612 </varlistentry>
613
614 <varlistentry>
615 <term>Rationale of non-existent global site-packages</term>
616 <listitem><para>
617 There is no need to have global site-packages in Nix. Each package has isolated
618 dependency tree and installing any python package will only populate <varname>$PATH</varname>
619 inside user environment. See <xref linkend="ssec-python-build-env" /> to create self-contained
620 interpreter with a set of packages.
621 </para></listitem>
622 </varlistentry>
623
624</variablelist>
625
626</section>
627
628
629<section xml:id="ssec-python-contrib"><title>Contributing guidelines</title>
630<para>
631 Following rules are desired to be respected:
632</para>
633
634<itemizedlist>
635
636 <listitem><para>
637 Make sure package builds for all python interpreters. Use <varname>disabled</varname> argument to
638 <function>buildPythonPackage</function> to set unsupported interpreters.
639 </para></listitem>
640
641 <listitem><para>
642 If tests need to be disabled for a package, make sure you leave a comment about reasoning.
643 </para></listitem>
644
645 <listitem><para>
646 Packages in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
647 are sorted quasi-alphabetically to avoid merge conflicts.
648 </para></listitem>
649
650</itemizedlist>
651
652</section>
653
654</section>
655
656
657<section xml:id="sec-language-ruby"><title>Ruby</title>
658 <para>There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert
659 this into a nix expression that contains all Gem dependencies automatically.</para>
660
661 <para>For example, to package sensu, we did:</para>
662
663<screen>
664<![CDATA[$ cd pkgs/servers/monitoring
665$ mkdir sensu
666$ cat > Gemfile
667source 'https://rubygems.org'
668gem 'sensu'
669$ bundler package --path /tmp/vendor/bundle
670$ $(nix-build '<nixpkgs>' -A bundix)/bin/bundix
671$ cat > default.nix
672{ lib, bundlerEnv, ruby }:
673
674bundlerEnv {
675 name = "sensu-0.17.1";
676
677 inherit ruby;
678 gemfile = ./Gemfile;
679 lockfile = ./Gemfile.lock;
680 gemset = ./gemset.nix;
681
682 meta = with lib; {
683 description = "A monitoring framework that aims to be simple, malleable,
684and scalable.";
685 homepage = http://sensuapp.org/;
686 license = with licenses; mit;
687 maintainers = with maintainers; [ theuni ];
688 platforms = platforms.unix;
689 };
690}]]>
691</screen>
692
693<para>Please check in the <filename>Gemfile</filename>, <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so future updates can be run easily.
694</para>
695
696</section>
697
698<section xml:id="sec-language-go"><title>Go</title>
699
700<para>The function <varname>buildGoPackage</varname> builds
701standard Go packages.
702</para>
703
704<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
705<programlisting>
706net = buildGoPackage rec {
707 name = "go.net-${rev}";
708 goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
709 subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
710 rev = "e0403b4e005";
711 src = fetchFromGitHub {
712 inherit rev;
713 owner = "golang";
714 repo = "net";
715 sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
716 };
717 goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
718 propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
719 buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
720 disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
721};
722</programlisting>
723</example>
724
725<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage,
726the following arguments are of special significance to the function:
727
728<calloutlist>
729
730 <callout arearefs='ex-buildGoPackage-1'>
731 <para>
732 <varname>goPackagePath</varname> specifies the package's canonical Go import path.
733 </para>
734 </callout>
735
736 <callout arearefs='ex-buildGoPackage-2'>
737 <para>
738 <varname>subPackages</varname> limits the builder from building child packages that
739 have not been listed. If <varname>subPackages</varname> is not specified, all child
740 packages will be built.
741 </para>
742 <para>
743 In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
744 <literal>code.google.com/p/go.net/ipv4</literal> will be built.
745 </para>
746 </callout>
747
748 <callout arearefs='ex-buildGoPackage-3'>
749 <para>
750 <varname>goPackageAliases</varname> is a list of alternative import paths
751 that are valid for this library.
752 Packages that depend on this library will automatically rename
753 import paths that match any of the aliases to <literal>goPackagePath</literal>.
754 </para>
755 <para>
756 In this example imports will be renamed from
757 <literal>code.google.com/p/go.net</literal> to
758 <literal>golang.org/x/net</literal> in every package that depend on the
759 <literal>go.net</literal> library.
760 </para>
761 </callout>
762
763 <callout arearefs='ex-buildGoPackage-4'>
764 <para>
765 <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
766 listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
767 program is being build instead, use <varname>buildInputs</varname>. If a library's tests require
768 additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
769 </para>
770 </callout>
771
772 <callout arearefs='ex-buildGoPackage-5'>
773 <para>
774 <varname>buildFlags</varname> is a list of flags passed to the go build command.
775 </para>
776 </callout>
777
778 <callout arearefs='ex-buildGoPackage-6'>
779 <para>
780 If <varname>disabled</varname> is <literal>true</literal>,
781 nix will refuse to build this package.
782 </para>
783 <para>
784 In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
785 is an utility function that returns <literal>true</literal> if go used to build the
786 package has version 1.3.x.
787 </para>
788 </callout>
789
790</calloutlist>
791
792</para>
793
794<para>
795Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
796build a Go package as follows:
797
798<screen>
799$ nix-build -A goPackages.net
800</screen>
801
802</para>
803
804<para>
805You may use Go packages installed into the active Nix profiles by adding
806the following to your ~/.bashrc:
807
808<screen>
809for p in $NIX_PROFILES; do
810 GOPATH="$p/share/go:$GOPATH"
811done
812</screen>
813</para>
814
815 <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para>
816</section>
817
818
819<section xml:id="sec-language-java"><title>Java</title>
820
821<para>Ant-based Java packages are typically built from source as follows:
822
823<programlisting>
824stdenv.mkDerivation {
825 name = "...";
826 src = fetchurl { ... };
827
828 buildInputs = [ jdk ant ];
829
830 buildPhase = "ant";
831}
832</programlisting>
833
834Note that <varname>jdk</varname> is an alias for the OpenJDK.</para>
835
836<para>JAR files that are intended to be used by other packages should
837be installed in <filename>$out/share/java</filename>. The OpenJDK has
838a stdenv setup hook that adds any JARs in the
839<filename>share/java</filename> directories of the build inputs to the
840<envar>CLASSPATH</envar> environment variable. For instance, if the
841package <literal>libfoo</literal> installs a JAR named
842<filename>foo.jar</filename> in its <filename>share/java</filename>
843directory, and another package declares the attribute
844
845<programlisting>
846buildInputs = [ jdk libfoo ];
847</programlisting>
848
849then <envar>CLASSPATH</envar> will be set to
850<filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.</para>
851
852<para>Private JARs
853should be installed in a location like
854<filename>$out/share/<replaceable>package-name</replaceable></filename>.</para>
855
856<para>If your Java package provides a program, you need to generate a
857wrapper script to run it using the OpenJRE. You can use
858<literal>makeWrapper</literal> for this:
859
860<programlisting>
861buildInputs = [ makeWrapper ];
862
863installPhase =
864 ''
865 mkdir -p $out/bin
866 makeWrapper ${jre}/bin/java $out/bin/foo \
867 --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
868 '';
869</programlisting>
870
871Note the use of <literal>jre</literal>, which is the part of the
872OpenJDK package that contains the Java Runtime Environment. By using
873<literal>${jre}/bin/java</literal> instead of
874<literal>${jdk}/bin/java</literal>, you prevent your package from
875depending on the JDK at runtime.</para>
876
877<para>It is possible to use a different Java compiler than
878<command>javac</command> from the OpenJDK. For instance, to use the
879Eclipse Java Compiler:
880
881<programlisting>
882buildInputs = [ jre ant ecj ];
883</programlisting>
884
885(Note that here you don’t need the full JDK as an input, but just the
886JRE.) The ECJ has a stdenv setup hook that sets some environment
887variables to cause Ant to use ECJ, but this doesn’t work with all Ant
888files. Similarly, you can use the GNU Java Compiler:
889
890<programlisting>
891buildInputs = [ gcj ant ];
892</programlisting>
893
894Here, Ant will automatically use <command>gij</command> (the GNU Java
895Runtime) instead of the OpenJRE.</para>
896
897</section>
898
899
900<section xml:id="sec-language-lua"><title>Lua</title>
901
902<para>
903 Lua packages are built by the <varname>buildLuaPackage</varname> function. This function is
904 implemented
905 in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">
906 <filename>pkgs/development/lua-modules/generic/default.nix</filename></link>
907 and works similarly to <varname>buildPerlPackage</varname>. (See
908 <xref linkend="sec-language-perl"/> for details.)
909</para>
910
911<para>
912 Lua packages are defined
913 in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.
914 Most of them are simple. For example:
915
916 <programlisting>
917fileSystem = buildLuaPackage {
918 name = "filesystem-1.6.2";
919 src = fetchurl {
920 url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
921 sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
922 };
923 meta = {
924 homepage = "https://github.com/keplerproject/luafilesystem";
925 hydraPlatforms = stdenv.lib.platforms.linux;
926 maintainers = with maintainers; [ flosse ];
927 };
928};
929 </programlisting>
930</para>
931
932<para>
933 Though, more complicated package should be placed in a seperate file in
934 <link
935 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
936</para>
937<para>
938 Lua packages accept additional parameter <varname>disabled</varname>, which defines
939 the condition of disabling package from luaPackages. For example, if package has
940 <varname>disabled</varname> assigned to <literal>lua.luaversion != "5.1"</literal>,
941 it will not be included in any luaPackages except lua51Packages, making it
942 only be built for lua 5.1.
943</para>
944
945</section>
946
947<section xml:id="sec-language-coq"><title>Coq</title>
948 <para>
949 Coq libraries should be installed in
950 <literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>.
951 Such directories are automatically added to the
952 <literal>$COQPATH</literal> environment variable by the hook defined
953 in the Coq derivation.
954 </para>
955 <para>
956 Some libraries require OCaml and sometimes also Camlp5. The exact
957 versions that were used to build Coq are saved in the
958 <literal>coq.ocaml</literal> and <literal>coq.camlp5</literal>
959 attributes.
960 </para>
961 <para>
962 Here is a simple package example. It is a pure Coq library, thus it
963 only depends on Coq. Its <literal>makefile</literal> has been
964 generated using <literal>coq_makefile</literal> so we only have to
965 set the <literal>$COQLIB</literal> variable at install time.
966 </para>
967 <programlisting>
968{stdenv, fetchurl, coq}:
969stdenv.mkDerivation {
970 src = fetchurl {
971 url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
972 sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
973 };
974
975 name = "coq-karatsuba";
976
977 buildInputs = [ coq ];
978
979 installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
980}
981</programlisting>
982</section>
983
984<!--
985<section><title>Haskell</title>
986
987<para>TODO</para>
988
989</section>
990
991
992<section><title>TeX / LaTeX</title>
993
994<para>* Special support for building TeX documents</para>
995
996</section>
997-->
998
999
1000</chapter>