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

<!-- $NetBSD: build.xml,v 1.27 2006/04/21 07:54:12 rillig Exp $ -->

<chapter id="build">
<title>The build process</title>

<sect1 id="build.intro">
<title>Introduction</title>

<para>This chapter gives a detailed description on how a package is
built. Building a package is separated into different
<emphasis>phases</emphasis> (for example <varname>fetch</varname>,
<varname>build</varname>, <varname>install</varname>), all of which are
described in the following sections. Each phase is splitted into
so-called <emphasis>stages</emphasis>, which take the name of the
containing phase, prefixed by one of <varname>pre-</varname>,
<varname>do-</varname> or <varname>post-</varname>. (Examples are
<varname>pre-configure</varname>, <varname>post-build</varname>.) Most
of the actual work is done in the <varname>do-*</varname> stages.</para>

<para>The basic steps for building a program are always the same.  First
the program's source (<emphasis>distfile</emphasis>) must be brought to
the local system and then extracted. After any pkgsrc-specific patches
to compile properly are applied, the software can be configured, then
built (usually by compiling), and finally the generated binaries, etc.
can be put into place on the system.</para>

</sect1>

  <sect1 id="build.prefix">
    <title>Program location</title>

    <para>Before outlining the process performed by the &os; package system in
      the next section, here's a brief discussion on where programs are
      installed, and which variables influence this.</para>

    <para>The automatic variable <varname>PREFIX</varname> indicates
      where all files of the final program shall be installed. It is
      usually set to <varname>LOCALBASE</varname>
      (<filename>/usr/pkg</filename>), or <varname>CROSSBASE</varname>
      for pkgs in the <quote>cross</quote> category.  The value of
      <varname>PREFIX</varname> needs to be put
      into the various places in the program's source where paths to
      these files are encoded.  See <xref
      linkend="components.patches"/> and <xref
      linkend="fixes.libtool"/> for more details.</para>

    <para>When choosing which of these variables to use,
      follow the following rules:</para>

    <itemizedlist>
      <listitem>
	<para><varname>PREFIX</varname> always points to the location where the current
	  pkg will be installed.  When referring to a pkg's own installation path,
	  use <quote>${PREFIX}</quote>.</para>
      </listitem>

      <listitem>
	<para><varname>LOCALBASE</varname> is where all non-X11 pkgs are installed.
	  If you need to construct a -I or -L argument to the compiler to find
	  includes and libraries installed by another non-X11 pkg, use
	  <quote>${LOCALBASE}</quote>.</para>
      </listitem>

      <listitem>
	<para><varname>X11BASE</varname> is where the actual X11 distribution (from
	  xsrc, etc.) is installed. When looking for
	  <emphasis>standard</emphasis> X11 includes (not
	  those installed by a pkg), use <quote>${X11BASE}</quote>.</para>
      </listitem>

      <listitem>
	<para>X11-based packages are special in that they may be installed in
	  either <varname>X11BASE</varname> or <varname>LOCALBASE</varname>.</para>

	<para>Usually, X11 packages should be installed under
	  <varname>LOCALBASE</varname> whenever possible.  Note that you will
	  need to include <filename>../../mk/x11.buildlink3.mk</filename>
	  in them to request the
	  presence of X11 and to get the right compilation flags.</para>

	<para>Even though, there are some packages that cannot be installed
	  under <varname>LOCALBASE</varname>: those that come with app-defaults
	  files. These packages are special and they must be placed under
	  <varname>X11BASE</varname>. To accomplish this, set either
	  <varname>USE_X11BASE</varname> or <varname>USE_IMAKE</varname> in
	  your package.</para>

	<para>Some notes: If you need
	  to find includes or libraries installed by a pkg that has
	  <varname>USE_IMAKE</varname> or <varname>USE_X11BASE</varname> in
	  its pkg <filename>Makefile</filename>, you need to look in
	  <emphasis>both</emphasis> <filename>${X11BASE}</filename> and
	  <filename>${LOCALBASE}</filename>. To force installation of
	  all X11 packages in <varname>LOCALBASE</varname>, the
	  <filename role="pkg">pkgtools/xpkgwedge</filename> package
	  is enabled by default.</para>
      </listitem>

      <listitem>
	<para><varname>X11PREFIX</varname> should be used to refer to the installed
	  location of an X11 package. <varname>X11PREFIX</varname> will be set to
	  <varname>X11BASE</varname> if xpkgwedge is not installed,
	  and to <varname>LOCALBASE</varname> if xpkgwedge is installed.</para>
      </listitem>

      <listitem>
	<para>If xpkgwedge is installed, it is possible to have some packages installed
	  in <varname>X11BASE</varname> and some in <varname>LOCALBASE</varname>.
	  To determine the prefix of an installed package, the
	  <varname>EVAL_PREFIX</varname> definition can be used. It takes pairs in the
	  format <quote>DIRNAME=&lt;package&gt;</quote>, and the &man.make.1; variable
	  <varname>DIRNAME</varname> will be set to the prefix of the installed
	  package &lt;package&gt;, or <quote>${X11PREFIX}</quote> if the package is
	  not installed.</para>

	<para>This is best illustrated by example.</para>

	<para>The following lines are taken from
	  <filename>pkgsrc/wm/scwm/Makefile</filename>:</para>

<programlisting>
    EVAL_PREFIX+=           GTKDIR=gtk+
    CONFIGURE_ARGS+=        --with-guile-prefix=${LOCALBASE:Q}
    CONFIGURE_ARGS+=        --with-gtk-prefix=${GTKDIR:Q}
    CONFIGURE_ARGS+=        --enable-multibyte
</programlisting>

	<para>Specific defaults can be defined for the packages evaluated using
	  <varname>EVAL_PREFIX</varname>, by using a definition of the form:</para>

<programlisting>
    GTKDIR_DEFAULT= ${LOCALBASE}
</programlisting>

	<para>where <varname>GTKDIR</varname> corresponds
	  to the first definition in
	  the <varname>EVAL_PREFIX</varname> pair.</para>
      </listitem>

      <listitem>
        <para>Within <filename>${PREFIX}</filename>, packages should
          install files according to &man.hier.7;, with the exception that
          manual pages go into <filename>${PREFIX}/man</filename>, not
          <filename>${PREFIX}/share/man</filename>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

<sect1 id="build.builddirs">
<title>Directories used during the build process</title>

<para>When building a package, a number of directories is used to store
source files, temporary files, pkgsrc-internal files, and so on. These
directories are explained here.</para>

<para>Some of the directory variables contain relative pathnames. There
are two common base directories for these relative directories:
<varname>PKGSRCDIR/PKGPATH</varname> is used for directories that are
pkgsrc-specific. <varname>WRKSRC</varname> is used for directories
inside the package itself.</para>

<variablelist>

<varlistentry><term><varname>PKGSRCDIR</varname></term>
<listitem><para>This is an absolute pathname that points to the pkgsrc
root directory. Generally, you don't need
it.</para></listitem></varlistentry>

<varlistentry><term><varname>PKGPATH</varname></term>
<listitem><para>This is a pathname relative to
<varname>PKGSRCDIR</varname> that points to the current
package.</para></listitem></varlistentry>

<varlistentry><term><varname>WRKDIR</varname></term>
<listitem><para>This is an absolute pathname pointing to the directory
where all work takes place. The distfiles are extraced to this
directory. It also contains temporary directories and log files used by
the various pkgsrc frameworks, like <emphasis>buildlink</emphasis> or
the <emphasis>wrappers</emphasis>.</para></listitem></varlistentry>

<varlistentry><term><varname>WRKSRC</varname></term>
<listitem><para>This is an absolute pathname pointing to the directory
where the distfiles are extracted. It is usually a direct subdirectory
of <varname>WRKDIR</varname>, and often it's the only directory entry
that isn't hidden. This variable may be changed by a package
<filename>Makefile</filename>.</para></listitem></varlistentry>

</variablelist>
</sect1>

<sect1 id="build.running">
<title>Running a phase</title>

<para>You can run a particular phase by typing <command>make
phase</command>, where <emphasis>phase</emphasis> is the name of the
phase. This will automatically run all phases that are required for this
phase. The default phase is <varname>build</varname>, that is, when you
run <command>make</command> without parameters in a package directory,
the package will be built, but not installed.</para>

</sect1>

<sect1 id="build.fetch">
<title>The <emphasis>fetch</emphasis> phase</title>

	  <para>This will check if the file(s) given in the variables
	    <varname>DISTFILES</varname> and <varname>PATCHFILES</varname> (as
	    defined in the package's Makefile) are present on the
	    local system in <filename>/usr/pkgsrc/distfiles</filename>. If they
	    are not present, an attempt will be made to fetch them using commands
	    of the form:</para>

<programlisting>
    ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
</programlisting>

	  <para>where ${site} varies through several possibilities in turn: first,
	    <varname>MASTER_SITE_OVERRIDE</varname> is tried, then the sites
	    specified in either <varname>SITES.file</varname> if defined, else
	    <varname>MASTER_SITES</varname> or <varname>PATCH_SITES</varname>, as
	    applies, then finally the value of
	    <varname>MASTER_SITE_BACKUP</varname>. The order of all except the
	    first can be optionally sorted by the user, via setting either
	    <varname>MASTER_SORT_AWK</varname> or
	    <varname>MASTER_SORT_REGEX</varname>.</para>

</sect1>

<sect1 id="build.checksum">
<title>The <emphasis>checksum</emphasis> phase</title>

	  <para>After the distfile(s) are fetched, their checksum is generated and
	    compared with the checksums stored in the distinfo file. If the
	    checksums don't match, the build is aborted. This is to ensure the same
	    distfile is used for building, and that the distfile wasn't changed,
	    e.g. by some malign force, deliberately changed distfiles on the master
	    distribution site or network lossage.</para>

</sect1>

<sect1 id="build.extract">
<title>The <emphasis>extract</emphasis> phase</title>

	<para>When the distfiles are present on the local system, they
	need to be extracted, as they usually come in the form of some
	compressed archive format.</para>

	<para>By default, all <varname>DISTFILES</varname> are
	extracted. If you only need some of them, you can set the
	<varname>EXTRACT_ONLY</varname> variable to the list of those
	files.</para>

	<para>Extracting the files is usually done by a little program,
	<filename>mk/scripts/extract</filename>, which already knows how
	to extract various archive formats, so most likely you will not
	need to change anything here. But if you need, the following
	variables may help you:</para>

	<variablelist>

	<varlistentry><term><varname>EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</varname></term>
	<listitem><para>Use these variables to override the default
	options for an extract command, which are defined in
	<filename>mk/scripts/extract</filename>.</para></listitem></varlistentry>

	<varlistentry><term><varname>EXTRACT_USING</varname></term>
	<listitem><para>This variable can be set to
	<literal>pax</literal>, <literal>tar</literal> or an absolute
	pathname pointing to the command with which tar archives should
	be extracted.</para></listitem></varlistentry>

	</variablelist>

	<para>If the <filename>extract</filename> program doesn't serve
	your needs, you can also override the
	<varname>EXTRACT_CMD</varname> variable, which holds the command
	used for extracting the files. This command is executed in the
	<filename>${WRKSRC}</filename> directory. During execution of
	this command, the shell variable <varname>extract_file</varname>
	holds the absolute pathname of the file that is going to be
	extracted.</para>

	<para>And if that still does not suffice, you can override the
	<varname>do-extract</varname> target in the package
	Makefile.</para>


</sect1>

<sect1 id="build.patch">
<title>The <emphasis>patch</emphasis> phase</title>

	  <para>After extraction, all the patches named by the
	    <varname>PATCHFILES</varname>, those present in the patches
	    subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
	    <filename>/usr/local/patches/graphics/png</filename>) are applied.
	    Patchfiles ending in <filename>.Z</filename> or
	    <filename>.gz</filename> are uncompressed before they are applied,
	    files ending in <filename>.orig</filename> or
	    <filename>.rej</filename> are ignored. Any special options to &man.patch.1;
	    can be handed in <varname>PATCH_DIST_ARGS</varname>.
	    See <xref linkend="components.patches"/> for more details.</para>

	  <para>By default &man.patch.1; is given special args to make it fail if the
	    patches apply with some lines of fuzz. Please fix (regen) the patches
	    so that they apply cleanly. The rationale behind this is that
	    patches that don't apply cleanly may end up being applied in the wrong
	    place, and cause severe harm there.</para>

</sect1>

<sect1 id="build.tools">
<title>The <emphasis>tools</emphasis> phase</title>

<para>This is covered in
<xref linkend="tools"/>.
</para>

</sect1>

<sect1 id="build.wrapper">
<title>The <emphasis>wrapper</emphasis> phase</title>

	<para>This phase creates wrapper programs for the compilers and
	linkers. The following variables can be used to tweak the
	wrappers.</para>

	<variablelist>

	<varlistentry><term><varname>ECHO_WRAPPER_MSG</varname></term>
		<listitem><para>The command used to print progress
		messages. Does nothing by default. Set to
		<literal>${ECHO}</literal> to see the progress
		messages.</para></listitem></varlistentry>

	<varlistentry><term><varname>WRAPPER_DEBUG</varname></term>
		<listitem><para>This variable can be set to
		<literal>yes</literal> (default) or
		<literal>no</literal>, depending on whether you want
		additional information in the wrapper log
		file.</para></listitem></varlistentry>

	<varlistentry><term><varname>WRAPPER_UPDATE_CACHE</varname></term>
		<listitem><para>This variable can be set to
		<literal>yes</literal> or <literal>no</literal>,
		depending on whether the wrapper should use its cache,
		which will improve the speed. The default value is
		<literal>yes</literal>, but is forced to
		<literal>no</literal> if the platform does not support
		it.</para></listitem></varlistentry>

	<varlistentry><term><varname>WRAPPER_REORDER_CMDS</varname></term>

		<listitem><para>A list of reordering commands. A
		reordering command has the form
		<literal>reorder:l:<replaceable>lib1</replaceable>:<replaceable>lib2</replaceable></literal>.
		It ensures that that
		<literal>-l<replaceable>lib1</replaceable></literal>
		occurs before
		<literal>-l<replaceable>lib2</replaceable></literal>.
		</para></listitem></varlistentry>

	<varlistentry><term><varname>WRAPPER_TRANSFORM_CMDS</varname></term>
		<listitem><para>A list of transformation commands. [TODO:
		investigate further]</para></listitem></varlistentry>

<!-- These should probably be internal variables
	<varlistentry><term><varname>WRAPPEES</varname></term>
		<listitem><para></para></listitem></varlistentry>
	<varlistentry><term><varname>UNWRAP_PATTERNS</varname></term>
		<listitem><para></para></listitem></varlistentry>
	<varlistentry><term><varname>UNWRAP_FILES</varname></term>
		<listitem><para></para></listitem></varlistentry>
-->

	</variablelist>
</sect1>

<sect1 id="build.configure">
<title>The <emphasis>configure</emphasis> phase</title>

<para>Most pieces of software need information on the header files,
system calls, and library routines which are available on the platform
they run on. The process of determining this information is known as
configuration, and is usually automated. In most cases, a script is
supplied with the distfiles, and its invocation results in generation of
header files, Makefiles, etc.</para>

<para>If the package contains a configure script, this can be invoked by
setting <varname>HAS_CONFIGURE</varname> to <quote>yes</quote>. If the
configure script is a GNU autoconf script, you should set
<varname>GNU_CONFIGURE</varname> to <quote>yes</quote> instead. What
happens in the <emphasis>configure</emphasis> phase is roughly:</para>

<programlisting>
    .for d in ${CONFIGURE_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${CONFIGURE_ENV} \
                ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
    .endfor
</programlisting>

<para><varname>CONFIGURE_DIRS</varname> (default: <quote>.</quote>) is a
list of pathnames relative to <varname>WRKSRC</varname>. In each of
these directories, the configure script is run with the environment
<varname>CONFIGURE_ENV</varname> and arguments
<varname>CONFIGURE_ARGS</varname>. The variables
<varname>CONFIGURE_ENV</varname>, <varname>CONFIGURE_SCRIPT</varname>
(default: <quote>./configure</quote>) and
<varname>CONFIGURE_ARGS</varname> may all be changed by the
package.</para>

<para>If the program uses an <filename>Imakefile</filename> for
configuration, the appropriate steps can be invoked by setting
<varname>USE_IMAKE</varname> to <quote>yes</quote>. (If you only want
the package installed in <varname>${X11PREFIX}</varname> but xmkmf not
being run, set <varname>USE_X11BASE</varname> instead.)</para>

</sect1>

<sect1 id="build.build">
<title>The <emphasis>build</emphasis> phase</title>

<para>For building a package, a rough equivalent of the following code
is executed.</para>

<programlisting>
    .for d in ${BUILD_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
                    -f ${MAKEFILE} ${BUILD_TARGET}
    .endfor
</programlisting>

<para><varname>BUILD_DIRS</varname> (default: <quote>.</quote>) is a
list of pathnames relative to <varname>WRKSRC</varname>. In each of
these directories, <varname>MAKE_PROGRAM</varname> is run with the
environment <varname>MAKE_ENV</varname> and arguments
<varname>BUILD_MAKE_FLAGS</varname>. The variables
<varname>MAKE_ENV</varname>, <varname>BUILD_MAKE_FLAGS</varname>,
<varname>MAKEFILE</varname> and <varname>BUILD_TARGET</varname> may all
be changed by the package.</para>

<para>The default value of <varname>MAKE_PROGRAM</varname> is
<quote>gmake</quote> if <varname>USE_TOOLS</varname> contains
<quote>gmake</quote>, <quote>make</quote> otherwise. The default value
of <varname>MAKEFILE</varname> is <quote>Makefile</quote>, and
<varname>BUILD_TARGET</varname> defaults to <quote>all</quote>.</para>

</sect1>

<sect1 id="build.test">
<title>The <emphasis>test</emphasis> phase</title>

<para>[TODO]</para>

</sect1>

<sect1 id="build.install">
<title>The <emphasis>install</emphasis> phase</title>

	<para>Once the build stage has completed, the final step is to
	install the software in public directories, so users can access
	the programs and files.</para>

	<para>In the <emphasis>install</emphasis> phase, a rough
	equivalent of the following code is executed. Additionally,
	before and after this code, much magic is performed to do
	consistency checks, registering the package, and so on.</para>

<programlisting>
    .for d in ${INSTALL_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
                    -f ${MAKEFILE} ${BUILD_TARGET}
    .endfor
</programlisting>

	<para>The variable's meanings are analogous to the ones in the
	<emphasis>build</emphasis> phase.
	<varname>INSTALL_DIRS</varname> defaults to
	<varname>BUILD_DIRS</varname>. <varname>INSTALL_TARGET</varname>
	is <quote>install</quote> by default, plus
	<quote>install.man</quote> if <varname>USE_IMAKE</varname> is
	defined.</para>

	<para>In the <emphasis>install</emphasis> phase, the following
	variables are useful. They are all variations of the
	&man.install.1; command that have the owner, group and
	permissions preset. <varname>INSTALL</varname> is the plain
	install command. The specialized variants, together with their
	intended use, are:</para>

	<variablelist>
	<varlistentry><term><varname>INSTALL_PROGRAM_DIR</varname></term>
		<listitem><para>directories that contain binaries</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_SCRIPT_DIR</varname></term>
		<listitem><para>directories that contain scripts</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_LIB_DIR</varname></term>
		<listitem><para>directories that contain shared and static libraries</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_DATA_DIR</varname></term>
		<listitem><para>directories that contain data files</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_MAN_DIR</varname></term>
		<listitem><para>directories that contain man pages</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_PROGRAM</varname></term>
		<listitem><para>binaries that can be stripped from debugging symbols</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_SCRIPT</varname></term>
		<listitem><para>binaries that cannot be stripped</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_GAME</varname></term>
		<listitem><para>game binaries</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_LIB</varname></term>
		<listitem><para>shared and static libraries</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_DATA</varname></term>
		<listitem><para>data files</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_GAME_DATA</varname></term>
		<listitem><para>data files for games</para></listitem></varlistentry>
	<varlistentry><term><varname>INSTALL_MAN</varname></term>
		<listitem><para>man pages</para></listitem></varlistentry>
	</variablelist>

	<para>Some other variables are:</para>

	<variablelist>
	<varlistentry><term><varname>INSTALLATION_DIRS</varname></term>
		<listitem><para>A list of directories relative to
		<varname>PREFIX</varname> that are created by pkgsrc at
		the beginning of the <emphasis>install</emphasis> phase. If
		this variable is set,
		<varname>NO_MTREE</varname>=<quote>yes</quote> is
		assumed, which means that the package claims to create
		all needed directories itself before installing files to
		it. Therefore this variable should only be set in
		<filename>Makefile</filename>s that are under control of
		the package's author.</para></listitem></varlistentry>
	</variablelist>


</sect1>

<sect1 id="build.package">
<title>The <emphasis>package</emphasis> phase</title>

<para>[TODO]</para>

</sect1>

  <sect1 id="build.helpful-targets">
    <title>Other helpful targets</title>

    <variablelist>
      <varlistentry>
	<term>pre/post-*</term>

	<listitem>
	  <para>For any of the main targets described in the previous section, two
	    auxiliary targets exist with <quote>pre-</quote> and
	    <quote>post-</quote> used as a prefix
	    for the main target's name.  These targets are invoked before and
	    after the main target is called, allowing extra configuration or
	    installation steps be performed from a package's Makefile, for
	    example, which a program's configure script
	    or install target omitted.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>do-*</term>

	<listitem>
	  <para>Should one of the main targets do the wrong thing, and should there
	    be no variable to fix this, you can redefine it with the do-*
	    target.  (Note that redefining the target itself instead of the
	    do-* target is a bad idea, as the pre-* and post-* targets won't be
	    called anymore, etc.) You will not usually need to do this.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>reinstall</term>

	<listitem>
	  <para>If you did a <command>make install</command> and you noticed some file
	    was not installed properly, you can repeat the installation with this
	    target, which will ignore the <quote>already installed</quote> flag.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>deinstall</term>

	<listitem>
	  <para>This target does a &man.pkg.delete.1; in the current directory,
	    effectively de-installing the package. The following variables can
	    be used to tune the behaviour:</para>

	  <variablelist>
	    <varlistentry>
	      <term><varname>PKG_VERBOSE</varname></term>

	      <listitem>
		<para>Add a "-v" to the &man.pkg.delete.1; command.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>DEINSTALLDEPENDS</varname></term>

	      <listitem>
		<para>Remove all packages that require (depend on) the given package.
		  This can be used to remove any packages that may have been pulled in
		  by a given package, e.g. if <command>make deinstall
		    DEINSTALLDEPENDS=1</command> is done in
		  <filename>pkgsrc/x11/kde</filename>, this is likely to remove whole
		  KDE. Works by adding <quote>-R</quote> to the &man.pkg.delete.1; command line.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>update</term>

	<listitem>
	  <para>This target causes the current package to be updated to the latest
	    version.  The package and all depending packages first get de-installed,
	    then current versions of the corresponding packages get compiled and
	    installed.  This is similar to manually noting which packages are
	    currently installed, then performing a series of <command>make
	      deinstall</command> and <command>make install</command> (or whatever
	    <varname>UPDATE_TARGET</varname> is set to) for these packages.</para>

	  <para>You can use the <quote>update</quote> target to resume package
	    updating in case a previous <command>make update</command> was interrupted
	    for some reason.  However, in this case, make sure you don't call
	    <command>make clean</command> or otherwise remove the list of dependent
	    packages in <varname>WRKDIR</varname>.  Otherwise, you lose the
	    ability to automatically update the current package along with the
	    dependent packages you have installed.</para>

	  <para>Resuming an interrupted <command>make update</command> will only work as
	    long as the package tree remains unchanged.  If the source code for
	    one of the packages to be updated has been changed, resuming
	    <command>make update</command> will most certainly fail!</para>

	  <para>The following variables can be used either on the command line or in
	    <filename>/etc/mk.conf</filename> to alter the behaviour of
	    <command>make update</command>:</para>

	  <variablelist>
	    <varlistentry>
	      <term><varname>UPDATE_TARGET</varname></term>

	      <listitem>
		<para>Install target to recursively use for the updated package and the
		  dependent packages.  Defaults to <varname>DEPENDS_TARGET</varname> if set,
		  <quote>install</quote> otherwise for <command>make update</command>.
		  e.g. <command>make update UPDATE_TARGET=package</command></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>NOCLEAN</varname></term>

	      <listitem>
		<para>Don't clean up after updating.  Useful if you want to leave the
		  work sources of the updated packages around for inspection or
		  other purposes.  Be sure you eventually clean up the source
		  tree (see the <quote>clean-update</quote> target below) or you may
		  run into troubles with old source code still lying around on your
		  next <command>make</command> or <command>make update</command>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>REINSTALL</varname></term>

	      <listitem>
		<para>Deinstall each package before installing (making
		  <varname>DEPENDS_TARGET</varname>). This may be necessary if the
		  <quote>clean-update</quote> target (see below) was called after
		  interrupting a running <command>make update</command>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>DEPENDS_TARGET</varname></term>

	      <listitem>
		<para>Allows you to disable recursion and hardcode the target for
		  packages.  The default is <quote>update</quote> for the update target,
		  facilitating a recursive update of prerequisite packages.
		  Only set <varname>DEPENDS_TARGET</varname> if you want to disable
		  recursive updates. Use <varname>UPDATE_TARGET</varname> instead to just
		  set a specific target for each package to be installed during
		  <command>make update</command> (see above).</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>clean-update</term>

	<listitem>
	  <para>Clean the source tree for all packages that would get updated if
	    <command>make update</command> was called from the current directory.
	    This target should not be used if the current package (or any of its
	    depending packages) have already been de-installed (e.g., after calling
	    <command>make update</command>) or you may lose some packages you intended
	    to update. As a rule of thumb: only use this target
	    <emphasis>before</emphasis> the first time you run
	    <command>make update</command> and only if you have a dirty package tree
	    (e.g., if you used <varname>NOCLEAN</varname>).</para>

	  <para>If you are unsure about whether your tree is clean, you can either
	    perform a <command>make clean</command> at the top of the tree, or use
	    the following sequence of commands from the directory of the package
	    you want to update (<emphasis>before</emphasis> running
	    <command>make update</command> for the first time, otherwise you lose
	    all the packages you wanted to update!):</para>

	  <screen><prompt>#</prompt> <userinput>make clean-update</userinput>
<prompt>#</prompt> <userinput>make clean CLEANDEPENDS=YES</userinput>
<prompt>#</prompt> <userinput>make update</userinput></screen>

	  <para>The following variables can be used either on the command line or in
	    <filename>/etc/mk.conf</filename> to alter the behaviour of
	    <command>make clean-update</command>:</para>

	  <variablelist>
	    <varlistentry>
	      <term><varname>CLEAR_DIRLIST</varname></term>

	      <listitem>
		<para>After <command>make clean</command>, do not reconstruct the list of
		  directories to update for this package.  Only use this if <command>make
		    update</command> successfully installed all packages you wanted to
		  update.  Normally, this is done automatically on <command>make
		    update</command>, but may have been suppressed by the
		  <varname>NOCLEAN</varname> variable (see above).</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>info</term>

	<listitem>
	  <para>This target invokes &man.pkg.info.1; for the current
	    package. You can use this to check which version of a package is
	    installed.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>readme</term>

	<listitem>
	  <para>This target generates a <filename>README.html</filename> file, which
	    can be viewed using a browser such as
	    <filename role="pkg">www/mozilla</filename> or
	    <filename role="pkg">www/links</filename>.
	    The generated files contain references to any
	    packages which are in the <varname>PACKAGES</varname> directory on
	    the local host. The generated files can be made to refer to URLs based on
	    <varname>FTP_PKG_URL_HOST</varname> and
	    <varname>FTP_PKG_URL_DIR</varname>. For example, if I wanted to generate
	    <filename>README.html</filename> files which pointed to binary packages
	    on the local machine, in the directory
	    <filename>/usr/packages</filename>, set
	    <varname>FTP_PKG_URL_HOST=file://localhost</varname> and
	    <varname>FTP_PKG_URL_DIR=/usr/packages</varname>. The
	    <varname>${PACKAGES}</varname> directory and its subdirectories will be
	    searched for all the binary packages.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>readme-all</term>

	<listitem>
	  <para>Use this target to create a file <filename>README-all.html</filename>
	    which contains a list of all packages currently available in the &os;
	    Packages Collection, together with the category they belong to and a
	    short description. This file is compiled from the
	    <filename>pkgsrc/*/README.html</filename> files, so be sure to run
	    this <emphasis>after</emphasis> a <command>make readme</command>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>cdrom-readme</term>

	<listitem>
	  <para>This is very much the same as the <quote>readme</quote> target (see
	    above), but is to be used when generating a pkgsrc tree to be written
	    to a CD-ROM.  This target also produces
	    <filename>README.html</filename> files, and can be made to refer
	    to URLs based on <varname>CDROM_PKG_URL_HOST</varname> and
	    <varname>CDROM_PKG_URL_DIR</varname>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>show-distfiles</term>

	<listitem>
	  <para>This target shows which distfiles and patchfiles are needed to build
	    the package. (<varname>DISTFILES</varname> and
	    <varname>PATCHFILES</varname>, but not <filename>patches/*</filename>)</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>show-downlevel</term>

	<listitem>
	  <para>This target shows nothing if the package is not installed. If a version
	    of this package is installed, but is not the version provided in this
	    version of pkgsrc, then a warning message is displayed. This target can
	    be used to show which of your installed packages are downlevel, and so
	    the old versions can be deleted, and the current ones added.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>show-pkgsrc-dir</term>

	<listitem>
	  <para>This target shows the directory in the pkgsrc hierarchy from which the
	    package can be built and installed. This may not be the same directory
	    as the one from which the package was installed. This target is intended
	    to be used by people who may wish to upgrade many packages on a single
	    host, and can be invoked from the top-level pkgsrc Makefile by using the
	    <quote>show-host-specific-pkgs</quote> target.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>show-installed-depends</term>

	<listitem>
	  <para>This target shows which installed packages match the current package's
	    <varname>DEPENDS</varname>. Useful if out of date dependencies are
	    causing build problems.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>check-shlibs</term>

	<listitem>
	  <para>After a package is installed, check all its binaries and (on ELF
	    platforms) shared libraries to see if they find the shared libs they need.
	    Run by default if <varname>PKG_DEVELOPER</varname> is set in
	    <filename>/etc/mk.conf</filename>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>print-PLIST</term>

	<listitem>
	  <para>After a <quote>make install</quote> from a new or
	    upgraded pkg, this prints out an attempt to generate a new
	    <filename>PLIST</filename> from a <command>find -newer
	    work/.extract_done</command>.  An attempt is made to care
	    for shared libs etc., but it is
	    <emphasis>strongly</emphasis> recommended to review the
	    result before putting it into
	    <filename>PLIST</filename>. On upgrades, it's useful to
	    diff the output of this command against an already
	    existing <filename>PLIST</filename> file.</para>

	  <para>If the package installs files via &man.tar.1; or other
	    methods that don't update file access times, be sure to
	    add these files manually to your
	    <filename>PLIST</filename>, as the <quote>find
	    -newer</quote> command used by this target won't catch
	    them!</para>

	  <para> See <xref linkend="print-PLIST"/> for more
	    information on this target.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>bulk-package</term>

	<listitem>
	  <para>Used to do bulk builds. If an appropriate binary package already exists,
	    no action is taken. If not, this target will compile, install and
	    package it (and its depends, if <varname>PKG_DEPENDS</varname> is
	    set properly. See <xref linkend="binary.configuration"/>).
	    After creating the binary
	    package, the sources, the just-installed package and its required
	    packages are removed, preserving free disk space.</para>

	  <para><emphasis>Beware that this target may deinstall all
	    packages installed on a system!</emphasis></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>bulk-install</term>

	<listitem>
	  <para>Used during bulk-installs to install required packages. If an
	    up-to-date binary package is available, it will be installed via
	    &man.pkg.add.1;. If not, <command>make bulk-package</command> will be executed,
	    but the installed binary won't be removed. </para>

	  <para> A binary package is considered <quote>up-to-date</quote> to be
	    installed via &man.pkg.add.1; if:</para>

	  <itemizedlist>
	    <listitem>
	      <para>None of the package's files (<filename>Makefile</filename>,
		...) were modified since it was built.</para>
	    </listitem>

	    <listitem>
	      <para>None of the package's required (binary) packages were
		modified since it was built.</para>
	    </listitem>
	  </itemizedlist>

	  <para><emphasis>Beware that this target may deinstall all
	    packages installed on a system!</emphasis></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
</chapter>