* Document nix-install-package and the nixpkg file format.

This commit is contained in:
Eelco Dolstra 2006-09-29 14:16:41 +00:00
parent 070e07ed5a
commit 0212feeed6
5 changed files with 240 additions and 34 deletions

View file

@ -10,7 +10,8 @@ XSLTPROC = $(xsltproc) $(xmlflags) \
man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \ man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
nix-collect-garbage.1 nix-push.1 nix-pull.1 \ nix-collect-garbage.1 nix-push.1 nix-pull.1 \
nix-prefetch-url.1 nix-channel.1 \ nix-prefetch-url.1 nix-channel.1 \
nix-pack-closure.1 nix-unpack-closure.1 nix-pack-closure.1 nix-unpack-closure.1 \
nix-install-package.1
FIGURES = figures/user-environments.png FIGURES = figures/user-environments.png

View file

@ -38,45 +38,49 @@
<xi:include href="opt-common.xml" /> <xi:include href="opt-common.xml" />
<xi:include href="env-common.xml" /> <xi:include href="env-common.xml" />
<xi:include href="conf-file.xml" /> <xi:include href="conf-file.xml" />
<section xml:id="sec-nix-env">
<title>nix-env</title>
<xi:include href="nix-env.xml" />
</section>
<section xml:id="sec-nix-build"> <section xml:id="sec-nix-build">
<title>nix-build</title> <title>nix-build</title>
<xi:include href="nix-build.xml" /> <xi:include href="nix-build.xml" />
</section> </section>
<section>
<title>nix-store</title>
<xi:include href="nix-store.xml" />
</section>
<section xml:id="sec-nix-instantiate">
<title>nix-instantiate</title>
<xi:include href="nix-instantiate.xml" />
</section>
<section>
<title>nix-collect-garbage</title>
<xi:include href="nix-collect-garbage.xml" />
</section>
<section xml:id="sec-nix-channel"> <section xml:id="sec-nix-channel">
<title>nix-channel</title> <title>nix-channel</title>
<xi:include href="nix-channel.xml" /> <xi:include href="nix-channel.xml" />
</section> </section>
<section> <section>
<title>nix-push</title> <title>nix-collect-garbage</title>
<xi:include href="nix-push.xml" /> <xi:include href="nix-collect-garbage.xml" />
</section>
<section xml:id="sec-nix-env">
<title>nix-env</title>
<xi:include href="nix-env.xml" />
</section>
<section xml:id="sec-nix-install-package">
<title>nix-install-package</title>
<xi:include href="nix-install-package.xml" />
</section>
<section xml:id="sec-nix-instantiate">
<title>nix-instantiate</title>
<xi:include href="nix-instantiate.xml" />
</section> </section>
<section> <section>
<title>nix-pull</title> <title>nix-pack-closure</title>
<xi:include href="nix-pull.xml" /> <xi:include href="nix-pack-closure.xml" />
</section> </section>
<section> <section>
<title>nix-prefetch-url</title> <title>nix-prefetch-url</title>
<xi:include href="nix-prefetch-url.xml" /> <xi:include href="nix-prefetch-url.xml" />
</section> </section>
<section> <section>
<title>nix-pack-closure</title> <title>nix-pull</title>
<xi:include href="nix-pack-closure.xml" /> <xi:include href="nix-pull.xml" />
</section>
<section xml:id="sec-nix-push">
<title>nix-push</title>
<xi:include href="nix-push.xml" />
</section>
<section>
<title>nix-store</title>
<xi:include href="nix-store.xml" />
</section> </section>
<section> <section>
<title>nix-unpack-closure</title> <title>nix-unpack-closure</title>

View file

@ -0,0 +1,192 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<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>
<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 <link linkend="sec-nix-push"><command>nix-push</command>
manifest</link>. 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 users
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 users current profile.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection><title>Examples</title>
<para></para>
<para>To install <filename>subversion-1.4.0.nixpkg</filename> into the
users 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 elemens 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>The manifest to be pulled by
<command>nix-pull</command>. The manifest must contain
<replaceable>outPath</replaceable>.</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. After
<command>nix-install-package</command> has obtained the manifest
from <replaceable>manifestURL</replaceable>, it performs a
<literal>nix-env -i</literal> <replaceable>outPath</replaceable>
to install the binary package.</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>

View file

@ -476,7 +476,7 @@ available in the subscribed channels.</para>
</section> </section>
<section xml:id="sec-one-click"><title>One-click installations</title> <section xml:id="sec-one-click"><title>One-click installs</title>
<para>TODO</para> <para>TODO</para>

View file

@ -35,19 +35,15 @@ div.chapter > div.titlepage h2, div.appendix > div.titlepage h2
margin-top: 1.5em; margin-top: 1.5em;
} }
div.sect1 h2 /* sections */ div.section > div.titlepage h2 /* sections */
{ {
font-size: 150%; font-size: 150%;
} margin-top: 1.5em;
/* Extra space between sections. */
div.section > div.titlepage h2
{
margin-top: 1.2em;
} }
div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
{ {
margin-top: 1.4em;
font-size: 125%; font-size: 125%;
} }
@ -73,7 +69,7 @@ div.example
padding: 6px 6px; padding: 6px 6px;
margin-left: 0em; margin-left: 0em;
margin-right: 0em; margin-right: 0em;
background: #eeeeee; background: #f4f4f8;
} }
pre.programlisting pre.programlisting
@ -94,7 +90,7 @@ pre.screen
margin-left: 1.5em; margin-left: 1.5em;
margin-right: 1.5em; margin-right: 1.5em;
color: #600000; color: #600000;
background: #eeeeee; background: #f4f4f8;
font-family: monospace; font-family: monospace;
/* font-size: 90%; */ /* font-size: 90%; */
} }
@ -186,9 +182,14 @@ tt, code
} }
div.variablelist dd p
{
margin-top: 0em;
}
div.variablelist dd div.variablelist dd
{ {
margin-bottom: 1em; margin-left: 1.5em;
} }
.default .default
@ -251,3 +252,11 @@ table.productionset table.productionset
{ {
font-family: monospace; font-family: monospace;
} }
strong.command
{
// font-family: monospace;
// font-style: italic;
// font-weight: normal;
color: #400000;
}