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

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">
1.5       rillig      5: <title>Chapter 11. Package components - files, directories and contents</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">
1.10      rillig      8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.1       dsieger     9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.5       rillig     10: <link rel="prev" href="creating.html" title="Chapter 10. Creating a new pkgsrc package from scratch">
                     11: <link rel="next" href="makefile.html" title="Chapter 12. Programming in Makefiles">
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.5       rillig     16: <tr><th colspan="3" align="center">Chapter 11. Package components - files, directories and contents</th></tr>
1.1       dsieger    17: <tr>
                     18: <td width="20%" align="left">
                     19: <a accesskey="p" href="creating.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="makefile.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">
1.5       rillig     29: <a name="components"></a>Chapter 11. 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>
                     32: <dl>
1.10      rillig     33: <dt><span class="sect1"><a href="components.html#components.Makefile">11.1. Makefile</a></span></dt>
                     34: <dt><span class="sect1"><a href="components.html#components.distinfo">11.2. distinfo</a></span></dt>
1.5       rillig     35: <dt><span class="sect1"><a href="components.html#components.patches">11.3. patches/*</a></span></dt>
1.1       dsieger    36: <dd><dl>
1.5       rillig     37: <dt><span class="sect2"><a href="components.html#components.patch.structure">11.3.1. Structure of a single patch file</a></span></dt>
                     38: <dt><span class="sect2"><a href="components.html#components.patches.caveats">11.3.2. Creating patch files</a></span></dt>
                     39: <dt><span class="sect2"><a href="components.html#components.patches.sources">11.3.3. Sources where the patch files come from</a></span></dt>
                     40: <dt><span class="sect2"><a href="components.html#components.patches.guidelines">11.3.4. Patching guidelines</a></span></dt>
                     41: <dt><span class="sect2"><a href="components.html#components.patches.feedback">11.3.5. Feedback to the author</a></span></dt>
1.1       dsieger    42: </dl></dd>
1.5       rillig     43: <dt><span class="sect1"><a href="components.html#other-mandatory-files">11.4. Other mandatory files</a></span></dt>
                     44: <dt><span class="sect1"><a href="components.html#components.optional">11.5. Optional files</a></span></dt>
1.1       dsieger    45: <dd><dl>
1.5       rillig     46: <dt><span class="sect2"><a href="components.html#components.optional.bin">11.5.1. Files affecting the binary package</a></span></dt>
                     47: <dt><span class="sect2"><a href="components.html#components.optional.build">11.5.2. Files affecting the build process</a></span></dt>
                     48: <dt><span class="sect2"><a href="components.html#components.optional.none">11.5.3. Files affecting nothing at all</a></span></dt>
1.1       dsieger    49: </dl></dd>
1.10      rillig     50: <dt><span class="sect1"><a href="components.html#work-dir">11.6. work*</a></span></dt>
                     51: <dt><span class="sect1"><a href="components.html#files-dir">11.7. files/*</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>
                     57: <div class="sect1" lang="en">
                     58: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig     59: <a name="components.Makefile"></a>11.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>
                     72: <div class="itemizedlist"><ul type="disc">
                     73: <li><p><code class="varname">DISTNAME</code> is the basename of the
                     74:     distribution file to be downloaded from the package's
                     75:     website.</p></li>
                     76: <li><p><code class="varname">PKGNAME</code> is the name of the
                     77:     package, as used by pkgsrc. You only need to provide it if
                     78:     <code class="varname">DISTNAME</code> (which is the default) is not a good
                     79:     name for the package in pkgsrc.  Usually it is the pkgsrc
                     80:     directory name together with the version number. It must match the
                     81:     regular expression
                     82:     <code class="varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>, that is, it
                     83:     starts with a letter or digit, and contains only letters, digits,
                     84:     dashes, underscores, dots and plus signs.</p></li>
                     85: <li><p><code class="varname">SVR4_PKGNAME</code> is the name of
                     86:     the package file to create if the <code class="varname">PKGNAME</code>
                     87:     isn't unique on a SVR4 system. The default is
                     88:     <code class="varname">PKGNAME</code>, which may be shortened when you use
                     89:     <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/gensolpkg/README.html" target="_top"><code class="filename">pkgtools/gensolpkg</code></a>. Only add
                     90:     <code class="varname">SVR4_PKGNAME</code> if <code class="varname">PKGNAME</code>
                     91:     does not produce an unique package name on a SVR4 system.
                     92:     The length of <code class="varname">SVR4_PKGNAME</code> is limited to 5
                     93:     characters.</p></li>
                     94: <li>
                     95: <p><code class="varname">CATEGORIES</code> is a list of categories
                     96:     which the package fits in. You can choose any of the top-level
                     97:     directories of pkgsrc for it.</p>
                     98: <p>Currently the following values are available for
                     99:     <code class="varname">CATEGORIES</code>. If more than
                    100:     one is used, they need to be separated by spaces:</p>
                    101: <pre class="programlisting">
                    102: archivers     cross         geography     meta-pkgs     security
                    103: audio         databases     graphics      misc          shells
                    104: benchmarks    devel         ham           multimedia    sysutils
                    105: biology       editors       inputmethod   net           textproc
                    106: cad           emulators     lang          news          time
                    107: chat          finance       mail          parallel      wm
                    108: comms         fonts         math          pkgtools      www
                    109: converters    games         mbone         print         x11
                    110: </pre>
                    111: </li>
                    112: <li><p><code class="varname">MASTER_SITES</code>,
                    113:     <code class="varname">DYNAMIC_MASTER_SITES</code>,
                    114:     <code class="varname">DIST_SUBDIR</code>, <code class="varname">EXTRACT_SUFX</code>
                    115:     and <code class="varname">DISTFILES</code> are discussed in detail in
1.10      rillig    116:     <a class="xref" href="build.html#build.fetch" title="17.5. The fetch phase">Section 17.5, &#8220;The fetch phase&#8221;</a>.</p></li>
1.1       dsieger   117: </ul></div>
                    118: <p>The second section contains information about separately
                    119:   downloaded patches, if any.
                    120:   </p>
                    121: <div class="itemizedlist"><ul type="disc">
                    122: <li><p><code class="varname">PATCHFILES:</code>
                    123:     Name(s) of additional files that contain distribution patches.
                    124:     There is no default. pkgsrc will look for them at
                    125:     <code class="varname">PATCH_SITES</code>.
                    126:     They will automatically be uncompressed before patching if
                    127:     the names end with <code class="filename">.gz</code> or
                    128:     <code class="filename">.Z</code>.</p></li>
                    129: <li><p><code class="varname">PATCH_SITES</code>:
                    130:     Primary location(s) for distribution patch files (see
                    131:     <code class="varname">PATCHFILES</code> below) if not found locally.</p></li>
                    132: </ul></div>
                    133: <p>The third section contains the following variables.
                    134:   </p>
                    135: <div class="itemizedlist"><ul type="disc">
1.9       jmcneill  136: <li><p><code class="varname">MAINTAINER</code> is the email
                    137:     address of the person who feels responsible for this package,
                    138:     and who is most likely to look at problems or questions regarding
                    139:     this package which have been reported with <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a>.
                    140:     Other developers may contact the <code class="varname">MAINTAINER</code>
                    141:     before making changes to the package, but are not required to
                    142:     do so. When packaging a new program, set <code class="varname">MAINTAINER</code>
                    143:     to yourself. If you really can't maintain the package for future
                    144:     updates, set it to
1.6       hubertf   145:     <code class="email">&lt;<a class="email" href="mailto:pkgsrc-users@NetBSD.org">pkgsrc-users@NetBSD.org</a>&gt;</code>.</p></li>
1.9       jmcneill  146: <li><p><code class="varname">OWNER</code> should be used instead
                    147:     of <code class="varname">MAINTAINER</code> when you do not want other
                    148:     developers to update or change the package without contacting
                    149:     you first. A package Makefile should contain one of
                    150:     <code class="varname">MAINTAINER</code> or <code class="varname">OWNER</code>, but
                    151:     not both.  </p></li>
1.1       dsieger   152: <li><p><code class="varname">HOMEPAGE</code> is a URL where users can
                    153:     find more information about the package.</p></li>
                    154: <li><p><code class="varname">COMMENT</code> is a one-line
                    155:     description of the package (should not include the package
                    156:     name).</p></li>
                    157: </ul></div>
                    158: <p>Other variables that affect the build:
                    159:   </p>
                    160: <div class="itemizedlist"><ul type="disc"><li>
                    161: <p><code class="varname">WRKSRC</code>: The directory where the
                    162:       interesting distribution files of the package are found. The
                    163:       default is <code class="filename">${WRKDIR}/${DISTNAME}</code>, which
                    164:       works for most packages.</p>
                    165: <p>If a package doesn't create a subdirectory for itself
                    166:       (most GNU software does, for instance), but extracts itself in
                    167:       the current directory, you should set
                    168:       <code class="varname">WRKSRC=${WRKDIR}</code>.</p>
                    169: <p>If a package doesn't create a subdirectory with the
                    170:       name of <code class="varname">DISTNAME</code> but some different name,
                    171:       set <code class="varname">WRKSRC</code> to point to the proper name in
                    172:       <code class="filename">${WRKDIR}</code>, for example
                    173:       <code class="varname">WRKSRC=${WRKDIR}/${DISTNAME}/unix</code>. See
                    174:       <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/tcl/README.html" target="_top"><code class="filename">lang/tcl</code></a> and <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/tk/README.html" target="_top"><code class="filename">x11/tk</code></a> for other examples.</p>
                    175: <p>The name of the working directory created by pkgsrc is
                    176:       taken from the <code class="varname">WRKDIR_BASENAME</code>
                    177:       variable. By default, its value is
                    178:       <code class="filename">work</code>. If you want to use the same
                    179:       pkgsrc tree for building different kinds of binary packages,
                    180:       you can change the variable according to your needs. Two
                    181:       other variables handle common cases of setting
                    182:       <code class="varname">WRKDIR_BASENAME</code> individually. If
                    183:       <code class="varname">OBJHOSTNAME</code> is defined in
1.6       hubertf   184:       <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>, the first component of
1.1       dsieger   185:       the host's name is attached to the directory name. If
                    186:       <code class="varname">OBJMACHINE</code> is defined, the platform name
                    187:       is attached, which might look like
                    188:       <code class="filename">work.i386</code> or
                    189:       <code class="filename">work.sparc</code>.</p>
                    190: </li></ul></div>
                    191: <p>Please pay attention to the following gotchas:</p>
                    192: <div class="itemizedlist"><ul type="disc">
                    193: <li><p>Add <code class="varname">MANCOMPRESSED</code> if man pages are
                    194:       installed in compressed form by the package.  For packages using
                    195:       BSD-style makefiles which honor MANZ, there is
                    196:       <code class="varname">MANCOMPRESSED_IF_MANZ</code>.</p></li>
                    197: <li><p>Replace <code class="filename">/usr/local</code> with
                    198:       &#8220;<span class="quote">${PREFIX}</span>&#8221; in all files (see patches,
                    199:       below).</p></li>
1.6       hubertf   200: <li><p>If the package installs any info files, see <a class="xref" href="fixes.html#faq.info-files" title="19.6.7. Packages installing info files">Section 19.6.7, &#8220;Packages installing info files&#8221;</a>.</p></li>
1.1       dsieger   201: </ul></div>
                    202: </div>
                    203: <div class="sect1" lang="en">
                    204: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    205: <a name="components.distinfo"></a>11.2. <code class="filename">distinfo</code>
1.1       dsieger   206: </h2></div></div></div>
                    207: <p>The <code class="filename">distinfo</code> file contains the message
                    208:   digest, or checksum, of each distfile needed for the package. This
                    209:   ensures that the distfiles retrieved from the Internet have not been
                    210:   corrupted during transfer or altered by a malign force to introduce
                    211:   a security hole. Due to recent rumor about weaknesses of digest
                    212:   algorithms, all distfiles are protected using both SHA1 and RMD160
                    213:   message digests, as well as the file size.</p>
                    214: <p>The <code class="filename">distinfo</code> file also contains the
                    215:   checksums for all the patches found in the
1.6       hubertf   216:   <code class="filename">patches</code> directory (see <a class="xref" href="components.html#components.patches" title="11.3. patches/*">Section 11.3, &#8220;patches/*&#8221;</a>).</p>
1.1       dsieger   217: <p>To regenerate the <code class="filename">distinfo</code> file, use the
1.6       hubertf   218:   <span class="command"><strong>make makedistinfo</strong></span> or <span class="command"><strong>make mdi</strong></span>
1.1       dsieger   219:   command.</p>
                    220: <p>Some packages have different sets of distfiles depending on
                    221:   the platform, for example <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/navigator/README.html" target="_top"><code class="filename">www/navigator</code></a>). These are kept in the same
                    222:   <code class="filename">distinfo</code> file and care should be taken when
                    223:   upgrading such a package to ensure distfile information is not
                    224:   lost.</p>
                    225: </div>
                    226: <div class="sect1" lang="en">
                    227: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    228: <a name="components.patches"></a>11.3. patches/*</h2></div></div></div>
1.1       dsieger   229: <p>Many packages still don't work out-of-the box on the various
                    230:   platforms that are supported by pkgsrc. Therefore, a number of custom
                    231:   patch files are needed to make the package work. These patch files are
                    232:   found in the <code class="filename">patches/</code> directory.</p>
                    233: <p>In the <span class="emphasis"><em>patch</em></span> phase, these patches are
                    234:   applied to the files in <code class="varname">WRKSRC</code> directory after
1.6       hubertf   235:   extracting them, in <a class="ulink" href="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03" target="_top">alphabetic
1.1       dsieger   236:   order</a>, so <code class="filename">patch-aa</code> is applied before
                    237:   <code class="filename">patch-ab</code>, etc.</p>
                    238: <div class="sect2" lang="en">
                    239: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    240: <a name="components.patch.structure"></a>11.3.1. Structure of a single patch file</h3></div></div></div>
1.1       dsieger   241: <p>The <code class="filename">patch-*</code> files should be in
1.6       hubertf   242:   <span class="command"><strong>diff -bu</strong></span> format, and apply without a fuzz to avoid
1.1       dsieger   243:   problems. (To force patches to apply with fuzz you can set
                    244:   <code class="varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, each patch
                    245:   should contain only changes for a single file, and no file should be
                    246:   patched by more than one patch file. This helps to keep future
                    247:   modifications simple.</p>
                    248: <p>Each patch file is structured as follows: In the first line,
                    249:   there is the RCS Id of the patch itself. The second line should be
                    250:   empty for aesthetic reasons. After that, there should be a comment for
                    251:   each change that the patch does. There are a number of standard
                    252:   cases:</p>
                    253: <div class="itemizedlist"><ul type="disc">
                    254: <li><p>Patches that replace the <code class="literal">==</code>
1.6       hubertf   255:   operator for <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?test+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">test</span>(1)</span></a> with <code class="literal">=</code> in shell scripts
1.7       rillig    256:   are so common that they don't need a comment at all.</p></li>
1.1       dsieger   257: <li><p>Patches for commonly known vulnerabilities should
                    258:   mention the vulnerability ID (CAN, CVE).</p></li>
                    259: <li><p>Patches that change source code should mention the
                    260:   platform and other environment (for example, the compiler) that the
                    261:   patch is needed for.</p></li>
                    262: </ul></div>
                    263: <p>In all other cases, the patch should be commented so that any
                    264:   developer who knows the code of the application can make some use of
                    265:   the patch. Special care should be taken for the upstream developers,
                    266:   since we generally want that they accept our patches, so we have less
                    267:   work in the future.</p>
                    268: </div>
                    269: <div class="sect2" lang="en">
                    270: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    271: <a name="components.patches.caveats"></a>11.3.2. Creating patch files</h3></div></div></div>
1.1       dsieger   272: <p>One important thing to mention is to pay attention that no RCS
                    273:   IDs get stored in the patch files, as these will cause problems when
                    274:   later checked into the NetBSD CVS tree. Use the
1.6       hubertf   275:   <span class="command"><strong>pkgdiff</strong></span> command from the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html" target="_top"><code class="filename">pkgtools/pkgdiff</code></a> package to avoid these
1.1       dsieger   276:   problems.</p>
                    277: <p>For even more automation, we recommend using
1.6       hubertf   278:   <span class="command"><strong>mkpatches</strong></span> from the same package to make a
1.1       dsieger   279:   whole set of patches. You just have to backup files before you
                    280:   edit them to <code class="filename">filename.orig</code>, e.g. with
1.6       hubertf   281:   <span class="command"><strong>cp -p filename filename.orig</strong></span> or, easier, by
                    282:   using <span class="command"><strong>pkgvi</strong></span> again from the same package. If
1.1       dsieger   283:   you upgrade a package this way, you can easily compare the new
                    284:   set of patches with the previously existing one with
1.6       hubertf   285:   <span class="command"><strong>patchdiff</strong></span>. Copy the patches you want to use
1.1       dsieger   286:   or update from the <code class="filename">work/.newpatches</code>
                    287:   directory to <code class="filename">patches/</code>.</p>
                    288: <p>When you have finished a package, remember to generate
1.6       hubertf   289:   the checksums for the patch files by using the <span class="command"><strong>make
1.10      rillig    290:   makepatchsum</strong></span> command, see <a class="xref" href="components.html#components.distinfo" title="11.2. distinfo">Section 11.2, &#8220;distinfo&#8221;</a>.</p>
1.1       dsieger   291: <p>When adding a patch that corrects a problem in the
                    292:   distfile (rather than e.g. enforcing pkgsrc's view of where
                    293:   man pages should go), send the patch as a bug report to the
                    294:   maintainer.  This benefits non-pkgsrc users of the package,
                    295:   and usually makes it possible to remove the patch in future
                    296:   version.</p>
1.2       rillig    297: <p>The file names of the patch files are usually of the form
                    298:   <code class="filename">patch-<em class="replaceable"><code>[a-z][a-z]</code></em></code>.</p>
1.1       dsieger   299: </div>
                    300: <div class="sect2" lang="en">
                    301: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    302: <a name="components.patches.sources"></a>11.3.3. Sources where the patch files come from</h3></div></div></div>
1.1       dsieger   303: <p>If you want to share patches between multiple packages
                    304:   in pkgsrc, e.g. because they use the same distfiles, set
                    305:   <code class="varname">PATCHDIR</code> to the path where the patch files
                    306:   can be found, e.g.:</p>
                    307: <pre class="programlisting">
                    308: PATCHDIR= ${.CURDIR}/../xemacs/patches
                    309: </pre>
                    310: <p>Patch files that are distributed by the author or other
                    311:     maintainers can be listed in
                    312:     <code class="varname">PATCHFILES</code>.</p>
                    313: <p>If it is desired to store any patches that should not be
                    314:     committed into pkgsrc, they can be kept outside the pkgsrc
                    315:     tree in the <code class="filename">$LOCALPATCHES</code> directory. The
                    316:     directory tree there is expected to have the same
                    317:     &#8220;<span class="quote">category/package</span>&#8221; structure as pkgsrc, and
                    318:     patches are expected to be stored inside these dirs (also
                    319:     known as <code class="filename">$LOCALPATCHES/$PKGPATH</code>). For
                    320:     example, if you want to keep a private patch for
                    321:     <code class="filename">pkgsrc/graphics/png</code>, keep it in
                    322:     <code class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
                    323:     files in the named directory are expected to be patch files,
                    324:     and <span class="emphasis"><em>they are applied after pkgsrc patches are
                    325:     applied</em></span>.</p>
                    326: </div>
                    327: <div class="sect2" lang="en">
                    328: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    329: <a name="components.patches.guidelines"></a>11.3.4. Patching guidelines</h3></div></div></div>
1.1       dsieger   330: <p>When fixing a portability issue in the code do not use
                    331:       preprocessor magic to check for the current operating system nor
                    332:       platform.  Doing so hurts portability to other platforms because
                    333:       the OS-specific details are not abstracted appropriately.</p>
                    334: <p>The general rule to follow is: instead of checking for the
                    335:       operating system the application is being built on, check for the
                    336:       specific <span class="emphasis"><em>features</em></span> you need.  For example,
                    337:       instead of assuming that kqueue is available under NetBSD and
                    338:       using the <code class="varname">__NetBSD__</code> macro to conditionalize
1.9       jmcneill  339:       kqueue support, add a check that detects kqueue itself &mdash;
1.1       dsieger   340:       yes, this generally involves patching the
1.6       hubertf   341:       <span class="command"><strong>configure</strong></span> script.  There is absolutely nothing
1.1       dsieger   342:       that prevents some OSes from adopting interfaces from other OSes
                    343:       (e.g. Linux implementing kqueue), something that the above checks
                    344:       cannot take into account.</p>
                    345: <p>Of course, checking for features generally involves more
                    346:       work on the developer's side, but the resulting changes are
                    347:       cleaner and there are chances they will work on many other
                    348:       platforms.  Not to mention that there are higher chances of being
                    349:       later integrated into the mainstream sources.  Remember:
                    350:       <span class="emphasis"><em>It doesn't work unless it is right!</em></span></p>
                    351: <p>Some typical examples:</p>
                    352: <div class="table">
1.5       rillig    353: <a name="patch-examples"></a><p class="title"><b>Table 11.1. Patching examples</b></p>
1.1       dsieger   354: <div class="table-contents"><table summary="Patching examples" border="1">
                    355: <colgroup>
                    356: <col>
                    357: <col>
                    358: <col>
                    359: </colgroup>
                    360: <thead><tr>
                    361: <th>Where</th>
                    362: <th>Incorrect</th>
                    363: <th>Correct</th>
                    364: </tr></thead>
                    365: <tbody>
                    366: <tr>
                    367: <td>configure script</td>
                    368: <td>
                    369: <pre class="programlisting">
                    370: case ${target_os} in
                    371: netbsd*) have_kvm=yes ;;
                    372: *)       have_kvm=no  ;;
                    373: esac
                    374: </pre>
                    375:              </td>
                    376: <td>
                    377: <pre class="programlisting">
                    378: AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)
                    379: </pre>
                    380:              </td>
                    381: </tr>
                    382: <tr>
                    383: <td>C source file</td>
                    384: <td>
                    385: <pre class="programlisting">
                    386: #if defined(__NetBSD__)
                    387: #  include &lt;sys/event.h&gt;
                    388: #endif
                    389: </pre>
                    390:              </td>
                    391: <td>
                    392: <pre class="programlisting">
                    393: #if defined(HAVE_SYS_EVENT_H)
                    394: #  include &lt;sys/event.h&gt;
                    395: #endif
                    396: </pre>
                    397:              </td>
                    398: </tr>
                    399: <tr>
                    400: <td>C source file</td>
                    401: <td>
                    402: <pre class="programlisting">
                    403: int
                    404: monitor_file(...)
                    405: {
                    406: #if defined(__NetBSD__)
                    407:         int fd = kqueue();
                    408:         ...
                    409: #else
                    410:         ...
                    411: #endif
                    412: }
                    413: </pre>
                    414:              </td>
                    415: <td>
                    416: <pre class="programlisting">
                    417: int
                    418: monitor_file(...)
                    419: {
                    420: #if defined(HAVE_KQUEUE)
                    421:         int fd = kqueue();
                    422:         ...
                    423: #else
                    424:        ...
                    425: #endif
                    426: }
                    427: </pre>
                    428:              </td>
                    429: </tr>
                    430: </tbody>
                    431: </table></div>
                    432: </div>
                    433: <br class="table-break"><p>For more information, please read the <span class="emphasis"><em>Making
1.6       hubertf   434:       packager-friendly software</em></span> article (<a class="ulink" href="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html" target="_top">part
                    435:       1</a>, <a class="ulink" href="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html" target="_top">part
1.1       dsieger   436:       2</a>).  It summarizes multiple details on how to make
                    437:       software easier to package; all the suggestions in it were
                    438:       collected from our experience in pkgsrc work, so they are possibly
                    439:       helpful when creating patches too.</p>
                    440: </div>
                    441: <div class="sect2" lang="en">
                    442: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    443: <a name="components.patches.feedback"></a>11.3.5. Feedback to the author</h3></div></div></div>
1.1       dsieger   444: <p>Always, always, <span class="strong"><strong>always</strong></span>
                    445:       feed back any <span class="emphasis"><em>portability fixes</em></span> or
                    446:       improvements you do to a package to the mainstream developers.
                    447:       This is the only way to get their attention on portability issues
                    448:       and to ensure that future versions can be built out-of-the box on
                    449:       NetBSD.  Furthermore, any user that gets newer distfiles will get
                    450:       the fixes straight from the packaged code.</p>
                    451: <p>This generally involves cleaning up the patches
                    452:       (because sometimes the patches that are
                    453:       added to pkgsrc are quick hacks), filling bug reports in the
                    454:       appropriate trackers for the projects and working with the
                    455:       mainstream authors to accept your changes.  It is
                    456:       <span class="emphasis"><em>extremely important</em></span> that you do it so that
                    457:       the packages in pkgsrc are kept simple and thus further changes
                    458:       can be done without much hassle.</p>
                    459: <p>Support the idea of free software!</p>
                    460: </div>
                    461: </div>
                    462: <div class="sect1" lang="en">
                    463: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    464: <a name="other-mandatory-files"></a>11.4. Other mandatory files</h2></div></div></div>
1.1       dsieger   465: <div class="variablelist"><dl>
                    466: <dt><span class="term"><code class="filename">DESCR</code></span></dt>
                    467: <dd><p>A multi-line description of the piece of software.  This should include
                    468:          any credits where they are due.  Please bear in mind that others do not
                    469:          share your sense of humour (or spelling idiosyncrasies), and that others
                    470:          will read everything that you write here.</p></dd>
                    471: <dt><span class="term"><code class="filename">PLIST</code></span></dt>
                    472: <dd><p>This file governs the files that are installed on your
                    473:          system: all the binaries, manual pages, etc. There are other
                    474:          directives which may be entered in this file, to control the
                    475:          creation and deletion of directories, and the location of
1.6       hubertf   476:          inserted files.  See <a class="xref" href="plist.html" title="Chapter 13. PLIST issues">Chapter 13, <i>PLIST issues</i></a> for more
1.1       dsieger   477:          information.</p></dd>
                    478: </dl></div>
                    479: </div>
                    480: <div class="sect1" lang="en">
                    481: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    482: <a name="components.optional"></a>11.5. Optional files</h2></div></div></div>
1.1       dsieger   483: <div class="sect2" lang="en">
                    484: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    485: <a name="components.optional.bin"></a>11.5.1. Files affecting the binary package</h3></div></div></div>
1.1       dsieger   486: <div class="variablelist"><dl>
                    487: <dt><span class="term"><code class="filename">INSTALL</code></span></dt>
1.6       hubertf   488: <dd><p>This shell script is invoked twice by <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a>.
1.1       dsieger   489:            First time after package extraction and before files are
                    490:            moved in place, the second time after the files to install
                    491:            are moved in place. This can be used to do any custom
                    492:            procedures not possible with @exec commands in
1.6       hubertf   493:            <code class="filename">PLIST</code>. See <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a> and
                    494:            <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current"><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="15.1. Files and directories outside the installation prefix">Section 15.1, &#8220;Files and directories outside the installation prefix&#8221;</a>.</p></dd>
1.1       dsieger   495: <dt><span class="term"><code class="filename">DEINSTALL</code></span></dt>
                    496: <dd><p>This script is executed before and after any files are removed.  It is
                    497:            this script's responsibility to clean up any additional messy details
                    498:            around the package's installation, since all pkg_delete knows is how to
                    499:            delete the files created in the original distribution.
1.6       hubertf   500:            See <a class="citerefentry" 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>
                    501:            and <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a> for more information.</p></dd>
1.1       dsieger   502: <dt><span class="term"><code class="filename">MESSAGE</code></span></dt>
                    503: <dd>
                    504: <p>This file is displayed after installation of the package.
                    505:            Useful for things like legal notices on almost-free
                    506:            software and hints for updating config files after
                    507:            installing modules for apache, PHP etc.
                    508:            Please note that you can modify variables in it easily by using
                    509:            <code class="varname">MESSAGE_SUBST</code> in the package's
                    510:            <code class="filename">Makefile</code>:</p>
                    511: <pre class="programlisting">
                    512: MESSAGE_SUBST+=  SOMEVAR="somevalue"
                    513: </pre>
                    514: <p>replaces "${SOMEVAR}" with &#8220;<span class="quote">somevalue</span>&#8221; in
                    515:            <code class="filename">MESSAGE</code>.  By default, substitution is
                    516:            performed for <code class="varname">PKGNAME</code>,
                    517:            <code class="varname">PKGBASE</code>, <code class="varname">PREFIX</code>,
                    518:            <code class="varname">LOCALBASE</code>, <code class="varname">X11PREFIX</code>,
                    519:            <code class="varname">X11BASE</code>,
                    520:            <code class="varname">PKG_SYSCONFDIR</code>,
                    521:            <code class="varname">ROOT_GROUP</code>, and
1.11    ! jnemeth   522:            <code class="varname">ROOT_USER</code>.</p>
1.1       dsieger   523: <p>You can display a different or additional files by
                    524:            setting the <code class="varname">MESSAGE_SRC</code> variable.  Its
                    525:            default is <code class="filename">MESSAGE</code>, if the file
                    526:            exists.</p>
                    527: </dd>
                    528: <dt><span class="term"><code class="filename">ALTERNATIVES</code></span></dt>
                    529: <dd><p>FIXME: There is no documentation on the
                    530:        alternatives framework.</p></dd>
                    531: </dl></div>
                    532: </div>
                    533: <div class="sect2" lang="en">
                    534: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    535: <a name="components.optional.build"></a>11.5.2. Files affecting the build process</h3></div></div></div>
1.1       dsieger   536: <div class="variablelist"><dl>
                    537: <dt><span class="term"><code class="filename">Makefile.common</code></span></dt>
                    538: <dd><p>This file contains arbitrary things that could
                    539:        also go into a <code class="filename">Makefile</code>, but its purpose is
                    540:        to be used by more than one package. This file should only be
                    541:        used when the packages that will use the file are known in
                    542:        advance. For other purposes it is often better to write a
                    543:        <code class="filename">*.mk</code> file and give it a good name that
                    544:        describes what it does.</p></dd>
                    545: <dt><span class="term"><code class="filename">buildlink3.mk</code></span></dt>
                    546: <dd><p>This file contains the dependency information
1.6       hubertf   547:        for the buildlink3 framework (see <a class="xref" href="buildlink.html" title="Chapter 14. Buildlink methodology">Chapter 14, <i>Buildlink methodology</i></a>).</p></dd>
1.1       dsieger   548: <dt><span class="term"><code class="filename">hacks.mk</code></span></dt>
                    549: <dd><p>This file contains workarounds for compiler bugs
                    550:        and similar things. It is included automatically by the pkgsrc
                    551:        infrastructure, so you don't need an extra
                    552:        <code class="literal">.include</code> line for
                    553:        it.</p></dd>
                    554: <dt><span class="term"><code class="filename">options.mk</code></span></dt>
                    555: <dd><p>This file contains the code for the
1.6       hubertf   556:        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   557:        selected by the user. If a package has only one or two options,
                    558:        it is equally acceptable to put the code directly into the
                    559:        <code class="filename">Makefile</code>.</p></dd>
                    560: </dl></div>
                    561: </div>
                    562: <div class="sect2" lang="en">
                    563: <div class="titlepage"><div><div><h3 class="title">
1.5       rillig    564: <a name="components.optional.none"></a>11.5.3. Files affecting nothing at all</h3></div></div></div>
1.1       dsieger   565: <div class="variablelist"><dl>
                    566: <dt><span class="term"><code class="filename">README*</code></span></dt>
                    567: <dd><p>These files do not take place in the creation of
                    568:        a package and thus are purely informative to the package
                    569:        developer.</p></dd>
                    570: <dt><span class="term"><code class="filename">TODO</code></span></dt>
                    571: <dd><p>This file contains things that need to be done
                    572:        to make the package even
                    573:        better.</p></dd>
                    574: </dl></div>
                    575: </div>
                    576: </div>
                    577: <div class="sect1" lang="en">
                    578: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    579: <a name="work-dir"></a>11.6. <code class="filename">work*</code>
1.1       dsieger   580: </h2></div></div></div>
1.6       hubertf   581: <p>When you type <span class="command"><strong>make</strong></span>, the distribution files are
1.1       dsieger   582:     unpacked into the directory denoted by
                    583:     <code class="varname">WRKDIR</code>. It can be removed by running
1.6       hubertf   584:     <span class="command"><strong>make clean</strong></span>. Besides the sources, this
1.1       dsieger   585:     directory is also used to keep various timestamp files.
                    586:     The directory gets <span class="emphasis"><em>removed completely</em></span> on clean.
                    587:     The default is <code class="filename">${.CURDIR}/work</code>
                    588:     or <code class="filename">${.CURDIR}/work.${MACHINE_ARCH}</code>
                    589:     if <code class="varname">OBJMACHINE</code> is set.</p>
                    590: </div>
                    591: <div class="sect1" lang="en">
                    592: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.5       rillig    593: <a name="files-dir"></a>11.7. <code class="filename">files/*</code>
1.1       dsieger   594: </h2></div></div></div>
                    595: <p>If you have any files that you wish to be placed in the package prior
                    596:     to configuration or building, you could place these files here and use
1.6       hubertf   597:     a <span class="command"><strong>${CP}</strong></span> command in the
1.1       dsieger   598:     &#8220;<span class="quote">pre-configure</span>&#8221; target to achieve
                    599:     this. Alternatively, you could simply diff the file against
                    600:     <code class="filename">/dev/null</code> and use the patch mechanism to manage
                    601:     the creation of this file.</p>
                    602: <p>If you want to share files in this way with other
                    603:     packages, set the <code class="varname">FILESDIR</code> variable to point
                    604:     to the other package's <code class="filename">files</code> directory,
                    605:     e.g.:</p>
                    606: <pre class="programlisting">
                    607: FILESDIR=${.CURDIR}/../xemacs/files
                    608: </pre>
                    609: </div>
                    610: </div>
                    611: <div class="navfooter">
                    612: <hr>
                    613: <table width="100%" summary="Navigation footer">
                    614: <tr>
                    615: <td width="40%" align="left">
                    616: <a accesskey="p" href="creating.html">Prev</a> </td>
                    617: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
                    618: <td width="40%" align="right"> <a accesskey="n" href="makefile.html">Next</a>
                    619: </td>
                    620: </tr>
                    621: <tr>
1.5       rillig    622: <td width="40%" align="left" valign="top">Chapter 10. Creating a new pkgsrc package from scratch </td>
1.1       dsieger   623: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.10      rillig    624: <td width="40%" align="right" valign="top"> Chapter 12. Programming in Makefiles</td>
1.1       dsieger   625: </tr>
                    626: </table>
                    627: </div>
                    628: </body>
                    629: </html>

CVSweb <webmaster@jp.NetBSD.org>