nixpkgs/doc/functions/trivial-builders.xml
2019-03-08 21:07:11 -08:00

114 lines
4.1 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-trivial-builders">
<title>Trivial builders</title>
<para>
Nixpkgs provides a couple of functions that help with building derivations.
The most important one, <function>stdenv.mkDerivation</function>, has already
been documented above. The following functions wrap
<function>stdenv.mkDerivation</function>, making it easier to use in certain
cases.
</para>
<variablelist>
<varlistentry>
<term>
<literal>runCommand</literal>
</term>
<listitem>
<para>
This takes three arguments, <literal>name</literal>,
<literal>env</literal>, and <literal>buildCommand</literal>.
<literal>name</literal> is just the name that Nix will append to the store
path in the same way that <literal>stdenv.mkDerivation</literal> uses its
<literal>name</literal> attribute. <literal>env</literal> is an attribute
set specifying environment variables that will be set for this derivation.
These attributes are then passed to the wrapped
<literal>stdenv.mkDerivation</literal>. <literal>buildCommand</literal>
specifies the commands that will be run to create this derivation. Note
that you will need to create <literal>$out</literal> for Nix to register
the command as successful.
</para>
<para>
An example of using <literal>runCommand</literal> is provided below.
</para>
<programlisting>
(import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
echo My example command is running
mkdir $out
echo I can write data to the Nix store > $out/message
echo I can also run basic commands like:
echo ls
ls
echo whoami
whoami
echo date
date
''
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>runCommandCC</literal>
</term>
<listitem>
<para>
This works just like <literal>runCommand</literal>. The only difference is
that it also provides a C compiler in <literal>buildCommand</literal>s
environment. To minimize your dependencies, you should only use this if
you are sure you will need a C compiler as part of running your command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal>
</term>
<listitem>
<para>
These functions write <literal>text</literal> to the Nix store. This is
useful for creating scripts from Nix expressions.
<literal>writeTextFile</literal> takes an attribute set and expects two
arguments, <literal>name</literal> and <literal>text</literal>.
<literal>name</literal> corresponds to the name used in the Nix store
path. <literal>text</literal> will be the contents of the file. You can
also set <literal>executable</literal> to true to make this file have the
executable bit set.
</para>
<para>
Many more commands wrap <literal>writeTextFile</literal> including
<literal>writeText</literal>, <literal>writeTextDir</literal>,
<literal>writeScript</literal>, and <literal>writeScriptBin</literal>.
These are convenience functions over <literal>writeTextFile</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>symlinkJoin</literal>
</term>
<listitem>
<para>
This can be used to put many derivations into the same directory
structure. It works by creating a new derivation and adding symlinks to
each of the paths listed. It expects two arguments,
<literal>name</literal>, and <literal>paths</literal>.
<literal>name</literal> is the name used in the Nix store path for the
created derivation. <literal>paths</literal> is a list of paths that will
be symlinked. These paths can be to Nix store derivations or any other
subdirectory contained within.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>