Return to configuring.xml CVS log

Up to [cvs.NetBSD.org] / pkgsrc / doc / guide / files

Over 1200 files touched but no revisions bumped :)

RECOMMENDED is removed. It becomes ABI_DEPENDS.

BUILDLINK_RECOMMENDED.foo becomes BUILDLINK_ABI_DEPENDS.foo.

BUILDLINK_DEPENDS.foo becomes BUILDLINK_API_DEPENDS.foo.

BUILDLINK_DEPENDS does not change.

IGNORE_RECOMMENDED (which defaulted to "no") becomes USE_ABI_DEPENDS
which defaults to "yes".

Added to obsolete.mk checking for IGNORE_RECOMMENDED.

I did not manually go through and fix any aesthetic tab/spacing issues.

I have tested the above patch on DragonFly building and packaging
subversion and pkglint and their many dependencies.

I have also tested USE_ABI_DEPENDS=no on my NetBSD workstation (where I
have used IGNORE_RECOMMENDED for a long time). I have been an active user
of IGNORE_RECOMMENDED since it was available.

As suggested, I removed the documentation sentences suggesting bumping for
"security" issues.

As discussed on tech-pkg.

I will commit to revbump, pkglint, pkg_install, createbuildlink separately.

Note that if you use wip, it will fail!  I will commit to pkgsrc-wip
later (within day).

<!-- $NetBSD: configuring.xml,v 1.13 2006/04/06 06:21:57 reed Exp $ -->

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

  <sect1 id="general-configuration">
    <title>General configuration</title>

    <para>In this section, you can find some variables that apply to all
      pkgsrc packages.  The preferred method of setting these variables
      is by setting them in <filename>/etc/mk.conf</filename>.
      <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>
      </itemizedlist>
    </para>
  </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>
	<!--	DISTDIR -->
	<!--	FAILOVER_FETCH -->
      </itemizedlist>
    </para>
  </sect1>

  <!-- Compiler settings -->
  <!--	PKGSRC_COMPILER -->
  <!--	CFLAGS -->

  <!-- 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>
	<listitem><para><varname>ALLOW_VULNERABILITIES.<replaceable>pkgbase</replaceable></varname>:
	    A space separated list of vulnerability IDs that may be ignored when
		performing the automated security checks.  These IDs are listed in the
		pkg-vulnerabilities file and are displayed by
		<command>audit-packages</command> when
		it finds a vulnerable package.
	  </para>
	</listitem>
	<listitem><para><varname>SKIP_AUDIT_PACKAGES</varname>:
	    If this is set to <quote>yes</quote>, the automated security checks
		(which use the <filename role="pkg">security/audit-packages</filename>
		package) will be <emphasis role="strong">entirely</emphasis> skipped
		for <emphasis role="strong">all</emphasis> packages built.  Normally
		you'll want to use ALLOW_VULNERABILITIES instead of this.
	  </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>