Annotation of htdocs/docs/pkgsrc/components.html, revision 1.61

1.32      sevan       1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1       dsieger     2: <html>
                      3: <head>
1.60      wiz         4: <meta charset="UTF-8">
1.59      martin      5: <title>Chapter 12. Package components - files, directories and contents</title>
1.14      spz         6: <link rel="stylesheet" type="text/css" href="/global.css">
1.1       dsieger     7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
1.10      rillig      8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.59      martin      9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
                     10: <link rel="prev" href="help-devel.html" title="Chapter 11. Getting help">
                     11: <link rel="next" href="build.html" title="Chapter 13. The build process">
1.1       dsieger    12: </head>
                     13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
                     14: <div class="navheader">
                     15: <table width="100%" summary="Navigation header">
1.59      martin     16: <tr><th colspan="3" align="center">Chapter 12. Package components - files, directories and contents</th></tr>
1.1       dsieger    17: <tr>
                     18: <td width="20%" align="left">
1.59      martin     19: <a accesskey="p" href="help-devel.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="build.html">Next</a>
1.1       dsieger    22: </td>
                     23: </tr>
                     24: </table>
                     25: <hr>
                     26: </div>
1.18      asau       27: <div class="chapter">
1.1       dsieger    28: <div class="titlepage"><div><div><h2 class="title">
1.59      martin     29: <a name="components"></a>Chapter 12. Package components - files, directories and contents</h2></div></div></div>
1.1       dsieger    30: <div class="toc">
                     31: <p><b>Table of Contents</b></p>
1.28      leot       32: <dl class="toc">
1.46      rillig     33: <dt><span class="sect1"><a href="components.html#components.Makefile">12.1. <code class="filename">Makefile</code></a></span></dt>
                     34: <dt><span class="sect1"><a href="components.html#components.distinfo">12.2. <code class="filename">distinfo</code></a></span></dt>
                     35: <dt><span class="sect1"><a href="components.html#components.patches">12.3. <code class="filename">patches/*</code></a></span></dt>
1.1       dsieger    36: <dd><dl>
1.46      rillig     37: <dt><span class="sect2"><a href="components.html#components.patch.structure">12.3.1. Structure of a single patch file</a></span></dt>
                     38: <dt><span class="sect2"><a href="components.html#components.patches.caveats">12.3.2. Creating patch files</a></span></dt>
                     39: <dt><span class="sect2"><a href="components.html#components.patches.sources">12.3.3. Sources where the patch files come from</a></span></dt>
                     40: <dt><span class="sect2"><a href="components.html#components.patches.guidelines">12.3.4. Patching guidelines</a></span></dt>
                     41: <dt><span class="sect2"><a href="components.html#components.patches.feedback">12.3.5. Feedback to the author</a></span></dt>
1.1       dsieger    42: </dl></dd>
1.46      rillig     43: <dt><span class="sect1"><a href="components.html#other-mandatory-files">12.4. Other mandatory files</a></span></dt>
                     44: <dt><span class="sect1"><a href="components.html#components.optional">12.5. Optional files</a></span></dt>
1.1       dsieger    45: <dd><dl>
1.46      rillig     46: <dt><span class="sect2"><a href="components.html#components.optional.bin">12.5.1. Files affecting the binary package</a></span></dt>
                     47: <dt><span class="sect2"><a href="components.html#components.optional.build">12.5.2. Files affecting the build process</a></span></dt>
                     48: <dt><span class="sect2"><a href="components.html#components.optional.none">12.5.3. Files affecting nothing at all</a></span></dt>
1.1       dsieger    49: </dl></dd>
1.46      rillig     50: <dt><span class="sect1"><a href="components.html#work-dir">12.6. <code class="filename">work*</code></a></span></dt>
                     51: <dt><span class="sect1"><a href="components.html#files-dir">12.7. <code class="filename">files/*</code></a></span></dt>
1.1       dsieger    52: </dl>
                     53: </div>
                     54: <p>Whenever you're preparing a package, there are a number of
                     55: files involved which are described in the following
                     56: sections.</p>
1.18      asau       57: <div class="sect1">
1.1       dsieger    58: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin     59: <a name="components.Makefile"></a>12.1. <code class="filename">Makefile</code>
1.1       dsieger    60: </h2></div></div></div>
                     61: <p>Building, installation and creation of a binary package are all
                     62:   controlled by the package's <code class="filename">Makefile</code>.
                     63:   The <code class="filename">Makefile</code> describes various things about
                     64:   a package, for example from where to get it, how to configure,
                     65:   build, and install it.</p>
                     66: <p>A package <code class="filename">Makefile</code> contains several
                     67:   sections that describe the package.</p>
                     68: <p>In the first section there are the following variables, which
                     69:   should appear exactly in the order given here.  The order and
                     70:   grouping of the variables is mostly historical and has no further
                     71:   meaning.</p>
1.18      asau       72: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.12      wiz        73: <li class="listitem"><p><code class="varname">DISTNAME</code> is the basename of the
1.1       dsieger    74:     distribution file to be downloaded from the package's
                     75:     website.</p></li>
1.12      wiz        76: <li class="listitem"><p><code class="varname">PKGNAME</code> is the name of the
1.19      asau       77:     package, as used by pkgsrc. You need to provide it if
1.1       dsieger    78:     <code class="varname">DISTNAME</code> (which is the default) is not a good
1.19      asau       79:     name for the package in pkgsrc or <code class="varname">DISTNAME</code> is not
                     80:     provided (no distribution file is required).  Usually it is the pkgsrc
1.1       dsieger    81:     directory name together with the version number. It must match the
                     82:     regular expression
                     83:     <code class="varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>, that is, it
                     84:     starts with a letter or digit, and contains only letters, digits,
1.50      nia        85:     dashes, underscores, dots and plus signs.
                     86:     New packages should have entirely lower-case names, with the exception
                     87:     of some that must follow pre-existing conventions
                     88:     (e.g. R packages begin with <code class="varname">R-</code>).
                     89:     You can use the <code class="code">:tl</code> variable modifier to lower-case
                     90:     the package name.</p></li>
1.12      wiz        91: <li class="listitem">
1.1       dsieger    92: <p><code class="varname">CATEGORIES</code> is a list of categories
                     93:     which the package fits in. You can choose any of the top-level
                     94:     directories of pkgsrc for it.</p>
                     95: <p>Currently the following values are available for
                     96:     <code class="varname">CATEGORIES</code>. If more than
                     97:     one is used, they need to be separated by spaces:</p>
                     98: <pre class="programlisting">
                     99: archivers     cross         geography     meta-pkgs     security
                    100: audio         databases     graphics      misc          shells
                    101: benchmarks    devel         ham           multimedia    sysutils
                    102: biology       editors       inputmethod   net           textproc
                    103: cad           emulators     lang          news          time
                    104: chat          finance       mail          parallel      wm
                    105: comms         fonts         math          pkgtools      www
                    106: converters    games         mbone         print         x11
                    107: </pre>
                    108: </li>
1.12      wiz       109: <li class="listitem"><p><code class="varname">MASTER_SITES</code>,
1.1       dsieger   110:     <code class="varname">DYNAMIC_MASTER_SITES</code>,
                    111:     <code class="varname">DIST_SUBDIR</code>, <code class="varname">EXTRACT_SUFX</code>
                    112:     and <code class="varname">DISTFILES</code> are discussed in detail in
1.59      martin    113:     <a class="xref" href="build.html#build.fetch" title="13.5. The fetch phase">Section 13.5, “The <span class="emphasis"><em>fetch</em></span> phase”</a>.</p></li>
1.1       dsieger   114: </ul></div>
                    115: <p>The second section contains information about separately
                    116:   downloaded patches, if any.
                    117:   </p>
1.18      asau      118: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.21      wiz       119: <li class="listitem"><p><code class="varname">PATCHFILES</code>:
1.1       dsieger   120:     Name(s) of additional files that contain distribution patches.
                    121:     There is no default. pkgsrc will look for them at
                    122:     <code class="varname">PATCH_SITES</code>.
                    123:     They will automatically be uncompressed before patching if
                    124:     the names end with <code class="filename">.gz</code> or
                    125:     <code class="filename">.Z</code>.</p></li>
1.12      wiz       126: <li class="listitem"><p><code class="varname">PATCH_SITES</code>:
1.1       dsieger   127:     Primary location(s) for distribution patch files (see
1.21      wiz       128:     <code class="varname">PATCHFILES</code> above) if not found locally.</p></li>
                    129: <li class="listitem"><p><code class="varname">PATCH_DIST_STRIP</code>:
1.58      leot      130:     an argument to <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/patch.1"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> that sets the pathname strip count to
1.21      wiz       131:     help find the correct files to patch. It defaults to
1.61    ! wiz       132:     <span class="command"><strong>-p1</strong></span>.</p></li>
1.1       dsieger   133: </ul></div>
                    134: <p>The third section contains the following variables.
                    135:   </p>
1.18      asau      136: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.55      gutterid  137: <li class="listitem"><p><code class="varname">MAINTAINER</code> is the email address
                    138:     of the person who is currently responsible for this package.  In
                    139:     theory, the maintainer will be aware of upstream release, keep it
                    140:     updated, and generally resolve problems.  Others contemplating
                    141:     significant changes should ask the maintainer for advice or review
                    142:     of a proposed change.  This is not necessary for micro updates,
                    143:     bug fixes, pkgsrc-wide changes affecting many packages, and other
                    144:     things expected to be uncontroversial.  It goes with this "should
                    145:     ask" that the maintainer should respond to inquiries reasonably
                    146:     promptly (most of the time), and either approve changes or provide
                    147:     reasons why not.  Typically, when packaging a new program, set
                    148:     <code class="varname">MAINTAINER</code> to yourself.  If you don't intend to
                    149:     maintain the package (especially if you feel you have no special
                    150:     insight), set it to <code class="email">&lt;<a class="email" href="mailto:pkgsrc-users@NetBSD.org">pkgsrc-users@NetBSD.org</a>&gt;</code>.  This
                    151:     special value is a code point indicating that there is no
1.60      wiz       152:     maintainer.</p></li>
1.12      wiz       153: <li class="listitem"><p><code class="varname">HOMEPAGE</code> is a URL where users can
1.1       dsieger   154:     find more information about the package.</p></li>
1.12      wiz       155: <li class="listitem"><p><code class="varname">COMMENT</code> is a one-line
1.1       dsieger   156:     description of the package (should not include the package
                    157:     name).</p></li>
1.33      leot      158: <li class="listitem"><p><code class="varname">LICENSE</code> indicates the license(s)
1.59      martin    159:     applicable for the package. See <a class="xref" href="fixes.html#handling-licenses" title="21.1.3. Handling licenses">Section 21.1.3, “Handling licenses”</a> for further details.</p></li>
1.1       dsieger   160: </ul></div>
                    161: <p>Other variables that affect the build:
                    162:   </p>
1.18      asau      163: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
1.1       dsieger   164: <p><code class="varname">WRKSRC</code>: The directory where the
                    165:       interesting distribution files of the package are found. The
                    166:       default is <code class="filename">${WRKDIR}/${DISTNAME}</code>, which
                    167:       works for most packages.</p>
                    168: <p>If a package doesn't create a subdirectory for itself
                    169:       (most GNU software does, for instance), but extracts itself in
                    170:       the current directory, you should set
                    171:       <code class="varname">WRKSRC=${WRKDIR}</code>.</p>
                    172: <p>If a package doesn't create a subdirectory with the
                    173:       name of <code class="varname">DISTNAME</code> but some different name,
                    174:       set <code class="varname">WRKSRC</code> to point to the proper name in
                    175:       <code class="filename">${WRKDIR}</code>, for example
                    176:       <code class="varname">WRKSRC=${WRKDIR}/${DISTNAME}/unix</code>. See
1.51      leot      177:       <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/tcl/index.html" target="_top"><code class="filename">lang/tcl</code></a> and <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/tk/index.html" target="_top"><code class="filename">x11/tk</code></a> for other examples.</p>
1.1       dsieger   178: <p>The name of the working directory created by pkgsrc is
                    179:       taken from the <code class="varname">WRKDIR_BASENAME</code>
                    180:       variable. By default, its value is
                    181:       <code class="filename">work</code>. If you want to use the same
                    182:       pkgsrc tree for building different kinds of binary packages,
                    183:       you can change the variable according to your needs. Two
                    184:       other variables handle common cases of setting
                    185:       <code class="varname">WRKDIR_BASENAME</code> individually. If
                    186:       <code class="varname">OBJHOSTNAME</code> is defined in
1.6       hubertf   187:       <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>, the first component of
1.1       dsieger   188:       the host's name is attached to the directory name. If
                    189:       <code class="varname">OBJMACHINE</code> is defined, the platform name
                    190:       is attached, which might look like
                    191:       <code class="filename">work.i386</code> or
                    192:       <code class="filename">work.sparc</code>.</p>
                    193: </li></ul></div>
                    194: <p>Please pay attention to the following gotchas:</p>
1.18      asau      195: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.12      wiz       196: <li class="listitem"><p>Add <code class="varname">MANCOMPRESSED</code> if man pages are
1.1       dsieger   197:       installed in compressed form by the package.  For packages using
                    198:       BSD-style makefiles which honor MANZ, there is
                    199:       <code class="varname">MANCOMPRESSED_IF_MANZ</code>.</p></li>
1.12      wiz       200: <li class="listitem"><p>Replace <code class="filename">/usr/local</code> with
1.59      martin    201:       <span class="quote">“<span class="quote">${PREFIX}</span>”</span> in all files (see patches,
1.1       dsieger   202:       below).</p></li>
1.59      martin    203: <li class="listitem"><p>If the package installs any info files, see <a class="xref" href="fixes.html#faq.info-files" title="21.6.8. Packages installing info files">Section 21.6.8, “Packages installing info files”</a>.</p></li>
1.1       dsieger   204: </ul></div>
                    205: </div>
1.18      asau      206: <div class="sect1">
1.1       dsieger   207: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    208: <a name="components.distinfo"></a>12.2. <code class="filename">distinfo</code>
1.1       dsieger   209: </h2></div></div></div>
                    210: <p>The <code class="filename">distinfo</code> file contains the message
                    211:   digest, or checksum, of each distfile needed for the package. This
                    212:   ensures that the distfiles retrieved from the Internet have not been
                    213:   corrupted during transfer or altered by a malign force to introduce
1.30      rillig    214:   a security hole. To provide maximum security, all distfiles are
1.53      gutterid  215:   protected using two different message digest algorithms (BLAKE2s
                    216:   and SHA512), as well as the file size.</p>
1.1       dsieger   217: <p>The <code class="filename">distinfo</code> file also contains the
                    218:   checksums for all the patches found in the
1.59      martin    219:   <code class="filename">patches</code> directory (see <a class="xref" href="components.html#components.patches" title="12.3. patches/*">Section 12.3, “<code class="filename">patches/*</code>”</a>). These checksums ensure that patches
1.38      leot      220:   are only applied intentionally and that they don't accidentally change,
                    221:   e.g. when merging different changes together. They also make sure that
                    222:   new patches are actually added to CVS and old ones are removed.
                    223:   Too see whether the patches and the <code class="filename">distinfo</code> file
                    224:   match, run <span class="command"><strong>pkglint</strong></span> after changing the patches.</p>
1.1       dsieger   225: <p>To regenerate the <code class="filename">distinfo</code> file, use the
1.30      rillig    226:   <span class="command"><strong>make distinfo</strong></span> command.</p>
1.1       dsieger   227: <p>Some packages have different sets of distfiles depending on
1.51      leot      228:   the platform, for example <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/openjdk8/index.html" target="_top"><code class="filename">lang/openjdk8</code></a>. These are kept in the same
1.1       dsieger   229:   <code class="filename">distinfo</code> file and care should be taken when
                    230:   upgrading such a package to ensure distfile information is not
                    231:   lost.</p>
                    232: </div>
1.18      asau      233: <div class="sect1">
1.1       dsieger   234: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    235: <a name="components.patches"></a>12.3. <code class="filename">patches/*</code>
1.30      rillig    236: </h2></div></div></div>
                    237: <p>Some packages don't work out-of-the box on the various
                    238:   platforms that are supported by pkgsrc. These packages need
                    239:   to be patched to make them work. The patch files can be
1.1       dsieger   240:   found in the <code class="filename">patches/</code> directory.</p>
                    241: <p>In the <span class="emphasis"><em>patch</em></span> phase, these patches are
                    242:   applied to the files in <code class="varname">WRKSRC</code> directory after
1.30      rillig    243:   extracting them, in alphabetic order.</p>
1.18      asau      244: <div class="sect2">
1.1       dsieger   245: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    246: <a name="components.patch.structure"></a>12.3.1. Structure of a single patch file</h3></div></div></div>
1.1       dsieger   247: <p>The <code class="filename">patch-*</code> files should be in
1.6       hubertf   248:   <span class="command"><strong>diff -bu</strong></span> format, and apply without a fuzz to avoid
1.1       dsieger   249:   problems. (To force patches to apply with fuzz you can set
                    250:   <code class="varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, each patch
                    251:   should contain only changes for a single file, and no file should be
                    252:   patched by more than one patch file. This helps to keep future
                    253:   modifications simple.</p>
                    254: <p>Each patch file is structured as follows: In the first line,
                    255:   there is the RCS Id of the patch itself. The second line should be
                    256:   empty for aesthetic reasons. After that, there should be a comment for
                    257:   each change that the patch does. There are a number of standard
                    258:   cases:</p>
1.18      asau      259: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.12      wiz       260: <li class="listitem"><p>Patches for commonly known vulnerabilities should
1.1       dsieger   261:   mention the vulnerability ID (CAN, CVE).</p></li>
1.12      wiz       262: <li class="listitem"><p>Patches that change source code should mention the
1.1       dsieger   263:   platform and other environment (for example, the compiler) that the
                    264:   patch is needed for.</p></li>
                    265: </ul></div>
1.30      rillig    266: <p>The patch should be commented so that any
1.1       dsieger   267:   developer who knows the code of the application can make some use of
                    268:   the patch. Special care should be taken for the upstream developers,
                    269:   since we generally want that they accept our patches, so we have less
                    270:   work in the future.</p>
                    271: </div>
1.18      asau      272: <div class="sect2">
1.1       dsieger   273: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    274: <a name="components.patches.caveats"></a>12.3.2. Creating patch files</h3></div></div></div>
1.1       dsieger   275: <p>One important thing to mention is to pay attention that no RCS
                    276:   IDs get stored in the patch files, as these will cause problems when
                    277:   later checked into the NetBSD CVS tree. Use the
1.51      leot      278:   <span class="command"><strong>pkgdiff</strong></span> command from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/index.html" target="_top"><code class="filename">pkgtools/pkgdiff</code></a> package to avoid these
1.1       dsieger   279:   problems.</p>
                    280: <p>For even more automation, we recommend using
1.6       hubertf   281:   <span class="command"><strong>mkpatches</strong></span> from the same package to make a
1.52      gutterid  282:   whole set of patches. You just have to back up files before you
                    283:   edit them to <code class="filename">filename.orig</code>, e.g., with
1.6       hubertf   284:   <span class="command"><strong>cp -p filename filename.orig</strong></span> or, easier, by
                    285:   using <span class="command"><strong>pkgvi</strong></span> again from the same package. If
1.1       dsieger   286:   you upgrade a package this way, you can easily compare the new
                    287:   set of patches with the previously existing one with
1.13      wiz       288:   <span class="command"><strong>patchdiff</strong></span>. The files in <code class="filename">patches</code>
                    289:   are replaced by new files, so carefully check if you want to take all
                    290:   the changes.</p>
1.1       dsieger   291: <p>When you have finished a package, remember to generate
1.6       hubertf   292:   the checksums for the patch files by using the <span class="command"><strong>make
1.59      martin    293:   makepatchsum</strong></span> command, see <a class="xref" href="components.html#components.distinfo" title="12.2. distinfo">Section 12.2, “<code class="filename">distinfo</code>”</a>.</p>
1.1       dsieger   294: <p>When adding a patch that corrects a problem in the
                    295:   distfile (rather than e.g. enforcing pkgsrc's view of where
                    296:   man pages should go), send the patch as a bug report to the
                    297:   maintainer.  This benefits non-pkgsrc users of the package,
                    298:   and usually makes it possible to remove the patch in future
                    299:   version.</p>
1.2       rillig    300: <p>The file names of the patch files are usually of the form
1.13      wiz       301:   <code class="filename">patch-<em class="replaceable"><code>path_to_file__with__underscores.c</code></em></code>.
                    302:   Many packages still use the previous convention
                    303:   <code class="filename">patch-<em class="replaceable"><code>[a-z][a-z]</code></em></code>,
                    304:   but new patches should be of the form containing the filename.
1.51      leot      305:   <span class="command"><strong>mkpatches</strong></span> included in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/index.html" target="_top"><code class="filename">pkgtools/pkgdiff</code></a> takes care of the name
1.13      wiz       306:   automatically.</p>
1.52      gutterid  307: <p>When updating pre-existing patch files, if a file uses the old
                    308:   <code class="filename">patch-<em class="replaceable"><code>[a-z][a-z]</code></em></code>
                    309:   convention, it's best not to change it to the new form, as that will
                    310:   just cause churn that makes it harder to track changes to patching
                    311:   over time. Similarly, if a patch now applies at different line offsets,
                    312:   but still applies cleanly as-is, there's no need to update it, as that
                    313:   also unnecessarily complicates the patch history.</p>
1.1       dsieger   314: </div>
1.18      asau      315: <div class="sect2">
1.1       dsieger   316: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    317: <a name="components.patches.sources"></a>12.3.3. Sources where the patch files come from</h3></div></div></div>
1.1       dsieger   318: <p>If you want to share patches between multiple packages
                    319:   in pkgsrc, e.g. because they use the same distfiles, set
                    320:   <code class="varname">PATCHDIR</code> to the path where the patch files
                    321:   can be found, e.g.:</p>
                    322: <pre class="programlisting">
1.41      rillig    323: PATCHDIR=       ../../editors/xemacs/patches
1.1       dsieger   324: </pre>
                    325: <p>Patch files that are distributed by the author or other
                    326:     maintainers can be listed in
                    327:     <code class="varname">PATCHFILES</code>.</p>
                    328: <p>If it is desired to store any patches that should not be
                    329:     committed into pkgsrc, they can be kept outside the pkgsrc
                    330:     tree in the <code class="filename">$LOCALPATCHES</code> directory. The
                    331:     directory tree there is expected to have the same
1.59      martin    332:     <span class="quote">“<span class="quote">category/package</span>”</span> structure as pkgsrc, and
1.1       dsieger   333:     patches are expected to be stored inside these dirs (also
                    334:     known as <code class="filename">$LOCALPATCHES/$PKGPATH</code>). For
                    335:     example, if you want to keep a private patch for
                    336:     <code class="filename">pkgsrc/graphics/png</code>, keep it in
                    337:     <code class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
                    338:     files in the named directory are expected to be patch files,
                    339:     and <span class="emphasis"><em>they are applied after pkgsrc patches are
                    340:     applied</em></span>.</p>
                    341: </div>
1.18      asau      342: <div class="sect2">
1.1       dsieger   343: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    344: <a name="components.patches.guidelines"></a>12.3.4. Patching guidelines</h3></div></div></div>
1.1       dsieger   345: <p>When fixing a portability issue in the code do not use
                    346:       preprocessor magic to check for the current operating system nor
                    347:       platform.  Doing so hurts portability to other platforms because
                    348:       the OS-specific details are not abstracted appropriately.</p>
                    349: <p>The general rule to follow is: instead of checking for the
                    350:       operating system the application is being built on, check for the
                    351:       specific <span class="emphasis"><em>features</em></span> you need.  For example,
                    352:       instead of assuming that kqueue is available under NetBSD and
                    353:       using the <code class="varname">__NetBSD__</code> macro to conditionalize
1.9       jmcneill  354:       kqueue support, add a check that detects kqueue itself &mdash;
1.1       dsieger   355:       yes, this generally involves patching the
1.6       hubertf   356:       <span class="command"><strong>configure</strong></span> script.  There is absolutely nothing
1.1       dsieger   357:       that prevents some OSes from adopting interfaces from other OSes
                    358:       (e.g. Linux implementing kqueue), something that the above checks
                    359:       cannot take into account.</p>
                    360: <p>Of course, checking for features generally involves more
                    361:       work on the developer's side, but the resulting changes are
                    362:       cleaner and there are chances they will work on many other
                    363:       platforms.  Not to mention that there are higher chances of being
                    364:       later integrated into the mainstream sources.  Remember:
                    365:       <span class="emphasis"><em>It doesn't work unless it is right!</em></span></p>
                    366: <p>Some typical examples:</p>
                    367: <div class="table">
1.59      martin    368: <a name="patch-examples"></a><p class="title"><b>Table 12.1. Patching examples</b></p>
1.29      tnn       369: <div class="table-contents"><table class="table" summary="Patching examples" border="1">
1.1       dsieger   370: <colgroup>
                    371: <col>
                    372: <col>
                    373: <col>
                    374: </colgroup>
                    375: <thead><tr>
                    376: <th>Where</th>
                    377: <th>Incorrect</th>
                    378: <th>Correct</th>
                    379: </tr></thead>
                    380: <tbody>
                    381: <tr>
                    382: <td>configure script</td>
                    383: <td>
                    384: <pre class="programlisting">
                    385: case ${target_os} in
                    386: netbsd*) have_kvm=yes ;;
                    387: *)       have_kvm=no  ;;
                    388: esac
                    389: </pre>
                    390:              </td>
                    391: <td>
                    392: <pre class="programlisting">
                    393: AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)
                    394: </pre>
                    395:              </td>
                    396: </tr>
                    397: <tr>
                    398: <td>C source file</td>
                    399: <td>
                    400: <pre class="programlisting">
                    401: #if defined(__NetBSD__)
                    402: #  include &lt;sys/event.h&gt;
                    403: #endif
                    404: </pre>
                    405:              </td>
                    406: <td>
                    407: <pre class="programlisting">
                    408: #if defined(HAVE_SYS_EVENT_H)
                    409: #  include &lt;sys/event.h&gt;
                    410: #endif
                    411: </pre>
                    412:              </td>
                    413: </tr>
                    414: <tr>
                    415: <td>C source file</td>
                    416: <td>
                    417: <pre class="programlisting">
                    418: int
                    419: monitor_file(...)
                    420: {
                    421: #if defined(__NetBSD__)
                    422:         int fd = kqueue();
                    423:         ...
                    424: #else
                    425:         ...
                    426: #endif
                    427: }
                    428: </pre>
                    429:              </td>
                    430: <td>
                    431: <pre class="programlisting">
                    432: int
                    433: monitor_file(...)
                    434: {
                    435: #if defined(HAVE_KQUEUE)
                    436:         int fd = kqueue();
                    437:         ...
                    438: #else
1.31      rillig    439:         ...
1.1       dsieger   440: #endif
                    441: }
                    442: </pre>
                    443:              </td>
                    444: </tr>
                    445: </tbody>
                    446: </table></div>
                    447: </div>
1.36      maya      448: <br class="table-break">
1.1       dsieger   449: </div>
1.18      asau      450: <div class="sect2">
1.1       dsieger   451: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    452: <a name="components.patches.feedback"></a>12.3.5. Feedback to the author</h3></div></div></div>
1.1       dsieger   453: <p>Always, always, <span class="strong"><strong>always</strong></span>
                    454:       feed back any <span class="emphasis"><em>portability fixes</em></span> or
                    455:       improvements you do to a package to the mainstream developers.
                    456:       This is the only way to get their attention on portability issues
                    457:       and to ensure that future versions can be built out-of-the box on
                    458:       NetBSD.  Furthermore, any user that gets newer distfiles will get
                    459:       the fixes straight from the packaged code.</p>
                    460: <p>This generally involves cleaning up the patches
                    461:       (because sometimes the patches that are
1.17      wiz       462:       added to pkgsrc are quick hacks), filing bug reports in the
1.1       dsieger   463:       appropriate trackers for the projects and working with the
                    464:       mainstream authors to accept your changes.  It is
                    465:       <span class="emphasis"><em>extremely important</em></span> that you do it so that
                    466:       the packages in pkgsrc are kept simple and thus further changes
                    467:       can be done without much hassle.</p>
1.13      wiz       468: <p>When you have done this, please add a URL to the upstream
                    469:       bug report to the patch comment.</p>
1.1       dsieger   470: <p>Support the idea of free software!</p>
                    471: </div>
                    472: </div>
1.18      asau      473: <div class="sect1">
1.1       dsieger   474: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    475: <a name="other-mandatory-files"></a>12.4. Other mandatory files</h2></div></div></div>
1.18      asau      476: <div class="variablelist"><dl class="variablelist">
1.1       dsieger   477: <dt><span class="term"><code class="filename">DESCR</code></span></dt>
                    478: <dd><p>A multi-line description of the piece of software.  This should include
                    479:          any credits where they are due.  Please bear in mind that others do not
                    480:          share your sense of humour (or spelling idiosyncrasies), and that others
                    481:          will read everything that you write here.</p></dd>
                    482: <dt><span class="term"><code class="filename">PLIST</code></span></dt>
                    483: <dd><p>This file governs the files that are installed on your
                    484:          system: all the binaries, manual pages, etc. There are other
                    485:          directives which may be entered in this file, to control the
                    486:          creation and deletion of directories, and the location of
1.59      martin    487:          inserted files.  See <a class="xref" href="plist.html" title="Chapter 19. PLIST issues">Chapter 19, <i>PLIST issues</i></a> for more
1.1       dsieger   488:          information.</p></dd>
                    489: </dl></div>
                    490: </div>
1.18      asau      491: <div class="sect1">
1.1       dsieger   492: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    493: <a name="components.optional"></a>12.5. Optional files</h2></div></div></div>
1.18      asau      494: <div class="sect2">
1.1       dsieger   495: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    496: <a name="components.optional.bin"></a>12.5.1. Files affecting the binary package</h3></div></div></div>
1.18      asau      497: <div class="variablelist"><dl class="variablelist">
1.1       dsieger   498: <dt><span class="term"><code class="filename">INSTALL</code></span></dt>
1.15      wiz       499: <dd>
1.58      leot      500: <p>This shell script is invoked twice by <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_add.1"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a>.
1.1       dsieger   501:            First time after package extraction and before files are
                    502:            moved in place, the second time after the files to install
                    503:            are moved in place. This can be used to do any custom
                    504:            procedures not possible with @exec commands in
1.58      leot      505:            <code class="filename">PLIST</code>. See <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_add.1"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a> and
1.59      martin    506:            <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_create.1"><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a> for more information.  See also <a class="xref" href="pkginstall.html#files-and-dirs-outside-prefix" title="20.1. Files and directories outside the installation prefix">Section 20.1, “Files and directories outside the installation prefix”</a>.
1.15      wiz       507:            Please note that you can modify variables in it easily by using
                    508:            <code class="varname">FILES_SUBST</code> in the package's
                    509:            <code class="filename">Makefile</code>:</p>
                    510: <pre class="programlisting">
                    511: FILES_SUBST+=  SOMEVAR="somevalue"
                    512: </pre>
1.59      martin    513: <p>replaces "@SOMEVAR@" with <span class="quote">“<span class="quote">somevalue</span>”</span> in the
1.15      wiz       514:            <code class="filename">INSTALL</code>.  By default, substitution is
                    515:            performed for <code class="varname">PREFIX</code>,
                    516:            <code class="varname">LOCALBASE</code>, <code class="varname">X11BASE</code>,
                    517:            <code class="varname">VARBASE</code>, and a few others, type
                    518:            <span class="command"><strong>make help topic=FILES_SUBST</strong></span> for a
                    519:            complete list.</p>
                    520: </dd>
1.1       dsieger   521: <dt><span class="term"><code class="filename">DEINSTALL</code></span></dt>
                    522: <dd><p>This script is executed before and after any files are removed.  It is
                    523:            this script's responsibility to clean up any additional messy details
                    524:            around the package's installation, since all pkg_delete knows is how to
                    525:            delete the files created in the original distribution.
1.58      leot      526:            See <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_delete.1"><span class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a>
                    527:            and <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_create.1"><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a> for more information.
1.15      wiz       528:            The same methods to replace variables can be used as for
                    529:            the <code class="filename">INSTALL</code> file.</p></dd>
1.1       dsieger   530: <dt><span class="term"><code class="filename">MESSAGE</code></span></dt>
                    531: <dd>
                    532: <p>This file is displayed after installation of the package.
1.49      leot      533:            While this was used often in the past, it has two
                    534:            problems: the display will be missed if many packages are
1.57      jkoshy    535:            installed at once, and the person installing the package
1.49      leot      536:            and the one using or configuring it may be different.  It
                    537:            should therefore be used only in exceptional circumstances
                    538:            where lasting negative consequences would result from
                    539:            someone not reading it.</p>
                    540: <p>MESSAGE should not be used for:</p>
                    541: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
                    542: <li class="listitem"><p>exhortations to read the documentation</p></li>
                    543: <li class="listitem"><p>reminders to install rc.d files and set variables</p></li>
                    544: <li class="listitem"><p>anything that should be explained in the
                    545:              installation/configuration documentation that should
                    546:              come with the package</p></li>
                    547: </ul></div>
                    548: <p>If the documentation provided by upstream needs
                    549:            enhancing, create e.g. files/README.pkgsrc and install it
                    550:            in the package's documentation directory.
                    551:            </p>
                    552: <p>Note that MESSAGE is shown for all operating
                    553:            systems and all init systems.  If a MESSAGE is necessary,
                    554:            it should be narrowed to only those operating systems and
                    555:            init systems to which it applies.</p>
                    556: <p>Note that you can modify variables in it easily by using
1.1       dsieger   557:            <code class="varname">MESSAGE_SUBST</code> in the package's
                    558:            <code class="filename">Makefile</code>:</p>
                    559: <pre class="programlisting">
                    560: MESSAGE_SUBST+=  SOMEVAR="somevalue"
                    561: </pre>
1.59      martin    562: <p>replaces "${SOMEVAR}" with <span class="quote">“<span class="quote">somevalue</span>”</span> in
1.1       dsieger   563:            <code class="filename">MESSAGE</code>.  By default, substitution is
                    564:            performed for <code class="varname">PKGNAME</code>,
                    565:            <code class="varname">PKGBASE</code>, <code class="varname">PREFIX</code>,
1.27      sevan     566:            <code class="varname">LOCALBASE</code>, <code class="varname">X11BASE</code>,
1.1       dsieger   567:            <code class="varname">PKG_SYSCONFDIR</code>,
                    568:            <code class="varname">ROOT_GROUP</code>, and
1.11      jnemeth   569:            <code class="varname">ROOT_USER</code>.</p>
1.1       dsieger   570: <p>You can display a different or additional files by
                    571:            setting the <code class="varname">MESSAGE_SRC</code> variable.  Its
                    572:            default is <code class="filename">MESSAGE</code>, if the file
                    573:            exists.</p>
                    574: </dd>
                    575: <dt><span class="term"><code class="filename">ALTERNATIVES</code></span></dt>
1.19      asau      576: <dd>
                    577: <p>This file is used by the alternatives framework.
                    578:            It creates, configures, and destroys generic wrappers used to
                    579:            run programs with similar interfaces.
                    580:            See pkg_alternatives(8) from pkgtools/pkg_alternatives
                    581:             for more information.</p>
                    582: <p>Each line of the file contains two filenames, first
                    583:            the wrapper and then the alternative provided by the package.
                    584:            Both paths are relative to <code class="varname">PREFIX</code>.</p>
                    585: </dd>
1.1       dsieger   586: </dl></div>
                    587: </div>
1.18      asau      588: <div class="sect2">
1.1       dsieger   589: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    590: <a name="components.optional.build"></a>12.5.2. Files affecting the build process</h3></div></div></div>
1.18      asau      591: <div class="variablelist"><dl class="variablelist">
1.1       dsieger   592: <dt><span class="term"><code class="filename">Makefile.common</code></span></dt>
                    593: <dd><p>This file contains arbitrary things that could
                    594:        also go into a <code class="filename">Makefile</code>, but its purpose is
                    595:        to be used by more than one package. This file should only be
                    596:        used when the packages that will use the file are known in
                    597:        advance. For other purposes it is often better to write a
                    598:        <code class="filename">*.mk</code> file and give it a good name that
                    599:        describes what it does.</p></dd>
                    600: <dt><span class="term"><code class="filename">buildlink3.mk</code></span></dt>
                    601: <dd><p>This file contains the dependency information
1.59      martin    602:        for the buildlink3 framework (see <a class="xref" href="buildlink.html" title="Chapter 18. Buildlink methodology">Chapter 18, <i>Buildlink methodology</i></a>).</p></dd>
1.1       dsieger   603: <dt><span class="term"><code class="filename">hacks.mk</code></span></dt>
                    604: <dd><p>This file contains workarounds for compiler bugs
                    605:        and similar things. It is included automatically by the pkgsrc
                    606:        infrastructure, so you don't need an extra
                    607:        <code class="literal">.include</code> line for
                    608:        it.</p></dd>
                    609: <dt><span class="term"><code class="filename">options.mk</code></span></dt>
                    610: <dd><p>This file contains the code for the
1.59      martin    611:        package-specific options (see <a class="xref" href="options.html" title="Chapter 16. Options handling">Chapter 16, <i>Options handling</i></a>) that can be
1.1       dsieger   612:        selected by the user. If a package has only one or two options,
                    613:        it is equally acceptable to put the code directly into the
                    614:        <code class="filename">Makefile</code>.</p></dd>
                    615: </dl></div>
                    616: </div>
1.18      asau      617: <div class="sect2">
1.1       dsieger   618: <div class="titlepage"><div><div><h3 class="title">
1.59      martin    619: <a name="components.optional.none"></a>12.5.3. Files affecting nothing at all</h3></div></div></div>
1.18      asau      620: <div class="variablelist"><dl class="variablelist">
1.1       dsieger   621: <dt><span class="term"><code class="filename">README*</code></span></dt>
                    622: <dd><p>These files do not take place in the creation of
                    623:        a package and thus are purely informative to the package
                    624:        developer.</p></dd>
                    625: <dt><span class="term"><code class="filename">TODO</code></span></dt>
                    626: <dd><p>This file contains things that need to be done
                    627:        to make the package even
                    628:        better.</p></dd>
                    629: </dl></div>
                    630: </div>
                    631: </div>
1.18      asau      632: <div class="sect1">
1.1       dsieger   633: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    634: <a name="work-dir"></a>12.6. <code class="filename">work*</code>
1.1       dsieger   635: </h2></div></div></div>
1.6       hubertf   636: <p>When you type <span class="command"><strong>make</strong></span>, the distribution files are
1.1       dsieger   637:     unpacked into the directory denoted by
                    638:     <code class="varname">WRKDIR</code>. It can be removed by running
1.6       hubertf   639:     <span class="command"><strong>make clean</strong></span>. Besides the sources, this
1.1       dsieger   640:     directory is also used to keep various timestamp files.
                    641:     The directory gets <span class="emphasis"><em>removed completely</em></span> on clean.
                    642:     The default is <code class="filename">${.CURDIR}/work</code>
                    643:     or <code class="filename">${.CURDIR}/work.${MACHINE_ARCH}</code>
                    644:     if <code class="varname">OBJMACHINE</code> is set.</p>
                    645: </div>
1.18      asau      646: <div class="sect1">
1.1       dsieger   647: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.59      martin    648: <a name="files-dir"></a>12.7. <code class="filename">files/*</code>
1.1       dsieger   649: </h2></div></div></div>
1.43      rillig    650: <p>If you have any files that you wish to be placed in the package
                    651:     prior to configuration or building, you can place these files here
                    652:     and use a <span class="command"><strong>${CP}</strong></span> command in the
1.59      martin    653:     <span class="quote">“<span class="quote">post-extract</span>”</span> target to achieve this.</p>
1.1       dsieger   654: <p>If you want to share files in this way with other
                    655:     packages, set the <code class="varname">FILESDIR</code> variable to point
                    656:     to the other package's <code class="filename">files</code> directory,
                    657:     e.g.:</p>
                    658: <pre class="programlisting">
1.41      rillig    659: FILESDIR=       ../../editors/xemacs/files
1.1       dsieger   660: </pre>
                    661: </div>
                    662: </div>
                    663: <div class="navfooter">
                    664: <hr>
                    665: <table width="100%" summary="Navigation footer">
                    666: <tr>
                    667: <td width="40%" align="left">
1.59      martin    668: <a accesskey="p" href="help-devel.html">Prev</a> </td>
1.1       dsieger   669: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1.59      martin    670: <td width="40%" align="right"> <a accesskey="n" href="build.html">Next</a>
1.1       dsieger   671: </td>
                    672: </tr>
                    673: <tr>
1.59      martin    674: <td width="40%" align="left" valign="top">Chapter 11. Getting help </td>
1.1       dsieger   675: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.59      martin    676: <td width="40%" align="right" valign="top"> Chapter 13. The build process</td>
1.1       dsieger   677: </tr>
                    678: </table>
                    679: </div>
                    680: </body>
                    681: </html>

CVSweb <webmaster@jp.NetBSD.org>