Annotation of htdocs/docs/pkgsrc/build.html, revision 1.2

1.1       dsieger     1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html>
                      3: <head>
                      4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
                      5: <title>Chapter 16. The build process</title>
1.2     ! rillig      6: <link rel="stylesheet" href="/global.css" type="text/css">
1.1       dsieger     7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
                      8: <link rel="start" href="index.html" title="The pkgsrc guide">
                      9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
                     10: <link rel="prev" href="options.html" title="Chapter 15. Options handling">
                     11: <link rel="next" href="tools.html" title="Chapter 17. Tools needed for building or running">
                     12: </head>
                     13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
                     14: <div class="navheader">
                     15: <table width="100%" summary="Navigation header">
                     16: <tr><th colspan="3" align="center">Chapter 16. The build process</th></tr>
                     17: <tr>
                     18: <td width="20%" align="left">
                     19: <a accesskey="p" href="options.html">Prev</a> </td>
                     20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
                     21: <td width="20%" align="right"> <a accesskey="n" href="tools.html">Next</a>
                     22: </td>
                     23: </tr>
                     24: </table>
                     25: <hr>
                     26: </div>
                     27: <div class="chapter" lang="en">
                     28: <div class="titlepage"><div><div><h2 class="title">
                     29: <a name="build"></a>Chapter 16. The build process</h2></div></div></div>
                     30: <div class="toc">
                     31: <p><b>Table of Contents</b></p>
                     32: <dl>
                     33: <dt><span class="sect1"><a href="build.html#build.intro">16.1. Introduction</a></span></dt>
                     34: <dt><span class="sect1"><a href="build.html#build.prefix">16.2. Program location</a></span></dt>
                     35: <dt><span class="sect1"><a href="build.html#build.builddirs">16.3. Directories used during the build process</a></span></dt>
                     36: <dt><span class="sect1"><a href="build.html#build.running">16.4. Running a phase</a></span></dt>
                     37: <dt><span class="sect1"><a href="build.html#build.fetch">16.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
                     38: <dd><dl>
                     39: <dt><span class="sect2"><a href="build.html#build.fetch.what">16.5.1. What to fetch and where to get it from</a></span></dt>
                     40: <dt><span class="sect2"><a href="build.html#build.fetch.how">16.5.2. How are the files fetched?</a></span></dt>
                     41: </dl></dd>
                     42: <dt><span class="sect1"><a href="build.html#build.checksum">16.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
                     43: <dt><span class="sect1"><a href="build.html#build.extract">16.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
                     44: <dt><span class="sect1"><a href="build.html#build.patch">16.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
                     45: <dt><span class="sect1"><a href="build.html#build.tools">16.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
                     46: <dt><span class="sect1"><a href="build.html#build.wrapper">16.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
                     47: <dt><span class="sect1"><a href="build.html#build.configure">16.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
                     48: <dt><span class="sect1"><a href="build.html#build.build">16.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
                     49: <dt><span class="sect1"><a href="build.html#build.test">16.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
                     50: <dt><span class="sect1"><a href="build.html#build.install">16.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
                     51: <dt><span class="sect1"><a href="build.html#build.package">16.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
                     52: <dt><span class="sect1"><a href="build.html#build.clean">16.16. Cleaning up</a></span></dt>
                     53: <dt><span class="sect1"><a href="build.html#build.helpful-targets">16.17. Other helpful targets</a></span></dt>
                     54: </dl>
                     55: </div>
                     56: <div class="sect1" lang="en">
                     57: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                     58: <a name="build.intro"></a>16.1. Introduction</h2></div></div></div>
                     59: <p>This chapter gives a detailed description on how a package is
                     60:     built. Building a package is separated into different
                     61:     <span class="emphasis"><em>phases</em></span> (for example <code class="varname">fetch</code>,
                     62:     <code class="varname">build</code>, <code class="varname">install</code>), all of which are
                     63:     described in the following sections. Each phase is splitted into
                     64:     so-called <span class="emphasis"><em>stages</em></span>, which take the name of the
                     65:     containing phase, prefixed by one of <code class="varname">pre-</code>,
                     66:     <code class="varname">do-</code> or <code class="varname">post-</code>. (Examples are
                     67:     <code class="varname">pre-configure</code>, <code class="varname">post-build</code>.) Most
                     68:     of the actual work is done in the <code class="varname">do-*</code> stages.</p>
                     69: <p>Never override the regular targets (like
                     70:     <code class="varname">fetch</code>), if you have to, override the
                     71:     <code class="varname">do-*</code> ones instead.</p>
                     72: <p>The basic steps for building a program are always the same.  First
                     73:     the program's source (<span class="emphasis"><em>distfile</em></span>) must be brought to
                     74:     the local system and then extracted. After any pkgsrc-specific patches
                     75:     to compile properly are applied, the software can be configured, then
                     76:     built (usually by compiling), and finally the generated binaries, etc.
                     77:     can be put into place on the system.</p>
                     78: <p>To get more details about what is happening at each step,
                     79:     you can set the <code class="varname">PKG_VERBOSE</code> variable, or the
                     80:     <code class="varname">PATCH_DEBUG</code> variable if you are just interested
                     81:     in more details about the <span class="emphasis"><em>patch</em></span> step.</p>
                     82: </div>
                     83: <div class="sect1" lang="en">
                     84: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                     85: <a name="build.prefix"></a>16.2. Program location</h2></div></div></div>
                     86: <p>Before outlining the process performed by the NetBSD package system in
                     87:     the next section, here's a brief discussion on where programs are
                     88:     installed, and which variables influence this.</p>
                     89: <p>The automatic variable <code class="varname">PREFIX</code> indicates
                     90:     where all files of the final program shall be installed. It is
                     91:     usually set to <code class="varname">LOCALBASE</code>
                     92:     (<code class="filename">/usr/pkg</code>), or <code class="varname">CROSSBASE</code>
                     93:     for pkgs in the <code class="filename">cross</code> category.  The value of
                     94:     <code class="varname">PREFIX</code> needs to be put
                     95:     into the various places in the program's source where paths to
                     96:     these files are encoded.  See <a href="components.html#components.patches" title="10.3. patches/*">Section 10.3, &#8220;patches/*&#8221;</a> and <a href="fixes.html#fixes.libtool" title="18.3.1. Shared libraries - libtool">Section 18.3.1, &#8220;Shared libraries - libtool&#8221;</a> for more details.</p>
                     97: <p>When choosing which of these variables to use,
                     98:     follow the following rules:</p>
                     99: <div class="itemizedlist"><ul type="disc">
                    100: <li><p><code class="varname">PREFIX</code> always points to the location
                    101:        where the current pkg will be installed.  When referring to a
                    102:        pkg's own installation path, use
                    103:        &#8220;<span class="quote">${PREFIX}</span>&#8221;.</p></li>
                    104: <li><p><code class="varname">LOCALBASE</code> is where all non-X11 pkgs
                    105:        are installed.  If you need to construct a -I or -L argument
                    106:        to the compiler to find includes and libraries installed by
                    107:        another non-X11 pkg, use &#8220;<span class="quote">${LOCALBASE}</span>&#8221;. The name
                    108:        <code class="varname">LOCALBASE</code> stems from FreeBSD, which
                    109:        installed all packages in <code class="filename">/usr/local</code>. As
                    110:        pkgsrc leaves <code class="filename">/usr/local</code> for the system
                    111:        administrator, this variable is a misnomer.</p></li>
                    112: <li><p><code class="varname">X11BASE</code> is where the actual X11
                    113:        distribution (from xsrc, etc.) is installed. When looking for
                    114:        <span class="emphasis"><em>standard</em></span> X11 includes (not those
                    115:        installed by a package), use &#8220;<span class="quote">${X11BASE}</span>&#8221;.</p></li>
                    116: <li>
                    117: <p>X11-based packages are special in that they may be
                    118:        installed in either <code class="varname">X11BASE</code> or
                    119:        <code class="varname">LOCALBASE</code>.</p>
                    120: <p>Usually, X11 packages should be installed under
                    121:        <code class="varname">LOCALBASE</code> whenever possible.  Note that you
                    122:        will need to include
                    123:        <code class="filename">../../mk/x11.buildlink3.mk</code> in them to
                    124:        request the presence of X11 and to get the right compilation
                    125:        flags.</p>
                    126: <p>Even though, there are some packages that cannot be installed
                    127:        under <code class="varname">LOCALBASE</code>: those that come with app-defaults
                    128:        files. These packages are special and they must be placed under
                    129:        <code class="varname">X11BASE</code>. To accomplish this, set either
                    130:        <code class="varname">USE_X11BASE</code> or <code class="varname">USE_IMAKE</code> in
                    131:        your package.</p>
                    132: <p>Some notes: If you need
                    133:        to find includes or libraries installed by a pkg that has
                    134:        <code class="varname">USE_IMAKE</code> or <code class="varname">USE_X11BASE</code> in
                    135:        its pkg <code class="filename">Makefile</code>, you need to look in
                    136:        <span class="emphasis"><em>both</em></span> <code class="filename">${X11BASE}</code> and
                    137:        <code class="filename">${LOCALBASE}</code>. To force installation of
                    138:        all X11 packages in <code class="varname">LOCALBASE</code>, the
                    139:        <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/xpkgwedge/README.html" target="_top"><code class="filename">pkgtools/xpkgwedge</code></a> package
                    140:        is enabled by default.</p>
                    141: </li>
                    142: <li><p><code class="varname">X11PREFIX</code> should be used to refer to
                    143:        the installed location of an X11
                    144:        package. <code class="varname">X11PREFIX</code> will be set to
                    145:        <code class="varname">X11BASE</code> if xpkgwedge is not installed, and
                    146:        to <code class="varname">LOCALBASE</code> if xpkgwedge is
                    147:        installed.</p></li>
                    148: <li>
                    149: <p>If xpkgwedge is installed, it is possible to have some
                    150:        packages installed in <code class="varname">X11BASE</code> and some in
                    151:        <code class="varname">LOCALBASE</code>.  To determine the prefix of an
                    152:        installed package, the <code class="varname">EVAL_PREFIX</code>
                    153:        definition can be used. It takes pairs in the format
                    154:        &#8220;<span class="quote">DIRNAME=&lt;package&gt;</span>&#8221;, and the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>
                    155:        variable <code class="varname">DIRNAME</code> will be set to the prefix
                    156:        of the installed package &lt;package&gt;, or
                    157:        &#8220;<span class="quote">${X11PREFIX}</span>&#8221; if the package is not
                    158:        installed.</p>
                    159: <p>This is best illustrated by example.</p>
                    160: <p>The following lines are taken from
                    161:        <code class="filename">pkgsrc/wm/scwm/Makefile</code>:</p>
                    162: <pre class="programlisting">
                    163: EVAL_PREFIX+=           GTKDIR=gtk+
                    164: CONFIGURE_ARGS+=        --with-guile-prefix=${LOCALBASE:Q}
                    165: CONFIGURE_ARGS+=        --with-gtk-prefix=${GTKDIR:Q}
                    166: CONFIGURE_ARGS+=        --enable-multibyte
                    167: </pre>
                    168: <p>Specific defaults can be defined for the packages
                    169:        evaluated using <code class="varname">EVAL_PREFIX</code>, by using a
                    170:        definition of the form:</p>
                    171: <pre class="programlisting">
                    172: GTKDIR_DEFAULT= ${LOCALBASE}
                    173: </pre>
                    174: <p>where <code class="varname">GTKDIR</code> corresponds
                    175:        to the first definition in
                    176:        the <code class="varname">EVAL_PREFIX</code> pair.</p>
                    177: </li>
                    178: <li><p>Within <code class="filename">${PREFIX}</code>, packages should
                    179:        install files according to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?hier+7+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">hier</span>(7)</span></a>, with the exception that
                    180:        manual pages go into <code class="filename">${PREFIX}/man</code>, not
                    181:        <code class="filename">${PREFIX}/share/man</code>.</p></li>
                    182: </ul></div>
                    183: </div>
                    184: <div class="sect1" lang="en">
                    185: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    186: <a name="build.builddirs"></a>16.3. Directories used during the build process</h2></div></div></div>
                    187: <p>When building a package, a number of directories is used to store
                    188:     source files, temporary files, pkgsrc-internal files, and so on. These
                    189:     directories are explained here.</p>
                    190: <p>Some of the directory variables contain relative pathnames. There
                    191:     are two common base directories for these relative directories:
                    192:     <code class="varname">PKGSRCDIR/PKGPATH</code> is used for directories that are
                    193:     pkgsrc-specific. <code class="varname">WRKSRC</code> is used for directories
                    194:     inside the package itself.</p>
                    195: <div class="variablelist"><dl>
                    196: <dt><span class="term"><code class="varname">PKGSRCDIR</code></span></dt>
                    197: <dd><p>This is an absolute pathname that points to the pkgsrc
                    198:       root directory. Generally, you don't need
                    199:       it.</p></dd>
                    200: <dt><span class="term"><code class="varname">PKGDIR</code></span></dt>
                    201: <dd><p>This is an absolute pathname that points to the
                    202:       current package.</p></dd>
                    203: <dt><span class="term"><code class="varname">PKGPATH</code></span></dt>
                    204: <dd><p>This is a pathname relative to
                    205:       <code class="varname">PKGSRCDIR</code> that points to the current
                    206:       package.</p></dd>
                    207: <dt><span class="term"><code class="varname">WRKDIR</code></span></dt>
                    208: <dd><p>This is an absolute pathname pointing to the directory
                    209:       where all work takes place. The distfiles are extracted to this
                    210:       directory. It also contains temporary directories and log files used by
                    211:       the various pkgsrc frameworks, like <span class="emphasis"><em>buildlink</em></span> or
                    212:       the <span class="emphasis"><em>wrappers</em></span>.</p></dd>
                    213: <dt><span class="term"><code class="varname">WRKSRC</code></span></dt>
                    214: <dd><p>This is an absolute pathname pointing to the directory
                    215:       where the distfiles are extracted. It is usually a direct subdirectory
                    216:       of <code class="varname">WRKDIR</code>, and often it's the only directory entry
                    217:       that isn't hidden. This variable may be changed by a package
                    218:       <code class="filename">Makefile</code>.</p></dd>
                    219: </dl></div>
                    220: </div>
                    221: <div class="sect1" lang="en">
                    222: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    223: <a name="build.running"></a>16.4. Running a phase</h2></div></div></div>
                    224: <p>You can run a particular phase by typing <span><strong class="command">make
                    225:     phase</strong></span>, where <span class="emphasis"><em>phase</em></span> is the name of the
                    226:     phase. This will automatically run all phases that are required for this
                    227:     phase. The default phase is <code class="varname">build</code>, that is, when you
                    228:     run <span><strong class="command">make</strong></span> without parameters in a package directory,
                    229:     the package will be built, but not installed.</p>
                    230: </div>
                    231: <div class="sect1" lang="en">
                    232: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    233: <a name="build.fetch"></a>16.5. The <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
                    234: <p>The first step in building a package is to fetch the
                    235:     distribution files (distfiles) from the sites that are providing
                    236:     them. This is the task of the <span class="emphasis"><em>fetch</em></span>
                    237:     phase.</p>
                    238: <div class="sect2" lang="en">
                    239: <div class="titlepage"><div><div><h3 class="title">
                    240: <a name="build.fetch.what"></a>16.5.1. What to fetch and where to get it from</h3></div></div></div>
                    241: <p>In simple cases, <code class="varname">MASTER_SITES</code>
                    242:       defines all URLs from where the distfile, whose name is
                    243:       derived from the <code class="varname">DISTNAME</code> variable, is
                    244:       fetched. The more complicated cases are described
                    245:       below.</p>
                    246: <p>The variable <code class="varname">DISTFILES</code> specifies
                    247:       the list of distfiles that have to be fetched. Its value
                    248:       defaults to <code class="literal">${DISTNAME}${EXTRACT_SUFX}</code>,
                    249:       so that most packages don't need to define it at all.
                    250:       <code class="varname">EXTRACT_SUFX</code> is
                    251:       <code class="literal">.tar.gz</code> by default, but can be changed
                    252:       freely. Note that if your package requires additional
                    253:       distfiles to the default one, you cannot just append the
                    254:       additional filenames using the <code class="literal">+=</code>
                    255:       operator, but you have write for example:</p>
                    256: <pre class="programlisting">
                    257: DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz
                    258: </pre>
                    259: <p>Each distfile is fetched from a list of sites, usually
                    260:       <code class="varname">MASTER_SITES</code>. If the package has multiple
                    261:       <code class="varname">DISTFILES</code> or multiple
                    262:       <code class="varname">PATCHFILES</code> from different sites, you can
                    263:       set
                    264:       <code class="varname">SITES.<em class="replaceable"><code>distfile</code></em></code>
                    265:       to the list of URLs where the file
                    266:       <code class="filename"><em class="replaceable"><code>distfile</code></em></code>
                    267:       (including the suffix) can be found.</p>
                    268: <pre class="programlisting">
                    269: DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
                    270: DISTFILES+=     foo-file.tar.gz
                    271: SITES.foo-file.tar.gz= \
                    272: http://www.somewhere.com/somehow/ \
                    273: http://www.somewhereelse.com/mirror/somehow/
                    274: </pre>
                    275: <p>When actually fetching the distfiles, each item from
                    276:       <code class="varname">MASTER_SITES</code> or
                    277:       <code class="varname">SITES.*</code> gets the name of each distfile
                    278:       appended to it, without an intermediate slash. Therefore,
                    279:       all site values have to end with a slash or other separator
                    280:       character. This allows for example to set
                    281:       <code class="varname">MASTER_SITES</code> to a URL of a CGI script
                    282:       that gets the name of the distfile as a parameter. In this
                    283:       case, the definition would look like:</p>
                    284: <pre class="programlisting">
                    285: MASTER_SITES=   http://www.example.com/download.cgi?file=
                    286: </pre>
                    287: <p>There are some predefined values for
                    288:       <code class="varname">MASTER_SITES</code>, which can be used in
                    289:       packages.  The names of the variables should speak for
                    290:       themselves.</p>
                    291: <pre class="programlisting">
                    292: ${MASTER_SITE_APACHE}
                    293: ${MASTER_SITE_BACKUP}
                    294: ${MASTER_SITE_CYGWIN}
                    295: ${MASTER_SITE_DEBIAN}
                    296: ${MASTER_SITE_FREEBSD}
                    297: ${MASTER_SITE_FREEBSD_LOCAL}
                    298: ${MASTER_SITE_GENTOO}
                    299: ${MASTER_SITE_GNOME}
                    300: ${MASTER_SITE_GNU}
                    301: ${MASTER_SITE_GNUSTEP}
                    302: ${MASTER_SITE_IFARCHIVE}
                    303: ${MASTER_SITE_KDE}
                    304: ${MASTER_SITE_MOZILLA}
                    305: ${MASTER_SITE_MYSQL}
                    306: ${MASTER_SITE_OPENOFFICE}
                    307: ${MASTER_SITE_PERL_CPAN}
                    308: ${MASTER_SITE_PGSQL}
                    309: ${MASTER_SITE_R_CRAN}
                    310: ${MASTER_SITE_SOURCEFORGE}
                    311: ${MASTER_SITE_SOURCEFORGE_JP}
                    312: ${MASTER_SITE_SUNSITE}
                    313: ${MASTER_SITE_SUSE}
                    314: ${MASTER_SITE_TEX_CTAN}
                    315: ${MASTER_SITE_XCONTRIB}
                    316: ${MASTER_SITE_XEMACS}
                    317: </pre>
                    318: <p>Some explanations for the less self-explaining ones:
                    319:       <code class="varname">MASTER_SITE_BACKUP</code> contains backup sites
                    320:       for packages that are maintained in <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/%24%7BDIST_SUBDIR%7D" target="_top">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}</a>.  <code class="varname">MASTER_SITE_LOCAL</code> contains local
                    321:       package source distributions that are maintained in <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/LOCAL_PORTS/" target="_top">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/LOCAL_PORTS/</a>.</p>
                    322: <p>If you choose one of these predefined sites, you may
                    323:       want to specify a subdirectory of that site. Since these
                    324:       macros may expand to more than one actual site, you
                    325:       <span class="emphasis"><em>must</em></span> use the following construct to
                    326:       specify a subdirectory:</p>
                    327: <pre class="programlisting">
                    328: MASTER_SITES=   ${MASTER_SITE_GNU:=subdirectory/name/}
                    329: MASTER_SITES=   ${MASTER_SITE_SOURCEFORGE:=project_name/}
                    330: </pre>
                    331: <p>Note the trailing slash after the subdirectory
                    332:       name.</p>
                    333: </div>
                    334: <div class="sect2" lang="en">
                    335: <div class="titlepage"><div><div><h3 class="title">
                    336: <a name="build.fetch.how"></a>16.5.2. How are the files fetched?</h3></div></div></div>
                    337: <p>The <span class="emphasis"><em>fetch</em></span> phase makes sure that
                    338:       all the distfiles exist in a local directory
                    339:       (<code class="varname">DISTDIR</code>, which can be set by the pkgsrc
                    340:       user). If the files do not exist, they are fetched using
                    341:       commands of the form</p>
                    342: <pre class="programlisting">
                    343: ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
                    344: </pre>
                    345: <p>where <code class="literal">${site}</code> varies through
                    346:       several possibilities in turn: first,
                    347:       <code class="varname">MASTER_SITE_OVERRIDE</code> is tried, then the
                    348:       sites specified in either <code class="varname">SITES.file</code> if
                    349:       defined, else <code class="varname">MASTER_SITES</code> or
                    350:       <code class="varname">PATCH_SITES</code>, as applies, then finally the
                    351:       value of <code class="varname">MASTER_SITE_BACKUP</code>. The order of
                    352:       all except the first and the last can be optionally sorted
                    353:       by the user, via setting either
                    354:       <code class="varname">MASTER_SORT_RANDOM</code>, and
                    355:       <code class="varname">MASTER_SORT_AWK</code> or
                    356:       <code class="varname">MASTER_SORT_REGEX</code>.</p>
                    357: <p>The distfiles mirror run by the NetBSD Foundation uses the
                    358:       <span class="emphasis"><em>mirror-distfiles</em></span> target to mirror the
                    359:       distfiles, if they are freely distributable.  Packages setting
                    360:       <code class="varname">NO_SRC_ON_FTP</code> (usually to
                    361:       &#8220;<span class="quote">${RESTRICTED}</span>&#8221;) will not have their distfiles
                    362:       mirrored.</p>
                    363: </div>
                    364: </div>
                    365: <div class="sect1" lang="en">
                    366: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    367: <a name="build.checksum"></a>16.6. The <span class="emphasis"><em>checksum</em></span> phase</h2></div></div></div>
                    368: <p>After the distfile(s) are fetched, their checksum is
                    369:     generated and compared with the checksums stored in the
                    370:     distinfo file. If the checksums don't match, the build is
                    371:     aborted. This is to ensure the same distfile is used for
                    372:     building, and that the distfile wasn't changed, e.g. by some
                    373:     malign force, deliberately changed distfiles on the master
                    374:     distribution site or network lossage.</p>
                    375: </div>
                    376: <div class="sect1" lang="en">
                    377: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    378: <a name="build.extract"></a>16.7. The <span class="emphasis"><em>extract</em></span> phase</h2></div></div></div>
                    379: <p>When the distfiles are present on the local system, they
                    380:     need to be extracted, as they usually come in the form of some
                    381:     compressed archive format.</p>
                    382: <p>By default, all <code class="varname">DISTFILES</code> are
                    383:     extracted. If you only need some of them, you can set the
                    384:     <code class="varname">EXTRACT_ONLY</code> variable to the list of those
                    385:     files.</p>
                    386: <p>Extracting the files is usually done by a little
                    387:     program, <code class="filename">mk/extract/extract</code>, which
                    388:     already knows how to extract various archive formats, so most
                    389:     likely you will not need to change anything here. But if you
                    390:     need, the following variables may help you:</p>
                    391: <div class="variablelist"><dl>
                    392: <dt><span class="term"><code class="varname">EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</code></span></dt>
                    393: <dd><p>Use these variables to override the default
                    394:       options for an extract command, which are defined in
                    395:       <code class="filename">mk/extract/extract</code>.</p></dd>
                    396: <dt><span class="term"><code class="varname">EXTRACT_USING</code></span></dt>
                    397: <dd><p>This variable can be set to
                    398:       <code class="literal">gtar</code>, <code class="literal">nbtar</code> (which is the
                    399:       default value), <code class="literal">pax</code>, or an
                    400:       absolute pathname pointing to the command with which tar
                    401:       archives should be
                    402:       extracted.</p></dd>
                    403: </dl></div>
                    404: <p>If the <code class="filename">extract</code> program doesn't
                    405:     serve your needs, you can also override the
                    406:     <code class="varname">EXTRACT_CMD</code> variable, which holds the
                    407:     command used for extracting the files. This command is
                    408:     executed in the <code class="filename">${WRKSRC}</code>
                    409:     directory. During execution of this command, the shell
                    410:     variable <code class="varname">extract_file</code> holds the absolute
                    411:     pathname of the file that is going to be extracted.</p>
                    412: <p>And if that still does not suffice, you can override the
                    413:     <code class="varname">do-extract</code> target in the package
                    414:     Makefile.</p>
                    415: </div>
                    416: <div class="sect1" lang="en">
                    417: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    418: <a name="build.patch"></a>16.8. The <span class="emphasis"><em>patch</em></span> phase</h2></div></div></div>
                    419: <p>After extraction, all the patches named by the
                    420:     <code class="varname">PATCHFILES</code>, those present in the patches
                    421:     subdirectory of the package as well as in
                    422:     $LOCALPATCHES/$PKGPATH (e.g.
                    423:     <code class="filename">/usr/local/patches/graphics/png</code>) are
                    424:     applied.  Patchfiles ending in <code class="filename">.Z</code> or
                    425:     <code class="filename">.gz</code> are uncompressed before they are
                    426:     applied, files ending in <code class="filename">.orig</code> or
                    427:     <code class="filename">.rej</code> are ignored. Any special options to
                    428:     <a href="http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> can be handed in
                    429:     <code class="varname">PATCH_DIST_ARGS</code>.  See <a href="components.html#components.patches" title="10.3. patches/*">Section 10.3, &#8220;patches/*&#8221;</a> for more details.</p>
                    430: <p>By default <a href="http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given special args to make
                    431:     it fail if the patches apply with some lines of fuzz. Please
                    432:     fix (regen) the patches so that they apply cleanly. The
                    433:     rationale behind this is that patches that don't apply cleanly
                    434:     may end up being applied in the wrong place, and cause severe
                    435:     harm there.</p>
                    436: </div>
                    437: <div class="sect1" lang="en">
                    438: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    439: <a name="build.tools"></a>16.9. The <span class="emphasis"><em>tools</em></span> phase</h2></div></div></div>
                    440: <p>This is covered in <a href="tools.html" title="Chapter 17. Tools needed for building or running">Chapter 17, <i>Tools needed for building or running</i></a>.
                    441:     </p>
                    442: </div>
                    443: <div class="sect1" lang="en">
                    444: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    445: <a name="build.wrapper"></a>16.10. The <span class="emphasis"><em>wrapper</em></span> phase</h2></div></div></div>
                    446: <p>This phase creates wrapper programs for the compilers and
                    447:     linkers. The following variables can be used to tweak the
                    448:     wrappers.</p>
                    449: <div class="variablelist"><dl>
                    450: <dt><span class="term"><code class="varname">ECHO_WRAPPER_MSG</code></span></dt>
                    451: <dd><p>The command used to print progress
                    452:       messages. Does nothing by default. Set to
                    453:       <code class="literal">${ECHO}</code> to see the progress
                    454:       messages.</p></dd>
                    455: <dt><span class="term"><code class="varname">WRAPPER_DEBUG</code></span></dt>
                    456: <dd><p>This variable can be set to
                    457:       <code class="literal">yes</code> (default) or <code class="literal">no</code>,
                    458:       depending on whether you want additional information in the
                    459:       wrapper log file.</p></dd>
                    460: <dt><span class="term"><code class="varname">WRAPPER_UPDATE_CACHE</code></span></dt>
                    461: <dd><p>This variable can be set to
                    462:       <code class="literal">yes</code> or <code class="literal">no</code>, depending
                    463:       on whether the wrapper should use its cache, which will
                    464:       improve the speed. The default value is
                    465:       <code class="literal">yes</code>, but is forced to
                    466:       <code class="literal">no</code> if the platform does not support
                    467:       it.</p></dd>
                    468: <dt><span class="term"><code class="varname">WRAPPER_REORDER_CMDS</code></span></dt>
                    469: <dd><p>A list of reordering commands. A reordering
                    470:       command has the form
                    471:       <code class="literal">reorder:l:<em class="replaceable"><code>lib1</code></em>:<em class="replaceable"><code>lib2</code></em></code>.
                    472:       It ensures that that
                    473:       <code class="literal">-l<em class="replaceable"><code>lib1</code></em></code> occurs
                    474:       before <code class="literal">-l<em class="replaceable"><code>lib2</code></em></code>.
                    475:       </p></dd>
                    476: <dt><span class="term"><code class="varname">WRAPPER_TRANSFORM_CMDS</code></span></dt>
                    477: <dd><p>A list of transformation commands. [TODO:
                    478:       investigate further]</p></dd>
                    479: </dl></div>
                    480: </div>
                    481: <div class="sect1" lang="en">
                    482: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    483: <a name="build.configure"></a>16.11. The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
                    484: <p>Most pieces of software need information on the header
                    485:     files, system calls, and library routines which are available
                    486:     on the platform they run on. The process of determining this
                    487:     information is known as configuration, and is usually
                    488:     automated. In most cases, a script is supplied with the
                    489:     distfiles, and its invocation results in generation of header
                    490:     files, Makefiles, etc.</p>
                    491: <p>If the package contains a configure script, this can be
                    492:     invoked by setting <code class="varname">HAS_CONFIGURE</code> to
                    493:     &#8220;<span class="quote">yes</span>&#8221;. If the configure script is a GNU autoconf
                    494:     script, you should set <code class="varname">GNU_CONFIGURE</code> to
                    495:     &#8220;<span class="quote">yes</span>&#8221; instead. What happens in the
                    496:     <span class="emphasis"><em>configure</em></span> phase is roughly:</p>
                    497: <pre class="programlisting">
                    498: .for d in ${CONFIGURE_DIRS}
                    499:         cd ${WRKSRC} \
                    500:         &amp;&amp; cd ${d} \
                    501:         &amp;&amp; env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
                    502: .endfor
                    503: </pre>
                    504: <p><code class="varname">CONFIGURE_DIRS</code> (default:
                    505:     &#8220;<span class="quote">.</span>&#8221;) is a list of pathnames relative to
                    506:     <code class="varname">WRKSRC</code>. In each of these directories, the
                    507:     configure script is run with the environment
                    508:     <code class="varname">CONFIGURE_ENV</code> and arguments
                    509:     <code class="varname">CONFIGURE_ARGS</code>. The variables
                    510:     <code class="varname">CONFIGURE_ENV</code>,
                    511:     <code class="varname">CONFIGURE_SCRIPT</code> (default:
                    512:     &#8220;<span class="quote">./configure</span>&#8221;) and
                    513:     <code class="varname">CONFIGURE_ARGS</code> may all be changed by the
                    514:     package.</p>
                    515: <p>If the program uses an <code class="filename">Imakefile</code>
                    516:     for configuration, the appropriate steps can be invoked by
                    517:     setting <code class="varname">USE_IMAKE</code> to
                    518:     &#8220;<span class="quote">yes</span>&#8221;. (If you only want the package installed in
                    519:     <code class="varname">${X11PREFIX}</code> but xmkmf not being run, set
                    520:     <code class="varname">USE_X11BASE</code> instead.)  You can add variables to
                    521:     xmkmf's environment by adding them to the
                    522:     <code class="varname">SCRIPTS_ENV</code> variable.</p>
                    523: <p>If there is no configure step at all, set
                    524:     <code class="varname">NO_CONFIGURE</code> to &#8220;<span class="quote">yes</span>&#8221;.</p>
                    525: </div>
                    526: <div class="sect1" lang="en">
                    527: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    528: <a name="build.build"></a>16.12. The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
                    529: <p>For building a package, a rough equivalent of the
                    530:     following code is executed.</p>
                    531: <pre class="programlisting">
                    532: .for d in ${BUILD_DIRS}
                    533:         cd ${WRKSRC} \
                    534:         &amp;&amp; cd ${d} \
                    535:         &amp;&amp; env ${MAKE_ENV} \
                    536:             ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
                    537:                 -f ${MAKE_FILE} \
                    538:                 ${BUILD_TARGET}
                    539: .endfor
                    540: </pre>
                    541: <p><code class="varname">BUILD_DIRS</code> (default:
                    542:     &#8220;<span class="quote">.</span>&#8221;) is a list of pathnames relative to
                    543:     <code class="varname">WRKSRC</code>. In each of these directories,
                    544:     <code class="varname">MAKE_PROGRAM</code> is run with the environment
                    545:     <code class="varname">MAKE_ENV</code> and arguments
                    546:     <code class="varname">BUILD_MAKE_FLAGS</code>. The variables
                    547:     <code class="varname">MAKE_ENV</code>,
                    548:     <code class="varname">BUILD_MAKE_FLAGS</code>,
                    549:     <code class="varname">MAKE_FILE</code> and
                    550:     <code class="varname">BUILD_TARGET</code> may all be changed by the
                    551:     package.</p>
                    552: <p>The default value of <code class="varname">MAKE_PROGRAM</code> is
                    553:     &#8220;<span class="quote">gmake</span>&#8221; if <code class="varname">USE_TOOLS</code> contains
                    554:     &#8220;<span class="quote">gmake</span>&#8221;, &#8220;<span class="quote">make</span>&#8221; otherwise. The
                    555:     default value of <code class="varname">MAKE_FILE</code> is
                    556:     &#8220;<span class="quote">Makefile</span>&#8221;, and <code class="varname">BUILD_TARGET</code>
                    557:     defaults to &#8220;<span class="quote">all</span>&#8221;.</p>
                    558: <p>If there is no build step at all, set
                    559:     <code class="varname">NO_BUILD</code> to &#8220;<span class="quote">yes</span>&#8221;.</p>
                    560: </div>
                    561: <div class="sect1" lang="en">
                    562: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    563: <a name="build.test"></a>16.13. The <span class="emphasis"><em>test</em></span> phase</h2></div></div></div>
                    564: <p>[TODO]</p>
                    565: </div>
                    566: <div class="sect1" lang="en">
                    567: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    568: <a name="build.install"></a>16.14. The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
                    569: <p>Once the build stage has completed, the final step is to
                    570:     install the software in public directories, so users can
                    571:     access the programs and files.</p>
                    572: <p>In the <span class="emphasis"><em>install</em></span> phase, a rough
                    573:     equivalent of the following code is executed. Additionally,
                    574:     before and after this code, much magic is performed to do
                    575:     consistency checks, registering the package, and so on.</p>
                    576: <pre class="programlisting">
                    577: .for d in ${INSTALL_DIRS}
                    578:         cd ${WRKSRC} \
                    579:         &amp;&amp; cd ${d} \
                    580:         &amp;&amp; env ${MAKE_ENV} \
                    581:             ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
                    582:                 -f ${MAKE_FILE} \
                    583:                 ${INSTALL_TARGET}
                    584: .endfor
                    585: </pre>
                    586: <p>The variable's meanings are analogous to the ones in the
                    587:     <span class="emphasis"><em>build</em></span> phase.
                    588:     <code class="varname">INSTALL_DIRS</code> defaults to
                    589:     <code class="varname">BUILD_DIRS</code>. <code class="varname">INSTALL_TARGET</code>
                    590:     is &#8220;<span class="quote">install</span>&#8221; by default, plus
                    591:     &#8220;<span class="quote">install.man</span>&#8221; if <code class="varname">USE_IMAKE</code> is
                    592:     defined and <code class="varname">NO_INSTALL_MANPAGES</code> is not
                    593:     defined.</p>
                    594: <p>In the <span class="emphasis"><em>install</em></span> phase, the following
                    595:     variables are useful. They are all variations of the
                    596:     <a href="http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a> command that have the owner, group and
                    597:     permissions preset. <code class="varname">INSTALL</code> is the plain
                    598:     install command. The specialized variants, together with their
                    599:     intended use, are:</p>
                    600: <div class="variablelist"><dl>
                    601: <dt><span class="term"><code class="varname">INSTALL_PROGRAM_DIR</code></span></dt>
                    602: <dd><p>directories that contain
                    603:       binaries</p></dd>
                    604: <dt><span class="term"><code class="varname">INSTALL_SCRIPT_DIR</code></span></dt>
                    605: <dd><p>directories that contain
                    606:       scripts</p></dd>
                    607: <dt><span class="term"><code class="varname">INSTALL_LIB_DIR</code></span></dt>
                    608: <dd><p>directories that contain shared and static
                    609:       libraries</p></dd>
                    610: <dt><span class="term"><code class="varname">INSTALL_DATA_DIR</code></span></dt>
                    611: <dd><p>directories that contain data
                    612:       files</p></dd>
                    613: <dt><span class="term"><code class="varname">INSTALL_MAN_DIR</code></span></dt>
                    614: <dd><p>directories that contain man
                    615:       pages</p></dd>
                    616: <dt><span class="term"><code class="varname">INSTALL_PROGRAM</code></span></dt>
                    617: <dd><p>binaries that can be stripped from debugging
                    618:       symbols</p></dd>
                    619: <dt><span class="term"><code class="varname">INSTALL_SCRIPT</code></span></dt>
                    620: <dd><p>binaries that cannot be
                    621:       stripped</p></dd>
                    622: <dt><span class="term"><code class="varname">INSTALL_GAME</code></span></dt>
                    623: <dd><p>game
                    624:       binaries</p></dd>
                    625: <dt><span class="term"><code class="varname">INSTALL_LIB</code></span></dt>
                    626: <dd><p>shared and static
                    627:       libraries</p></dd>
                    628: <dt><span class="term"><code class="varname">INSTALL_DATA</code></span></dt>
                    629: <dd><p>data files</p></dd>
                    630: <dt><span class="term"><code class="varname">INSTALL_GAME_DATA</code></span></dt>
                    631: <dd><p>data files for
                    632:       games</p></dd>
                    633: <dt><span class="term"><code class="varname">INSTALL_MAN</code></span></dt>
                    634: <dd><p>man pages</p></dd>
                    635: </dl></div>
                    636: <p>Some other variables are:</p>
                    637: <div class="variablelist"><dl>
                    638: <dt><span class="term"><code class="varname">INSTALLATION_DIRS</code></span></dt>
                    639: <dd><p>A list of directories relative to
                    640:       <code class="varname">PREFIX</code> that are created by pkgsrc at the
                    641:       beginning of the <span class="emphasis"><em>install</em></span> phase.
                    642:       The package is supposed to create all needed directories itself
                    643:       before installing files to it and list all other directories here.
                    644:       </p></dd>
                    645: </dl></div>
                    646: <p>In the rare cases that a package shouldn't install anything,
                    647:     set <code class="varname">NO_INSTALL</code> to &#8220;<span class="quote">yes</span>&#8221;. This is
                    648:     mostly relevant for packages in the <code class="filename">regress</code>
                    649:     category.</p>
                    650: </div>
                    651: <div class="sect1" lang="en">
                    652: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    653: <a name="build.package"></a>16.15. The <span class="emphasis"><em>package</em></span> phase</h2></div></div></div>
                    654: <p>Once the install stage has completed, a binary package of
                    655:     the installed files can be built.  These binary packages can be
                    656:     used for quick installation without previous compilation, e.g. by
                    657:     the <span><strong class="command">make bin-install</strong></span> or by using
                    658:     <span><strong class="command">pkg_add</strong></span>.</p>
                    659: <p>By default, the binary packages are created in
                    660:     <code class="filename">${PACKAGES}/All</code> and symlinks are created in
                    661:     <code class="filename">${PACKAGES}/<em class="replaceable"><code>category</code></em></code>,
                    662:     one for each category in the <code class="varname">CATEGORIES</code>
                    663:     variable.  <code class="varname">PACKAGES</code> defaults to
                    664:     <code class="filename">pkgsrc/packages</code>.</p>
                    665: <p>If there should be no binary package, set
                    666:     <code class="varname">NO_PACKAGE</code> to &#8220;<span class="quote">yes</span>&#8221;.
                    667:     This should only be used in rare cases, like when a package
                    668:     definitely is only usable on the machine where it is built and even
                    669:     then, a binary package can be useful.</p>
                    670: </div>
                    671: <div class="sect1" lang="en">
                    672: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    673: <a name="build.clean"></a>16.16. Cleaning up</h2></div></div></div>
                    674: <p>Once you're finished with a package, you can clean the work
                    675:     directory by running <span><strong class="command">make clean</strong></span>.  If you want
                    676:     to clean the work directories of all dependencies too, use
                    677:     <span><strong class="command">make clean-depends</strong></span>.</p>
                    678: </div>
                    679: <div class="sect1" lang="en">
                    680: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    681: <a name="build.helpful-targets"></a>16.17. Other helpful targets</h2></div></div></div>
                    682: <div class="variablelist"><dl>
                    683: <dt><span class="term">pre/post-*</span></dt>
                    684: <dd><p>For any of the main targets described in the
                    685:          previous section, two auxiliary targets exist with
                    686:          &#8220;<span class="quote">pre-</span>&#8221; and &#8220;<span class="quote">post-</span>&#8221; used as a
                    687:          prefix for the main target's name.  These targets are
                    688:          invoked before and after the main target is called,
                    689:          allowing extra configuration or installation steps be
                    690:          performed from a package's Makefile, for example, which
                    691:          a program's configure script or install target
                    692:          omitted.</p></dd>
                    693: <dt><span class="term">do-*</span></dt>
                    694: <dd><p>Should one of the main targets do the wrong thing,
                    695:          and should there be no variable to fix this, you can
                    696:          redefine it with the do-* target.  (Note that redefining
                    697:          the target itself instead of the do-* target is a bad
                    698:          idea, as the pre-* and post-* targets won't be called
                    699:          anymore, etc.) You will not usually need to do
                    700:          this.</p></dd>
                    701: <dt><span class="term">reinstall</span></dt>
                    702: <dd>
                    703: <p>If you did a <span><strong class="command">make install</strong></span> and
                    704:          you noticed some file was not installed properly, you
                    705:          can repeat the installation with this target, which will
                    706:          ignore the &#8220;<span class="quote">already installed</span>&#8221; flag.</p>
                    707: <p>This is the default value of
                    708:          <code class="varname">DEPENDS_TARGET</code> except in the case of
                    709:          <span><strong class="command">make update</strong></span> and <span><strong class="command">make
                    710:          package</strong></span>, where the defaults are
                    711:          &#8220;<span class="quote">package</span>&#8221; and &#8220;<span class="quote">update</span>&#8221;,
                    712:          respectively.</p>
                    713: </dd>
                    714: <dt><span class="term">deinstall</span></dt>
                    715: <dd>
                    716: <p>This target does a <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a> in the
                    717:          current directory, effectively de-installing the
                    718:          package. The following variables can be used to tune the
                    719:          behaviour:</p>
                    720: <div class="variablelist"><dl>
                    721: <dt><span class="term"><code class="varname">PKG_VERBOSE</code></span></dt>
                    722: <dd><p>Add a "-v" to the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a> command.</p></dd>
                    723: <dt><span class="term"><code class="varname">DEINSTALLDEPENDS</code></span></dt>
                    724: <dd><p>Remove all packages that require (depend on)
                    725:                the given package.  This can be used to remove any
                    726:                packages that may have been pulled in by a given
                    727:                package, e.g. if <span><strong class="command">make deinstall
                    728:                DEINSTALLDEPENDS=1</strong></span> is done in
                    729:                <code class="filename">pkgsrc/x11/kde</code>, this is
                    730:                likely to remove whole KDE. Works by adding
                    731:                &#8220;<span class="quote">-R</span>&#8221; to the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a>
                    732:                command line.</p></dd>
                    733: </dl></div>
                    734: </dd>
                    735: <dt><span class="term">bin-install</span></dt>
                    736: <dd><p>Install a binary package from local disk and via FTP
                    737:          from a list of sites (see the
                    738:          <code class="varname">BINPKG_SITES</code> variable), and do a
                    739:          <span><strong class="command">make package</strong></span> if no binary package is
                    740:          available anywhere.  The arguments given to
                    741:          <span><strong class="command">pkg_add</strong></span> can be set via
                    742:          <code class="varname">BIN_INSTALL_FLAGS</code> e.g., to do verbose
                    743:          operation, etc.</p></dd>
                    744: <dt><span class="term">update</span></dt>
                    745: <dd>
                    746: <p>This target causes the current package to be
                    747:          updated to the latest version.  The package and all
                    748:          depending packages first get de-installed, then current
                    749:          versions of the corresponding packages get compiled and
                    750:          installed.  This is similar to manually noting which
                    751:          packages are currently installed, then performing a
                    752:          series of <span><strong class="command">make deinstall</strong></span> and
                    753:          <span><strong class="command">make install</strong></span> (or whatever
                    754:          <code class="varname">UPDATE_TARGET</code> is set to) for these
                    755:          packages.</p>
                    756: <p>You can use the &#8220;<span class="quote">update</span>&#8221; target to
                    757:          resume package updating in case a previous <span><strong class="command">make
                    758:          update</strong></span> was interrupted for some reason.
                    759:          However, in this case, make sure you don't call
                    760:          <span><strong class="command">make clean</strong></span> or otherwise remove the
                    761:          list of dependent packages in <code class="varname">WRKDIR</code>.
                    762:          Otherwise, you lose the ability to automatically update
                    763:          the current package along with the dependent packages
                    764:          you have installed.</p>
                    765: <p>Resuming an interrupted <span><strong class="command">make
                    766:          update</strong></span> will only work as long as the package
                    767:          tree remains unchanged.  If the source code for one of
                    768:          the packages to be updated has been changed, resuming
                    769:          <span><strong class="command">make update</strong></span> will most certainly
                    770:          fail!</p>
                    771: <p>The following variables can be used either on the
                    772:          command line or in <code class="filename">/etc/mk.conf</code> to
                    773:          alter the behaviour of <span><strong class="command">make
                    774:          update</strong></span>:</p>
                    775: <div class="variablelist"><dl>
                    776: <dt><span class="term"><code class="varname">UPDATE_TARGET</code></span></dt>
                    777: <dd><p>Install target to recursively use for the
                    778:                updated package and the dependent packages.
                    779:                Defaults to <code class="varname">DEPENDS_TARGET</code> if
                    780:                set, &#8220;<span class="quote">install</span>&#8221; otherwise for
                    781:                <span><strong class="command">make update</strong></span>.  Other good
                    782:                targets are &#8220;<span class="quote">package</span>&#8221; or
                    783:                &#8220;<span class="quote">bin-install</span>&#8221;.  Do not set this to
                    784:                &#8220;<span class="quote">update</span>&#8221; or you will get stuck in an
                    785:                endless loop!</p></dd>
                    786: <dt><span class="term"><code class="varname">NOCLEAN</code></span></dt>
                    787: <dd><p>Don't clean up after updating.  Useful if
                    788:                you want to leave the work sources of the updated
                    789:                packages around for inspection or other purposes.
                    790:                Be sure you eventually clean up the source tree
                    791:                (see the &#8220;<span class="quote">clean-update</span>&#8221; target below)
                    792:                or you may run into troubles with old source code
                    793:                still lying around on your next
                    794:                <span><strong class="command">make</strong></span> or <span><strong class="command">make
                    795:                update</strong></span>.</p></dd>
                    796: <dt><span class="term"><code class="varname">REINSTALL</code></span></dt>
                    797: <dd><p>Deinstall each package before installing
                    798:                (making <code class="varname">DEPENDS_TARGET</code>). This
                    799:                may be necessary if the
                    800:                &#8220;<span class="quote">clean-update</span>&#8221; target (see below) was
                    801:                called after interrupting a running <span><strong class="command">make
                    802:                update</strong></span>.</p></dd>
                    803: <dt><span class="term"><code class="varname">DEPENDS_TARGET</code></span></dt>
                    804: <dd><p>Allows you to disable recursion and hardcode
                    805:                the target for packages.  The default is
                    806:                &#8220;<span class="quote">update</span>&#8221; for the update target,
                    807:                facilitating a recursive update of prerequisite
                    808:                packages.  Only set
                    809:                <code class="varname">DEPENDS_TARGET</code> if you want to
                    810:                disable recursive updates. Use
                    811:                <code class="varname">UPDATE_TARGET</code> instead to just
                    812:                set a specific target for each package to be
                    813:                installed during <span><strong class="command">make update</strong></span>
                    814:                (see above).</p></dd>
                    815: </dl></div>
                    816: </dd>
                    817: <dt><span class="term">clean-update</span></dt>
                    818: <dd>
                    819: <p>Clean the source tree for all packages that would
                    820:          get updated if <span><strong class="command">make update</strong></span> was called
                    821:          from the current directory.  This target should not be
                    822:          used if the current package (or any of its depending
                    823:          packages) have already been de-installed (e.g., after
                    824:          calling <span><strong class="command">make update</strong></span>) or you may lose
                    825:          some packages you intended to update. As a rule of
                    826:          thumb: only use this target <span class="emphasis"><em>before</em></span>
                    827:          the first time you run <span><strong class="command">make update</strong></span>
                    828:          and only if you have a dirty package tree (e.g., if you
                    829:          used <code class="varname">NOCLEAN</code>).</p>
                    830: <p>If you are unsure about whether your tree is
                    831:          clean, you can either perform a <span><strong class="command">make
                    832:          clean</strong></span> at the top of the tree, or use the
                    833:          following sequence of commands from the directory of the
                    834:          package you want to update (<span class="emphasis"><em>before</em></span>
                    835:          running <span><strong class="command">make update</strong></span> for the first
                    836:          time, otherwise you lose all the packages you wanted to
                    837:          update!):</p>
                    838: <pre class="screen">
                    839: <code class="prompt">#</code> <strong class="userinput"><code>make clean-update</code></strong>
                    840: <code class="prompt">#</code> <strong class="userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
                    841: <code class="prompt">#</code> <strong class="userinput"><code>make update</code></strong>
                    842:          </pre>
                    843: <p>The following variables can be used either on the
                    844:          command line or in <code class="filename">/etc/mk.conf</code> to
                    845:          alter the behaviour of <span><strong class="command">make
                    846:          clean-update</strong></span>:</p>
                    847: <div class="variablelist"><dl>
                    848: <dt><span class="term"><code class="varname">CLEAR_DIRLIST</code></span></dt>
                    849: <dd><p>After <span><strong class="command">make clean</strong></span>, do not
                    850:                reconstruct the list of directories to update for
                    851:                this package.  Only use this if <span><strong class="command">make
                    852:                update</strong></span> successfully installed all
                    853:                packages you wanted to update.  Normally, this is
                    854:                done automatically on <span><strong class="command">make
                    855:                update</strong></span>, but may have been suppressed by
                    856:                the <code class="varname">NOCLEAN</code> variable (see
                    857:                above).</p></dd>
                    858: </dl></div>
                    859: </dd>
                    860: <dt><span class="term">replace</span></dt>
                    861: <dd>
                    862: <p>Update the installation of the current package.  This
                    863:          differs from update in that it does not replace dependent
                    864:          packages.  You will need to install <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_tarup/README.html" target="_top"><code class="filename">pkgtools/pkg_tarup</code></a> for this
                    865:          target to work.</p>
                    866: <p><span class="emphasis"><em>Be careful when using this
                    867:          target!</em></span> There are no guarantees that dependent
                    868:          packages will still work, in particular they will most
                    869:          certainly break if you <span><strong class="command">make replace</strong></span> a
                    870:          library package whose shared library major version changed
                    871:          between your installed version and the new one.  For this
                    872:          reason, this target is not officially supported and only
                    873:          recommended for advanced users.</p>
                    874: </dd>
                    875: <dt><span class="term">info</span></dt>
                    876: <dd><p>This target invokes <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_info</span>(1)</span></a> for the current
                    877:          package. You can use this to check which version of a
                    878:          package is installed.</p></dd>
                    879: <dt><span class="term">index</span></dt>
                    880: <dd>
                    881: <p>This is a top-level command, i.e. it should be used in
                    882:          the <code class="filename">pkgsrc</code> directory.  It creates a
                    883:          database of all packages in the local pkgsrc tree, including
                    884:          dependencies, comment, maintainer, and some other useful
                    885:          information.  Individual entries are created by running
                    886:          <span><strong class="command">make describe</strong></span> in the packages'
                    887:          directories.  This index file is saved as
                    888:          <code class="filename">pkgsrc/INDEX</code>.  It can be displayed in
                    889:          verbose format by running <span><strong class="command">make
                    890:          print-index</strong></span>.  You can search in it with
                    891:          <span><strong class="command">make search
                    892:          key=<em class="replaceable"><code>something</code></em></strong></span>.  You can
                    893:          extract a list of all packages that depend on a particular
                    894:          one by running <span><strong class="command">make show-deps
                    895:          PKG=<em class="replaceable"><code>somepackage</code></em></strong></span>.</p>
                    896: <p>Running this command takes a very long time, some
                    897:          hours even on fast machines!</p>
                    898: </dd>
                    899: <dt><span class="term">readme</span></dt>
                    900: <dd>
                    901: <p>This target generates a
                    902:          <code class="filename">README.html</code> file, which can be
                    903:          viewed using a browser such as <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/firefox/README.html" target="_top"><code class="filename">www/firefox</code></a> or <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/links/README.html" target="_top"><code class="filename">www/links</code></a>.  The generated files
                    904:          contain references to any packages which are in the
                    905:          <code class="varname">PACKAGES</code> directory on the local
                    906:          host. The generated files can be made to refer to URLs
                    907:          based on <code class="varname">FTP_PKG_URL_HOST</code> and
                    908:          <code class="varname">FTP_PKG_URL_DIR</code>. For example, if I
                    909:          wanted to generate <code class="filename">README.html</code>
                    910:          files which pointed to binary packages on the local
                    911:          machine, in the directory
                    912:          <code class="filename">/usr/packages</code>, set
                    913:          <code class="varname">FTP_PKG_URL_HOST=file://localhost</code> and
                    914:          <code class="varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
                    915:          <code class="varname">${PACKAGES}</code> directory and its
                    916:          subdirectories will be searched for all the binary
                    917:          packages.</p>
                    918: <p>The target can be run at the toplevel or in category
                    919:          directories, in which case it descends recursively.</p>
                    920: </dd>
                    921: <dt><span class="term">readme-all</span></dt>
                    922: <dd><p>This is a top-level command, run it in
                    923:          <code class="filename">pkgsrc</code>.  Use this target to create a
                    924:          file <code class="filename">README-all.html</code> which contains a
                    925:          list of all packages currently available in the NetBSD
                    926:          Packages Collection, together with the category they belong
                    927:          to and a short description. This file is compiled from the
                    928:          <code class="filename">pkgsrc/*/README.html</code> files, so be sure
                    929:          to run this <span class="emphasis"><em>after</em></span> a <span><strong class="command">make
                    930:          readme</strong></span>.</p></dd>
                    931: <dt><span class="term">cdrom-readme</span></dt>
                    932: <dd><p>This is very much the same as the
                    933:          &#8220;<span class="quote">readme</span>&#8221; target (see above), but is to be
                    934:          used when generating a pkgsrc tree to be written to a
                    935:          CD-ROM.  This target also produces
                    936:          <code class="filename">README.html</code> files, and can be made
                    937:          to refer to URLs based on
                    938:          <code class="varname">CDROM_PKG_URL_HOST</code> and
                    939:          <code class="varname">CDROM_PKG_URL_DIR</code>.</p></dd>
                    940: <dt><span class="term">show-distfiles</span></dt>
                    941: <dd><p>This target shows which distfiles and patchfiles
                    942:          are needed to build the package
                    943:          (<code class="varname">ALLFILES</code>, which contains all
                    944:          <code class="varname">DISTFILES</code> and
                    945:          <code class="varname">PATCHFILES</code>, but not
                    946:          <code class="filename">patches/*</code>).</p></dd>
                    947: <dt><span class="term">show-downlevel</span></dt>
                    948: <dd><p>This target shows nothing if the package is not
                    949:          installed. If a version of this package is installed,
                    950:          but is not the version provided in this version of
                    951:          pkgsrc, then a warning message is displayed. This target
                    952:          can be used to show which of your installed packages are
                    953:          downlevel, and so the old versions can be deleted, and
                    954:          the current ones added.</p></dd>
                    955: <dt><span class="term">show-pkgsrc-dir</span></dt>
                    956: <dd><p>This target shows the directory in the pkgsrc
                    957:          hierarchy from which the package can be built and
                    958:          installed. This may not be the same directory as the one
                    959:          from which the package was installed. This target is
                    960:          intended to be used by people who may wish to upgrade
                    961:          many packages on a single host, and can be invoked from
                    962:          the top-level pkgsrc Makefile by using the
                    963:          &#8220;<span class="quote">show-host-specific-pkgs</span>&#8221; target.</p></dd>
                    964: <dt><span class="term">show-installed-depends</span></dt>
                    965: <dd><p>This target shows which installed packages match
                    966:          the current package's <code class="varname">DEPENDS</code>. Useful
                    967:          if out of date dependencies are causing build
                    968:          problems.</p></dd>
                    969: <dt><span class="term">check-shlibs</span></dt>
                    970: <dd><p>After a package is installed, check all its
                    971:          binaries and (on ELF platforms) shared libraries to see
                    972:          if they find the shared libs they need.  Run by default
                    973:          if <code class="varname">PKG_DEVELOPER</code> is set in
                    974:          <code class="filename">/etc/mk.conf</code>.</p></dd>
                    975: <dt><span class="term">print-PLIST</span></dt>
                    976: <dd>
                    977: <p>After a &#8220;<span class="quote">make install</span>&#8221; from a new or
                    978:          upgraded pkg, this prints out an attempt to generate a
                    979:          new <code class="filename">PLIST</code> from a <span><strong class="command">find
                    980:          -newer work/.extract_done</strong></span>.  An attempt is made
                    981:          to care for shared libs etc., but it is
                    982:          <span class="emphasis"><em>strongly</em></span> recommended to review the
                    983:          result before putting it into
                    984:          <code class="filename">PLIST</code>. On upgrades, it's useful to
                    985:          diff the output of this command against an already
                    986:          existing <code class="filename">PLIST</code> file.</p>
                    987: <p>If the package installs files via <a href="http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">tar</span>(1)</span></a> or
                    988:          other methods that don't update file access times, be
                    989:          sure to add these files manually to your
                    990:          <code class="filename">PLIST</code>, as the &#8220;<span class="quote">find
                    991:          -newer</span>&#8221; command used by this target won't catch
                    992:          them!</p>
                    993: <p>See <a href="plist.html#print-PLIST" title="12.3. Tweaking output of make print-PLIST">Section 12.3, &#8220;Tweaking output of <span><strong class="command">make print-PLIST</strong></span>&#8221;</a> for more
                    994:          information on this target.</p>
                    995: </dd>
                    996: <dt><span class="term">bulk-package</span></dt>
                    997: <dd>
                    998: <p>Used to do bulk builds. If an appropriate binary
                    999:          package already exists, no action is taken. If not, this
                   1000:          target will compile, install and package it (and its
                   1001:          depends, if <code class="varname">PKG_DEPENDS</code> is set
                   1002:          properly. See <a href="binary.html#binary.configuration" title="6.3.1. Configuration">Section 6.3.1, &#8220;Configuration&#8221;</a>).
                   1003:          After creating the binary package, the sources, the
                   1004:          just-installed package and its required packages are
                   1005:          removed, preserving free disk space.</p>
                   1006: <p><span class="emphasis"><em>Beware that this target may deinstall
                   1007:          all packages installed on a system!</em></span></p>
                   1008: </dd>
                   1009: <dt><span class="term">bulk-install</span></dt>
                   1010: <dd>
                   1011: <p>Used during bulk-installs to install required
                   1012:          packages. If an up-to-date binary package is available,
                   1013:          it will be installed via <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a>. If not,
                   1014:          <span><strong class="command">make bulk-package</strong></span> will be executed,
                   1015:          but the installed binary won't be removed.</p>
                   1016: <p>A binary package is considered
                   1017:          &#8220;<span class="quote">up-to-date</span>&#8221; to be installed via
                   1018:          <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a> if:</p>
                   1019: <div class="itemizedlist"><ul type="disc">
                   1020: <li><p>None of the package's files
                   1021:              (<code class="filename">Makefile</code>, ...) were modified
                   1022:              since it was built.</p></li>
                   1023: <li><p>None of the package's required (binary)
                   1024:              packages were modified since it was built.</p></li>
                   1025: </ul></div>
                   1026: <p><span class="emphasis"><em>Beware that this target may deinstall
                   1027:          all packages installed on a system!</em></span></p>
                   1028: </dd>
                   1029: </dl></div>
                   1030: </div>
                   1031: </div>
                   1032: <div class="navfooter">
                   1033: <hr>
                   1034: <table width="100%" summary="Navigation footer">
                   1035: <tr>
                   1036: <td width="40%" align="left">
                   1037: <a accesskey="p" href="options.html">Prev</a> </td>
                   1038: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
                   1039: <td width="40%" align="right"> <a accesskey="n" href="tools.html">Next</a>
                   1040: </td>
                   1041: </tr>
                   1042: <tr>
                   1043: <td width="40%" align="left" valign="top">Chapter 15. Options handling </td>
                   1044: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
                   1045: <td width="40%" align="right" valign="top"> Chapter 17. Tools needed for building or running</td>
                   1046: </tr>
                   1047: </table>
                   1048: </div>
                   1049: </body>
                   1050: </html>

CVSweb <webmaster@jp.NetBSD.org>