lix/doc/manual/expressions/generic-builder.xml

<section xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      version="5.0"
      xml:id='sec-generic-builder'>

<title>Generic Builder Syntax</title>

<para>Recall from <xref linkend='ex-hello-builder' /> that the builder
looked something like this:

<programlisting>
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install</programlisting>

The builders for almost all Unix packages look like this — set up some
environment variables, unpack the sources, configure, build, and
install.  For this reason the standard environment provides some Bash
functions that automate the build process.  Here is what a builder
using the generic build facilities looks like:</para>

<programlisting>
buildInputs="$perl" ①

source $stdenv/setup ②

genericBuild ③</programlisting>

<para>Here is what each line means:

<orderedlist>

  <listitem>

    <para>The <literal>buildInputs</literal> variable tells
    <filename>setup</filename> to use the indicated packages as
    <quote>inputs</quote>.  This means that if a package provides a
    <filename>bin</filename> subdirectory, it's added to
    <literal>PATH</literal>; if it has a <filename>include</filename>
    subdirectory, it's added to GCC's header search path; and so
    on.<footnote><para>How does it work? <filename>setup</filename>
    tries to source the file
    <filename><emphasis>pkg</emphasis>/nix-support/setup-hook</filename>
    of all dependencies.  These “setup hooks” can then set up whatever
    environment variables they want; for instance, the setup hook for
    Perl sets the <literal>PERL5LIB</literal> environment variable to
    contain the <filename>lib/site_perl</filename> directories of all
    inputs.</para></footnote>
    </para>

  </listitem>

  <listitem arearefs='ex-hello-builder2-co-2'>

    <para>The function <function>genericBuild</function> is defined in
    the file <literal>$stdenv/setup</literal>.</para>

  </listitem>

  <listitem arearefs='ex-hello-builder2-co-3'>

    <para>The final step calls the shell function
    <function>genericBuild</function>, which performs the steps that
    were done explicitly in <xref linkend='ex-hello-builder' />.  The
    generic builder is smart enough to figure out whether to unpack
    the sources using <command>gzip</command>,
    <command>bzip2</command>, etc.  It can be customised in many ways;
    see the Nixpkgs manual for details.</para>

  </listitem>

</orderedlist>

</para>

<para>Discerning readers will note that the
<literal>buildInputs</literal> could just as well have been set in the Nix
expression, like this:

<programlisting>
  buildInputs = [ perl ];</programlisting>

The <varname>perl</varname> attribute can then be removed, and the
builder becomes even shorter:

<programlisting>
source $stdenv/setup
genericBuild</programlisting>

In fact, <varname>mkDerivation</varname> provides a default builder
that looks exactly like that, so it is actually possible to omit the
builder for Hello entirely.</para>

</section>