about summary refs log tree commit diff
path: root/doc/manual/package-management.xml
blob: 0b7299e9af87b6fb43417f66fc4bdf7172fa5f44 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
<chapter id='chap-package-management'><title>Package Management</title>

<para>This chapter discusses how to do package management with Nix,
i.e., how to obtain, install, upgrade, and erase components.  This is
the <quote>user's</quote> perspective of the Nix system — people
who want to <emphasis>create</emphasis> components should consult
<xref linkend='chap-writing-nix-expressions' />.</para>


<sect1><title>Basic package management</title>

<para>The main command for package management is
<command>nix-env</command>.  You can use it to install, upgrade, and
erase components, and to query what components are installed or are
available for installation.</para>

<para>In Nix, different users can have different <quote>views</quote>
on the set of installed applications.  That is, there might be lots of
applications present on the system (possibly in many different
versions), but users can have a specific selection of those active —
where <quote>active</quote> just means that it appears in a directory
in the user's <envar>PATH</envar>.  Such a view on the set of
installed applications is called a <emphasis>user
environment</emphasis>, which is just a directory tree consisting of
symlinks to the files of the active applications.  </para>

<para>Components are installed from a set of <emphasis>Nix
expressions</emphasis> that tell Nix how to build those components,
including, if necessary, their dependencies.  There is a collection of
Nix expressions called the Nix Package collection that contains
components ranging from basic development stuff such as GCC and Glibc,
to end-user applications like Mozilla Firefox.  (Nix is however not
tied to the Nix Package collection; you could write your own Nix
expression based on that, or completely new.)  You can download the
latest version from <ulink
url='http://catamaran.labs.cs.uu.nl/dist/nix' />.  You probably want
the latest unstable release; currently the stable releases tend to lag
behind quite a bit.</para>

<para>Assuming that you have downloaded and unpacked a release of Nix
Packages, you can view the set of available components in the release:

<screen>
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable>
ant-blackdown-1.4.2
aterm-2.2
bash-3.0
binutils-2.15
bison-1.875d
blackdown-1.4.2
bzip2-1.0.2
...</screen>

where <literal>nixpkgs-<replaceable>version</replaceable></literal> is
where you've unpacked the release.</para>

<para>It is also possible to see the <emphasis>status</emphasis> of
available component, i.e., whether they are installed into the user
environment and/or present in the system:

<screen>
$ nix-env -qasf nixpkgs-<replaceable>version</replaceable>
...
-PS bash-3.0
--S binutils-2.15
IPS bison-1.875d
...</screen>

The first character (<literal>I</literal>) indicates whether the
component is installed in your current user environment.  The second
(<literal>P</literal>) indicates whether it is present on your system
(in which case installing it into your user environment would be very
quick).  The last one (<literal>S</literal>) indicates whether there
is a so-called <emphasis>substitute</emphasis> for the component,
which is Nix's mechanism for doing binary deployment.  It just means
that Nix know that it can fetch a pre-built component from somewhere
(typically a network server) instead of building it locally.</para>

<para>So now that we have a set of Nix expressions we can build the
components contained in them.  This is done using <literal>nix-env
-i</literal>.  For instance,

<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>

will install the component called <literal>subversion</literal> (which
is, of course, the <ulink
url='http://subversion.tigris.org/'>Subversion version management
system</ulink>).</para>

<para>When you do this for the first time, Nix will start building
Subversion and all its dependencies.  This will take quite a while —
typically an hour or two on modern machines.  Fortunately, there is a
faster way (so just do a Ctrl-C on that install operation!): you just
need to tell Nix that pre-built binaries of all those components are
available somewhere.  This is done using the
<command>nix-pull</command> command, which must be supplied with a URL
containing a <emphasis>manifest</emphasis> describing what binaries
are available.  This URL should correspond to the Nix Packages release
that you're using.  For instance, if you obtained a release from
<ulink
url='http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/' />,
then you should do:

<screen>
$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/MANIFEST</screen>

If you then issue the installation command, it should start
downloading binaries from <systemitem
class='fqdomainname'>catamaran.labs.cs.uu.nl</systemitem>, instead of
building them from source.  This might still take a while since all
dependencies must be downloaded, but on a reasonably fast connection
such as an ADSL line it's on the order of a few minutes.</para>

<para>Naturally, packages can also be uninstalled:

<screen>
$ nix-env -e subversion</screen>

</para>

<para>Upgrading to a new version is just as easy.  If you have a new
release of Nix Packages, you can do:

<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>

This will <emphasis>only</emphasis> upgrade Subversion if there is a
<quote>newer</quote> version in the new set of Nix expressions, as
defined by some pretty much arbitrary rules regarding ordering of
version numbers (which generally do what you'd expect of them).  To
just unconditionally replace Subversion with whatever version is in
the Nix expressions, use <parameter>-i</parameter> instead of
<parameter>-u</parameter> — <parameter>-i</parameter> will
remove whatever version is already installed.</para>

<para>You can also upgrade all components for which there are newer
versions:

<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>

</para>

<para>If you grow tired of specifying the Nix expressions using
<parameter>-f</parameter> all the time, you can set a default
location:

<screen>
$ nix-env -I nixpkgs-<replaceable>version</replaceable></screen>

After this you can just say, for instance, <literal>nix-env -u
'*'</literal>.<footnote><para>Setting a default using
<parameter>-I</parameter> currently clashes with using Nix channels,
since <literal>nix-channel --update</literal> calls <literal>nix-env
-I</literal> to set the default to the Nix expressions it downloaded
from the channel, replacing whatever default you had
set.</para></footnote></para>

</sect1>


<sect1><title>Profiles</title>

<para>In Nix, operations such as upgrading or removing components
never overwrite or remove the files of those components, and they
don't even touch the user environments that point to them.  Rather,
they cause a <emphasis>new</emphasis> user environment to be
constructed based on the old one.  This is illustrated in Figure
bla.</para>

<figure><title>User environments</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref='figures/user-environments.png' format='PNG' />
    </imageobject>
  </mediaobject>
</figure>


</sect1>


<sect1><title>Garbage collection</title>

<para>Bla</para>

</sect1>


<sect1><title>Channels</title>

<para>Bla</para>

</sect1>


</chapter>