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