path: root/doc/manual/command-ref/nix-install-package.xml

<refentry 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-nix-install-package">

<refmeta>
  <refentrytitle>nix-install-package</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
</refmeta>

<refnamediv>
  <refname>nix-install-package</refname>
  <refpurpose>install a Nix Package file</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-install-package</command>
    <arg><option>--non-interactive</option></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--profile</option></arg>
        <arg choice='plain'><option>-p</option></arg>
      </group>
      <replaceable>path</replaceable>
    </arg>
    <arg><option>--set</option></arg>
    <sbr />
    <group choice='req'>
      <arg choice='req'>
        <option>--url</option>
        <arg choice='plain'><replaceable>url</replaceable></arg>
      </arg>
      <arg choice='req'>
        <arg choice='plain'><replaceable>file</replaceable></arg>
      </arg>
    </group>
  </cmdsynopsis>
</refsynopsisdiv>


<refsection><title>Description</title>

<para>The command <command>nix-install-package</command> interactively
installs a Nix Package file (<filename>*.nixpkg</filename>), which is
a small file that contains a store path to be installed along with the
URL of a binary cache.  The Nix Package file is either
<replaceable>file</replaceable>, or automatically downloaded from
<replaceable>url</replaceable> if the <option>--url</option> switch is
used.</para>

<para><command>nix-install-package</command> is used in <link
linkend="sec-one-click">one-click installs</link> to download and
install pre-built binary packages with all necessary dependencies.
<command>nix-install-package</command> is intended to be associated
with the MIME type <literal>application/nix-package</literal> in a web
browser so that it is invoked automatically when you click on
<filename>*.nixpkg</filename> files.  When invoked, it restarts itself
in a terminal window (since otherwise it would be invisible when run
from a browser), asks the user to confirm whether to install the
package, and if so downloads and installs the package into the user’s
current profile.</para>

<para>To obtain a window, <command>nix-install-package</command> tries
to restart itself with <command>xterm</command>,
<command>konsole</command> and
<command>gnome-terminal</command>.</para>

</refsection>


<refsection><title>Options</title>

<variablelist>

  <varlistentry><term><option>--non-interactive</option></term>

    <listitem><para>Do not open a new terminal window and do not ask
    for confirmation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--profile</option></term>
    <term><option>-p</option></term>

    <listitem><para>Install the package into the specified profile
    rather than the user’s current profile.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--set</option></term>

    <listitem><para>Install the package as the profile so that the
    profile contains exactly the contents of the package.</para></listitem>

  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Examples</title>

<para>To install <filename>subversion-1.4.0.nixpkg</filename> into the
user’s current profile, without any prompting:

<screen>
$ nix-install-package --non-interactive subversion-1.4.0.nixpkg</screen>

</para>

<para>To install the same package from some URL into a different
profile:

<screen>
$ nix-install-package --non-interactive -p /nix/var/nix/profiles/eelco \
    --url http://nix.cs.uu.nl/dist/nix/nixpkgs-0.10pre6622/pkgs/subversion-1.4.0-i686-linux.nixpkg</screen>

</para>

</refsection>


<refsection><title>Format of <literal>nixpkg</literal> files</title>

<para>A Nix Package file consists of a single line with the following
format:

<screen>
NIXPKG1 <replaceable>manifestURL</replaceable> <replaceable>name</replaceable> <replaceable>system</replaceable> <replaceable>drvPath</replaceable> <replaceable>outPath</replaceable></screen>

The elements are as follows:

<variablelist>

  <varlistentry><term><literal>NIXPKG1</literal></term>

    <listitem><para>The version of the Nix Package
    file.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>manifestURL</replaceable></term>

    <listitem><para>Obsolete.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>name</replaceable></term>

    <listitem><para>The symbolic name and version of the
    package.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>system</replaceable></term>

    <listitem><para>The platform identifier of the platform for which
    this binary package is intended.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>drvPath</replaceable></term>

    <listitem><para>The path in the Nix store of the derivation from
    which <replaceable>outPath</replaceable> was built.  Not currently
    used.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>outPath</replaceable></term>

    <listitem><para>The path in the Nix store of the
    package.</para></listitem>

  </varlistentry>

  <varlistentry><term><replaceable>binaryCacheURL</replaceable></term>

    <listitem><para>The URL of a binary cache containing the closure
    of <replaceable>outPath</replaceable>.</para></listitem>

  </varlistentry>

</variablelist>

</para>

<para>An example follows:

<screen>
NIXPKG1 http://.../nixpkgs-0.10pre6622/MANIFEST subversion-1.4.0 i686-darwin \
  /nix/store/4kh60jkp...-subversion-1.4.0.drv \
  /nix/store/nkw7wpgb...-subversion-1.4.0</screen>

(The line breaks (<literal>\</literal>) are for presentation purposes
and not part of the actual file.)

</para>

</refsection>


</refentry>