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, “The <span class="emphasis"><em>fetch</em></span> phase”</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"><<a href="mailto:pkgsrc-users@NetBSD.org">pkgsrc-users@NetBSD.org</a>></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: “<span class="quote">${PREFIX}</span>” 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, “Packages installing info files”</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, “patches/*”</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, “<code class="filename">distinfo</code>”</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: “<span class="quote">category/package</span>” 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 —
! 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 <sys/event.h>
! 380: #endif
! 381: </pre>
! 382: </td>
! 383: <td>
! 384: <pre class="programlisting">
! 385: #if defined(HAVE_SYS_EVENT_H)
! 386: # include <sys/event.h>
! 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, “Files and directories outside the installation prefix”</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 “<span class="quote">somevalue</span>” 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: “<span class="quote">pre-configure</span>” 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>