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

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

CVSweb <webmaster@jp.NetBSD.org>