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

<!-- $NetBSD: using.xml,v 1.22 2006/07/29 15:57:04 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>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><prompt>#</prompt> <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><prompt>#</prompt> <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><prompt>%</prompt> <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/mozilla</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>You can overwrite some of the major distribution sites to fit to sites
        that are close to your own.  Have a look at
        <filename>pkgsrc/mk/defaults/mk.conf</filename> to find some examples
        &mdash; in particular, look for the <varname>MASTER_SORT</varname>,
        <varname>MASTER_SORT_REGEX</varname> and
        <varname>INET_COUNTRY</varname> definitions.  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><prompt>%</prompt> <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>
    <prompt>%</prompt> <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>
    <prompt>%</prompt> <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>
    <prompt>%</prompt> <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 can not 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>

    <sect2 id="selecting-the-compiler">
      <title>Selecting the compiler</title>

      <para>By default, pkgsrc will use GCC to build packages.  This may be
        overridden by setting the following variables in /etc/mk.conf:
        </para>

      <variablelist>
        <varlistentry>
          <term><varname>PKGSRC_COMPILER</varname>:</term>

          <listitem>
            <para> This is a list of values specifying the chain of
              compilers to invoke when building packages.  Valid values
              are: </para>

<!-- TODO: update this list after jlam's changes in May 2005 -->
            <itemizedlist>
              <listitem><para><varname>distcc</varname>:
                distributed C/C++ (chainable)</para>
              </listitem>

              <listitem><para><varname>ccache</varname>:
                compiler cache (chainable)</para>
              </listitem>

              <listitem><para><varname>gcc</varname>:
                GNU C/C++ Compiler</para>
              </listitem>

              <listitem><para><varname>mipspro</varname>:
                Silicon Graphics, Inc. MIPSpro (n32/n64)</para>
              </listitem>

              <listitem><para><varname>mipspro</varname>:
                Silicon Graphics, Inc. MIPSpro (o32)</para>
              </listitem>

              <listitem><para><varname>sunpro</varname>:
                Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para>
              </listitem>
            </itemizedlist>

            <para> The default is
              <quote><varname>gcc</varname></quote>.  You can use
              <varname>ccache</varname> and/or
              <varname>distcc</varname> with an appropriate
              <varname>PKGSRC_COMPILER</varname> setting,
              e.g. <quote><varname>ccache gcc</varname></quote>.  This
              variable should always be
              terminated with a value for a real compiler.  </para>
	  </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>GCC_REQD</varname>:</term>
<!--
   TODO: what are the effects of setting GCC_REQD if PKGSRC_COMPILER
   is not gcc?
-->
          <listitem>
            <para> This specifies the minimum version of GCC to use
              when building packages.  If the system GCC doesn't
              satisfy this requirement, then pkgsrc will build and
              install one of the GCC packages to use instead. </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

</sect1>
</chapter>