Annotation of htdocs/docs/pkgsrc/fixes.html, revision 1.76
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.71 leot 118: <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0"><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.71 leot 374: <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1.i386+NetBSD-9.0"><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.71 leot 486: <p><a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1.i386+NetBSD-9.0"><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.71 leot 497: exported in <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_summary+5.i386+NetBSD-9.0"><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.71 leot 548: not be deleted using <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0"><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
803: <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sed+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> commands, like this:</p>
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.71 leot 923: <code class="literal">https://github.com/username/exampleproject/archive/v1.0.zip</code>,
1.68 rillig 924: then you are packaging a tagged release.</p>
1.40 tnn 925: <pre class="programlisting">
926: DISTNAME= exampleproject-1.0
1.41 tnn 927: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
928: #GITHUB_PROJECT= # can be omitted if same as DISTNAME
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.63 rillig 935: <a name="build.fetch.github.commit"></a>21.2.3.2. Fetch based on a specific commit</h4></div></div></div>
1.68 rillig 936: <p>If your distfile URL looks similar to
1.71 leot 937: <code class="literal">https://github.com​/example​/example​/archive​/988881adc9fc3655077dc2d4d757d480b5ea0e11.tar.gz</code>,
1.68 rillig 938: then you are packaging a specific commit not tied to a
939: release.</p>
1.40 tnn 940: <pre class="programlisting">
941: DISTNAME= example-1.0
1.49 jnemeth 942: MASTER_SITES= ${MASTER_SITE_GITHUB:=example/}
1.41 tnn 943: #GITHUB_PROJECT= # can be omitted if same as DISTNAME
944: GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
1.52 sevan 945: </pre>
1.40 tnn 946: </div>
947: <div class="sect3">
948: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 949: <a name="build.fetch.github.release"></a>21.2.3.3. Fetch based on release</h4></div></div></div>
1.68 rillig 950: <p>If your distfile URL looks similar to
1.71 leot 951: <code class="literal">https://github.com​/username/exampleproject​/releases​/download​/rel-1.6​/offensive-1.6.zip</code>,
1.68 rillig 952: then you are packaging a release.</p>
1.40 tnn 953: <pre class="programlisting">
954: DISTNAME= offensive-1.6
1.41 tnn 955: PKGNAME= ${DISTNAME:S/offensive/proper/}
956: MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
957: GITHUB_PROJECT= exampleproject
958: GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME}
959: EXTRACT_SUFX= .zip
1.52 sevan 960: </pre>
1.40 tnn 961: </div>
962: </div>
1.1 dsieger 963: </div>
1.24 asau 964: <div class="sect1">
1.1 dsieger 965: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 966: <a name="fixes.configure"></a>21.3. The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
1.24 asau 967: <div class="sect2">
1.1 dsieger 968: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 969: <a name="fixes.libtool"></a>21.3.1. Shared libraries - libtool</h3></div></div></div>
1.1 dsieger 970: <p>pkgsrc supports many different machines, with different
971: object formats like a.out and ELF, and varying abilities to do
972: shared library and dynamic loading at all. To accompany this,
973: varying commands and options have to be passed to the
974: compiler, linker, etc. to get the Right Thing, which can be
975: pretty annoying especially if you don't have all the machines
976: at your hand to test things. The
1.59 leot 977: <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 978: can help here, as it just <span class="quote">“<span class="quote">knows</span>”</span> how to build
1.1 dsieger 979: both static and dynamic libraries from a set of source files,
980: thus being platform-independent.</p>
981: <p>Here's how to use libtool in a package in seven simple
982: steps:</p>
1.15 wiz 983: <div class="orderedlist"><ol class="orderedlist" type="1">
984: <li class="listitem"><p>Add <code class="varname">USE_LIBTOOL=yes</code> to the package
1.1 dsieger 985: Makefile.</p></li>
1.15 wiz 986: <li class="listitem"><p>For library objects, use <span class="quote">“<span class="quote">${LIBTOOL} --mode=compile
987: ${CC}</span>”</span> in place of <span class="quote">“<span class="quote">${CC}</span>”</span>. You could even
1.1 dsieger 988: add it to the definition of <code class="varname">CC</code>, if only
989: libraries are being built in a given Makefile. This one command
990: will build both PIC and non-PIC library objects, so you need not
991: have separate shared and non-shared library rules.</p></li>
1.15 wiz 992: <li class="listitem">
1.1 dsieger 993: <p>For the linking of the library, remove any
1.15 wiz 994: <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
995: -Bshareable</span>”</span> commands, and instead use:</p>
1.1 dsieger 996: <pre class="programlisting">
997: ${LIBTOOL} --mode=link \
998: ${CC} -o ${.TARGET:.a=.la} \
999: ${OBJS:.o=.lo} \
1000: -rpath ${PREFIX}/lib \
1001: -version-info major:minor
1.52 sevan 1002: </pre>
1.1 dsieger 1003: <p>Note that the library is changed to have a
1004: <code class="filename">.la</code> extension, and the objects are
1005: changed to have a <code class="filename">.lo</code>
1006: extension. Change <code class="varname">OBJS</code> as
1007: necessary. This automatically creates all of the
1008: <code class="filename">.a</code>,
1009: <code class="filename">.so.major.minor</code>, and ELF symlinks (if
1010: necessary) in the build directory. Be sure to include
1.15 wiz 1011: <span class="quote">“<span class="quote">-version-info</span>”</span>, especially when major and
1.1 dsieger 1012: minor are zero, as libtool will otherwise strip off the
1013: shared library version.</p>
1014: <p>From the libtool manual:</p>
1015: <pre class="programlisting">
1016: So, libtool library versions are described by three integers:
1017:
1018: CURRENT
1019: The most recent interface number that this library implements.
1020:
1021: REVISION
1022: The implementation number of the CURRENT interface.
1023:
1024: AGE
1025: The difference between the newest and oldest interfaces that
1026: this library implements. In other words, the library implements
1027: all the interface numbers in the range from number `CURRENT -
1028: AGE' to `CURRENT'.
1029:
1030: If two libraries have identical CURRENT and AGE numbers, then the
1031: dynamic linker chooses the library with the greater REVISION number.
1.52 sevan 1032: </pre>
1.15 wiz 1033: <p>The <span class="quote">“<span class="quote">-release</span>”</span> option will produce
1.1 dsieger 1034: different results for a.out and ELF (excluding symlinks)
1035: in only one case. An ELF library of the form
1.15 wiz 1036: <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 1037: will have a symlink of
1.15 wiz 1038: <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 1039: on an a.out platform. This is handled
1040: automatically.</p>
1.15 wiz 1041: <p>The <span class="quote">“<span class="quote">-rpath argument</span>”</span> is the install
1.1 dsieger 1042: directory of the library being built.</p>
1043: <p>In the <code class="filename">PLIST</code>, include only the
1044: <code class="filename">.la</code> file, the other files will be
1045: added automatically.</p>
1046: </li>
1.15 wiz 1047: <li class="listitem">
1.1 dsieger 1048: <p>When linking shared object (<code class="filename">.so</code>)
1.71 leot 1049: files, i.e. files that are loaded via <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?dlopen+3.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">dlopen</span>(3)</span></a>, NOT
1.15 wiz 1050: shared libraries, use <span class="quote">“<span class="quote">-module
1051: -avoid-version</span>”</span> to prevent them getting version
1.1 dsieger 1052: tacked on.</p>
1053: <p>The <code class="filename">PLIST</code> file gets the
1054: <code class="filename">foo.so</code> entry.</p>
1055: </li>
1.15 wiz 1056: <li class="listitem">
1.1 dsieger 1057: <p>When linking programs that depend on these libraries
1058: <span class="emphasis"><em>before</em></span> they are installed, preface
1.71 leot 1059: the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?cc+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">cc</span>(1)</span></a> or <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?ld+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">ld</span>(1)</span></a> line with <span class="quote">“<span class="quote">${LIBTOOL}
1.15 wiz 1060: --mode=link</span>”</span>, and it will find the correct
1.1 dsieger 1061: libraries (static or shared), but please be aware that
1062: libtool will not allow you to specify a relative path in
1.15 wiz 1063: -L (such as <span class="quote">“<span class="quote">-L../somelib</span>”</span>), because it
1.1 dsieger 1064: expects you to change that argument to be the
1065: <code class="filename">.la</code> file. e.g.</p>
1066: <pre class="programlisting">
1067: ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
1.52 sevan 1068: </pre>
1.1 dsieger 1069: <p>should be changed to:</p>
1070: <pre class="programlisting">
1071: ${LIBTOOL} --mode=link ${CC} -o <em class="replaceable"><code>someprog</code></em> <em class="replaceable"><code>../somelib/somelib.la</code></em>
1.52 sevan 1072: </pre>
1.1 dsieger 1073: <p>and it will do the right thing with the libraries.</p>
1074: </li>
1.15 wiz 1075: <li class="listitem">
1.71 leot 1076: <p>When installing libraries, preface the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?install+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a>
1077: or <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?cp+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">cp</span>(1)</span></a> command with <span class="quote">“<span class="quote">${LIBTOOL}
1.15 wiz 1078: --mode=install</span>”</span>, and change the library name to
1.1 dsieger 1079: <code class="filename">.la</code>. e.g.</p>
1080: <pre class="programlisting">
1.14 jakllsch 1081: ${LIBTOOL} --mode=install ${BSD_INSTALL_LIB} ${SOMELIB:.a=.la} ${PREFIX}/lib
1.52 sevan 1082: </pre>
1.1 dsieger 1083: <p>This will install the static <code class="filename">.a</code>,
1084: shared library, any needed symlinks, and run
1.71 leot 1085: <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?ldconfig+8.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">ldconfig</span>(8)</span></a>.</p>
1.1 dsieger 1086: </li>
1.15 wiz 1087: <li class="listitem"><p>In your <code class="filename">PLIST</code>, include only
1.1 dsieger 1088: the <code class="filename">.la</code>
1089: file (this is a change from previous behaviour).</p></li>
1090: </ol></div>
1091: </div>
1.24 asau 1092: <div class="sect2">
1.1 dsieger 1093: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1094: <a name="using-libtool"></a>21.3.2. Using libtool on GNU packages that already support libtool</h3></div></div></div>
1.1 dsieger 1095: <p>Add <code class="varname">USE_LIBTOOL=yes</code> to the
1096: package Makefile. This will override the package's own libtool
1097: in most cases. For older libtool using packages, libtool is
1098: made by ltconfig script during the do-configure step; you can
1.7 hubertf 1099: check the libtool script location by doing <span class="command"><strong>make
1.1 dsieger 1100: configure; find work*/ -name libtool</strong></span>.</p>
1101: <p><code class="varname">LIBTOOL_OVERRIDE</code> specifies which libtool
1102: scripts, relative to <code class="varname">WRKSRC</code>, to override. By
1.15 wiz 1103: default, it is set to <span class="quote">“<span class="quote">libtool */libtool
1104: */*/libtool</span>”</span>. If this does not match the location of the
1.1 dsieger 1105: package's libtool script(s), set it as appropriate.</p>
1106: <p>If you do not need <code class="filename">*.a</code> static
1107: libraries built and installed, then use
1108: <code class="varname">SHLIBTOOL_OVERRIDE</code> instead.</p>
1109: <p>If your package makes use of the platform-independent library
1110: for loading dynamic shared objects, that comes with libtool
1111: (libltdl), you should include devel/libltdl/buildlink3.mk.</p>
1112: <p>Some packages use libtool incorrectly so that the package
1113: may not work or build in some circumstances. Some of the more
1114: common errors are:</p>
1.24 asau 1115: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1116: <li class="listitem">
1.1 dsieger 1117: <p>The inclusion of a shared object (-module) as a dependent library in an
1118: executable or library. This in itself isn't a problem if one of two things
1119: has been done:</p>
1.15 wiz 1120: <div class="orderedlist"><ol class="orderedlist" type="1">
1121: <li class="listitem"><p>The shared object is named correctly, i.e.
1.1 dsieger 1122: <code class="filename">libfoo.la</code>, not
1123: <code class="filename">foo.la</code></p></li>
1.15 wiz 1124: <li class="listitem"><p>The -dlopen option is used when linking an executable.</p></li>
1.1 dsieger 1125: </ol></div>
1126: </li>
1.15 wiz 1127: <li class="listitem"><p>The use of libltdl without the correct calls to initialisation routines.
1.1 dsieger 1128: The function lt_dlinit() should be called and the macro
1129: <code class="varname">LTDL_SET_PRELOADED_SYMBOLS</code> included in
1130: executables.</p></li>
1131: </ul></div>
1132: </div>
1.24 asau 1133: <div class="sect2">
1.1 dsieger 1134: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1135: <a name="autoconf-automake"></a>21.3.3. GNU Autoconf/Automake</h3></div></div></div>
1.1 dsieger 1136: <p>If a package needs GNU autoconf or automake to be executed
1137: to regenerate the configure script and Makefile.in makefile
1138: templates, then they should be executed in a pre-configure
1139: target.</p>
1140: <p>For packages that need only autoconf:</p>
1141: <pre class="programlisting">
1142: AUTOCONF_REQD= 2.50 # if default version is not good enough
1143: USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
1144: ...
1145:
1146: pre-configure:
1147: cd ${WRKSRC} && autoconf
1148:
1149: ...
1.52 sevan 1150: </pre>
1.1 dsieger 1151: <p>and for packages that need automake and autoconf:</p>
1152: <pre class="programlisting">
1153: AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
1154: USE_TOOLS+= automake # use "automake14" for automake-1.4
1155: ...
1156:
1157: pre-configure:
1158: set -e; cd ${WRKSRC}; \
1159: aclocal; autoheader; automake -a --foreign -i; autoconf
1160:
1161: ...
1.52 sevan 1162: </pre>
1.1 dsieger 1163: <p>Packages which use GNU Automake will almost certainly
1164: require GNU Make.</p>
1165: <p>There are times when the configure process makes
1166: additional changes to the generated files, which then causes
1167: the build process to try to re-execute the automake sequence.
1168: This is prevented by touching various files in the configure
1169: stage. If this causes problems with your package you can set
1170: <code class="varname">AUTOMAKE_OVERRIDE=NO</code> in the package
1171: Makefile.</p>
1172: </div>
1173: </div>
1.24 asau 1174: <div class="sect1">
1.1 dsieger 1175: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1176: <a name="programming-languages"></a>21.4. Programming languages</h2></div></div></div>
1.24 asau 1177: <div class="sect2">
1.1 dsieger 1178: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1179: <a name="basic-programming-languages"></a>21.4.1. C, C++, and Fortran</h3></div></div></div>
1.1 dsieger 1180: <p>Compilers for the C, C++, and Fortran languages comes with
1181: the NetBSD base system. By default, pkgsrc assumes that a package
1182: is written in C and will hide all other compilers (via the wrapper
1.76 ! rillig 1183: framework, see <a class="xref" href="buildlink.html" title="Chapter 18. Buildlink methodology">Chapter 18, <i>Buildlink methodology</i></a>).</p>
1.1 dsieger 1184: <p>To declare which language's compiler a package needs, set
1185: the <code class="varname">USE_LANGUAGES</code> variable. Allowed values
1.15 wiz 1186: currently are <span class="quote">“<span class="quote">c</span>”</span>, <span class="quote">“<span class="quote">c++</span>”</span>, and
1187: <span class="quote">“<span class="quote">fortran</span>”</span> (and any combination). The default is
1188: <span class="quote">“<span class="quote">c</span>”</span>. Packages using GNU configure scripts, even if
1.1 dsieger 1189: written in C++, usually need a C compiler for the configure
1190: phase.</p>
1191: </div>
1.24 asau 1192: <div class="sect2">
1.1 dsieger 1193: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1194: <a name="java-programming-language"></a>21.4.2. Java</h3></div></div></div>
1.1 dsieger 1195: <p>If a program is written in Java, use the Java framework in
1196: pkgsrc. The package must include
1197: <code class="filename">../../mk/java-vm.mk</code>. This Makefile fragment
1198: provides the following variables:</p>
1.24 asau 1199: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1200: <li class="listitem"><p><code class="varname">USE_JAVA</code> defines if a build
1.1 dsieger 1201: dependency on the JDK is added. If
1.15 wiz 1202: <code class="varname">USE_JAVA</code> is set to <span class="quote">“<span class="quote">run</span>”</span>, then
1.1 dsieger 1203: there is only a runtime dependency on the JDK. The default is
1.15 wiz 1204: <span class="quote">“<span class="quote">yes</span>”</span>, which also adds a build dependency on the
1.1 dsieger 1205: JDK.</p></li>
1.15 wiz 1206: <li class="listitem"><p>Set <code class="varname">USE_JAVA2</code> to declare that
1.1 dsieger 1207: a package needs a Java2 implementation. The supported values
1.15 wiz 1208: are <span class="quote">“<span class="quote">yes</span>”</span>, <span class="quote">“<span class="quote">1.4</span>”</span>, and
1209: <span class="quote">“<span class="quote">1.5</span>”</span>. <span class="quote">“<span class="quote">yes</span>”</span> accepts any Java2
1210: implementation, <span class="quote">“<span class="quote">1.4</span>”</span> insists on versions 1.4 or
1211: above, and <span class="quote">“<span class="quote">1.5</span>”</span> only accepts versions 1.5 or
1.1 dsieger 1212: above. This variable is not set by default.</p></li>
1.16 wiz 1213: <li class="listitem"><p><code class="varname">PKG_JAVA_HOME</code> is
1214: automatically set to the runtime location of the used Java
1215: implementation dependency. It may be used to set
1216: <code class="varname">JAVA_HOME</code> to a good value if the program
1217: needs this variable to be defined.
1218: </p></li>
1.1 dsieger 1219: </ul></div>
1220: </div>
1.24 asau 1221: <div class="sect2">
1.1 dsieger 1222: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1223: <a name="perl-scripts"></a>21.4.3. Packages containing perl scripts</h3></div></div></div>
1.1 dsieger 1224: <p>If your package contains interpreted perl scripts, add
1.15 wiz 1225: <span class="quote">“<span class="quote">perl</span>”</span> to the <code class="varname">USE_TOOLS</code> variable
1.1 dsieger 1226: and set <code class="varname">REPLACE_PERL</code> to ensure that the proper
1227: interpreter path is set. <code class="varname">REPLACE_PERL</code> should
1228: contain a list of scripts, relative to <code class="varname">WRKSRC</code>,
1.34 wiz 1229: that you want adjusted. Every occurrence of
1230: <code class="filename">*/bin/perl</code> in a she-bang line will be
1231: replaced with the full path to the perl executable.</p>
1.1 dsieger 1232: <p>If a particular version of perl is needed, set the
1233: <code class="varname">PERL5_REQD</code> variable to the version number. The
1.15 wiz 1234: default is <span class="quote">“<span class="quote">5.0</span>”</span>.</p>
1.63 rillig 1235: <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 1236: about handling perl modules.</p>
1237: </div>
1.24 asau 1238: <div class="sect2">
1.1 dsieger 1239: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1240: <a name="shell-scripts"></a>21.4.4. Packages containing shell scripts</h3></div></div></div>
1.23 wiz 1241: <p><code class="varname">REPLACE_SH</code>,
1242: <code class="varname">REPLACE_BASH</code>, <code class="varname">REPLACE_CSH</code>,
1243: and <code class="varname">REPLACE_KSH</code> can be used to replace shell
1244: hash bangs in files. Please use the appropriate one, prefering
1245: <code class="varname">REPLACE_SH</code> in case this shell is sufficient.
1.34 wiz 1246: Each should contain a list of scripts, relative to
1247: <code class="varname">WRKSRC</code>, that you want adjusted. Every
1248: occurrence of the matching shell in a she-bang line will be
1249: replaced with the full path to the shell executable.
1.23 wiz 1250: When using <code class="varname">REPLACE_BASH</code>, don't forget to add
1251: <code class="filename">bash</code> to <code class="varname">USE_TOOLS</code>.</p>
1252: </div>
1.24 asau 1253: <div class="sect2">
1.23 wiz 1254: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1255: <a name="other-programming-languages"></a>21.4.5. Other programming languages</h3></div></div></div>
1.1 dsieger 1256: <p>Currently, there is no special handling for other languages
1257: in pkgsrc. If a compiler package provides a
1258: <code class="filename">buildlink3.mk</code> file, include that, otherwise
1259: just add a (build) dependency on the appropriate compiler
1260: package.</p>
1261: </div>
1262: </div>
1.24 asau 1263: <div class="sect1">
1.1 dsieger 1264: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1265: <a name="fixes.build"></a>21.5. The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
1.1 dsieger 1266: <p>The most common failures when building a package are that
1267: some platforms do not provide certain header files, functions or
1268: libraries, or they provide the functions in a library that the
1269: original package author didn't know. To work around this, you
1270: can rewrite the source code in most cases so that it does not
1271: use the missing functions or provides a replacement function.</p>
1.24 asau 1272: <div class="sect2">
1.1 dsieger 1273: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1274: <a name="fixes.build.cpp"></a>21.5.1. Compiling C and C++ code conditionally</h3></div></div></div>
1.1 dsieger 1275: <p>If a package already comes with a GNU configure script, the
1276: preferred way to fix the build failure is to change the
1277: configure script, not the code. In the other cases, you can
1278: utilize the C preprocessor, which defines certain macros
1279: depending on the operating system and hardware architecture it
1280: compiles for. These macros can be queried using for example
1281: <code class="varname">#if defined(__i386)</code>. Almost every operating
1282: system, hardware architecture and compiler has its own macro.
1283: For example, if the macros <code class="varname">__GNUC__</code>,
1284: <code class="varname">__i386__</code> and <code class="varname">__NetBSD__</code>
1285: are all defined, you know that you are using NetBSD on an i386
1286: compatible CPU, and your compiler is GCC.</p>
1287: <p>The list of the following macros for hardware and
1288: operating system depends on the compiler that is used. For
1289: example, if you want to conditionally compile code on Solaris,
1290: don't use <code class="varname">__sun__</code>, as the SunPro compiler
1291: does not define it. Use <code class="varname">__sun</code> instead.</p>
1.24 asau 1292: <div class="sect3">
1.1 dsieger 1293: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1294: <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 1295: <p>To distinguish between 4.4 BSD-derived systems and the
1296: rest of the world, you should use the following code.</p>
1297: <pre class="programlisting">
1298: #include <sys/param.h>
1299: #if (defined(BSD) && BSD >= 199306)
1300: /* BSD-specific code goes here */
1301: #else
1302: /* non-BSD-specific code goes here */
1303: #endif
1304: </pre>
1305: <p>If this distinction is not fine enough, you can also test
1306: for the following macros.</p>
1307: <pre class="programlisting">
1.25 obache 1308: Cygwin __CYGWIN__
1309: DragonFly __DragonFly__
1.1 dsieger 1310: FreeBSD __FreeBSD__
1.25 obache 1311: Haiku __HAIKU__
1.1 dsieger 1312: Interix __INTERIX
1313: IRIX __sgi (TODO: get a definite source for this)
1314: Linux linux, __linux, __linux__
1.37 dholland 1315: Mac OS X __APPLE__
1.25 obache 1316: MirBSD __MirBSD__ (__OpenBSD__ is also defined)
1317: Minix3 __minix
1.1 dsieger 1318: NetBSD __NetBSD__
1319: OpenBSD __OpenBSD__
1320: Solaris sun, __sun
1321: </pre>
1322: </div>
1.24 asau 1323: <div class="sect3">
1.1 dsieger 1324: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1325: <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 1326: <pre class="programlisting">
1327: i386 i386, __i386, __i386__
1328: MIPS __mips
1329: SPARC sparc, __sparc
1330: </pre>
1331: </div>
1.24 asau 1332: <div class="sect3">
1.1 dsieger 1333: <div class="titlepage"><div><div><h4 class="title">
1.63 rillig 1334: <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 1335: <pre class="programlisting">
1336: GCC __GNUC__ (major version), __GNUC_MINOR__
1337: MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41)
1338: SunPro __SUNPRO_C (0x570 for Sun C 5.7)
1339: SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8)
1340: </pre>
1341: </div>
1342: </div>
1.24 asau 1343: <div class="sect2">
1.1 dsieger 1344: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1345: <a name="compiler-bugs"></a>21.5.2. How to handle compiler bugs</h3></div></div></div>
1.1 dsieger 1346: <p>Some source files trigger bugs in the compiler, based on
1347: combinations of compiler version and architecture and almost
1348: always relation to optimisation being enabled. Common symptoms
1349: are gcc internal errors or never finishing compiling a
1350: file.</p>
1351: <p>Typically, a workaround involves testing the
1352: <code class="varname">MACHINE_ARCH</code> and compiler version, disabling
1353: optimisation for that combination of file,
1.39 tnn 1354: <code class="varname">MACHINE_ARCH</code> and compiler.</p>
1355: <p>This used to be a big problem in the past, but is rarely
1356: needed now as compiler technology has matured. If you still need
1357: to add a compiler specific workaround, please do so in the file
1358: <code class="filename">hacks.mk</code> and describe the symptom and
1359: compiler version as detailed as possible.</p>
1.1 dsieger 1360: </div>
1.24 asau 1361: <div class="sect2">
1.1 dsieger 1362: <div class="titlepage"><div><div><h3 class="title">
1.69 rillig 1363: <a name="fixes.build.header"></a>21.5.3. No such file or directory</h3></div></div></div>
1364: <p>Compilation sometimes fails with an error message like this:</p>
1365: <pre class="programlisting">
1366: .../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
1367: fatal error: pango/pango.h: No such file or directory
1368: </pre>
1369: <p>The proper way to fix this problem depends on the type of the
1370: header, which is described in the following sections.</p>
1371: <div class="sect3">
1372: <div class="titlepage"><div><div><h4 class="title">
1373: <a name="fixes.build.header.bl3"></a>21.5.3.1. Headers from other packages</h4></div></div></div>
1374: <p>If the header name looks like it comes from a different package,
1375: that other package should be included via the buildlink3
1376: framework.</p>
1377: <p>First, look whether the header is somewhere in the buildlink3
1378: directory below <code class="varname">WRKDIR</code>. In the above case of
1379: the missing Pango header:</p>
1380: <pre class="programlisting">
1381: <code class="prompt">$</code> find work/.buildlink/ -print | grep -F pango/pango.h
1382: </pre>
1383: <p>In the case of Pango, the output is:</p>
1384: <pre class="programlisting">
1385: work/.buildlink/include/pango-1.0/pango/pango.h
1386: </pre>
1387: <p>If the <code class="filename">pango/pango.h</code> file were placed directly
1388: in the <code class="filename">.buildlink</code> directory, it would have been
1389: found automatically. There is an extra <code class="filename">pango-1.0</code>
1390: path component though, which means that the compiler command line must
1391: contain an option of the form
1392: <code class="literal">-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</code>. In
1393: most cases this option is generated by the configure script, which can be examined using:</p>
1394: <pre class="programlisting">
1395: <code class="prompt">$</code> $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile
1396: -I/usr/pkg/include/pango-1.0
1397: -I/usr/pkg/include/pango-1.0
1398: -I/usr/pkg/include/pango-1.0
1399: -I/usr/pkg/include/pango-1.0
1400: -I/usr/pkg/include/pango-1.0
1401: </pre>
1402: <p>This looks good. These options are transformed by the buildlink
1403: wrapper to refer to the correct path inside
1404: <code class="filename">work/.buildlink</code>.</p>
1405: <p>Since the compilation fails though, examine the compiler command
1406: lines in <code class="filename">work/.work.log</code> to see whether the
1407: <code class="literal">-I</code> option is included in the particular command
1408: line.</p>
1409: <p>To further analyze the situation, run <span class="command"><strong>bmake
1410: build-env</strong></span>, which sets up an interactive, realistic environment
1411: including all the pkgsrc wrapper commands and environment variables. From
1412: there, try to compile some simple example programs that use the
1413: header.</p>
1414: </div>
1415: <div class="sect3">
1416: <div class="titlepage"><div><div><h4 class="title">
1417: <a name="fixes.build.header.gen"></a>21.5.3.2. Headers generated during the build</h4></div></div></div>
1418: <p>If the name of the header seems to come from the package itself,
1419: and if the build is run with parallel jobs, the package may have some
1420: undeclared dependencies between the <code class="filename">.c</code> and the
1421: <code class="filename">.h</code> files, and a C file is compiled before its
1422: required header is generated.</p>
1423: <p>To see whether the build runs with parallel jobs, run
1424: <span class="command"><strong>bmake show-all-build | grep JOBS</strong></span>. Its output looks
1425: like this:</p>
1426: <pre class="programlisting">
1427: usr MAKE_JOBS= 7
1428: pkg MAKE_JOBS_SAFE # undefined
1429: def _MAKE_JOBS_N= 7
1430: </pre>
1431: <p>In this case the pkgsrc user has asked pkgsrc to build packages
1432: with 7 jobs in parallel (<code class="varname">MAKE_JOBS</code>). The
1433: package could have disabled parallel builds by setting
1434: <code class="varname">MAKE_JOBS_SAFE</code> to <code class="literal">no</code>, but
1435: in this case it hasn't.</p>
1436: <p>To see whether the build failure is caused by parallel builds,
1437: first save the exact error message and a bit of context, maybe you need
1438: it later for reporting a bug. Next, run:</p>
1439: <pre class="programlisting">
1440: MAKE_JOBS_SAFE=no bmake clean build
1441: </pre>
1442: <p>If that succeeds, <a class="ulink" href="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd" target="_top">file a bug
1443: report</a> against the pkgsrc package, including the exact error
1444: message and the contents of your <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> file.</p>
1445: </div>
1.70 rillig 1446: <div class="sect3">
1447: <div class="titlepage"><div><div><h4 class="title">
1448: <a name="fixes.build.header.symlink"></a>21.5.3.3. Symlinks</h4></div></div></div>
1449: <p>Pkgsrc does not work reliably if any of
1450: <code class="varname">LOCALBASE</code>, <code class="varname">VARBASE</code> or
1451: <code class="varname">WRKDIR</code> contains a symlink. Since 2019Q2, the pkgsrc
1452: bootstrap program prevents installing pkgsrc in symlink-based
1453: directories. Existing pkgsrc installations are not checked for symlinks
1454: though.</p>
1455: <p>The "No such file or directory" error messages are a typical
1456: symptom of symlinks, and it's quite difficult to find out that this is
1457: the actual cause.</p>
1458: </div>
1459: <div class="sect3">
1460: <div class="titlepage"><div><div><h4 class="title">
1461: <a name="fixes.build.header.stale"></a>21.5.3.4. Stale working directories</h4></div></div></div>
1462: <p>When building a hierarchy of packages, it may happen that one
1463: package is built and then pkgsrc is updated. This situation can provoke
1464: various hard to diagnose build errors. To clean up the situation:</p>
1465: <pre class="programlisting">
1466: <code class="prompt">$</code> (cd ../../ && test -f mk/bsd.pkg.mk && rm -rf */*/work)
1467: </pre>
1468: <p>(The test for <code class="filename">bsd.pkg.mk</code> just prevents running
1469: this command in the wrong directory.)</p>
1470: <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
1471: that directory as well.</p>
1472: </div>
1473: <div class="sect3">
1474: <div class="titlepage"><div><div><h4 class="title">
1475: <a name="fixes.build.header.misc"></a>21.5.3.5. Other possible reasons</h4></div></div></div>
1476: <p>On platforms other than BSD, third-party packages are installed in
1477: <code class="filename">/usr/include</code>, together with the base system. This
1478: means that pkgsrc cannot distinguish between headers provided by the base
1479: system (which it needs) and headers from third-party packages (which are
1480: often included in pkgsrc as well). This can lead to subtle version
1481: mismatches.</p>
1482: <p>In pkgsrc installations that have been active for several years, it
1483: may happen that some files are manually deleted. To exclude this unlikely
1484: reason, run <span class="command"><strong>pkg_admin check</strong></span>.</p>
1485: <p>It may help to run <span class="command"><strong>pkg_admin rebuild-tree</strong></span> to
1486: check/fix dependencies.</p>
1487: <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>
1488: for contact information. Be prepared to describe what you have tried so
1489: far and what any error messages were.</p>
1490: </div>
1.69 rillig 1491: </div>
1492: <div class="sect2">
1493: <div class="titlepage"><div><div><h3 class="title">
1494: <a name="undefined-reference"></a>21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span>
1.15 wiz 1495: </h3></div></div></div>
1.1 dsieger 1496: <p>This error message often means that a package did not
1497: link to a shared library it needs. The following functions are
1498: known to cause this error message over and over.</p>
1499: <div class="informaltable">
1.48 tnn 1500: <a name="undefined-reference-functions"></a><table class="informaltable" border="1">
1.1 dsieger 1501: <colgroup>
1502: <col>
1503: <col>
1504: <col>
1505: </colgroup>
1506: <thead><tr>
1507: <th>Function</th>
1508: <th>Library</th>
1509: <th>Affected platforms</th>
1510: </tr></thead>
1511: <tbody>
1512: <tr>
1513: <td>accept, bind, connect</td>
1514: <td>-lsocket</td>
1515: <td>Solaris</td>
1516: </tr>
1517: <tr>
1518: <td>crypt</td>
1519: <td>-lcrypt</td>
1520: <td>DragonFly, NetBSD</td>
1521: </tr>
1522: <tr>
1523: <td>dlopen, dlsym</td>
1524: <td>-ldl</td>
1525: <td>Linux</td>
1526: </tr>
1527: <tr>
1528: <td>gethost*</td>
1529: <td>-lnsl</td>
1530: <td>Solaris</td>
1531: </tr>
1532: <tr>
1533: <td>inet_aton</td>
1534: <td>-lresolv</td>
1535: <td>Solaris</td>
1536: </tr>
1537: <tr>
1538: <td>nanosleep, sem_*, timer_*</td>
1539: <td>-lrt</td>
1540: <td>Solaris</td>
1541: </tr>
1542: <tr>
1543: <td>openpty</td>
1544: <td>-lutil</td>
1545: <td>Linux</td>
1546: </tr>
1547: </tbody>
1548: </table>
1549: </div>
1550: <p>To fix these linker errors, it is often sufficient to say
1551: <code class="literal">LIBS.<em class="replaceable"><code>OperatingSystem</code></em>+=
1552: -l<em class="replaceable"><code>foo</code></em></code> to the package
1.7 hubertf 1553: <code class="filename">Makefile</code> and then say <span class="command"><strong>bmake clean;
1.1 dsieger 1554: bmake</strong></span>.</p>
1.24 asau 1555: <div class="sect3">
1.1 dsieger 1556: <div class="titlepage"><div><div><h4 class="title">
1.69 rillig 1557: <a name="undefined-reference-sunpro"></a>21.5.4.1. Special issue: The SunPro compiler</h4></div></div></div>
1.1 dsieger 1558: <p>When you are using the SunPro compiler, there is another
1559: possibility. That compiler cannot handle the following code:</p>
1560: <pre class="programlisting">
1561: extern int extern_func(int);
1562:
1563: static inline int
1564: inline_func(int x)
1565: {
1566: return extern_func(x);
1567: }
1568:
1569: int main(void)
1570: {
1571: return 0;
1572: }
1573: </pre>
1574: <p>It generates the code for <code class="function">inline_func</code> even if
1575: that function is never used. This code then refers to
1576: <code class="function">extern_func</code>, which can usually not be resolved. To
1577: solve this problem you can try to tell the package to disable inlining
1578: of functions.</p>
1579: </div>
1580: </div>
1.24 asau 1581: <div class="sect2">
1.1 dsieger 1582: <div class="titlepage"><div><div><h3 class="title">
1.69 rillig 1583: <a name="out-of-memory"></a>21.5.5. Running out of memory</h3></div></div></div>
1.1 dsieger 1584: <p>Sometimes packages fail to build because the compiler runs
1585: into an operating system specific soft limit. With the
1586: <code class="varname">UNLIMIT_RESOURCES</code> variable pkgsrc can be told
1.43 wiz 1587: to unlimit the resources. Currently, the allowed values are any combination of
1588: <span class="quote">“<span class="quote">cputime</span>”</span>, <span class="quote">“<span class="quote">datasize</span>”</span>,
1589: <span class="quote">“<span class="quote">memorysize</span>”</span>, and <span class="quote">“<span class="quote">stacksize</span>”</span>.
1.1 dsieger 1590: Setting this variable is similar to running the shell builtin
1.7 hubertf 1591: <span class="command"><strong>ulimit</strong></span> command to raise the maximum data
1.1 dsieger 1592: segment size or maximum stack size of a process, respectively, to
1593: their hard limits.</p>
1594: </div>
1595: </div>
1.24 asau 1596: <div class="sect1">
1.1 dsieger 1597: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 1598: <a name="fixes.install"></a>21.6. The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
1.24 asau 1599: <div class="sect2">
1.1 dsieger 1600: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1601: <a name="install-scripts"></a>21.6.1. Creating needed directories</h3></div></div></div>
1.7 hubertf 1602: <p>The BSD-compatible <span class="command"><strong>install</strong></span> supplied
1.1 dsieger 1603: with some operating systems cannot create more than one
1604: directory at a time. As such, you should call
1605: <code class="literal">${INSTALL_*_DIR}</code> like this:</p>
1606: <pre class="programlisting">
1607: ${INSTALL_DATA_DIR} ${PREFIX}/dir1
1608: ${INSTALL_DATA_DIR} ${PREFIX}/dir2
1.52 sevan 1609: </pre>
1.15 wiz 1610: <p>You can also just append <span class="quote">“<span class="quote"><code class="literal">dir1
1611: dir2</code></span>”</span> to the
1.1 dsieger 1612: <code class="varname">INSTALLATION_DIRS</code> variable, which will
1613: automatically do the right thing.</p>
1614: </div>
1.24 asau 1615: <div class="sect2">
1.1 dsieger 1616: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1617: <a name="where-to-install-documentation"></a>21.6.2. Where to install documentation</h3></div></div></div>
1.1 dsieger 1618: <p>In general, documentation should be installed into
1619: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1620: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code> (the latter
1621: includes the version number of the package).</p>
1622: <p>Many modern packages using GNU autoconf allow to set the
1623: directory where HTML documentation is installed with the
1.15 wiz 1624: <span class="quote">“<span class="quote">--with-html-dir</span>”</span> option. Sometimes using this flag
1.1 dsieger 1625: is needed because otherwise the documentation ends up in
1626: <code class="filename">${PREFIX}/share/doc/html</code> or other
1627: places.</p>
1628: <p>An exception to the above is that library API documentation
1.59 leot 1629: 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 1630: browsers (devhelp) should be left at their default location, which
1631: is <code class="filename">${PREFIX}/share/gtk-doc</code>. Such
1632: documentation can be recognized from files ending in
1633: <code class="filename">.devhelp</code> or <code class="filename">.devhelp2</code>.
1634: (It is also acceptable to install such files in
1635: <code class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
1636: <code class="filename">${PREFIX}/share/doc/${PKGNAME}</code>; the
1637: <code class="filename">.devhelp*</code> file must be directly in that
1638: directory then, no additional subdirectory level is allowed in
1639: this case. This is usually achieved by using
1.15 wiz 1640: <span class="quote">“<span class="quote">--with-html-dir=${PREFIX}/share/doc</span>”</span>.
1.1 dsieger 1641: <code class="filename">${PREFIX}/share/gtk-doc</code> is preferred
1642: though.)</p>
1643: </div>
1.24 asau 1644: <div class="sect2">
1.1 dsieger 1645: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1646: <a name="installing-score-files"></a>21.6.3. Installing highscore files</h3></div></div></div>
1.1 dsieger 1647: <p>Certain packages, most of them in the games category, install
1648: a score file that allows all users on the system to record their
1649: highscores. In order for this to work, the binaries need to be
1650: installed setgid and the score files owned by the appropriate
1.21 wiz 1651: group and/or owner (traditionally the "games" user/group). Set
1652: <code class="varname">USE_GAMESGROUP</code> to yes to support this. The
1.1 dsieger 1653: following variables, documented in more detail in
1654: <code class="filename">mk/defaults/mk.conf</code>, control this
1.21 wiz 1655: behaviour: <code class="varname">GAMEDATAMODE</code>,
1656: <code class="varname">GAMEDIRMODE</code>, <code class="varname">GAMES_GROUP</code>,
1.47 leot 1657: <code class="varname">GAMEMODE</code>, <code class="varname">GAME_USER</code>.
1658: Other useful variables are: <code class="varname">GAMEDIR_PERMS</code>,
1659: <code class="varname">GAMEDATA_PERMS</code> and
1660: <code class="varname">SETGID_GAMES_PERMS</code>.</p>
1661: <p>An example that illustrates some of the variables described above is
1662: <code class="filename">games/moon-buggy</code>. <code class="varname">OWN_DIRS_PERMS</code> is
1663: used to properly set directory permissions of the directory where the
1664: scorefile is saved, <code class="varname">REQD_FILES_PERMS</code> is used to create a
1665: dummy scorefile (<code class="filename">mbscore</code>) with the proper permissions
1666: and <code class="varname">SPECIAL_PERMS</code> is used to install setgid the game
1667: binary:</p>
1668: <pre class="programlisting">
1.53 rillig 1669: USE_GAMESGROUP= yes
1.47 leot 1670:
1.53 rillig 1671: BUILD_DEFS+= VARBASE
1.47 leot 1672:
1.53 rillig 1673: OWN_DIRS_PERMS+= ${VARBASE}/games/moon-buggy ${GAMEDIR_PERMS}
1674: REQD_FILES_PERMS+= /dev/null ${VARBASE}/games/moon-buggy/mbscore ${GAMEDATA_PERMS}
1675: SPECIAL_PERMS+= ${PREFIX}/bin/moon-buggy ${SETGID_GAMES_PERMS}
1.52 sevan 1676: </pre>
1.47 leot 1677: <p>Various <code class="varname">INSTALL_*</code> variables are also available:
1678: <code class="varname">INSTALL_GAME</code> to install setgid game binaries,
1679: <code class="varname">INSTALL_GAME_DIR</code> to install game directories that are
1680: needed to be accessed by setgid games and
1681: <code class="varname">INSTALL_GAME_DATA</code> to install scorefiles.</p>
1.9 jmcneill 1682: <p>A package should therefore never hard code file ownership or
1.47 leot 1683: access permissions but rely on <code class="varname">*_PERMS</code> as described above
1684: or alternatively on <code class="varname">INSTALL_GAME</code>,
1685: <code class="varname">INSTALL_GAME_DATA</code> and
1686: <code class="varname">INSTALL_GAME_DIR</code> to set these correctly.</p>
1.1 dsieger 1687: </div>
1.24 asau 1688: <div class="sect2">
1.1 dsieger 1689: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1690: <a name="destdir-support"></a>21.6.4. Adding DESTDIR support to packages</h3></div></div></div>
1.9 jmcneill 1691: <p><code class="varname">DESTDIR</code> support means that a package
1692: installs into a staging directory, not the final location of the
1693: files. Then a binary package is created which can be used for
1694: installation as usual. There are two ways: Either the package must
1.15 wiz 1695: install as root (<span class="quote">“<span class="quote">destdir</span>”</span>) or the package can
1696: install as non-root user (<span class="quote">“<span class="quote">user-destdir</span>”</span>).</p>
1.24 asau 1697: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1698: <li class="listitem"><p><code class="varname">PKG_DESTDIR_SUPPORT</code> has to be
1.54 leot 1699: set to <span class="quote">“<span class="quote">destdir</span>”</span> or <span class="quote">“<span class="quote">user-destdir</span>”</span>.
1700: By default <code class="varname">PKG_DESTDIR_SUPPORT</code>
1.22 wiz 1701: is set to <span class="quote">“<span class="quote">user-destdir</span>”</span> to help catching more
1702: potential packaging problems. If bsd.prefs.mk is included in the Makefile,
1.9 jmcneill 1703: <code class="varname">PKG_DESTDIR_SUPPORT</code> needs to be set before
1704: the inclusion.</p></li>
1.15 wiz 1705: <li class="listitem"><p>All installation operations have to be prefixed with
1.3 rillig 1706: <code class="filename">${DESTDIR}</code>.</p></li>
1.15 wiz 1707: <li class="listitem"><p>automake gets this DESTDIR mostly right
1.3 rillig 1708: automatically. Many manual rules and pre/post-install often are
1709: incorrect; fix them.</p></li>
1.15 wiz 1710: <li class="listitem"><p>If files are installed with special owner/group
1.11 imil 1711: use <code class="varname">SPECIAL_PERMS</code>.</p></li>
1.15 wiz 1712: <li class="listitem"><p>In general, packages should support
1.3 rillig 1713: <code class="varname">UNPRIVILEGED</code> to be able to use
1714: DESTDIR.</p></li>
1715: </ul></div>
1716: </div>
1.24 asau 1717: <div class="sect2">
1.3 rillig 1718: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1719: <a name="hardcoded-paths"></a>21.6.5. Packages with hardcoded paths to other interpreters</h3></div></div></div>
1.1 dsieger 1720: <p>Your package may also contain scripts with hardcoded paths to
1721: other interpreters besides (or as well as) perl. To correct the
1722: full pathname to the script interpreter, you need to set the
1723: following definitions in your <code class="filename">Makefile</code> (we
1.7 hubertf 1724: shall use <span class="command"><strong>tclsh</strong></span> in this example):</p>
1.1 dsieger 1725: <pre class="programlisting">
1726: REPLACE_INTERPRETER+= tcl
1727: REPLACE.tcl.old= .*/bin/tclsh
1728: REPLACE.tcl.new= ${PREFIX}/bin/tclsh
1729: REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed,
1730: # relative to ${WRKSRC}, just as in REPLACE_PERL
1.52 sevan 1731: </pre>
1.24 asau 1732: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 1733: <h3 class="title">Note</h3>
1734: <p>Before March 2006, these variables were called
1735: <code class="varname">_REPLACE.*</code> and
1736: <code class="varname">_REPLACE_FILES.*</code>.</p>
1737: </div>
1738: </div>
1.24 asau 1739: <div class="sect2">
1.1 dsieger 1740: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1741: <a name="perl-modules"></a>21.6.6. Packages installing perl modules</h3></div></div></div>
1.1 dsieger 1742: <p>Makefiles of packages providing perl5 modules should include
1743: the Makefile fragment
1744: <code class="filename">../../lang/perl5/module.mk</code>. It provides a
1.7 hubertf 1745: <span class="command"><strong>do-configure</strong></span> target for the standard perl
1.1 dsieger 1746: configuration for such modules as well as various hooks to tune
1747: this configuration. See comments in this file for
1748: details.</p>
1749: <p>Perl5 modules will install into different places depending
1750: on the version of perl used during the build process. To
1751: address this, pkgsrc will append lines to the
1752: <code class="filename">PLIST</code> corresponding to the files listed in
1753: the installed <code class="filename">.packlist</code> file generated by
1754: most perl5 modules. This is invoked by defining
1755: <code class="varname">PERL5_PACKLIST</code> to a space-separated list of
1.26 wiz 1756: packlist files relative to <code class="varname">PERL5_PACKLIST_DIR</code>
1757: (<code class="varname">PERL5_INSTALLVENDORARCH</code> by default),
1758: e.g.:</p>
1.1 dsieger 1759: <pre class="programlisting">
1.26 wiz 1760: PERL5_PACKLIST= auto/Pg/.packlist
1.52 sevan 1761: </pre>
1.26 wiz 1762: <p>The perl5 config variables
1763: <code class="varname">installarchlib</code>,
1764: <code class="varname">installscript</code>,
1765: <code class="varname">installvendorbin</code>,
1766: <code class="varname">installvendorscript</code>,
1767: <code class="varname">installvendorarch</code>,
1768: <code class="varname">installvendorlib</code>,
1769: <code class="varname">installvendorman1dir</code>, and
1770: <code class="varname">installvendorman3dir</code> represent those
1771: locations in which components of perl5 modules may be installed,
1772: provided as variable with uppercase and prefixed with
1773: <code class="varname">PERL5_</code>, e.g. <code class="varname">PERL5_INSTALLARCHLIB</code>
1774: and may be used by perl5 packages that don't have a packlist.
1775: These variables are also substituted for in the
1776: <code class="filename">PLIST</code> as uppercase prefixed with
1777: <code class="varname">PERL5_SUB_</code>.</p>
1.1 dsieger 1778: </div>
1.24 asau 1779: <div class="sect2">
1.1 dsieger 1780: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1781: <a name="faq.info-files"></a>21.6.7. Packages installing info files</h3></div></div></div>
1.1 dsieger 1782: <p>Some packages install info files or use the
1.15 wiz 1783: <span class="quote">“<span class="quote">makeinfo</span>”</span> or <span class="quote">“<span class="quote">install-info</span>”</span>
1.1 dsieger 1784: commands. <code class="varname">INFO_FILES</code> should be defined in
1785: the package Makefile so that <code class="filename">INSTALL</code> and
1786: <code class="filename">DEINSTALL</code> scripts will be generated to
1787: handle registration of the info files in the Info directory
1.15 wiz 1788: file. The <span class="quote">“<span class="quote">install-info</span>”</span> command used for the info
1.1 dsieger 1789: files registration is either provided by the system, or by a
1790: special purpose package automatically added as dependency if
1791: needed.</p>
1792: <p><code class="varname">PKGINFODIR</code> is the directory under
1793: <code class="filename">${PREFIX}</code> where info files are primarily
1794: located. <code class="varname">PKGINFODIR</code> defaults to
1.15 wiz 1795: <span class="quote">“<span class="quote">info</span>”</span> and can be overridden by the user.</p>
1.1 dsieger 1796: <p>The info files for the package should be listed in the
1797: package <code class="filename">PLIST</code>; however any split info files
1798: need not be listed.</p>
1.15 wiz 1799: <p>A package which needs the <span class="quote">“<span class="quote">makeinfo</span>”</span> command
1800: at build time must add <span class="quote">“<span class="quote">makeinfo</span>”</span> to
1.1 dsieger 1801: <code class="varname">USE_TOOLS</code> in its Makefile. If a minimum
1.15 wiz 1802: version of the <span class="quote">“<span class="quote">makeinfo</span>”</span> command is needed it
1.1 dsieger 1803: should be noted with the <code class="varname">TEXINFO_REQD</code>
1804: variable in the package <code class="filename">Makefile</code>. By
1805: default, a minimum version of 3.12 is required. If the system
1.7 hubertf 1806: does not provide a <span class="command"><strong>makeinfo</strong></span> command or if it
1.1 dsieger 1807: does not match the required minimum, a build dependency on the
1.59 leot 1808: <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 1809: be added automatically.</p>
1810: <p>The build and installation process of the software provided
1811: by the package should not use the
1.7 hubertf 1812: <span class="command"><strong>install-info</strong></span> command as the registration of
1.1 dsieger 1813: info files is the task of the package
1814: <code class="filename">INSTALL</code> script, and it must use the
1.7 hubertf 1815: appropriate <span class="command"><strong>makeinfo</strong></span> command.</p>
1.1 dsieger 1816: <p>To achieve this goal, the pkgsrc infrastructure creates
1.7 hubertf 1817: overriding scripts for the <span class="command"><strong>install-info</strong></span> and
1818: <span class="command"><strong>makeinfo</strong></span> commands in a directory listed early
1.1 dsieger 1819: in <code class="varname">PATH</code>.</p>
1.7 hubertf 1820: <p>The script overriding <span class="command"><strong>install-info</strong></span> has
1.1 dsieger 1821: no effect except the logging of a message. The script overriding
1.7 hubertf 1822: <span class="command"><strong>makeinfo</strong></span> logs a message and according to the
1.1 dsieger 1823: value of <code class="varname">TEXINFO_REQD</code> either runs the appropriate
1.7 hubertf 1824: <span class="command"><strong>makeinfo</strong></span> command or exit on error.</p>
1.1 dsieger 1825: </div>
1.24 asau 1826: <div class="sect2">
1.1 dsieger 1827: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1828: <a name="manpages"></a>21.6.8. Packages installing man pages</h3></div></div></div>
1.1 dsieger 1829: <p>All packages that install manual pages should install them
1830: into the same directory, so that there is one common place to look
1831: for them. In pkgsrc, this place is
1832: <code class="literal">${PREFIX}/${PKGMANDIR}</code>, and this expression
1833: should be used in packages. The default for
1834: <code class="varname">PKGMANDIR</code> is
1.15 wiz 1835: <span class="quote">“<span class="quote"><code class="filename">man</code></span>”</span>. Another often-used value
1836: is <span class="quote">“<span class="quote"><code class="filename">share/man</code></span>”</span>.</p>
1.24 asau 1837: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 1838: <h3 class="title">Note</h3>
1839: <p>The support for a custom <code class="varname">PKGMANDIR</code>
1840: is far from complete.</p>
1841: </div>
1842: <p>The <code class="filename">PLIST</code> files can just use
1843: <code class="filename">man/</code> as the top level directory for the man
1844: page file entries, and the pkgsrc framework will convert as
1845: needed. In all other places, the correct
1846: <code class="varname">PKGMANDIR</code> must be used.</p>
1847: <p>Packages that are
1848: configured with <code class="varname">GNU_CONFIGURE</code> set as
1.15 wiz 1849: <span class="quote">“<span class="quote">yes</span>”</span>, by default will use the
1.1 dsieger 1850: <code class="filename">./configure</code>
1851: --mandir switch to set where the man pages should be installed.
1852: The path is <code class="varname">GNU_CONFIGURE_MANDIR</code> which defaults
1853: to <code class="varname">${PREFIX}/${PKGMANDIR}</code>.</p>
1854: <p>Packages that use <code class="varname">GNU_CONFIGURE</code> but do not
1855: use --mandir, can set <code class="varname">CONFIGURE_HAS_MANDIR</code>
1.15 wiz 1856: to <span class="quote">“<span class="quote">no</span>”</span>.
1.1 dsieger 1857: Or if the <code class="filename">./configure</code> script uses
1858: a non-standard use of --mandir, you can set
1859: <code class="varname">GNU_CONFIGURE_MANDIR</code> as needed.</p>
1.76 ! rillig 1860: <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 1861: information on installation of compressed manual pages.</p>
1862: </div>
1.24 asau 1863: <div class="sect2">
1.1 dsieger 1864: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1865: <a name="gconf-data-files"></a>21.6.9. Packages installing GConf data files</h3></div></div></div>
1.1 dsieger 1866: <p>If a package installs <code class="filename">.schemas</code> or
1.5 rillig 1867: <code class="filename">.entries</code> files, used by GConf,
1.1 dsieger 1868: you need to take some extra steps to make sure they get registered
1869: in the database:</p>
1.15 wiz 1870: <div class="orderedlist"><ol class="orderedlist" type="1">
1871: <li class="listitem"><p>Include <code class="filename">../../devel/GConf/schemas.mk</code>
1.1 dsieger 1872: instead of its <code class="filename">buildlink3.mk</code> file. This
1.5 rillig 1873: takes care of rebuilding the GConf database at installation and
1.1 dsieger 1874: deinstallation time, and tells the package where to install
1.5 rillig 1875: GConf data files using some standard configure arguments. It
1.1 dsieger 1876: also disallows any access to the database directly from the
1877: package.</p></li>
1.15 wiz 1878: <li class="listitem"><p>Ensure that the package installs its
1.1 dsieger 1879: <code class="filename">.schemas</code> files under
1880: <code class="filename">${PREFIX}/share/gconf/schemas</code>. If they get
1881: installed under <code class="filename">${PREFIX}/etc</code>, you will
1882: need to manually patch the package.</p></li>
1.15 wiz 1883: <li class="listitem"><p>Check the PLIST and remove any entries under the etc/gconf
1.1 dsieger 1884: directory, as they will be handled automatically. See
1.63 rillig 1885: <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 1886: <li class="listitem"><p>Define the <code class="varname">GCONF_SCHEMAS</code> variable in
1.1 dsieger 1887: your <code class="filename">Makefile</code> with a list of all
1888: <code class="filename">.schemas</code> files installed by the package, if
1889: any. Names must not contain any directories in them.</p></li>
1.15 wiz 1890: <li class="listitem"><p>Define the <code class="varname">GCONF_ENTRIES</code> variable in
1.1 dsieger 1891: your <code class="filename">Makefile</code> with a
1892: list of all <code class="filename">.entries</code> files installed by the
1893: package, if any. Names must not contain any directories in
1894: them.</p></li>
1895: </ol></div>
1896: </div>
1.24 asau 1897: <div class="sect2">
1.1 dsieger 1898: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1899: <a name="scrollkeeper-data-files"></a>21.6.10. Packages installing scrollkeeper/rarian data files</h3></div></div></div>
1.1 dsieger 1900: <p>If a package installs <code class="filename">.omf</code> files, used by
1.12 mishka 1901: scrollkeeper/rarian, you need to take some extra steps to make sure they
1.1 dsieger 1902: get registered in the database:</p>
1.15 wiz 1903: <div class="orderedlist"><ol class="orderedlist" type="1">
1904: <li class="listitem"><p>Include
1.12 mishka 1905: <code class="filename">../../mk/omf-scrollkeeper.mk</code>
1906: instead of rarian's <code class="filename">buildlink3.mk</code> file. This
1.1 dsieger 1907: takes care of rebuilding the scrollkeeper database at
1908: installation and deinstallation time, and disallows any access
1909: to it directly from the package.</p></li>
1.15 wiz 1910: <li class="listitem"><p>Check the PLIST and remove any entries under the
1.1 dsieger 1911: <code class="filename">libdata/scrollkeeper</code> directory, as they
1912: will be handled automatically.</p></li>
1.15 wiz 1913: <li class="listitem"><p>Remove the <code class="filename">share/omf</code> directory from
1.12 mishka 1914: the PLIST. It will be handled by rarian. (<span class="command"><strong>make
1915: print-PLIST</strong></span> does this automatically.)</p></li>
1.1 dsieger 1916: </ol></div>
1917: </div>
1.24 asau 1918: <div class="sect2">
1.1 dsieger 1919: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1920: <a name="x11-fonts"></a>21.6.11. Packages installing X11 fonts</h3></div></div></div>
1.1 dsieger 1921: <p>If a package installs font files, you will need to rebuild
1922: the fonts database in the directory where they get installed at
1923: installation and deinstallation time. This can be automatically
1924: done by using the pkginstall framework.</p>
1925: <p>You can list the directories where fonts are installed in the
1926: <code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code>
1927: variables, where <em class="replaceable"><code>type</code></em> can be one of
1.15 wiz 1928: <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 1929: Also make sure that the database file
1930: <code class="filename">fonts.dir</code> is not listed in the PLIST.</p>
1931: <p>Note that you should not create new directories for fonts;
1932: instead use the standard ones to avoid that the user needs to
1933: manually configure his X server to find them.</p>
1934: </div>
1.24 asau 1935: <div class="sect2">
1.1 dsieger 1936: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1937: <a name="gtk2-modules"></a>21.6.12. Packages installing GTK2 modules</h3></div></div></div>
1.1 dsieger 1938: <p>If a package installs GTK2 immodules or loaders, you need to
1939: take some extra steps to get them registered in the GTK2 database
1940: properly:</p>
1.15 wiz 1941: <div class="orderedlist"><ol class="orderedlist" type="1">
1942: <li class="listitem"><p>Include
1.1 dsieger 1943: <code class="filename">../../x11/gtk2/modules.mk</code> instead of its
1944: <code class="filename">buildlink3.mk</code> file. This takes care of
1945: rebuilding the database at installation and deinstallation time.</p></li>
1.15 wiz 1946: <li class="listitem"><p>Set <code class="varname">GTK2_IMMODULES=YES</code> if
1.1 dsieger 1947: your package installs GTK2 immodules.</p></li>
1.15 wiz 1948: <li class="listitem"><p>Set <code class="varname">GTK2_LOADERS=YES</code> if your package installs
1.1 dsieger 1949: GTK2 loaders.</p></li>
1.15 wiz 1950: <li class="listitem">
1.1 dsieger 1951: <p>Patch the package to not touch any of the GTK2
1952: databases directly. These are:</p>
1.24 asau 1953: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.15 wiz 1954: <li class="listitem"><p><code class="filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p></li>
1955: <li class="listitem"><p><code class="filename">libdata/gtk-2.0/gtk.immodules</code></p></li>
1.1 dsieger 1956: </ul></div>
1957: </li>
1.15 wiz 1958: <li class="listitem"><p>Check the <code class="filename">PLIST</code> and remove
1.1 dsieger 1959: any entries under the <code class="filename">libdata/gtk-2.0</code>
1960: directory, as they will be handled automatically.</p></li>
1961: </ol></div>
1962: </div>
1.24 asau 1963: <div class="sect2">
1.1 dsieger 1964: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1965: <a name="sgml-xml-data"></a>21.6.13. Packages installing SGML or XML data</h3></div></div></div>
1.1 dsieger 1966: <p>If a package installs SGML or XML data files that need to be
1967: registered in system-wide catalogs (like DTDs, sub-catalogs,
1968: etc.), you need to take some extra steps:</p>
1.15 wiz 1969: <div class="orderedlist"><ol class="orderedlist" type="1">
1970: <li class="listitem"><p>Include
1.1 dsieger 1971: <code class="filename">../../textproc/xmlcatmgr/catalogs.mk</code> in
1972: your <code class="filename">Makefile</code>, which takes care of
1973: registering those files in system-wide catalogs at
1974: installation and deinstallation time.</p></li>
1.15 wiz 1975: <li class="listitem"><p>Set <code class="varname">SGML_CATALOGS</code> to the full path of
1.1 dsieger 1976: any SGML catalogs installed by the package.</p></li>
1.15 wiz 1977: <li class="listitem"><p>Set <code class="varname">XML_CATALOGS</code> to the full path of
1.1 dsieger 1978: any XML catalogs installed by the package.</p></li>
1.15 wiz 1979: <li class="listitem"><p>Set <code class="varname">SGML_ENTRIES</code> to individual entries
1.1 dsieger 1980: to be added to the SGML catalog. These come in groups of
1981: three strings; see xmlcatmgr(1) for more information
1982: (specifically, arguments recognized by the 'add' action).
1983: Note that you will normally not use this variable.</p></li>
1.15 wiz 1984: <li class="listitem"><p>Set <code class="varname">XML_ENTRIES</code> to individual entries
1.1 dsieger 1985: to be added to the XML catalog. These come in groups of three
1986: strings; see xmlcatmgr(1) for more information (specifically,
1987: arguments recognized by the 'add' action). Note that you will
1988: normally not use this variable.</p></li>
1989: </ol></div>
1990: </div>
1.24 asau 1991: <div class="sect2">
1.1 dsieger 1992: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 1993: <a name="mime-database"></a>21.6.14. Packages installing extensions to the MIME database</h3></div></div></div>
1.1 dsieger 1994: <p>If a package provides extensions to the MIME database by
1995: installing <code class="filename">.xml</code> files inside
1996: <code class="filename">${PREFIX}/share/mime/packages</code>, you
1997: need to take some extra steps to ensure that the database is kept
1998: consistent with respect to these new files:</p>
1.15 wiz 1999: <div class="orderedlist"><ol class="orderedlist" type="1">
2000: <li class="listitem"><p>Include
1.1 dsieger 2001: <code class="filename">../../databases/shared-mime-info/mimedb.mk</code>
2002: (avoid using the <code class="filename">buildlink3.mk</code> file from
2003: this same directory, which is reserved for inclusion from
2004: other <code class="filename">buildlink3.mk</code> files). It takes
2005: care of rebuilding the MIME database at installation and
2006: deinstallation time, and disallows any access to it directly
2007: from the package.</p></li>
1.15 wiz 2008: <li class="listitem"><p>Check the PLIST and remove any entries under the
1.1 dsieger 2009: <code class="filename">share/mime</code> directory,
2010: <span class="emphasis"><em>except</em></span> for files saved under
2011: <code class="filename">share/mime/packages</code>. The former are
2012: handled automatically by
2013: the update-mime-database program, but the latter are
2014: package-dependent and must be removed by the package that
2015: installed them in the first place.</p></li>
1.15 wiz 2016: <li class="listitem"><p>Remove any <code class="filename">share/mime/*</code> directories
1.1 dsieger 2017: from the PLIST. They will be handled by the shared-mime-info
2018: package.</p></li>
2019: </ol></div>
2020: </div>
1.24 asau 2021: <div class="sect2">
1.1 dsieger 2022: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2023: <a name="intltool"></a>21.6.15. Packages using intltool</h3></div></div></div>
1.1 dsieger 2024: <p>If a package uses intltool during its build, add
2025: <code class="literal">intltool</code> to the <code class="varname">USE_TOOLS</code>,
2026: which forces it to use the intltool package provided by pkgsrc,
2027: instead of the one bundled with the distribution file.</p>
2028: <p>This tracks intltool's build-time dependencies and uses the
2029: latest available version; this way, the package benefits of any
2030: bug fixes that may have appeared since it was released.</p>
2031: </div>
1.24 asau 2032: <div class="sect2">
1.1 dsieger 2033: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2034: <a name="startup-scripts"></a>21.6.16. Packages installing startup scripts</h3></div></div></div>
1.1 dsieger 2035: <p>If a package contains a rc.d script, it won't be copied into
2036: the startup directory by default, but you can enable it, by adding
2037: the option <code class="varname">PKG_RCD_SCRIPTS=YES</code> in
1.7 hubertf 2038: <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>. This option will copy the scripts
1.1 dsieger 2039: into <code class="filename">/etc/rc.d</code> when a package is installed, and
2040: it will automatically remove the scripts when the package is
2041: deinstalled.</p>
2042: </div>
1.24 asau 2043: <div class="sect2">
1.1 dsieger 2044: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2045: <a name="tex-packages"></a>21.6.17. Packages installing TeX modules</h3></div></div></div>
1.1 dsieger 2046: <p>If a package installs TeX packages into the texmf tree,
2047: the <code class="filename">ls-R</code> database of the tree needs to be
2048: updated.</p>
1.24 asau 2049: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1.1 dsieger 2050: <h3 class="title">Note</h3>
1.14 jakllsch 2051: <p>Except the main TeX packages such as kpathsea,
1.1 dsieger 2052: packages should install files
1.14 jakllsch 2053: into <code class="filename">${PREFIX}/share/texmf-dist</code>,
2054: not <code class="filename">${PREFIX}/share/texmf</code>.</p>
1.1 dsieger 2055: </div>
1.15 wiz 2056: <div class="orderedlist"><ol class="orderedlist" type="1">
2057: <li class="listitem"><p>Include
1.14 jakllsch 2058: <code class="filename">../../print/kpathsea/texmf.mk</code>. This
1.1 dsieger 2059: takes care of rebuilding the <code class="filename">ls-R</code>
2060: database at installation and deinstallation time.</p></li>
1.15 wiz 2061: <li class="listitem">
1.1 dsieger 2062: <p>If your package installs files into a texmf
2063: tree other than the one
1.14 jakllsch 2064: at <code class="filename">${PREFIX}/share/texmf-dist</code>,
2065: set <code class="varname">TEX_TEXMF_DIRS</code> to the list of all texmf
1.1 dsieger 2066: trees that need database update.</p>
2067: <p>If your package also installs font map files that need
1.7 hubertf 2068: to be registered using <span class="command"><strong>updmap</strong></span>,
1.18 dholland 2069: include <code class="filename">../../print/tex-tetex/map.mk</code> and
1.14 jakllsch 2070: set <code class="varname">TEX_MAP_FILES</code> and/or
2071: <code class="varname">TEX_MIXEDMAP_FILES</code> to the list of all
1.7 hubertf 2072: such font map files. Then <span class="command"><strong>updmap</strong></span> will
1.1 dsieger 2073: be run automatically at installation/deinstallation to
2074: enable/disable font map files for TeX output
2075: drivers.</p>
2076: </li>
1.15 wiz 2077: <li class="listitem"><p>Make sure that none of <code class="filename">ls-R</code>
1.1 dsieger 2078: databases are included in <code class="filename">PLIST</code>, as
1.18 dholland 2079: they will be removed only by the kpathsea package.</p></li>
1.1 dsieger 2080: </ol></div>
2081: </div>
1.24 asau 2082: <div class="sect2">
1.1 dsieger 2083: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2084: <a name="emulation-packages"></a>21.6.18. Packages supporting running binaries in
1.1 dsieger 2085: emulation</h3></div></div></div>
2086: <p>There are some packages that provide libraries and
2087: executables for running binaries from a one operating system
2088: on a different one (if the latter supports it). One example
2089: is running Linux binaries on NetBSD.</p>
1.59 leot 2090: <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 2091: helps in extracting and packaging Linux rpm packages.</p>
2092: <p>The <code class="varname">CHECK_SHLIBS</code> can be set to no to
1.7 hubertf 2093: avoid the <span class="command"><strong>check-shlibs</strong></span> target, which tests
1.1 dsieger 2094: if all libraries for each installed executable can be found by
2095: the dynamic linker. Since the standard dynamic linker is run,
2096: this fails for emulation packages, because the libraries used
2097: by the emulation are not in the standard directories.</p>
2098: </div>
1.24 asau 2099: <div class="sect2">
1.1 dsieger 2100: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2101: <a name="hicolor-theme"></a>21.6.19. Packages installing hicolor theme icons</h3></div></div></div>
1.1 dsieger 2102: <p>If a package installs images under the
2103: <code class="filename">share/icons/hicolor</code> and/or updates the
2104: <code class="filename">share/icons/hicolor/icon-theme.cache</code>
2105: database, you need to take some extra steps to make sure that the
2106: shared theme directory is handled appropriately and that the cache
2107: database is rebuilt:</p>
1.15 wiz 2108: <div class="orderedlist"><ol class="orderedlist" type="1">
2109: <li class="listitem"><p>Include
1.1 dsieger 2110: <code class="filename">../../graphics/hicolor-icon-theme/buildlink3.mk</code>.</p></li>
1.15 wiz 2111: <li class="listitem"><p>Check the <code class="filename">PLIST</code> and remove the
1.1 dsieger 2112: entry that refers to the theme cache.</p></li>
1.15 wiz 2113: <li class="listitem"><p>Ensure that the PLIST does not remove the shared icon
1.1 dsieger 2114: directories from the <code class="filename">share/icons/hicolor</code>
2115: hierarchy because they will be handled automatically.</p></li>
2116: </ol></div>
2117: <p>The best way to verify that the PLIST is correct with
2118: respect to the last two points is to regenerate it using
1.7 hubertf 2119: <span class="command"><strong>make print-PLIST</strong></span>.</p>
1.1 dsieger 2120: </div>
1.24 asau 2121: <div class="sect2">
1.1 dsieger 2122: <div class="titlepage"><div><div><h3 class="title">
1.63 rillig 2123: <a name="desktop-files"></a>21.6.20. Packages installing desktop files</h3></div></div></div>
1.1 dsieger 2124: <p>If a package installs <code class="filename">.desktop</code> files
2125: under <code class="filename">share/applications</code> and these include
1.29 rodent 2126: MIME information (MimeType key), you need to take extra steps to
2127: ensure that they are registered into the MIME database:</p>
1.15 wiz 2128: <div class="orderedlist"><ol class="orderedlist" type="1">
2129: <li class="listitem"><p>Include
1.1 dsieger 2130: <code class="filename">../../sysutils/desktop-file-utils/desktopdb.mk</code>.</p></li>
1.15 wiz 2131: <li class="listitem"><p>Check the PLIST and remove the entry that refers to the
1.1 dsieger 2132: <code class="filename">share/applications/mimeinfo.cache</code> file.
2133: It will be handled automatically.</p></li>
2134: </ol></div>
2135: <p>The best way to verify that the PLIST is correct with
1.7 hubertf 2136: respect to the last point is to regenerate it using <span class="command"><strong>make
1.1 dsieger 2137: print-PLIST</strong></span>.</p>
2138: </div>
2139: </div>
1.24 asau 2140: <div class="sect1">
1.1 dsieger 2141: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.63 rillig 2142: <a name="punting"></a>21.7. Marking packages as having problems</h2></div></div></div>
1.1 dsieger 2143: <p>In some cases one does not have the time to solve a problem
1.14 jakllsch 2144: immediately. In this case, one can plainly mark a package as broken. For
2145: this, one just sets the variable <code class="varname">BROKEN</code> to the
2146: reason why the package is broken (similar to the
1.66 rillig 2147: <code class="varname">PKG_FAIL_REASON</code> variable). A user trying to build
1.14 jakllsch 2148: the package will immediately be shown this message, and the build
2149: will not be even tried.</p>
2150: <p><code class="varname">BROKEN</code> packages are removed from pkgsrc in irregular
1.1 dsieger 2151: intervals.</p>
2152: </div>
2153: </div>
2154: <div class="navfooter">
2155: <hr>
2156: <table width="100%" summary="Navigation footer">
2157: <tr>
2158: <td width="40%" align="left">
1.76 ! rillig 2159: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
1.1 dsieger 2160: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1.76 ! rillig 2161: <td width="40%" align="right"> <a accesskey="n" href="gnome.html">Next</a>
1.1 dsieger 2162: </td>
2163: </tr>
2164: <tr>
1.76 ! rillig 2165: <td width="40%" align="left" valign="top">Chapter 20. The pkginstall framework </td>
1.1 dsieger 2166: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.76 ! rillig 2167: <td width="40%" align="right" valign="top"> Chapter 22. GNOME packaging and porting</td>
1.1 dsieger 2168: </tr>
2169: </table>
2170: </div>
2171: </body>
2172: </html>
CVSweb <webmaster@jp.NetBSD.org>