<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-declarative-package-mgmt">
 <title>Declarative Package Management</title>

 <para>
  With declarative package management, you specify which packages you want on
  your system by setting the option
  <xref linkend="opt-environment.systemPackages"/>. For instance, adding the
  following line to <filename>configuration.nix</filename> enables the Mozilla
  Thunderbird email application:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
</programlisting>
  The effect of this specification is that the Thunderbird package from Nixpkgs
  will be built or downloaded as part of the system when you run
  <command>nixos-rebuild switch</command>.
 </para>

 <note>
  <para>
   Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
  </para>
 </note>

 <para>
  You can get a list of the available packages as follows:
<screen>
<prompt>$ </prompt>nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
<replaceable>...</replaceable>
</screen>
  The first column in the output is the <emphasis>attribute name</emphasis>,
  such as <literal>nixos.thunderbird</literal>.
 </para>
 <para>
  Note: the <literal>nixos</literal> prefix tells us that we want to get the
  package from the <literal>nixos</literal> channel and works only in CLI tools.

  In declarative configuration use <literal>pkgs</literal> prefix (variable).
 </para>

 <para>
  To “uninstall” a package, simply remove it from
  <xref linkend="opt-environment.systemPackages"/> and run
  <command>nixos-rebuild switch</command>.
 </para>

 <xi:include href="customizing-packages.xml" />

 <xi:include href="adding-custom-packages.xml" />
</section>
