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, “patches/*”</a> and <a href="fixes.html#fixes.libtool" title="18.3.1. Shared libraries - libtool">Section 18.3.1, “Shared libraries - libtool”</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: “<span class="quote">${PREFIX}</span>”.</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 “<span class="quote">${LOCALBASE}</span>”. 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 “<span class="quote">${X11BASE}</span>”.</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: “<span class="quote">DIRNAME=<package></span>”, 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 <package>, or
157: “<span class="quote">${X11PREFIX}</span>” 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: “<span class="quote">${RESTRICTED}</span>”) 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, “patches/*”</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: “<span class="quote">yes</span>”. If the configure script is a GNU autoconf
494: script, you should set <code class="varname">GNU_CONFIGURE</code> to
495: “<span class="quote">yes</span>” 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: && cd ${d} \
501: && env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
502: .endfor
503: </pre>
504: <p><code class="varname">CONFIGURE_DIRS</code> (default:
505: “<span class="quote">.</span>”) 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: “<span class="quote">./configure</span>”) 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: “<span class="quote">yes</span>”. (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 “<span class="quote">yes</span>”.</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: && cd ${d} \
535: && 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: “<span class="quote">.</span>”) 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: “<span class="quote">gmake</span>” if <code class="varname">USE_TOOLS</code> contains
554: “<span class="quote">gmake</span>”, “<span class="quote">make</span>” otherwise. The
555: default value of <code class="varname">MAKE_FILE</code> is
556: “<span class="quote">Makefile</span>”, and <code class="varname">BUILD_TARGET</code>
557: defaults to “<span class="quote">all</span>”.</p>
558: <p>If there is no build step at all, set
559: <code class="varname">NO_BUILD</code> to “<span class="quote">yes</span>”.</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: && cd ${d} \
580: && 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 “<span class="quote">install</span>” by default, plus
591: “<span class="quote">install.man</span>” 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 “<span class="quote">yes</span>”. 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 “<span class="quote">yes</span>”.
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: “<span class="quote">pre-</span>” and “<span class="quote">post-</span>” 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 “<span class="quote">already installed</span>” 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: “<span class="quote">package</span>” and “<span class="quote">update</span>”,
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: “<span class="quote">-R</span>” 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 “<span class="quote">update</span>” 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, “<span class="quote">install</span>” otherwise for
781: <span><strong class="command">make update</strong></span>. Other good
782: targets are “<span class="quote">package</span>” or
783: “<span class="quote">bin-install</span>”. Do not set this to
784: “<span class="quote">update</span>” 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 “<span class="quote">clean-update</span>” 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: “<span class="quote">clean-update</span>” 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: “<span class="quote">update</span>” 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: “<span class="quote">readme</span>” 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: “<span class="quote">show-host-specific-pkgs</span>” 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 “<span class="quote">make install</span>” 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 “<span class="quote">find
991: -newer</span>” 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, “Tweaking output of <span><strong class="command">make print-PLIST</strong></span>”</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, “Configuration”</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: “<span class="quote">up-to-date</span>” 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>