937 lines
37 KiB
XML
937 lines
37 KiB
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=<package></quote>, and the &man.make.1; variable
|
|
<varname>DIRNAME</varname> will be set to the prefix of the installed
|
|
package <package>, 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>
|