pkgsrc/doc/guide/files/using.xml

<!-- $NetBSD: using.xml,v 1.29 2006/12/15 13:22:14 martti 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>To use binary packages, you need some tools to manage
  them. On NetBSD, these tools are already installed. On all other
  operating systems, you need to install them first. For the
  following platforms, prebuilt versions of the package tools
  are available and can simply be downloaded and unpacked in the
  <filename>/</filename> directory:</para>

  <informaltable id="binary-bootstrap-kits">
    <tgroup cols="2">
      <thead><row><entry>Platform</entry><entry>URL</entry></row></thead>
      <tbody>
	<row><entry>Solaris 9</entry><entry><filename>ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/bootstrap-pkgsrc/</filename></entry></row>
	<row><entry>Solaris 10</entry><entry><filename>http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/</filename></entry></row>
      </tbody>
    </tgroup>
  </informaltable>

  <para>These pre-built package tools use
  <filename>/usr/pkg</filename> for the base directory, and
  <filename>/var/db/pkg</filename> for the database of installed
  packages. If you cannot use these directories for whatever
  reasons (maybe because you're not root), you have to build the
  package tools 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. You can get them on CD-ROMs, DVDs, or via FTP
    or HTTP.</para>

    <para>The binary packages can be found at the following
    locations.</para>

    <informaltable id="binary-packages">
      <tgroup cols="2">
	<thead><row><entry>Platform</entry><entry>URL</entry></row></thead>
	<tbody>
	  <row><entry>NetBSD</entry><entry><filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/</filename></entry></row>
	  <row><entry>Solaris 9</entry><entry><filename>ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/</filename></entry></row>
	  <row><entry>Solaris 10</entry><entry><filename>http://public.enst.fr/pkgsrc/packages/</filename></entry></row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>Most of these directories contain binary packages for
    multiple platforms. Select the appropriate subdirectories,
    according to your machine architecture and operating system,
    until you find a directory called <filename>All</filename>. This
    directory contains all the binary packages. Further, there are
    subdirectories for categories that contain symbolic links that
    point to the actual binary package in
    <filename>../All</filename>. This directory layout is used for
    all package repositories, no matter if they are accessed via
    HTTP, FTP, NFS, CD-ROM, or the local filesystem.</para>

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

    <para>If you have the files on a CD-ROM or downloaded them to
    your hard disk, you can install them with the following command
    (be sure to <command>su</command> to root first):</para>

    <screen>&rprompt; <userinput>pkg_add /path/to/package.tgz</userinput></screen>

    <para>If you have FTP access and you don't want to download the
    packages via FTP prior to installation, you can do this
    automatically by giving <command>pkg_add</command> an FTP URL:</para>

    <screen>&rprompt; <userinput>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All/package</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>To save some typing, you can set the
    <varname>PKG_PATH</varname> environment variable to a semicolon-separated
    list of paths (including remote URLs); trailing slashes are not allowed.
    </para>

    <para>Additionally to the <filename>All</filename> directory
    there exists a <filename>vulnerable</filename> directory to
    which binary packages with known vulnerabilities are
    moved, since removing them could cause missing dependencies. To
    use these packages, add the <filename>vulnerable</filename>
    directory to your <varname>PKG_PATH</varname>. 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. An example
    <varname>PKG_PATH</varname> would be:
    <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/vulnerable</filename>
    Please note that semicolon (';') is a shell meta-character, so
    you'll probably have to quote it.</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
  <filename>mk.conf</filename>. 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 <filename>mk.conf</filename>.</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
    <filename>/etc/mk.conf</filename> 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 <filename>/etc/mk.conf</filename> 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
    <filename>/etc/mk.conf</filename> 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>