diff options
author | grant <grant@pkgsrc.org> | 2004-10-21 14:27:36 +0000 |
---|---|---|
committer | grant <grant@pkgsrc.org> | 2004-10-21 14:27:36 +0000 |
commit | 993557136874c37faa801471e150e41a35d64f66 (patch) | |
tree | 33c12f96b885de4e38aaf259542d73ad55e5f341 /doc/guide/files/using.xml | |
parent | 027e24bc57b8c2f8ba04039476b94e567e6deea6 (diff) | |
download | pkgsrc-993557136874c37faa801471e150e41a35d64f66.tar.gz |
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.
Diffstat (limited to 'doc/guide/files/using.xml')
-rw-r--r-- | doc/guide/files/using.xml | 286 |
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/<OSvers>/<arch>/All/package.tgz</userinput></screen> + + <para>If there is any doubt, the uname utility can be used to + determine the <OSvers>, and <arch> 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> |