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

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

CVSweb <webmaster@jp.NetBSD.org>