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