Annotation of htdocs/docs/pkgsrc/fixes.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 18. Making your package work</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="tools.html" title="Chapter 17. Tools needed for building or running">
11: <link rel="next" href="debug.html" title="Chapter 19. Debugging">
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 18. Making your package work</th></tr>
17: <tr>
18: <td width="20%" align="left">
19: <a accesskey="p" href="tools.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="debug.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="fixes"></a>Chapter 18. Making your package work</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="fixes.html#general-operation">18.1. General operation</a></span></dt>
34: <dd><dl>
35: <dt><span class="sect2"><a href="fixes.html#portability-of-packages">18.1.1. Portability of packages</a></span></dt>
36: <dt><span class="sect2"><a href="fixes.html#pulling-vars-from-etc-mk.conf">18.1.2. How to pull in user-settable variables from <code class="filename">mk.conf</code></a></span></dt>
37: <dt><span class="sect2"><a href="fixes.html#user-interaction">18.1.3. User interaction</a></span></dt>
38: <dt><span class="sect2"><a href="fixes.html#handling-licenses">18.1.4. Handling licenses</a></span></dt>
39: <dt><span class="sect2"><a href="fixes.html#restricted-packages">18.1.5. Restricted packages</a></span></dt>
40: <dt><span class="sect2"><a href="fixes.html#dependencies">18.1.6. Handling dependencies</a></span></dt>
41: <dt><span class="sect2"><a href="fixes.html#conflicts">18.1.7. Handling conflicts with other packages</a></span></dt>
42: <dt><span class="sect2"><a href="fixes.html#not-building-packages">18.1.8. Packages that cannot or should not be built</a></span></dt>
43: <dt><span class="sect2"><a href="fixes.html#undeletable-packages">18.1.9. Packages which should not be deleted, once installed</a></span></dt>
44: <dt><span class="sect2"><a href="fixes.html#security-handling">18.1.10. Handling packages with security problems</a></span></dt>
45: <dt><span class="sect2"><a href="fixes.html#bumping-pkgrevision">18.1.11. How to handle incrementing versions when fixing an existing package</a></span></dt>
46: <dt><span class="sect2"><a href="fixes.html#fixes.subst">18.1.12. Substituting variable text in the package files (the SUBST framework)</a></span></dt>
47: </dl></dd>
48: <dt><span class="sect1"><a href="fixes.html#fixes.fetch">18.2. Fixing problems in the <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
49: <dd><dl>
50: <dt><span class="sect2"><a href="fixes.html#no-plain-download">18.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt>
51: <dt><span class="sect2"><a href="fixes.html#modified-distfiles-same-name">18.2.2. How to handle modified distfiles with the 'old' name</a></span></dt>
52: </dl></dd>
53: <dt><span class="sect1"><a href="fixes.html#fixes.configure">18.3. Fixing problems in the <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
54: <dd><dl>
55: <dt><span class="sect2"><a href="fixes.html#fixes.libtool">18.3.1. Shared libraries - libtool</a></span></dt>
56: <dt><span class="sect2"><a href="fixes.html#using-libtool">18.3.2. Using libtool on GNU packages that already support libtool</a></span></dt>
57: <dt><span class="sect2"><a href="fixes.html#autoconf-automake">18.3.3. GNU Autoconf/Automake</a></span></dt>
58: </dl></dd>
59: <dt><span class="sect1"><a href="fixes.html#programming-languages">18.4. Programming languages</a></span></dt>
60: <dd><dl>
61: <dt><span class="sect2"><a href="fixes.html#basic-programming-languages">18.4.1. C, C++, and Fortran</a></span></dt>
62: <dt><span class="sect2"><a href="fixes.html#java-programming-language">18.4.2. Java</a></span></dt>
63: <dt><span class="sect2"><a href="fixes.html#perl-scripts">18.4.3. Packages containing perl scripts</a></span></dt>
64: <dt><span class="sect2"><a href="fixes.html#other-programming-languages">18.4.4. Other programming languages</a></span></dt>
65: </dl></dd>
66: <dt><span class="sect1"><a href="fixes.html#fixes.build">18.5. Fixing problems in the <span class="emphasis"><em>build</em></span> phase</a></span></dt>
67: <dd><dl>
68: <dt><span class="sect2"><a href="fixes.html#fixes.build.cpp">18.5.1. Compiling C and C++ code conditionally</a></span></dt>
69: <dt><span class="sect2"><a href="fixes.html#compiler-bugs">18.5.2. How to handle compiler bugs</a></span></dt>
70: <dt><span class="sect2"><a href="fixes.html#undefined-reference">18.5.3. Undefined reference to “<span class="quote">...</span>”</a></span></dt>
71: <dt><span class="sect2"><a href="fixes.html#out-of-memory">18.5.4. Running out of memory</a></span></dt>
72: </dl></dd>
73: <dt><span class="sect1"><a href="fixes.html#fixes.install">18.6. Fixing problems in the <span class="emphasis"><em>install</em></span> phase</a></span></dt>
74: <dd><dl>
75: <dt><span class="sect2"><a href="fixes.html#install-scripts">18.6.1. Creating needed directories</a></span></dt>
76: <dt><span class="sect2"><a href="fixes.html#where-to-install-documentation">18.6.2. Where to install documentation</a></span></dt>
77: <dt><span class="sect2"><a href="fixes.html#installing-score-files">18.6.3. Installing highscore files</a></span></dt>
78: <dt><span class="sect2"><a href="fixes.html#hardcoded-paths">18.6.4. Packages with hardcoded paths to other interpreters</a></span></dt>
79: <dt><span class="sect2"><a href="fixes.html#perl-modules">18.6.5. Packages installing perl modules</a></span></dt>
80: <dt><span class="sect2"><a href="fixes.html#faq.info-files">18.6.6. Packages installing info files</a></span></dt>
81: <dt><span class="sect2"><a href="fixes.html#manpages">18.6.7. Packages installing man pages</a></span></dt>
82: <dt><span class="sect2"><a href="fixes.html#gconf2-data-files">18.6.8. Packages installing GConf2 data files</a></span></dt>
83: <dt><span class="sect2"><a href="fixes.html#scrollkeeper-data-files">18.6.9. Packages installing scrollkeeper data files</a></span></dt>
84: <dt><span class="sect2"><a href="fixes.html#x11-fonts">18.6.10. Packages installing X11 fonts</a></span></dt>
85: <dt><span class="sect2"><a href="fixes.html#gtk2-modules">18.6.11. Packages installing GTK2 modules</a></span></dt>
86: <dt><span class="sect2"><a href="fixes.html#sgml-xml-data">18.6.12. Packages installing SGML or XML data</a></span></dt>
87: <dt><span class="sect2"><a href="fixes.html#mime-database">18.6.13. Packages installing extensions to the MIME database</a></span></dt>
88: <dt><span class="sect2"><a href="fixes.html#intltool">18.6.14. Packages using intltool</a></span></dt>
89: <dt><span class="sect2"><a href="fixes.html#startup-scripts">18.6.15. Packages installing startup scripts</a></span></dt>
90: <dt><span class="sect2"><a href="fixes.html#tex-packages">18.6.16. Packages installing TeX modules</a></span></dt>
91: <dt><span class="sect2"><a href="fixes.html#emulation-packages">18.6.17. Packages supporting running binaries in
92: emulation</a></span></dt>
93: <dt><span class="sect2"><a href="fixes.html#hicolor-theme">18.6.18. Packages installing hicolor theme icons</a></span></dt>
94: <dt><span class="sect2"><a href="fixes.html#desktop-files">18.6.19. Packages installing desktop files</a></span></dt>
95: </dl></dd>
96: <dt><span class="sect1"><a href="fixes.html#punting">18.7. Marking packages as having problems</a></span></dt>
97: </dl>
98: </div>
99: <div class="sect1" lang="en">
100: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
101: <a name="general-operation"></a>18.1. General operation</h2></div></div></div>
102: <div class="sect2" lang="en">
103: <div class="titlepage"><div><div><h3 class="title">
104: <a name="portability-of-packages"></a>18.1.1. Portability of packages</h3></div></div></div>
105: <p>One appealing feature of pkgsrc is that it runs on many
106: different platforms. As a result, it is important to ensure,
107: where possible, that packages in pkgsrc are portable. This
108: chapter mentions some particular details you should pay
109: attention to while working on pkgsrc.</p>
110: </div>
111: <div class="sect2" lang="en">
112: <div class="titlepage"><div><div><h3 class="title">
113: <a name="pulling-vars-from-etc-mk.conf"></a>18.1.2. How to pull in user-settable variables from <code class="filename">mk.conf</code>
114: </h3></div></div></div>
115: <p>The pkgsrc user can configure pkgsrc by overriding several
116: variables in the file pointed to by <code class="varname">MAKECONF</code>,
117: which is <code class="filename">/etc/mk.conf</code> by default. When you
118: want to use those variables in the preprocessor directives of
119: <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> (for example <code class="literal">.if</code> or
120: <code class="literal">.for</code>), you need to include the file
121: <code class="filename">../../mk/bsd.prefs.mk</code> before, which in turn
122: loads the user preferences.</p>
123: <p>But note that some variables may not be completely defined
124: after <code class="filename">../../mk/bsd.prefs.mk</code> has been
125: included, as they may contain references to variables that are
126: not yet defined. In shell commands this is no problem, since
127: variables are actually macros, which are only expanded when they
128: are used. But in the preprocessor directives mentioned above and
129: in dependency lines (of the form <code class="literal">target:
130: dependencies</code>) the variables are expanded at load
131: time.</p>
132: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
133: <h3 class="title">Note</h3>
134: <p>Currently there is no exhaustive list of all
135: variables that tells you whether they can be used at load time
136: or only at run time, but it is in preparation.</p>
137: </div>
138: </div>
139: <div class="sect2" lang="en">
140: <div class="titlepage"><div><div><h3 class="title">
141: <a name="user-interaction"></a>18.1.3. User interaction</h3></div></div></div>
142: <p>Occasionally, packages require interaction from the user,
143: and this can be in a number of ways:</p>
144: <div class="itemizedlist"><ul type="disc">
145: <li><p>When fetching the distfiles, some packages require user
146: interaction such as entering username/password or accepting a
147: license on a web page.</p></li>
148: <li><p>When extracting the distfiles, some packages may ask for
149: passwords.</p></li>
150: <li><p>help to configure the package before it is built</p></li>
151: <li><p>help during the build process</p></li>
152: <li><p>help during the installation of a package</p></li>
153: </ul></div>
154: <p>The <code class="varname">INTERACTIVE_STAGE</code> definition is
155: provided to notify the pkgsrc mechanism of an interactive stage
156: which will be needed, and this should be set in the package's
157: <code class="filename">Makefile</code>, e.g.:</p>
158: <pre class="programlisting">
159: INTERACTIVE_STAGE= build
160: </pre>
161: <p>Multiple interactive stages can be specified:</p>
162: <pre class="programlisting">
163: INTERACTIVE_STAGE= configure install
164: </pre>
165: <p>The user can then decide to skip this package by setting the
166: <code class="varname">BATCH</code> variable.</p>
167: </div>
168: <div class="sect2" lang="en">
169: <div class="titlepage"><div><div><h3 class="title">
170: <a name="handling-licenses"></a>18.1.4. Handling licenses</h3></div></div></div>
171: <p>Authors of software can choose the licence under which
172: software can be copied. This is due to copyright law, and reasons
173: for license choices are outside the scope of pkgsrc. The pkgsrc
174: system recognizes that there are a number of licenses which some
175: users may find objectionable or difficult or impossible to comply
176: with. The Free Software Foundation has declared some licenses
177: "Free", and the Open Source Initiative has a definition of "Open
178: Source". The pkgsrc system, as a policy choice, does not label
179: packages which have licenses that are Free or Open Source.
180: However, packages without a license meeting either of those tests
181: are labeled with a license tag denoting the license. Note that a
182: package with no license to copy trivially does not meet either the
183: Free or Open Source test.</p>
184: <p>For packages which are not Free or Open Source, pkgsrc will
185: not build the package unless the user has indicated to pkgsrc that
186: packages with that particular license may be built. Note that
187: this documentation avoids the term "accepted the license". The
188: pkgsrc system is merely providing a mechanism to avoid
189: accidentally building a package with a non-free license;
190: judgement and responsibility remain with the user. (Installation
191: of binary packages are not currently subject to this mechanism;
192: this is a bug.)</p>
193: <p>One might want to only install packages with a BSD license,
194: or the GPL, and not the other. The pkgsrc license tag mechanism
195: does not provide a way to do this. It might be possible to put in
196: tags for free licenses, and have a default
197: <code class="varname">ACCEPTABLE_LICENSES</code> variable value, but this is
198: widely viewed as having a very poor ratio of benefit to
199: work.</p>
200: <p>The license tag mechanism is intended to address
201: copyright-related issues surrounding building, installing and
202: using a package, and not to address redistribution issues (see
203: <code class="varname">RESTRICTED</code> and
204: <code class="varname">NO_SRC_ON_FTP</code>, etc.). However, the above
205: definition of licenses for which tags are not needed implies
206: that packages with redistribution restrictions should have
207: tags, because Free or Open Source programs do not have
208: redistribution restrictions.</p>
209: <p>Denoting that a package may be copied according to a
210: particular license is done by placing the license in
211: <code class="filename">pkgsrc/licenses</code> and setting the
212: <code class="varname">LICENSE</code> variable to a string identifying the
213: license, e.g. in <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/graphics/xv/README.html" target="_top"><code class="filename">graphics/xv</code></a>:</p>
214: <pre class="programlisting">
215: LICENSE= xv-license
216: </pre>
217: <p>When trying to build, the user will get a notice that the
218: package is covered by a license which has not been placed in the
219: <code class="varname">ACCEPTABLE_LICENSES</code> variable:</p>
220: <pre class="programlisting">
221: <code class="prompt">%</code> <strong class="userinput"><code>make</code></strong>
222: ===> xv-3.10anb9 has an unacceptable license: xv-license.
223: ===> To view the license, enter "/usr/bin/make show-license".
224: ===> To indicate acceptance, add this line to your /etc/mk.conf:
225: ===> ACCEPTABLE_LICENSES+=xv-license
226: *** Error code 1
227: </pre>
228: <p>The license can be viewed with <span><strong class="command">make
229: show-license</strong></span>, and if the user so chooses, the line
230: printed above can be added to <code class="filename">/etc/mk.conf</code> to
231: convey to pkgsrc that it should not in the future fail because of
232: that license:</p>
233: <pre class="programlisting">
234: ACCEPTABLE_LICENSES+=xv-license
235: </pre>
236: <p>When adding a package with a new license, the license text
237: should be added to <code class="filename">pkgsrc/licenses</code> for
238: displaying. A list of known licenses can be seen in this
239: directory.</p>
240: <p>When the license changes (in a way other than formatting),
241: please make sure that the new license has a different name (e.g.,
242: append the version number if it exists, or the date). Just
243: because a user told pkgsrc to build programs under a previous
244: version of a license does not mean that pkgsrc should build
245: programs under the new licenses. The higher-level point is that
246: pkgsrc does not evaluate licenses for reasonableness; the only
247: test is a mechanistic test of whether a particular text has been
248: approved by either of two bodies.</p>
249: <p>The use of <code class="varname">LICENSE=shareware</code>,
250: <code class="varname">LICENSE=no-commercial-use</code>, and similar language
251: is deprecated because it does not crisply refer to a particular
252: license text. Another problem with such usage is that it does not
253: enable a user to tell pkgsrc to proceed for a single package
254: without also telling pkgsrc to proceed for all packages with that
255: tag.</p>
256: </div>
257: <div class="sect2" lang="en">
258: <div class="titlepage"><div><div><h3 class="title">
259: <a name="restricted-packages"></a>18.1.5. Restricted packages</h3></div></div></div>
260: <p>Some licenses restrict how software may be re-distributed.
261: Because a license tag is required unless the package is Free or
262: Open Source, all packages with restrictions should have license
263: tags. By declaring the restrictions, package tools can
264: automatically refrain from e.g. placing binary packages on FTP
265: sites.</p>
266: <p>There are four restrictions that may be encoded, which are
267: the cross product of sources (distfiles) and binaries not being
268: placed on FTP sites and CD-ROMs. Because this is rarely the exact
269: language in any license, and because non-Free licenses tend to be
270: different from each other, pkgsrc adopts a definition of FTP and
271: CD-ROM. Pkgsrc uses "FTP" to mean that the source or binary file
272: should not be made available over the Internet at no charge.
273: Pkgsrc uses "CD-ROM" to mean that the source or binary may not be
274: made available on some kind of media, together with other source
275: and binary packages, and which is sold for a distribution charge.
276: </p>
277: <p>In order to encode these restrictions, the package system
278: defines five make variables that can be set to note these
279: restrictions:</p>
280: <div class="itemizedlist"><ul type="disc">
281: <li>
282: <p><code class="varname">RESTRICTED</code></p>
283: <p>This variable should be set whenever a restriction
284: exists (regardless of its kind). Set this variable to a
285: string containing the reason for the restriction. It should
286: be understood that those wanting to understand the restriction
287: will have to read the license, and perhaps seek advice of
288: counsel.</p>
289: </li>
290: <li>
291: <p><code class="varname">NO_BIN_ON_CDROM</code></p>
292: <p>Binaries may not be placed on CD-ROM containing other
293: binary packages, for which a distribution charge may be made.
294: In this case, set this variable to
295: <code class="varname">${RESTRICTED}</code>.</p>
296: </li>
297: <li>
298: <p><code class="varname">NO_BIN_ON_FTP</code></p>
299: <p>Binaries may not made available on the Internet without
300: charge. In this case, set this variable to
301: <code class="varname">${RESTRICTED}</code>. If this variable is set,
302: binary packages will not be included on ftp.NetBSD.org.</p>
303: </li>
304: <li>
305: <p><code class="varname">NO_SRC_ON_CDROM</code></p>
306: <p>Distfiles may not be placed on CD-ROM, together with
307: other distfiles, for which a fee may be charged. In this
308: case, set this variable to <code class="varname">${RESTRICTED}</code>.
309: </p>
310: </li>
311: <li>
312: <p><code class="varname">NO_SRC_ON_FTP</code></p>
313: <p>Distfiles may not made available via FTP at no charge.
314: In this case, set this variable to
315: <code class="varname">${RESTRICTED}</code>. If this variable is set,
316: the distfile(s) will not be mirrored on ftp.NetBSD.org.</p>
317: </li>
318: </ul></div>
319: <p>Please note that the use of <code class="varname">NO_PACKAGE</code>,
320: <code class="varname">IGNORE</code>, <code class="varname">NO_CDROM</code>, or other
321: generic make variables to denote restrictions is deprecated,
322: because they unconditionally prevent users from generating
323: binary packages!</p>
324: </div>
325: <div class="sect2" lang="en">
326: <div class="titlepage"><div><div><h3 class="title">
327: <a name="dependencies"></a>18.1.6. Handling dependencies</h3></div></div></div>
328: <p>Your package may depend on some other package being present
329: - and there are various ways of expressing this dependency.
330: pkgsrc supports the <code class="varname">BUILD_DEPENDS</code> and
331: <code class="varname">DEPENDS</code> definitions, the
332: <code class="varname">USE_TOOLS</code> definition, as well as dependencies
333: via <code class="filename">buildlink3.mk</code>, which is the preferred way
334: to handle dependencies, and which uses the variables named above.
335: See <a href="buildlink.html" title="Chapter 13. Buildlink methodology">Chapter 13, <i>Buildlink methodology</i></a> for more information.</p>
336: <p>The basic difference between the two variables is as
337: follows: The <code class="varname">DEPENDS</code> definition registers
338: that pre-requisite in the binary package so it will be pulled in
339: when the binary package is later installed, whilst the
340: <code class="varname">BUILD_DEPENDS</code> definition does not, marking a
341: dependency that is only needed for building the package.</p>
342: <p>This means that if you only need a package present whilst
343: you are building, it should be noted as a
344: <code class="varname">BUILD_DEPENDS</code>.</p>
345: <p>The format for a <code class="varname">BUILD_DEPENDS</code> and a
346: <code class="varname">DEPENDS</code> definition is:</p>
347: <pre class="programlisting">
348: <pre-req-package-name>:../../<category>/<pre-req-package>
349: </pre>
350: <p>Please note that the “<span class="quote">pre-req-package-name</span>”
351: may include any of the wildcard version numbers recognized by
352: <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>.</p>
353: <div class="orderedlist"><ol type="1">
354: <li>
355: <p>If your package needs another package's binaries or
356: libraries to build or run, and if that package has a
357: <code class="filename">buildlink3.mk</code> file available, use it:</p>
358: <pre class="programlisting">
359: .include "../../graphics/jpeg/buildlink3.mk"
360: </pre>
361: </li>
362: <li>
363: <p>If your package needs to use another package to build
364: itself and there is no <code class="filename">buildlink3.mk</code>
365: file available, use the <code class="varname">BUILD_DEPENDS</code>
366: definition:</p>
367: <pre class="programlisting">
368: BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
369: </pre>
370: </li>
371: <li>
372: <p>If your package needs a library with which to link and
373: again there is no <code class="filename">buildlink3.mk</code> file
374: available, this is specified using the
375: <code class="varname">DEPENDS</code> definition. For example:</p>
376: <pre class="programlisting">
377: DEPENDS+= xpm-3.4j:../../graphics/xpm
378: </pre>
379: <p>You can also use wildcards in package dependences:</p>
380: <pre class="programlisting">
381: DEPENDS+= xpm-[0-9]*:../../graphics/xpm
382: </pre>
383: <p>Note that such wildcard dependencies are retained when
384: creating binary packages. The dependency is checked when
385: installing the binary package and any package which matches
386: the pattern will be used. Wildcard dependencies should be
387: used with care.</p>
388: <p>The “<span class="quote">-[0-9]*</span>” should be used instead of
389: “<span class="quote">-*</span>” to avoid potentially ambiguous matches
390: such as “<span class="quote">tk-postgresql</span>” matching a
391: “<span class="quote">tk-*</span>” <code class="varname">DEPENDS</code>.</p>
392: <p>Wildcards can also be used to specify that a package
393: will only build against a certain minimum version of a
394: pre-requisite:</p>
395: <pre class="programlisting">
396: DEPENDS+= tiff>=3.5.4:../../graphics/tiff
397: </pre>
398: <p>This means that the package will build against version
399: 3.5.4 of the tiff library or newer. Such a dependency may
400: be warranted if, for example, the API of the library has
401: changed with version 3.5.4 and a package would not compile
402: against an earlier version of tiff.</p>
403: <p>Please note that such dependencies should only be
404: updated if a package requires a newer pre-requisite, but
405: not to denote recommendations such as
406: ABI changes that do not prevent a package from building
407: correctly. Such recommendations can be expressed using
408: <code class="varname">ABI_DEPENDS</code>:</p>
409: <pre class="programlisting">
410: ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff
411: </pre>
412: <p>In addition to the above <code class="varname">DEPENDS</code>
413: line, this denotes that while a package will build against
414: tiff>=3.5.4, at least version 3.6.1 is recommended.
415: <code class="varname">ABI_DEPENDS</code> entries will be turned into
416: dependencies unless explicitly ignored (in which case a
417: warning will be printed).</p>
418: <p>To ignore these ABI dependency recommendations and just
419: use the required <code class="varname">DEPENDS</code>, set
420: <code class="varname">USE_ABI_DEPENDS=NO</code>. This may make
421: it easier and faster to update packages built using pkgsrc,
422: since older compatible dependencies can continue to be
423: used. This is useful for people who watch their rebuilds
424: very carefully; it is not very good as a general-purpose
425: hammer. If you use it, you need to be mindful of possible
426: ABI changes, including those from the underlying OS.</p>
427: <p>Packages that are built with recommendations ignored
428: may not be uploaded to ftp.NetBSD.org by developers and
429: should not be used across different systems that may have
430: different versions of binary packages installed.</p>
431: <p>For security fixes, please update the package
432: vulnerabilities file. See <a href="fixes.html#security-handling" title="18.1.10. Handling packages with security problems">Section 18.1.10, “Handling packages with security problems”</a> for more
433: information.</p>
434: </li>
435: <li>
436: <p>If your package needs some executable to be able to run
437: correctly and if there's no
438: <code class="filename">buildlink3.mk</code> file, this is specified
439: using the <code class="varname">DEPENDS</code> variable. The
440: <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/lyx/README.html" target="_top"><code class="filename">print/lyx</code></a> package needs to
441: be able to execute the latex binary from the teTeX package
442: when it runs, and that is specified:</p>
443: <pre class="programlisting">
444: DEPENDS+= teTeX-[0-9]*:../../print/teTeX
445: </pre>
446: <p>The comment about wildcard dependencies from previous
447: paragraph applies here, too.</p>
448: </li>
449: </ol></div>
450: <p>If your package needs files from another package to build,
451: add the relevant distribution files to
452: <code class="varname">DISTFILES</code>, so they will be extracted
453: automatically. See the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/ghostscript/README.html" target="_top"><code class="filename">print/ghostscript</code></a> package for an example.
454: (It relies on the jpeg sources being present in source form
455: during the build.)</p>
456: </div>
457: <div class="sect2" lang="en">
458: <div class="titlepage"><div><div><h3 class="title">
459: <a name="conflicts"></a>18.1.7. Handling conflicts with other packages</h3></div></div></div>
460: <p>Your package may conflict with other packages a user might
461: already have installed on his system, e.g. if your package
462: installs the same set of files as another package in the pkgsrc
463: tree.</p>
464: <p>In this case you can set <code class="varname">CONFLICTS</code> to a
465: space-separated list of packages (including version string) your
466: package conflicts with.</p>
467: <p>For example, <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/Xaw3d/README.html" target="_top"><code class="filename">x11/Xaw3d</code></a>
468: and <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/Xaw-Xpm/README.html" target="_top"><code class="filename">x11/Xaw-Xpm</code></a>
469: install the same shared library, thus you set in
470: <code class="filename">pkgsrc/x11/Xaw3d/Makefile</code>:</p>
471: <pre class="programlisting">
472: CONFLICTS= Xaw-Xpm-[0-9]*
473: </pre>
474: <p>and in <code class="filename">pkgsrc/x11/Xaw-Xpm/Makefile</code>:</p>
475: <pre class="programlisting">
476: CONFLICTS= Xaw3d-[0-9]*
477: </pre>
478: <p>Packages will automatically conflict with other packages
479: with the name prefix and a different version
480: string. “<span class="quote">Xaw3d-1.5</span>” e.g. will automatically
481: conflict with the older version “<span class="quote">Xaw3d-1.3</span>”.</p>
482: </div>
483: <div class="sect2" lang="en">
484: <div class="titlepage"><div><div><h3 class="title">
485: <a name="not-building-packages"></a>18.1.8. Packages that cannot or should not be built</h3></div></div></div>
486: <p>There are several reasons why a package might be
487: instructed to not build under certain circumstances. If the
488: package builds and runs on most platforms, the exceptions
489: should be noted with <code class="varname">NOT_FOR_PLATFORM</code>. If
490: the package builds and runs on a small handful of platforms,
491: set <code class="varname">ONLY_FOR_PLATFORM</code> instead.
492: Both <code class="varname">ONLY_FOR_PLATFORM</code> and
493: <code class="varname">NOT_FOR_PLATFORM</code> are OS triples
494: (OS-version-platform) that can use glob-style
495: wildcards.</p>
496: <p>Some packages are tightly bound to a specific version of an
497: operating system, e.g. LKMs or <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/lsof/README.html" target="_top"><code class="filename">sysutils/lsof</code></a>. Such binary packages are not
498: backwards compatible with other versions of the OS, and should be
499: uploaded to a version specific directory on the FTP server. Mark
500: these packages by setting <code class="varname">OSVERSION_SPECIFIC</code> to
501: “<span class="quote">yes</span>”. This variable is not currently used by any of
502: the package system internals, but may be used in the
503: future.</p>
504: <p>If the package should be skipped (for example, because it
505: provides functionality already provided by the system), set
506: <code class="varname">PKG_SKIP_REASON</code> to a descriptive message. If
507: the package should fail because some preconditions are not met,
508: set <code class="varname">PKG_FAIL_REASON</code> to a descriptive
509: message.</p>
510: </div>
511: <div class="sect2" lang="en">
512: <div class="titlepage"><div><div><h3 class="title">
513: <a name="undeletable-packages"></a>18.1.9. Packages which should not be deleted, once installed</h3></div></div></div>
514: <p>To ensure that a package may not be deleted, once it has been
515: installed, the <code class="varname">PKG_PRESERVE</code> definition should
516: be set in the package Makefile. This will be carried into any
517: binary package that is made from this pkgsrc entry. A
518: “<span class="quote">preserved</span>” package will
519: not be deleted using <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> unless the
520: “<span class="quote">-f</span>” option is used.</p>
521: </div>
522: <div class="sect2" lang="en">
523: <div class="titlepage"><div><div><h3 class="title">
524: <a name="security-handling"></a>18.1.10. Handling packages with security problems</h3></div></div></div>
525: <p>When a vulnerability is found, this should be noted in
526: <code class="filename">localsrc/security/advisories/pkg-vulnerabilities</code>,
527: and after committing that file, use <span><strong class="command">make upload</strong></span>
528: in the same directory to update the file on ftp.NetBSD.org.</p>
529: <p>After fixing the vulnerability by a patch, its
530: <code class="varname">PKGREVISION</code> should be increased (this
531: is of course not necessary if the problem is fixed by using
532: a newer release of the software).</p>
533: <p>Also, if the fix should be applied to the stable pkgsrc
534: branch, be sure to submit a pullup request!</p>
535: <p>Binary packages already on ftp.NetBSD.org will be handled
536: semi-automatically by a weekly cron job.</p>
537: </div>
538: <div class="sect2" lang="en">
539: <div class="titlepage"><div><div><h3 class="title">
540: <a name="bumping-pkgrevision"></a>18.1.11. How to handle incrementing versions when fixing an existing package</h3></div></div></div>
541: <p>When making fixes to an existing package it can be useful
542: to change the version number in <code class="varname">PKGNAME</code>. To
543: avoid conflicting with future versions by the original author, a
544: “<span class="quote">nb1</span>”, “<span class="quote">nb2</span>”, ... suffix can be used
545: on package versions by setting <code class="varname">PKGREVISION=1</code>
546: (2, ...). The “<span class="quote">nb</span>” is treated like a
547: “<span class="quote">.</span>” by the package tools. e.g.</p>
548: <pre class="programlisting">
549: DISTNAME= foo-17.42
550: PKGREVISION= 9
551: </pre>
552: <p>will result in a <code class="varname">PKGNAME</code> of
553: “<span class="quote">foo-17.42nb9</span>”. If you want to use the original
554: value of <code class="varname">PKGNAME</code> without the “<span class="quote">nbX</span>”
555: suffix, e.g. for setting <code class="varname">DIST_SUBDIR</code>, use
556: <code class="varname">PKGNAME_NOREV</code>.</p>
557: <p>When a new release of the package is released, the
558: <code class="varname">PKGREVISION</code> should be removed, e.g. on a new
559: minor release of the above package, things should be like:</p>
560: <pre class="programlisting">
561: DISTNAME= foo-17.43
562: </pre>
563: <p><code class="varname">PKGREVISION</code> should be incremented for any
564: non-trivial change in the resulting binary package. Without a
565: <code class="varname">PKGREVISION</code> bump, someone with the previous
566: version installed has no way of knowing that their package is out
567: of date. Thus, changes without increasing
568: <code class="varname">PKGREVISION</code> are essentially labeled "this is so
569: trivial that no reasonable person would want to upgrade", and this
570: is the rough test for when increasing
571: <code class="varname">PKGREVISION</code> is appropriate. Examples of
572: changes that do not merit increasing
573: <code class="varname">PKGREVISION</code> are:</p>
574: <div class="itemizedlist"><ul type="disc">
575: <li><p>Changing <code class="varname">HOMEPAGE</code>, <code class="varname">MAINTAINER</code>,
576: or comments in Makefile.</p></li>
577: <li><p>
578: Changing build variables if the resulting binary package is the same.</p></li>
579: <li><p>
580: Changing <code class="filename">DESCR</code>.</p></li>
581: <li><p>
582: Adding <code class="varname">PKG_OPTIONS</code> if the default options don't change.</p></li>
583: </ul></div>
584: <p>Examples of changes that do merit an increase to
585: <code class="varname">PKGREVISION</code> include:</p>
586: <div class="itemizedlist"><ul type="disc">
587: <li><p>
588: Security fixes</p></li>
589: <li><p>
590: Changes or additions to a patch file</p></li>
591: <li><p>
592: Changes to the <code class="filename">PLIST</code></p></li>
593: </ul></div>
594: <p>PKGREVISION must also be incremented when dependencies have ABI
595: changes.</p>
596: </div>
597: <div class="sect2" lang="en">
598: <div class="titlepage"><div><div><h3 class="title">
599: <a name="fixes.subst"></a>18.1.12. Substituting variable text in the package files (the SUBST framework)</h3></div></div></div>
600: <p>When you want to replace the same text in multiple files
601: or when the replacement text varies, patches alone cannot help.
602: This is where the SUBST framework comes in. It provides an
603: easy-to-use interface for replacing text in files.
604: Example:</p>
605: <pre class="programlisting">
606: SUBST_CLASSES+= fix-paths
607: SUBST_STAGE.fix-paths= pre-configure
608: SUBST_MESSAGE.fix-paths= Fixing absolute paths.
609: SUBST_FILES.fix-paths= src/*.c
610: SUBST_FILES.fix-paths+= scripts/*.sh
611: SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
612: SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
613: </pre>
614: <p><code class="varname">SUBST_CLASSES</code> is a list of identifiers
615: that are used to identify the different SUBST blocks that are
616: defined. The SUBST framework is heavily used by pkgsrc, so it is
617: important to always use the <code class="literal">+=</code> operator with
618: this variable. Otherwise some substitutions may be
619: skipped.</p>
620: <p>The remaining variables of each SUBST block are
621: parameterized with the identifier from the first line
622: (<code class="literal">fix-paths</code> in this case.) They can be seen as
623: parameters to a function call.</p>
624: <p><code class="varname">SUBST_STAGE.*</code> specifies the stage at
625: which the replacement will take place. All combinations of
626: <code class="literal">pre-</code>, <code class="literal">do-</code> and
627: <code class="literal">post-</code> together with a phase name are
628: possible, though only few are actually used. Most commonly used
629: are <code class="literal">post-patch</code> and
630: <code class="literal">pre-configure</code>. Of these two,
631: <code class="literal">pre-configure</code> should be preferred because
632: then it is possible to run <span><strong class="command">bmake patch</strong></span> and
633: have the state after applying the patches but before making any
634: other changes. This is especially useful when you are debugging
635: a package in order to create new patches for it. Similarly,
636: <code class="literal">post-build</code> is preferred over
637: <code class="literal">pre-install</code>, because the install phase should
638: generally be kept as simple as possible. When you use
639: <code class="literal">post-build</code>, you have the same files in the
640: working directory that will be installed later, so you can check
641: if the substitution has succeeded.</p>
642: <p><code class="varname">SUBST_MESSAGE.*</code> is an optional text
643: that is printed just before the substitution is done.</p>
644: <p><code class="varname">SUBST_FILES.*</code> is the list of shell
645: globbing patterns that specifies the files in which the
646: substitution will take place. The patterns are interpreted
647: relatively to the <code class="varname">WRKSRC</code> directory.</p>
648: <p><code class="varname">SUBST_SED.*</code> is a list of arguments to
649: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?sed+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> that specify the actual substitution. Every sed
650: command should be prefixed with <code class="literal">-e</code>, so that
651: all SUBST blocks look uniform.</p>
652: <p>There are some more variables, but they are so seldomly
653: used that they are only documented in the
654: <code class="filename">mk/subst.mk</code> file.</p>
655: </div>
656: </div>
657: <div class="sect1" lang="en">
658: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
659: <a name="fixes.fetch"></a>18.2. Fixing problems in the <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
660: <div class="sect2" lang="en">
661: <div class="titlepage"><div><div><h3 class="title">
662: <a name="no-plain-download"></a>18.2.1. Packages whose distfiles aren't available for plain downloading</h3></div></div></div>
663: <p>If you need to download from a dynamic URL you can set
664: <code class="varname">DYNAMIC_MASTER_SITES</code> and a <span><strong class="command">make
665: fetch</strong></span> will call <code class="filename">files/getsite.sh</code>
666: with the name of each file to download as an argument, expecting
667: it to output the URL of the directory from which to download
668: it. <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/graphics/ns-cult3d/README.html" target="_top"><code class="filename">graphics/ns-cult3d</code></a> is an
669: example of this usage.</p>
670: <p>If the download can't be automated, because the user must
671: submit personal information to apply for a password, or must pay
672: for the source, or whatever, you can set
673: <code class="varname">FETCH_MESSAGE</code> to a list of lines that are
674: displayed to the user before aborting the build. Example:</p>
675: <pre class="programlisting">
676: FETCH_MESSAGE= "Please download the files"
677: FETCH_MESSAGE+= " "${DISTFILES:Q}
678: FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
679: </pre>
680: </div>
681: <div class="sect2" lang="en">
682: <div class="titlepage"><div><div><h3 class="title">
683: <a name="modified-distfiles-same-name"></a>18.2.2. How to handle modified distfiles with the 'old' name</h3></div></div></div>
684: <p>Sometimes authors of a software package make some
685: modifications after the software was released, and they put up a
686: new distfile without changing the package's version number. If a
687: package is already in pkgsrc at that time, the checksum will
688: no longer match. The contents of the new distfile should be
689: compared against the old one before changing anything, to make
690: sure the distfile was really updated on purpose, and that
691: no trojan horse or so crept in.
692: Please mention that the distfiles were compared and what was found
693: in your commit message.
694: Then, the correct way to work around this is to
695: set <code class="varname">DIST_SUBDIR</code> to a unique directory name,
696: usually based on <code class="varname">PKGNAME_NOREV</code>. All
697: <code class="varname">DISTFILES</code> and
698: <code class="varname">PATCHFILES</code> for this package will be put in that
699: subdirectory of the local distfiles directory.
700: (See <a href="fixes.html#bumping-pkgrevision" title="18.1.11. How to handle incrementing versions when fixing an existing package">Section 18.1.11, “How to handle incrementing versions when fixing an existing package”</a> for more details.)
701: In case this
702: happens more often, <code class="varname">PKGNAME</code> can be used (thus
703: including the <code class="filename">nbX</code> suffix) or a date stamp
704: can be appended, like <code class="varname">${PKGNAME_NOREV}-YYYYMMDD</code>.
705: Do not forget regenerating the <code class="filename">distinfo</code> file
706: after that, since it contains the <code class="varname">DIST_SUBDIR</code>
707: path in the filenames.
708: Also increase the PKGREVISION if the installed package is different.
709: Furthermore, a mail to the package's authors seems appropriate
710: telling them that changing distfiles after releases without
711: changing the file names is not good practice.</p>
712: </div>
713: </div>
714: <div class="sect1" lang="en">
715: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
716: <a name="fixes.configure"></a>18.3. Fixing problems in the <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
717: <div class="sect2" lang="en">
718: <div class="titlepage"><div><div><h3 class="title">
719: <a name="fixes.libtool"></a>18.3.1. Shared libraries - libtool</h3></div></div></div>
720: <p>pkgsrc supports many different machines, with different
721: object formats like a.out and ELF, and varying abilities to do
722: shared library and dynamic loading at all. To accompany this,
723: varying commands and options have to be passed to the
724: compiler, linker, etc. to get the Right Thing, which can be
725: pretty annoying especially if you don't have all the machines
726: at your hand to test things. The
727: <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/libtool/README.html" target="_top"><code class="filename">devel/libtool</code></a> pkg
728: can help here, as it just “<span class="quote">knows</span>” how to build
729: both static and dynamic libraries from a set of source files,
730: thus being platform-independent.</p>
731: <p>Here's how to use libtool in a package in seven simple
732: steps:</p>
733: <div class="orderedlist"><ol type="1">
734: <li><p>Add <code class="varname">USE_LIBTOOL=yes</code> to the package
735: Makefile.</p></li>
736: <li><p>For library objects, use “<span class="quote">${LIBTOOL} --mode=compile
737: ${CC}</span>” in place of “<span class="quote">${CC}</span>”. You could even
738: add it to the definition of <code class="varname">CC</code>, if only
739: libraries are being built in a given Makefile. This one command
740: will build both PIC and non-PIC library objects, so you need not
741: have separate shared and non-shared library rules.</p></li>
742: <li>
743: <p>For the linking of the library, remove any
744: “<span class="quote">ar</span>”, “<span class="quote">ranlib</span>”, and “<span class="quote">ld
745: -Bshareable</span>” commands, and instead use:</p>
746: <pre class="programlisting">
747: ${LIBTOOL} --mode=link \
748: ${CC} -o ${.TARGET:.a=.la} \
749: ${OBJS:.o=.lo} \
750: -rpath ${PREFIX}/lib \
751: -version-info major:minor
752: </pre>
753: <p>Note that the library is changed to have a
754: <code class="filename">.la</code> extension, and the objects are
755: changed to have a <code class="filename">.lo</code>
756: extension. Change <code class="varname">OBJS</code> as
757: necessary. This automatically creates all of the
758: <code class="filename">.a</code>,
759: <code class="filename">.so.major.minor</code>, and ELF symlinks (if
760: necessary) in the build directory. Be sure to include
761: “<span class="quote">-version-info</span>”, especially when major and
762: minor are zero, as libtool will otherwise strip off the
763: shared library version.</p>
764: <p>From the libtool manual:</p>
765: <pre class="programlisting">
766: So, libtool library versions are described by three integers:
767:
768: CURRENT
769: The most recent interface number that this library implements.
770:
771: REVISION
772: The implementation number of the CURRENT interface.
773:
774: AGE
775: The difference between the newest and oldest interfaces that
776: this library implements. In other words, the library implements
777: all the interface numbers in the range from number `CURRENT -
778: AGE' to `CURRENT'.
779:
780: If two libraries have identical CURRENT and AGE numbers, then the
781: dynamic linker chooses the library with the greater REVISION number.
782: </pre>
783: <p>The “<span class="quote">-release</span>” option will produce
784: different results for a.out and ELF (excluding symlinks)
785: in only one case. An ELF library of the form
786: “<span class="quote">libfoo-release.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”
787: will have a symlink of
788: “<span class="quote">libfoo.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”
789: on an a.out platform. This is handled
790: automatically.</p>
791: <p>The “<span class="quote">-rpath argument</span>” is the install
792: directory of the library being built.</p>
793: <p>In the <code class="filename">PLIST</code>, include only the
794: <code class="filename">.la</code> file, the other files will be
795: added automatically.</p>
796: </li>
797: <li>
798: <p>When linking shared object (<code class="filename">.so</code>)
799: files, i.e. files that are loaded via <a href="http://netbsd.gw.com/cgi-bin/man-cgi?dlopen+3+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">dlopen</span>(3)</span></a>, NOT
800: shared libraries, use “<span class="quote">-module
801: -avoid-version</span>” to prevent them getting version
802: tacked on.</p>
803: <p>The <code class="filename">PLIST</code> file gets the
804: <code class="filename">foo.so</code> entry.</p>
805: </li>
806: <li>
807: <p>When linking programs that depend on these libraries
808: <span class="emphasis"><em>before</em></span> they are installed, preface
809: the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cc+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cc</span>(1)</span></a> or <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ld</span>(1)</span></a> line with “<span class="quote">${LIBTOOL}
810: --mode=link</span>”, and it will find the correct
811: libraries (static or shared), but please be aware that
812: libtool will not allow you to specify a relative path in
813: -L (such as “<span class="quote">-L../somelib</span>”), because it
814: expects you to change that argument to be the
815: <code class="filename">.la</code> file. e.g.</p>
816: <pre class="programlisting">
817: ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
818: </pre>
819: <p>should be changed to:</p>
820: <pre class="programlisting">
821: ${LIBTOOL} --mode=link ${CC} -o <em class="replaceable"><code>someprog</code></em> <em class="replaceable"><code>../somelib/somelib.la</code></em>
822: </pre>
823: <p>and it will do the right thing with the libraries.</p>
824: </li>
825: <li>
826: <p>When installing libraries, preface the <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>
827: or <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cp+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cp</span>(1)</span></a> command with “<span class="quote">${LIBTOOL}
828: --mode=install</span>”, and change the library name to
829: <code class="filename">.la</code>. e.g.</p>
830: <pre class="programlisting">
831: ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
832: </pre>
833: <p>This will install the static <code class="filename">.a</code>,
834: shared library, any needed symlinks, and run
835: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ldconfig+8+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ldconfig</span>(8)</span></a>.</p>
836: </li>
837: <li><p>In your <code class="filename">PLIST</code>, include only
838: the <code class="filename">.la</code>
839: file (this is a change from previous behaviour).</p></li>
840: </ol></div>
841: </div>
842: <div class="sect2" lang="en">
843: <div class="titlepage"><div><div><h3 class="title">
844: <a name="using-libtool"></a>18.3.2. Using libtool on GNU packages that already support libtool</h3></div></div></div>
845: <p>Add <code class="varname">USE_LIBTOOL=yes</code> to the
846: package Makefile. This will override the package's own libtool
847: in most cases. For older libtool using packages, libtool is
848: made by ltconfig script during the do-configure step; you can
849: check the libtool script location by doing <span><strong class="command">make
850: configure; find work*/ -name libtool</strong></span>.</p>
851: <p><code class="varname">LIBTOOL_OVERRIDE</code> specifies which libtool
852: scripts, relative to <code class="varname">WRKSRC</code>, to override. By
853: default, it is set to “<span class="quote">libtool */libtool
854: */*/libtool</span>”. If this does not match the location of the
855: package's libtool script(s), set it as appropriate.</p>
856: <p>If you do not need <code class="filename">*.a</code> static
857: libraries built and installed, then use
858: <code class="varname">SHLIBTOOL_OVERRIDE</code> instead.</p>
859: <p>If your package makes use of the platform-independent library
860: for loading dynamic shared objects, that comes with libtool
861: (libltdl), you should include devel/libltdl/buildlink3.mk.</p>
862: <p>Some packages use libtool incorrectly so that the package
863: may not work or build in some circumstances. Some of the more
864: common errors are:</p>
865: <div class="itemizedlist"><ul type="disc">
866: <li>
867: <p>The inclusion of a shared object (-module) as a dependent library in an
868: executable or library. This in itself isn't a problem if one of two things
869: has been done:</p>
870: <div class="orderedlist"><ol type="1">
871: <li><p>The shared object is named correctly, i.e.
872: <code class="filename">libfoo.la</code>, not
873: <code class="filename">foo.la</code></p></li>
874: <li><p>The -dlopen option is used when linking an executable.</p></li>
875: </ol></div>
876: </li>
877: <li><p>The use of libltdl without the correct calls to initialisation routines.
878: The function lt_dlinit() should be called and the macro
879: <code class="varname">LTDL_SET_PRELOADED_SYMBOLS</code> included in
880: executables.</p></li>
881: </ul></div>
882: </div>
883: <div class="sect2" lang="en">
884: <div class="titlepage"><div><div><h3 class="title">
885: <a name="autoconf-automake"></a>18.3.3. GNU Autoconf/Automake</h3></div></div></div>
886: <p>If a package needs GNU autoconf or automake to be executed
887: to regenerate the configure script and Makefile.in makefile
888: templates, then they should be executed in a pre-configure
889: target.</p>
890: <p>For packages that need only autoconf:</p>
891: <pre class="programlisting">
892: AUTOCONF_REQD= 2.50 # if default version is not good enough
893: USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
894: ...
895:
896: pre-configure:
897: cd ${WRKSRC} && autoconf
898:
899: ...
900: </pre>
901: <p>and for packages that need automake and autoconf:</p>
902: <pre class="programlisting">
903: AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
904: USE_TOOLS+= automake # use "automake14" for automake-1.4
905: ...
906:
907: pre-configure:
908: set -e; cd ${WRKSRC}; \
909: aclocal; autoheader; automake -a --foreign -i; autoconf
910:
911: ...
912: </pre>
913: <p>Packages which use GNU Automake will almost certainly
914: require GNU Make.</p>
915: <p>There are times when the configure process makes
916: additional changes to the generated files, which then causes
917: the build process to try to re-execute the automake sequence.
918: This is prevented by touching various files in the configure
919: stage. If this causes problems with your package you can set
920: <code class="varname">AUTOMAKE_OVERRIDE=NO</code> in the package
921: Makefile.</p>
922: </div>
923: </div>
924: <div class="sect1" lang="en">
925: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
926: <a name="programming-languages"></a>18.4. Programming languages</h2></div></div></div>
927: <div class="sect2" lang="en">
928: <div class="titlepage"><div><div><h3 class="title">
929: <a name="basic-programming-languages"></a>18.4.1. C, C++, and Fortran</h3></div></div></div>
930: <p>Compilers for the C, C++, and Fortran languages comes with
931: the NetBSD base system. By default, pkgsrc assumes that a package
932: is written in C and will hide all other compilers (via the wrapper
933: framework, see <a href="buildlink.html" title="Chapter 13. Buildlink methodology">Chapter 13, <i>Buildlink methodology</i></a>).</p>
934: <p>To declare which language's compiler a package needs, set
935: the <code class="varname">USE_LANGUAGES</code> variable. Allowed values
936: currently are “<span class="quote">c</span>”, “<span class="quote">c++</span>”, and
937: “<span class="quote">fortran</span>” (and any combination). The default is
938: “<span class="quote">c</span>”. Packages using GNU configure scripts, even if
939: written in C++, usually need a C compiler for the configure
940: phase.</p>
941: </div>
942: <div class="sect2" lang="en">
943: <div class="titlepage"><div><div><h3 class="title">
944: <a name="java-programming-language"></a>18.4.2. Java</h3></div></div></div>
945: <p>If a program is written in Java, use the Java framework in
946: pkgsrc. The package must include
947: <code class="filename">../../mk/java-vm.mk</code>. This Makefile fragment
948: provides the following variables:</p>
949: <div class="itemizedlist"><ul type="disc">
950: <li><p><code class="varname">USE_JAVA</code> defines if a build
951: dependency on the JDK is added. If
952: <code class="varname">USE_JAVA</code> is set to “<span class="quote">run</span>”, then
953: there is only a runtime dependency on the JDK. The default is
954: “<span class="quote">yes</span>”, which also adds a build dependency on the
955: JDK.</p></li>
956: <li><p>Set <code class="varname">USE_JAVA2</code> to declare that
957: a package needs a Java2 implementation. The supported values
958: are “<span class="quote">yes</span>”, “<span class="quote">1.4</span>”, and
959: “<span class="quote">1.5</span>”. “<span class="quote">yes</span>” accepts any Java2
960: implementation, “<span class="quote">1.4</span>” insists on versions 1.4 or
961: above, and “<span class="quote">1.5</span>” only accepts versions 1.5 or
962: above. This variable is not set by default.</p></li>
963: </ul></div>
964: </div>
965: <div class="sect2" lang="en">
966: <div class="titlepage"><div><div><h3 class="title">
967: <a name="perl-scripts"></a>18.4.3. Packages containing perl scripts</h3></div></div></div>
968: <p>If your package contains interpreted perl scripts, add
969: “<span class="quote">perl</span>” to the <code class="varname">USE_TOOLS</code> variable
970: and set <code class="varname">REPLACE_PERL</code> to ensure that the proper
971: interpreter path is set. <code class="varname">REPLACE_PERL</code> should
972: contain a list of scripts, relative to <code class="varname">WRKSRC</code>,
973: that you want adjusted. Every occurrence of
974: <code class="filename">*/bin/perl</code> will be replaced with the full
975: path to the perl executable.</p>
976: <p>If a particular version of perl is needed, set the
977: <code class="varname">PERL5_REQD</code> variable to the version number. The
978: default is “<span class="quote">5.0</span>”.</p>
979: <p>See <a href="fixes.html#perl-modules" title="18.6.5. Packages installing perl modules">Section 18.6.5, “Packages installing perl modules”</a> for information
980: about handling perl modules.</p>
981: </div>
982: <div class="sect2" lang="en">
983: <div class="titlepage"><div><div><h3 class="title">
984: <a name="other-programming-languages"></a>18.4.4. Other programming languages</h3></div></div></div>
985: <p>Currently, there is no special handling for other languages
986: in pkgsrc. If a compiler package provides a
987: <code class="filename">buildlink3.mk</code> file, include that, otherwise
988: just add a (build) dependency on the appropriate compiler
989: package.</p>
990: </div>
991: </div>
992: <div class="sect1" lang="en">
993: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
994: <a name="fixes.build"></a>18.5. Fixing problems in the <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
995: <p>The most common failures when building a package are that
996: some platforms do not provide certain header files, functions or
997: libraries, or they provide the functions in a library that the
998: original package author didn't know. To work around this, you
999: can rewrite the source code in most cases so that it does not
1000: use the missing functions or provides a replacement function.</p>
1001: <div class="sect2" lang="en">
1002: <div class="titlepage"><div><div><h3 class="title">
1003: <a name="fixes.build.cpp"></a>18.5.1. Compiling C and C++ code conditionally</h3></div></div></div>
1004: <p>If a package already comes with a GNU configure script, the
1005: preferred way to fix the build failure is to change the
1006: configure script, not the code. In the other cases, you can
1007: utilize the C preprocessor, which defines certain macros
1008: depending on the operating system and hardware architecture it
1009: compiles for. These macros can be queried using for example
1010: <code class="varname">#if defined(__i386)</code>. Almost every operating
1011: system, hardware architecture and compiler has its own macro.
1012: For example, if the macros <code class="varname">__GNUC__</code>,
1013: <code class="varname">__i386__</code> and <code class="varname">__NetBSD__</code>
1014: are all defined, you know that you are using NetBSD on an i386
1015: compatible CPU, and your compiler is GCC.</p>
1016: <p>The list of the following macros for hardware and
1017: operating system depends on the compiler that is used. For
1018: example, if you want to conditionally compile code on Solaris,
1019: don't use <code class="varname">__sun__</code>, as the SunPro compiler
1020: does not define it. Use <code class="varname">__sun</code> instead.</p>
1021: <div class="sect3" lang="en">
1022: <div class="titlepage"><div><div><h4 class="title">
1023: <a name="fixes.build.cpp.os"></a>18.5.1.1. C preprocessor macros to identify the operating system</h4></div></div></div>
1024: <p>To distinguish between 4.4 BSD-derived systems and the
1025: rest of the world, you should use the following code.</p>
1026: <pre class="programlisting">
1027: #include <sys/param.h>
1028: #if (defined(BSD) && BSD >= 199306)
1029: /* BSD-specific code goes here */
1030: #else
1031: /* non-BSD-specific code goes here */
1032: #endif
1033: </pre>
1034: <p>If this distinction is not fine enough, you can also test
1035: for the following macros.</p>
1036: <pre class="programlisting">
1037: FreeBSD __FreeBSD__
1038: DragonFly __DragonFly__
1039: Interix __INTERIX
1040: IRIX __sgi (TODO: get a definite source for this)
1041: Linux linux, __linux, __linux__
1042: NetBSD __NetBSD__
1043: OpenBSD __OpenBSD__
1044: Solaris sun, __sun
1045: </pre>
1046: </div>
1047: <div class="sect3" lang="en">
1048: <div class="titlepage"><div><div><h4 class="title">
1049: <a name="fixes.build.cpp.arch"></a>18.5.1.2. C preprocessor macros to identify the hardware architecture</h4></div></div></div>
1050: <pre class="programlisting">
1051: i386 i386, __i386, __i386__
1052: MIPS __mips
1053: SPARC sparc, __sparc
1054: </pre>
1055: </div>
1056: <div class="sect3" lang="en">
1057: <div class="titlepage"><div><div><h4 class="title">
1058: <a name="fixes.build.cpp.compiler"></a>18.5.1.3. C preprocessor macros to identify the compiler</h4></div></div></div>
1059: <pre class="programlisting">
1060: GCC __GNUC__ (major version), __GNUC_MINOR__
1061: MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41)
1062: SunPro __SUNPRO_C (0x570 for Sun C 5.7)
1063: SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8)
1064: </pre>
1065: </div>
1066: </div>
1067: <div class="sect2" lang="en">
1068: <div class="titlepage"><div><div><h3 class="title">
1069: <a name="compiler-bugs"></a>18.5.2. How to handle compiler bugs</h3></div></div></div>
1070: <p>Some source files trigger bugs in the compiler, based on
1071: combinations of compiler version and architecture and almost
1072: always relation to optimisation being enabled. Common symptoms
1073: are gcc internal errors or never finishing compiling a
1074: file.</p>
1075: <p>Typically, a workaround involves testing the
1076: <code class="varname">MACHINE_ARCH</code> and compiler version, disabling
1077: optimisation for that combination of file,
1078: <code class="varname">MACHINE_ARCH</code> and compiler, and documenting it
1079: in <code class="filename">pkgsrc/doc/HACKS</code>. See that file for a
1080: number of examples.</p>
1081: </div>
1082: <div class="sect2" lang="en">
1083: <div class="titlepage"><div><div><h3 class="title">
1084: <a name="undefined-reference"></a>18.5.3. Undefined reference to “<span class="quote">...</span>”</h3></div></div></div>
1085: <p>This error message often means that a package did not
1086: link to a shared library it needs. The following functions are
1087: known to cause this error message over and over.</p>
1088: <div class="informaltable">
1089: <a name="undefined-reference-functions"></a><table border="1">
1090: <colgroup>
1091: <col>
1092: <col>
1093: <col>
1094: </colgroup>
1095: <thead><tr>
1096: <th>Function</th>
1097: <th>Library</th>
1098: <th>Affected platforms</th>
1099: </tr></thead>
1100: <tbody>
1101: <tr>
1102: <td>accept, bind, connect</td>
1103: <td>-lsocket</td>
1104: <td>Solaris</td>
1105: </tr>
1106: <tr>
1107: <td>crypt</td>
1108: <td>-lcrypt</td>
1109: <td>DragonFly, NetBSD</td>
1110: </tr>
1111: <tr>
1112: <td>dlopen, dlsym</td>
1113: <td>-ldl</td>
1114: <td>Linux</td>
1115: </tr>
1116: <tr>
1117: <td>gethost*</td>
1118: <td>-lnsl</td>
1119: <td>Solaris</td>
1120: </tr>
1121: <tr>
1122: <td>inet_aton</td>
1123: <td>-lresolv</td>
1124: <td>Solaris</td>
1125: </tr>
1126: <tr>
1127: <td>nanosleep, sem_*, timer_*</td>
1128: <td>-lrt</td>
1129: <td>Solaris</td>
1130: </tr>
1131: <tr>
1132: <td>openpty</td>
1133: <td>-lutil</td>
1134: <td>Linux</td>
1135: </tr>
1136: </tbody>
1137: </table>
1138: </div>
1139: <p>To fix these linker errors, it is often sufficient to say
1140: <code class="literal">LIBS.<em class="replaceable"><code>OperatingSystem</code></em>+=
1141: -l<em class="replaceable"><code>foo</code></em></code> to the package
1142: <code class="filename">Makefile</code> and then say <span><strong class="command">bmake clean;
1143: bmake</strong></span>.</p>
1144: <div class="sect3" lang="en">
1145: <div class="titlepage"><div><div><h4 class="title">
1146: <a name="undefined-reference-sunpro"></a>18.5.3.1. Special issue: The SunPro compiler</h4></div></div></div>
1147: <p>When you are using the SunPro compiler, there is another
1148: possibility. That compiler cannot handle the following code:</p>
1149: <pre class="programlisting">
1150: extern int extern_func(int);
1151:
1152: static inline int
1153: inline_func(int x)
1154: {
1155: return extern_func(x);
1156: }
1157:
1158: int main(void)
1159: {
1160: return 0;
1161: }
1162: </pre>
1163: <p>It generates the code for <code class="function">inline_func</code> even if
1164: that function is never used. This code then refers to
1165: <code class="function">extern_func</code>, which can usually not be resolved. To
1166: solve this problem you can try to tell the package to disable inlining
1167: of functions.</p>
1168: </div>
1169: </div>
1170: <div class="sect2" lang="en">
1171: <div class="titlepage"><div><div><h3 class="title">
1172: <a name="out-of-memory"></a>18.5.4. Running out of memory</h3></div></div></div>
1173: <p>Sometimes packages fail to build because the compiler runs
1174: into an operating system specific soft limit. With the
1175: <code class="varname">UNLIMIT_RESOURCES</code> variable pkgsrc can be told
1176: to unlimit the resources. Currently, the allowed values are
1177: “<span class="quote">datasize</span>” and “<span class="quote">stacksize</span>” (or both).
1178: Setting this variable is similar to running the shell builtin
1179: <span><strong class="command">ulimit</strong></span> command to raise the maximum data
1180: segment size or maximum stack size of a process, respectively, to
1181: their hard limits.</p>
1182: </div>
1183: </div>
1184: <div class="sect1" lang="en">
1185: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1186: <a name="fixes.install"></a>18.6. Fixing problems in the <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
1187: <div class="sect2" lang="en">
1188: <div class="titlepage"><div><div><h3 class="title">
1189: <a name="install-scripts"></a>18.6.1. Creating needed directories</h3></div></div></div>
1190: <p>The BSD-compatible <span><strong class="command">install</strong></span> supplied
1191: with some operating systems cannot create more than one
1192: directory at a time. As such, you should call
1193: <code class="literal">${INSTALL_*_DIR}</code> like this:</p>
1194: <pre class="programlisting">
1195: ${INSTALL_DATA_DIR} ${PREFIX}/dir1
1196: ${INSTALL_DATA_DIR} ${PREFIX}/dir2
1197: </pre>
1198: <p>You can also just append “<span class="quote"><code class="literal">dir1
1199: dir2</code></span>” to the
1200: <code class="varname">INSTALLATION_DIRS</code> variable, which will
1201: automatically do the right thing.</p>
1202: </div>
1203: <div class="sect2" lang="en">
1204: <div class="titlepage"><div><div><h3 class="title">
1205: <a name="where-to-install-documentation"></a>18.6.2. Where to install documentation</h3></div></div></div>
1206: <p>In general, documentation should be installed into
1207: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1208: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code> (the latter
1209: includes the version number of the package).</p>
1210: <p>Many modern packages using GNU autoconf allow to set the
1211: directory where HTML documentation is installed with the
1212: “<span class="quote">--with-html-dir</span>” option. Sometimes using this flag
1213: is needed because otherwise the documentation ends up in
1214: <code class="filename">${PREFIX}/share/doc/html</code> or other
1215: places.</p>
1216: <p>An exception to the above is that library API documentation
1217: generated with the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/gtk-doc/README.html" target="_top"><code class="filename">textproc/gtk-doc</code></a> tools, for use by special
1218: browsers (devhelp) should be left at their default location, which
1219: is <code class="filename">${PREFIX}/share/gtk-doc</code>. Such
1220: documentation can be recognized from files ending in
1221: <code class="filename">.devhelp</code> or <code class="filename">.devhelp2</code>.
1222: (It is also acceptable to install such files in
1223: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1224: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code>; the
1225: <code class="filename">.devhelp*</code> file must be directly in that
1226: directory then, no additional subdirectory level is allowed in
1227: this case. This is usually achieved by using
1228: “<span class="quote">--with-html-dir=${PREFIX}/share/doc</span>”.
1229: <code class="filename">${PREFIX}/share/gtk-doc</code> is preferred
1230: though.)</p>
1231: </div>
1232: <div class="sect2" lang="en">
1233: <div class="titlepage"><div><div><h3 class="title">
1234: <a name="installing-score-files"></a>18.6.3. Installing highscore files</h3></div></div></div>
1235: <p>Certain packages, most of them in the games category, install
1236: a score file that allows all users on the system to record their
1237: highscores. In order for this to work, the binaries need to be
1238: installed setgid and the score files owned by the appropriate
1239: group and/or owner (traditionally the "games" user/group). The
1240: following variables, documented in more detail in
1241: <code class="filename">mk/defaults/mk.conf</code>, control this
1242: behaviour: <code class="varname">SETGIDGAME</code>,
1243: <code class="varname">GAMEDATAMODE</code>, <code class="varname">GAMEGRP</code>,
1244: <code class="varname">GAMEMODE</code>, <code class="varname">GAMEOWN</code>.</p>
1245: <p>Note that per default, setgid installation of games is
1246: disabled; setting <code class="varname">SETGIDGAME=YES</code> will set all
1247: the other variables accordingly.</p>
1248: <p>A package should therefor never hard code file ownership or
1249: access permissions but rely on <code class="varname">INSTALL_GAME</code> and
1250: <code class="varname">INSTALL_GAME_DATA</code> to set these
1251: correctly.</p>
1252: </div>
1253: <div class="sect2" lang="en">
1254: <div class="titlepage"><div><div><h3 class="title">
1255: <a name="hardcoded-paths"></a>18.6.4. Packages with hardcoded paths to other interpreters</h3></div></div></div>
1256: <p>Your package may also contain scripts with hardcoded paths to
1257: other interpreters besides (or as well as) perl. To correct the
1258: full pathname to the script interpreter, you need to set the
1259: following definitions in your <code class="filename">Makefile</code> (we
1260: shall use <span><strong class="command">tclsh</strong></span> in this example):</p>
1261: <pre class="programlisting">
1262: REPLACE_INTERPRETER+= tcl
1263: REPLACE.tcl.old= .*/bin/tclsh
1264: REPLACE.tcl.new= ${PREFIX}/bin/tclsh
1265: REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed,
1266: # relative to ${WRKSRC}, just as in REPLACE_PERL
1267: </pre>
1268: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1269: <h3 class="title">Note</h3>
1270: <p>Before March 2006, these variables were called
1271: <code class="varname">_REPLACE.*</code> and
1272: <code class="varname">_REPLACE_FILES.*</code>.</p>
1273: </div>
1274: </div>
1275: <div class="sect2" lang="en">
1276: <div class="titlepage"><div><div><h3 class="title">
1277: <a name="perl-modules"></a>18.6.5. Packages installing perl modules</h3></div></div></div>
1278: <p>Makefiles of packages providing perl5 modules should include
1279: the Makefile fragment
1280: <code class="filename">../../lang/perl5/module.mk</code>. It provides a
1281: <span><strong class="command">do-configure</strong></span> target for the standard perl
1282: configuration for such modules as well as various hooks to tune
1283: this configuration. See comments in this file for
1284: details.</p>
1285: <p>Perl5 modules will install into different places depending
1286: on the version of perl used during the build process. To
1287: address this, pkgsrc will append lines to the
1288: <code class="filename">PLIST</code> corresponding to the files listed in
1289: the installed <code class="filename">.packlist</code> file generated by
1290: most perl5 modules. This is invoked by defining
1291: <code class="varname">PERL5_PACKLIST</code> to a space-separated list of
1292: paths to packlist files, e.g.:</p>
1293: <pre class="programlisting">
1294: PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
1295: </pre>
1296: <p>The variables <code class="varname">PERL5_SITELIB</code>,
1297: <code class="varname">PERL5_SITEARCH</code>, and
1298: <code class="varname">PERL5_ARCHLIB</code> represent the three locations
1299: in which perl5 modules may be installed, and may be used by
1300: perl5 packages that don't have a packlist. These three
1301: variables are also substituted for in the
1302: <code class="filename">PLIST</code>.</p>
1303: </div>
1304: <div class="sect2" lang="en">
1305: <div class="titlepage"><div><div><h3 class="title">
1306: <a name="faq.info-files"></a>18.6.6. Packages installing info files</h3></div></div></div>
1307: <p>Some packages install info files or use the
1308: “<span class="quote">makeinfo</span>” or “<span class="quote">install-info</span>”
1309: commands. <code class="varname">INFO_FILES</code> should be defined in
1310: the package Makefile so that <code class="filename">INSTALL</code> and
1311: <code class="filename">DEINSTALL</code> scripts will be generated to
1312: handle registration of the info files in the Info directory
1313: file. The “<span class="quote">install-info</span>” command used for the info
1314: files registration is either provided by the system, or by a
1315: special purpose package automatically added as dependency if
1316: needed.</p>
1317: <p><code class="varname">PKGINFODIR</code> is the directory under
1318: <code class="filename">${PREFIX}</code> where info files are primarily
1319: located. <code class="varname">PKGINFODIR</code> defaults to
1320: “<span class="quote">info</span>” and can be overridden by the user.</p>
1321: <p>The info files for the package should be listed in the
1322: package <code class="filename">PLIST</code>; however any split info files
1323: need not be listed.</p>
1324: <p>A package which needs the “<span class="quote">makeinfo</span>” command
1325: at build time must add “<span class="quote">makeinfo</span>” to
1326: <code class="varname">USE_TOOLS</code> in its Makefile. If a minimum
1327: version of the “<span class="quote">makeinfo</span>” command is needed it
1328: should be noted with the <code class="varname">TEXINFO_REQD</code>
1329: variable in the package <code class="filename">Makefile</code>. By
1330: default, a minimum version of 3.12 is required. If the system
1331: does not provide a <span><strong class="command">makeinfo</strong></span> command or if it
1332: does not match the required minimum, a build dependency on the
1333: <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/gtexinfo/README.html" target="_top"><code class="filename">devel/gtexinfo</code></a> package will
1334: be added automatically.</p>
1335: <p>The build and installation process of the software provided
1336: by the package should not use the
1337: <span><strong class="command">install-info</strong></span> command as the registration of
1338: info files is the task of the package
1339: <code class="filename">INSTALL</code> script, and it must use the
1340: appropriate <span><strong class="command">makeinfo</strong></span> command.</p>
1341: <p>To achieve this goal, the pkgsrc infrastructure creates
1342: overriding scripts for the <span><strong class="command">install-info</strong></span> and
1343: <span><strong class="command">makeinfo</strong></span> commands in a directory listed early
1344: in <code class="varname">PATH</code>.</p>
1345: <p>The script overriding <span><strong class="command">install-info</strong></span> has
1346: no effect except the logging of a message. The script overriding
1347: <span><strong class="command">makeinfo</strong></span> logs a message and according to the
1348: value of <code class="varname">TEXINFO_REQD</code> either runs the appropriate
1349: <span><strong class="command">makeinfo</strong></span> command or exit on error.</p>
1350: </div>
1351: <div class="sect2" lang="en">
1352: <div class="titlepage"><div><div><h3 class="title">
1353: <a name="manpages"></a>18.6.7. Packages installing man pages</h3></div></div></div>
1354: <p>All packages that install manual pages should install them
1355: into the same directory, so that there is one common place to look
1356: for them. In pkgsrc, this place is
1357: <code class="literal">${PREFIX}/${PKGMANDIR}</code>, and this expression
1358: should be used in packages. The default for
1359: <code class="varname">PKGMANDIR</code> is
1360: “<span class="quote"><code class="filename">man</code></span>”. Another often-used value
1361: is “<span class="quote"><code class="filename">share/man</code></span>”.</p>
1362: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1363: <h3 class="title">Note</h3>
1364: <p>The support for a custom <code class="varname">PKGMANDIR</code>
1365: is far from complete.</p>
1366: </div>
1367: <p>The <code class="filename">PLIST</code> files can just use
1368: <code class="filename">man/</code> as the top level directory for the man
1369: page file entries, and the pkgsrc framework will convert as
1370: needed. In all other places, the correct
1371: <code class="varname">PKGMANDIR</code> must be used.</p>
1372: <p>Packages that are
1373: configured with <code class="varname">GNU_CONFIGURE</code> set as
1374: “<span class="quote">yes</span>”, by default will use the
1375: <code class="filename">./configure</code>
1376: --mandir switch to set where the man pages should be installed.
1377: The path is <code class="varname">GNU_CONFIGURE_MANDIR</code> which defaults
1378: to <code class="varname">${PREFIX}/${PKGMANDIR}</code>.</p>
1379: <p>Packages that use <code class="varname">GNU_CONFIGURE</code> but do not
1380: use --mandir, can set <code class="varname">CONFIGURE_HAS_MANDIR</code>
1381: to “<span class="quote">no</span>”.
1382: Or if the <code class="filename">./configure</code> script uses
1383: a non-standard use of --mandir, you can set
1384: <code class="varname">GNU_CONFIGURE_MANDIR</code> as needed.</p>
1385: <p>See <a href="plist.html#manpage-compression" title="12.5. Man page compression">Section 12.5, “Man page compression”</a> for
1386: information on installation of compressed manual pages.</p>
1387: </div>
1388: <div class="sect2" lang="en">
1389: <div class="titlepage"><div><div><h3 class="title">
1390: <a name="gconf2-data-files"></a>18.6.8. Packages installing GConf2 data files</h3></div></div></div>
1391: <p>If a package installs <code class="filename">.schemas</code> or
1392: <code class="filename">.entries</code> files, used by GConf2,
1393: you need to take some extra steps to make sure they get registered
1394: in the database:</p>
1395: <div class="orderedlist"><ol type="1">
1396: <li><p>Include <code class="filename">../../devel/GConf2/schemas.mk</code>
1397: instead of its <code class="filename">buildlink3.mk</code> file. This
1398: takes care of rebuilding the GConf2 database at installation and
1399: deinstallation time, and tells the package where to install
1400: GConf2 data files using some standard configure arguments. It
1401: also disallows any access to the database directly from the
1402: package.</p></li>
1403: <li><p>Ensure that the package installs its
1404: <code class="filename">.schemas</code> files under
1405: <code class="filename">${PREFIX}/share/gconf/schemas</code>. If they get
1406: installed under <code class="filename">${PREFIX}/etc</code>, you will
1407: need to manually patch the package.</p></li>
1408: <li><p>Check the PLIST and remove any entries under the etc/gconf
1409: directory, as they will be handled automatically. See
1410: <a href="faq.html#faq.conf" title="8.14. How do I change the location of configuration files?">Section 8.14, “How do I change the location of configuration files?”</a> for more information.</p></li>
1411: <li><p>Define the <code class="varname">GCONF2_SCHEMAS</code> variable in
1412: your <code class="filename">Makefile</code> with a list of all
1413: <code class="filename">.schemas</code> files installed by the package, if
1414: any. Names must not contain any directories in them.</p></li>
1415: <li><p>Define the <code class="varname">GCONF2_ENTRIES</code> variable in
1416: your <code class="filename">Makefile</code> with a
1417: list of all <code class="filename">.entries</code> files installed by the
1418: package, if any. Names must not contain any directories in
1419: them.</p></li>
1420: </ol></div>
1421: </div>
1422: <div class="sect2" lang="en">
1423: <div class="titlepage"><div><div><h3 class="title">
1424: <a name="scrollkeeper-data-files"></a>18.6.9. Packages installing scrollkeeper data files</h3></div></div></div>
1425: <p>If a package installs <code class="filename">.omf</code> files, used by
1426: scrollkeeper, you need to take some extra steps to make sure they
1427: get registered in the database:</p>
1428: <div class="orderedlist"><ol type="1">
1429: <li><p>Include
1430: <code class="filename">../../textproc/scrollkeeper/omf.mk</code>
1431: instead of its <code class="filename">buildlink3.mk</code> file. This
1432: takes care of rebuilding the scrollkeeper database at
1433: installation and deinstallation time, and disallows any access
1434: to it directly from the package.</p></li>
1435: <li><p>Check the PLIST and remove any entries under the
1436: <code class="filename">libdata/scrollkeeper</code> directory, as they
1437: will be handled automatically.</p></li>
1438: <li><p>Remove the <code class="filename">share/omf</code> directory from
1439: the PLIST. It will be handled by scrollkeeper.</p></li>
1440: </ol></div>
1441: </div>
1442: <div class="sect2" lang="en">
1443: <div class="titlepage"><div><div><h3 class="title">
1444: <a name="x11-fonts"></a>18.6.10. Packages installing X11 fonts</h3></div></div></div>
1445: <p>If a package installs font files, you will need to rebuild
1446: the fonts database in the directory where they get installed at
1447: installation and deinstallation time. This can be automatically
1448: done by using the pkginstall framework.</p>
1449: <p>You can list the directories where fonts are installed in the
1450: <code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code>
1451: variables, where <em class="replaceable"><code>type</code></em> can be one of
1452: “<span class="quote">ttf</span>”, “<span class="quote">type1</span>” or “<span class="quote">x11</span>”.
1453: Also make sure that the database file
1454: <code class="filename">fonts.dir</code> is not listed in the PLIST.</p>
1455: <p>Note that you should not create new directories for fonts;
1456: instead use the standard ones to avoid that the user needs to
1457: manually configure his X server to find them.</p>
1458: </div>
1459: <div class="sect2" lang="en">
1460: <div class="titlepage"><div><div><h3 class="title">
1461: <a name="gtk2-modules"></a>18.6.11. Packages installing GTK2 modules</h3></div></div></div>
1462: <p>If a package installs GTK2 immodules or loaders, you need to
1463: take some extra steps to get them registered in the GTK2 database
1464: properly:</p>
1465: <div class="orderedlist"><ol type="1">
1466: <li><p>Include
1467: <code class="filename">../../x11/gtk2/modules.mk</code> instead of its
1468: <code class="filename">buildlink3.mk</code> file. This takes care of
1469: rebuilding the database at installation and deinstallation time.</p></li>
1470: <li><p>Set <code class="varname">GTK2_IMMODULES=YES</code> if
1471: your package installs GTK2 immodules.</p></li>
1472: <li><p>Set <code class="varname">GTK2_LOADERS=YES</code> if your package installs
1473: GTK2 loaders.</p></li>
1474: <li>
1475: <p>Patch the package to not touch any of the GTK2
1476: databases directly. These are:</p>
1477: <div class="itemizedlist"><ul type="disc">
1478: <li><p><code class="filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p></li>
1479: <li><p><code class="filename">libdata/gtk-2.0/gtk.immodules</code></p></li>
1480: </ul></div>
1481: </li>
1482: <li><p>Check the <code class="filename">PLIST</code> and remove
1483: any entries under the <code class="filename">libdata/gtk-2.0</code>
1484: directory, as they will be handled automatically.</p></li>
1485: </ol></div>
1486: </div>
1487: <div class="sect2" lang="en">
1488: <div class="titlepage"><div><div><h3 class="title">
1489: <a name="sgml-xml-data"></a>18.6.12. Packages installing SGML or XML data</h3></div></div></div>
1490: <p>If a package installs SGML or XML data files that need to be
1491: registered in system-wide catalogs (like DTDs, sub-catalogs,
1492: etc.), you need to take some extra steps:</p>
1493: <div class="orderedlist"><ol type="1">
1494: <li><p>Include
1495: <code class="filename">../../textproc/xmlcatmgr/catalogs.mk</code> in
1496: your <code class="filename">Makefile</code>, which takes care of
1497: registering those files in system-wide catalogs at
1498: installation and deinstallation time.</p></li>
1499: <li><p>Set <code class="varname">SGML_CATALOGS</code> to the full path of
1500: any SGML catalogs installed by the package.</p></li>
1501: <li><p>Set <code class="varname">XML_CATALOGS</code> to the full path of
1502: any XML catalogs installed by the package.</p></li>
1503: <li><p>Set <code class="varname">SGML_ENTRIES</code> to individual entries
1504: to be added to the SGML catalog. These come in groups of
1505: three strings; see xmlcatmgr(1) for more information
1506: (specifically, arguments recognized by the 'add' action).
1507: Note that you will normally not use this variable.</p></li>
1508: <li><p>Set <code class="varname">XML_ENTRIES</code> to individual entries
1509: to be added to the XML catalog. These come in groups of three
1510: strings; see xmlcatmgr(1) for more information (specifically,
1511: arguments recognized by the 'add' action). Note that you will
1512: normally not use this variable.</p></li>
1513: </ol></div>
1514: </div>
1515: <div class="sect2" lang="en">
1516: <div class="titlepage"><div><div><h3 class="title">
1517: <a name="mime-database"></a>18.6.13. Packages installing extensions to the MIME database</h3></div></div></div>
1518: <p>If a package provides extensions to the MIME database by
1519: installing <code class="filename">.xml</code> files inside
1520: <code class="filename">${PREFIX}/share/mime/packages</code>, you
1521: need to take some extra steps to ensure that the database is kept
1522: consistent with respect to these new files:</p>
1523: <div class="orderedlist"><ol type="1">
1524: <li><p>Include
1525: <code class="filename">../../databases/shared-mime-info/mimedb.mk</code>
1526: (avoid using the <code class="filename">buildlink3.mk</code> file from
1527: this same directory, which is reserved for inclusion from
1528: other <code class="filename">buildlink3.mk</code> files). It takes
1529: care of rebuilding the MIME database at installation and
1530: deinstallation time, and disallows any access to it directly
1531: from the package.</p></li>
1532: <li><p>Check the PLIST and remove any entries under the
1533: <code class="filename">share/mime</code> directory,
1534: <span class="emphasis"><em>except</em></span> for files saved under
1535: <code class="filename">share/mime/packages</code>. The former are
1536: handled automatically by
1537: the update-mime-database program, but the latter are
1538: package-dependent and must be removed by the package that
1539: installed them in the first place.</p></li>
1540: <li><p>Remove any <code class="filename">share/mime/*</code> directories
1541: from the PLIST. They will be handled by the shared-mime-info
1542: package.</p></li>
1543: </ol></div>
1544: </div>
1545: <div class="sect2" lang="en">
1546: <div class="titlepage"><div><div><h3 class="title">
1547: <a name="intltool"></a>18.6.14. Packages using intltool</h3></div></div></div>
1548: <p>If a package uses intltool during its build, add
1549: <code class="literal">intltool</code> to the <code class="varname">USE_TOOLS</code>,
1550: which forces it to use the intltool package provided by pkgsrc,
1551: instead of the one bundled with the distribution file.</p>
1552: <p>This tracks intltool's build-time dependencies and uses the
1553: latest available version; this way, the package benefits of any
1554: bug fixes that may have appeared since it was released.</p>
1555: </div>
1556: <div class="sect2" lang="en">
1557: <div class="titlepage"><div><div><h3 class="title">
1558: <a name="startup-scripts"></a>18.6.15. Packages installing startup scripts</h3></div></div></div>
1559: <p>If a package contains a rc.d script, it won't be copied into
1560: the startup directory by default, but you can enable it, by adding
1561: the option <code class="varname">PKG_RCD_SCRIPTS=YES</code> in
1562: <code class="filename">/etc/mk.conf</code>. This option will copy the scripts
1563: into <code class="filename">/etc/rc.d</code> when a package is installed, and
1564: it will automatically remove the scripts when the package is
1565: deinstalled.</p>
1566: </div>
1567: <div class="sect2" lang="en">
1568: <div class="titlepage"><div><div><h3 class="title">
1569: <a name="tex-packages"></a>18.6.16. Packages installing TeX modules</h3></div></div></div>
1570: <p>If a package installs TeX packages into the texmf tree,
1571: the <code class="filename">ls-R</code> database of the tree needs to be
1572: updated.</p>
1573: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1574: <h3 class="title">Note</h3>
1575: <p>Except the main TeX packages such as teTeX-texmf,
1576: packages should install files
1577: into <code class="varname">PKG_LOCALTEXMFPREFIX</code>,
1578: not <code class="varname">PKG_TEXMFPREFIX</code>.</p>
1579: </div>
1580: <div class="orderedlist"><ol type="1">
1581: <li><p>Include
1582: <code class="filename">../../print/teTeX/module.mk</code> instead
1583: of <code class="filename">../../mk/tex.buildlink3.mk</code>. This
1584: takes care of rebuilding the <code class="filename">ls-R</code>
1585: database at installation and deinstallation time.</p></li>
1586: <li>
1587: <p>If your package installs files into a texmf
1588: tree other than the one
1589: at <code class="varname">PKG_LOCALTEXMFPREFIX</code>,
1590: set <code class="varname">TEXMFDIRS</code> to the list of all texmf
1591: trees that need database update.</p>
1592: <p>If your package also installs font map files that need
1593: to be registered using <span><strong class="command">updmap</strong></span>,
1594: set <code class="varname">TEX_FONTMAPS</code> to the list of all
1595: such font map files. Then <span><strong class="command">updmap</strong></span> will
1596: be run automatically at installation/deinstallation to
1597: enable/disable font map files for TeX output
1598: drivers.</p>
1599: </li>
1600: <li><p>Make sure that none of <code class="filename">ls-R</code>
1601: databases are included in <code class="filename">PLIST</code>, as
1602: they will be removed only by the teTeX-bin package.</p></li>
1603: </ol></div>
1604: </div>
1605: <div class="sect2" lang="en">
1606: <div class="titlepage"><div><div><h3 class="title">
1607: <a name="emulation-packages"></a>18.6.17. Packages supporting running binaries in
1608: emulation</h3></div></div></div>
1609: <p>There are some packages that provide libraries and
1610: executables for running binaries from a one operating system
1611: on a different one (if the latter supports it). One example
1612: is running Linux binaries on NetBSD.</p>
1613: <p>The <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/rpm2pkg/README.html" target="_top"><code class="filename">pkgtools/rpm2pkg</code></a>
1614: helps in extracting and packaging Linux rpm packages.</p>
1615: <p>The <code class="varname">CHECK_SHLIBS</code> can be set to no to
1616: avoid the <span><strong class="command">check-shlibs</strong></span> target, which tests
1617: if all libraries for each installed executable can be found by
1618: the dynamic linker. Since the standard dynamic linker is run,
1619: this fails for emulation packages, because the libraries used
1620: by the emulation are not in the standard directories.</p>
1621: </div>
1622: <div class="sect2" lang="en">
1623: <div class="titlepage"><div><div><h3 class="title">
1624: <a name="hicolor-theme"></a>18.6.18. Packages installing hicolor theme icons</h3></div></div></div>
1625: <p>If a package installs images under the
1626: <code class="filename">share/icons/hicolor</code> and/or updates the
1627: <code class="filename">share/icons/hicolor/icon-theme.cache</code>
1628: database, you need to take some extra steps to make sure that the
1629: shared theme directory is handled appropriately and that the cache
1630: database is rebuilt:</p>
1631: <div class="orderedlist"><ol type="1">
1632: <li><p>Include
1633: <code class="filename">../../graphics/hicolor-icon-theme/buildlink3.mk</code>.</p></li>
1634: <li><p>Check the <code class="filename">PLIST</code> and remove the
1635: entry that refers to the theme cache.</p></li>
1636: <li><p>Ensure that the PLIST does not remove the shared icon
1637: directories from the <code class="filename">share/icons/hicolor</code>
1638: hierarchy because they will be handled automatically.</p></li>
1639: </ol></div>
1640: <p>The best way to verify that the PLIST is correct with
1641: respect to the last two points is to regenerate it using
1642: <span><strong class="command">make print-PLIST</strong></span>.</p>
1643: </div>
1644: <div class="sect2" lang="en">
1645: <div class="titlepage"><div><div><h3 class="title">
1646: <a name="desktop-files"></a>18.6.19. Packages installing desktop files</h3></div></div></div>
1647: <p>If a package installs <code class="filename">.desktop</code> files
1648: under <code class="filename">share/applications</code> and these include
1649: MIME information, you need to take extra steps to ensure that they
1650: are registered into the MIME database:</p>
1651: <div class="orderedlist"><ol type="1">
1652: <li><p>Include
1653: <code class="filename">../../sysutils/desktop-file-utils/desktopdb.mk</code>.</p></li>
1654: <li><p>Check the PLIST and remove the entry that refers to the
1655: <code class="filename">share/applications/mimeinfo.cache</code> file.
1656: It will be handled automatically.</p></li>
1657: </ol></div>
1658: <p>The best way to verify that the PLIST is correct with
1659: respect to the last point is to regenerate it using <span><strong class="command">make
1660: print-PLIST</strong></span>.</p>
1661: </div>
1662: </div>
1663: <div class="sect1" lang="en">
1664: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1665: <a name="punting"></a>18.7. Marking packages as having problems</h2></div></div></div>
1666: <p>In some cases one does not have the time to solve a problem
1667: immediately. There are currently two ways to declare that one knows
1668: that a package has problems.</p>
1669: <div class="itemizedlist"><ul type="disc">
1670: <li><p>The first way is to plainly mark it as broken. For
1671: this, one just sets the variable <code class="varname">BROKEN</code> to the
1672: reason why the package is broken (similar to the
1673: <code class="varname">RESTRICTED</code> variable). A user trying to build
1674: the package will immediately be shown this message, and the build
1675: will not be even tried.</p></li>
1676: <li><p>After each pkgsrc freeze period (a time when the
1677: tree is stabilized and a new pkgsrc branch is cut), the packages
1678: that were not building in the official branch build on the latest
1679: NetBSD release will be marked as broken on that branch. This is
1680: done by setting the <code class="varname">BROKEN_IN</code> variable to the
1681: branch name (or appending the branch name to it). If a user tries
1682: to build such a package and the build fails, the user gets a
1683: message that says that the package was broken on the respective
1684: branch(es).</p></li>
1685: </ul></div>
1686: <p>Both types of packages are removed from pkgsrc in irregular
1687: intervals.</p>
1688: </div>
1689: </div>
1690: <div class="navfooter">
1691: <hr>
1692: <table width="100%" summary="Navigation footer">
1693: <tr>
1694: <td width="40%" align="left">
1695: <a accesskey="p" href="tools.html">Prev</a> </td>
1696: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1697: <td width="40%" align="right"> <a accesskey="n" href="debug.html">Next</a>
1698: </td>
1699: </tr>
1700: <tr>
1701: <td width="40%" align="left" valign="top">Chapter 17. Tools needed for building or running </td>
1702: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1703: <td width="40%" align="right" valign="top"> Chapter 19. Debugging</td>
1704: </tr>
1705: </table>
1706: </div>
1707: </body>
1708: </html>
CVSweb <webmaster@jp.NetBSD.org>