import The pkgsrc guide, the docbook conversion/replacement of

Packages.txt; Packages.txt will be going away.

this package contains the source files and a mechanism to install
pkgsrc/doc/pkgsrc.{html,txt} which are distributed with pkgsrc. it
uses the same docbook infrastructure that is used to build the
documentation on www.NetBSD.org.

1 files changed, 286 insertions, 0 deletions

diff --git a/doc/guide/files/using.xml b/doc/guide/files/using.xml
new file mode 100644
index 00000000000..c97cc148515
--- /dev/null
+++ b/doc/guide/files/using.xml
@@ -0,0 +1,286 @@
+<!-- $NetBSD: using.xml,v 1.1.1.1 2004/10/21 14:27:37 grant 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>
+      <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</filename> for anonymous FTP
+        access.  Please pick the right subdirectory there as indicated
+        by <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 CDROM
+        distributions, only that the directory may be rooted somewhere
+        else, probably somewhere below
+        <filename>/cdrom</filename>. Please consult your CDROMs
+        documentation for the exact location. </para>  
+    </sect2>
+
+    <sect2>
+      <title>How to use binary packages</title>
+      
+      <para> If you have the files on a CDROM or downloaded them to
+        your hard disk, youcan 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;OSvers&gt;/&lt;arch&gt;/All/package.tgz</userinput></screen>
+
+      <para>If there is any doubt, the uname utility can be used to
+        determine the &lt;OSvers&gt;, and &lt;arch&gt; by running
+        <command>uname -rp</command>. </para>
+
+      <para>Also 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>After you've installed packages, be sure to have
+        <filename>/usr/pkg/bin</filename> in your
+        <varname>PATH</varname> so you can actually start the just
+        installed program. </para> 
+    </sect2>
+
+    <sect2>
+      <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>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <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"/>. </para>
+
+    <sect2>
+      <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>
+    </sect2>
+    
+
+    <sect2>
+      <title>Fetching distfiles</title>
+
+      <para>The distfile (i.e. the unmodified source)
+        must exist on your system for the packages system to be able
+        to build it. If it does not exist, pkgsrc will use &man.ftp.1; to
+        fetch it 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/bsd.pkg.defaults.mk</filename> to find some examples
+        - 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>
+      <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 running
+        <command>make</command>. 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 (ie, 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/bsd.pkg.defaults.mk</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 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>DISTFILES</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 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_SITE</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/bsd.pkg.defaults.mk</filename> for more details.</para>
+
+      <para>A final word of warning: If you setup 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>
+      <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>
+            
+            <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>:
+                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>
+          <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>