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

<!-- $NetBSD: using.xml,v 1.16 2006/02/12 14:44:59 rillig Exp $ -->

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

  <sect1 id="getting-started">
    <title>Working with binary packages</title>

    <para> This section describes how to find, retrieve and install a
      precompiled binary package that someone else already prepared
      for your type of machine. </para>

    <sect2 id="where-to-get-binary-packages">
      <title>Where to get binary packages</title>

      <para> Precompiled packages are stored on ftp.NetBSD.org and its
        mirrors in the directory
        <filename>/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/</filename> for
	anonymous FTP access.  <varname>OSVERSION</varname> is the &os;
	version (<command>uname -r</command>), <varname>ARCH</varname>
	is the architecture (<command>uname -p</command>).
	In that directory, there is a
        subdirectory for each category plus a subdirectory
        <filename>All</filename> which includes the actual binaries in
        <filename>.tgz</filename> files. The category subdirectories
        use symbolic links to those files (this is the same directory
        layout as in
        <filename>/usr/pkgsrc/packages</filename>). </para>

      <para> This same directory layout applies for CD-ROM
        distributions, only that the directory may be rooted somewhere
        else, probably somewhere below
        <filename>/cdrom</filename>. Please consult your CD-ROMs
        documentation for the exact location. </para>
    </sect2>

    <sect2 id="how-to-use-binary-packages">
      <title>How to use 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.tgz</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="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> This 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 on a NetBSD system the
        <quote>comp</quote> and the <quote>text</quote> distribution
        sets must be installed. 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>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 you don't have a permanent Internet connection and you want to know
        which files to download, <command>make fetch-list</command> will tell you
        what you'll need. Put these distfiles into
        <filename>/usr/pkgsrc/distfiles</filename>.</para>
    </sect2>

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

      <para>Assuming that the distfile has been fetched (see previous section), become
        root and change into the relevant directory and run
        <command>make</command>.</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, and</para>

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

      <para>to install the various components into the correct places
        on your system. Installing the package on your system requires
        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>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>