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

<!-- $NetBSD: configuring.xml,v 1.21 2006/09/18 12:52:20 rillig Exp $ -->

<chapter id="configuring">
  <title>Configuring pkgsrc</title>

<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>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.</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
	    &mdash; 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. <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>PKGMAKECONF</varname>: Location of
	    the <filename>mk.conf</filename> 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="conf.compiler">
<title>Selecting and configuring the compiler</title>

  <!--	PKGSRC_COMPILER -->

<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
    <filename>/etc/mk.conf</filename> 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" /etc/mk.conf</command>
PKG_DEFAULT_OPTIONS=    -arts -dvdread -esound
PKG_OPTIONS.kdebase=    debug -sasl
PKG_OPTIONS.apache=     suexec </screen>

    <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
    <filename>/etc/mk.conf</filename> 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
    <filename>/etc/mk.conf</filename> to use the options framework
    directly.  Support for the legacy variables will be removed
    eventually.</para>
  </sect1>

</chapter>