Annotation of htdocs/docs/pkgsrc/fixes.html, revision 1.78

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

CVSweb <webmaster@jp.NetBSD.org>