405 lines
16 KiB
XML
405 lines
16 KiB
XML
<!-- $NetBSD: configuring.xml,v 1.31 2007/12/30 22:54:39 darcy Exp $ -->
|
|
|
|
<chapter id="configuring">
|
|
<title>Configuring pkgsrc</title>
|
|
|
|
<anchor id="mk.conf" />
|
|
|
|
<para>The whole pkgsrc system is configured in a single file, usually
|
|
called <filename>mk.conf</filename>. In which directory pkgsrc looks for
|
|
that file depends on the installation. On NetBSD, when you use
|
|
&man.make.1; from the base system, it is in the directory
|
|
<filename>/etc/</filename>. In all other cases the default location is
|
|
<literal>${PREFIX}/etc/</literal>, depending on where you told the
|
|
bootstrap program to install the binary packages.</para>
|
|
|
|
<para>During the bootstrap, an example configuration file is created. To
|
|
use that, you have to create the directory
|
|
<filename>${PREFIX}/etc</filename> and copy the example file
|
|
there.</para>
|
|
|
|
<para>The format of the configuration file is that of the usual
|
|
BSD-style <filename>Makefile</filename>s. The whole pkgsrc configuration
|
|
is done by setting variables in this file. Note that you can define all
|
|
kinds of variables, and no special error checking (for example for
|
|
spelling mistakes) takes place, so you have to try it out to see if it
|
|
works.</para>
|
|
|
|
<sect1 id="general-configuration">
|
|
<title>General configuration</title>
|
|
|
|
<para>In this section, you can find some variables that apply to all
|
|
pkgsrc packages. A complete list of the variables that can be
|
|
configured by the user is available in
|
|
<filename>mk/defaults/mk.conf</filename>, together with some
|
|
comments that describe each variable's intent.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><varname>LOCALBASE</varname>: Where
|
|
packages will be installed. The default is
|
|
<filename>/usr/pkg</filename>. Do not mix binary packages
|
|
with different <varname>LOCALBASE</varname>s!</para>
|
|
</listitem>
|
|
<listitem><para><varname>CROSSBASE</varname>: Where
|
|
<quote>cross</quote> category packages will be
|
|
installed. The default is
|
|
<filename>${LOCALBASE}/cross</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>X11BASE</varname>: Where
|
|
X11 is installed on the system. The default is
|
|
<filename>/usr/X11R6</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>DISTDIR</varname>: Where to store the
|
|
downloaded copies of the original source distributions used
|
|
for building pkgsrc packages. The default is
|
|
<filename>${PKGSRCDIR}/distfiles</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>PKG_DBDIR</varname>: Where the
|
|
database about installed packages is stored. The default is
|
|
<filename>/var/db/pkg</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>MASTER_SITE_OVERRIDE</varname>:
|
|
If set, override the packages'
|
|
<varname>MASTER_SITES</varname> with this value.</para>
|
|
</listitem>
|
|
<listitem><para><varname>MASTER_SITE_BACKUP</varname>:
|
|
Backup location(s) for distribution files and patch files
|
|
if not found locally or in
|
|
<filename>${MASTER_SITES}</filename> or
|
|
<filename>${PATCH_SITES}</filename> respectively.
|
|
The defaults are
|
|
<filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</filename>
|
|
and
|
|
<filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>BINPKG_SITES</varname>:
|
|
List of sites carrying binary pkgs. <replaceable>rel</replaceable> and
|
|
<replaceable>arch</replaceable> are replaced with OS
|
|
release (<quote>2.0</quote>, etc.) and architecture
|
|
(<quote>mipsel</quote>, etc.).</para>
|
|
</listitem>
|
|
<listitem><para><varname>ACCEPTABLE_LICENSES</varname>:
|
|
List of acceptable licenses. Whenever you try to build a package
|
|
whose license is not in this list, you will get an error message
|
|
that includes instructions on how to change this variable.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="variables-affecting-build">
|
|
<title>Variables affecting the build process</title>
|
|
<para>XXX
|
|
<itemizedlist>
|
|
<listitem><para><varname>PACKAGES</varname>: The top level
|
|
directory for the binary packages. The default is
|
|
<filename>${PKGSRCDIR}/packages</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>WRKOBJDIR</varname>:
|
|
The top level directory where, if defined, the separate
|
|
working directories will get created, and symbolically
|
|
linked to from <filename>${WRKDIR}</filename> (see below).
|
|
This is useful for building packages on several
|
|
architectures, then <filename>${PKGSRCDIR}</filename>
|
|
can be NFS-mounted while <filename>${WRKOBJDIR}</filename>
|
|
is local to every architecture. (It should be noted that
|
|
<varname>PKGSRCDIR</varname> should not be set by the user
|
|
— it is an internal definition which refers to the
|
|
root of the pkgsrc tree. It is possible to have many
|
|
pkgsrc tree instances.)</para>
|
|
</listitem>
|
|
<listitem><para><varname>LOCALPATCHES</varname>:
|
|
Directory for local patches that aren't part of pkgsrc.
|
|
See <xref linkend="components.patches" /> for more
|
|
information.</para>
|
|
</listitem>
|
|
<listitem><para><varname>PKGMAKECONF</varname>: Location of
|
|
the &mk.conf; file used by a package's
|
|
BSD-style Makefile. If this is not set,
|
|
<varname>MAKECONF</varname> is set to
|
|
<filename>/dev/null</filename> to avoid picking up
|
|
settings used by builds in <filename>/usr/src</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>DEPENDS_TARGET</varname>:
|
|
By default, dependencies are only installed, and no binary
|
|
package is created for them. You can set this variable to
|
|
<literal>package</literal> to automatically create binary
|
|
packages after installing dependencies.</para>
|
|
</listitem>
|
|
|
|
<!-- DISTDIR -->
|
|
<!-- FAILOVER_FETCH -->
|
|
</itemizedlist></para>
|
|
</sect1>
|
|
|
|
<sect1 id="variables-affecting-installation">
|
|
<title>Variables affecting the installation process</title>
|
|
|
|
<para>A growing number of packages support installation into a
|
|
subdirectory of <varname>WRKDIR</varname>. This allows a package
|
|
to be built, before the actual filesystem is touched. DESTDIR
|
|
support exists in two variations:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Basic DESTDIR support means that the package
|
|
installation and packaging is still run as
|
|
root.</para></listitem>
|
|
<listitem><para>Full DESTDIR support can run the complete build,
|
|
installation and packaging as normal user. Root privileges are
|
|
only needed to add packages.</para></listitem>
|
|
</itemizedlist>
|
|
<para>To use the DESTDIR support, set either
|
|
<varname>USE_DESTDIR=yes</varname> to use the basic support for
|
|
packages that offer it or <varname>USE_DESTDIR=full</varname> to
|
|
get the full support with fallback to basic
|
|
support. <varname>USE_DESTDIR=full</varname> needs <filename
|
|
role="pkg">pkgtools/pkg_install</filename> version 20070802 (or
|
|
newer). It might become the default DESTDIR support later.</para>
|
|
<para>DESTDIR support changes the behaviour of various targets
|
|
slightly. To install a package after building it, use
|
|
<literal>package-install</literal>. <literal>package</literal> and
|
|
<literal>install</literal> don't do that any
|
|
longer. <literal>package-install</literal> can be used as
|
|
<varname>DEPENDS_TARGET</varname>. <literal>bin-install</literal>
|
|
will ask for the root password to install the package and fail,
|
|
<literal>package-install</literal> will ask again.</para>
|
|
<para>With basic DESTDIR support, <userinput>make
|
|
clean</userinput> needs to be run as root.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="conf.compiler">
|
|
<title>Selecting and configuring the compiler</title>
|
|
|
|
<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. Note that only one real compiler
|
|
should be listed (e.g. <quote><varname>sunpro gcc</varname></quote>
|
|
is not allowed).</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>
|
|
|
|
<sect2 id="conf.cflags">
|
|
<title>Additional flags to the compiler (<varname>CFLAGS</varname>)</title>
|
|
|
|
<para>If you wish to set the <varname>CFLAGS</varname> variable,
|
|
please make sure to use the <literal>+=</literal> operator
|
|
instead of the <literal>=</literal> operator:</para>
|
|
|
|
<programlisting>
|
|
CFLAGS+= -your -flags
|
|
</programlisting>
|
|
|
|
<para>Using <varname>CFLAGS=</varname> (i.e. without the
|
|
<quote>+</quote>) may lead to problems with packages that need
|
|
to add their own flags. Also, you may want to take a look at
|
|
the <filename role="pkg">devel/cpuflags</filename> package if
|
|
you're interested in optimization for the current CPU.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="conf.ldflags">
|
|
<title>Additional flags to the linker (<varname>LDFLAGS</varname>)</title>
|
|
|
|
<para>If you want to pass flags to the linker, both in the configure
|
|
step and the build step, you can do this in two ways. Either set
|
|
<varname>LDFLAGS</varname> or <varname>LIBS</varname>. The difference
|
|
between the two is that <varname>LIBS</varname> will be appended to
|
|
the command line, while <varname>LDFLAGS</varname> come earlier.
|
|
<varname>LDFLAGS</varname> is pre-loaded with rpath settings for ELF
|
|
machines depending on the setting of <varname>USE_IMAKE</varname> or
|
|
the inclusion of <filename>mk/x11.buildlink3.mk</filename>. As with
|
|
<varname>CFLAGS</varname>, if you do not wish to override these
|
|
settings, use the <literal>+=</literal> operator:</para>
|
|
<programlisting>
|
|
LDFLAGS+= -your -linkerflags
|
|
</programlisting>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- Configuration files -->
|
|
<!-- PKG_SYSCONFBASE -->
|
|
<!-- PKG_SYSCONFDIR.foobar -->
|
|
|
|
<!-- Security -->
|
|
<!-- PKGVULNDIR -->
|
|
|
|
<sect1 id="developer-advanced-settings">
|
|
<title>Developer/advanced settings</title>
|
|
|
|
<!-- USE_ABI_DEPENDS -->
|
|
<para>XXX
|
|
<itemizedlist>
|
|
<listitem><para><varname>PKG_DEVELOPER</varname>:
|
|
Run some sanity checks that package developers want:
|
|
<itemizedlist>
|
|
<listitem><para>make sure patches apply with zero
|
|
fuzz</para></listitem>
|
|
<listitem><para>run check-shlibs to see that all
|
|
binaries will find their shared libs.</para>
|
|
<!-- XXX: some more stuff -->
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem><para><varname>PKG_DEBUG_LEVEL</varname>: The level
|
|
of debugging output which is displayed whilst making and
|
|
installing the package. The default value for this is 0,
|
|
which will not display the commands as they are executed
|
|
(normal, default, quiet operation); the value 1 will display
|
|
all shell commands before their invocation, and the value 2
|
|
will display both the shell commands before their invocation,
|
|
and their actual execution progress with <command>set
|
|
-x</command> will be displayed.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- pkginstall-related variables -->
|
|
<!-- PKG_REGISTER_SHELLS -->
|
|
<!-- PKG_RCD_SCRIPTS -->
|
|
|
|
<sect1 id="selecting-build-options">
|
|
<title>Selecting Build Options</title>
|
|
|
|
<para>Some packages have build time options, usually to select
|
|
between different dependencies, enable optional support for big
|
|
dependencies or enable experimental features.</para>
|
|
|
|
<para>To see which options, if any, a package supports, and which
|
|
options are mutually exclusive, run <command>make
|
|
show-options</command>, for example:</para>
|
|
|
|
<programlisting>
|
|
The following options are supported by this package:
|
|
ssl Enable SSL support.
|
|
Exactly one of the following gecko options is required:
|
|
firefox Use firefox as gecko rendering engine.
|
|
mozilla Use mozilla as gecko rendering engine.
|
|
At most one of the following database options may be selected:
|
|
mysql Enable support for MySQL database.
|
|
pgsql Enable support for PostgreSQL database.
|
|
|
|
These options are enabled by default: firefox
|
|
These options are currently enabled: mozilla ssl
|
|
</programlisting>
|
|
|
|
<para>The following variables can be defined in
|
|
&mk.conf; to select which options to
|
|
enable for a package: <varname>PKG_DEFAULT_OPTIONS</varname>,
|
|
which can be used to select or disable options for all packages
|
|
that support them, and
|
|
<varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>,
|
|
which can be used to select or disable options specifically for
|
|
package <replaceable>pkgbase</replaceable>. Options listed in
|
|
these variables are selected, options preceded by <quote>-</quote>
|
|
are disabled. A few examples:</para>
|
|
|
|
<screen>
|
|
&uprompt; <command>grep "PKG.*OPTION" &mk.conf;</command>
|
|
PKG_DEFAULT_OPTIONS= -arts -dvdread -esound
|
|
PKG_OPTIONS.kdebase= debug -sasl
|
|
PKG_OPTIONS.apache= suexec </screen>
|
|
|
|
<para>It is important to note that options that were specifically
|
|
suggested by the package maintainer must be explicitely removed if
|
|
you do not wish to include the option. If you are unsure you can view
|
|
the current state with <command>make show-options</command>.</para>
|
|
|
|
<para>The following settings are consulted in the order given, and
|
|
the last setting that selects or disables an option is
|
|
used:</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>the default options as suggested by the package
|
|
maintainer</para></listitem>
|
|
|
|
<listitem><para>the options implied by the settings of legacy
|
|
variables (see below)</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_DEFAULT_OPTIONS</varname></para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname></para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>For groups of mutually exclusive options, the last option
|
|
selected is used, all others are automatically disabled. If an
|
|
option of the group is explicitly disabled, the previously
|
|
selected option, if any, is used. It is an error if no option
|
|
from a required group of options is selected, and building the
|
|
package will fail.</para>
|
|
|
|
<para>Before the options framework was introduced, build options
|
|
were selected by setting a variable (often named
|
|
<varname>USE_<replaceable>FOO</replaceable></varname>) in
|
|
&mk.conf; for each option. To ease
|
|
transition to the options framework for the user, these legacy
|
|
variables are converted to the appropriate options setting
|
|
(<varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>)
|
|
automatically. A warning is issued to prompt the user to update
|
|
&mk.conf; to use the options framework
|
|
directly. Support for the legacy variables will be removed
|
|
eventually.</para>
|
|
</sect1>
|
|
|
|
</chapter>
|