Annotation of htdocs/docs/pkgsrc/fixes.html, revision 1.78
1.56 sevan 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1 dsieger 2: <html>
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.63 rillig 5: <title>Chapter 21. Making your package work</title>
1.17 spz 6: <link rel="stylesheet" type="text/css" href="/global.css">
1.1 dsieger 7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
1.10 rillig 8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.1 dsieger 9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.76 rillig 10: <link rel="prev" href="pkginstall.html" title="Chapter 20. The pkginstall framework">
11: <link rel="next" href="gnome.html" title="Chapter 22. GNOME packaging and porting">
1.1 dsieger 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">
1.63 rillig 16: <tr><th colspan="3" align="center">Chapter 21. Making your package work</th></tr>
1.1 dsieger 17: <tr>
18: <td width="20%" align="left">
1.76 rillig 19: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
1.1 dsieger 20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
1.76 rillig 21: <td width="20%" align="right"> <a accesskey="n" href="gnome.html">Next</a>
1.1 dsieger 22: </td>
23: </tr>
24: </table>
25: <hr>
26: </div>
1.24 asau 27: <div class="chapter">
1.1 dsieger 28: <div class="titlepage"><div><div><h2 class="title">
1.63 rillig 29: <a name="fixes"></a>Chapter 21. Making your package work</h2></div></div></div>
1.1 dsieger 30: <div class="toc">
31: <p><b>Table of Contents</b></p>
1.47 leot 32: <dl class="toc">
1.63 rillig 33: <dt><span class="sect1"><a href="fixes.html#general-operation">21.1. General operation</a></span></dt>
1.1 dsieger 34: <dd><dl>
1.63 rillig 35: <dt><span class="sect2"><a href="fixes.html#pulling-vars-from-etc-mk.conf">21.1.1. How to pull in user-settable variables from <code class="filename">mk.conf</code></a></span></dt>
36: <dt><span class="sect2"><a href="fixes.html#user-interaction">21.1.2. User interaction</a></span></dt>
37: <dt><span class="sect2"><a href="fixes.html#handling-licenses">21.1.3. Handling licenses</a></span></dt>
38: <dt><span class="sect2"><a href="fixes.html#restricted-packages">21.1.4. Restricted packages</a></span></dt>
39: <dt><span class="sect2"><a href="fixes.html#dependencies">21.1.5. Handling dependencies</a></span></dt>
40: <dt><span class="sect2"><a href="fixes.html#conflicts">21.1.6. Handling conflicts with other packages</a></span></dt>
41: <dt><span class="sect2"><a href="fixes.html#not-building-packages">21.1.7. Packages that cannot or should not be built</a></span></dt>
42: <dt><span class="sect2"><a href="fixes.html#undeletable-packages">21.1.8. Packages which should not be deleted, once installed</a></span></dt>
43: <dt><span class="sect2"><a href="fixes.html#security-handling">21.1.9. Handling packages with security problems</a></span></dt>
44: <dt><span class="sect2"><a href="fixes.html#bumping-pkgrevision">21.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt>
45: <dt><span class="sect2"><a href="fixes.html#fixes.subst">21.1.11. Substituting variable text in the package files (the SUBST framework)</a></span></dt>
1.1 dsieger 46: </dl></dd>
1.63 rillig 47: <dt><span class="sect1"><a href="fixes.html#fixes.fetch">21.2. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
1.1 dsieger 48: <dd><dl>
1.63 rillig 49: <dt><span class="sect2"><a href="fixes.html#no-plain-download">21.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt>
50: <dt><span class="sect2"><a href="fixes.html#modified-distfiles-same-name">21.2.2. How to handle modified distfiles with the 'old' name</a></span></dt>
51: <dt><span class="sect2"><a href="fixes.html#build.fetch.github">21.2.3. Packages hosted on github.com</a></span></dt>
1.1 dsieger 52: </dl></dd>
1.63 rillig 53: <dt><span class="sect1"><a href="fixes.html#fixes.configure">21.3. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
1.1 dsieger 54: <dd><dl>
1.63 rillig 55: <dt><span class="sect2"><a href="fixes.html#fixes.libtool">21.3.1. Shared libraries - libtool</a></span></dt>
56: <dt><span class="sect2"><a href="fixes.html#using-libtool">21.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">21.3.3. GNU Autoconf/Automake</a></span></dt>
1.1 dsieger 58: </dl></dd>
1.63 rillig 59: <dt><span class="sect1"><a href="fixes.html#programming-languages">21.4. Programming languages</a></span></dt>
1.1 dsieger 60: <dd><dl>
1.63 rillig 61: <dt><span class="sect2"><a href="fixes.html#basic-programming-languages">21.4.1. C, C++, and Fortran</a></span></dt>
62: <dt><span class="sect2"><a href="fixes.html#java-programming-language">21.4.2. Java</a></span></dt>
63: <dt><span class="sect2"><a href="fixes.html#perl-scripts">21.4.3. Packages containing perl scripts</a></span></dt>
64: <dt><span class="sect2"><a href="fixes.html#shell-scripts">21.4.4. Packages containing shell scripts</a></span></dt>
65: <dt><span class="sect2"><a href="fixes.html#other-programming-languages">21.4.5. Other programming languages</a></span></dt>
1.1 dsieger 66: </dl></dd>
1.63 rillig 67: <dt><span class="sect1"><a href="fixes.html#fixes.build">21.5. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
1.1 dsieger 68: <dd><dl>
1.63 rillig 69: <dt><span class="sect2"><a href="fixes.html#fixes.build.cpp">21.5.1. Compiling C and C++ code conditionally</a></span></dt>
70: <dt><span class="sect2"><a href="fixes.html#compiler-bugs">21.5.2. How to handle compiler bugs</a></span></dt>
1.69 rillig 71: <dt><span class="sect2"><a href="fixes.html#fixes.build.header">21.5.3. No such file or directory</a></span></dt>
72: <dt><span class="sect2"><a href="fixes.html#undefined-reference">21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
73: <dt><span class="sect2"><a href="fixes.html#out-of-memory">21.5.5. Running out of memory</a></span></dt>
1.1 dsieger 74: </dl></dd>
1.63 rillig 75: <dt><span class="sect1"><a href="fixes.html#fixes.install">21.6. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
1.1 dsieger 76: <dd><dl>
1.63 rillig 77: <dt><span class="sect2"><a href="fixes.html#install-scripts">21.6.1. Creating needed directories</a></span></dt>
78: <dt><span class="sect2"><a href="fixes.html#where-to-install-documentation">21.6.2. Where to install documentation</a></span></dt>
79: <dt><span class="sect2"><a href="fixes.html#installing-score-files">21.6.3. Installing highscore files</a></span></dt>
80: <dt><span class="sect2"><a href="fixes.html#destdir-support">21.6.4. Adding DESTDIR support to packages</a></span></dt>
81: <dt><span class="sect2"><a href="fixes.html#hardcoded-paths">21.6.5. Packages with hardcoded paths to other interpreters</a></span></dt>
82: <dt><span class="sect2"><a href="fixes.html#perl-modules">21.6.6. Packages installing perl modules</a></span></dt>
83: <dt><span class="sect2"><a href="fixes.html#faq.info-files">21.6.7. Packages installing info files</a></span></dt>
84: <dt><span class="sect2"><a href="fixes.html#manpages">21.6.8. Packages installing man pages</a></span></dt>
85: <dt><span class="sect2"><a href="fixes.html#gconf-data-files">21.6.9. Packages installing GConf data files</a></span></dt>
86: <dt><span class="sect2"><a href="fixes.html#scrollkeeper-data-files">21.6.10. Packages installing scrollkeeper/rarian data files</a></span></dt>
87: <dt><span class="sect2"><a href="fixes.html#x11-fonts">21.6.11. Packages installing X11 fonts</a></span></dt>
88: <dt><span class="sect2"><a href="fixes.html#gtk2-modules">21.6.12. Packages installing GTK2 modules</a></span></dt>
89: <dt><span class="sect2"><a href="fixes.html#sgml-xml-data">21.6.13. Packages installing SGML or XML data</a></span></dt>
90: <dt><span class="sect2"><a href="fixes.html#mime-database">21.6.14. Packages installing extensions to the MIME database</a></span></dt>
91: <dt><span class="sect2"><a href="fixes.html#intltool">21.6.15. Packages using intltool</a></span></dt>
92: <dt><span class="sect2"><a href="fixes.html#startup-scripts">21.6.16. Packages installing startup scripts</a></span></dt>
93: <dt><span class="sect2"><a href="fixes.html#tex-packages">21.6.17. Packages installing TeX modules</a></span></dt>
94: <dt><span class="sect2"><a href="fixes.html#emulation-packages">21.6.18. Packages supporting running binaries in
1.1 dsieger 95: emulation</a></span></dt>
1.63 rillig 96: <dt><span class="sect2"><a href="fixes.html#hicolor-theme">21.6.19. Packages installing hicolor theme icons</a></span></dt>
97: <dt><span class="sect2"><a href="fixes.html#desktop-files">21.6.20. Packages installing desktop files</a></span></dt>
1.1 dsieger 98: </dl></dd>
1.63 rillig 99: <dt><span class="sect1"><a href="fixes.html#punting">21.7. Marking packages as having problems</a></span></dt>
1.1 dsieger 100: </dl>
101: </div>
1.24 asau 102: <div class="sect1">
1.1 dsieger 103: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 104: <a name="general-operation"></a>21.1. General operation</h2></div></div></div>
1.1 dsieger 105: <p>One appealing feature of pkgsrc is that it runs on many
1.50 rillig 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>
1.24 asau 110: <div class="sect2">
1.1 dsieger 111: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 112: <a name="pulling-vars-from-etc-mk.conf"></a>21.1.1. How to pull in user-settable variables from <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>
1.1 dsieger 113: </h3></div></div></div>
114: <p>The pkgsrc user can configure pkgsrc by overriding several
115: variables in the file pointed to by <code class="varname">MAKECONF</code>,
1.7 hubertf 116: which is <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> by default. When you
1.1 dsieger 117: want to use those variables in the preprocessor directives of
1.78 ! kim 118: <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/make.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> (for example <code class="literal">.if</code> or
1.1 dsieger 119: <code class="literal">.for</code>), you need to include the file
120: <code class="filename">../../mk/bsd.prefs.mk</code> before, which in turn
121: loads the user preferences.</p>
122: <p>But note that some variables may not be completely defined
123: after <code class="filename">../../mk/bsd.prefs.mk</code> has been
124: included, as they may contain references to variables that are
1.50 rillig 125: not yet defined. In shell commands (the lines in
126: <code class="filename">Makefile</code> that are indented with a tab) this
127: is no problem, since variables are only expanded when they are
128: used. But in the preprocessor directives mentioned above and in
129: dependency lines (of the form <code class="literal">target:
1.1 dsieger 130: dependencies</code>) the variables are expanded at load
131: time.</p>
1.24 asau 132: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 133: <h3 class="title">Note</h3>
1.50 rillig 134: <p>To check whether a variable can be used at load time,
135: run <span class="command"><strong>pkglint -Wall</strong></span> on your package.</p>
1.1 dsieger 136: </div>
137: </div>
1.24 asau 138: <div class="sect2">
1.1 dsieger 139: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 140: <a name="user-interaction"></a>21.1.2. User interaction</h3></div></div></div>
1.1 dsieger 141: <p>Occasionally, packages require interaction from the user,
142: and this can be in a number of ways:</p>
1.24 asau 143: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 144: <li class="listitem"><p>When fetching the distfiles, some packages require user
1.1 dsieger 145: interaction such as entering username/password or accepting a
146: license on a web page.</p></li>
1.15 wiz 147: <li class="listitem"><p>When extracting the distfiles, some packages may ask for
1.1 dsieger 148: passwords.</p></li>
1.15 wiz 149: <li class="listitem"><p>help to configure the package before it is built</p></li>
150: <li class="listitem"><p>help during the build process</p></li>
151: <li class="listitem"><p>help during the installation of a package</p></li>
1.1 dsieger 152: </ul></div>
1.50 rillig 153: <p>A package can set the <code class="varname">INTERACTIVE_STAGE</code>
154: variable to define which stages need interaction. This should be
155: done in the package's <code class="filename">Makefile</code>, e.g.:</p>
1.1 dsieger 156: <pre class="programlisting">
157: INTERACTIVE_STAGE= configure install
1.52 sevan 158: </pre>
1.1 dsieger 159: <p>The user can then decide to skip this package by setting the
1.50 rillig 160: <code class="varname">BATCH</code> variable. Packages that require interaction
161: are also excluded from bulk builds.</p>
1.1 dsieger 162: </div>
1.24 asau 163: <div class="sect2">
1.1 dsieger 164: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 165: <a name="handling-licenses"></a>21.1.3. Handling licenses</h3></div></div></div>
1.52 sevan 166: <p>Authors of software can choose the licence under which software
167: can be copied. The Free Software Foundation has declared some
168: licenses "Free", and the Open Source Initiative has a definition of
169: "Open Source".</p>
170: <p>By default, pkgsrc allows packages with Free or Open Source
171: licenses to be built. To allow packages with other licenses to be
172: built as well, the pkgsrc user needs to add these licenses to the
173: <code class="varname">ACCEPTABLE_LICENSES</code> variable in <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>. Note
174: that this variable only affects which packages may be
175: <span class="emphasis"><em>built</em></span>, while the license terms often also
176: restrict the actual use of the package and its redistribution.</p>
1.1 dsieger 177: <p>One might want to only install packages with a BSD license,
1.50 rillig 178: or the GPL, and not the other. The free licenses are added to the
1.52 sevan 179: default <code class="varname">ACCEPTABLE_LICENSES</code> variable. The pkgsrc
1.13 jnemeth 180: user can override the default by setting the
181: <code class="varname">ACCEPTABLE_LICENSES</code> variable with "=" instead
1.52 sevan 182: of "+=". The licenses accepted by default are defined in the
183: <code class="varname">DEFAULT_ACCEPTABLE_LICENSES</code> variable in the file
184: <code class="filename">pkgsrc/mk/license.mk</code>.</p>
1.1 dsieger 185: <p>The license tag mechanism is intended to address
186: copyright-related issues surrounding building, installing and
187: using a package, and not to address redistribution issues (see
188: <code class="varname">RESTRICTED</code> and
1.52 sevan 189: <code class="varname">NO_SRC_ON_FTP</code>, etc.).
1.13 jnemeth 190: Packages with redistribution restrictions should set these
191: tags.</p>
1.1 dsieger 192: <p>Denoting that a package may be copied according to a
193: particular license is done by placing the license in
194: <code class="filename">pkgsrc/licenses</code> and setting the
195: <code class="varname">LICENSE</code> variable to a string identifying the
1.59 leot 196: license, e.g. in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/graphics/xv/README.html" target="_top"><code class="filename">graphics/xv</code></a>:</p>
1.1 dsieger 197: <pre class="programlisting">
198: LICENSE= xv-license
1.52 sevan 199: </pre>
1.1 dsieger 200: <p>When trying to build, the user will get a notice that the
201: package is covered by a license which has not been placed in the
202: <code class="varname">ACCEPTABLE_LICENSES</code> variable:</p>
203: <pre class="programlisting">
204: <code class="prompt">%</code> <strong class="userinput"><code>make</code></strong>
205: ===> xv-3.10anb9 has an unacceptable license: xv-license.
206: ===> To view the license, enter "/usr/bin/make show-license".
207: ===> To indicate acceptance, add this line to your /etc/mk.conf:
208: ===> ACCEPTABLE_LICENSES+=xv-license
209: *** Error code 1
1.52 sevan 210: </pre>
1.7 hubertf 211: <p>The license can be viewed with <span class="command"><strong>make
1.1 dsieger 212: show-license</strong></span>, and if the user so chooses, the line
1.7 hubertf 213: printed above can be added to <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> to
1.1 dsieger 214: convey to pkgsrc that it should not in the future fail because of
215: that license:</p>
216: <pre class="programlisting">
217: ACCEPTABLE_LICENSES+=xv-license
1.52 sevan 218: </pre>
219: <p>The use of <code class="varname">LICENSE=shareware</code>,
220: <code class="varname">LICENSE=no-commercial-use</code>, and similar language
221: is deprecated because it does not crisply refer to a particular
222: license text. Another problem with such usage is that it does not
223: enable a user to tell pkgsrc to proceed for a single package
224: without also telling pkgsrc to proceed for all packages with that
225: tag.</p>
226: <div class="sect3">
227: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 228: <a name="new-license"></a>21.1.3.1. Adding a package with a new license</h4></div></div></div>
1.27 rodent 229: <p>When adding a package with a new license, the following steps
230: are required:</p>
231: <div class="orderedlist"><ol class="orderedlist" type="1">
232: <li class="listitem">
1.68 rillig 233: <p>Check whether the license qualifies as Free or Open Source by
234: referencing <a class="ulink" href="https://www.gnu.org/licenses/license-list.en.html" target="_top">Various
235: Licenses and Comments about Them</a> and <a class="ulink" href="https://opensource.org/licenses/alphabetical" target="_top">Licenses by Name |
1.52 sevan 236: Open Source Initiative</a>. If this is the case, the filename in
237: <code class="filename">pkgsrc/licenses/</code> does not need the
238: <code class="filename">-license</code> suffix, and the license name should be
239: added to:</p>
1.27 rodent 240: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.68 rillig 241: <li class="listitem"><p>DEFAULT_ACCEPTABLE_LICENSES in
242: <code class="filename">pkgsrc/mk/license.mk</code></p></li>
243: <li class="listitem"><p>default_acceptable_licenses in
244: <code class="filename">pkgsrc/pkgtools/pkg_install/files/lib/license.c</code></p></li>
1.27 rodent 245: </ul></div>
246: </li>
1.68 rillig 247: <li class="listitem"><p>The license text should be added to
248: <code class="filename">pkgsrc/licenses</code> for displaying. A list of known
249: licenses can be seen in this directory.</p></li>
1.27 rodent 250: </ol></div>
1.52 sevan 251: </div>
252: <div class="sect3">
253: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 254: <a name="change-license"></a>21.1.3.2. Change to the license</h4></div></div></div>
1.1 dsieger 255: <p>When the license changes (in a way other than formatting),
1.52 sevan 256: make sure that the new license has a different name (e.g.,
1.1 dsieger 257: append the version number if it exists, or the date). Just
258: because a user told pkgsrc to build programs under a previous
259: version of a license does not mean that pkgsrc should build
260: programs under the new licenses. The higher-level point is that
261: pkgsrc does not evaluate licenses for reasonableness; the only
262: test is a mechanistic test of whether a particular text has been
1.52 sevan 263: approved by either of two bodies (FSF or OSI).</p>
264: </div>
1.1 dsieger 265: </div>
1.24 asau 266: <div class="sect2">
1.1 dsieger 267: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 268: <a name="restricted-packages"></a>21.1.4. Restricted packages</h3></div></div></div>
1.1 dsieger 269: <p>Some licenses restrict how software may be re-distributed.
1.52 sevan 270: By declaring the restrictions, package tools can
1.1 dsieger 271: automatically refrain from e.g. placing binary packages on FTP
272: sites.</p>
1.52 sevan 273: <p>There are four possible restrictions, which are
1.1 dsieger 274: the cross product of sources (distfiles) and binaries not being
275: placed on FTP sites and CD-ROMs. Because this is rarely the exact
276: language in any license, and because non-Free licenses tend to be
277: different from each other, pkgsrc adopts a definition of FTP and
1.52 sevan 278: CD-ROM.
279:
280: "FTP" means making the source or binary file available over the
281: Internet at no charge.
282:
283: "CD-ROM" means making the source or binary available on some kind of
284: media, together with other source and binary packages, which is sold
285: for a distribution charge.
1.1 dsieger 286: </p>
287: <p>In order to encode these restrictions, the package system
288: defines five make variables that can be set to note these
289: restrictions:</p>
1.24 asau 290: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 291: <li class="listitem">
1.1 dsieger 292: <p><code class="varname">RESTRICTED</code></p>
293: <p>This variable should be set whenever a restriction
294: exists (regardless of its kind). Set this variable to a
295: string containing the reason for the restriction. It should
296: be understood that those wanting to understand the restriction
297: will have to read the license, and perhaps seek advice of
298: counsel.</p>
299: </li>
1.15 wiz 300: <li class="listitem">
1.1 dsieger 301: <p><code class="varname">NO_BIN_ON_CDROM</code></p>
302: <p>Binaries may not be placed on CD-ROM containing other
303: binary packages, for which a distribution charge may be made.
304: In this case, set this variable to
305: <code class="varname">${RESTRICTED}</code>.</p>
306: </li>
1.15 wiz 307: <li class="listitem">
1.1 dsieger 308: <p><code class="varname">NO_BIN_ON_FTP</code></p>
309: <p>Binaries may not made available on the Internet without
310: charge. In this case, set this variable to
311: <code class="varname">${RESTRICTED}</code>. If this variable is set,
312: binary packages will not be included on ftp.NetBSD.org.</p>
313: </li>
1.15 wiz 314: <li class="listitem">
1.1 dsieger 315: <p><code class="varname">NO_SRC_ON_CDROM</code></p>
316: <p>Distfiles may not be placed on CD-ROM, together with
317: other distfiles, for which a fee may be charged. In this
318: case, set this variable to <code class="varname">${RESTRICTED}</code>.
319: </p>
320: </li>
1.15 wiz 321: <li class="listitem">
1.1 dsieger 322: <p><code class="varname">NO_SRC_ON_FTP</code></p>
323: <p>Distfiles may not made available via FTP at no charge.
324: In this case, set this variable to
325: <code class="varname">${RESTRICTED}</code>. If this variable is set,
326: the distfile(s) will not be mirrored on ftp.NetBSD.org.</p>
327: </li>
328: </ul></div>
1.52 sevan 329: <p>Please note that packages will be removed from pkgsrc when the
330: distfiles are not distributable and cannot be obtained for a period
331: of one full quarter branch. Packages with manual/interactive fetch
332: must have a maintainer and it is his/her responsibility to ensure
333: this.</p>
1.1 dsieger 334: </div>
1.24 asau 335: <div class="sect2">
1.1 dsieger 336: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 337: <a name="dependencies"></a>21.1.5. Handling dependencies</h3></div></div></div>
1.72 gutterid 338: <p>Your package may depend on some other package being present,
339: and there are various ways of expressing this dependency.
340: pkgsrc supports the <code class="varname">DEPENDS</code>,
341: <code class="varname">BUILD_DEPENDS</code>,
342: <code class="varname">TOOL_DEPENDS</code>, and
343: <code class="varname">TEST_DEPENDS</code> definitions, the
1.1 dsieger 344: <code class="varname">USE_TOOLS</code> definition, as well as dependencies
345: via <code class="filename">buildlink3.mk</code>, which is the preferred way
346: to handle dependencies, and which uses the variables named above.
1.76 rillig 347: See <a class="xref" href="buildlink.html" title="Chapter 18. Buildlink methodology">Chapter 18, <i>Buildlink methodology</i></a> for more information.</p>
1.72 gutterid 348: <p>The basic difference is that the <code class="varname">DEPENDS</code>
349: definition registers that pre-requisite in the binary package so it
350: will be pulled in when the binary package is later installed, whilst
351: the <code class="varname">BUILD_DEPENDS</code>, <code class="varname">TOOL_DEPENDS</code>,
352: and <code class="varname">TEST_DEPENDS</code> definitions do not, marking a
353: dependency that is only needed for building or testing the resulting
1.76 rillig 354: package. See also <a class="xref" href="creating.html" title="Chapter 14. Creating a new pkgsrc package from scratch">Chapter 14, <i>Creating a new pkgsrc package from scratch</i></a> for more information.</p>
1.1 dsieger 355: <p>This means that if you only need a package present whilst
1.72 gutterid 356: you are building or testing, it should be noted as a
357: <code class="varname">TOOL_DEPENDS</code>,
358: <code class="varname">BUILD_DEPENDS</code>, or
359: <code class="varname">TEST_DEPENDS</code>. When cross-compiling,
1.64 leot 360: <code class="varname">TOOL_DEPENDS</code> are <span class="emphasis"><em>native</em></span>
361: packages, i.e. packages for the architecture where the package
362: is built;
363: <code class="varname">BUILD_DEPENDS</code> are <span class="emphasis"><em>target</em></span>
1.72 gutterid 364: packages, i.e., packages for the architecture for which the package
1.64 leot 365: is built.</p>
1.72 gutterid 366: <p>The format for a <code class="varname">DEPENDS</code>,
367: <code class="varname">BUILD_DEPENDS</code>, <code class="varname">TOOL_DEPENDS</code>,
368: and <code class="varname">TEST_DEPENDS</code> definition is:</p>
1.1 dsieger 369: <pre class="programlisting">
370: <pre-req-package-name>:../../<category>/<pre-req-package>
1.52 sevan 371: </pre>
1.15 wiz 372: <p>Please note that the <span class="quote">“<span class="quote">pre-req-package-name</span>”</span>
1.1 dsieger 373: may include any of the wildcard version numbers recognized by
1.78 ! kim 374: <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/pkg_info.1"><span class="citerefentry"><span class="refentrytitle">pkg_info</span>(1)</span></a>.</p>
1.15 wiz 375: <div class="orderedlist"><ol class="orderedlist" type="1">
376: <li class="listitem">
1.1 dsieger 377: <p>If your package needs another package's binaries or
1.30 wiz 378: libraries to build and run, and if that package has a
1.1 dsieger 379: <code class="filename">buildlink3.mk</code> file available, use it:</p>
380: <pre class="programlisting">
381: .include "../../graphics/jpeg/buildlink3.mk"
1.52 sevan 382: </pre>
1.1 dsieger 383: </li>
1.15 wiz 384: <li class="listitem">
1.30 wiz 385: <p>If your package needs another package's binaries or
386: libraries only for building, and if that package has a
387: <code class="filename">buildlink3.mk</code> file available, use it:</p>
388: <pre class="programlisting">
389: .include "../../graphics/jpeg/buildlink3.mk"
1.52 sevan 390: </pre>
1.30 wiz 391: <p>but set
392: <code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>jpeg</code></em>?=build</code>
393: to make it a build dependency only. This case is rather
394: rare.</p>
395: </li>
396: <li class="listitem">
1.17 spz 397: <p>If your package needs binaries from another package to build,
1.64 leot 398: use the <code class="varname">TOOL_DEPENDS</code> definition:</p>
1.1 dsieger 399: <pre class="programlisting">
1.64 leot 400: TOOL_DEPENDS+= itstool-[0-9]*:../../textproc/itstool
1.52 sevan 401: </pre>
1.1 dsieger 402: </li>
1.64 leot 403: <li class="listitem"><p>If your package needs static libraries to link against, header
404: files to include, etc. from another package to build,
405: use the <code class="varname">BUILD_DEPENDS</code> definition.</p></li>
1.17 spz 406: <li class="listitem"><p>If your package needs a library with which to link and
407: there is no <code class="filename">buildlink3.mk</code> file
408: available, create one. Using
409: <code class="varname">DEPENDS</code> won't be sufficient because the
410: include files and libraries will be hidden from the compiler.</p></li>
1.15 wiz 411: <li class="listitem">
1.17 spz 412: <p>If your package needs some executable to be able to run
413: correctly and if there's no
414: <code class="filename">buildlink3.mk</code> file, this is specified
415: using the <code class="varname">DEPENDS</code> variable. The
1.59 leot 416: <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/lyx/README.html" target="_top"><code class="filename">print/lyx</code></a> package needs to
1.58 wiz 417: be able to execute the latex binary from the tex-latex-bin package
1.17 spz 418: when it runs, and that is specified:</p>
1.1 dsieger 419: <pre class="programlisting">
1.58 wiz 420: DEPENDS+= tex-latex-bin-[0-9]*:../../print/tex-latex-bin
1.52 sevan 421: </pre>
1.17 spz 422: </li>
1.72 gutterid 423: <li class="listitem"><p>If your package includes a test suite that has extra
424: dependencies only required for this purpose (frequently this
425: can be run as a <span class="quote">“<span class="quote">make test</span>”</span> target), use the
426: <code class="varname">TEST_DEPENDS</code> variable.</p></li>
1.17 spz 427: <li class="listitem">
428: <p>You can use wildcards in package dependencies. Note that
429: such wildcard dependencies are retained when creating binary
430: packages. The dependency is checked when installing the binary
431: package and any package which matches the pattern will be
432: used. Wildcard dependencies should be used with care.</p>
1.15 wiz 433: <p>The <span class="quote">“<span class="quote">-[0-9]*</span>”</span> should be used instead of
434: <span class="quote">“<span class="quote">-*</span>”</span> to avoid potentially ambiguous matches
435: such as <span class="quote">“<span class="quote">tk-postgresql</span>”</span> matching a
436: <span class="quote">“<span class="quote">tk-*</span>”</span> <code class="varname">DEPENDS</code>.</p>
1.1 dsieger 437: <p>Wildcards can also be used to specify that a package
438: will only build against a certain minimum version of a
439: pre-requisite:</p>
440: <pre class="programlisting">
1.17 spz 441: DEPENDS+= ImageMagick>=6.0:../../graphics/ImageMagick
1.52 sevan 442: </pre>
1.17 spz 443: <p>This means that the package will build using version 6.0
444: of ImageMagick or newer. Such a dependency may be warranted
445: if, for example, the command line options of an executable
446: have changed.</p>
447: <p>If you need to depend on minimum versions of libraries,
1.75 wiz 448: set
449: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
450: to the appropriate pattern before including its
451: <code class="filename">buildlink3.mk</code> file, e.g.</p>
452: <pre class="programlisting">
453: BUILDLINK_API_DEPENDS.jpeg+= jpeg>=9.0
454: .include "../../graphics/jpeg/buildlink3.mk"
455: </pre>
1.1 dsieger 456: <p>For security fixes, please update the package
1.63 rillig 457: vulnerabilities file. See <a class="xref" href="fixes.html#security-handling" title="21.1.9. Handling packages with security problems">Section 21.1.9, “Handling packages with security problems”</a> for more
1.1 dsieger 458: information.</p>
459: </li>
460: </ol></div>
461: <p>If your package needs files from another package to build,
462: add the relevant distribution files to
463: <code class="varname">DISTFILES</code>, so they will be extracted
1.59 leot 464: automatically. See the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/ghostscript/README.html" target="_top"><code class="filename">print/ghostscript</code></a> package for an example.
1.1 dsieger 465: (It relies on the jpeg sources being present in source form
466: during the build.)</p>
467: </div>
1.24 asau 468: <div class="sect2">
1.1 dsieger 469: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 470: <a name="conflicts"></a>21.1.6. Handling conflicts with other packages</h3></div></div></div>
1.1 dsieger 471: <p>Your package may conflict with other packages a user might
472: already have installed on his system, e.g. if your package
473: installs the same set of files as another package in the pkgsrc
1.35 wiz 474: tree or has the same <code class="varname">PKGNAME</code>.</p>
1.60 leot 475: <p>For example, <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/libXaw3d/README.html" target="_top"><code class="filename">x11/libXaw3d</code></a>
476: and <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/Xaw-Xpm/README.html" target="_top"><code class="filename">x11/Xaw-Xpm</code></a>
477: install the same shared library, thus you set in
478: <code class="filename">pkgsrc/x11/libXaw3d/Makefile</code>:</p>
479: <pre class="programlisting">
480: CONFLICTS= Xaw-Xpm-[0-9]*
481: </pre>
482: <p>and in <code class="filename">pkgsrc/x11/Xaw-Xpm/Makefile</code>:</p>
483: <pre class="programlisting">
484: CONFLICTS= libXaw3d-[0-9]*
485: </pre>
1.78 ! kim 486: <p><a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/pkg_add.1"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a> is able to detect attempts to install packages
1.60 leot 487: that conflict with existing packages and abort. However, in many
488: situations this is too late in the process. Binary package managers
489: will not know about the conflict until they attempt to install the
490: package after already downloading it and all its dependencies.
491: Users may also waste time building a package and its dependencies
492: only to find out at the end that it conflicts with another package
493: they have installed.</p>
494: <p>To avoid these issues <code class="varname">CONFLICTS</code> entries
495: should be added in all cases where it is known that packages conflict
496: with each other. These <code class="varname">CONFLICTS</code> entries are
1.78 ! kim 497: exported in <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/pkg_summary.5"><span class="citerefentry"><span class="refentrytitle">pkg_summary</span>(5)</span></a> files and consumed by binary package
1.60 leot 498: managers to inform users that packages cannot be installed onto
499: the target system.</p>
1.1 dsieger 500: </div>
1.24 asau 501: <div class="sect2">
1.1 dsieger 502: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 503: <a name="not-building-packages"></a>21.1.7. Packages that cannot or should not be built</h3></div></div></div>
1.1 dsieger 504: <p>There are several reasons why a package might be
505: instructed to not build under certain circumstances. If the
506: package builds and runs on most platforms, the exceptions
1.37 dholland 507: should be noted with <code class="varname">BROKEN_ON_PLATFORM</code>. If
508: the package builds and runs on a small handful of platforms,
509: set <code class="varname">BROKEN_EXCEPT_ON_PLATFORM</code> instead.
510: Both <code class="varname">BROKEN_ON_PLATFORM</code> and
511: <code class="varname">BROKEN_EXCEPT_ON_PLATFORM</code> are OS triples
512: (OS-version-platform) that can use glob-style
513: wildcards.</p>
514: <p>If a package is not appropriate for some platforms (as
1.55 maya 515: opposed to merely broken), a different set of variables should be
1.37 dholland 516: used as this affects failure reporting and statistics.
517: If the package is appropriate for most platforms, the exceptions
1.1 dsieger 518: should be noted with <code class="varname">NOT_FOR_PLATFORM</code>. If
1.37 dholland 519: the package is appropriate for only a small handful of platforms
520: (often exactly one), set <code class="varname">ONLY_FOR_PLATFORM</code> instead.
1.1 dsieger 521: Both <code class="varname">ONLY_FOR_PLATFORM</code> and
522: <code class="varname">NOT_FOR_PLATFORM</code> are OS triples
523: (OS-version-platform) that can use glob-style
524: wildcards.</p>
525: <p>Some packages are tightly bound to a specific version of an
1.59 leot 526: operating system, e.g. LKMs or <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/lsof/README.html" target="_top"><code class="filename">sysutils/lsof</code></a>. Such binary packages are not
1.1 dsieger 527: backwards compatible with other versions of the OS, and should be
528: uploaded to a version specific directory on the FTP server. Mark
529: these packages by setting <code class="varname">OSVERSION_SPECIFIC</code> to
1.15 wiz 530: <span class="quote">“<span class="quote">yes</span>”</span>. This variable is not currently used by any of
1.1 dsieger 531: the package system internals, but may be used in the
532: future.</p>
533: <p>If the package should be skipped (for example, because it
534: provides functionality already provided by the system), set
535: <code class="varname">PKG_SKIP_REASON</code> to a descriptive message. If
536: the package should fail because some preconditions are not met,
537: set <code class="varname">PKG_FAIL_REASON</code> to a descriptive
538: message.</p>
539: </div>
1.24 asau 540: <div class="sect2">
1.1 dsieger 541: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 542: <a name="undeletable-packages"></a>21.1.8. Packages which should not be deleted, once installed</h3></div></div></div>
1.1 dsieger 543: <p>To ensure that a package may not be deleted, once it has been
544: installed, the <code class="varname">PKG_PRESERVE</code> definition should
545: be set in the package Makefile. This will be carried into any
546: binary package that is made from this pkgsrc entry. A
1.15 wiz 547: <span class="quote">“<span class="quote">preserved</span>”</span> package will
1.78 ! kim 548: not be deleted using <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/pkg_delete.1"><span class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a> unless the
1.15 wiz 549: <span class="quote">“<span class="quote">-f</span>”</span> option is used.</p>
1.1 dsieger 550: </div>
1.24 asau 551: <div class="sect2">
1.1 dsieger 552: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 553: <a name="security-handling"></a>21.1.9. Handling packages with security problems</h3></div></div></div>
1.1 dsieger 554: <p>When a vulnerability is found, this should be noted in
555: <code class="filename">localsrc/security/advisories/pkg-vulnerabilities</code>,
1.19 wiz 556: and after committing that file, ask pkgsrc-security@NetBSD.org to
557: update the file on ftp.NetBSD.org.</p>
1.1 dsieger 558: <p>After fixing the vulnerability by a patch, its
1.19 wiz 559: <code class="varname">PKGREVISION</code> should be increased (this is of
560: course not necessary if the problem is fixed by using a newer
561: release of the software), and the pattern in the
562: pkg-vulnerabilities file must be updated.</p>
1.1 dsieger 563: <p>Also, if the fix should be applied to the stable pkgsrc
564: branch, be sure to submit a pullup request!</p>
565: <p>Binary packages already on ftp.NetBSD.org will be handled
566: semi-automatically by a weekly cron job.</p>
567: </div>
1.24 asau 568: <div class="sect2">
1.1 dsieger 569: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 570: <a name="bumping-pkgrevision"></a>21.1.10. How to handle incrementing versions when fixing an existing package</h3></div></div></div>
1.1 dsieger 571: <p>When making fixes to an existing package it can be useful
572: to change the version number in <code class="varname">PKGNAME</code>. To
573: avoid conflicting with future versions by the original author, a
1.15 wiz 574: <span class="quote">“<span class="quote">nb1</span>”</span>, <span class="quote">“<span class="quote">nb2</span>”</span>, ... suffix can be used
1.1 dsieger 575: on package versions by setting <code class="varname">PKGREVISION=1</code>
1.15 wiz 576: (2, ...). The <span class="quote">“<span class="quote">nb</span>”</span> is treated like a
577: <span class="quote">“<span class="quote">.</span>”</span> by the package tools. e.g.</p>
1.1 dsieger 578: <pre class="programlisting">
579: DISTNAME= foo-17.42
580: PKGREVISION= 9
1.52 sevan 581: </pre>
1.1 dsieger 582: <p>will result in a <code class="varname">PKGNAME</code> of
1.15 wiz 583: <span class="quote">“<span class="quote">foo-17.42nb9</span>”</span>. If you want to use the original
584: value of <code class="varname">PKGNAME</code> without the <span class="quote">“<span class="quote">nbX</span>”</span>
1.1 dsieger 585: suffix, e.g. for setting <code class="varname">DIST_SUBDIR</code>, use
586: <code class="varname">PKGNAME_NOREV</code>.</p>
587: <p>When a new release of the package is released, the
588: <code class="varname">PKGREVISION</code> should be removed, e.g. on a new
589: minor release of the above package, things should be like:</p>
590: <pre class="programlisting">
591: DISTNAME= foo-17.43
1.52 sevan 592: </pre>
1.1 dsieger 593: <p><code class="varname">PKGREVISION</code> should be incremented for any
594: non-trivial change in the resulting binary package. Without a
595: <code class="varname">PKGREVISION</code> bump, someone with the previous
596: version installed has no way of knowing that their package is out
597: of date. Thus, changes without increasing
598: <code class="varname">PKGREVISION</code> are essentially labeled "this is so
599: trivial that no reasonable person would want to upgrade", and this
600: is the rough test for when increasing
601: <code class="varname">PKGREVISION</code> is appropriate. Examples of
602: changes that do not merit increasing
603: <code class="varname">PKGREVISION</code> are:</p>
1.24 asau 604: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 605: <li class="listitem"><p>Changing <code class="varname">HOMEPAGE</code>,
1.68 rillig 606: <code class="varname">MAINTAINER</code>, <code class="varname">OWNER</code>, or
607: comments in Makefile.</p></li>
608: <li class="listitem"><p>Changing build variables if the resulting binary
609: package is the same.</p></li>
610: <li class="listitem"><p>Changing
611: <code class="filename">DESCR</code>.</p></li>
612: <li class="listitem"><p>Adding <code class="varname">PKG_OPTIONS</code> if the
613: default options don't change.</p></li>
1.1 dsieger 614: </ul></div>
615: <p>Examples of changes that do merit an increase to
616: <code class="varname">PKGREVISION</code> include:</p>
1.24 asau 617: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.68 rillig 618: <li class="listitem"><p>Security fixes</p></li>
619: <li class="listitem"><p>Changes or additions to a patch
620: file</p></li>
621: <li class="listitem"><p>Changes to the
622: <code class="filename">PLIST</code></p></li>
623: <li class="listitem"><p>A dependency is changed or
624: renamed.</p></li>
1.1 dsieger 625: </ul></div>
626: <p>PKGREVISION must also be incremented when dependencies have ABI
627: changes.</p>
628: </div>
1.24 asau 629: <div class="sect2">
1.1 dsieger 630: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 631: <a name="fixes.subst"></a>21.1.11. Substituting variable text in the package files (the SUBST framework)</h3></div></div></div>
1.73 rillig 632: <p>When you want to replace the same text in multiple files, or
633: multiple times in the same file, it is cumbersome to maintain a patch
634: file for this. This is where the SUBST framework steps in. It provides an
635: easy-to-use interface for replacing text in files. It just needs the
636: following information:</p>
1.69 rillig 637: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.73 rillig 638: <li class="listitem"><p>In which phase of the package build cycle should the
639: replacement happen?</p></li>
640: <li class="listitem"><p>In which files should the replacement
1.69 rillig 641: happen?</p></li>
1.73 rillig 642: <li class="listitem"><p>Which text should be replaced with
643: what?</p></li>
1.69 rillig 644: </ul></div>
645: <p>This information is encoded in a block of <code class="varname">SUBST</code>
1.73 rillig 646: variables. A minimal example is:</p>
1.1 dsieger 647: <pre class="programlisting">
1.73 rillig 648: SUBST_CLASSES+= paths
649: SUBST_STAGE.paths= pre-configure
650: SUBST_FILES.paths= src/*.c
651: SUBST_SED.paths= -e 's,/usr/local,${PREFIX},g'
652: </pre>
653: <p>Translated into English, it means: In the pre-configure stage (that
654: is, after applying the patches from the patches/ directory and before
655: running the configure script and the portability check), replace the text
656: <code class="literal">/usr/local</code> with the content of the variable
657: <code class="varname">PREFIX</code>.</p>
658: <p>Each SUBST block starts by appending an identifier to
659: <code class="varname">SUBST_CLASSES</code> (note the <code class="literal">+=</code>). This
660: identifier can be chosen freely by the package. If there should ever be
661: duplicate identifiers, the pkgsrc infrastructure will catch this and fail
662: early, so don't worry about name collisions.</p>
663: <p>Except for <code class="varname">SUBST_CLASSES</code>, all variables in a
664: SUBST block are parameterized using this identifier. In the remainder of
665: this section, these parameterized variables are written as
666: <code class="varname">SUBST_STAGE.*</code>.</p>
667: <pre class="programlisting">
668: SUBST_CLASSES+= paths
669: SUBST_STAGE.paths= pre-configure
670: SUBST_MESSAGE.paths= Fixing absolute paths.
671: SUBST_FILES.paths= src/*.c
672: SUBST_FILES.paths+= scripts/*.sh
673: SUBST_SED.paths= -e 's,"/usr/local,"${PREFIX},g'
674: SUBST_SED.paths+= -e 's,"/var/log,"${VARBASE}/log,g'
675: SUBST_VARS.paths= LOCALBASE PREFIX PKGVERSION
676: </pre>
677: <p>To get a complete picture about the SUBST substitutions, run
678: <span class="command"><strong>bmake show-all-subst</strong></span>. If something doesn't work as
679: expected, run pkglint on the package, which detects several typical
680: mistakes surrounding the SUBST blocks. For any questions that might
681: remain after this, have a look at
682: <code class="filename">mk/subst.mk</code>.</p>
683: <div class="sect3">
684: <div class="titlepage"><div><div><h4 class="title">
685: <a name="fixes.subst.when"></a>21.1.11.1. Choosing the time where the substitutions happen</h4></div></div></div>
686: <p>The <code class="varname">SUBST_STAGE.*</code> is one of
687: {pre,do,post}-{extract,patch,configure,build,test,install}. Of these,
688: <code class="literal">pre-configure</code> is used most often, by far. The most
689: popular stages are, in chronological order:</p>
690: <div class="variablelist"><dl class="variablelist">
691: <dt><span class="term"><code class="literal">post-extract</code></span></dt>
692: <dd>
693: <p>The substitutions are applied immediately after the
694: distfiles are extracted. Running <span class="command"><strong>bmake extract</strong></span> on the
695: package will leave no traces of the original files.</p>
696: <p>When the substitution applies to files for which there is also a
697: patch in the <code class="filename">patches/</code> directory, this means that the
698: patches will be computed based on the result of the substitution. When
699: these patches are sent to the upstream maintainer later, to be fixed in
700: the upstream package, these patches may no longer match what the upstream
701: author is used to. Because of this, <code class="literal">pre-configure</code> is
702: often a better choice.</p>
703: </dd>
704: <dt><span class="term"><code class="literal">pre-configure</code></span></dt>
705: <dd>
706: <p>The substitutions are applied after the patches from the
707: <code class="filename">patches/</code> directory. This makes it possible to run
708: <span class="command"><strong>bmake patch</strong></span> on the package, after which the patches
709: can be edited using the tools pkgvi and mkpatches from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html" target="_top"><code class="filename">pkgtools/pkgdiff</code></a> package.</p>
710: <p>When updating the patches, it is helpful to explicitly separate the
711: <span class="command"><strong>bmake patch</strong></span> from the <span class="command"><strong>bmake
712: configure</strong></span>, and to only edit the patches between these commands.
713: Otherwise the substitutions from the SUBST block will end up in the patch
714: file. When this happens in really obvious ways, pkglint will complain
715: about patches that contain a hard-coded <code class="literal">/usr/pkg</code>
716: instead of the correct and intended <code class="literal">@PREFIX@</code>, but it
717: can only detect these really obvious
718: cases.</p>
719: </dd>
720: <dt><span class="term"><code class="literal">do-configure</code></span></dt>
721: <dd><p>This stage should only be used if the package defines a
722: <code class="literal">pre-configure</code> action itself, and the substitution must
723: happen after that. Typical examples are packages that use the
724: <code class="literal">pre-configure</code> stage to regenerate the GNU configure
725: script from
726: <code class="filename">configure.ac</code>.</p></dd>
727: <dt><span class="term"><code class="literal">post-configure</code></span></dt>
728: <dd><p>This stage is used to fix up any mistakes by the
729: configure stage.</p></dd>
730: <dt><span class="term"><code class="literal">pre-build</code></span></dt>
731: <dd><p>This stage should only be used for substitutions that are
732: clearly related to building the package, not for fixing the
733: configuration. Substitutions for pathnames (such as replacing
734: <code class="filename">/usr/local</code> with <code class="literal">${PREFIX}</code>) or
735: user names (such as replacing <code class="literal">@MY_USER@</code> with the
736: actual username) belong in pre-configure or post-configure
737: instead.</p></dd>
738: <dt><span class="term"><code class="literal">post-build</code></span></dt>
739: <dd>
740: <p>Just as with pre-build, this stage should only be used
741: for substitutions that are clearly related to building the package, not
742: for fixing the configuration. Substitutions for pathnames (such as
743: replacing <code class="filename">/usr/local</code> with
744: <code class="literal">${PREFIX}</code>) or user names (such as replacing
745: <code class="literal">@MY_USER@</code> with the actual username) belong in
746: pre-configure or post-configure instead.</p>
747: <p>A typical use is to update pkg-config files to include the rpath
748: compiler options.</p>
749: </dd>
750: <dt><span class="term"><code class="literal">pre-install</code></span></dt>
751: <dd><p>In general, the install phase should be as simple as
752: possible. As with the pre-build and post-build stages, it should not be
753: used to fix pathnames or user names, these belong in pre-configure
754: instead. There are only few legitimate use cases for applying
755: substitutions in this stage.</p></dd>
756: </dl></div>
757: </div>
758: <div class="sect3">
759: <div class="titlepage"><div><div><h4 class="title">
1.74 rillig 760: <a name="fixes.subst.where"></a>21.1.11.2. Choosing the files where the substitutions happen</h4></div></div></div>
1.73 rillig 761: <p>The <code class="varname">SUBST_FILES.*</code> variable contains a list of
762: filename patterns. These patterns are relative to
763: <code class="varname">WRKSRC</code> since that is where most substitutions happen.
764: A typical example is:</p>
765: <pre class="programlisting">
766: SUBST_FILES.path= Makefile */Makefile */*/Makefile *.[ch]
767: </pre>
768: <p>The above patterns, especially the last, are quite broad. The SUBST
769: implementation checks that each filename pattern that is mentioned here
770: has an effect. For example, if none of the
771: <code class="filename">*/*/Makefile</code> files contains the patterns to be found
772: and substituted, that filename pattern is redundant and should be left
1.74 rillig 773: out. By default, the SUBST framework will complain with an error message.
774: If the text to be substituted occurs in some of the files from a single
775: pattern, but not in all of them, that is totally ok, and the SUBST
1.73 rillig 776: framework will only print an INFO message for those files.</p>
777: <p>If there is a good reason for having redundant filename patterns,
1.74 rillig 778: set <code class="varname">SUBST_NOOP_OK.*</code> to <code class="literal">yes</code>.</p>
1.73 rillig 779: <p>Another popular way of choosing the files for the substitutions is
780: via a shell command, like this:</p>
781: <pre class="programlisting">
1.74 rillig 782: C_FILES_CMD= cd ${WRKSRC} && ${FIND} . -name '*.c'
1.73 rillig 783: SUBST_FILES.path= ${C_FILES_CMD:sh}
784: </pre>
785: <p>The variable name <code class="varname">C_FILES_CMD</code> in this example is
786: freely chosen and independent of the SUBST framework.</p>
787: <p>In this variant, the <code class="varname">SUBST_FILES.*</code> variable
788: lists each file individually. Thereby chances are higher that there are
789: filename patterns in which no substitution happens. Since the SUBST
790: framework cannot know whether the filename patterns in
791: <code class="varname">SUBST_FILES.*</code> have been explicitly listed in the
792: Makefile (where any redundant filename pattern would be suspicious) or
793: been generated by a shell command (in which redundant filename patterns
794: are more likely and to be expected), it will complain about these
795: redundant filename patterns. Therefore, SUBST blocks that use a shell
796: command to generate the list of filename patterns often need to set
797: <code class="varname">SUBST_NOOP_OK.*</code> to <code class="literal">yes</code>.</p>
798: </div>
799: <div class="sect3">
800: <div class="titlepage"><div><div><h4 class="title">
801: <a name="fixes.subst.what"></a>21.1.11.3. Choosing what to substitute</h4></div></div></div>
802: <p>In most cases, the substitutions are given using one or more
1.78 ! kim 803: <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/sed.1"><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> commands, like this:</p>
1.73 rillig 804: <pre class="programlisting">
805: SUBST_SED.path= -e 's|/usr/local|${PREFIX}|g'
806: </pre>
807: <p>Each of the sed commands needs to be preceded by the
808: <code class="literal">-e</code> option and should be specified on a line of its
809: own, to avoid hiding short sed commands at the end of a line.</p>
810: <p>Since the sed commands often contain shell metacharacters as the
811: separator (the <code class="literal">|</code> in the above example), it is common
812: to enclose them in single quotes.</p>
813: <p>A common substitution is to replace placeholders of the form
814: <code class="literal">@VARNAME@</code> with their pkgsrc counterpart variable
815: <code class="literal">${VARNAME}</code>. A typical example is:</p>
816: <pre class="programlisting">
817: SUBST_VARS.path= PREFIX
818: </pre>
819: <p>This type of substitutions is typically done by the GNU configure
1.74 rillig 820: scripts during the do-configure stage, but in some cases these need to be
821: overridden. The same pattern is also used when a package defines patches
822: that replace previously hard-coded paths like
823: <code class="literal">/usr/local</code> with a <code class="literal">@PREFIX@</code>
824: placeholder first, which then gets substituted by the actual
825: <code class="literal">${PREFIX}</code> in the pre-configure stage. In many of these
826: cases, it works equally well to just use the SUBST framework to directly
827: replace <code class="literal">/usr/local</code> with <code class="literal">${PREFIX}</code>,
828: thereby omitting the intermediate patch file.</p>
1.73 rillig 829: <p>If the above is not flexible enough, it is possible to not use sed
830: at all for the substitution but to specify an entirely different command,
831: like this:</p>
832: <pre class="programlisting">
833: SUBST_FILTER_CMD.path= LC_ALL=C ${TR} -d '\r'
834: </pre>
835: <p>This is used for the few remaining packages in which the
836: distributed files use Windows-style line endings that need to be
837: converted to UNIX-style line endings.</p>
838: </div>
839: <div class="sect3">
840: <div class="titlepage"><div><div><h4 class="title">
841: <a name="fixes.subst.other"></a>21.1.11.4. Other SUBST variables</h4></div></div></div>
842: <p>When a SUBST block is applied during a package build, a message is
843: logged. The default message is fine for most purposes but can be
844: overridden by setting <code class="literal">SUBST_MESSAGE.*</code> to an individual
845: message.</p>
846: </div>
1.1 dsieger 847: </div>
848: </div>
1.24 asau 849: <div class="sect1">
1.1 dsieger 850: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 851: <a name="fixes.fetch"></a>21.2. The <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
1.24 asau 852: <div class="sect2">
1.1 dsieger 853: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 854: <a name="no-plain-download"></a>21.2.1. Packages whose distfiles aren't available for plain downloading</h3></div></div></div>
1.1 dsieger 855: <p>If you need to download from a dynamic URL you can set
1.7 hubertf 856: <code class="varname">DYNAMIC_MASTER_SITES</code> and a <span class="command"><strong>make
1.1 dsieger 857: fetch</strong></span> will call <code class="filename">files/getsite.sh</code>
858: with the name of each file to download as an argument, expecting
859: it to output the URL of the directory from which to download
1.59 leot 860: it. <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/graphics/ns-cult3d/README.html" target="_top"><code class="filename">graphics/ns-cult3d</code></a> is an
1.1 dsieger 861: example of this usage.</p>
862: <p>If the download can't be automated, because the user must
863: submit personal information to apply for a password, or must pay
864: for the source, or whatever, you can set
865: <code class="varname">FETCH_MESSAGE</code> to a list of lines that are
866: displayed to the user before aborting the build. Example:</p>
867: <pre class="programlisting">
868: FETCH_MESSAGE= "Please download the files"
869: FETCH_MESSAGE+= " "${DISTFILES:Q}
870: FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
1.52 sevan 871: </pre>
1.1 dsieger 872: </div>
1.24 asau 873: <div class="sect2">
1.1 dsieger 874: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 875: <a name="modified-distfiles-same-name"></a>21.2.2. How to handle modified distfiles with the 'old' name</h3></div></div></div>
1.1 dsieger 876: <p>Sometimes authors of a software package make some
877: modifications after the software was released, and they put up a
878: new distfile without changing the package's version number. If a
879: package is already in pkgsrc at that time, the checksum will
880: no longer match. The contents of the new distfile should be
881: compared against the old one before changing anything, to make
882: sure the distfile was really updated on purpose, and that
883: no trojan horse or so crept in.
884: Please mention that the distfiles were compared and what was found
1.29 rodent 885: in your commit message.</p>
1.51 wiz 886: <p>Then, the correct way to work around this is to set
887: <code class="varname">DIST_SUBDIR</code> to a unique directory name, usually
888: based on <code class="varname">PKGNAME_NOREV</code> (but take care with
889: python or ruby packages, where <code class="varname">PKGNAME</code> includes
890: a variable prefix). All <code class="varname">DISTFILES</code> and
1.1 dsieger 891: <code class="varname">PATCHFILES</code> for this package will be put in that
1.63 rillig 892: subdirectory of the local distfiles directory. (See <a class="xref" href="fixes.html#bumping-pkgrevision" title="21.1.10. How to handle incrementing versions when fixing an existing package">Section 21.1.10, “How to handle incrementing versions when fixing an existing package”</a> for more details.) In case this
1.1 dsieger 893: happens more often, <code class="varname">PKGNAME</code> can be used (thus
1.51 wiz 894: including the <code class="filename">nbX</code> suffix) or a date stamp can
895: be appended, like
896: <code class="varname">${PKGNAME_NOREV}-YYYYMMDD</code>.</p>
1.68 rillig 897: <p><code class="varname">DIST_SUBDIR</code> is also used when a distfile's
898: name does not contain a version and the distfile is apt to change. In
899: cases where the likelihood of this is very small,
900: <code class="varname">DIST_SUBDIR</code> might not be required. Additionally,
901: <code class="varname">DIST_SUBDIR</code> must not be removed unless the
902: distfile name changes, even if a package is being moved or
903: renamed.</p>
1.29 rodent 904: <p>Do not forget regenerating the <code class="filename">distinfo</code> file
1.1 dsieger 905: after that, since it contains the <code class="varname">DIST_SUBDIR</code>
906: path in the filenames.
1.29 rodent 907: Also, increase the PKGREVISION if the installed package is different.
1.1 dsieger 908: Furthermore, a mail to the package's authors seems appropriate
909: telling them that changing distfiles after releases without
910: changing the file names is not good practice.</p>
911: </div>
1.40 tnn 912: <div class="sect2">
913: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 914: <a name="build.fetch.github"></a>21.2.3. Packages hosted on github.com</h3></div></div></div>
1.68 rillig 915: <p>Helper methods exist for packages hosted on github.com which
916: will often have distfile names that clash with other packages, for
917: example <code class="filename">1.0.tar.gz</code>. Use one of the three recipes
918: from below:</p>
1.40 tnn 919: <div class="sect3">
920: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 921: <a name="build.fetch.github.tag"></a>21.2.3.1. Fetch based on a tagged release</h4></div></div></div>
1.68 rillig 922: <p>If your distfile URL looks similar to
1.77 bacon 923: <code class="literal">https://github.com/username/example/archive/v1.0.zip</code>,
1.68 rillig 924: then you are packaging a tagged release.</p>
1.40 tnn 925: <pre class="programlisting">
1.77 bacon 926: DISTNAME= example-1.0
1.41 tnn 927: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1.77 bacon 928: #GITHUB_PROJECT= example # can be omitted if same as DISTNAME
1.41 tnn 929: GITHUB_TAG= v${PKGVERSION_NOREV}
1.40 tnn 930: EXTRACT_SUFX= .zip
931: </pre>
932: </div>
933: <div class="sect3">
934: <div class="titlepage"><div><div><h4 class="title">
1.77 bacon 935: <a name="build.fetch.github.commit.prerelease"></a>21.2.3.2. Fetch based on a specific commit before the first release</h4></div></div></div>
936: <p>If your distfile looks similar to
937: <code class="literal">https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</code> and is from a commit before the first
938: release, then set the package version to 0.0.0.N, where N is the number
939: of commits to the repository, and set GITHUB_TAG to the commit hash.
940: This will (almost) ensure that the first tagged release will have a
941: version greater than this one so that package upgrades will function
942: properly.</p>
943: <pre class="programlisting">
944: DISTNAME= example-0.0.0.347
945: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
946: #GITHUB_PROJECT= example # can be omitted if same as DISTNAME
947: GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
948: </pre>
949: </div>
950: <div class="sect3">
951: <div class="titlepage"><div><div><h4 class="title">
952: <a name="build.fetch.github.commit.postrelease"></a>21.2.3.3. Fetch based on a specific commit after a release</h4></div></div></div>
953: <p>If your distfile looks similar to
954: <code class="literal">https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</code> and is from a commit after a release,
955: then include the last release version and the commit count since that
956: release in the package version and set GITHUB_TAG to the commit hash.
957: The latest release and commit count are shown in the output of
958: "git describe --tags":
959: </p>
960: <pre class="screen">
961: # git clone https://github.com/username/example
962: # cd example
963: # git describe --tags
964: 1.2.3-5-g988881a
965: </pre>
1.40 tnn 966: <pre class="programlisting">
1.77 bacon 967: DISTNAME= example-1.2.3.5
968: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
969: #GITHUB_PROJECT= example # can be omitted if same as DISTNAME
1.41 tnn 970: GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
1.52 sevan 971: </pre>
1.40 tnn 972: </div>
973: <div class="sect3">
974: <div class="titlepage"><div><div><h4 class="title">
1.77 bacon 975: <a name="build.fetch.github.release"></a>21.2.3.4. Fetch based on release</h4></div></div></div>
1.68 rillig 976: <p>If your distfile URL looks similar to
1.77 bacon 977: <code class="literal">https://github.com/username/example/releases/download/rel-1.6/offensive-1.6.zip</code>,
1.68 rillig 978: then you are packaging a release.</p>
1.40 tnn 979: <pre class="programlisting">
980: DISTNAME= offensive-1.6
1.41 tnn 981: PKGNAME= ${DISTNAME:S/offensive/proper/}
982: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1.77 bacon 983: GITHUB_PROJECT= example
1.41 tnn 984: GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME}
985: EXTRACT_SUFX= .zip
1.52 sevan 986: </pre>
1.40 tnn 987: </div>
988: </div>
1.1 dsieger 989: </div>
1.24 asau 990: <div class="sect1">
1.1 dsieger 991: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 992: <a name="fixes.configure"></a>21.3. The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
1.24 asau 993: <div class="sect2">
1.1 dsieger 994: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 995: <a name="fixes.libtool"></a>21.3.1. Shared libraries - libtool</h3></div></div></div>
1.1 dsieger 996: <p>pkgsrc supports many different machines, with different
997: object formats like a.out and ELF, and varying abilities to do
998: shared library and dynamic loading at all. To accompany this,
999: varying commands and options have to be passed to the
1000: compiler, linker, etc. to get the Right Thing, which can be
1001: pretty annoying especially if you don't have all the machines
1002: at your hand to test things. The
1.59 leot 1003: <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/libtool/README.html" target="_top"><code class="filename">devel/libtool</code></a> pkg
1.15 wiz 1004: can help here, as it just <span class="quote">“<span class="quote">knows</span>”</span> how to build
1.1 dsieger 1005: both static and dynamic libraries from a set of source files,
1006: thus being platform-independent.</p>
1007: <p>Here's how to use libtool in a package in seven simple
1008: steps:</p>
1.15 wiz 1009: <div class="orderedlist"><ol class="orderedlist" type="1">
1010: <li class="listitem"><p>Add <code class="varname">USE_LIBTOOL=yes</code> to the package
1.1 dsieger 1011: Makefile.</p></li>
1.15 wiz 1012: <li class="listitem"><p>For library objects, use <span class="quote">“<span class="quote">${LIBTOOL} --mode=compile
1013: ${CC}</span>”</span> in place of <span class="quote">“<span class="quote">${CC}</span>”</span>. You could even
1.1 dsieger 1014: add it to the definition of <code class="varname">CC</code>, if only
1015: libraries are being built in a given Makefile. This one command
1016: will build both PIC and non-PIC library objects, so you need not
1017: have separate shared and non-shared library rules.</p></li>
1.15 wiz 1018: <li class="listitem">
1.1 dsieger 1019: <p>For the linking of the library, remove any
1.15 wiz 1020: <span class="quote">“<span class="quote">ar</span>”</span>, <span class="quote">“<span class="quote">ranlib</span>”</span>, and <span class="quote">“<span class="quote">ld
1021: -Bshareable</span>”</span> commands, and instead use:</p>
1.1 dsieger 1022: <pre class="programlisting">
1023: ${LIBTOOL} --mode=link \
1024: ${CC} -o ${.TARGET:.a=.la} \
1025: ${OBJS:.o=.lo} \
1026: -rpath ${PREFIX}/lib \
1027: -version-info major:minor
1.52 sevan 1028: </pre>
1.1 dsieger 1029: <p>Note that the library is changed to have a
1030: <code class="filename">.la</code> extension, and the objects are
1031: changed to have a <code class="filename">.lo</code>
1032: extension. Change <code class="varname">OBJS</code> as
1033: necessary. This automatically creates all of the
1034: <code class="filename">.a</code>,
1035: <code class="filename">.so.major.minor</code>, and ELF symlinks (if
1036: necessary) in the build directory. Be sure to include
1.15 wiz 1037: <span class="quote">“<span class="quote">-version-info</span>”</span>, especially when major and
1.1 dsieger 1038: minor are zero, as libtool will otherwise strip off the
1039: shared library version.</p>
1040: <p>From the libtool manual:</p>
1041: <pre class="programlisting">
1042: So, libtool library versions are described by three integers:
1043:
1044: CURRENT
1045: The most recent interface number that this library implements.
1046:
1047: REVISION
1048: The implementation number of the CURRENT interface.
1049:
1050: AGE
1051: The difference between the newest and oldest interfaces that
1052: this library implements. In other words, the library implements
1053: all the interface numbers in the range from number `CURRENT -
1054: AGE' to `CURRENT'.
1055:
1056: If two libraries have identical CURRENT and AGE numbers, then the
1057: dynamic linker chooses the library with the greater REVISION number.
1.52 sevan 1058: </pre>
1.15 wiz 1059: <p>The <span class="quote">“<span class="quote">-release</span>”</span> option will produce
1.1 dsieger 1060: different results for a.out and ELF (excluding symlinks)
1061: in only one case. An ELF library of the form
1.15 wiz 1062: <span class="quote">“<span class="quote">libfoo-release.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”</span>
1.1 dsieger 1063: will have a symlink of
1.15 wiz 1064: <span class="quote">“<span class="quote">libfoo.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”</span>
1.1 dsieger 1065: on an a.out platform. This is handled
1066: automatically.</p>
1.15 wiz 1067: <p>The <span class="quote">“<span class="quote">-rpath argument</span>”</span> is the install
1.1 dsieger 1068: directory of the library being built.</p>
1069: <p>In the <code class="filename">PLIST</code>, include only the
1070: <code class="filename">.la</code> file, the other files will be
1071: added automatically.</p>
1072: </li>
1.15 wiz 1073: <li class="listitem">
1.1 dsieger 1074: <p>When linking shared object (<code class="filename">.so</code>)
1.78 ! kim 1075: files, i.e. files that are loaded via <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/dlopen.3"><span class="citerefentry"><span class="refentrytitle">dlopen</span>(3)</span></a>, NOT
1.15 wiz 1076: shared libraries, use <span class="quote">“<span class="quote">-module
1077: -avoid-version</span>”</span> to prevent them getting version
1.1 dsieger 1078: tacked on.</p>
1079: <p>The <code class="filename">PLIST</code> file gets the
1080: <code class="filename">foo.so</code> entry.</p>
1081: </li>
1.15 wiz 1082: <li class="listitem">
1.1 dsieger 1083: <p>When linking programs that depend on these libraries
1084: <span class="emphasis"><em>before</em></span> they are installed, preface
1.78 ! kim 1085: the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/cc.1"><span class="citerefentry"><span class="refentrytitle">cc</span>(1)</span></a> or <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/ld.1"><span class="citerefentry"><span class="refentrytitle">ld</span>(1)</span></a> line with <span class="quote">“<span class="quote">${LIBTOOL}
1.15 wiz 1086: --mode=link</span>”</span>, and it will find the correct
1.1 dsieger 1087: libraries (static or shared), but please be aware that
1088: libtool will not allow you to specify a relative path in
1.15 wiz 1089: -L (such as <span class="quote">“<span class="quote">-L../somelib</span>”</span>), because it
1.1 dsieger 1090: expects you to change that argument to be the
1091: <code class="filename">.la</code> file. e.g.</p>
1092: <pre class="programlisting">
1093: ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
1.52 sevan 1094: </pre>
1.1 dsieger 1095: <p>should be changed to:</p>
1096: <pre class="programlisting">
1097: ${LIBTOOL} --mode=link ${CC} -o <em class="replaceable"><code>someprog</code></em> <em class="replaceable"><code>../somelib/somelib.la</code></em>
1.52 sevan 1098: </pre>
1.1 dsieger 1099: <p>and it will do the right thing with the libraries.</p>
1100: </li>
1.15 wiz 1101: <li class="listitem">
1.78 ! kim 1102: <p>When installing libraries, preface the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/install.1"><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a>
! 1103: or <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/cp.1"><span class="citerefentry"><span class="refentrytitle">cp</span>(1)</span></a> command with <span class="quote">“<span class="quote">${LIBTOOL}
1.15 wiz 1104: --mode=install</span>”</span>, and change the library name to
1.1 dsieger 1105: <code class="filename">.la</code>. e.g.</p>
1106: <pre class="programlisting">
1.14 jakllsch 1107: ${LIBTOOL} --mode=install ${BSD_INSTALL_LIB} ${SOMELIB:.a=.la} ${PREFIX}/lib
1.52 sevan 1108: </pre>
1.1 dsieger 1109: <p>This will install the static <code class="filename">.a</code>,
1110: shared library, any needed symlinks, and run
1.78 ! kim 1111: <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.0/i386/ldconfig.8"><span class="citerefentry"><span class="refentrytitle">ldconfig</span>(8)</span></a>.</p>
1.1 dsieger 1112: </li>
1.15 wiz 1113: <li class="listitem"><p>In your <code class="filename">PLIST</code>, include only
1.1 dsieger 1114: the <code class="filename">.la</code>
1115: file (this is a change from previous behaviour).</p></li>
1116: </ol></div>
1117: </div>
1.24 asau 1118: <div class="sect2">
1.1 dsieger 1119: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1120: <a name="using-libtool"></a>21.3.2. Using libtool on GNU packages that already support libtool</h3></div></div></div>
1.1 dsieger 1121: <p>Add <code class="varname">USE_LIBTOOL=yes</code> to the
1122: package Makefile. This will override the package's own libtool
1123: in most cases. For older libtool using packages, libtool is
1124: made by ltconfig script during the do-configure step; you can
1.7 hubertf 1125: check the libtool script location by doing <span class="command"><strong>make
1.1 dsieger 1126: configure; find work*/ -name libtool</strong></span>.</p>
1127: <p><code class="varname">LIBTOOL_OVERRIDE</code> specifies which libtool
1128: scripts, relative to <code class="varname">WRKSRC</code>, to override. By
1.15 wiz 1129: default, it is set to <span class="quote">“<span class="quote">libtool */libtool
1130: */*/libtool</span>”</span>. If this does not match the location of the
1.1 dsieger 1131: package's libtool script(s), set it as appropriate.</p>
1132: <p>If you do not need <code class="filename">*.a</code> static
1133: libraries built and installed, then use
1134: <code class="varname">SHLIBTOOL_OVERRIDE</code> instead.</p>
1135: <p>If your package makes use of the platform-independent library
1136: for loading dynamic shared objects, that comes with libtool
1137: (libltdl), you should include devel/libltdl/buildlink3.mk.</p>
1138: <p>Some packages use libtool incorrectly so that the package
1139: may not work or build in some circumstances. Some of the more
1140: common errors are:</p>
1.24 asau 1141: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1142: <li class="listitem">
1.1 dsieger 1143: <p>The inclusion of a shared object (-module) as a dependent library in an
1144: executable or library. This in itself isn't a problem if one of two things
1145: has been done:</p>
1.15 wiz 1146: <div class="orderedlist"><ol class="orderedlist" type="1">
1147: <li class="listitem"><p>The shared object is named correctly, i.e.
1.1 dsieger 1148: <code class="filename">libfoo.la</code>, not
1149: <code class="filename">foo.la</code></p></li>
1.15 wiz 1150: <li class="listitem"><p>The -dlopen option is used when linking an executable.</p></li>
1.1 dsieger 1151: </ol></div>
1152: </li>
1.15 wiz 1153: <li class="listitem"><p>The use of libltdl without the correct calls to initialisation routines.
1.1 dsieger 1154: The function lt_dlinit() should be called and the macro
1155: <code class="varname">LTDL_SET_PRELOADED_SYMBOLS</code> included in
1156: executables.</p></li>
1157: </ul></div>
1158: </div>
1.24 asau 1159: <div class="sect2">
1.1 dsieger 1160: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1161: <a name="autoconf-automake"></a>21.3.3. GNU Autoconf/Automake</h3></div></div></div>
1.1 dsieger 1162: <p>If a package needs GNU autoconf or automake to be executed
1163: to regenerate the configure script and Makefile.in makefile
1164: templates, then they should be executed in a pre-configure
1165: target.</p>
1166: <p>For packages that need only autoconf:</p>
1167: <pre class="programlisting">
1168: AUTOCONF_REQD= 2.50 # if default version is not good enough
1169: USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
1170: ...
1171:
1172: pre-configure:
1173: cd ${WRKSRC} && autoconf
1174:
1175: ...
1.52 sevan 1176: </pre>
1.1 dsieger 1177: <p>and for packages that need automake and autoconf:</p>
1178: <pre class="programlisting">
1179: AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
1180: USE_TOOLS+= automake # use "automake14" for automake-1.4
1181: ...
1182:
1183: pre-configure:
1184: set -e; cd ${WRKSRC}; \
1185: aclocal; autoheader; automake -a --foreign -i; autoconf
1186:
1187: ...
1.52 sevan 1188: </pre>
1.1 dsieger 1189: <p>Packages which use GNU Automake will almost certainly
1190: require GNU Make.</p>
1191: <p>There are times when the configure process makes
1192: additional changes to the generated files, which then causes
1193: the build process to try to re-execute the automake sequence.
1194: This is prevented by touching various files in the configure
1195: stage. If this causes problems with your package you can set
1196: <code class="varname">AUTOMAKE_OVERRIDE=NO</code> in the package
1197: Makefile.</p>
1198: </div>
1199: </div>
1.24 asau 1200: <div class="sect1">
1.1 dsieger 1201: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1202: <a name="programming-languages"></a>21.4. Programming languages</h2></div></div></div>
1.24 asau 1203: <div class="sect2">
1.1 dsieger 1204: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1205: <a name="basic-programming-languages"></a>21.4.1. C, C++, and Fortran</h3></div></div></div>
1.1 dsieger 1206: <p>Compilers for the C, C++, and Fortran languages comes with
1207: the NetBSD base system. By default, pkgsrc assumes that a package
1208: is written in C and will hide all other compilers (via the wrapper
1.76 rillig 1209: framework, see <a class="xref" href="buildlink.html" title="Chapter 18. Buildlink methodology">Chapter 18, <i>Buildlink methodology</i></a>).</p>
1.1 dsieger 1210: <p>To declare which language's compiler a package needs, set
1211: the <code class="varname">USE_LANGUAGES</code> variable. Allowed values
1.15 wiz 1212: currently are <span class="quote">“<span class="quote">c</span>”</span>, <span class="quote">“<span class="quote">c++</span>”</span>, and
1213: <span class="quote">“<span class="quote">fortran</span>”</span> (and any combination). The default is
1214: <span class="quote">“<span class="quote">c</span>”</span>. Packages using GNU configure scripts, even if
1.1 dsieger 1215: written in C++, usually need a C compiler for the configure
1216: phase.</p>
1217: </div>
1.24 asau 1218: <div class="sect2">
1.1 dsieger 1219: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1220: <a name="java-programming-language"></a>21.4.2. Java</h3></div></div></div>
1.1 dsieger 1221: <p>If a program is written in Java, use the Java framework in
1222: pkgsrc. The package must include
1223: <code class="filename">../../mk/java-vm.mk</code>. This Makefile fragment
1224: provides the following variables:</p>
1.24 asau 1225: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1226: <li class="listitem"><p><code class="varname">USE_JAVA</code> defines if a build
1.1 dsieger 1227: dependency on the JDK is added. If
1.15 wiz 1228: <code class="varname">USE_JAVA</code> is set to <span class="quote">“<span class="quote">run</span>”</span>, then
1.1 dsieger 1229: there is only a runtime dependency on the JDK. The default is
1.15 wiz 1230: <span class="quote">“<span class="quote">yes</span>”</span>, which also adds a build dependency on the
1.1 dsieger 1231: JDK.</p></li>
1.15 wiz 1232: <li class="listitem"><p>Set <code class="varname">USE_JAVA2</code> to declare that
1.1 dsieger 1233: a package needs a Java2 implementation. The supported values
1.15 wiz 1234: are <span class="quote">“<span class="quote">yes</span>”</span>, <span class="quote">“<span class="quote">1.4</span>”</span>, and
1235: <span class="quote">“<span class="quote">1.5</span>”</span>. <span class="quote">“<span class="quote">yes</span>”</span> accepts any Java2
1236: implementation, <span class="quote">“<span class="quote">1.4</span>”</span> insists on versions 1.4 or
1237: above, and <span class="quote">“<span class="quote">1.5</span>”</span> only accepts versions 1.5 or
1.1 dsieger 1238: above. This variable is not set by default.</p></li>
1.16 wiz 1239: <li class="listitem"><p><code class="varname">PKG_JAVA_HOME</code> is
1240: automatically set to the runtime location of the used Java
1241: implementation dependency. It may be used to set
1242: <code class="varname">JAVA_HOME</code> to a good value if the program
1243: needs this variable to be defined.
1244: </p></li>
1.1 dsieger 1245: </ul></div>
1246: </div>
1.24 asau 1247: <div class="sect2">
1.1 dsieger 1248: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1249: <a name="perl-scripts"></a>21.4.3. Packages containing perl scripts</h3></div></div></div>
1.1 dsieger 1250: <p>If your package contains interpreted perl scripts, add
1.15 wiz 1251: <span class="quote">“<span class="quote">perl</span>”</span> to the <code class="varname">USE_TOOLS</code> variable
1.1 dsieger 1252: and set <code class="varname">REPLACE_PERL</code> to ensure that the proper
1253: interpreter path is set. <code class="varname">REPLACE_PERL</code> should
1254: contain a list of scripts, relative to <code class="varname">WRKSRC</code>,
1.34 wiz 1255: that you want adjusted. Every occurrence of
1256: <code class="filename">*/bin/perl</code> in a she-bang line will be
1257: replaced with the full path to the perl executable.</p>
1.1 dsieger 1258: <p>If a particular version of perl is needed, set the
1259: <code class="varname">PERL5_REQD</code> variable to the version number. The
1.15 wiz 1260: default is <span class="quote">“<span class="quote">5.0</span>”</span>.</p>
1.63 rillig 1261: <p>See <a class="xref" href="fixes.html#perl-modules" title="21.6.6. Packages installing perl modules">Section 21.6.6, “Packages installing perl modules”</a> for information
1.1 dsieger 1262: about handling perl modules.</p>
1263: </div>
1.24 asau 1264: <div class="sect2">
1.1 dsieger 1265: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1266: <a name="shell-scripts"></a>21.4.4. Packages containing shell scripts</h3></div></div></div>
1.23 wiz 1267: <p><code class="varname">REPLACE_SH</code>,
1268: <code class="varname">REPLACE_BASH</code>, <code class="varname">REPLACE_CSH</code>,
1269: and <code class="varname">REPLACE_KSH</code> can be used to replace shell
1270: hash bangs in files. Please use the appropriate one, prefering
1271: <code class="varname">REPLACE_SH</code> in case this shell is sufficient.
1.34 wiz 1272: Each should contain a list of scripts, relative to
1273: <code class="varname">WRKSRC</code>, that you want adjusted. Every
1274: occurrence of the matching shell in a she-bang line will be
1275: replaced with the full path to the shell executable.
1.23 wiz 1276: When using <code class="varname">REPLACE_BASH</code>, don't forget to add
1277: <code class="filename">bash</code> to <code class="varname">USE_TOOLS</code>.</p>
1278: </div>
1.24 asau 1279: <div class="sect2">
1.23 wiz 1280: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1281: <a name="other-programming-languages"></a>21.4.5. Other programming languages</h3></div></div></div>
1.1 dsieger 1282: <p>Currently, there is no special handling for other languages
1283: in pkgsrc. If a compiler package provides a
1284: <code class="filename">buildlink3.mk</code> file, include that, otherwise
1285: just add a (build) dependency on the appropriate compiler
1286: package.</p>
1287: </div>
1288: </div>
1.24 asau 1289: <div class="sect1">
1.1 dsieger 1290: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1291: <a name="fixes.build"></a>21.5. The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
1.1 dsieger 1292: <p>The most common failures when building a package are that
1293: some platforms do not provide certain header files, functions or
1294: libraries, or they provide the functions in a library that the
1295: original package author didn't know. To work around this, you
1296: can rewrite the source code in most cases so that it does not
1297: use the missing functions or provides a replacement function.</p>
1.24 asau 1298: <div class="sect2">
1.1 dsieger 1299: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1300: <a name="fixes.build.cpp"></a>21.5.1. Compiling C and C++ code conditionally</h3></div></div></div>
1.1 dsieger 1301: <p>If a package already comes with a GNU configure script, the
1302: preferred way to fix the build failure is to change the
1303: configure script, not the code. In the other cases, you can
1304: utilize the C preprocessor, which defines certain macros
1305: depending on the operating system and hardware architecture it
1306: compiles for. These macros can be queried using for example
1307: <code class="varname">#if defined(__i386)</code>. Almost every operating
1308: system, hardware architecture and compiler has its own macro.
1309: For example, if the macros <code class="varname">__GNUC__</code>,
1310: <code class="varname">__i386__</code> and <code class="varname">__NetBSD__</code>
1311: are all defined, you know that you are using NetBSD on an i386
1312: compatible CPU, and your compiler is GCC.</p>
1313: <p>The list of the following macros for hardware and
1314: operating system depends on the compiler that is used. For
1315: example, if you want to conditionally compile code on Solaris,
1316: don't use <code class="varname">__sun__</code>, as the SunPro compiler
1317: does not define it. Use <code class="varname">__sun</code> instead.</p>
1.24 asau 1318: <div class="sect3">
1.1 dsieger 1319: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1320: <a name="fixes.build.cpp.os"></a>21.5.1.1. C preprocessor macros to identify the operating system</h4></div></div></div>
1.1 dsieger 1321: <p>To distinguish between 4.4 BSD-derived systems and the
1322: rest of the world, you should use the following code.</p>
1323: <pre class="programlisting">
1324: #include <sys/param.h>
1325: #if (defined(BSD) && BSD >= 199306)
1326: /* BSD-specific code goes here */
1327: #else
1328: /* non-BSD-specific code goes here */
1329: #endif
1330: </pre>
1331: <p>If this distinction is not fine enough, you can also test
1332: for the following macros.</p>
1333: <pre class="programlisting">
1.25 obache 1334: Cygwin __CYGWIN__
1335: DragonFly __DragonFly__
1.1 dsieger 1336: FreeBSD __FreeBSD__
1.25 obache 1337: Haiku __HAIKU__
1.1 dsieger 1338: Interix __INTERIX
1339: IRIX __sgi (TODO: get a definite source for this)
1340: Linux linux, __linux, __linux__
1.37 dholland 1341: Mac OS X __APPLE__
1.25 obache 1342: MirBSD __MirBSD__ (__OpenBSD__ is also defined)
1343: Minix3 __minix
1.1 dsieger 1344: NetBSD __NetBSD__
1345: OpenBSD __OpenBSD__
1346: Solaris sun, __sun
1347: </pre>
1348: </div>
1.24 asau 1349: <div class="sect3">
1.1 dsieger 1350: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1351: <a name="fixes.build.cpp.arch"></a>21.5.1.2. C preprocessor macros to identify the hardware architecture</h4></div></div></div>
1.1 dsieger 1352: <pre class="programlisting">
1353: i386 i386, __i386, __i386__
1354: MIPS __mips
1355: SPARC sparc, __sparc
1356: </pre>
1357: </div>
1.24 asau 1358: <div class="sect3">
1.1 dsieger 1359: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1360: <a name="fixes.build.cpp.compiler"></a>21.5.1.3. C preprocessor macros to identify the compiler</h4></div></div></div>
1.1 dsieger 1361: <pre class="programlisting">
1362: GCC __GNUC__ (major version), __GNUC_MINOR__
1363: MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41)
1364: SunPro __SUNPRO_C (0x570 for Sun C 5.7)
1365: SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8)
1366: </pre>
1367: </div>
1368: </div>
1.24 asau 1369: <div class="sect2">
1.1 dsieger 1370: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1371: <a name="compiler-bugs"></a>21.5.2. How to handle compiler bugs</h3></div></div></div>
1.1 dsieger 1372: <p>Some source files trigger bugs in the compiler, based on
1373: combinations of compiler version and architecture and almost
1374: always relation to optimisation being enabled. Common symptoms
1375: are gcc internal errors or never finishing compiling a
1376: file.</p>
1377: <p>Typically, a workaround involves testing the
1378: <code class="varname">MACHINE_ARCH</code> and compiler version, disabling
1379: optimisation for that combination of file,
1.39 tnn 1380: <code class="varname">MACHINE_ARCH</code> and compiler.</p>
1381: <p>This used to be a big problem in the past, but is rarely
1382: needed now as compiler technology has matured. If you still need
1383: to add a compiler specific workaround, please do so in the file
1384: <code class="filename">hacks.mk</code> and describe the symptom and
1385: compiler version as detailed as possible.</p>
1.1 dsieger 1386: </div>
1.24 asau 1387: <div class="sect2">
1.1 dsieger 1388: <div class="titlepage"><div><div><h3 class="title">
1.69 rillig 1389: <a name="fixes.build.header"></a>21.5.3. No such file or directory</h3></div></div></div>
1390: <p>Compilation sometimes fails with an error message like this:</p>
1391: <pre class="programlisting">
1392: .../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
1393: fatal error: pango/pango.h: No such file or directory
1394: </pre>
1395: <p>The proper way to fix this problem depends on the type of the
1396: header, which is described in the following sections.</p>
1397: <div class="sect3">
1398: <div class="titlepage"><div><div><h4 class="title">
1399: <a name="fixes.build.header.bl3"></a>21.5.3.1. Headers from other packages</h4></div></div></div>
1400: <p>If the header name looks like it comes from a different package,
1401: that other package should be included via the buildlink3
1402: framework.</p>
1403: <p>First, look whether the header is somewhere in the buildlink3
1404: directory below <code class="varname">WRKDIR</code>. In the above case of
1405: the missing Pango header:</p>
1406: <pre class="programlisting">
1407: <code class="prompt">$</code> find work/.buildlink/ -print | grep -F pango/pango.h
1408: </pre>
1409: <p>In the case of Pango, the output is:</p>
1410: <pre class="programlisting">
1411: work/.buildlink/include/pango-1.0/pango/pango.h
1412: </pre>
1413: <p>If the <code class="filename">pango/pango.h</code> file were placed directly
1414: in the <code class="filename">.buildlink</code> directory, it would have been
1415: found automatically. There is an extra <code class="filename">pango-1.0</code>
1416: path component though, which means that the compiler command line must
1417: contain an option of the form
1418: <code class="literal">-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</code>. In
1419: most cases this option is generated by the configure script, which can be examined using:</p>
1420: <pre class="programlisting">
1421: <code class="prompt">$</code> $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile
1422: -I/usr/pkg/include/pango-1.0
1423: -I/usr/pkg/include/pango-1.0
1424: -I/usr/pkg/include/pango-1.0
1425: -I/usr/pkg/include/pango-1.0
1426: -I/usr/pkg/include/pango-1.0
1427: </pre>
1428: <p>This looks good. These options are transformed by the buildlink
1429: wrapper to refer to the correct path inside
1430: <code class="filename">work/.buildlink</code>.</p>
1431: <p>Since the compilation fails though, examine the compiler command
1432: lines in <code class="filename">work/.work.log</code> to see whether the
1433: <code class="literal">-I</code> option is included in the particular command
1434: line.</p>
1435: <p>To further analyze the situation, run <span class="command"><strong>bmake
1436: build-env</strong></span>, which sets up an interactive, realistic environment
1437: including all the pkgsrc wrapper commands and environment variables. From
1438: there, try to compile some simple example programs that use the
1439: header.</p>
1440: </div>
1441: <div class="sect3">
1442: <div class="titlepage"><div><div><h4 class="title">
1443: <a name="fixes.build.header.gen"></a>21.5.3.2. Headers generated during the build</h4></div></div></div>
1444: <p>If the name of the header seems to come from the package itself,
1445: and if the build is run with parallel jobs, the package may have some
1446: undeclared dependencies between the <code class="filename">.c</code> and the
1447: <code class="filename">.h</code> files, and a C file is compiled before its
1448: required header is generated.</p>
1449: <p>To see whether the build runs with parallel jobs, run
1450: <span class="command"><strong>bmake show-all-build | grep JOBS</strong></span>. Its output looks
1451: like this:</p>
1452: <pre class="programlisting">
1453: usr MAKE_JOBS= 7
1454: pkg MAKE_JOBS_SAFE # undefined
1455: def _MAKE_JOBS_N= 7
1456: </pre>
1457: <p>In this case the pkgsrc user has asked pkgsrc to build packages
1458: with 7 jobs in parallel (<code class="varname">MAKE_JOBS</code>). The
1459: package could have disabled parallel builds by setting
1460: <code class="varname">MAKE_JOBS_SAFE</code> to <code class="literal">no</code>, but
1461: in this case it hasn't.</p>
1462: <p>To see whether the build failure is caused by parallel builds,
1463: first save the exact error message and a bit of context, maybe you need
1464: it later for reporting a bug. Next, run:</p>
1465: <pre class="programlisting">
1466: MAKE_JOBS_SAFE=no bmake clean build
1467: </pre>
1468: <p>If that succeeds, <a class="ulink" href="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd" target="_top">file a bug
1469: report</a> against the pkgsrc package, including the exact error
1470: message and the contents of your <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> file.</p>
1471: </div>
1.70 rillig 1472: <div class="sect3">
1473: <div class="titlepage"><div><div><h4 class="title">
1474: <a name="fixes.build.header.symlink"></a>21.5.3.3. Symlinks</h4></div></div></div>
1475: <p>Pkgsrc does not work reliably if any of
1476: <code class="varname">LOCALBASE</code>, <code class="varname">VARBASE</code> or
1477: <code class="varname">WRKDIR</code> contains a symlink. Since 2019Q2, the pkgsrc
1478: bootstrap program prevents installing pkgsrc in symlink-based
1479: directories. Existing pkgsrc installations are not checked for symlinks
1480: though.</p>
1481: <p>The "No such file or directory" error messages are a typical
1482: symptom of symlinks, and it's quite difficult to find out that this is
1483: the actual cause.</p>
1484: </div>
1485: <div class="sect3">
1486: <div class="titlepage"><div><div><h4 class="title">
1487: <a name="fixes.build.header.stale"></a>21.5.3.4. Stale working directories</h4></div></div></div>
1488: <p>When building a hierarchy of packages, it may happen that one
1489: package is built and then pkgsrc is updated. This situation can provoke
1490: various hard to diagnose build errors. To clean up the situation:</p>
1491: <pre class="programlisting">
1492: <code class="prompt">$</code> (cd ../../ && test -f mk/bsd.pkg.mk && rm -rf */*/work)
1493: </pre>
1494: <p>(The test for <code class="filename">bsd.pkg.mk</code> just prevents running
1495: this command in the wrong directory.)</p>
1496: <p>If you have set <code class="varname">WRKOBJDIR</code> in <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>, remove
1497: that directory as well.</p>
1498: </div>
1499: <div class="sect3">
1500: <div class="titlepage"><div><div><h4 class="title">
1501: <a name="fixes.build.header.misc"></a>21.5.3.5. Other possible reasons</h4></div></div></div>
1502: <p>On platforms other than BSD, third-party packages are installed in
1503: <code class="filename">/usr/include</code>, together with the base system. This
1504: means that pkgsrc cannot distinguish between headers provided by the base
1505: system (which it needs) and headers from third-party packages (which are
1506: often included in pkgsrc as well). This can lead to subtle version
1507: mismatches.</p>
1508: <p>In pkgsrc installations that have been active for several years, it
1509: may happen that some files are manually deleted. To exclude this unlikely
1510: reason, run <span class="command"><strong>pkg_admin check</strong></span>.</p>
1511: <p>It may help to run <span class="command"><strong>pkg_admin rebuild-tree</strong></span> to
1512: check/fix dependencies.</p>
1513: <p>If all of the above doesn't help, see <a class="xref" href="help-user.html" title="Chapter 2. Getting help">Chapter 2, <i>Getting help</i></a>
1514: for contact information. Be prepared to describe what you have tried so
1515: far and what any error messages were.</p>
1516: </div>
1.69 rillig 1517: </div>
1518: <div class="sect2">
1519: <div class="titlepage"><div><div><h3 class="title">
1520: <a name="undefined-reference"></a>21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span>
1.15 wiz 1521: </h3></div></div></div>
1.1 dsieger 1522: <p>This error message often means that a package did not
1523: link to a shared library it needs. The following functions are
1524: known to cause this error message over and over.</p>
1525: <div class="informaltable">
1.48 tnn 1526: <a name="undefined-reference-functions"></a><table class="informaltable" border="1">
1.1 dsieger 1527: <colgroup>
1528: <col>
1529: <col>
1530: <col>
1531: </colgroup>
1532: <thead><tr>
1533: <th>Function</th>
1534: <th>Library</th>
1535: <th>Affected platforms</th>
1536: </tr></thead>
1537: <tbody>
1538: <tr>
1539: <td>accept, bind, connect</td>
1540: <td>-lsocket</td>
1541: <td>Solaris</td>
1542: </tr>
1543: <tr>
1544: <td>crypt</td>
1545: <td>-lcrypt</td>
1546: <td>DragonFly, NetBSD</td>
1547: </tr>
1548: <tr>
1549: <td>dlopen, dlsym</td>
1550: <td>-ldl</td>
1551: <td>Linux</td>
1552: </tr>
1553: <tr>
1554: <td>gethost*</td>
1555: <td>-lnsl</td>
1556: <td>Solaris</td>
1557: </tr>
1558: <tr>
1559: <td>inet_aton</td>
1560: <td>-lresolv</td>
1561: <td>Solaris</td>
1562: </tr>
1563: <tr>
1564: <td>nanosleep, sem_*, timer_*</td>
1565: <td>-lrt</td>
1566: <td>Solaris</td>
1567: </tr>
1568: <tr>
1569: <td>openpty</td>
1570: <td>-lutil</td>
1571: <td>Linux</td>
1572: </tr>
1573: </tbody>
1574: </table>
1575: </div>
1576: <p>To fix these linker errors, it is often sufficient to say
1577: <code class="literal">LIBS.<em class="replaceable"><code>OperatingSystem</code></em>+=
1578: -l<em class="replaceable"><code>foo</code></em></code> to the package
1.7 hubertf 1579: <code class="filename">Makefile</code> and then say <span class="command"><strong>bmake clean;
1.1 dsieger 1580: bmake</strong></span>.</p>
1.24 asau 1581: <div class="sect3">
1.1 dsieger 1582: <div class="titlepage"><div><div><h4 class="title">
1.69 rillig 1583: <a name="undefined-reference-sunpro"></a>21.5.4.1. Special issue: The SunPro compiler</h4></div></div></div>
1.1 dsieger 1584: <p>When you are using the SunPro compiler, there is another
1585: possibility. That compiler cannot handle the following code:</p>
1586: <pre class="programlisting">
1587: extern int extern_func(int);
1588:
1589: static inline int
1590: inline_func(int x)
1591: {
1592: return extern_func(x);
1593: }
1594:
1595: int main(void)
1596: {
1597: return 0;
1598: }
1599: </pre>
1600: <p>It generates the code for <code class="function">inline_func</code> even if
1601: that function is never used. This code then refers to
1602: <code class="function">extern_func</code>, which can usually not be resolved. To
1603: solve this problem you can try to tell the package to disable inlining
1604: of functions.</p>
1605: </div>
1606: </div>
1.24 asau 1607: <div class="sect2">
1.1 dsieger 1608: <div class="titlepage"><div><div><h3 class="title">
1.69 rillig 1609: <a name="out-of-memory"></a>21.5.5. Running out of memory</h3></div></div></div>
1.1 dsieger 1610: <p>Sometimes packages fail to build because the compiler runs
1611: into an operating system specific soft limit. With the
1612: <code class="varname">UNLIMIT_RESOURCES</code> variable pkgsrc can be told
1.43 wiz 1613: to unlimit the resources. Currently, the allowed values are any combination of
1614: <span class="quote">“<span class="quote">cputime</span>”</span>, <span class="quote">“<span class="quote">datasize</span>”</span>,
1615: <span class="quote">“<span class="quote">memorysize</span>”</span>, and <span class="quote">“<span class="quote">stacksize</span>”</span>.
1.1 dsieger 1616: Setting this variable is similar to running the shell builtin
1.7 hubertf 1617: <span class="command"><strong>ulimit</strong></span> command to raise the maximum data
1.1 dsieger 1618: segment size or maximum stack size of a process, respectively, to
1619: their hard limits.</p>
1620: </div>
1621: </div>
1.24 asau 1622: <div class="sect1">
1.1 dsieger 1623: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1624: <a name="fixes.install"></a>21.6. The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
1.24 asau 1625: <div class="sect2">
1.1 dsieger 1626: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1627: <a name="install-scripts"></a>21.6.1. Creating needed directories</h3></div></div></div>
1.7 hubertf 1628: <p>The BSD-compatible <span class="command"><strong>install</strong></span> supplied
1.1 dsieger 1629: with some operating systems cannot create more than one
1630: directory at a time. As such, you should call
1631: <code class="literal">${INSTALL_*_DIR}</code> like this:</p>
1632: <pre class="programlisting">
1633: ${INSTALL_DATA_DIR} ${PREFIX}/dir1
1634: ${INSTALL_DATA_DIR} ${PREFIX}/dir2
1.52 sevan 1635: </pre>
1.15 wiz 1636: <p>You can also just append <span class="quote">“<span class="quote"><code class="literal">dir1
1637: dir2</code></span>”</span> to the
1.1 dsieger 1638: <code class="varname">INSTALLATION_DIRS</code> variable, which will
1639: automatically do the right thing.</p>
1640: </div>
1.24 asau 1641: <div class="sect2">
1.1 dsieger 1642: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1643: <a name="where-to-install-documentation"></a>21.6.2. Where to install documentation</h3></div></div></div>
1.1 dsieger 1644: <p>In general, documentation should be installed into
1645: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1646: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code> (the latter
1647: includes the version number of the package).</p>
1648: <p>Many modern packages using GNU autoconf allow to set the
1649: directory where HTML documentation is installed with the
1.15 wiz 1650: <span class="quote">“<span class="quote">--with-html-dir</span>”</span> option. Sometimes using this flag
1.1 dsieger 1651: is needed because otherwise the documentation ends up in
1652: <code class="filename">${PREFIX}/share/doc/html</code> or other
1653: places.</p>
1654: <p>An exception to the above is that library API documentation
1.59 leot 1655: generated with the <a href="https://cdn.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
1.1 dsieger 1656: browsers (devhelp) should be left at their default location, which
1657: is <code class="filename">${PREFIX}/share/gtk-doc</code>. Such
1658: documentation can be recognized from files ending in
1659: <code class="filename">.devhelp</code> or <code class="filename">.devhelp2</code>.
1660: (It is also acceptable to install such files in
1661: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1662: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code>; the
1663: <code class="filename">.devhelp*</code> file must be directly in that
1664: directory then, no additional subdirectory level is allowed in
1665: this case. This is usually achieved by using
1.15 wiz 1666: <span class="quote">“<span class="quote">--with-html-dir=${PREFIX}/share/doc</span>”</span>.
1.1 dsieger 1667: <code class="filename">${PREFIX}/share/gtk-doc</code> is preferred
1668: though.)</p>
1669: </div>
1.24 asau 1670: <div class="sect2">
1.1 dsieger 1671: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1672: <a name="installing-score-files"></a>21.6.3. Installing highscore files</h3></div></div></div>
1.1 dsieger 1673: <p>Certain packages, most of them in the games category, install
1674: a score file that allows all users on the system to record their
1675: highscores. In order for this to work, the binaries need to be
1676: installed setgid and the score files owned by the appropriate
1.21 wiz 1677: group and/or owner (traditionally the "games" user/group). Set
1678: <code class="varname">USE_GAMESGROUP</code> to yes to support this. The
1.1 dsieger 1679: following variables, documented in more detail in
1680: <code class="filename">mk/defaults/mk.conf</code>, control this
1.21 wiz 1681: behaviour: <code class="varname">GAMEDATAMODE</code>,
1682: <code class="varname">GAMEDIRMODE</code>, <code class="varname">GAMES_GROUP</code>,
1.47 leot 1683: <code class="varname">GAMEMODE</code>, <code class="varname">GAME_USER</code>.
1684: Other useful variables are: <code class="varname">GAMEDIR_PERMS</code>,
1685: <code class="varname">GAMEDATA_PERMS</code> and
1686: <code class="varname">SETGID_GAMES_PERMS</code>.</p>
1687: <p>An example that illustrates some of the variables described above is
1688: <code class="filename">games/moon-buggy</code>. <code class="varname">OWN_DIRS_PERMS</code> is
1689: used to properly set directory permissions of the directory where the
1690: scorefile is saved, <code class="varname">REQD_FILES_PERMS</code> is used to create a
1691: dummy scorefile (<code class="filename">mbscore</code>) with the proper permissions
1692: and <code class="varname">SPECIAL_PERMS</code> is used to install setgid the game
1693: binary:</p>
1694: <pre class="programlisting">
1.53 rillig 1695: USE_GAMESGROUP= yes
1.47 leot 1696:
1.53 rillig 1697: BUILD_DEFS+= VARBASE
1.47 leot 1698:
1.53 rillig 1699: OWN_DIRS_PERMS+= ${VARBASE}/games/moon-buggy ${GAMEDIR_PERMS}
1700: REQD_FILES_PERMS+= /dev/null ${VARBASE}/games/moon-buggy/mbscore ${GAMEDATA_PERMS}
1701: SPECIAL_PERMS+= ${PREFIX}/bin/moon-buggy ${SETGID_GAMES_PERMS}
1.52 sevan 1702: </pre>
1.47 leot 1703: <p>Various <code class="varname">INSTALL_*</code> variables are also available:
1704: <code class="varname">INSTALL_GAME</code> to install setgid game binaries,
1705: <code class="varname">INSTALL_GAME_DIR</code> to install game directories that are
1706: needed to be accessed by setgid games and
1707: <code class="varname">INSTALL_GAME_DATA</code> to install scorefiles.</p>
1.9 jmcneill 1708: <p>A package should therefore never hard code file ownership or
1.47 leot 1709: access permissions but rely on <code class="varname">*_PERMS</code> as described above
1710: or alternatively on <code class="varname">INSTALL_GAME</code>,
1711: <code class="varname">INSTALL_GAME_DATA</code> and
1712: <code class="varname">INSTALL_GAME_DIR</code> to set these correctly.</p>
1.1 dsieger 1713: </div>
1.24 asau 1714: <div class="sect2">
1.1 dsieger 1715: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1716: <a name="destdir-support"></a>21.6.4. Adding DESTDIR support to packages</h3></div></div></div>
1.9 jmcneill 1717: <p><code class="varname">DESTDIR</code> support means that a package
1718: installs into a staging directory, not the final location of the
1719: files. Then a binary package is created which can be used for
1720: installation as usual. There are two ways: Either the package must
1.15 wiz 1721: install as root (<span class="quote">“<span class="quote">destdir</span>”</span>) or the package can
1722: install as non-root user (<span class="quote">“<span class="quote">user-destdir</span>”</span>).</p>
1.24 asau 1723: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1724: <li class="listitem"><p><code class="varname">PKG_DESTDIR_SUPPORT</code> has to be
1.54 leot 1725: set to <span class="quote">“<span class="quote">destdir</span>”</span> or <span class="quote">“<span class="quote">user-destdir</span>”</span>.
1726: By default <code class="varname">PKG_DESTDIR_SUPPORT</code>
1.22 wiz 1727: is set to <span class="quote">“<span class="quote">user-destdir</span>”</span> to help catching more
1728: potential packaging problems. If bsd.prefs.mk is included in the Makefile,
1.9 jmcneill 1729: <code class="varname">PKG_DESTDIR_SUPPORT</code> needs to be set before
1730: the inclusion.</p></li>
1.15 wiz 1731: <li class="listitem"><p>All installation operations have to be prefixed with
1.3 rillig 1732: <code class="filename">${DESTDIR}</code>.</p></li>
1.15 wiz 1733: <li class="listitem"><p>automake gets this DESTDIR mostly right
1.3 rillig 1734: automatically. Many manual rules and pre/post-install often are
1735: incorrect; fix them.</p></li>
1.15 wiz 1736: <li class="listitem"><p>If files are installed with special owner/group
1.11 imil 1737: use <code class="varname">SPECIAL_PERMS</code>.</p></li>
1.15 wiz 1738: <li class="listitem"><p>In general, packages should support
1.3 rillig 1739: <code class="varname">UNPRIVILEGED</code> to be able to use
1740: DESTDIR.</p></li>
1741: </ul></div>
1742: </div>
1.24 asau 1743: <div class="sect2">
1.3 rillig 1744: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1745: <a name="hardcoded-paths"></a>21.6.5. Packages with hardcoded paths to other interpreters</h3></div></div></div>
1.1 dsieger 1746: <p>Your package may also contain scripts with hardcoded paths to
1747: other interpreters besides (or as well as) perl. To correct the
1748: full pathname to the script interpreter, you need to set the
1749: following definitions in your <code class="filename">Makefile</code> (we
1.7 hubertf 1750: shall use <span class="command"><strong>tclsh</strong></span> in this example):</p>
1.1 dsieger 1751: <pre class="programlisting">
1752: REPLACE_INTERPRETER+= tcl
1753: REPLACE.tcl.old= .*/bin/tclsh
1754: REPLACE.tcl.new= ${PREFIX}/bin/tclsh
1755: REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed,
1756: # relative to ${WRKSRC}, just as in REPLACE_PERL
1.52 sevan 1757: </pre>
1.24 asau 1758: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 1759: <h3 class="title">Note</h3>
1760: <p>Before March 2006, these variables were called
1761: <code class="varname">_REPLACE.*</code> and
1762: <code class="varname">_REPLACE_FILES.*</code>.</p>
1763: </div>
1764: </div>
1.24 asau 1765: <div class="sect2">
1.1 dsieger 1766: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1767: <a name="perl-modules"></a>21.6.6. Packages installing perl modules</h3></div></div></div>
1.1 dsieger 1768: <p>Makefiles of packages providing perl5 modules should include
1769: the Makefile fragment
1770: <code class="filename">../../lang/perl5/module.mk</code>. It provides a
1.7 hubertf 1771: <span class="command"><strong>do-configure</strong></span> target for the standard perl
1.1 dsieger 1772: configuration for such modules as well as various hooks to tune
1773: this configuration. See comments in this file for
1774: details.</p>
1775: <p>Perl5 modules will install into different places depending
1776: on the version of perl used during the build process. To
1777: address this, pkgsrc will append lines to the
1778: <code class="filename">PLIST</code> corresponding to the files listed in
1779: the installed <code class="filename">.packlist</code> file generated by
1780: most perl5 modules. This is invoked by defining
1781: <code class="varname">PERL5_PACKLIST</code> to a space-separated list of
1.26 wiz 1782: packlist files relative to <code class="varname">PERL5_PACKLIST_DIR</code>
1783: (<code class="varname">PERL5_INSTALLVENDORARCH</code> by default),
1784: e.g.:</p>
1.1 dsieger 1785: <pre class="programlisting">
1.26 wiz 1786: PERL5_PACKLIST= auto/Pg/.packlist
1.52 sevan 1787: </pre>
1.26 wiz 1788: <p>The perl5 config variables
1789: <code class="varname">installarchlib</code>,
1790: <code class="varname">installscript</code>,
1791: <code class="varname">installvendorbin</code>,
1792: <code class="varname">installvendorscript</code>,
1793: <code class="varname">installvendorarch</code>,
1794: <code class="varname">installvendorlib</code>,
1795: <code class="varname">installvendorman1dir</code>, and
1796: <code class="varname">installvendorman3dir</code> represent those
1797: locations in which components of perl5 modules may be installed,
1798: provided as variable with uppercase and prefixed with
1799: <code class="varname">PERL5_</code>, e.g. <code class="varname">PERL5_INSTALLARCHLIB</code>
1800: and may be used by perl5 packages that don't have a packlist.
1801: These variables are also substituted for in the
1802: <code class="filename">PLIST</code> as uppercase prefixed with
1803: <code class="varname">PERL5_SUB_</code>.</p>
1.1 dsieger 1804: </div>
1.24 asau 1805: <div class="sect2">
1.1 dsieger 1806: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1807: <a name="faq.info-files"></a>21.6.7. Packages installing info files</h3></div></div></div>
1.1 dsieger 1808: <p>Some packages install info files or use the
1.15 wiz 1809: <span class="quote">“<span class="quote">makeinfo</span>”</span> or <span class="quote">“<span class="quote">install-info</span>”</span>
1.1 dsieger 1810: commands. <code class="varname">INFO_FILES</code> should be defined in
1811: the package Makefile so that <code class="filename">INSTALL</code> and
1812: <code class="filename">DEINSTALL</code> scripts will be generated to
1813: handle registration of the info files in the Info directory
1.15 wiz 1814: file. The <span class="quote">“<span class="quote">install-info</span>”</span> command used for the info
1.1 dsieger 1815: files registration is either provided by the system, or by a
1816: special purpose package automatically added as dependency if
1817: needed.</p>
1818: <p><code class="varname">PKGINFODIR</code> is the directory under
1819: <code class="filename">${PREFIX}</code> where info files are primarily
1820: located. <code class="varname">PKGINFODIR</code> defaults to
1.15 wiz 1821: <span class="quote">“<span class="quote">info</span>”</span> and can be overridden by the user.</p>
1.1 dsieger 1822: <p>The info files for the package should be listed in the
1823: package <code class="filename">PLIST</code>; however any split info files
1824: need not be listed.</p>
1.15 wiz 1825: <p>A package which needs the <span class="quote">“<span class="quote">makeinfo</span>”</span> command
1826: at build time must add <span class="quote">“<span class="quote">makeinfo</span>”</span> to
1.1 dsieger 1827: <code class="varname">USE_TOOLS</code> in its Makefile. If a minimum
1.15 wiz 1828: version of the <span class="quote">“<span class="quote">makeinfo</span>”</span> command is needed it
1.1 dsieger 1829: should be noted with the <code class="varname">TEXINFO_REQD</code>
1830: variable in the package <code class="filename">Makefile</code>. By
1831: default, a minimum version of 3.12 is required. If the system
1.7 hubertf 1832: does not provide a <span class="command"><strong>makeinfo</strong></span> command or if it
1.1 dsieger 1833: does not match the required minimum, a build dependency on the
1.59 leot 1834: <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/gtexinfo/README.html" target="_top"><code class="filename">devel/gtexinfo</code></a> package will
1.1 dsieger 1835: be added automatically.</p>
1836: <p>The build and installation process of the software provided
1837: by the package should not use the
1.7 hubertf 1838: <span class="command"><strong>install-info</strong></span> command as the registration of
1.1 dsieger 1839: info files is the task of the package
1840: <code class="filename">INSTALL</code> script, and it must use the
1.7 hubertf 1841: appropriate <span class="command"><strong>makeinfo</strong></span> command.</p>
1.1 dsieger 1842: <p>To achieve this goal, the pkgsrc infrastructure creates
1.7 hubertf 1843: overriding scripts for the <span class="command"><strong>install-info</strong></span> and
1844: <span class="command"><strong>makeinfo</strong></span> commands in a directory listed early
1.1 dsieger 1845: in <code class="varname">PATH</code>.</p>
1.7 hubertf 1846: <p>The script overriding <span class="command"><strong>install-info</strong></span> has
1.1 dsieger 1847: no effect except the logging of a message. The script overriding
1.7 hubertf 1848: <span class="command"><strong>makeinfo</strong></span> logs a message and according to the
1.1 dsieger 1849: value of <code class="varname">TEXINFO_REQD</code> either runs the appropriate
1.7 hubertf 1850: <span class="command"><strong>makeinfo</strong></span> command or exit on error.</p>
1.1 dsieger 1851: </div>
1.24 asau 1852: <div class="sect2">
1.1 dsieger 1853: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1854: <a name="manpages"></a>21.6.8. Packages installing man pages</h3></div></div></div>
1.1 dsieger 1855: <p>All packages that install manual pages should install them
1856: into the same directory, so that there is one common place to look
1857: for them. In pkgsrc, this place is
1858: <code class="literal">${PREFIX}/${PKGMANDIR}</code>, and this expression
1859: should be used in packages. The default for
1860: <code class="varname">PKGMANDIR</code> is
1.15 wiz 1861: <span class="quote">“<span class="quote"><code class="filename">man</code></span>”</span>. Another often-used value
1862: is <span class="quote">“<span class="quote"><code class="filename">share/man</code></span>”</span>.</p>
1.24 asau 1863: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 1864: <h3 class="title">Note</h3>
1865: <p>The support for a custom <code class="varname">PKGMANDIR</code>
1866: is far from complete.</p>
1867: </div>
1868: <p>The <code class="filename">PLIST</code> files can just use
1869: <code class="filename">man/</code> as the top level directory for the man
1870: page file entries, and the pkgsrc framework will convert as
1871: needed. In all other places, the correct
1872: <code class="varname">PKGMANDIR</code> must be used.</p>
1873: <p>Packages that are
1874: configured with <code class="varname">GNU_CONFIGURE</code> set as
1.15 wiz 1875: <span class="quote">“<span class="quote">yes</span>”</span>, by default will use the
1.1 dsieger 1876: <code class="filename">./configure</code>
1877: --mandir switch to set where the man pages should be installed.
1878: The path is <code class="varname">GNU_CONFIGURE_MANDIR</code> which defaults
1879: to <code class="varname">${PREFIX}/${PKGMANDIR}</code>.</p>
1880: <p>Packages that use <code class="varname">GNU_CONFIGURE</code> but do not
1881: use --mandir, can set <code class="varname">CONFIGURE_HAS_MANDIR</code>
1.15 wiz 1882: to <span class="quote">“<span class="quote">no</span>”</span>.
1.1 dsieger 1883: Or if the <code class="filename">./configure</code> script uses
1884: a non-standard use of --mandir, you can set
1885: <code class="varname">GNU_CONFIGURE_MANDIR</code> as needed.</p>
1.76 rillig 1886: <p>See <a class="xref" href="plist.html#manpage-compression" title="19.5. Man page compression">Section 19.5, “Man page compression”</a> for
1.1 dsieger 1887: information on installation of compressed manual pages.</p>
1888: </div>
1.24 asau 1889: <div class="sect2">
1.1 dsieger 1890: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1891: <a name="gconf-data-files"></a>21.6.9. Packages installing GConf data files</h3></div></div></div>
1.1 dsieger 1892: <p>If a package installs <code class="filename">.schemas</code> or
1.5 rillig 1893: <code class="filename">.entries</code> files, used by GConf,
1.1 dsieger 1894: you need to take some extra steps to make sure they get registered
1895: in the database:</p>
1.15 wiz 1896: <div class="orderedlist"><ol class="orderedlist" type="1">
1897: <li class="listitem"><p>Include <code class="filename">../../devel/GConf/schemas.mk</code>
1.1 dsieger 1898: instead of its <code class="filename">buildlink3.mk</code> file. This
1.5 rillig 1899: takes care of rebuilding the GConf database at installation and
1.1 dsieger 1900: deinstallation time, and tells the package where to install
1.5 rillig 1901: GConf data files using some standard configure arguments. It
1.1 dsieger 1902: also disallows any access to the database directly from the
1903: package.</p></li>
1.15 wiz 1904: <li class="listitem"><p>Ensure that the package installs its
1.1 dsieger 1905: <code class="filename">.schemas</code> files under
1906: <code class="filename">${PREFIX}/share/gconf/schemas</code>. If they get
1907: installed under <code class="filename">${PREFIX}/etc</code>, you will
1908: need to manually patch the package.</p></li>
1.15 wiz 1909: <li class="listitem"><p>Check the PLIST and remove any entries under the etc/gconf
1.1 dsieger 1910: directory, as they will be handled automatically. See
1.63 rillig 1911: <a class="xref" href="faq.html#faq.conf" title="10.13. How do I change the location of configuration files?">Section 10.13, “How do I change the location of configuration files?”</a> for more information.</p></li>
1.15 wiz 1912: <li class="listitem"><p>Define the <code class="varname">GCONF_SCHEMAS</code> variable in
1.1 dsieger 1913: your <code class="filename">Makefile</code> with a list of all
1914: <code class="filename">.schemas</code> files installed by the package, if
1915: any. Names must not contain any directories in them.</p></li>
1.15 wiz 1916: <li class="listitem"><p>Define the <code class="varname">GCONF_ENTRIES</code> variable in
1.1 dsieger 1917: your <code class="filename">Makefile</code> with a
1918: list of all <code class="filename">.entries</code> files installed by the
1919: package, if any. Names must not contain any directories in
1920: them.</p></li>
1921: </ol></div>
1922: </div>
1.24 asau 1923: <div class="sect2">
1.1 dsieger 1924: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1925: <a name="scrollkeeper-data-files"></a>21.6.10. Packages installing scrollkeeper/rarian data files</h3></div></div></div>
1.1 dsieger 1926: <p>If a package installs <code class="filename">.omf</code> files, used by
1.12 mishka 1927: scrollkeeper/rarian, you need to take some extra steps to make sure they
1.1 dsieger 1928: get registered in the database:</p>
1.15 wiz 1929: <div class="orderedlist"><ol class="orderedlist" type="1">
1930: <li class="listitem"><p>Include
1.12 mishka 1931: <code class="filename">../../mk/omf-scrollkeeper.mk</code>
1932: instead of rarian's <code class="filename">buildlink3.mk</code> file. This
1.1 dsieger 1933: takes care of rebuilding the scrollkeeper database at
1934: installation and deinstallation time, and disallows any access
1935: to it directly from the package.</p></li>
1.15 wiz 1936: <li class="listitem"><p>Check the PLIST and remove any entries under the
1.1 dsieger 1937: <code class="filename">libdata/scrollkeeper</code> directory, as they
1938: will be handled automatically.</p></li>
1.15 wiz 1939: <li class="listitem"><p>Remove the <code class="filename">share/omf</code> directory from
1.12 mishka 1940: the PLIST. It will be handled by rarian. (<span class="command"><strong>make
1941: print-PLIST</strong></span> does this automatically.)</p></li>
1.1 dsieger 1942: </ol></div>
1943: </div>
1.24 asau 1944: <div class="sect2">
1.1 dsieger 1945: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1946: <a name="x11-fonts"></a>21.6.11. Packages installing X11 fonts</h3></div></div></div>
1.1 dsieger 1947: <p>If a package installs font files, you will need to rebuild
1948: the fonts database in the directory where they get installed at
1949: installation and deinstallation time. This can be automatically
1950: done by using the pkginstall framework.</p>
1951: <p>You can list the directories where fonts are installed in the
1952: <code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code>
1953: variables, where <em class="replaceable"><code>type</code></em> can be one of
1.15 wiz 1954: <span class="quote">“<span class="quote">ttf</span>”</span>, <span class="quote">“<span class="quote">type1</span>”</span> or <span class="quote">“<span class="quote">x11</span>”</span>.
1.1 dsieger 1955: Also make sure that the database file
1956: <code class="filename">fonts.dir</code> is not listed in the PLIST.</p>
1957: <p>Note that you should not create new directories for fonts;
1958: instead use the standard ones to avoid that the user needs to
1959: manually configure his X server to find them.</p>
1960: </div>
1.24 asau 1961: <div class="sect2">
1.1 dsieger 1962: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1963: <a name="gtk2-modules"></a>21.6.12. Packages installing GTK2 modules</h3></div></div></div>
1.1 dsieger 1964: <p>If a package installs GTK2 immodules or loaders, you need to
1965: take some extra steps to get them registered in the GTK2 database
1966: properly:</p>
1.15 wiz 1967: <div class="orderedlist"><ol class="orderedlist" type="1">
1968: <li class="listitem"><p>Include
1.1 dsieger 1969: <code class="filename">../../x11/gtk2/modules.mk</code> instead of its
1970: <code class="filename">buildlink3.mk</code> file. This takes care of
1971: rebuilding the database at installation and deinstallation time.</p></li>
1.15 wiz 1972: <li class="listitem"><p>Set <code class="varname">GTK2_IMMODULES=YES</code> if
1.1 dsieger 1973: your package installs GTK2 immodules.</p></li>
1.15 wiz 1974: <li class="listitem"><p>Set <code class="varname">GTK2_LOADERS=YES</code> if your package installs
1.1 dsieger 1975: GTK2 loaders.</p></li>
1.15 wiz 1976: <li class="listitem">
1.1 dsieger 1977: <p>Patch the package to not touch any of the GTK2
1978: databases directly. These are:</p>
1.24 asau 1979: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1980: <li class="listitem"><p><code class="filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p></li>
1981: <li class="listitem"><p><code class="filename">libdata/gtk-2.0/gtk.immodules</code></p></li>
1.1 dsieger 1982: </ul></div>
1983: </li>
1.15 wiz 1984: <li class="listitem"><p>Check the <code class="filename">PLIST</code> and remove
1.1 dsieger 1985: any entries under the <code class="filename">libdata/gtk-2.0</code>
1986: directory, as they will be handled automatically.</p></li>
1987: </ol></div>
1988: </div>
1.24 asau 1989: <div class="sect2">
1.1 dsieger 1990: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1991: <a name="sgml-xml-data"></a>21.6.13. Packages installing SGML or XML data</h3></div></div></div>
1.1 dsieger 1992: <p>If a package installs SGML or XML data files that need to be
1993: registered in system-wide catalogs (like DTDs, sub-catalogs,
1994: etc.), you need to take some extra steps:</p>
1.15 wiz 1995: <div class="orderedlist"><ol class="orderedlist" type="1">
1996: <li class="listitem"><p>Include
1.1 dsieger 1997: <code class="filename">../../textproc/xmlcatmgr/catalogs.mk</code> in
1998: your <code class="filename">Makefile</code>, which takes care of
1999: registering those files in system-wide catalogs at
2000: installation and deinstallation time.</p></li>
1.15 wiz 2001: <li class="listitem"><p>Set <code class="varname">SGML_CATALOGS</code> to the full path of
1.1 dsieger 2002: any SGML catalogs installed by the package.</p></li>
1.15 wiz 2003: <li class="listitem"><p>Set <code class="varname">XML_CATALOGS</code> to the full path of
1.1 dsieger 2004: any XML catalogs installed by the package.</p></li>
1.15 wiz 2005: <li class="listitem"><p>Set <code class="varname">SGML_ENTRIES</code> to individual entries
1.1 dsieger 2006: to be added to the SGML catalog. These come in groups of
2007: three strings; see xmlcatmgr(1) for more information
2008: (specifically, arguments recognized by the 'add' action).
2009: Note that you will normally not use this variable.</p></li>
1.15 wiz 2010: <li class="listitem"><p>Set <code class="varname">XML_ENTRIES</code> to individual entries
1.1 dsieger 2011: to be added to the XML catalog. These come in groups of three
2012: strings; see xmlcatmgr(1) for more information (specifically,
2013: arguments recognized by the 'add' action). Note that you will
2014: normally not use this variable.</p></li>
2015: </ol></div>
2016: </div>
1.24 asau 2017: <div class="sect2">
1.1 dsieger 2018: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2019: <a name="mime-database"></a>21.6.14. Packages installing extensions to the MIME database</h3></div></div></div>
1.1 dsieger 2020: <p>If a package provides extensions to the MIME database by
2021: installing <code class="filename">.xml</code> files inside
2022: <code class="filename">${PREFIX}/share/mime/packages</code>, you
2023: need to take some extra steps to ensure that the database is kept
2024: consistent with respect to these new files:</p>
1.15 wiz 2025: <div class="orderedlist"><ol class="orderedlist" type="1">
2026: <li class="listitem"><p>Include
1.1 dsieger 2027: <code class="filename">../../databases/shared-mime-info/mimedb.mk</code>
2028: (avoid using the <code class="filename">buildlink3.mk</code> file from
2029: this same directory, which is reserved for inclusion from
2030: other <code class="filename">buildlink3.mk</code> files). It takes
2031: care of rebuilding the MIME database at installation and
2032: deinstallation time, and disallows any access to it directly
2033: from the package.</p></li>
1.15 wiz 2034: <li class="listitem"><p>Check the PLIST and remove any entries under the
1.1 dsieger 2035: <code class="filename">share/mime</code> directory,
2036: <span class="emphasis"><em>except</em></span> for files saved under
2037: <code class="filename">share/mime/packages</code>. The former are
2038: handled automatically by
2039: the update-mime-database program, but the latter are
2040: package-dependent and must be removed by the package that
2041: installed them in the first place.</p></li>
1.15 wiz 2042: <li class="listitem"><p>Remove any <code class="filename">share/mime/*</code> directories
1.1 dsieger 2043: from the PLIST. They will be handled by the shared-mime-info
2044: package.</p></li>
2045: </ol></div>
2046: </div>
1.24 asau 2047: <div class="sect2">
1.1 dsieger 2048: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2049: <a name="intltool"></a>21.6.15. Packages using intltool</h3></div></div></div>
1.1 dsieger 2050: <p>If a package uses intltool during its build, add
2051: <code class="literal">intltool</code> to the <code class="varname">USE_TOOLS</code>,
2052: which forces it to use the intltool package provided by pkgsrc,
2053: instead of the one bundled with the distribution file.</p>
2054: <p>This tracks intltool's build-time dependencies and uses the
2055: latest available version; this way, the package benefits of any
2056: bug fixes that may have appeared since it was released.</p>
2057: </div>
1.24 asau 2058: <div class="sect2">
1.1 dsieger 2059: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2060: <a name="startup-scripts"></a>21.6.16. Packages installing startup scripts</h3></div></div></div>
1.1 dsieger 2061: <p>If a package contains a rc.d script, it won't be copied into
2062: the startup directory by default, but you can enable it, by adding
2063: the option <code class="varname">PKG_RCD_SCRIPTS=YES</code> in
1.7 hubertf 2064: <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>. This option will copy the scripts
1.1 dsieger 2065: into <code class="filename">/etc/rc.d</code> when a package is installed, and
2066: it will automatically remove the scripts when the package is
2067: deinstalled.</p>
2068: </div>
1.24 asau 2069: <div class="sect2">
1.1 dsieger 2070: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2071: <a name="tex-packages"></a>21.6.17. Packages installing TeX modules</h3></div></div></div>
1.1 dsieger 2072: <p>If a package installs TeX packages into the texmf tree,
2073: the <code class="filename">ls-R</code> database of the tree needs to be
2074: updated.</p>
1.24 asau 2075: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 2076: <h3 class="title">Note</h3>
1.14 jakllsch 2077: <p>Except the main TeX packages such as kpathsea,
1.1 dsieger 2078: packages should install files
1.14 jakllsch 2079: into <code class="filename">${PREFIX}/share/texmf-dist</code>,
2080: not <code class="filename">${PREFIX}/share/texmf</code>.</p>
1.1 dsieger 2081: </div>
1.15 wiz 2082: <div class="orderedlist"><ol class="orderedlist" type="1">
2083: <li class="listitem"><p>Include
1.14 jakllsch 2084: <code class="filename">../../print/kpathsea/texmf.mk</code>. This
1.1 dsieger 2085: takes care of rebuilding the <code class="filename">ls-R</code>
2086: database at installation and deinstallation time.</p></li>
1.15 wiz 2087: <li class="listitem">
1.1 dsieger 2088: <p>If your package installs files into a texmf
2089: tree other than the one
1.14 jakllsch 2090: at <code class="filename">${PREFIX}/share/texmf-dist</code>,
2091: set <code class="varname">TEX_TEXMF_DIRS</code> to the list of all texmf
1.1 dsieger 2092: trees that need database update.</p>
2093: <p>If your package also installs font map files that need
1.7 hubertf 2094: to be registered using <span class="command"><strong>updmap</strong></span>,
1.18 dholland 2095: include <code class="filename">../../print/tex-tetex/map.mk</code> and
1.14 jakllsch 2096: set <code class="varname">TEX_MAP_FILES</code> and/or
2097: <code class="varname">TEX_MIXEDMAP_FILES</code> to the list of all
1.7 hubertf 2098: such font map files. Then <span class="command"><strong>updmap</strong></span> will
1.1 dsieger 2099: be run automatically at installation/deinstallation to
2100: enable/disable font map files for TeX output
2101: drivers.</p>
2102: </li>
1.15 wiz 2103: <li class="listitem"><p>Make sure that none of <code class="filename">ls-R</code>
1.1 dsieger 2104: databases are included in <code class="filename">PLIST</code>, as
1.18 dholland 2105: they will be removed only by the kpathsea package.</p></li>
1.1 dsieger 2106: </ol></div>
2107: </div>
1.24 asau 2108: <div class="sect2">
1.1 dsieger 2109: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2110: <a name="emulation-packages"></a>21.6.18. Packages supporting running binaries in
1.1 dsieger 2111: emulation</h3></div></div></div>
2112: <p>There are some packages that provide libraries and
2113: executables for running binaries from a one operating system
2114: on a different one (if the latter supports it). One example
2115: is running Linux binaries on NetBSD.</p>
1.59 leot 2116: <p>The <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/rpm2pkg/README.html" target="_top"><code class="filename">pkgtools/rpm2pkg</code></a>
1.1 dsieger 2117: helps in extracting and packaging Linux rpm packages.</p>
2118: <p>The <code class="varname">CHECK_SHLIBS</code> can be set to no to
1.7 hubertf 2119: avoid the <span class="command"><strong>check-shlibs</strong></span> target, which tests
1.1 dsieger 2120: if all libraries for each installed executable can be found by
2121: the dynamic linker. Since the standard dynamic linker is run,
2122: this fails for emulation packages, because the libraries used
2123: by the emulation are not in the standard directories.</p>
2124: </div>
1.24 asau 2125: <div class="sect2">
1.1 dsieger 2126: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2127: <a name="hicolor-theme"></a>21.6.19. Packages installing hicolor theme icons</h3></div></div></div>
1.1 dsieger 2128: <p>If a package installs images under the
2129: <code class="filename">share/icons/hicolor</code> and/or updates the
2130: <code class="filename">share/icons/hicolor/icon-theme.cache</code>
2131: database, you need to take some extra steps to make sure that the
2132: shared theme directory is handled appropriately and that the cache
2133: database is rebuilt:</p>
1.15 wiz 2134: <div class="orderedlist"><ol class="orderedlist" type="1">
2135: <li class="listitem"><p>Include
1.1 dsieger 2136: <code class="filename">../../graphics/hicolor-icon-theme/buildlink3.mk</code>.</p></li>
1.15 wiz 2137: <li class="listitem"><p>Check the <code class="filename">PLIST</code> and remove the
1.1 dsieger 2138: entry that refers to the theme cache.</p></li>
1.15 wiz 2139: <li class="listitem"><p>Ensure that the PLIST does not remove the shared icon
1.1 dsieger 2140: directories from the <code class="filename">share/icons/hicolor</code>
2141: hierarchy because they will be handled automatically.</p></li>
2142: </ol></div>
2143: <p>The best way to verify that the PLIST is correct with
2144: respect to the last two points is to regenerate it using
1.7 hubertf 2145: <span class="command"><strong>make print-PLIST</strong></span>.</p>
1.1 dsieger 2146: </div>
1.24 asau 2147: <div class="sect2">
1.1 dsieger 2148: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2149: <a name="desktop-files"></a>21.6.20. Packages installing desktop files</h3></div></div></div>
1.1 dsieger 2150: <p>If a package installs <code class="filename">.desktop</code> files
2151: under <code class="filename">share/applications</code> and these include
1.29 rodent 2152: MIME information (MimeType key), you need to take extra steps to
2153: ensure that they are registered into the MIME database:</p>
1.15 wiz 2154: <div class="orderedlist"><ol class="orderedlist" type="1">
2155: <li class="listitem"><p>Include
1.1 dsieger 2156: <code class="filename">../../sysutils/desktop-file-utils/desktopdb.mk</code>.</p></li>
1.15 wiz 2157: <li class="listitem"><p>Check the PLIST and remove the entry that refers to the
1.1 dsieger 2158: <code class="filename">share/applications/mimeinfo.cache</code> file.
2159: It will be handled automatically.</p></li>
2160: </ol></div>
2161: <p>The best way to verify that the PLIST is correct with
1.7 hubertf 2162: respect to the last point is to regenerate it using <span class="command"><strong>make
1.1 dsieger 2163: print-PLIST</strong></span>.</p>
2164: </div>
2165: </div>
1.24 asau 2166: <div class="sect1">
1.1 dsieger 2167: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 2168: <a name="punting"></a>21.7. Marking packages as having problems</h2></div></div></div>
1.1 dsieger 2169: <p>In some cases one does not have the time to solve a problem
1.14 jakllsch 2170: immediately. In this case, one can plainly mark a package as broken. For
2171: this, one just sets the variable <code class="varname">BROKEN</code> to the
2172: reason why the package is broken (similar to the
1.66 rillig 2173: <code class="varname">PKG_FAIL_REASON</code> variable). A user trying to build
1.14 jakllsch 2174: the package will immediately be shown this message, and the build
2175: will not be even tried.</p>
2176: <p><code class="varname">BROKEN</code> packages are removed from pkgsrc in irregular
1.1 dsieger 2177: intervals.</p>
2178: </div>
2179: </div>
2180: <div class="navfooter">
2181: <hr>
2182: <table width="100%" summary="Navigation footer">
2183: <tr>
2184: <td width="40%" align="left">
1.76 rillig 2185: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
1.1 dsieger 2186: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1.76 rillig 2187: <td width="40%" align="right"> <a accesskey="n" href="gnome.html">Next</a>
1.1 dsieger 2188: </td>
2189: </tr>
2190: <tr>
1.76 rillig 2191: <td width="40%" align="left" valign="top">Chapter 20. The pkginstall framework </td>
1.1 dsieger 2192: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.76 rillig 2193: <td width="40%" align="right" valign="top"> Chapter 22. GNOME packaging and porting</td>
1.1 dsieger 2194: </tr>
2195: </table>
2196: </div>
2197: </body>
2198: </html>
CVSweb <webmaster@jp.NetBSD.org>