nix-super/doc/manual/expressions/expression-syntax.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-expression-syntax'>

<title>Expression Syntax</title>

<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
(<filename>default.nix</filename>)</title>
<programlisting>
{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' />

stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' />
  name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' />
  builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' />
  src = fetchurl { <co xml:id='ex-hello-nix-co-5' />
    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
  };
  inherit perl; <co xml:id='ex-hello-nix-co-6' />
}</programlisting>
</example>

<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU
Hello.  It's actually already in the Nix Packages collection in
<filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>.
It is customary to place each package in a separate directory and call
the single Nix expression in that directory
<filename>default.nix</filename>.  The file has the following elements
(referenced from the figure by number):

<calloutlist>

  <callout arearefs='ex-hello-nix-co-1'>

    <para>This states that the expression is a
    <emphasis>function</emphasis> that expects to be called with three
    arguments: <varname>stdenv</varname>, <varname>fetchurl</varname>,
    and <varname>perl</varname>.  They are needed to build Hello, but
    we don't know how to build them here; that's why they are function
    arguments.  <varname>stdenv</varname> is a package that is used
    by almost all Nix Packages packages; it provides a
    <quote>standard</quote> environment consisting of the things you
    would expect in a basic Unix environment: a C/C++ compiler (GCC,
    to be precise), the Bash shell, fundamental Unix tools such as
    <command>cp</command>, <command>grep</command>,
    <command>tar</command>, etc.  <varname>fetchurl</varname> is a
    function that downloads files.  <varname>perl</varname> is the
    Perl interpreter.</para>

    <para>Nix functions generally have the form <literal>{ x, y, ...,
    z }: e</literal> where <varname>x</varname>, <varname>y</varname>,
    etc. are the names of the expected arguments, and where
    <replaceable>e</replaceable> is the body of the function.  So
    here, the entire remainder of the file is the body of the
    function; when given the required arguments, the body should
    describe how to build an instance of the Hello package.</para>

  </callout>

  <callout arearefs='ex-hello-nix-co-2'>

    <para>So we have to build a package.  Building something from
    other stuff is called a <emphasis>derivation</emphasis> in Nix (as
    opposed to sources, which are built by humans instead of
    computers).  We perform a derivation by calling
    <varname>stdenv.mkDerivation</varname>.
    <varname>mkDerivation</varname> is a function provided by
    <varname>stdenv</varname> that builds a package from a set of
    <emphasis>attributes</emphasis>.  A set is just a list of
    key/value pairs where each key is a string and each value is an
    arbitrary Nix expression.  They take the general form <literal>{
    <replaceable>name1</replaceable> =
    <replaceable>expr1</replaceable>; <replaceable>...</replaceable>
    <replaceable>nameN</replaceable> =
    <replaceable>exprN</replaceable>; }</literal>.</para>

  </callout>

  <callout arearefs='ex-hello-nix-co-3'>

    <para>The attribute <varname>name</varname> specifies the symbolic
    name and version of the package.  Nix doesn't really care about
    these things, but they are used by for instance <command>nix-env
    -q</command> to show a <quote>human-readable</quote> name for
    packages.  This attribute is required by
    <varname>mkDerivation</varname>.</para>

  </callout>

  <callout arearefs='ex-hello-nix-co-4'>

    <para>The attribute <varname>builder</varname> specifies the
    builder.  This attribute can sometimes be omitted, in which case
    <varname>mkDerivation</varname> will fill in a default builder
    (which does a <literal>configure; make; make install</literal>, in
    essence).  Hello is sufficiently simple that the default builder
    would suffice, but in this case, we will show an actual builder
    for educational purposes.  The value
    <command>./builder.sh</command> refers to the shell script shown
    in <xref linkend='ex-hello-builder' />, discussed below.</para>

  </callout>

  <callout arearefs='ex-hello-nix-co-5'>

    <para>The builder has to know what the sources of the package
    are.  Here, the attribute <varname>src</varname> is bound to the
    result of a call to the <command>fetchurl</command> function.
    Given a URL and an MD5 hash of the expected contents of the file
    at that URL, this function builds a derivation that downloads the
    file and checks its hash.  So the sources are a dependency that
    like all other dependencies is built before Hello itself is
    built.</para>

    <para>Instead of <varname>src</varname> any other name could have
    been used, and in fact there can be any number of sources (bound
    to different attributes).  However, <varname>src</varname> is
    customary, and it's also expected by the default builder (which we
    don't use in this example).</para>

  </callout>

  <callout arearefs='ex-hello-nix-co-6'>

    <para>Since the derivation requires Perl, we have to pass the
    value of the <varname>perl</varname> function argument to the
    builder.  All attributes in the set are actually passed as
    environment variables to the builder, so declaring an attribute

    <programlisting>
perl = perl;</programlisting>

    will do the trick: it binds an attribute <varname>perl</varname>
    to the function argument which also happens to be called
    <varname>perl</varname>.  However, it looks a bit silly, so there
    is a shorter syntax.  The <literal>inherit</literal> keyword
    causes the specified attributes to be bound to whatever variables
    with the same name happen to be in scope.</para>

  </callout>

</calloutlist>

</para>

</section>