path: root/doc/guide/files/using.xml

<!-- $NetBSD: using.xml,v 1.33 2007/10/18 22:44:09 rillig Exp $ -->

<chapter id="using"> <?dbhtml filename="using.html"?>
<title>Using pkgsrc</title>

<para>Basically, there are two ways of using pkgsrc. The first
is to only install the package tools and to use binary packages
that someone else has prepared. This is the <quote>pkg</quote>
in pkgsrc. The second way is to install the <quote>src</quote>
of pkgsrc, too. Then you are able to build your own packages,
and you can still use binary packages from someone else.</para>

<sect1 id="using-pkg">
  <title>Using binary packages</title>

  <para>On the <ulink url="ftp://ftp.NetBSD.org/">ftp.NetBSD.org</ulink>
  server and its mirrors, there are collections of binary packages,
  ready to be installed. These binary packages have been built using the
  default settings for the directories, that is:</para>

  <itemizedlist>
  <listitem><para><filename>/usr/pkg</filename> for <varname>LOCALBASE</varname>, where most of the files are installed,</para></listitem>
  <listitem><para><filename>/usr/pkg/etc</filename> for configuration files,</para></listitem>
  <listitem><para><filename>/var</filename> for <varname>VARBASE</varname>, where those files are installed that may change after installation.</para></listitem>
  </itemizedlist>

  <para>If you cannot use these directories for whatever reasons (maybe
  because you're not root), you cannot use these binary packages, but
  have to build the packages yourself, which is explained in <xref
  linkend="bootstrapping-pkgsrc" />.</para>

  <sect2 id="finding-binary-packages">
    <title>Finding binary packages</title>

    <para>To install binary packages, you first need to know from where
    to get them. The first place where you should look is on the main
    pkgsrc FTP server in the directory <ulink
    url="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/"><filename>/pub/pkgsrc/packages</filename></ulink>.</para>

    <para>This directory contains binary packages for multiple
    platforms. First, select your operating system. (Ignore the
    directories with version numbers attached to it, they just exist for
    legacy reasons.) Then, select your hardware architecture, and in the
    third step, the OS version and the <quote>version</quote> of pkgsrc.</para>

    <para>In this directory, you often find a file called
    <filename>bootstrap.tar.gz</filename> which contains the package
    management tools. If the file is missing, it is likely that your
    operating system already provides those tools. Download the file and
    extract it in the <filename>/</filename> directory. It will create
    the directories <filename>/usr/pkg</filename> (containing the tools
    for managing binary packages) and <filename>/var/db/pkg</filename>
    (the database of installed packages).</para>
  </sect2>

  <sect2 id="installing-binary-packages">
    <title>Installing binary packages</title>

    <para>In the directory from the last section, there is a
    subdirectory called <filename>All</filename>, which contains all the
    binary packages that are available for the platform, excluding those
    that may not be distributed via FTP or CDROM (depending on which
    medium you are using), and the ones that have vulnerabilities and
    therefore are considered insecure to install without thinking
    before.</para>

    <para>To install packages directly from an FTP or HTTP server, run
    the following commands in a Bourne-compatible shell (be sure to
    <command>su</command> to root first):</para>

<screen>
&rprompt; <userinput>PATH="/usr/pkg/sbin:$PATH"</userinput>
&rprompt; <userinput>PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/<replaceable>OPSYS</replaceable>/<replaceable>ARCH</replaceable>/<replaceable>VERSIONS</replaceable>/All"</userinput>
&rprompt; <userinput>export PATH PKG_PATH</userinput>
</screen>

    <para>Instead of URLs, you can also use local paths, for example if
    you are installing from a set of CDROMs, DVDs or an NFS-mounted
    repository. If you want to install packages from multiple sources,
    you can separate them by a semicolon in
    <varname>PKG_PATH</varname>.</para>

    <para>After these preparations, installing a package is very
    easy:</para>

<screen>
&rprompt; <userinput>pkg_add openoffice2</userinput>
&rprompt; <userinput>pkg_add kde-3.5.7</userinput>
&rprompt; <userinput>pkg_add ap2-php5-*</userinput>
</screen>

    <para>Note that any prerequisite packages needed to run the
    package in question will be installed, too, assuming they are
    present where you install from.</para>

    <para>As mentioned above, packages for which vulnerabilities get
    known are not stored in the <filename>All</filename> subdirectory.
    They don't get deleted since that could be very frustrating if many
    other packages depend on it. Instead, they are moved to the
    <filename>vulnerable</filename> subdirectory. So you may need to add
    this directory to the <varname>PKG_PATH</varname> variable. 
    However, you should run <filename
    role="pkg">security/audit-packages</filename> regularly, especially
    after installing new packages, and verify that the vulnerabilities
    are acceptable for your configuration.</para>

    <para>After you've installed packages, be sure to have
    <filename>/usr/pkg/bin</filename> and <filename>/usr/pkg/sbin</filename> in your
    <varname>PATH</varname> so you can actually start the just
    installed program.</para>
  </sect2>

  <sect2 id="using.pkg_delete">
    <title>Deinstalling packages</title>

    <para>To deinstall a package, it does not matter whether it was
    installed from source code or from a binary package. The
    <command>pkg_delete</command> command does not know it anyway.
    To delete a package, you can just run <command>pkg_delete
    <replaceable>package-name</replaceable></command>. The package
    name can be given with or without version number. Wildcards can
    also be used to deinstall a set of packages, for example
    <literal>*emacs*</literal>. Be sure to include them in quotes,
    so that the shell does not expand them before
    <literal>pkg_delete</literal> sees them.</para>

    <para>The <option>-r</option> option is very powerful: it
    removes all the packages that require the package in question
    and then removes the package itself. For example:

    <screen>
&rprompt; <userinput>pkg_delete -r jpeg</userinput>
    </screen>

    will remove jpeg and all the packages that used it; this allows
    upgrading the jpeg package.</para>

  </sect2>

  <sect2 id="using.pkg_info">
    <title>Getting information about installed packages</title>

    <para>The <command>pkg_info</command> shows information about
    installed packages or binary package files.</para>

  </sect2>

  <sect2 id="vulnerabilities">
    <title>Checking for security vulnerabilities in installed packages</title>

    <para>
      The NetBSD Security-Officer and Packages Groups maintain a list of
      known security vulnerabilities to packages which are (or have been)
      included in pkgsrc.  The list is available from the NetBSD
      FTP site at <ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"/>.
    </para>

    <para>
      Through <filename role="pkg">security/audit-packages</filename>,
      this list can be downloaded
      automatically, and a security audit of all packages installed on a system
      can take place.
    </para>

    <para>
      There are two components to
      <filename role="pkg">security/audit-packages</filename>.  The first
      component, <quote>download-vulnerability-list</quote>, is for downloading
      the list of vulnerabilities from the NetBSD FTP site.  The second
      component, <quote>audit-packages</quote>, checks to see if any of your
      installed packages are vulnerable.  If a package is vulnerable, you
      will see output similar to the following:
    </para>

    <screen>Package samba-2.0.9 has a local-root-shell vulnerability, see
    http://www.samba.org/samba/whatsnew/macroexploit.html</screen>

    <para>
      One can set up <filename
      role="pkg">security/audit-packages</filename> to download the
      <ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities">vulnerabilities</ulink>
      file daily, and include a package audit in the daily security script.
      Details on this are located in the <ulink
      url="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/security/audit-packages/MESSAGE?rev=HEAD&amp;content-type=text/x-cvsweb-markup">MESSAGE</ulink>
      file for <filename role="pkg">security/audit-packages</filename>.
    </para>
  </sect2>

  <sect2 id="pkg_versions">
    <title>Finding if newer versions of your installed packages are in pkgsrc</title>
    <para>
      Install <filename role="pkg">pkgtools/pkglint</filename> and run
      <command>lintpkgsrc</command> with the <quote>-i</quote>
      argument to check if your packages are up-to-date, e.g.
    </para>
    <screen>
&cprompt; <userinput>lintpkgsrc -i</userinput>
...
Version mismatch: 'tcsh' 6.09.00 vs 6.10.00
    </screen>
    <para>You can then use <command>make update</command> to update the
    package on your system and rebuild any dependencies.
    </para>
  </sect2>

  <sect2 id="using.pkg_admin">
    <title>Other administrative functions</title>

    <para>The <command>pkg_admin</command> executes various
    administrative functions on the package system.</para>

  </sect2>

  <sect2 id="a-word-of-warning">
    <title>A word of warning</title>

    <para>Please pay very careful attention to the warnings
    expressed in the &man.pkg.add.1; manual page about the
    inherent dangers of installing binary packages which you did
    not create yourself, and the security holes that can be
    introduced onto your system by indiscriminate adding of such
    files.</para>

    <para>The same warning of course applies to every package you
    install from source when you haven't completely read and
    understood the source code of the package, the compiler that
    is used to build the package and all the other tools that are
    involved.</para>

  </sect2>
</sect1>

<sect1 id="building-packages-from-source">
  <title>Building packages from source</title>

  <para>After obtaining pkgsrc, the <filename>pkgsrc</filename>
  directory now contains a set of packages, organized into
  categories. You can browse the online index of packages, or run
  <command>make readme</command> from the <filename>pkgsrc</filename>
  directory to build local <filename>README.html</filename> files for
  all packages, viewable with any web browser such as <filename
  role="pkg">www/lynx</filename> or <filename
  role="pkg">www/firefox</filename>.</para>

  <para>The default <emphasis>prefix</emphasis> for installed packages
  is <filename>/usr/pkg</filename>. If you wish to change this, you
  should do so by setting <varname>LOCALBASE</varname> in
  &mk.conf;. You should not try to use multiple
  different <varname>LOCALBASE</varname> definitions on the same
  system (inside a chroot is an exception). </para>

  <para>The rest of this chapter assumes that the package is already
  in pkgsrc. If it is not, see <xref linkend="developers-guide"/> for
  instructions how to create your own packages.</para>

  <sect2 id="requirements">
    <title>Requirements</title>

    <para>To build packages from source, you need a working C
    compiler. On NetBSD, you need to install the
    <quote>comp</quote> and the <quote>text</quote> distribution
    sets. If you want to build X11-related packages, the
    <quote>xbase</quote> and <quote>xcomp</quote> distribution
    sets are required, too.</para>
    <!-- FIXME: what about installing x11/XFree86-*? -->
  </sect2>


  <sect2 id="fetching-distfiles">
    <title>Fetching distfiles</title>

    <para>The first step for building a package is downloading the
    distfiles (i.e. the unmodified source). If they have not yet been
    downloaded, pkgsrc will fetch them automatically.</para>

    <para>If you have all files that you need in the
    <filename>distfiles</filename> directory,
    you don't need to connect. If the distfiles are on CD-ROM, you can
    mount the CD-ROM on <filename>/cdrom</filename> and add:
    <screen>DISTDIR=/cdrom/pkgsrc/distfiles</screen>
    to your &mk.conf;.</para>

    <para>By default a list of distribution sites will be randomly
    intermixed to prevent huge load on servers which holding popular
    packages (for example, SourceForge.net mirrors). Thus, every
    time when you need to fetch yet another distfile all the mirrors
    will be tried in new (random) order. You can turn this feature
    off by setting <varname>MASTER_SORT_RANDOM=NO</varname> (for
    <varname>PKG_DEVELOPER</varname>s it's already disabled).</para>

    <para>You can overwrite some of the major distribution sites to
    fit to sites that are close to your own.  By setting one or two
    variables you can modify the order in which the master sites are
    accessed.  <varname>MASTER_SORT</varname> contains a whitespace
    delimited list of domain suffixes.
    <varname>MASTER_SORT_REGEX</varname> is even more flexible, it
    contains a whitespace delimited list of regular expressions.  It
    has higher priority than <varname>MASTER_SORT</varname>.  Have a
    look at <filename>pkgsrc/mk/defaults/mk.conf</filename> to find
    some examples.  This may save some of your bandwidth and
    time.</para>

    <para>You can change these settings either in your shell's environment, or,
    if you want to keep the settings, by editing the
    &mk.conf; file,
    and adding the definitions there.</para>

    <para>
      If a package depends on many other packages (such as
      <filename role="pkg">meta-pkgs/kde3</filename>), the build process may
      alternate between periods of
      downloading source, and compiling. To ensure you have all the source
      downloaded initially you can run the command:
      <screen>&cprompt; <userinput>make fetch-list | sh</userinput></screen>
      which will output and run a set of shell commands to fetch the
      necessary files into the <filename>distfiles</filename> directory.  You can
      also choose to download the files manually.
    </para>

  </sect2>

  <sect2 id="how-to-build-and-install">
    <title>How to build and install</title>

    <para>
      Once the software has downloaded, any patches will be applied, then it
      will be compiled for you. This may take some time depending on your
      computer, and how many other packages the software depends on and their
      compile time.
    </para>

    <note><para>If using bootstrap or pkgsrc on a non-NetBSD system,
    use the pkgsrc <command>bmake</command> command instead of
    <quote>make</quote> in the examples in this guide.</para></note>

    <para>For example, type</para>

    <screen>
&cprompt; <userinput>cd misc/figlet</userinput>
&cprompt; <userinput>make</userinput>
    </screen>

    <para>at the shell prompt to build the various components of the
    package.</para>

    <para>The next stage is to actually install the newly compiled
    program onto your system. Do this by entering:

    <screen>
&cprompt; <userinput>make install</userinput>
    </screen>

    while you are still in the directory for whatever package you
    are installing.</para>

    <para>Installing the package on your system may require you to
    be root.  However, pkgsrc has a
    <emphasis>just-in-time-su</emphasis> feature, which allows you
    to only become root for the actual installation step.</para>

    <para>That's it, the software should now be installed and setup for use.
    You can now enter:

    <screen>
&cprompt; <userinput>make clean</userinput>
    </screen>

    to remove the compiled files in the work directory, as you shouldn't need
    them any more. If other packages were also added to your system
    (dependencies) to allow your program to compile, you can tidy these up
    also with the command:</para>

    <screen>
&cprompt; <userinput>make clean-depends</userinput>
    </screen>

    <para>Taking the figlet utility as an example, we can install it on our
    system by building as shown in <xref linkend="logs"/>.</para>

    <para>The program is installed under the default root of the
    packages tree - <filename>/usr/pkg</filename>. Should this not
    conform to your tastes, set the <varname>LOCALBASE</varname>
    variable in your environment, and it will use that value as the
    root of your packages tree. So, to use
    <filename>/usr/local</filename>, set
    <varname>LOCALBASE=/usr/local</varname> in your environment.
    Please note that you should use a directory which is dedicated to
    packages and not shared with other programs (i.e., do not try and
    use <varname>LOCALBASE=/usr</varname>).  Also, you should not try
    to add any of your own files or directories (such as
    <filename>src/</filename>, <filename>obj/</filename>, or
    <filename>pkgsrc/</filename>) below the
    <varname>LOCALBASE</varname> tree.  This is to prevent possible
    conflicts between programs and other files installed by the
    package system and whatever else may have been installed
    there.</para>

    <para>Some packages look in &mk.conf; to
    alter some configuration options at build time.  Have a look at
    <filename>pkgsrc/mk/defaults/mk.conf</filename> to get an overview
    of what will be set there by default.  Environment variables such
    as <varname>LOCALBASE</varname> can be set in
    &mk.conf; to save having to remember to
    set them each time you want to use pkgsrc.</para>

    <para>Occasionally, people want to <quote>look under the
    covers</quote> to see what is going on when a package is building
    or being installed. This may be for debugging purposes, or out of
    simple curiosity. A number of utility values have been added to
    help with this.</para>

    <orderedlist>
      <listitem>
	<para>If you invoke the &man.make.1; command with
	<varname>PKG_DEBUG_LEVEL=2</varname>, then a huge amount of
	information will be displayed. For example,</para>

	<screen><userinput>make patch PKG_DEBUG_LEVEL=2</userinput></screen>

	<para>will show all the commands that are invoked, up to and
	including the <quote>patch</quote> stage.</para>
      </listitem>

      <listitem>
	<para>If you want to know the value of a certain &man.make.1;
	definition, then the <varname>VARNAME</varname> definition
	should be used, in conjunction with the show-var
	target. e.g. to show the expansion of the &man.make.1;
	variable <varname>LOCALBASE</varname>:</para>

	<screen>
&cprompt; <userinput>make show-var VARNAME=LOCALBASE</userinput>
/usr/pkg
&cprompt;
	</screen>

      </listitem>
    </orderedlist>

    <para>If you want to install a binary package that you've either
    created yourself (see next section), that you put into
    pkgsrc/packages manually or that is located on a remote FTP
    server, you can use the "bin-install" target. This target will
    install a binary package - if available - via &man.pkg.add.1;,
    else do a <command>make package</command>.  The list of remote FTP
    sites searched is kept in the variable
    <varname>BINPKG_SITES</varname>, which defaults to
    ftp.NetBSD.org. Any flags that should be added to &man.pkg.add.1;
    can be put into <varname>BIN_INSTALL_FLAGS</varname>.  See
    <filename>pkgsrc/mk/defaults/mk.conf</filename> for more
    details.</para>

    <para>A final word of warning: If you set up a system that has a
    non-standard setting for <varname>LOCALBASE</varname>, be sure to
    set that before any packages are installed, as you cannot use
    several directories for the same purpose. Doing so will result in
    pkgsrc not being able to properly detect your installed packages,
    and fail miserably. Note also that precompiled binary packages are
    usually built with the default <varname>LOCALBASE</varname> of
    <filename>/usr/pkg</filename>, and that you should
    <emphasis>not</emphasis> install any if you use a non-standard
    <varname>LOCALBASE</varname>.</para>
  </sect2>
</sect1>
</chapter>