Annotation of pkgsrc/doc/pkgsrc.html, revision 1.75
1.75 ! rillig 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
! 2: <html>
1.1 grant 3: <head>
1.75 ! rillig 4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
! 5: <title>The pkgsrc guide</title>
! 6: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
! 7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
! 8: <meta name="description" content="pkgsrc is a centralized package management system for
! 9: Unix-like operating systems. This guide provides information for
! 10: users and developers of pkgsrc. It covers installation of binary
! 11: and source packages, creation of binary and source packages and
! 12: a high-level overview about the infrastructure.">
! 13: </head>
! 14: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en">
! 15: <div class="titlepage">
! 16: <div>
! 17: <div><h1 class="title">
! 18: <a name="the-pkgsrc-guide"></a>The pkgsrc guide</h1></div>
! 19: <div><h2 class="subtitle">Documentation on the NetBSD packages system</h2></div>
! 20: <div><div class="authorgroup">
! 21: <div class="author">
! 22: <h3 class="author">
! 23: <span class="firstname">Alistair</span> <span class="surname">Crooks</span>
! 24: </h3>
! 25: <div class="affiliation"><div class="address"><p><code class="email"><<a href="mailto:agc@NetBSD.org">agc@NetBSD.org</a>></code></p></div></div>
! 26: </div>
! 27: <div class="author">
! 28: <h3 class="author">
! 29: <span class="firstname">Hubert</span> <span class="surname">Feyrer</span>
! 30: </h3>
! 31: <div class="affiliation"><div class="address"><p><code class="email"><<a href="mailto:hubertf@NetBSD.org">hubertf@NetBSD.org</a>></code></p></div></div>
! 32: </div>
! 33: <h3 class="corpauthor">
! 34: The pkgsrc Developers
! 35: </h3>
! 36: </div></div>
! 37: <div><p class="copyright">Copyright © 1994-2006 The NetBSD Foundation, Inc</p></div>
! 38: <div xmlns="http://www.w3.org/TR/xhtml1/transitional"><p xmlns="" class="pubdate">$NetBSD: pkgsrc.xml,v 1.18 2006/05/19 22:05:09 rillig Exp $</p></div><div><div class="abstract">
! 39: <p class="title"><b>Abstract</b></p>
! 40: <p>pkgsrc is a centralized package management system for
! 41: Unix-like operating systems. This guide provides information for
! 42: users and developers of pkgsrc. It covers installation of binary
! 43: and source packages, creation of binary and source packages and
! 44: a high-level overview about the infrastructure.</p>
! 45: </div></div>
! 46: </div>
! 47: <hr>
! 48: </div>
! 49: <div class="toc">
! 50: <p><b>Table of Contents</b></p>
! 51: <dl>
! 52: <dt><span class="chapter"><a href="#introduction">1. What is pkgsrc?</a></span></dt>
! 53: <dd><dl>
! 54: <dt><span class="sect1"><a href="#introduction-section">1.1. Introduction</a></span></dt>
! 55: <dt><span class="sect1"><a href="#overview">1.2. Overview</a></span></dt>
! 56: <dt><span class="sect1"><a href="#terminology">1.3. Terminology</a></span></dt>
! 57: <dd><dl><dt><span class="sect2"><a href="#term.people">1.3.1. People involved in pkgsrc</a></span></dt></dl></dd>
! 58: <dt><span class="sect1"><a href="#typography">1.4. Typography</a></span></dt>
! 59: </dl></dd>
! 60: <dt><span class="part"><a href="#users-guide">I. The pkgsrc user's guide</a></span></dt>
! 61: <dd><dl>
! 62: <dt><span class="chapter"><a href="#getting">2. Where to get pkgsrc and how to keep it up-to-date</a></span></dt>
! 63: <dd><dl>
! 64: <dt><span class="sect1"><a href="#getting-first">2.1. Getting pkgsrc for the first time</a></span></dt>
! 65: <dd><dl>
! 66: <dt><span class="sect2"><a href="#getting-via-tar">2.1.1. As tar file</a></span></dt>
! 67: <dt><span class="sect2"><a href="#getting-via-sup">2.1.2. Via SUP</a></span></dt>
! 68: <dt><span class="sect2"><a href="#getting-via-cvs">2.1.3. Via CVS</a></span></dt>
! 69: </dl></dd>
! 70: <dt><span class="sect1"><a href="#uptodate">2.2. Keeping pkgsrc up-to-date</a></span></dt>
! 71: <dd><dl>
! 72: <dt><span class="sect2"><a href="#uptodate-tar">2.2.1. Via tar files</a></span></dt>
! 73: <dt><span class="sect2"><a href="#uptodate-cvs">2.2.2. Via CVS</a></span></dt>
! 74: </dl></dd>
! 75: </dl></dd>
! 76: <dt><span class="chapter"><a href="#platforms">3. Using pkgsrc on systems other than NetBSD</a></span></dt>
! 77: <dd><dl>
! 78: <dt><span class="sect1"><a href="#bootstrapping-pkgsrc">3.1. Bootstrapping pkgsrc</a></span></dt>
! 79: <dt><span class="sect1"><a href="#platform-specific-notes">3.2. Platform-specific notes</a></span></dt>
! 80: <dd><dl>
! 81: <dt><span class="sect2"><a href="#darwin">3.2.1. Darwin (Mac OS X)</a></span></dt>
! 82: <dt><span class="sect2"><a href="#freebsd">3.2.2. FreeBSD</a></span></dt>
! 83: <dt><span class="sect2"><a href="#interix">3.2.3. Interix</a></span></dt>
! 84: <dt><span class="sect2"><a href="#irix">3.2.4. IRIX</a></span></dt>
! 85: <dt><span class="sect2"><a href="#linux">3.2.5. Linux</a></span></dt>
! 86: <dt><span class="sect2"><a href="#openbsd">3.2.6. OpenBSD</a></span></dt>
! 87: <dt><span class="sect2"><a href="#solaris">3.2.7. Solaris</a></span></dt>
! 88: </dl></dd>
! 89: </dl></dd>
! 90: <dt><span class="chapter"><a href="#using">4. Using pkgsrc</a></span></dt>
! 91: <dd><dl>
! 92: <dt><span class="sect1"><a href="#using-pkg">4.1. Using binary packages</a></span></dt>
! 93: <dd><dl>
! 94: <dt><span class="sect2"><a href="#finding-binary-packages">4.1.1. Finding binary packages</a></span></dt>
! 95: <dt><span class="sect2"><a href="#installing-binary-packages">4.1.2. Installing binary packages</a></span></dt>
! 96: <dt><span class="sect2"><a href="#a-word-of-warning">4.1.3. A word of warning</a></span></dt>
! 97: </dl></dd>
! 98: <dt><span class="sect1"><a href="#building-packages-from-source">4.2. Building packages from source</a></span></dt>
! 99: <dd><dl>
! 100: <dt><span class="sect2"><a href="#requirements">4.2.1. Requirements</a></span></dt>
! 101: <dt><span class="sect2"><a href="#fetching-distfiles">4.2.2. Fetching distfiles</a></span></dt>
! 102: <dt><span class="sect2"><a href="#how-to-build-and-install">4.2.3. How to build and install</a></span></dt>
! 103: <dt><span class="sect2"><a href="#selecting-the-compiler">4.2.4. Selecting the compiler</a></span></dt>
! 104: </dl></dd>
! 105: </dl></dd>
! 106: <dt><span class="chapter"><a href="#configuring">5. Configuring pkgsrc</a></span></dt>
! 107: <dd><dl>
! 108: <dt><span class="sect1"><a href="#general-configuration">5.1. General configuration</a></span></dt>
! 109: <dt><span class="sect1"><a href="#variables-affecting-build">5.2. Variables affecting the build process</a></span></dt>
! 110: <dt><span class="sect1"><a href="#developer-advanced-settings">5.3. Developer/advanced settings</a></span></dt>
! 111: <dt><span class="sect1"><a href="#selecting-build-options">5.4. Selecting Build Options</a></span></dt>
! 112: </dl></dd>
! 113: <dt><span class="chapter"><a href="#binary">6. Creating binary packages</a></span></dt>
! 114: <dd><dl>
! 115: <dt><span class="sect1"><a href="#building-a-single-binary-package">6.1. Building a single binary package</a></span></dt>
! 116: <dt><span class="sect1"><a href="#settings-for-creationg-of-binary-packages">6.2. Settings for creation of binary packages</a></span></dt>
! 117: <dt><span class="sect1"><a href="#bulkbuild">6.3. Doing a bulk build of all packages</a></span></dt>
! 118: <dd><dl>
! 119: <dt><span class="sect2"><a href="#binary.configuration">6.3.1. Configuration</a></span></dt>
! 120: <dt><span class="sect2"><a href="#other-environmental-considerations">6.3.2. Other environmental considerations</a></span></dt>
! 121: <dt><span class="sect2"><a href="#operation">6.3.3. Operation</a></span></dt>
! 122: <dt><span class="sect2"><a href="#what-it-does">6.3.4. What it does</a></span></dt>
! 123: <dt><span class="sect2"><a href="#disk-space-requirements">6.3.5. Disk space requirements</a></span></dt>
! 124: <dt><span class="sect2"><a href="#setting-up-a-sandbox">6.3.6. Setting up a sandbox for chrooted builds</a></span></dt>
! 125: <dt><span class="sect2"><a href="#building-a-partial-set">6.3.7. Building a partial set of packages</a></span></dt>
! 126: <dt><span class="sect2"><a href="#bulk-upload">6.3.8. Uploading results of a bulk build</a></span></dt>
! 127: </dl></dd>
! 128: <dt><span class="sect1"><a href="#creating-cdroms">6.4. Creating a multiple CD-ROM packages collection</a></span></dt>
! 129: <dd><dl><dt><span class="sect2"><a href="#cdpack-example">6.4.1. Example of cdpack</a></span></dt></dl></dd>
! 130: </dl></dd>
! 131: <dt><span class="chapter"><a href="#faq">7. Frequently Asked Questions</a></span></dt>
! 132: <dd><dl>
! 133: <dt><span class="sect1"><a href="#mailing-list-pointers">7.1. Are there any mailing lists for pkg-related discussion?</a></span></dt>
! 134: <dt><span class="sect1"><a href="#pkgviews-docs">7.2. Where's the pkgviews documentation?</a></span></dt>
! 135: <dt><span class="sect1"><a href="#faq-pkgtools">7.3. Utilities for package management (pkgtools)</a></span></dt>
! 136: <dt><span class="sect1"><a href="#non-root-pkgsrc">7.4. How to use pkgsrc as non-root</a></span></dt>
! 137: <dt><span class="sect1"><a href="#resume-transfers">7.5. How to resume transfers when fetching distfiles?</a></span></dt>
! 138: <dt><span class="sect1"><a href="#XFree86-from-pkgsrc">7.6. How can I install/use XFree86 from pkgsrc?</a></span></dt>
! 139: <dt><span class="sect1"><a href="#x.org-from-pkgsrc">7.7. How can I install/use X.org from pkgsrc?</a></span></dt>
! 140: <dt><span class="sect1"><a href="#fetch-behind-firewall">7.8. How to fetch files from behind a firewall</a></span></dt>
! 141: <dt><span class="sect1"><a href="#passive-ftp">7.9. How do I tell <span><strong class="command">make fetch</strong></span> to do passive FTP?</a></span></dt>
! 142: <dt><span class="sect1"><a href="#fetching-all-distfiles">7.10. How to fetch all distfiles at once</a></span></dt>
! 143: <dt><span class="sect1"><a href="#tmac.andoc-missing">7.11. What does “<span class="quote">Don't know how to make
! 144: /usr/share/tmac/tmac.andoc</span>” mean?</a></span></dt>
! 145: <dt><span class="sect1"><a href="#bsd.own.mk-missing">7.12. What does “<span class="quote">Could not find bsd.own.mk</span>” mean?</a></span></dt>
! 146: <dt><span class="sect1"><a href="#using-sudo-with-pkgsrc">7.13. Using 'sudo' with pkgsrc</a></span></dt>
! 147: <dt><span class="sect1"><a href="#faq.conf">7.14. How do I change the location of configuration files?</a></span></dt>
! 148: <dt><span class="sect1"><a href="#audit-packages">7.15. Automated security checks</a></span></dt>
! 149: <dt><span class="sect1"><a href="#ufaq-cflags">7.16. Why do some packages ignore my <code class="varname">CFLAGS</code>?</a></span></dt>
! 150: </dl></dd>
! 151: </dl></dd>
! 152: <dt><span class="part"><a href="#developers-guide">II. The pkgsrc developer's guide</a></span></dt>
! 153: <dd><dl>
! 154: <dt><span class="chapter"><a href="#components">8. Package components - files, directories and contents</a></span></dt>
! 155: <dd><dl>
! 156: <dt><span class="sect1"><a href="#components.Makefile">8.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code></a></span></dt>
! 157: <dt><span class="sect1"><a href="#components.distinfo">8.2. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code></a></span></dt>
! 158: <dt><span class="sect1"><a href="#components.patches">8.3. patches/*</a></span></dt>
! 159: <dt><span class="sect1"><a href="#other-mandatory-files">8.4. Other mandatory files</a></span></dt>
! 160: <dt><span class="sect1"><a href="#components.optional">8.5. Optional files</a></span></dt>
! 161: <dt><span class="sect1"><a href="#work-dir">8.6. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work*</code></a></span></dt>
! 162: <dt><span class="sect1"><a href="#files-dir">8.7. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">files/*</code></a></span></dt>
! 163: </dl></dd>
! 164: <dt><span class="chapter"><a href="#makefile">9. Programming in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s</a></span></dt>
! 165: <dd><dl>
! 166: <dt><span class="sect1"><a href="#makefile.variables">9.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> variables</a></span></dt>
! 167: <dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">9.1.1. Naming conventions</a></span></dt></dl></dd>
! 168: <dt><span class="sect1"><a href="#makefile.code">9.2. Code snippets</a></span></dt>
! 169: <dd><dl>
! 170: <dt><span class="sect2"><a href="#adding-to-list">9.2.1. Adding things to a list</a></span></dt>
! 171: <dt><span class="sect2"><a href="#converting-internal-to-external">9.2.2. Converting an internal list into an external list</a></span></dt>
! 172: <dt><span class="sect2"><a href="#passing-variable-to-shell">9.2.3. Passing variables to a shell command</a></span></dt>
! 173: <dt><span class="sect2"><a href="#quoting-guideline">9.2.4. Quoting guideline</a></span></dt>
! 174: <dt><span class="sect2"><a href="#bsd-make-bug-workaround">9.2.5. Workaround for a bug in BSD Make</a></span></dt>
! 175: </dl></dd>
! 176: </dl></dd>
! 177: <dt><span class="chapter"><a href="#plist">10. PLIST issues</a></span></dt>
! 178: <dd><dl>
! 179: <dt><span class="sect1"><a href="#rcs-id">10.1. RCS ID</a></span></dt>
! 180: <dt><span class="sect1"><a href="#automatic-plist-generation">10.2. Semi-automatic <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> generation</a></span></dt>
! 181: <dt><span class="sect1"><a href="#print-PLIST">10.3. Tweaking output of <span><strong class="command">make print-PLIST</strong></span></a></span></dt>
! 182: <dt><span class="sect1"><a href="#plist.misc">10.4. Variable substitution in PLIST</a></span></dt>
! 183: <dt><span class="sect1"><a href="#manpage-compression">10.5. Man page compression</a></span></dt>
! 184: <dt><span class="sect1"><a href="#using-PLIST_SRC">10.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
! 185: <dt><span class="sect1"><a href="#platform-specific-plist">10.7. Platform-specific and differing PLISTs</a></span></dt>
! 186: <dt><span class="sect1"><a href="#faq.common-dirs">10.8. Sharing directories between packages</a></span></dt>
! 187: </dl></dd>
! 188: <dt><span class="chapter"><a href="#buildlink">11. Buildlink methodology</a></span></dt>
! 189: <dd><dl>
! 190: <dt><span class="sect1"><a href="#converting-to-buildlink3">11.1. Converting packages to use buildlink3</a></span></dt>
! 191: <dt><span class="sect1"><a href="#creating-buildlink3.mk">11.2. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 192: <dd><dl>
! 193: <dt><span class="sect2"><a href="#anatomy-of-bl3">11.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
! 194: <dt><span class="sect2"><a href="#updating-buildlink-depends">11.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 195: </dl></dd>
! 196: <dt><span class="sect1"><a href="#writing-builtin.mk">11.3. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> files</a></span></dt>
! 197: <dd><dl>
! 198: <dt><span class="sect2"><a href="#anatomy-of-builtin.mk">11.3.1. Anatomy of a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file</a></span></dt>
! 199: <dt><span class="sect2"><a href="#native-or-pkgsrc-preference">11.3.2. Global preferences for native or pkgsrc software</a></span></dt>
! 200: </dl></dd>
! 201: </dl></dd>
! 202: <dt><span class="chapter"><a href="#pkginstall">12. The pkginstall framework</a></span></dt>
! 203: <dd><dl>
! 204: <dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">12.1. Files and directories outside the installation prefix</a></span></dt>
! 205: <dd><dl>
! 206: <dt><span class="sect2"><a href="#dirs-outside-prefix">12.1.1. Directory manipulation</a></span></dt>
! 207: <dt><span class="sect2"><a href="#files-outside-prefix">12.1.2. File manipulation</a></span></dt>
! 208: </dl></dd>
! 209: <dt><span class="sect1"><a href="#conf-files">12.2. Configuration files</a></span></dt>
! 210: <dd><dl>
! 211: <dt><span class="sect2"><a href="#conf-files-sysconfdir">12.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
! 212: <dt><span class="sect2"><a href="#conf-files-configure">12.2.2. Telling the software where configuration files are</a></span></dt>
! 213: <dt><span class="sect2"><a href="#conf-files-patching">12.2.3. Patching installations</a></span></dt>
! 214: <dt><span class="sect2"><a href="#conf-files-disable">12.2.4. Disabling handling of configuration files</a></span></dt>
! 215: </dl></dd>
! 216: <dt><span class="sect1"><a href="#rcd-scripts">12.3. System startup scripts</a></span></dt>
! 217: <dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">12.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
! 218: <dt><span class="sect1"><a href="#users-and-groups">12.4. System users and groups</a></span></dt>
! 219: <dt><span class="sect1"><a href="#shells">12.5. System shells</a></span></dt>
! 220: <dd><dl><dt><span class="sect2"><a href="#shells-disable">12.5.1. Disabling shell registration</a></span></dt></dl></dd>
! 221: <dt><span class="sect1"><a href="#fonts">12.6. Fonts</a></span></dt>
! 222: <dd><dl><dt><span class="sect2"><a href="#fonts-disable">12.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
! 223: </dl></dd>
! 224: <dt><span class="chapter"><a href="#options">13. Options handling</a></span></dt>
! 225: <dd><dl>
! 226: <dt><span class="sect1"><a href="#global-default-options">13.1. Global default options</a></span></dt>
! 227: <dt><span class="sect1"><a href="#converting-to-options">13.2. Converting packages to use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code></a></span></dt>
! 228: <dt><span class="sect1"><a href="#option-names">13.3. Option Names</a></span></dt>
! 229: </dl></dd>
! 230: <dt><span class="chapter"><a href="#build">14. The build process</a></span></dt>
! 231: <dd><dl>
! 232: <dt><span class="sect1"><a href="#build.intro">14.1. Introduction</a></span></dt>
! 233: <dt><span class="sect1"><a href="#build.prefix">14.2. Program location</a></span></dt>
! 234: <dt><span class="sect1"><a href="#build.builddirs">14.3. Directories used during the build process</a></span></dt>
! 235: <dt><span class="sect1"><a href="#build.running">14.4. Running a phase</a></span></dt>
! 236: <dt><span class="sect1"><a href="#build.fetch">14.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
! 237: <dt><span class="sect1"><a href="#build.checksum">14.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
! 238: <dt><span class="sect1"><a href="#build.extract">14.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
! 239: <dt><span class="sect1"><a href="#build.patch">14.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
! 240: <dt><span class="sect1"><a href="#build.tools">14.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
! 241: <dt><span class="sect1"><a href="#build.wrapper">14.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
! 242: <dt><span class="sect1"><a href="#build.configure">14.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
! 243: <dt><span class="sect1"><a href="#build.build">14.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
! 244: <dt><span class="sect1"><a href="#build.test">14.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
! 245: <dt><span class="sect1"><a href="#build.install">14.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
! 246: <dt><span class="sect1"><a href="#build.package">14.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
! 247: <dt><span class="sect1"><a href="#build.helpful-targets">14.16. Other helpful targets</a></span></dt>
! 248: </dl></dd>
! 249: <dt><span class="chapter"><a href="#tools">15. Tools needed for building or running</a></span></dt>
! 250: <dd><dl>
! 251: <dt><span class="sect1"><a href="#pkgsrc-tools">15.1. Tools for pkgsrc builds</a></span></dt>
! 252: <dt><span class="sect1"><a href="#package-tools">15.2. Tools needed by packages</a></span></dt>
! 253: <dt><span class="sect1"><a href="#platform-tools">15.3. Tools provided by platforms</a></span></dt>
! 254: </dl></dd>
! 255: <dt><span class="chapter"><a href="#fixes">16. Making your package work</a></span></dt>
! 256: <dd><dl>
! 257: <dt><span class="sect1"><a href="#general-operation">16.1. General operation</a></span></dt>
! 258: <dd><dl>
! 259: <dt><span class="sect2"><a href="#pulling-vars-from-etc-mk.conf">16.1.1. How to pull in variables from /etc/mk.conf</a></span></dt>
! 260: <dt><span class="sect2"><a href="#where-to-install-documentation">16.1.2. Where to install documentation</a></span></dt>
! 261: <dt><span class="sect2"><a href="#restricted-packages">16.1.3. Restricted packages</a></span></dt>
! 262: <dt><span class="sect2"><a href="#dependencies">16.1.4. Handling dependencies</a></span></dt>
! 263: <dt><span class="sect2"><a href="#conflicts">16.1.5. Handling conflicts with other packages</a></span></dt>
! 264: <dt><span class="sect2"><a href="#not-building-packages">16.1.6. Packages that cannot or should not be built</a></span></dt>
! 265: <dt><span class="sect2"><a href="#undeletable-packages">16.1.7. Packages which should not be deleted, once installed</a></span></dt>
! 266: <dt><span class="sect2"><a href="#security-handling">16.1.8. Handling packages with security problems</a></span></dt>
! 267: <dt><span class="sect2"><a href="#compiler-bugs">16.1.9. How to handle compiler bugs</a></span></dt>
! 268: <dt><span class="sect2"><a href="#bumping-pkgrevision">16.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt>
! 269: <dt><span class="sect2"><a href="#portability-of-packages">16.1.11. Portability of packages</a></span></dt>
! 270: </dl></dd>
! 271: <dt><span class="sect1"><a href="#downloading-issues">16.2. Possible downloading issues</a></span></dt>
! 272: <dd><dl>
! 273: <dt><span class="sect2"><a href="#no-plain-download">16.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt>
! 274: <dt><span class="sect2"><a href="#modified-distfiles-same-name">16.2.2. How to handle modified distfiles with the 'old' name</a></span></dt>
! 275: </dl></dd>
! 276: <dt><span class="sect1"><a href="#configuration-gotchas">16.3. Configuration gotchas</a></span></dt>
! 277: <dd><dl>
! 278: <dt><span class="sect2"><a href="#fixes.libtool">16.3.1. Shared libraries - libtool</a></span></dt>
! 279: <dt><span class="sect2"><a href="#using-libtool">16.3.2. Using libtool on GNU packages that already support libtool</a></span></dt>
! 280: <dt><span class="sect2"><a href="#autoconf-automake">16.3.3. GNU Autoconf/Automake</a></span></dt>
! 281: </dl></dd>
! 282: <dt><span class="sect1"><a href="#fixes-build">16.4. Building the package</a></span></dt>
! 283: <dd><dl>
! 284: <dt><span class="sect2"><a href="#cpp-defines">16.4.1. CPP defines</a></span></dt>
! 285: <dt><span class="sect2"><a href="#cpp-list-examples">16.4.2. Examples of CPP defines for some platforms</a></span></dt>
! 286: <dt><span class="sect2"><a href="#cpp-list">16.4.3. Getting a list of CPP defines</a></span></dt>
! 287: </dl></dd>
! 288: <dt><span class="sect1"><a href="#package-specific-actions">16.5. Package specific actions</a></span></dt>
! 289: <dd><dl>
! 290: <dt><span class="sect2"><a href="#user-interaction">16.5.1. User interaction</a></span></dt>
! 291: <dt><span class="sect2"><a href="#handling-licenses">16.5.2. Handling licenses</a></span></dt>
! 292: <dt><span class="sect2"><a href="#installing-score-files">16.5.3. Installing score files</a></span></dt>
! 293: <dt><span class="sect2"><a href="#perl-scripts">16.5.4. Packages containing perl scripts</a></span></dt>
! 294: <dt><span class="sect2"><a href="#hardcoded-paths">16.5.5. Packages with hardcoded paths to other interpreters</a></span></dt>
! 295: <dt><span class="sect2"><a href="#perl-modules">16.5.6. Packages installing perl modules</a></span></dt>
! 296: <dt><span class="sect2"><a href="#faq.info-files">16.5.7. Packages installing info files</a></span></dt>
! 297: <dt><span class="sect2"><a href="#manpages">16.5.8. Packages installing man pages</a></span></dt>
! 298: <dt><span class="sect2"><a href="#gconf2-data-files">16.5.9. Packages installing GConf2 data files</a></span></dt>
! 299: <dt><span class="sect2"><a href="#scrollkeeper-data-files">16.5.10. Packages installing scrollkeeper data files</a></span></dt>
! 300: <dt><span class="sect2"><a href="#x11-fonts">16.5.11. Packages installing X11 fonts</a></span></dt>
! 301: <dt><span class="sect2"><a href="#gtk2-modules">16.5.12. Packages installing GTK2 modules</a></span></dt>
! 302: <dt><span class="sect2"><a href="#sgml-xml-data">16.5.13. Packages installing SGML or XML data</a></span></dt>
! 303: <dt><span class="sect2"><a href="#mime-database">16.5.14. Packages installing extensions to the MIME database</a></span></dt>
! 304: <dt><span class="sect2"><a href="#intltool">16.5.15. Packages using intltool</a></span></dt>
! 305: <dt><span class="sect2"><a href="#startup-scripts">16.5.16. Packages installing startup scripts</a></span></dt>
! 306: <dt><span class="sect2"><a href="#tex-packages">16.5.17. Packages installing TeX modules</a></span></dt>
! 307: </dl></dd>
! 308: <dt><span class="sect1"><a href="#feedback-to-author">16.6. Feedback to the author</a></span></dt>
! 309: </dl></dd>
! 310: <dt><span class="chapter"><a href="#debug">17. Debugging</a></span></dt>
! 311: <dt><span class="chapter"><a href="#submit">18. Submitting and Committing</a></span></dt>
! 312: <dd><dl>
! 313: <dt><span class="sect1"><a href="#submitting-binary-packages">18.1. Submitting binary packages</a></span></dt>
! 314: <dt><span class="sect1"><a href="#submitting-your-package">18.2. Submitting source packages (for non-NetBSD-developers)</a></span></dt>
! 315: <dt><span class="sect1"><a href="#general-notes-for-changes">18.3. General notes when adding, updating, or removing packages</a></span></dt>
! 316: <dt><span class="sect1"><a href="#committing-importing">18.4. Committing: Importing a package into CVS</a></span></dt>
! 317: <dt><span class="sect1"><a href="#updating-package">18.5. Updating a package to a newer version</a></span></dt>
! 318: <dt><span class="sect1"><a href="#moving-package">18.6. Moving a package in pkgsrc</a></span></dt>
! 319: </dl></dd>
! 320: <dt><span class="chapter"><a href="#devfaq">19. Frequently Asked Questions</a></span></dt>
! 321: </dl></dd>
! 322: <dt><span class="part"><a href="#infrastructure">III. The pkgsrc infrastructure internals</a></span></dt>
! 323: <dd><dl>
! 324: <dt><span class="chapter"><a href="#infr.design">20. Design of the pkgsrc infrastructure</a></span></dt>
! 325: <dd><dl>
! 326: <dt><span class="sect1"><a href="#infr.var">20.1. Variable evaluation</a></span></dt>
! 327: <dd><dl>
! 328: <dt><span class="sect2"><a href="#infr.var.load">20.1.1. At load time</a></span></dt>
! 329: <dt><span class="sect2"><a href="#infr.var.run">20.1.2. At runtime</a></span></dt>
! 330: </dl></dd>
! 331: <dt><span class="sect1"><a href="#infr.design.intf">20.2. Designing interfaces for Makefile fragments</a></span></dt>
! 332: <dd><dl>
! 333: <dt><span class="sect2"><a href="#infr.design.intf.proc">20.2.1. Procedures with parameters</a></span></dt>
! 334: <dt><span class="sect2"><a href="#infr.design.intf.action">20.2.2. Actions taken on behalf of parameters</a></span></dt>
! 335: </dl></dd>
! 336: </dl></dd>
! 337: <dt><span class="chapter"><a href="#regression">21. Regression tests</a></span></dt>
! 338: <dd><dl>
! 339: <dt><span class="sect1"><a href="#regression.descr">21.1. The regression tests framework</a></span></dt>
! 340: <dt><span class="sect1"><a href="#regression.run">21.2. Running the regression tests</a></span></dt>
! 341: <dt><span class="sect1"><a href="#regression.new">21.3. Adding a new regression test</a></span></dt>
! 342: <dd><dl>
! 343: <dt><span class="sect2"><a href="#regression.fun.override">21.3.1. Overridable functions</a></span></dt>
! 344: <dt><span class="sect2"><a href="#regression.fun.helper">21.3.2. Helper functions</a></span></dt>
! 345: </dl></dd>
! 346: </dl></dd>
! 347: <dt><span class="chapter"><a href="#porting">22. Porting pkgsrc</a></span></dt>
! 348: <dd><dl>
! 349: <dt><span class="sect1"><a href="#porting.opsys">22.1. Porting pkgsrc to a new operating system</a></span></dt>
! 350: <dt><span class="sect1"><a href="#porting.compiler">22.2. Adding support for a new compiler</a></span></dt>
! 351: </dl></dd>
! 352: </dl></dd>
! 353: <dt><span class="appendix"><a href="#examples">A. A simple example package: bison</a></span></dt>
! 354: <dd><dl>
! 355: <dt><span class="sect1"><a href="#example-files">A.1. files</a></span></dt>
! 356: <dd><dl>
! 357: <dt><span class="sect2"><a href="#example-Makefile">A.1.1. Makefile</a></span></dt>
! 358: <dt><span class="sect2"><a href="#example-descr">A.1.2. DESCR</a></span></dt>
! 359: <dt><span class="sect2"><a href="#example-plist">A.1.3. PLIST</a></span></dt>
! 360: <dt><span class="sect2"><a href="#checking-package-with-pkglint">A.1.4. Checking a package with <span><strong class="command">pkglint</strong></span></a></span></dt>
! 361: </dl></dd>
! 362: <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2. Steps for building, installing, packaging</a></span></dt>
! 363: </dl></dd>
! 364: <dt><span class="appendix"><a href="#logs">B. Build logs</a></span></dt>
! 365: <dd><dl>
! 366: <dt><span class="sect1"><a href="#logs.building">B.1. Building figlet</a></span></dt>
! 367: <dt><span class="sect1"><a href="#logs.package">B.2. Packaging figlet</a></span></dt>
! 368: </dl></dd>
! 369: <dt><span class="appendix"><a href="#ftp-layout">C. Layout of the FTP server's package archive</a></span></dt>
! 370: <dt><span class="appendix"><a href="#editing">D. Editing guidelines for the pkgsrc guide</a></span></dt>
! 371: <dd><dl>
! 372: <dt><span class="sect1"><a href="#targets">D.1. Targets</a></span></dt>
! 373: <dt><span class="sect1"><a href="#procedure">D.2. Procedure</a></span></dt>
! 374: </dl></dd>
! 375: </dl>
! 376: </div>
! 377: <div class="chapter" lang="en">
! 378: <div class="titlepage"><div><div><h2 class="title">
! 379: <a name="introduction"></a>Chapter 1. What is pkgsrc?</h2></div></div></div>
! 380: <div class="toc">
! 381: <p><b>Table of Contents</b></p>
! 382: <dl>
! 383: <dt><span class="sect1"><a href="#introduction-section">1.1. Introduction</a></span></dt>
! 384: <dt><span class="sect1"><a href="#overview">1.2. Overview</a></span></dt>
! 385: <dt><span class="sect1"><a href="#terminology">1.3. Terminology</a></span></dt>
! 386: <dd><dl><dt><span class="sect2"><a href="#term.people">1.3.1. People involved in pkgsrc</a></span></dt></dl></dd>
! 387: <dt><span class="sect1"><a href="#typography">1.4. Typography</a></span></dt>
! 388: </dl>
! 389: </div>
! 390: <div class="sect1" lang="en">
! 391: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 392: <a name="introduction-section"></a>1.1. Introduction</h2></div></div></div>
! 393: <p> There is a lot of software freely available for Unix-based
! 394: systems, which usually runs on NetBSD and other Unix-flavoured
! 395: systems, too, sometimes with some modifications. The NetBSD
! 396: Packages Collection (pkgsrc) incorporates any such changes
! 397: necessary to make that software run, and makes the installation
! 398: (and de-installation) of the software package easy by means of a
! 399: single command. </p>
! 400: <p>Once the software
! 401: has been built, it is manipulated with the <span><strong class="command">pkg_*</strong></span> tools
! 402: so that installation
! 403: and de-installation, printing of an inventory of all installed packages and
! 404: retrieval of one-line comments or more verbose descriptions are all
! 405: simple.</p>
! 406: <p>pkgsrc currently contains several thousand packages,
! 407: including:</p>
! 408: <div class="itemizedlist"><ul type="disc">
! 409: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache/README.html" target="_top"><code xmlns="" class="filename">www/apache</code></a> - The Apache
! 410: web server</p></li>
! 411: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html" target="_top"><code xmlns="" class="filename">www/mozilla</code></a> - The Mozilla
! 412: web browser</p></li>
! 413: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/gnome/README.html" target="_top"><code xmlns="" class="filename">meta-pkgs/gnome</code></a> - The GNOME
! 414: Desktop Environment</p></li>
! 415: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/kde3/README.html" target="_top"><code xmlns="" class="filename">meta-pkgs/kde3</code></a> - The K
! 416: Desktop Environment</p></li>
! 417: </ul></div>
! 418: <p>...just to name a few.</p>
! 419: <p>pkgsrc has built-in support for handling varying dependencies,
! 420: such as pthreads and X11, and extended features such as IPv6 support on
! 421: a range of platforms.</p>
! 422: <p>pkgsrc was derived from FreeBSD's ports system, and
! 423: initially developed for NetBSD only. Since then, pkgsrc has
! 424: grown a lot, and now supports the following platforms:</p>
! 425: <div class="itemizedlist"><ul type="disc">
! 426: <li><p><a href="http://developer.apple.com/darwin/" target="_top">Darwin</a>
! 427: (<a href="http://www.apple.com/macosx/" target="_top">Mac OS X</a>)</p></li>
! 428: <li><p><a href="http://www.DragonFlyBSD.org/" target="_top">DragonFly BSD</a></p></li>
! 429: <li><p><a href="http://www.FreeBSD.org/" target="_top">FreeBSD</a></p></li>
! 430: <li><p>Microsoft Windows, via <a href="http://www.microsoft.com/windows/sfu/" target="_top">Interix</a></p></li>
! 431: <li><p><a href="http://www.sgi.com/software/irix6.5/" target="_top">IRIX</a></p></li>
! 432: <li><p><a href="http://www.linux.org/" target="_top">Linux</a></p></li>
! 433: <li><p><a href="http://www.NetBSD.org/" target="_top">NetBSD</a> (of
! 434: course)</p></li>
! 435: <li><p><a href="http://h30097.www3.hp.com/" target="_top">Tru64</a>
! 436: (Digital UNIX, OSF1)</p></li>
! 437: <li><p><a href="http://www.openbsd.org/" target="_top">OpenBSD</a></p></li>
! 438: <li><p><a href="http://www.sun.com/solaris/" target="_top">Solaris</a></p></li>
! 439: </ul></div>
! 440: </div>
! 441: <div class="sect1" lang="en">
! 442: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 443: <a name="overview"></a>1.2. Overview</h2></div></div></div>
! 444: <p>This document is divided into three parts. The first,
! 445: <a href="#users-guide" title="Part I. The pkgsrc user's guide">The pkgsrc user's guide</a>,
! 446: describes how one can use one of the packages in the Package
! 447: Collection, either by installing a precompiled binary package,
! 448: or by building one's own copy using the NetBSD package system.
! 449: The second part, <a href="#developers-guide" title="Part II. The pkgsrc developer's guide">The pkgsrc developer's guide</a>, explains how to prepare a
! 450: package so it can be easily built by other NetBSD users without
! 451: knowing about the package's building details. The third part,
! 452: <a href="#infrastructure" title="Part III. The pkgsrc infrastructure internals">The pkgsrc infrastructure internals</a>
! 453: is intended for those who want to understand how pkgsrc is
! 454: implemented.</p>
! 455: <p>This document is available in various formats:
! 456: <span class="simplelist"><a href="index.html" target="_top">HTML</a>, <a href="pkgsrc.pdf" target="_top">PDF</a>, <a href="pkgsrc.ps" target="_top">PS</a>, <a href="pkgsrc.txt" target="_top">TXT</a></span>.</p>
! 457: </div>
! 458: <div class="sect1" lang="en">
! 459: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 460: <a name="terminology"></a>1.3. Terminology</h2></div></div></div>
! 461: <p>There has been a lot of talk about “<span class="quote">ports</span>”,
! 462: “<span class="quote">packages</span>”, etc. so far. Here is a description of all the
! 463: terminology used within this document.</p>
! 464: <div class="variablelist"><dl>
! 465: <dt><span class="term">Package</span></dt>
! 466: <dd><p>A set of files and building instructions
! 467: that describe what's necessary
! 468: to build a certain piece of software using
! 469: pkgsrc. Packages are traditionally stored under
! 470: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc</code>.</p></dd>
! 471: <dt><span class="term">The NetBSD package system</span></dt>
! 472: <dd><p>
! 473: This is the former name of “<span class="quote">pkgsrc</span>”. It is
! 474: part of the NetBSD operating system and can be bootstrapped to
! 475: run on non-NetBSD operating systems as well. It handles
! 476: building (compiling), installing, and removing of
! 477: packages.
! 478: </p></dd>
! 479: <dt><span class="term">Distfile</span></dt>
! 480: <dd><p>This term describes the file or files that are
! 481: provided by the author of the piece of software to
! 482: distribute his work. All the changes necessary to build on
! 483: NetBSD are reflected in the corresponding package. Usually
! 484: the distfile is in the form of a compressed tar-archive,
! 485: but other types are possible, too. Distfiles are usually
! 486: stored below
! 487: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/distfiles</code>.</p></dd>
! 488: <dt><span class="term">Port</span></dt>
! 489: <dd><p>This is the term used by FreeBSD and OpenBSD people
! 490: for what we call a package.
! 491: In NetBSD terminology, “<span class="quote">port</span>” refers to a different
! 492: architecture.</p></dd>
! 493: <dt><span class="term">Precompiled/binary package</span></dt>
! 494: <dd>
! 495: <p>A set of binaries built with pkgsrc from a distfile
! 496: and stuffed together in a single <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.tgz</code>
! 497: file so it can be installed on machines of the same
! 498: machine architecture without the need to
! 499: recompile. Packages are usually generated in
! 500: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/packages</code>; there is also
! 501: an archive on <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/" target="_top">ftp.NetBSD.org</a>.</p>
! 502: <p>Sometimes, this is referred to by the term “<span class="quote">package</span>” too,
! 503: especially in the context of precompiled packages.</p>
! 504: </dd>
! 505: <dt><span class="term">Program</span></dt>
! 506: <dd><p>The piece of software to be installed which will be constructed from
! 507: all the files in the distfile by the actions defined in the
! 508: corresponding package.</p></dd>
! 509: </dl></div>
! 510: <div class="sect2" lang="en">
! 511: <div class="titlepage"><div><div><h3 class="title">
! 512: <a name="term.people"></a>1.3.1. People involved in pkgsrc</h3></div></div></div>
! 513: <div class="variablelist"><dl>
! 514: <dt><span class="term">pkgsrc users</span></dt>
! 515: <dd>
! 516: <p>The
! 517: pkgsrc users are people who use the packages provided by pkgsrc.
! 518: Typically they are system administrators. The people using the
! 519: software that is inside the packages (maybe called “<span class="quote">end
! 520: users</span>”) are not covered by the pkgsrc guide.</p>
! 521: <p>There are two kinds of pkgsrc users: Some only want to
! 522: install pre-built binary packages. Others build the pkgsrc
! 523: packages from source, either for installing them directly or for
! 524: building binary packages themselves. For pkgsrc users <a href="#users-guide" title="Part I. The pkgsrc user's guide">Part I, “The pkgsrc user's guide”</a> should provide all necessary
! 525: documentation.</p>
! 526: </dd>
! 527: <dt><span class="term">package maintainers</span></dt>
! 528: <dd><p>A
! 529: package maintainer creates packages as described in <a href="#developers-guide" title="Part II. The pkgsrc developer's guide">Part II, “The pkgsrc developer's guide”</a>.</p></dd>
! 530: <dt><span class="term">infrastructure developers</span></dt>
! 531: <dd><p>These people are involved in all those files
! 532: that live in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/</code> directory and below.
! 533: Only these people should need to read through <a href="#infrastructure" title="Part III. The pkgsrc infrastructure internals">Part III, “The pkgsrc infrastructure internals”</a>, though others might be curious,
! 534: too.</p></dd>
! 535: </dl></div>
! 536: </div>
! 537: </div>
! 538: <div class="sect1" lang="en">
! 539: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 540: <a name="typography"></a>1.4. Typography</h2></div></div></div>
! 541: <p>When giving examples for commands, shell prompts are used to
! 542: show if the command should/can be issued as root, or if
! 543: “<span class="quote">normal</span>” user privileges are sufficient. We use a
! 544: <code class="prompt">#</code> for root's shell prompt, and a <code class="prompt">%</code> for users'
! 545: shell prompt, assuming they use the C-shell or tcsh.</p>
! 546: </div>
! 547: </div>
! 548: <div class="part" lang="en">
! 549: <div class="titlepage"><div><div><h1 class="title">
! 550: <a name="users-guide"></a>Part I. The pkgsrc user's guide</h1></div></div></div>
! 551: <div class="toc">
! 552: <p><b>Table of Contents</b></p>
! 553: <dl>
! 554: <dt><span class="chapter"><a href="#getting">2. Where to get pkgsrc and how to keep it up-to-date</a></span></dt>
! 555: <dd><dl>
! 556: <dt><span class="sect1"><a href="#getting-first">2.1. Getting pkgsrc for the first time</a></span></dt>
! 557: <dd><dl>
! 558: <dt><span class="sect2"><a href="#getting-via-tar">2.1.1. As tar file</a></span></dt>
! 559: <dt><span class="sect2"><a href="#getting-via-sup">2.1.2. Via SUP</a></span></dt>
! 560: <dt><span class="sect2"><a href="#getting-via-cvs">2.1.3. Via CVS</a></span></dt>
! 561: </dl></dd>
! 562: <dt><span class="sect1"><a href="#uptodate">2.2. Keeping pkgsrc up-to-date</a></span></dt>
! 563: <dd><dl>
! 564: <dt><span class="sect2"><a href="#uptodate-tar">2.2.1. Via tar files</a></span></dt>
! 565: <dt><span class="sect2"><a href="#uptodate-cvs">2.2.2. Via CVS</a></span></dt>
! 566: </dl></dd>
! 567: </dl></dd>
! 568: <dt><span class="chapter"><a href="#platforms">3. Using pkgsrc on systems other than NetBSD</a></span></dt>
! 569: <dd><dl>
! 570: <dt><span class="sect1"><a href="#bootstrapping-pkgsrc">3.1. Bootstrapping pkgsrc</a></span></dt>
! 571: <dt><span class="sect1"><a href="#platform-specific-notes">3.2. Platform-specific notes</a></span></dt>
! 572: <dd><dl>
! 573: <dt><span class="sect2"><a href="#darwin">3.2.1. Darwin (Mac OS X)</a></span></dt>
! 574: <dt><span class="sect2"><a href="#freebsd">3.2.2. FreeBSD</a></span></dt>
! 575: <dt><span class="sect2"><a href="#interix">3.2.3. Interix</a></span></dt>
! 576: <dt><span class="sect2"><a href="#irix">3.2.4. IRIX</a></span></dt>
! 577: <dt><span class="sect2"><a href="#linux">3.2.5. Linux</a></span></dt>
! 578: <dt><span class="sect2"><a href="#openbsd">3.2.6. OpenBSD</a></span></dt>
! 579: <dt><span class="sect2"><a href="#solaris">3.2.7. Solaris</a></span></dt>
! 580: </dl></dd>
! 581: </dl></dd>
! 582: <dt><span class="chapter"><a href="#using">4. Using pkgsrc</a></span></dt>
! 583: <dd><dl>
! 584: <dt><span class="sect1"><a href="#using-pkg">4.1. Using binary packages</a></span></dt>
! 585: <dd><dl>
! 586: <dt><span class="sect2"><a href="#finding-binary-packages">4.1.1. Finding binary packages</a></span></dt>
! 587: <dt><span class="sect2"><a href="#installing-binary-packages">4.1.2. Installing binary packages</a></span></dt>
! 588: <dt><span class="sect2"><a href="#a-word-of-warning">4.1.3. A word of warning</a></span></dt>
! 589: </dl></dd>
! 590: <dt><span class="sect1"><a href="#building-packages-from-source">4.2. Building packages from source</a></span></dt>
! 591: <dd><dl>
! 592: <dt><span class="sect2"><a href="#requirements">4.2.1. Requirements</a></span></dt>
! 593: <dt><span class="sect2"><a href="#fetching-distfiles">4.2.2. Fetching distfiles</a></span></dt>
! 594: <dt><span class="sect2"><a href="#how-to-build-and-install">4.2.3. How to build and install</a></span></dt>
! 595: <dt><span class="sect2"><a href="#selecting-the-compiler">4.2.4. Selecting the compiler</a></span></dt>
! 596: </dl></dd>
! 597: </dl></dd>
! 598: <dt><span class="chapter"><a href="#configuring">5. Configuring pkgsrc</a></span></dt>
! 599: <dd><dl>
! 600: <dt><span class="sect1"><a href="#general-configuration">5.1. General configuration</a></span></dt>
! 601: <dt><span class="sect1"><a href="#variables-affecting-build">5.2. Variables affecting the build process</a></span></dt>
! 602: <dt><span class="sect1"><a href="#developer-advanced-settings">5.3. Developer/advanced settings</a></span></dt>
! 603: <dt><span class="sect1"><a href="#selecting-build-options">5.4. Selecting Build Options</a></span></dt>
! 604: </dl></dd>
! 605: <dt><span class="chapter"><a href="#binary">6. Creating binary packages</a></span></dt>
! 606: <dd><dl>
! 607: <dt><span class="sect1"><a href="#building-a-single-binary-package">6.1. Building a single binary package</a></span></dt>
! 608: <dt><span class="sect1"><a href="#settings-for-creationg-of-binary-packages">6.2. Settings for creation of binary packages</a></span></dt>
! 609: <dt><span class="sect1"><a href="#bulkbuild">6.3. Doing a bulk build of all packages</a></span></dt>
! 610: <dd><dl>
! 611: <dt><span class="sect2"><a href="#binary.configuration">6.3.1. Configuration</a></span></dt>
! 612: <dt><span class="sect2"><a href="#other-environmental-considerations">6.3.2. Other environmental considerations</a></span></dt>
! 613: <dt><span class="sect2"><a href="#operation">6.3.3. Operation</a></span></dt>
! 614: <dt><span class="sect2"><a href="#what-it-does">6.3.4. What it does</a></span></dt>
! 615: <dt><span class="sect2"><a href="#disk-space-requirements">6.3.5. Disk space requirements</a></span></dt>
! 616: <dt><span class="sect2"><a href="#setting-up-a-sandbox">6.3.6. Setting up a sandbox for chrooted builds</a></span></dt>
! 617: <dt><span class="sect2"><a href="#building-a-partial-set">6.3.7. Building a partial set of packages</a></span></dt>
! 618: <dt><span class="sect2"><a href="#bulk-upload">6.3.8. Uploading results of a bulk build</a></span></dt>
! 619: </dl></dd>
! 620: <dt><span class="sect1"><a href="#creating-cdroms">6.4. Creating a multiple CD-ROM packages collection</a></span></dt>
! 621: <dd><dl><dt><span class="sect2"><a href="#cdpack-example">6.4.1. Example of cdpack</a></span></dt></dl></dd>
! 622: </dl></dd>
! 623: <dt><span class="chapter"><a href="#faq">7. Frequently Asked Questions</a></span></dt>
! 624: <dd><dl>
! 625: <dt><span class="sect1"><a href="#mailing-list-pointers">7.1. Are there any mailing lists for pkg-related discussion?</a></span></dt>
! 626: <dt><span class="sect1"><a href="#pkgviews-docs">7.2. Where's the pkgviews documentation?</a></span></dt>
! 627: <dt><span class="sect1"><a href="#faq-pkgtools">7.3. Utilities for package management (pkgtools)</a></span></dt>
! 628: <dt><span class="sect1"><a href="#non-root-pkgsrc">7.4. How to use pkgsrc as non-root</a></span></dt>
! 629: <dt><span class="sect1"><a href="#resume-transfers">7.5. How to resume transfers when fetching distfiles?</a></span></dt>
! 630: <dt><span class="sect1"><a href="#XFree86-from-pkgsrc">7.6. How can I install/use XFree86 from pkgsrc?</a></span></dt>
! 631: <dt><span class="sect1"><a href="#x.org-from-pkgsrc">7.7. How can I install/use X.org from pkgsrc?</a></span></dt>
! 632: <dt><span class="sect1"><a href="#fetch-behind-firewall">7.8. How to fetch files from behind a firewall</a></span></dt>
! 633: <dt><span class="sect1"><a href="#passive-ftp">7.9. How do I tell <span><strong class="command">make fetch</strong></span> to do passive FTP?</a></span></dt>
! 634: <dt><span class="sect1"><a href="#fetching-all-distfiles">7.10. How to fetch all distfiles at once</a></span></dt>
! 635: <dt><span class="sect1"><a href="#tmac.andoc-missing">7.11. What does “<span class="quote">Don't know how to make
! 636: /usr/share/tmac/tmac.andoc</span>” mean?</a></span></dt>
! 637: <dt><span class="sect1"><a href="#bsd.own.mk-missing">7.12. What does “<span class="quote">Could not find bsd.own.mk</span>” mean?</a></span></dt>
! 638: <dt><span class="sect1"><a href="#using-sudo-with-pkgsrc">7.13. Using 'sudo' with pkgsrc</a></span></dt>
! 639: <dt><span class="sect1"><a href="#faq.conf">7.14. How do I change the location of configuration files?</a></span></dt>
! 640: <dt><span class="sect1"><a href="#audit-packages">7.15. Automated security checks</a></span></dt>
! 641: <dt><span class="sect1"><a href="#ufaq-cflags">7.16. Why do some packages ignore my <code class="varname">CFLAGS</code>?</a></span></dt>
! 642: </dl></dd>
! 643: </dl>
! 644: </div>
! 645: <div class="chapter" lang="en">
! 646: <div class="titlepage"><div><div><h2 class="title">
! 647: <a name="getting"></a>Chapter 2. Where to get pkgsrc and how to keep it up-to-date</h2></div></div></div>
! 648: <div class="toc">
! 649: <p><b>Table of Contents</b></p>
! 650: <dl>
! 651: <dt><span class="sect1"><a href="#getting-first">2.1. Getting pkgsrc for the first time</a></span></dt>
! 652: <dd><dl>
! 653: <dt><span class="sect2"><a href="#getting-via-tar">2.1.1. As tar file</a></span></dt>
! 654: <dt><span class="sect2"><a href="#getting-via-sup">2.1.2. Via SUP</a></span></dt>
! 655: <dt><span class="sect2"><a href="#getting-via-cvs">2.1.3. Via CVS</a></span></dt>
! 656: </dl></dd>
! 657: <dt><span class="sect1"><a href="#uptodate">2.2. Keeping pkgsrc up-to-date</a></span></dt>
! 658: <dd><dl>
! 659: <dt><span class="sect2"><a href="#uptodate-tar">2.2.1. Via tar files</a></span></dt>
! 660: <dt><span class="sect2"><a href="#uptodate-cvs">2.2.2. Via CVS</a></span></dt>
! 661: </dl></dd>
! 662: </dl>
! 663: </div>
! 664: <p>The most common location where pkgsrc is installed is
! 665: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc</code> for the “<span class="quote">package
! 666: sources</span>” and <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> for the
! 667: installed binary packages. You are though free to install the
! 668: sources and binary packages wherever you want in your
! 669: filesystem, provided that both paths do not contain white-space
! 670: or other characters that are interpreted specially by the shell
! 671: and some other programs. A safe bet is to use only letters,
! 672: digits, underscores and dashes in the names.</p>
! 673: <div class="sect1" lang="en">
! 674: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 675: <a name="getting-first"></a>2.1. Getting pkgsrc for the first time</h2></div></div></div>
! 676: <p>Before you download any pkgsrc files, you should decide
! 677: whether you want the <span class="emphasis"><em>current</em></span> branch or the
! 678: <span class="emphasis"><em>stable</em></span> branch. The latter is forked on a
! 679: quarterly basis from the current branch and only gets modified
! 680: for security updates. The names of the stable branches are built
! 681: from the year and the quarter, for example
! 682: <code class="literal">2006Q1</code>.</p>
! 683: <p>The second step is to decide <span class="emphasis"><em>how</em></span> you
! 684: want to download pkgsrc. You can get it as a tar file, via SUP,
! 685: or via CVS. All three ways are described here.</p>
! 686: <div class="sect2" lang="en">
! 687: <div class="titlepage"><div><div><h3 class="title">
! 688: <a name="getting-via-tar"></a>2.1.1. As tar file</h3></div></div></div>
! 689: <p>The primary download location for all pkgsrc files is
! 690: <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/" target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/</a>. There are a
! 691: number of subdirectories for different purposes, which are
! 692: described in detail in <a href="#ftp-layout" title="Appendix C. Layout of the FTP server's package archive">Appendix C, <i>Layout of the FTP server's package archive</i></a>.</p>
! 693: <p>The tar file for the current branch is in the directory
! 694: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">current</code> and is called <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc.tar.gz" target="_top"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc.tar.gz</code></a>.
! 695: It is autogenerated daily.</p>
! 696: <p>The tar file for the stable branch 2006Q1 is in the
! 697: directory <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">2006Q1</code> and is also called <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/2006Q1/pkgsrc.tar.gz" target="_top"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc.tar.gz</code></a>.</p>
! 698: <p>After downloading the tar file, change to the directory
! 699: where you want to have pkgsrc. This is usually
! 700: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr</code>. Then, run <span><strong class="command">tar xfz
! 701: pkgsrc.tar.gz</strong></span> to extract the files.</p>
! 702: </div>
! 703: <div class="sect2" lang="en">
! 704: <div class="titlepage"><div><div><h3 class="title">
! 705: <a name="getting-via-sup"></a>2.1.2. Via SUP</h3></div></div></div>
! 706: <p>As an alternative to the tar file, you can get pkgsrc via
! 707: the Software Update Protocol, SUP. To do so, make sure your
! 708: supfile has a line
1.1 grant 709:
1.75 ! rillig 710: </p>
! 711: <pre class="programlisting">
1.51 rillig 712: release=pkgsrc
1.1 grant 713: </pre>
1.75 ! rillig 714: <p>
1.1 grant 715:
1.75 ! rillig 716: in it, see the examples in
! 717: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/share/examples/supfiles</code>, and that the
! 718: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc</code> directory exists. Then, simply
! 719: run <span><strong class="command">sup -v
! 720: <em class="replaceable"><code>/path/to/your/supfile</code></em></strong></span>.</p>
! 721: </div>
! 722: <div class="sect2" lang="en">
! 723: <div class="titlepage"><div><div><h3 class="title">
! 724: <a name="getting-via-cvs"></a>2.1.3. Via CVS</h3></div></div></div>
! 725: <p>To get pkgsrc via CVS, make sure you have <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cvs+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cvs</span>(1)</span></a>
! 726: installed. To do an initial (full) checkout of pkgsrc, you first
! 727: have to set some environment variables. For the C-Shell,
! 728: type:</p>
! 729: <pre class="screen">
! 730: <code class="prompt">%</code> <strong class="userinput"><code>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</code></strong>
! 731: <code class="prompt">%</code> <strong class="userinput"><code>setenv CVS_RSH ssh</code></strong>
! 732: </pre>
! 733: <p>Or, the same for the bourne shell:</p>
! 734: <pre class="screen">
! 735: <code class="prompt">$</code> <strong class="userinput"><code>CVSROOT="anoncvs@anoncvs.NetBSD.org:/cvsroot"</code></strong>
! 736: <code class="prompt">$</code> <strong class="userinput"><code>CVS_RSH="ssh"</code></strong>
! 737: <code class="prompt">$</code> <strong class="userinput"><code>export CVSROOT CVS_RSH</code></strong>
! 738: </pre>
! 739: <p>Then, you change to the directory where you want to have
! 740: your copy of pkgsrc. In most cases this is
! 741: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr</code>. In that directory you run the
! 742: checkout command, which is <span><strong class="command">cvs -q checkout -P
! 743: pkgsrc</strong></span> for the current branch and <span><strong class="command">cvs -q
! 744: checkout -rpkgsrc-2006Q1 -P pkgsrc</strong></span> for the stable
! 745: branch. This command will create a directory called
! 746: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc</code> with all the pkgsrc files in
! 747: it.</p>
! 748: </div>
! 749: </div>
! 750: <div class="sect1" lang="en">
! 751: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 752: <a name="uptodate"></a>2.2. Keeping pkgsrc up-to-date</h2></div></div></div>
! 753: <p>The preferred way to keep pkgsrc up-to-date is via CVS
! 754: (which also works if you have first installed it via a tar
! 755: file). It saves bandwidth and hard disk activity, compared to
! 756: downloading the tar file again.</p>
! 757: <div class="sect2" lang="en">
! 758: <div class="titlepage"><div><div><h3 class="title">
! 759: <a name="uptodate-tar"></a>2.2.1. Via tar files</h3></div></div></div>
! 760: <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
! 761: <h3 class="title">Warning</h3>
! 762: <p>Updating from tar file cannot detect or preserve
! 763: any changes you have done to your local copy of pkgsrc.
! 764: Therefore updating via CVS is strongly
! 765: recommended.</p>
! 766: </div>
! 767: <p>To update pkgsrc from a tar file, download the tar file as
! 768: explained above. Then, make sure that you have not made any
! 769: changes to the files in the pkgsrc directory. Remove the pkgsrc
! 770: directory and extract the new tar file. Done.</p>
! 771: </div>
! 772: <div class="sect2" lang="en">
! 773: <div class="titlepage"><div><div><h3 class="title">
! 774: <a name="uptodate-cvs"></a>2.2.2. Via CVS</h3></div></div></div>
! 775: <p>To update pkgsrc via CVS, make sure the environment
! 776: variable <code class="varname">CVS_RSH</code> is set as above. Then,
! 777: change to the pkgsrc directory and run <span><strong class="command">cvs -q update
! 778: -dP</strong></span>. The “<span class="quote">-q</span>” option tells cvs to only
! 779: report those files that have changed. The “<span class="quote">-d</span>”
! 780: option fetches new packages (which is curiously not done by
! 781: default), and the “<span class="quote">-P</span>” option removes empty
! 782: directories after everything has been updated.</p>
! 783: <div class="sect3" lang="en">
! 784: <div class="titlepage"><div><div><h4 class="title">
! 785: <a name="uptodate-cvs-switch"></a>2.2.2.1. Switching between different pkgsrc branches</h4></div></div></div>
! 786: <p>When updating pkgsrc, the CVS program keeps track of the
! 787: branch you selected. But if you, for whatever reason, want to
! 788: switch from the stable branch to the current one, you can do it
! 789: by adding the option “<span class="quote">-A</span>” after the
! 790: “<span class="quote">update</span>” keyword. To switch from the current branch
! 791: back to the stable branch, add the
! 792: “<span class="quote">-rpkgsrc-2006Q1</span>” option.</p>
! 793: </div>
! 794: <div class="sect3" lang="en">
! 795: <div class="titlepage"><div><div><h4 class="title">
! 796: <a name="uptodate-cvs-changes"></a>2.2.2.2. What happens to my changes when updating?</h4></div></div></div>
! 797: <p>When you update pkgsrc, the CVS program will only touch
! 798: those files that are registered in the CVS repository. That
! 799: means that any packages that you created on your own will stay
! 800: unmodified. If you change files that are managed by CVS, later
! 801: updates will try to merge your changes with those that have been
! 802: done by others. See the CVS manual, chapter
! 803: “<span class="quote">update</span>” for details.</p>
! 804: </div>
! 805: </div>
! 806: </div>
! 807: </div>
! 808: <div class="chapter" lang="en">
! 809: <div class="titlepage"><div><div><h2 class="title">
! 810: <a name="platforms"></a>Chapter 3. Using pkgsrc on systems other than NetBSD</h2></div></div></div>
! 811: <div class="toc">
! 812: <p><b>Table of Contents</b></p>
! 813: <dl>
! 814: <dt><span class="sect1"><a href="#bootstrapping-pkgsrc">3.1. Bootstrapping pkgsrc</a></span></dt>
! 815: <dt><span class="sect1"><a href="#platform-specific-notes">3.2. Platform-specific notes</a></span></dt>
! 816: <dd><dl>
! 817: <dt><span class="sect2"><a href="#darwin">3.2.1. Darwin (Mac OS X)</a></span></dt>
! 818: <dt><span class="sect2"><a href="#freebsd">3.2.2. FreeBSD</a></span></dt>
! 819: <dt><span class="sect2"><a href="#interix">3.2.3. Interix</a></span></dt>
! 820: <dt><span class="sect2"><a href="#irix">3.2.4. IRIX</a></span></dt>
! 821: <dt><span class="sect2"><a href="#linux">3.2.5. Linux</a></span></dt>
! 822: <dt><span class="sect2"><a href="#openbsd">3.2.6. OpenBSD</a></span></dt>
! 823: <dt><span class="sect2"><a href="#solaris">3.2.7. Solaris</a></span></dt>
! 824: </dl></dd>
! 825: </dl>
! 826: </div>
! 827: <div class="sect1" lang="en">
! 828: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 829: <a name="bootstrapping-pkgsrc"></a>3.1. Bootstrapping pkgsrc</h2></div></div></div>
! 830: <p>For operating systems other than NetBSD, we provide a bootstrap kit to
! 831: build the required tools to use pkgsrc on your platform. Besides
! 832: support for native NetBSD, pkgsrc and the bootstrap kit have support for
! 833: the following operating systems:</p>
! 834: <div class="itemizedlist"><ul type="disc">
! 835: <li><p>Darwin (Mac OS X)</p></li>
! 836: <li><p>DragonFly BSD</p></li>
! 837: <li><p>FreeBSD</p></li>
! 838: <li><p>Interix (Windows 2000, XP, 2003)</p></li>
! 839: <li><p>IRIX</p></li>
! 840: <li><p>Linux</p></li>
! 841: <li><p>OpenBSD</p></li>
! 842: <li><p>Solaris</p></li>
! 843: <li><p>Tru64 (Digital UNIX/OSF1)</p></li>
! 844: </ul></div>
! 845: <p>Support for other platforms is under development.</p>
! 846: <p>Installing the bootstrap kit should be as simple as:</p>
! 847: <pre class="screen">
! 848: <code class="prompt">#</code> <strong class="userinput"><code>env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc</code></strong>
! 849: <code class="prompt">#</code> <strong class="userinput"><code>cd pkgsrc/bootstrap</code></strong>
! 850: <code class="prompt">#</code> <strong class="userinput"><code>./bootstrap</code></strong></pre>
! 851: <p>See <a href="#getting" title="Chapter 2. Where to get pkgsrc and how to keep it up-to-date">Chapter 2, <i>Where to get pkgsrc and how to keep it up-to-date</i></a> for other ways to get
! 852: pkgsrc before bootstrapping. The given
! 853: <span><strong class="command">bootstrap</strong></span> command will use the defaults of
! 854: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> for the
! 855: <span class="emphasis"><em>prefix</em></span> where programs will be installed in,
! 856: and <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/var/db/pkg</code> for the package database
! 857: directory where pkgsrc will do its internal bookkeeping.
! 858: However, these can also be set using command-line
! 859: arguments.</p>
! 860: <p>Binary packages for the pkgsrc tools and an initial set of packages is
! 861: available for supported platforms. An up-to-date list of these can be
! 862: found on <a href="http://www.pkgsrc.org/" target="_top">www.pkgsrc.org</a>.
! 863: Note that this only works for privileged builds that install
! 864: into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>.</p>
! 865: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 866: <h3 class="title">Note</h3>
! 867: <p>The bootstrap installs a <span><strong class="command">bmake</strong></span> tool.
! 868: Use this <span><strong class="command">bmake</strong></span> when building via pkgsrc.
! 869: For examples in this guide, use <span><strong class="command">bmake</strong></span>
! 870: instead of “<span class="quote">make</span>”.</p>
! 871: </div>
! 872: </div>
! 873: <div class="sect1" lang="en">
! 874: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 875: <a name="platform-specific-notes"></a>3.2. Platform-specific notes</h2></div></div></div>
! 876: <p>Here are some platform-specific notes you should be aware of.</p>
! 877: <div class="sect2" lang="en">
! 878: <div class="titlepage"><div><div><h3 class="title">
! 879: <a name="darwin"></a>3.2.1. Darwin (Mac OS X)</h3></div></div></div>
! 880: <p>Darwin 5.x and 6.x are supported. There are two methods of using
! 881: pkgsrc on Mac OS X, by using a <a href="#platform.osx-image" title="3.2.1.1. Using a disk image">disk
! 882: image</a>, or a <a href="#platform.osx-ufs" title="3.2.1.2. Using a UFS partition">UFS
! 883: partition</a>.</p>
! 884: <p>Before you start, you will need to download and install the Mac OS X Developer
! 885: Tools from Apple's Developer Connection. See <a href="http://developer.apple.com/macosx/" target="_top">http://developer.apple.com/macosx/</a>
! 886: for details. Also, make sure you install X11 for Mac OS X and the X11 SDK
! 887: from <a href="http://www.apple.com/macosx/x11/download/" target="_top">http://www.apple.com/macosx/x11/download/</a>
! 888: if you intend to build packages that use the X11 Window System.</p>
! 889: <p>If you already have a UFS partition, or have a spare partition
! 890: that you can format as UFS, it is recommended to use that instead of
! 891: the disk image. It'll be somewhat faster and will mount automatically
! 892: at boot time, where you must manually mount a disk image.</p>
! 893: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 894: <h3 class="title">Note</h3>
! 895: <p>You cannot use a HFS+ file system for pkgsrc, because pkgsrc currently
! 896: requires the file system to be case-sensitive, and HFS+ is not.</p>
! 897: </div>
! 898: <div class="sect3" lang="en">
! 899: <div class="titlepage"><div><div><h4 class="title">
! 900: <a name="platform.osx-image"></a>3.2.1.1. Using a disk image</h4></div></div></div>
! 901: <p>Create the disk image:</p>
! 902: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd pkgsrc/bootstrap</code></strong>
! 903: <code class="prompt">#</code> <strong class="userinput"><code>./ufsdiskimage create ~/Documents/NetBSD 512</code></strong> # megabytes - season to taste
! 904: <code class="prompt">#</code> <strong class="userinput"><code>./ufsdiskimage mount ~/Documents/NetBSD</code></strong>
! 905: <code class="prompt">#</code> <strong class="userinput"><code>sudo chown `id -u`:`id -g` /Volumes/NetBSD</code></strong></pre>
! 906: <p>That's it!</p>
! 907: </div>
! 908: <div class="sect3" lang="en">
! 909: <div class="titlepage"><div><div><h4 class="title">
! 910: <a name="platform.osx-ufs"></a>3.2.1.2. Using a UFS partition</h4></div></div></div>
! 911: <p>By default, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr</code> will be on your root file
! 912: system, normally HFS+. It is possible to use the default
! 913: <span class="emphasis"><em>prefix</em></span> of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>
! 914: by symlinking <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> to a directory on a UFS
! 915: file system. Obviously, another symlink is required if you want to
! 916: place the package database directory outside the
! 917: <span class="emphasis"><em>prefix</em></span>. e.g.</p>
! 918: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>./bootstrap --pkgdbdir /usr/pkg/pkgdb</code></strong></pre>
! 919: <p>If you created your partitions at the time of installing Mac OS X
! 920: and formatted the target partition as UFS, it should automatically
! 921: mount on <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/Volumes/<volume name></code> when the
! 922: machine boots. If you are (re)formatting a partition as UFS, you need
! 923: to ensure that the partition map correctly reflects
! 924: “<span class="quote">Apple_UFS</span>” and not “<span class="quote">Apple_HFS</span>”.</p>
! 925: <p>The problem is that none of the disk tools will let you touch a
! 926: disk that is booted from. You can unmount the partition, but even if
! 927: you newfs it, the partition type will be incorrect and the
! 928: automounter won't mount it. It can be mounted manually, but it won't
! 929: appear in Finder.</p>
! 930: <p>You'll need to boot off of the OS X Installation (User) CD. When
! 931: the Installation program starts, go up to the menu and select Disk
! 932: Utility. Now, you will be able to select the partition you want
! 933: to be UFS, and Format it Apple UFS. Quit the Disk Utility, quit the
! 934: installer which will reboot your machine. The new UFS file system
! 935: will appear in Finder.</p>
! 936: <p>Be aware that the permissions on the new file system will be writable
! 937: by root only.</p>
! 938: <p>This note is as of 10.2 (Jaguar) and applies to earlier versions.
! 939: Hopefully Apple will fix Disk Utility in 10.3 (Panther).</p>
! 940: </div>
! 941: </div>
! 942: <div class="sect2" lang="en">
! 943: <div class="titlepage"><div><div><h3 class="title">
! 944: <a name="freebsd"></a>3.2.2. FreeBSD</h3></div></div></div>
! 945: <p>
! 946: FreeBSD 4.7 and 5.0 have been tested and are supported, other versions
! 947: may work.</p>
! 948: <p>Care should be taken so that the tools that this kit installs do not conflict
! 949: with the FreeBSD userland tools. There are several steps:</p>
! 950: <div class="orderedlist"><ol type="1">
! 951: <li><p>FreeBSD stores its ports pkg database in
! 952: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/var/db/pkg</code>. It is therefore
! 953: recommended that you choose a different location (e.g.
! 954: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgdb</code>) by
! 955: using the --pkgdbdir option to the bootstrap script.</p></li>
! 956: <li>
! 957: <p>If you do not intend to use the FreeBSD ports tools, it's probably a
! 958: good idea to move them out of the way to avoid confusion, e.g.</p>
! 959: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sbin</code></strong>
! 960: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_add pkg_add.orig</code></strong>
! 961: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_create pkg_create.orig</code></strong>
! 962: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
! 963: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_info pkg_info.orig</code></strong></pre>
! 964: </li>
! 965: <li><p>An example <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> file will be placed in
! 966: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf.example</code> file
! 967: when you use the bootstrap script.</p></li>
! 968: </ol></div>
! 969: </div>
! 970: <div class="sect2" lang="en">
! 971: <div class="titlepage"><div><div><h3 class="title">
! 972: <a name="interix"></a>3.2.3. Interix</h3></div></div></div>
! 973: <p>Interix is a POSIX-compatible subsystem for the Windows NT kernel,
! 974: providing a Unix-like environment with a tighter kernel integration than
! 975: available with Cygwin. It is part of the Windows Services for Unix
! 976: package, available for free for any licensed copy of Windows 2000, XP
! 977: (not including XP Home), or 2003. SFU can be downloaded from <a href="http://www.microsoft.com/windows/sfu/" target="_top">http://www.microsoft.com/windows/sfu/</a>.</p>
! 978: <p>Services for Unix 3.5, current as of this writing, has been tested. 3.0
! 979: or 3.1 may work, but are not officially supported. (The main difference
! 980: in 3.0/3.1 is lack of pthreads.)</p>
! 981: <div class="sect3" lang="en">
! 982: <div class="titlepage"><div><div><h4 class="title">
! 983: <a name="platform.interix-sfu-install"></a>3.2.3.1. When installing Interix/SFU</h4></div></div></div>
! 984: <p>At an absolute minimum, the following packages must be installed from
! 985: the Windows Services for Unix 3.5 distribution in order to use pkgsrc:</p>
! 986: <div class="itemizedlist"><ul type="disc">
! 987: <li><p>Utilities -> Base Utilities</p></li>
! 988: <li><p>Interix GNU Components -> (all)</p></li>
! 989: <li><p>Remote Connectivity</p></li>
! 990: <li><p>Interix SDK</p></li>
! 991: </ul></div>
! 992: <p>When using pkgsrc on Interix, DO NOT install the Utilities subcomponent
! 993: "UNIX Perl". That is Perl 5.6 without shared module support, installed to
! 994: /usr/local, and will only cause confusion. Instead, install Perl 5.8 from
! 995: pkgsrc (or from a binary package).</p>
! 996: <p>The Remote Connectivity subcomponent "Windows Remote Shell Service" does
! 997: not need to be installed, but Remote Connectivity itself should be
! 998: installed in order to have a working inetd.</p>
! 999: <p>During installation you may be asked whether to enable setuid
! 1000: behavior for Interix programs, and whether to make pathnames default to
! 1001: case-sensitive. Setuid should be enabled, and case-sensitivity MUST be
! 1002: enabled. (Without case-sensitivity, a large number of packages including
! 1003: perl will not build.)</p>
! 1004: <p>NOTE: Newer Windows service packs change the way binary execution
! 1005: works (via the Data Execution Prevention feature). In order to use
! 1006: pkgsrc and other gcc-compiled binaries reliably, a hotfix containing
! 1007: POSIX.EXE, PSXDLL.DLL, PSXRUN.EXE, and PSXSS.EXE (899522 or newer)
! 1008: must be installed. Hotfixes are available from Microsoft through a
! 1009: support contract; however, a NetBSD developer has made most Interix
! 1010: hotfixes available for personal use from <a href="http://www.duh.org/interix/hotfixes.php" target="_top">http://www.duh.org/interix/hotfixes.php</a>.</p>
! 1011: </div>
! 1012: <div class="sect3" lang="en">
! 1013: <div class="titlepage"><div><div><h4 class="title">
! 1014: <a name="platform.interix-sfu-postinstall"></a>3.2.3.2. What to do if Interix/SFU is already installed</h4></div></div></div>
! 1015: <p>If SFU is already installed and you wish to alter these settings to work
! 1016: with pkgsrc, note the following things.</p>
! 1017: <div class="itemizedlist"><ul type="disc">
! 1018: <li><p>To uninstall UNIX Perl, use Add/Remove Programs, select Microsoft
! 1019: Windows Services for UNIX, then click Change. In the installer, choose
! 1020: Add or Remove, then uncheck Utilities->UNIX Perl.</p></li>
! 1021: <li>
! 1022: <p>To enable case-sensitivity for the file system, run REGEDIT.EXE, and
! 1023: change the following registry key:</p>
! 1024: <p>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel</p>
! 1025: <p>Set the DWORD value "obcaseinsensitive" to 0; then reboot.</p>
! 1026: </li>
! 1027: <li>
! 1028: <p>To enable setuid binaries (optional), run REGEDIT.EXE, and change the
! 1029: following registry key:</p>
! 1030: <p>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Services for UNIX</p>
! 1031: <p>Set the DWORD value "EnableSetuidBinaries" to 1; then reboot.</p>
! 1032: </li>
! 1033: </ul></div>
! 1034: </div>
! 1035: <div class="sect3" lang="en">
! 1036: <div class="titlepage"><div><div><h4 class="title">
! 1037: <a name="platform.interix-notes"></a>3.2.3.3. Important notes for using pkgsrc</h4></div></div></div>
! 1038: <p>The package manager (either the pkgsrc "su" user, or the user
! 1039: running "pkg_add") must be a member of the local Administrators
! 1040: group. Such a user must also be used to run the bootstrap. This is
! 1041: slightly relaxed from the normal pkgsrc requirement of "root".</p>
! 1042: <p>The package manager should use a umask of 002. "make install" will
! 1043: automatically complain if this is not the case. This ensures that
! 1044: directories written in /var/db/pkg are Administrators-group writeable.</p>
! 1045: <p>The popular Interix binary packages from http://www.interopsystems.com/
! 1046: use an older version of pkgsrc's pkg_* tools. Ideally, these should
! 1047: NOT be used in conjunction with pkgsrc. If you choose to use them at
! 1048: the same time as the pkgsrc packages, ensure that you use the proper
! 1049: pkg_* tools for each type of binary package.</p>
! 1050: <p>The TERM setting used for DOS-type console windows (including those
! 1051: invoked by the csh and ksh startup shortcuts) is "interix". Most systems
! 1052: don't have a termcap/terminfo entry for it, but the following .termcap
! 1053: entry provides adequate emulation in most cases:</p>
! 1054: <pre class="programlisting">
! 1055: interix:kP=\E[S:kN=\E[T:kH=\E[U:dc@:DC@:tc=pcansi:
! 1056: </pre>
! 1057: </div>
! 1058: <div class="sect3" lang="en">
! 1059: <div class="titlepage"><div><div><h4 class="title">
! 1060: <a name="platform.interix-limits"></a>3.2.3.4. Limitations of the Interix platform</h4></div></div></div>
! 1061: <p>Though Interix suffices as a familiar and flexible substitute
! 1062: for a full Unix-like platform, it has some drawbacks that should
! 1063: be noted for those desiring to make the most of Interix.</p>
! 1064: <div class="itemizedlist"><ul type="disc">
! 1065: <li>
! 1066: <p><span class="strong"><strong>X11:</strong></span></p>
! 1067: <p>Interix comes with the standard set of X11R6 client libraries,
! 1068: and can run X11 based applications, but it does
! 1069: <span class="emphasis"><em>not</em></span> come with an X server. Some options are
! 1070: <a href="http://www.starnet.com/products/xwin32/" target="_top">StarNet X-Win32</a>,
! 1071: <a href="http://connectivity.hummingbird.com/products/nc/exceed/" target="_top">Hummingbird Exceed</a>
! 1072: (available in a trimmed version for Interix from Interop Systems as the
! 1073: <a href="http://www.interopsystems.com/InteropXserver.htm" target="_top">Interop X Server</a>),
! 1074: and the free X11 server included with
! 1075: <a href="http://x.cygwin.com/" target="_top">Cygwin</a>.</p>
! 1076: <p>Also, StarNet Communications has graciously provided a free
! 1077: version of their X-Win32 product that accepts connections only
! 1078: from localhost:
! 1079: <a href="http://www.starnet.com/xwin32LX/get_xwin32LX.htm" target="_top">X-Win32 LX</a>,
! 1080: recommended by the maintainer of Interix pkgsrc support.</p>
! 1081: </li>
! 1082: <li>
! 1083: <p><span class="strong"><strong>X11 acceleration:</strong></span></p>
! 1084: <p>Because Interix runs in a completely different NT subsystem from
! 1085: Win32 applications, it does not currently support various X11
! 1086: protocol extensions for acceleration (such as MIT-SHM or DGA).
! 1087: Most interactive applications to a local X server will run
! 1088: reasonably fast, but full motion video and other graphics
! 1089: intensive applications may require a faster-than-expected CPU.</p>
! 1090: </li>
! 1091: <li>
! 1092: <p><span class="strong"><strong>Audio:</strong></span></p>
! 1093: <p>Interix has no native support for audio output. For audio
! 1094: support, pkgsrc uses the <span><strong class="command">esound</strong></span> client/server
! 1095: audio system on Interix. Unlike on most platforms, the
! 1096: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/audio/esound/README.html" target="_top"><code xmlns="" class="filename">audio/esound</code></a> package does
! 1097: <span class="emphasis"><em>not</em></span> contain the <span><strong class="command">esd</strong></span>
! 1098: server component. To output audio via an Interix host, the
! 1099: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/emulators/cygwin_esound/README.html" target="_top"><code xmlns="" class="filename">emulators/cygwin_esound</code></a> package
! 1100: must also be installed.</p>
! 1101: </li>
! 1102: <li>
! 1103: <p><span class="strong"><strong>CD/DVDs, USB, and SCSI:</strong></span></p>
! 1104: <p>Direct device access is not currently supported in Interix, so it
! 1105: is not currently possible to access CD/DVD drives, USB devices,
! 1106: or SCSI devices through non-filesystem means. Among other things,
! 1107: this makes it impossible to use Interix directly for CD/DVD
! 1108: burning.</p>
! 1109: </li>
! 1110: <li>
! 1111: <p><span class="strong"><strong>Tape drives:</strong></span></p>
! 1112: <p>Due to the same limitations as for CD-ROMs and SCSI devices, tape
! 1113: drives are also not directly accessible in Interix. However,
! 1114: support is in work to make tape drive access possible by using
! 1115: Cygwin as a bridge (similarly to audio bridged via Cygwin's
! 1116: esound server).</p>
! 1117: </li>
! 1118: </ul></div>
! 1119: </div>
! 1120: <div class="sect3" lang="en">
! 1121: <div class="titlepage"><div><div><h4 class="title">
! 1122: <a name="platform.interix-knownissues"></a>3.2.3.5. Known issues for pkgsrc on Interix</h4></div></div></div>
! 1123: <p>It is not necessary, in general, to have a "root" user on the
! 1124: Windows system; any member of the local Administrators group will
! 1125: suffice. However, some packages currently assume that the user
! 1126: named "root" is the privileged user. To accommodate these, you
! 1127: may create such a user; make sure it is in the local group
! 1128: Administrators (or your language equivalent).</p>
! 1129: <p>"pkg_add" creates directories of mode 0755, not 0775, in
! 1130: $PKG_DBDIR. For the time being, install packages as the local
! 1131: Administrator (or your language equivalent), or run the following
! 1132: command after installing a package to work around the issue:</p>
! 1133: <pre class="screen">
! 1134: <code class="prompt">#</code> <strong class="userinput"><code>chmod -R g+w $PKG_DBDIR</code></strong></pre>
! 1135: </div>
! 1136: </div>
! 1137: <div class="sect2" lang="en">
! 1138: <div class="titlepage"><div><div><h3 class="title">
! 1139: <a name="irix"></a>3.2.4. IRIX</h3></div></div></div>
! 1140: <p>You will need a working C compiler, either gcc or SGI's MIPS and MIPSpro
! 1141: compiler (cc/c89). Please set the <code class="varname">CC</code> environment variable
! 1142: according to your preference. If you do not have a license for the MIPSpro
! 1143: compiler suite, you can download a gcc tardist file from <a href="http://freeware.sgi.com/" target="_top">http://freeware.sgi.com/</a>.</p>
! 1144: <p>Please note that you will need IRIX 6.5.17 or higher, as this is the earliest
! 1145: version of IRIX providing support for <a href="http://netbsd.gw.com/cgi-bin/man-cgi?if_indextoname+3+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">if_indextoname</span>(3)</span></a>, <a href="http://netbsd.gw.com/cgi-bin/man-cgi?if_nametoindex+3+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">if_nametoindex</span>(3)</span></a>,
! 1146: etc.</p>
! 1147: <p>At this point in time, pkgsrc only supports one ABI at a time. That is, you can not
! 1148: switch between the old 32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If
! 1149: you start out using "abi=n32", that's what all your packages will be built
! 1150: with.</p>
! 1151: <p>Therefore, please make sure that you have no conflicting
! 1152: <code class="varname">CFLAGS</code> in your environment or the
! 1153: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>. Particularly, make sure that you do not
! 1154: try to link n32 object files with lib64 or vice versa. Check your
! 1155: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/compiler.defaults</code>!</p>
! 1156: <p>If you have the actual pkgsrc tree mounted via NFS from a different host,
! 1157: please make sure to set <code class="varname">WRKOBJDIR</code> to a local directory,
! 1158: as it appears that IRIX linker occasionally runs into issues when trying to
! 1159: link over a network-mounted file system.</p>
! 1160: <p>The bootstrapping process should set all the right options for programs such
! 1161: as imake(1), but you may want to set some options depending on your local
! 1162: setup. Please see <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code> and, of
! 1163: course, your compiler's man pages for details.</p>
! 1164: <p>If you are using SGI's MIPSPro compiler, please set
1.1 grant 1165:
1.75 ! rillig 1166: </p>
! 1167: <pre class="programlisting">
! 1168: PKGSRC_COMPILER= mipspro
! 1169: </pre>
! 1170: <p>
1.1 grant 1171:
1.75 ! rillig 1172: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>. Otherwise, pkgsrc will assume you
! 1173: are using gcc and may end up passing invalid flags to the compiler. Note that
! 1174: bootstrap should create an appropriate <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf.example</code> by
! 1175: default.</p>
! 1176: <p>If you have both the MIPSPro compiler chain installed as well as gcc,
! 1177: but want to make sure that MIPRPro is used, please set your <code class="varname">PATH</code>
! 1178: to <span class="emphasis"><em>not</em></span> include the location of gcc (often
! 1179: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/freeware/bin</code>), and (important) pass the
! 1180: '--preserve-path' flag.</p>
! 1181: </div>
! 1182: <div class="sect2" lang="en">
! 1183: <div class="titlepage"><div><div><h3 class="title">
! 1184: <a name="linux"></a>3.2.5. Linux</h3></div></div></div>
! 1185: <p>
! 1186: Some versions of Linux (for example Debian GNU/Linux) need either
! 1187: libtermcap or libcurses (libncurses). Installing the distributions
! 1188: libncurses-dev package (or equivalent) should fix the problem.</p>
! 1189: <p>
! 1190: pkgsrc supports both gcc (GNU Compiler Collection) and icc (Intel C++
! 1191: Compiler). gcc is the default. icc 8.0 and 8.1 on i386 have been tested.
! 1192: </p>
! 1193: <p>To bootstrap using icc, assuming the default icc installation
! 1194: directory:</p>
! 1195: <pre class="programlisting">
! 1196: env CC=/opt/intel_cc_80/bin/icc LDFLAGS=-static-libcxa \
! 1197: ac_cv___attribute__=yes ./bootstrap
! 1198: </pre>
! 1199: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 1200: <h3 class="title">Note</h3>
! 1201: <p>icc 8.1 needs the `-i-static' argument instead of -static-libcxa.</p>
! 1202: </div>
! 1203: <p>icc supports __attribute__, but the GNU configure test uses a nested
! 1204: function, which icc does not support. #undef'ing __attribute__ has the
! 1205: unfortunate side-effect of breaking many of the Linux header files, which
! 1206: cannot be compiled properly without __attribute__. The test must be
! 1207: overridden so that __attribute__ is assumed supported by the
! 1208: compiler.</p>
! 1209: <p>After bootstrapping, you should set <code class="varname">PKGSRC_COMPILER</code>
! 1210: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>:</p>
! 1211: <pre class="programlisting">
! 1212: PKGSRC_COMPILER= icc
! 1213: </pre>
! 1214: <p>The default installation directory for icc is
! 1215: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/opt/intel_cc_80</code>, which
! 1216: is also the pkgsrc default. If you have installed it into a different
! 1217: directory, set <code class="varname">ICCBASE</code> in
! 1218: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>:</p>
! 1219: <pre class="programlisting">
! 1220: ICCBASE= /opt/icc
! 1221: </pre>
! 1222: <p>pkgsrc uses the static linking method of the runtime libraries
! 1223: provided by icc, so binaries can be run on other systems which do not
! 1224: have the shared libraries installed.</p>
! 1225: <p>Libtool, however, extracts a list of libraries from the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ld</span>(1)</span></a>
! 1226: command run when linking a C++ shared library and records it, throwing
! 1227: away the -Bstatic and -Bdynamic options interspersed between the libraries.
! 1228: This means that libtool-linked C++ shared libraries will have a
! 1229: runtime dependency on the icc libraries until this is fixed in libtool.
! 1230: </p>
! 1231: </div>
! 1232: <div class="sect2" lang="en">
! 1233: <div class="titlepage"><div><div><h3 class="title">
! 1234: <a name="openbsd"></a>3.2.6. OpenBSD</h3></div></div></div>
! 1235: <p>OpenBSD 3.0 and 3.2 are tested and supported.</p>
! 1236: <p>Care should be taken so that the tools that this kit installs do not conflict
! 1237: with the OpenBSD userland tools. There are several steps:</p>
! 1238: <div class="orderedlist"><ol type="1">
! 1239: <li><p>OpenBSD stores its ports pkg database in
! 1240: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/var/db/pkg</code>. It is therefore
! 1241: recommended that you choose a different location (e.g.
! 1242: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgdb</code>) by
! 1243: using the --pkgdbdir option to the bootstrap script.</p></li>
! 1244: <li>
! 1245: <p>If you do not intend to use the OpenBSD ports tools, it's probably a
! 1246: good idea to move them out of the way to avoid confusion, e.g.</p>
! 1247: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sbin</code></strong>
! 1248: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_add pkg_add.orig</code></strong>
! 1249: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_create pkg_create.orig</code></strong>
! 1250: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
! 1251: <code class="prompt">#</code> <strong class="userinput"><code>mv pkg_info pkg_info.orig</code></strong></pre>
! 1252: </li>
! 1253: <li>
! 1254: <p>An example <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> file will be placed in
! 1255: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf.example</code> file
! 1256: when you use the bootstrap script. OpenBSD's make program uses
! 1257: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>
! 1258: as well. You can work around this by enclosing all the pkgsrc-specific parts
! 1259: of the file with:</p>
! 1260: <pre class="programlisting">
! 1261: .ifdef BSD_PKG_MK
! 1262: # pkgsrc stuff, e.g. insert defaults/mk.conf or similar here
! 1263: .else
! 1264: # OpenBSD stuff
1.1 grant 1265: .endif
1266: </pre>
1.75 ! rillig 1267: </li>
! 1268: </ol></div>
! 1269: </div>
! 1270: <div class="sect2" lang="en">
! 1271: <div class="titlepage"><div><div><h3 class="title">
! 1272: <a name="solaris"></a>3.2.7. Solaris</h3></div></div></div>
! 1273: <p>Solaris 2.6 through 9 are supported on both x86 and sparc.
! 1274: You will need a working C compiler. Both gcc 2.95.3 and
! 1275: Sun WorkShop 5 have been tested.</p>
! 1276: <p>The following packages are required on Solaris 8 for the bootstrap
! 1277: process and to build packages.</p>
! 1278: <div class="itemizedlist"><ul type="disc">
! 1279: <li><p>SUNWsprot</p></li>
! 1280: <li><p>SUNWarc</p></li>
! 1281: <li><p>SUNWbtool</p></li>
! 1282: <li><p>SUNWtoo</p></li>
! 1283: <li><p>SUNWlibm</p></li>
! 1284: </ul></div>
! 1285: <p>Please note the use of GNU binutils on Solaris is
! 1286: <span class="emphasis"><em>not</em></span> supported.</p>
! 1287: <p>Whichever compiler you use, please ensure the compiler tools and
! 1288: your $prefix are in your <code class="varname">PATH</code>. This includes
! 1289: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/ccs/{bin,lib}</code>
! 1290: and e.g. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg/{bin,sbin}</code>.</p>
! 1291: <div class="sect3" lang="en">
! 1292: <div class="titlepage"><div><div><h4 class="title">
! 1293: <a name="solaris-gcc-note"></a>3.2.7.1. If you are using gcc</h4></div></div></div>
! 1294: <p>It makes life much simpler if you only use the same gcc consistently
! 1295: for building all packages.</p>
! 1296: <p>It is recommended that an external gcc be used only for bootstrapping,
! 1297: then either build gcc from
! 1298: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/gcc/README.html" target="_top"><code xmlns="" class="filename">lang/gcc</code></a> or install a binary gcc
! 1299: package, then remove gcc used during bootstrapping.</p>
! 1300: <p>Binary packages of gcc can be found through <a href="http://www.sun.com/bigadmin/common/freewareSearch.html" target="_top">http://www.sun.com/bigadmin/common/freewareSearch.html</a>.</p>
! 1301: </div>
! 1302: <div class="sect3" lang="en">
! 1303: <div class="titlepage"><div><div><h4 class="title">
! 1304: <a name="solaris-sun-workshop-note"></a>3.2.7.2. If you are using Sun WorkShop</h4></div></div></div>
! 1305: <p>You will need at least the following packages installed (from WorkShop
! 1306: 5.0)</p>
! 1307: <div class="itemizedlist"><ul type="disc">
! 1308: <li><p>SPROcc
! 1309: - Sun WorkShop Compiler C 5.0</p></li>
! 1310: <li><p>SPROcpl
! 1311: - Sun WorkShop Compiler C++ 5.0</p></li>
! 1312: <li><p>SPROild
! 1313: - Sun WorkShop Incremental Linker</p></li>
! 1314: <li><p>SPROlang
! 1315: - Sun WorkShop Compilers common components</p></li>
! 1316: </ul></div>
! 1317: <p>You should set <code class="varname">CC</code>, <code class="varname">CXX</code> and
! 1318: optionally, <code class="varname">CPP</code> in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>,
! 1319: e.g.:</p>
! 1320: <pre class="programlisting">
! 1321: CC= cc
! 1322: CXX= CC
! 1323: CPP= /usr/ccs/lib/cpp
1.1 grant 1324: </pre>
1.75 ! rillig 1325: </div>
! 1326: <div class="sect3" lang="en">
! 1327: <div class="titlepage"><div><div><h4 class="title">
! 1328: <a name="solaris-sunpro-64"></a>3.2.7.3. Buildling 64-bit binaries with SunPro</h4></div></div></div>
! 1329: <p>Building 64-bit binaries is a little trickier. First, you
! 1330: need to bootstrap pkgsrc in 64-bit mode. One problem here is
! 1331: that while building one of the programs in the bootstrap kit
! 1332: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bmake</code>), the <code class="varname">CFLAGS</code>
! 1333: variable is not honored, even if it is set in the environment.
! 1334: To work around this bug, you can create a simple shell script
! 1335: called <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">cc64</code> and put it somewhere in the
! 1336: <code class="varname">PATH</code>:</p>
! 1337: <pre class="programlisting">
! 1338: #! /bin/sh
! 1339: exec /opt/SUNWspro/bin/cc -xtarget=ultra -xarch=v9 ${1+"$@"}
1.1 grant 1340: </pre>
1.75 ! rillig 1341: <p>Then, pass the definition for <code class="varname">CC</code> in the
! 1342: environment of the <span><strong class="command">bootstrap</strong></span> command:</p>
! 1343: <pre class="programlisting">
! 1344: <code class="prompt">$</code> <strong class="userinput"><code>cd bootstrap</code></strong>
! 1345: <code class="prompt">$</code> <strong class="userinput"><code>CC=cc64 ./bootstrap</code></strong>
! 1346: </pre>
! 1347: <p>After bootstrapping, there are two alternative ways,
! 1348: depending on whether you want to find bugs in packages or get
! 1349: your system ready quickly. If you just want a running system,
! 1350: add the following lines to your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf</code>
! 1351: file:</p>
! 1352: <pre class="programlisting">
! 1353: CC= cc64
! 1354: CXX= CC64
! 1355: PKGSRC_COMPILER= sunpro
1.1 grant 1356: </pre>
1.75 ! rillig 1357: <p>This way, all calls to the compiler will be intercepted by
! 1358: the above wrapper and therefore get the necessary ABI options
! 1359: automatically. (Don't forget to create the shell script
! 1360: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">CC64</code>, too.)</p>
! 1361: <p>To find packages that ignore the user-specified
! 1362: <code class="varname">CFLAGS</code> and <code class="varname">CXXFLAGS</code>, add
! 1363: the following lines to your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf</code>
! 1364: file:</p>
! 1365: <pre class="programlisting">
! 1366: CC= cc
! 1367: CXX= CC
! 1368: PKGSRC_COMPILER= sunpro
! 1369: CFLAGS= -xtarget=ultra -xarch=v9
! 1370: CXXFLAGS= -xtarget=ultra -xarch=v9
! 1371: LDFLAGS= -xtarget=ultra -xarch=v9
1.1 grant 1372: </pre>
1.75 ! rillig 1373: <p>Packages that don't use the flags provided in the
! 1374: configuration file will try to build 32-bit binaries and fail
! 1375: during linking. Detecting this is useful to prevent bugs on
! 1376: other platforms where the error would not show up but pass
! 1377: silently.</p>
! 1378: </div>
! 1379: <div class="sect3" lang="en">
! 1380: <div class="titlepage"><div><div><h4 class="title">
! 1381: <a name="plat.sunos.problems"></a>3.2.7.4. Common problems</h4></div></div></div>
! 1382: <p>Sometimes, when using <span><strong class="command">libtool</strong></span>,
! 1383: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/bin/ksh</code> crashes with a segmentation fault.
! 1384: The workaround is to use another shell for the configure
! 1385: scripts, for example by installing <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/bash/README.html" target="_top"><code xmlns="" class="filename">shells/bash</code></a> and adding the following lines
! 1386: to your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf</code>:</p>
! 1387: <pre class="programlisting">
! 1388: CONFIG_SHELL= ${LOCALBASE}/bin/bash
! 1389: WRAPPER_SHELL= ${LOCALBASE}/bin/bash
1.1 grant 1390: </pre>
1.75 ! rillig 1391: <p>Then, rebuild the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool-base/README.html" target="_top"><code xmlns="" class="filename">devel/libtool-base</code></a> package.</p>
! 1392: </div>
! 1393: </div>
! 1394: </div>
! 1395: </div>
! 1396: <div class="chapter" lang="en">
! 1397: <div class="titlepage"><div><div><h2 class="title">
! 1398: <a name="using"></a>Chapter 4. Using pkgsrc</h2></div></div></div>
! 1399: <div class="toc">
! 1400: <p><b>Table of Contents</b></p>
! 1401: <dl>
! 1402: <dt><span class="sect1"><a href="#using-pkg">4.1. Using binary packages</a></span></dt>
! 1403: <dd><dl>
! 1404: <dt><span class="sect2"><a href="#finding-binary-packages">4.1.1. Finding binary packages</a></span></dt>
! 1405: <dt><span class="sect2"><a href="#installing-binary-packages">4.1.2. Installing binary packages</a></span></dt>
! 1406: <dt><span class="sect2"><a href="#a-word-of-warning">4.1.3. A word of warning</a></span></dt>
! 1407: </dl></dd>
! 1408: <dt><span class="sect1"><a href="#building-packages-from-source">4.2. Building packages from source</a></span></dt>
! 1409: <dd><dl>
! 1410: <dt><span class="sect2"><a href="#requirements">4.2.1. Requirements</a></span></dt>
! 1411: <dt><span class="sect2"><a href="#fetching-distfiles">4.2.2. Fetching distfiles</a></span></dt>
! 1412: <dt><span class="sect2"><a href="#how-to-build-and-install">4.2.3. How to build and install</a></span></dt>
! 1413: <dt><span class="sect2"><a href="#selecting-the-compiler">4.2.4. Selecting the compiler</a></span></dt>
! 1414: </dl></dd>
! 1415: </dl>
! 1416: </div>
! 1417: <p>Basically, there are two ways of using pkgsrc. The first
! 1418: is to only install the package tools and to use binary packages
! 1419: that someone else has prepared. This is the “<span class="quote">pkg</span>”
! 1420: in pkgsrc. The second way is to install the “<span class="quote">src</span>”
! 1421: of pkgsrc, too. Then you are able to build your own packages,
! 1422: and you can still use binary packages from someone else.</p>
! 1423: <div class="sect1" lang="en">
! 1424: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1425: <a name="using-pkg"></a>4.1. Using binary packages</h2></div></div></div>
! 1426: <p>To use binary packages, you need some tools to manage
! 1427: them. On NetBSD, these tools are already installed. On all other
! 1428: operating systems, you need to install them first. For the
! 1429: following platforms, prebuilt versions of the package tools
! 1430: are available and can simply be downloaded and unpacked in the
! 1431: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/</code> directory:</p>
! 1432: <div class="informaltable">
! 1433: <a name="binary-bootstrap-kits"></a><table border="1">
! 1434: <colgroup>
! 1435: <col>
! 1436: <col>
! 1437: </colgroup>
! 1438: <thead><tr>
! 1439: <th>Platform</th>
! 1440: <th>URL</th>
! 1441: </tr></thead>
! 1442: <tbody>
! 1443: <tr>
! 1444: <td>Solaris 9</td>
! 1445: <td><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/bootstrap-pkgsrc/</code></td>
! 1446: </tr>
! 1447: <tr>
! 1448: <td>Solaris 10</td>
! 1449: <td><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/</code></td>
! 1450: </tr>
! 1451: </tbody>
! 1452: </table>
! 1453: </div>
! 1454: <p>These prebuilt package tools use
! 1455: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> for the base directory, and
! 1456: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/var/db/pkg</code> for the database of installed
! 1457: packages. If you cannot use these directories for whatever
! 1458: reasons (maybe because you're not root), you have to build the
! 1459: package tools yourself, which is explained in <a href="#bootstrapping-pkgsrc" title="3.1. Bootstrapping pkgsrc">Section 3.1, “Bootstrapping pkgsrc”</a>.</p>
! 1460: <div class="sect2" lang="en">
! 1461: <div class="titlepage"><div><div><h3 class="title">
! 1462: <a name="finding-binary-packages"></a>4.1.1. Finding binary packages</h3></div></div></div>
! 1463: <p>To install binary packages, you first need to know from
! 1464: where to get them. You can get them on CD-ROMs, DVDs, or via FTP
! 1465: or HTTP.</p>
! 1466: <p>For NetBSD, the binary packages are made available on
! 1467: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp.NetBSD.org</code> and its mirrors, in the
! 1468: directory
! 1469: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/pub/NetBSD/packages/<em class="replaceable"><code>OSVERSION</code></em>/<em class="replaceable"><code>ARCH</code></em>/</code>.
! 1470: For <em class="replaceable"><code>OSVERSION</code></em>, you should insert the
! 1471: output of <span><strong class="command">uname -r</strong></span>, and for
! 1472: <em class="replaceable"><code>ARCH</code></em> the output of <span><strong class="command">uname
! 1473: -p</strong></span>.</p>
! 1474: <p>For some other platforms, binary packages can be found at
! 1475: the following locations:</p>
! 1476: <div class="informaltable">
! 1477: <a name="binary-packages"></a><table border="1">
! 1478: <colgroup>
! 1479: <col>
! 1480: <col>
! 1481: </colgroup>
! 1482: <thead><tr>
! 1483: <th>Platform</th>
! 1484: <th>URL</th>
! 1485: </tr></thead>
! 1486: <tbody>
! 1487: <tr>
! 1488: <td>Solaris 9</td>
! 1489: <td><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/</code></td>
! 1490: </tr>
! 1491: <tr>
! 1492: <td>Solaris 10</td>
! 1493: <td><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">http://public.enst.fr/pkgsrc/packages/</code></td>
! 1494: </tr>
! 1495: </tbody>
! 1496: </table>
! 1497: </div>
! 1498: <p>Most of these directories contain the pkgsrc distribution
! 1499: for multiple platforms. Select the appropriate subdirectories,
! 1500: according to your machine architecture and operating system,
! 1501: until you find a directory called <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">All</code>. This
! 1502: directory contains all the binary packages. Further, there are
! 1503: subdirectories for categories that contain symbolic links that
! 1504: point to the actual binary package in
! 1505: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../All</code>. This directory layout is used for
! 1506: all package repositories, no matter if they are accessed via
! 1507: HTTP, FTP, NFS, CD-ROM, or the local filesystem.</p>
! 1508: </div>
! 1509: <div class="sect2" lang="en">
! 1510: <div class="titlepage"><div><div><h3 class="title">
! 1511: <a name="installing-binary-packages"></a>4.1.2. Installing binary packages</h3></div></div></div>
! 1512: <p> If you have the files on a CD-ROM or downloaded them to
! 1513: your hard disk, you can install them with the following command
! 1514: (be sure to <span><strong class="command">su</strong></span> to root first):</p>
! 1515: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg_add /path/to/package.tgz</code></strong></pre>
! 1516: <p> If you have FTP access and you don't want to download the
! 1517: packages via FTP prior to installation, you can do this
! 1518: automatically by giving <span><strong class="command">pkg_add</strong></span> an FTP URL:
! 1519: </p>
! 1520: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/All/package.tgz</code></strong></pre>
! 1521: <p>Note that any prerequisite packages needed to run the
! 1522: package in question will be installed, too, assuming they are
! 1523: present where you install from. </p>
! 1524: <p>To save some typing, you can set the
! 1525: <code class="varname">PKG_PATH</code> environment variable to a semicolon-separated
! 1526: list of paths (including remote URLs); trailing slashes are not allowed.
! 1527: </p>
! 1528: <p>Additionally to the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">All</code> directory
! 1529: there exists a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">vulnerable</code> directory to
! 1530: which binary packages with known vulnerabilities are
! 1531: moved, since removing them could cause missing dependencies. To
! 1532: use these packages, add the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">vulnerable</code>
! 1533: directory to your <code class="varname">PKG_PATH</code>. However, you should run
! 1534: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html" target="_top"><code xmlns="" class="filename">security/audit-packages</code></a> regularly,
! 1535: especially after installing new packages, and verify that the
! 1536: vulnerabilities are acceptable for your configuration. An example
! 1537: <code class="varname">PKG_PATH</code> would be:
! 1538: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/vulnerable</code>
! 1539: Please note that semicolon (';') is a shell meta-character, so
! 1540: you'll probably have to quote it.</p>
! 1541: <p>After you've installed packages, be sure to have
! 1542: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg/bin</code> and <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg/sbin</code> in your
! 1543: <code class="varname">PATH</code> so you can actually start the just
! 1544: installed program. </p>
! 1545: </div>
! 1546: <div class="sect2" lang="en">
! 1547: <div class="titlepage"><div><div><h3 class="title">
! 1548: <a name="a-word-of-warning"></a>4.1.3. A word of warning</h3></div></div></div>
! 1549: <p>Please pay very careful attention to the warnings
! 1550: expressed in the <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> manual page about the
! 1551: inherent dangers of installing binary packages which you did
! 1552: not create yourself, and the security holes that can be
! 1553: introduced onto your system by indiscriminate adding of such
! 1554: files.</p>
! 1555: <p>The same warning of course applies to every package you
! 1556: install from source when you haven't completely read and
! 1557: understood the source code of the package, the compiler that
! 1558: is used to build the package and all the other tools that are
! 1559: involved.</p>
! 1560: </div>
! 1561: </div>
! 1562: <div class="sect1" lang="en">
! 1563: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1564: <a name="building-packages-from-source"></a>4.2. Building packages from source</h2></div></div></div>
! 1565: <p> This assumes that the package is already in pkgsrc. If it
! 1566: is not, see <a href="#developers-guide" title="Part II. The pkgsrc developer's guide">Part II, “The pkgsrc developer's guide”</a> for instructions
! 1567: how to create your own packages.</p>
! 1568: <div class="sect2" lang="en">
! 1569: <div class="titlepage"><div><div><h3 class="title">
! 1570: <a name="requirements"></a>4.2.1. Requirements</h3></div></div></div>
! 1571: <p> To build packages from source on a NetBSD system the
! 1572: “<span class="quote">comp</span>” and the “<span class="quote">text</span>” distribution
! 1573: sets must be installed. If you want to build X11-related
! 1574: packages the “<span class="quote">xbase</span>” and “<span class="quote">xcomp</span>”
! 1575: distribution sets are required, too.</p>
! 1576: </div>
! 1577: <div class="sect2" lang="en">
! 1578: <div class="titlepage"><div><div><h3 class="title">
! 1579: <a name="fetching-distfiles"></a>4.2.2. Fetching distfiles</h3></div></div></div>
! 1580: <p>The first step for building a package is downloading the
! 1581: distfiles (i.e. the unmodified source). If they have not yet been
! 1582: downloaded, pkgsrc will fetch them automatically.</p>
! 1583: <p>You can overwrite some of the major distribution sites to fit to sites
! 1584: that are close to your own. Have a look at
! 1585: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code> to find some examples
! 1586: — in particular, look for the <code class="varname">MASTER_SORT</code>,
! 1587: <code class="varname">MASTER_SORT_REGEX</code> and
! 1588: <code class="varname">INET_COUNTRY</code> definitions. This may save some of your
! 1589: bandwidth and time.</p>
! 1590: <p>You can change these settings either in your shell's environment, or,
! 1591: if you want to keep the settings, by editing the
! 1592: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> file,
! 1593: and adding the definitions there.</p>
! 1594: <p>If you don't have a permanent Internet connection and you want to know
! 1595: which files to download, <span><strong class="command">make fetch-list</strong></span> will tell you
! 1596: what you'll need. Put these distfiles into
! 1597: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/distfiles</code>.</p>
! 1598: </div>
! 1599: <div class="sect2" lang="en">
! 1600: <div class="titlepage"><div><div><h3 class="title">
! 1601: <a name="how-to-build-and-install"></a>4.2.3. How to build and install</h3></div></div></div>
! 1602: <p>Assuming that the distfile has been fetched (see previous section), become
! 1603: root and change into the relevant directory and run
! 1604: <span><strong class="command">make</strong></span>.</p>
! 1605: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 1606: <h3 class="title">Note</h3>
! 1607: <p>If using bootstrap or pkgsrc on a non-NetBSD system,
! 1608: use the pkgsrc <span><strong class="command">bmake</strong></span> command instead of
! 1609: “<span class="quote">make</span>” in the examples in this guide.</p>
! 1610: </div>
! 1611: <p>For example, type </p>
! 1612: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd misc/figlet</code></strong>
! 1613: <code class="prompt">%</code> <strong class="userinput"><code>make</code></strong></pre>
! 1614: <p>at the shell prompt to build the various components of the
! 1615: package, and</p>
! 1616: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong></pre>
! 1617: <p>to install the various components into the correct places
! 1618: on your system. Installing the package on your system requires
! 1619: you to be root. However, pkgsrc has a
! 1620: <span class="emphasis"><em>just-in-time-su</em></span> feature, which allows you
! 1621: to only become root for the actual installation step</p>
! 1622: <p>Taking the figlet utility as an example, we can install it on our
! 1623: system by building as shown in <a href="#logs" title="Appendix B. Build logs">Appendix B, <i>Build logs</i></a>.</p>
! 1624: <p>The program is installed under the default root of the packages tree -
! 1625: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>. Should this not conform to your tastes,
! 1626: set the <code class="varname">LOCALBASE</code>
! 1627: variable in your environment, and it will use that value as the root of
! 1628: your packages tree. So, to use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/local</code>, set
! 1629: <code class="varname">LOCALBASE=/usr/local</code> in your environment. Please note
! 1630: that you should use a directory which is
! 1631: dedicated to packages and not shared with other programs (i.e., do not try
! 1632: and use <code class="varname">LOCALBASE=/usr</code>). Also, you should not try to
! 1633: add any of your own files or directories (such as <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">src/</code>,
! 1634: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">obj/</code>, or <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/</code>) below the
! 1635: <code class="varname">LOCALBASE</code> tree. This is to prevent possible conflicts
! 1636: between programs and other files installed by the package system and
! 1637: whatever else may have been installed there.</p>
! 1638: <p>Some packages look in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to alter some
! 1639: configuration options at build time. Have a look at
! 1640: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code> to
! 1641: get an overview of what will be set there by default. Environment
! 1642: variables such as <code class="varname">LOCALBASE</code>
! 1643: can be set in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to
! 1644: save having to remember to set them each time you want to use pkgsrc.</p>
! 1645: <p>Occasionally, people want to “<span class="quote">look under the covers</span>” to see
! 1646: what is going on when a package is building or being installed. This may be
! 1647: for debugging purposes, or out of simple curiosity. A number of utility
! 1648: values have been added to help with this.</p>
! 1649: <div class="orderedlist"><ol type="1">
! 1650: <li>
! 1651: <p>If you invoke the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> command with <code class="varname">PKG_DEBUG_LEVEL=2</code>,
! 1652: then a huge amount of information will be displayed. For example,</p>
! 1653: <pre class="screen"><strong class="userinput"><code>make patch PKG_DEBUG_LEVEL=2</code></strong></pre>
! 1654: <p>will show all the commands that are invoked, up to and including the
! 1655: “<span class="quote">patch</span>” stage.</p>
! 1656: </li>
! 1657: <li>
! 1658: <p>If you want to know the value of a certain <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> definition, then
! 1659: the <code class="varname">VARNAME</code> definition should be used, in conjunction
! 1660: with the show-var target. e.g. to show the expansion of the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable
! 1661: <code class="varname">LOCALBASE</code>:</p>
! 1662: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>make show-var VARNAME=LOCALBASE</code></strong>
! 1663: /usr/pkg
! 1664: <code class="prompt">%</code>
! 1665: </pre>
! 1666: </li>
! 1667: </ol></div>
! 1668: <p>If you want to install a binary package that you've either
! 1669: created yourself (see next section), that you put into pkgsrc/packages manually or
! 1670: that is located on a remote FTP server, you can use the "bin-install"
! 1671: target. This target will install a binary package - if available - via
! 1672: <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>, else do a <span><strong class="command">make package</strong></span>.
! 1673: The list of remote
! 1674: FTP sites searched is kept in the variable
! 1675: <code class="varname">BINPKG_SITES</code>, which defaults to
! 1676: ftp.NetBSD.org. Any flags that should be added to <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> can be put
! 1677: into <code class="varname">BIN_INSTALL_FLAGS</code>.
! 1678: See <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code> for more details.</p>
! 1679: <p>A final word of warning: If you set up a system that has a non-standard
! 1680: setting for <code class="varname">LOCALBASE</code>, be sure to set that
! 1681: before any packages are installed, as you can not use several directories
! 1682: for the same purpose. Doing so will result in pkgsrc not being able to
! 1683: properly detect your installed packages, and fail miserably. Note also that
! 1684: precompiled binary packages are usually built with the default
! 1685: <code class="varname">LOCALBASE</code> of
! 1686: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>, and that you should <span class="emphasis"><em>not</em></span>
! 1687: install any if you use a non-standard <code class="varname">LOCALBASE</code>.</p>
! 1688: </div>
! 1689: <div class="sect2" lang="en">
! 1690: <div class="titlepage"><div><div><h3 class="title">
! 1691: <a name="selecting-the-compiler"></a>4.2.4. Selecting the compiler</h3></div></div></div>
! 1692: <p>By default, pkgsrc will use GCC to build packages. This may be
! 1693: overridden by setting the following variables in /etc/mk.conf:
! 1694: </p>
! 1695: <div class="variablelist"><dl>
! 1696: <dt><span class="term"><code class="varname">PKGSRC_COMPILER</code>:</span></dt>
! 1697: <dd>
! 1698: <p> This is a list of values specifying the chain of
! 1699: compilers to invoke when building packages. Valid values
! 1700: are: </p>
! 1701: <div class="itemizedlist"><ul type="disc">
! 1702: <li><p><code class="varname">distcc</code>:
! 1703: distributed C/C++ (chainable)</p></li>
! 1704: <li><p><code class="varname">ccache</code>:
! 1705: compiler cache (chainable)</p></li>
! 1706: <li><p><code class="varname">gcc</code>:
! 1707: GNU C/C++ Compiler</p></li>
! 1708: <li><p><code class="varname">mipspro</code>:
! 1709: Silicon Graphics, Inc. MIPSpro (n32/n64)</p></li>
! 1710: <li><p><code class="varname">mipspro</code>:
! 1711: Silicon Graphics, Inc. MIPSpro (o32)</p></li>
! 1712: <li><p><code class="varname">sunpro</code>:
! 1713: Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</p></li>
! 1714: </ul></div>
! 1715: <p> The default is
! 1716: “<span class="quote"><code class="varname">gcc</code></span>”. You can use
! 1717: <code class="varname">ccache</code> and/or
! 1718: <code class="varname">distcc</code> with an appropriate
! 1719: <code class="varname">PKGSRC_COMPILER</code> setting,
! 1720: e.g. “<span class="quote"><code class="varname">ccache gcc</code></span>”. This
! 1721: variable should always be
! 1722: terminated with a value for a real compiler. </p>
! 1723: </dd>
! 1724: <dt><span class="term"><code class="varname">GCC_REQD</code>:</span></dt>
! 1725: <dd><p> This specifies the minimum version of GCC to use
! 1726: when building packages. If the system GCC doesn't
! 1727: satisfy this requirement, then pkgsrc will build and
! 1728: install one of the GCC packages to use instead. </p></dd>
! 1729: </dl></div>
! 1730: </div>
! 1731: </div>
! 1732: </div>
! 1733: <div class="chapter" lang="en">
! 1734: <div class="titlepage"><div><div><h2 class="title">
! 1735: <a name="configuring"></a>Chapter 5. Configuring pkgsrc</h2></div></div></div>
! 1736: <div class="toc">
! 1737: <p><b>Table of Contents</b></p>
! 1738: <dl>
! 1739: <dt><span class="sect1"><a href="#general-configuration">5.1. General configuration</a></span></dt>
! 1740: <dt><span class="sect1"><a href="#variables-affecting-build">5.2. Variables affecting the build process</a></span></dt>
! 1741: <dt><span class="sect1"><a href="#developer-advanced-settings">5.3. Developer/advanced settings</a></span></dt>
! 1742: <dt><span class="sect1"><a href="#selecting-build-options">5.4. Selecting Build Options</a></span></dt>
! 1743: </dl>
! 1744: </div>
! 1745: <div class="sect1" lang="en">
! 1746: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1747: <a name="general-configuration"></a>5.1. General configuration</h2></div></div></div>
! 1748: <p>In this section, you can find some variables that apply to all
! 1749: pkgsrc packages. The preferred method of setting these variables
! 1750: is by setting them in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>.
! 1751: </p>
! 1752: <div class="itemizedlist"><ul type="disc">
! 1753: <li><p><code class="varname">LOCALBASE</code>: Where
! 1754: packages will be installed. The default is
! 1755: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>. Do not mix binary packages
! 1756: with different <code class="varname">LOCALBASE</code>s!</p></li>
! 1757: <li><p><code class="varname">CROSSBASE</code>: Where
! 1758: “<span class="quote">cross</span>” category packages will be
! 1759: installed. The default is
! 1760: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${LOCALBASE}/cross</code>.</p></li>
! 1761: <li><p><code class="varname">X11BASE</code>: Where
! 1762: X11 is installed on the system. The default is
! 1763: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/X11R6</code>.</p></li>
! 1764: <li><p><code class="varname">DISTDIR</code>: Where to store the
! 1765: downloaded copies of the original source distributions used
! 1766: for building pkgsrc packages. The default is
! 1767: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKGSRCDIR}/distfiles</code>.</p></li>
! 1768: <li><p><code class="varname">MASTER_SITE_OVERRIDE</code>:
! 1769: If set, override the packages'
! 1770: <code class="varname">MASTER_SITES</code> with this value.</p></li>
! 1771: <li><p><code class="varname">MASTER_SITE_BACKUP</code>:
! 1772: Backup location(s) for distribution files and patch files
! 1773: if not found locally or in
! 1774: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${MASTER_SITES}</code> or
! 1775: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PATCH_SITES}</code> respectively.
! 1776: The defaults are
! 1777: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</code>
! 1778: and
! 1779: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</code>.</p></li>
! 1780: <li><p><code class="varname">BINPKG_SITES</code>:
! 1781: List of sites carrying binary pkgs.</p></li>
! 1782: </ul></div>
! 1783: <p>
! 1784: </p>
! 1785: </div>
! 1786: <div class="sect1" lang="en">
! 1787: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1788: <a name="variables-affecting-build"></a>5.2. Variables affecting the build process</h2></div></div></div>
! 1789: <p>XXX
! 1790: </p>
! 1791: <div class="itemizedlist"><ul type="disc">
! 1792: <li><p><code class="varname">PACKAGES</code>: The top level
! 1793: directory for the binary packages. The default is
! 1794: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKGSRCDIR}/packages</code>.</p></li>
! 1795: <li><p><code class="varname">WRKOBJDIR</code>:
! 1796: The top level directory where, if defined, the separate
! 1797: working directories will get created, and symbolically
! 1798: linked to from <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKDIR}</code> (see below).
! 1799: This is useful for building packages on several
! 1800: architectures, then <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKGSRCDIR}</code>
! 1801: can be NFS-mounted while <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKOBJDIR}</code>
! 1802: is local to every architecture. (It should be noted that
! 1803: <code class="varname">PKGSRCDIR</code> should not be set by the user
! 1804: — it is an internal definition which refers to the
! 1805: root of the pkgsrc tree. It is possible to have many
! 1806: pkgsrc tree instances.)</p></li>
! 1807: <li><p><code class="varname">LOCALPATCHES</code>:
! 1808: Directory for local patches that aren't part of pkgsrc.
! 1809: See <a href="#components.patches" title="8.3. patches/*">Section 8.3, “patches/*”</a> for more
! 1810: information. <em class="replaceable"><code>rel</code></em> and
! 1811: <em class="replaceable"><code>arch</code></em> are replaced with OS
! 1812: release (“<span class="quote">2.0</span>”, etc.) and architecture
! 1813: (“<span class="quote">mipsel</span>”, etc.).</p></li>
! 1814: <li><p><code class="varname">PKGMAKECONF</code>: Location of
! 1815: the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf</code> file used by a package's
! 1816: BSD-style Makefile. If this is not set,
! 1817: <code class="varname">MAKECONF</code> is set to
! 1818: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/dev/null</code> to avoid picking up
! 1819: settings used by builds in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/src</code>.</p></li>
! 1820: </ul></div>
! 1821: <p>
! 1822: </p>
! 1823: </div>
! 1824: <div class="sect1" lang="en">
! 1825: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1826: <a name="developer-advanced-settings"></a>5.3. Developer/advanced settings</h2></div></div></div>
! 1827: <p>XXX
! 1828: </p>
! 1829: <div class="itemizedlist"><ul type="disc">
! 1830: <li>
! 1831: <p><code class="varname">PKG_DEVELOPER</code>:
! 1832: Run some sanity checks that package developers want:
! 1833: </p>
! 1834: <div class="itemizedlist"><ul type="circle">
! 1835: <li><p>make sure patches apply with zero fuzz</p></li>
! 1836: <li><p>run check-shlibs to see that all binaries will
! 1837: find their shared libs.</p></li>
! 1838: </ul></div>
! 1839: <p>
! 1840: </p>
! 1841: </li>
! 1842: <li><p><code class="varname">PKG_DEBUG_LEVEL</code>:
! 1843: The level of debugging output which is displayed whilst
! 1844: making and installing the package.
! 1845: The default value for this is 0, which will not display
! 1846: the commands as they are executed (normal, default, quiet
! 1847: operation); the value 1 will display all shell commands
! 1848: before their invocation, and the value 2 will display both
! 1849: the shell commands before their invocation, and their
! 1850: actual execution progress with <span><strong class="command">set -x</strong></span>
! 1851: will be displayed.</p></li>
! 1852: <li><p><code class="varname">ALLOW_VULNERABILITIES.<em class="replaceable"><code>pkgbase</code></em></code>:
! 1853: A space separated list of vulnerability IDs that may be ignored when
! 1854: performing the automated security checks. These IDs are listed in the
! 1855: pkg-vulnerabilities file and are displayed by
! 1856: <span><strong class="command">audit-packages</strong></span> when
! 1857: it finds a vulnerable package.
! 1858: </p></li>
! 1859: <li><p><code class="varname">SKIP_AUDIT_PACKAGES</code>:
! 1860: If this is set to “<span class="quote">yes</span>”, the automated security checks
! 1861: (which use the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html" target="_top"><code xmlns="" class="filename">security/audit-packages</code></a>
! 1862: package) will be <span class="strong"><strong>entirely</strong></span> skipped
! 1863: for <span class="strong"><strong>all</strong></span> packages built. Normally
! 1864: you'll want to use ALLOW_VULNERABILITIES instead of this.
! 1865: </p></li>
! 1866: </ul></div>
! 1867: <p>
! 1868: </p>
! 1869: </div>
! 1870: <div class="sect1" lang="en">
! 1871: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1872: <a name="selecting-build-options"></a>5.4. Selecting Build Options</h2></div></div></div>
! 1873: <p>Some packages have build time options, usually to select between
! 1874: different dependencies, enable optional support for big dependencies
! 1875: or enable experimental features.</p>
! 1876: <p>To see which options, if any, a package supports, and which
! 1877: options are mutually exclusive, run <span><strong class="command">make show-options</strong></span>,
! 1878: for example:</p>
! 1879: <pre class="programlisting">
! 1880: The following options are supported by this package:
! 1881: ssl Enable SSL support.
! 1882: Exactly one of the following gecko options is required:
! 1883: firefox Use firefox as gecko rendering engine.
! 1884: mozilla Use mozilla as gecko rendering engine.
! 1885: At most one of the following database options may be selected:
! 1886: mysql Enable support for MySQL database.
! 1887: pgsql Enable support for PostgreSQL database.
1.1 grant 1888:
1.75 ! rillig 1889: These options are enabled by default: firefox
! 1890: These options are currently enabled: mozilla ssl
1.1 grant 1891: </pre>
1.75 ! rillig 1892: <p>The following variables can be defined in
! 1893: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to select which options to enable
! 1894: for a package: <code class="varname">PKG_DEFAULT_OPTIONS</code>, which can be
! 1895: used to select or disable options for all packages that support them,
! 1896: and <code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code>,
! 1897: which can be used to select or disable options specifically for
! 1898: package <em class="replaceable"><code>pkgbase</code></em>. Options listed in these
! 1899: variables are selected, options preceded by “<span class="quote">-</span>” are
! 1900: disabled. A few examples:</p>
! 1901: <pre class="screen">
! 1902: <code class="prompt">$</code> <span><strong class="command">grep "PKG.*OPTION" /etc/mk.conf</strong></span>
! 1903: PKG_DEFAULT_OPTIONS= -arts -dvdread -esound
! 1904: PKG_OPTIONS.kdebase= debug -sasl
! 1905: PKG_OPTIONS.apache= suexec </pre>
! 1906: <p>The following settings are consulted in the order given, and the
! 1907: last setting that selects or disables an option is used:</p>
! 1908: <div class="orderedlist"><ol type="1">
! 1909: <li><p>the default options as suggested by the package
! 1910: maintainer</p></li>
! 1911: <li><p>the options implied by the settings of legacy
! 1912: variables (see below)</p></li>
! 1913: <li><p><code class="varname">PKG_DEFAULT_OPTIONS</code></p></li>
! 1914: <li><p><code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code></p></li>
! 1915: </ol></div>
! 1916: <p>For groups of mutually exclusive options, the last option
! 1917: selected is used, all others are automatically disabled. If an option
! 1918: of the group is explicitly disabled, the previously selected option,
! 1919: if any, is used. It is an error if no option from a required group of
! 1920: options is selected, and building the package will fail.</p>
! 1921: <p>Before the options framework was introduced, build options were
! 1922: selected by setting a variable (often named
! 1923: <code class="varname">USE_<em class="replaceable"><code>FOO</code></em></code>) in
! 1924: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> for each option. To ease transition
! 1925: to the options framework for the user, these legacy variables are
! 1926: converted to the appropriate options setting
! 1927: (<code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code>)
! 1928: automatically. A warning is issued to prompt the user to
! 1929: update <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to use the options framework
! 1930: directly. Support for the legacy variables will be removed
! 1931: eventually.</p>
! 1932: </div>
! 1933: </div>
! 1934: <div class="chapter" lang="en">
! 1935: <div class="titlepage"><div><div><h2 class="title">
! 1936: <a name="binary"></a>Chapter 6. Creating binary packages</h2></div></div></div>
! 1937: <div class="toc">
! 1938: <p><b>Table of Contents</b></p>
! 1939: <dl>
! 1940: <dt><span class="sect1"><a href="#building-a-single-binary-package">6.1. Building a single binary package</a></span></dt>
! 1941: <dt><span class="sect1"><a href="#settings-for-creationg-of-binary-packages">6.2. Settings for creation of binary packages</a></span></dt>
! 1942: <dt><span class="sect1"><a href="#bulkbuild">6.3. Doing a bulk build of all packages</a></span></dt>
! 1943: <dd><dl>
! 1944: <dt><span class="sect2"><a href="#binary.configuration">6.3.1. Configuration</a></span></dt>
! 1945: <dt><span class="sect2"><a href="#other-environmental-considerations">6.3.2. Other environmental considerations</a></span></dt>
! 1946: <dt><span class="sect2"><a href="#operation">6.3.3. Operation</a></span></dt>
! 1947: <dt><span class="sect2"><a href="#what-it-does">6.3.4. What it does</a></span></dt>
! 1948: <dt><span class="sect2"><a href="#disk-space-requirements">6.3.5. Disk space requirements</a></span></dt>
! 1949: <dt><span class="sect2"><a href="#setting-up-a-sandbox">6.3.6. Setting up a sandbox for chrooted builds</a></span></dt>
! 1950: <dt><span class="sect2"><a href="#building-a-partial-set">6.3.7. Building a partial set of packages</a></span></dt>
! 1951: <dt><span class="sect2"><a href="#bulk-upload">6.3.8. Uploading results of a bulk build</a></span></dt>
! 1952: </dl></dd>
! 1953: <dt><span class="sect1"><a href="#creating-cdroms">6.4. Creating a multiple CD-ROM packages collection</a></span></dt>
! 1954: <dd><dl><dt><span class="sect2"><a href="#cdpack-example">6.4.1. Example of cdpack</a></span></dt></dl></dd>
! 1955: </dl>
! 1956: </div>
! 1957: <div class="sect1" lang="en">
! 1958: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1959: <a name="building-a-single-binary-package"></a>6.1. Building a single binary package</h2></div></div></div>
! 1960: <p>
! 1961: Once you have built and installed a package, you can create a
! 1962: <span class="emphasis"><em>binary package</em></span> which can be installed on
! 1963: another system with <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>. This saves having to build
! 1964: the same package on a group of hosts and wasting CPU time. It
! 1965: also provides a simple means for others to install your package,
! 1966: should you distribute it.
! 1967: </p>
! 1968: <p>
! 1969: To create a binary package, change into the appropriate
! 1970: directory in pkgsrc, and run <span><strong class="command">make
! 1971: package</strong></span>:
! 1972: </p>
! 1973: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd misc/figlet</code></strong>
! 1974: <code class="prompt">#</code> <strong class="userinput"><code>make package</code></strong></pre>
! 1975: <p>
! 1976: This will build and install your package (if not already done),
! 1977: and then build a binary package from what was installed. You can
! 1978: then use the <span><strong class="command">pkg_*</strong></span> tools to manipulate
! 1979: it. Binary packages are created by default in
! 1980: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/packages</code>, in the form of a
! 1981: gzipped tar file. See <a href="#logs.package" title="B.2. Packaging figlet">Section B.2, “Packaging figlet”</a> for a
! 1982: continuation of the above <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/misc/figlet/README.html" target="_top"><code xmlns="" class="filename">misc/figlet</code></a> example.</p>
! 1983: <p>
! 1984: See <a href="#submit" title="Chapter 18. Submitting and Committing">Chapter 18, <i>Submitting and Committing</i></a> for information on how to submit
! 1985: such a binary package.</p>
! 1986: </div>
! 1987: <div class="sect1" lang="en">
! 1988: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1989: <a name="settings-for-creationg-of-binary-packages"></a>6.2. Settings for creation of binary packages</h2></div></div></div>
! 1990: <p>See <a href="#build.helpful-targets" title="14.16. Other helpful targets">Section 14.16, “Other helpful targets”</a>.</p>
! 1991: </div>
! 1992: <div class="sect1" lang="en">
! 1993: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 1994: <a name="bulkbuild"></a>6.3. Doing a bulk build of all packages</h2></div></div></div>
! 1995: <p>If you want to get a full set of precompiled binary
! 1996: packages, this section describes how to get them. Beware that
! 1997: the bulk build will remove all currently installed packages from
! 1998: your system!</p>
! 1999: <p>Having an FTP server configured either on the
! 2000: machine doing the bulk builds or on a nearby NFS server can help
! 2001: to make the packages available to other machines that can then
! 2002: save time by installing only the binary packages. See <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ftpd+8+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ftpd</span>(8)</span></a> for
! 2003: more information. If you use a remote NFS server's storage, be
! 2004: sure to not actually compile on NFS storage, as this slows
! 2005: things down a lot.</p>
! 2006: <div class="sect2" lang="en">
! 2007: <div class="titlepage"><div><div><h3 class="title">
! 2008: <a name="binary.configuration"></a>6.3.1. Configuration</h3></div></div></div>
! 2009: <div class="sect3" lang="en">
! 2010: <div class="titlepage"><div><div><h4 class="title">
! 2011: <a name="binary.bulk.build.conf"></a>6.3.1.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf</code></h4></div></div></div>
! 2012: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf</code> file is the main
! 2013: configuration file for bulk builds. You can configure how your
! 2014: copy of pkgsrc is kept up to date, how the distfiles are
! 2015: downloaded, how the packages are built and how the report is
! 2016: generated. You can find an annotated example file in
! 2017: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bulk/build.conf-example</code>. To use
! 2018: it, copy <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf-example</code> to
! 2019: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf</code> and edit it, following the
! 2020: comments in that file.</p>
! 2021: </div>
! 2022: <div class="sect3" lang="en">
! 2023: <div class="titlepage"><div><div><h4 class="title">
! 2024: <a name="binary.mk.conf"></a>6.3.1.2. /etc/mk.conf</h4></div></div></div>
! 2025: <p>You may want to set variables in
! 2026: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>.
! 2027: Look at <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code> for
! 2028: details of the default settings. You will want to ensure that
! 2029: <code class="varname">ACCEPTABLE_LICENSES</code> meet your local policy.
! 2030: As used in this example, <code class="varname">_ACCEPTABLE=yes</code>
! 2031: accepts <span class="emphasis"><em>all</em></span> licenses.</p>
! 2032: <pre class="programlisting">
! 2033: PACKAGES?= ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
! 2034: WRKOBJDIR?= /usr/tmp/pkgsrc # build here instead of in pkgsrc
! 2035: BSDSRCDIR= /usr/src
! 2036: BSDXSRCDIR= /usr/xsrc # for x11/xservers
! 2037: OBJHOSTNAME?= yes # use work.`hostname`
! 2038: FAILOVER_FETCH= yes # insist on the correct checksum
! 2039: PKG_DEVELOPER?= yes
! 2040: _ACCEPTABLE= yes
1.1 grant 2041: </pre>
1.75 ! rillig 2042: <p>Some options that are especially useful for bulk builds
! 2043: can be found at the top lines of the file
! 2044: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bulk/bsd.bulk-pkg.mk</code>. The most useful
! 2045: options of these are briefly described here.</p>
! 2046: <div class="itemizedlist"><ul type="disc">
! 2047: <li><p>If you are on a slow machine, you may want to
! 2048: set <code class="varname">USE_BULK_BROKEN_CHECK</code> to
! 2049: “<span class="quote">no</span>”.</p></li>
! 2050: <li><p>If you are doing bulk builds from a read-only
! 2051: copy of pkgsrc, you have to set <code class="varname">BULKFILESDIR</code>
! 2052: to the directory where all log files are created. Otherwise the
! 2053: log files are created in the pkgsrc directory.</p></li>
! 2054: <li><p>Another important variable is
! 2055: <code class="varname">BULK_PREREQ</code>, which is a list of packages that
! 2056: should be always available while building other
! 2057: packages.</p></li>
! 2058: </ul></div>
! 2059: <p>Some other options are scattered in the pkgsrc
! 2060: infrastructure:</p>
! 2061: <div class="itemizedlist"><ul type="disc">
! 2062: <li><p><code class="varname">ALLOW_VULNERABLE_PACKAGES</code>
! 2063: should be set to <code class="literal">yes</code>. The purpose of the bulk
! 2064: builds is creating binary packages, no matter if they are
! 2065: vulnerable or not. When uploading the packages to a public
! 2066: server, the vulnerable packages will be put into a directory of
! 2067: their own. Leaving this variable unset would prevent the bulk
! 2068: build system from even trying to build them, so possible
! 2069: building errors would not show up.</p></li>
! 2070: <li><p><code class="varname">CHECK_FILES</code>
! 2071: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bsd.pkg.check.mk</code>) can be set to
! 2072: “<span class="quote">yes</span>” to check that the installed set of files
! 2073: matches the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>.</p></li>
! 2074: <li><p><code class="varname">CHECK_INTERPRETER</code>
! 2075: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bsd.pkg.check.mk</code>) can be set to
! 2076: “<span class="quote">yes</span>” to check that the installed
! 2077: “<span class="quote">#!</span>”-scripts will find their
! 2078: interpreter.</p></li>
! 2079: </ul></div>
! 2080: </div>
! 2081: <div class="sect3" lang="en">
! 2082: <div class="titlepage"><div><div><h4 class="title">
! 2083: <a name="pre-build.local"></a>6.3.1.3. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pre-build.local</code></h4></div></div></div>
! 2084: <p>It is possible to configure the bulk build to perform
! 2085: certain site-specific tasks at the end of the pre-build
! 2086: stage. If the file
! 2087: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pre-build.local</code> exists in
! 2088: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/mk/bulk</code>, it will be executed
! 2089: (as a <a href="http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">sh</span>(1)</span></a> script) at the end of the usual pre-build
! 2090: stage. An example use of
! 2091: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pre-build.local</code> is to have the line:</p>
! 2092: <pre class="screen">echo "I do not have enough disk space to build this pig." \
! 2093: > misc/openoffice/$BROKENF</pre>
! 2094: <p>to prevent the system from trying to build a particular package
! 2095: which requires nearly 3 GB of disk space.</p>
! 2096: </div>
! 2097: </div>
! 2098: <div class="sect2" lang="en">
! 2099: <div class="titlepage"><div><div><h3 class="title">
! 2100: <a name="other-environmental-considerations"></a>6.3.2. Other environmental considerations</h3></div></div></div>
! 2101: <p>As <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> will be completely
! 2102: deleted at the start of bulk builds, make sure your login
! 2103: shell is placed somewhere else. Either drop it into
! 2104: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/local/bin</code> (and adjust your login
! 2105: shell in the passwd file), or (re-)install it via
! 2106: <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> from <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/rc.local</code>, so
! 2107: you can login after a reboot (remember that your current
! 2108: process won't die if the package is removed, you just can't
! 2109: start any new instances of the shell any more). Also, if you
! 2110: use NetBSD earlier than 1.5, or you still want to use the pkgsrc
! 2111: version of ssh for some reason, be sure to install ssh before
! 2112: starting it from <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">rc.local</code>:</p>
! 2113: <pre class="programlisting">
! 2114: ( cd /usr/pkgsrc/security/ssh ; make bulk-install )
! 2115: if [ -f /usr/pkg/etc/rc.d/sshd ]; then
! 2116: /usr/pkg/etc/rc.d/sshd
! 2117: fi
1.1 grant 2118: </pre>
1.75 ! rillig 2119: <p>Not doing so will result in you being not able to log in
! 2120: via ssh after the bulk build is finished or if the machine
! 2121: gets rebooted or crashes. You have been warned! :)</p>
! 2122: </div>
! 2123: <div class="sect2" lang="en">
! 2124: <div class="titlepage"><div><div><h3 class="title">
! 2125: <a name="operation"></a>6.3.3. Operation</h3></div></div></div>
! 2126: <p>Make sure you don't need any of the packages still
! 2127: installed.
! 2128: </p>
! 2129: <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
! 2130: <h3 class="title">Warning</h3>
! 2131: <p>During the bulk build, <span class="emphasis"><em>all packages will be
! 2132: removed!</em></span></p>
! 2133: </div>
! 2134: <p>Be sure to remove all other things that might
! 2135: interfere with builds, like some libs installed in
! 2136: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/local</code>, etc. then become root and type:</p>
! 2137: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
! 2138: <code class="prompt">#</code> <strong class="userinput"><code>sh mk/bulk/build</code></strong></pre>
! 2139: <p>If for some reason your last build didn't complete (power
! 2140: failure, system panic, ...), you can continue it by
! 2141: running:</p>
! 2142: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>sh mk/bulk/build restart</code></strong></pre>
! 2143: <p>
! 2144: At the end of the bulk build, you will get a summary via mail,
! 2145: and find build logs in the directory specified by
! 2146: <code class="varname">FTP</code> in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf</code>
! 2147: file.
! 2148: </p>
! 2149: </div>
! 2150: <div class="sect2" lang="en">
! 2151: <div class="titlepage"><div><div><h3 class="title">
! 2152: <a name="what-it-does"></a>6.3.4. What it does</h3></div></div></div>
! 2153: <p>The bulk builds consist of three steps:</p>
! 2154: <div class="variablelist"><dl>
! 2155: <dt><span class="term">1. pre-build</span></dt>
! 2156: <dd><p>
! 2157: The script updates your pkgsrc tree via (anon)cvs, then
! 2158: cleans out any broken distfiles, and removes all
! 2159: packages installed.</p></dd>
! 2160: <dt><span class="term">2. the bulk build</span></dt>
! 2161: <dd><p>
! 2162: This is basically “<span class="quote">make bulk-package</span>” with
! 2163: an optimised order in which packages will be
! 2164: built. Packages that don't require other packages will
! 2165: be built first, and packages with many dependencies will
! 2166: be built later.
! 2167: </p></dd>
! 2168: <dt><span class="term">3. post-build</span></dt>
! 2169: <dd><p>
! 2170: Generates a report that's placed in the directory
! 2171: specified in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">build.conf</code> file
! 2172: named <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">broken.html</code>, a short version
! 2173: of that report will also be mailed to the build's
! 2174: admin.</p></dd>
! 2175: </dl></div>
! 2176: <p>
! 2177: During the build, a list of broken packages will be compiled
! 2178: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/.broken</code> (or
! 2179: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.../.broken.${MACHINE}</code> if
! 2180: <code class="varname">OBJMACHINE</code> is set), individual build logs
! 2181: of broken builds can be found in the package's
! 2182: directory. These files are used by the bulk-targets to mark
! 2183: broken builds to not waste time trying to rebuild them, and
! 2184: they can be used to debug these broken package builds
! 2185: later.
! 2186: </p>
! 2187: </div>
! 2188: <div class="sect2" lang="en">
! 2189: <div class="titlepage"><div><div><h3 class="title">
! 2190: <a name="disk-space-requirements"></a>6.3.5. Disk space requirements</h3></div></div></div>
! 2191: <p>Currently, roughly the following requirements are valid for
! 2192: NetBSD 2.0/i386:</p>
! 2193: <div class="itemizedlist"><ul type="disc">
! 2194: <li><p>
! 2195: 10 GB - distfiles (NFS ok)
! 2196: </p></li>
! 2197: <li><p>
! 2198: 8 GB - full set of all binaries (NFS ok)
! 2199: </p></li>
! 2200: <li><p>
! 2201: 5 GB - temp space for compiling (local disk recommended)
! 2202: </p></li>
! 2203: </ul></div>
! 2204: <p>
! 2205: Note that all pkgs will be de-installed as soon as they are
! 2206: turned into a binary package, and that sources are removed,
! 2207: so there is no excessively huge demand to disk
! 2208: space. Afterwards, if the package is needed again, it will
! 2209: be installed via <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> instead of building again, so
! 2210: there are no cycles wasted by recompiling.
! 2211: </p>
! 2212: </div>
! 2213: <div class="sect2" lang="en">
! 2214: <div class="titlepage"><div><div><h3 class="title">
! 2215: <a name="setting-up-a-sandbox"></a>6.3.6. Setting up a sandbox for chrooted builds</h3></div></div></div>
! 2216: <p>
! 2217: If you don't want all the packages nuked from a machine
! 2218: (rendering it useless for anything but pkg compiling), there
! 2219: is the possibility of doing the package bulk build inside a
! 2220: chroot environment.
! 2221: </p>
! 2222: <p>
! 2223: The first step is to set up a chroot sandbox,
! 2224: e.g. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/sandbox</code>. This can be done by
! 2225: using null mounts, or manually.
! 2226: </p>
! 2227: <p>
! 2228: There is a shell script called
! 2229: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bulk/mksandbox</code> which will set
! 2230: up the sandbox environment using null mounts. It will also
! 2231: create a script called <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">sandbox</code> in the
! 2232: root of the sandbox environment, which will allow the null
! 2233: mounts to be activated using the <span><strong class="command">sandbox
! 2234: mount</strong></span> command and deactivated using the
! 2235: <span><strong class="command">sandbox umount</strong></span> command.
! 2236: </p>
! 2237: <p>
! 2238: To set up a sandbox environment by hand, after extracting all
! 2239: the sets from a NetBSD installation or doing a <span><strong class="command">make
! 2240: distribution DESTDIR=/usr/sandbox</strong></span> in
! 2241: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/src/etc</code>, be sure the following items
! 2242: are present and properly configured:
! 2243: </p>
! 2244: <div class="procedure"><ol type="1">
! 2245: <li>
! 2246: <p>Kernel</p>
! 2247: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cp /netbsd /usr/sandbox</code></strong></pre>
! 2248: </li>
! 2249: <li>
! 2250: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/dev/*</code></p>
! 2251: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sandbox/dev ; sh MAKEDEV all</code></strong></pre>
! 2252: </li>
! 2253: <li>
! 2254: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/resolv.conf</code> (for <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html" target="_top"><code xmlns="" class="filename">security/smtpd</code></a> and mail):</p>
! 2255: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cp /etc/resolv.conf /usr/sandbox/etc</code></strong></pre>
! 2256: </li>
! 2257: <li>
! 2258: <p>Working(!) mail config (hostname, sendmail.cf):</p>
! 2259: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail</code></strong></pre>
! 2260: </li>
! 2261: <li>
! 2262: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/localtime</code> (for <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html" target="_top"><code xmlns="" class="filename">security/smtpd</code></a>):</p>
! 2263: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ln -sf /usr/share/zoneinfo/UTC /usr/sandbox/etc/localtime</code></strong></pre>
! 2264: </li>
! 2265: <li>
! 2266: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/src</code> (system sources,
! 2267: e. g. for <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/aperture/README.html" target="_top"><code xmlns="" class="filename">sysutils/aperture</code></a>):</p>
! 2268: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ln -s ../disk1/cvs .</code></strong>
! 2269: <code class="prompt">#</code> <strong class="userinput"><code>ln -s cvs/src-2.0 src</code></strong></pre>
! 2270: </li>
! 2271: <li>
! 2272: <p>Create <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/var/db/pkg</code> (not part of default install):</p>
! 2273: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mkdir /usr/sandbox/var/db/pkg</code></strong></pre>
! 2274: </li>
! 2275: <li>
! 2276: <p>Create <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code> (not part of default install):</p>
! 2277: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mkdir /usr/sandbox/usr/pkg</code></strong></pre>
! 2278: </li>
! 2279: <li>
! 2280: <p>Checkout pkgsrc via cvs into
! 2281: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/sandbox/usr/pkgsrc</code>:</p>
! 2282: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sandbox/usr</code></strong>
! 2283: <code class="prompt">#</code> <strong class="userinput"><code>cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -d -P pkgsrc</code></strong></pre>
! 2284: <p>Do not mount/link this to the copy of your pkgsrc tree
! 2285: you do development in, as this will likely cause problems!
! 2286: </p>
! 2287: </li>
! 2288: <li><p>Make
! 2289: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/sandbox/usr/pkgsrc/packages</code> and
! 2290: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.../distfiles</code> point somewhere
! 2291: appropriate. NFS- and/or nullfs-mounts may come in handy!
! 2292: </p></li>
! 2293: <li><p>Edit <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>, see <a href="#binary.mk.conf" title="6.3.1.2. /etc/mk.conf">Section 6.3.1.2, “/etc/mk.conf”</a>.</p></li>
! 2294: <li><p>Adjust <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bulk/build.conf</code> to suit your needs.</p></li>
! 2295: </ol></div>
! 2296: <p>When the chroot sandbox is set up, you can start
! 2297: the build with the following steps:</p>
! 2298: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
! 2299: <code class="prompt">#</code> <strong class="userinput"><code>sh mk/bulk/do-sandbox-build</code></strong></pre>
! 2300: <p>
! 2301: This will just jump inside the sandbox and start building. At
! 2302: the end of the build, mail will be sent with the results of
! 2303: the build. Created binary pkgs will be in
! 2304: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/sandbox/usr/pkgsrc/packages</code>
! 2305: (wherever that points/mounts to/from).</p>
! 2306: </div>
! 2307: <div class="sect2" lang="en">
! 2308: <div class="titlepage"><div><div><h3 class="title">
! 2309: <a name="building-a-partial-set"></a>6.3.7. Building a partial set of packages</h3></div></div></div>
! 2310: <p> In addition to building a complete set of all packages in
! 2311: pkgsrc, the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bulk/build</code> script
! 2312: may be used to build a subset of the packages contained in
! 2313: pkgsrc. By setting <code class="varname">SPECIFIC_PKGS</code>
! 2314: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>, the variables</p>
! 2315: <div class="itemizedlist"><ul type="disc">
! 2316: <li><p>SITE_SPECIFIC_PKGS</p></li>
! 2317: <li><p>HOST_SPECIFIC_PKGS</p></li>
! 2318: <li><p>GROUP_SPECIFIC_PKGS</p></li>
! 2319: <li><p>USER_SPECIFIC_PKGS</p></li>
! 2320: </ul></div>
! 2321: <p> will define the set of packages which should be built.
! 2322: The bulk build code will also include any packages which are
! 2323: needed as dependencies for the explicitly listed packages.
! 2324: </p>
! 2325: <p> One use of this is to do a bulk build with
! 2326: <code class="varname">SPECIFIC_PKGS</code> in a chroot sandbox
! 2327: periodically to have a complete set of the binary packages
! 2328: needed for your site available without the overhead of
! 2329: building extra packages that are not needed. </p>
! 2330: </div>
! 2331: <div class="sect2" lang="en">
! 2332: <div class="titlepage"><div><div><h3 class="title">
! 2333: <a name="bulk-upload"></a>6.3.8. Uploading results of a bulk build</h3></div></div></div>
! 2334: <p>
! 2335: This section describes how pkgsrc developers can upload binary
! 2336: pkgs built by bulk builds to ftp.NetBSD.org.
! 2337: </p>
! 2338: <p>
! 2339: If you would like to automatically create checksum files for the
! 2340: binary packages you intend to upload, remember to set
! 2341: <code class="varname">MKSUMS=yes</code> in your
! 2342: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bulk/build.conf</code>.
! 2343: </p>
! 2344: <p>
! 2345: If you would like to PGP sign the checksum files (highly
! 2346: recommended!), remember to set
! 2347: <code class="varname">SIGN_AS=username@NetBSD.org</code> in your
! 2348: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bulk/build.conf</code>. This will prompt you for
! 2349: your GPG password to sign the files before uploading everything.
! 2350: </p>
! 2351: <p>
! 2352: Then, make sure that you have <code class="varname">RSYNC_DST</code>
! 2353: set properly in your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bulk/build.conf</code>
! 2354: file, i.e. adjust it to something like one of the following:
! 2355: </p>
! 2356: <pre class="screen">RSYNC_DST=ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload </pre>
! 2357: <p>Please use appropriate values for "pkgsrc-200xQy",
! 2358: "NetBSD-a.b.c" and "arch" here. If your login on ftp.NetBSD.org
! 2359: is different from your local login, write your login directly
! 2360: into the variable, e.g. my local account is "feyrer", but for my
! 2361: login "hubertf", I use:</p>
! 2362: <pre class="screen">RSYNC_DST=hubertf@ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload </pre>
! 2363: <p>
! 2364: A separate <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">upload</code> directory is used
! 2365: here to allow "closing" the directory during upload. To do
! 2366: so, run the following command on ftp.NetBSD.org next:
! 2367: </p>
! 2368: <pre class="screen">nbftp% <strong class="userinput"><code>mkdir -p -m 750 /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload</code></strong></pre>
! 2369: <p>
! 2370: Please note that <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/pub/NetBSD/packages</code> is
! 2371: only appropriate for packages for the NetBSD operating
! 2372: system. Binary packages for other operating systems should go
! 2373: into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/pub/pkgsrc</code>.
! 2374: </p>
! 2375: <p>
! 2376: Before uploading the binary pkgs, ssh authentication needs to
! 2377: be set up. This example shows how to set up temporary keys
! 2378: for the root account <span class="emphasis"><em>inside the sandbox</em></span>
! 2379: (assuming that no keys should be present there usually):
! 2380: </p>
! 2381: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>chroot /usr/sandbox</code></strong>
! 2382: chroot-<code class="prompt">#</code> <strong class="userinput"><code>rm $HOME/.ssh/id-dsa*</code></strong>
! 2383: chroot-<code class="prompt">#</code> <strong class="userinput"><code>ssh-keygen -t dsa</code></strong>
! 2384: chroot-<code class="prompt">#</code> <strong class="userinput"><code>cat $HOME/.ssh/id-dsa.pub</code></strong> </pre>
! 2385: <p>
! 2386: Now take the output of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">id-dsa.pub</code> and
! 2387: append it to your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">~/.ssh/authorized_keys</code>
! 2388: file on ftp.NetBSD.org. You can remove the key after the
! 2389: upload is done!
! 2390: </p>
! 2391: <p>
! 2392: Next, test if your ssh connection really works:
! 2393: </p>
! 2394: <pre class="screen">chroot-<code class="prompt">#</code> <strong class="userinput"><code>ssh ftp.NetBSD.org date</code></strong> </pre>
! 2395: <p>
! 2396: Use "-l yourNetBSDlogin" here as appropriate!
! 2397: </p>
! 2398: <p>
! 2399: Now after all this works, you can exit the sandbox and start
! 2400: the upload:
! 2401: </p>
! 2402: <pre class="screen">chroot-<code class="prompt">#</code> <strong class="userinput"><code>exit</code></strong>
! 2403: <code class="prompt">#</code> <strong class="userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
! 2404: <code class="prompt">#</code> <strong class="userinput"><code>sh mk/bulk/do-sandbox-upload</code></strong> </pre>
! 2405: <p>
! 2406: The upload process may take quite some time. Use <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ls+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ls</span>(1)</span></a> or
! 2407: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?du+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">du</span>(1)</span></a> on the FTP server to monitor progress of the
! 2408: upload. The upload script will take care of not uploading
! 2409: restricted packages and putting vulnerable packages into the
! 2410: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">vulnerable</code> subdirectory.
! 2411: </p>
! 2412: <p>
! 2413: After the upload has ended, first thing is to revoke ssh access:
! 2414: </p>
! 2415: <pre class="screen">nbftp% <strong class="userinput"><code>vi ~/.ssh/authorized_keys</code></strong>
! 2416: Gdd:x! </pre>
! 2417: <p>
! 2418: Use whatever is needed to remove the key you've entered
! 2419: before! Last, move the uploaded packages out of the
! 2420: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">upload</code> directory to have them accessible
! 2421: to everyone:
! 2422: </p>
! 2423: <pre class="screen">nbftp% <strong class="userinput"><code>cd /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch</code></strong>
! 2424: nbftp% <strong class="userinput"><code>mv upload/* .</code></strong>
! 2425: nbftp% <strong class="userinput"><code>rmdir upload</code></strong>
! 2426: nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> </pre>
! 2427: </div>
! 2428: </div>
! 2429: <div class="sect1" lang="en">
! 2430: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2431: <a name="creating-cdroms"></a>6.4. Creating a multiple CD-ROM packages collection</h2></div></div></div>
! 2432: <p>
! 2433: After your pkgsrc bulk-build has completed, you may wish to
! 2434: create a CD-ROM set of the resulting binary packages to assist
! 2435: in installing packages on other machines. The
! 2436: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/cdpack/README.html" target="_top"><code xmlns="" class="filename">pkgtools/cdpack</code></a> package provides
! 2437: a simple tool for creating the ISO 9660 images.
! 2438: <span><strong class="command">cdpack</strong></span> arranges the packages on the CD-ROMs in a
! 2439: way that keeps all the dependencies for a given package on the same
! 2440: CD as that package.
! 2441: </p>
! 2442: <div class="sect2" lang="en">
! 2443: <div class="titlepage"><div><div><h3 class="title">
! 2444: <a name="cdpack-example"></a>6.4.1. Example of cdpack</h3></div></div></div>
! 2445: <p>
! 2446: Complete documentation for cdpack is found in the cdpack(1)
! 2447: man page. The following short example assumes that the binary
! 2448: packages are left in
! 2449: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/packages/All</code> and that
! 2450: sufficient disk space exists in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/u2</code> to
! 2451: hold the ISO 9660 images.</p>
! 2452: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mkdir /u2/images</code></strong>
! 2453: <code class="prompt">#</code> <strong class="userinput"><code>pkg_add /usr/pkgsrc/packages/All/cdpack</code></strong>
! 2454: <code class="prompt">#</code> <strong class="userinput"><code>cdpack /usr/pkgsrc/packages/All /u2/images</code></strong></pre>
! 2455: <p>
! 2456: If you wish to include a common set of files
! 2457: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">COPYRIGHT</code>, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README</code>,
! 2458: etc.) on each CD in the collection, then you need to create a
! 2459: directory which contains these files. e.g.
! 2460: </p>
! 2461: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mkdir /tmp/common</code></strong>
! 2462: <code class="prompt">#</code> <strong class="userinput"><code>echo "This is a README" > /tmp/common/README</code></strong>
! 2463: <code class="prompt">#</code> <strong class="userinput"><code>echo "Another file" > /tmp/common/COPYING</code></strong>
! 2464: <code class="prompt">#</code> <strong class="userinput"><code>mkdir /tmp/common/bin</code></strong>
! 2465: <code class="prompt">#</code> <strong class="userinput"><code>echo "#!/bin/sh" > /tmp/common/bin/myscript</code></strong>
! 2466: <code class="prompt">#</code> <strong class="userinput"><code>echo "echo Hello world" >> /tmp/common/bin/myscript</code></strong>
! 2467: <code class="prompt">#</code> <strong class="userinput"><code>chmod 755 /tmp/common/bin/myscript</code></strong></pre>
! 2468: <p>Now create the images:</p>
! 2469: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images</code></strong></pre>
! 2470: <p>Each image will contain <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README</code>,
! 2471: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">COPYING</code>, and <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bin/myscript</code>
! 2472: in their root directories.</p>
! 2473: </div>
! 2474: </div>
! 2475: </div>
! 2476: <div class="chapter" lang="en">
! 2477: <div class="titlepage"><div><div><h2 class="title">
! 2478: <a name="faq"></a>Chapter 7. Frequently Asked Questions</h2></div></div></div>
! 2479: <div class="toc">
! 2480: <p><b>Table of Contents</b></p>
! 2481: <dl>
! 2482: <dt><span class="sect1"><a href="#mailing-list-pointers">7.1. Are there any mailing lists for pkg-related discussion?</a></span></dt>
! 2483: <dt><span class="sect1"><a href="#pkgviews-docs">7.2. Where's the pkgviews documentation?</a></span></dt>
! 2484: <dt><span class="sect1"><a href="#faq-pkgtools">7.3. Utilities for package management (pkgtools)</a></span></dt>
! 2485: <dt><span class="sect1"><a href="#non-root-pkgsrc">7.4. How to use pkgsrc as non-root</a></span></dt>
! 2486: <dt><span class="sect1"><a href="#resume-transfers">7.5. How to resume transfers when fetching distfiles?</a></span></dt>
! 2487: <dt><span class="sect1"><a href="#XFree86-from-pkgsrc">7.6. How can I install/use XFree86 from pkgsrc?</a></span></dt>
! 2488: <dt><span class="sect1"><a href="#x.org-from-pkgsrc">7.7. How can I install/use X.org from pkgsrc?</a></span></dt>
! 2489: <dt><span class="sect1"><a href="#fetch-behind-firewall">7.8. How to fetch files from behind a firewall</a></span></dt>
! 2490: <dt><span class="sect1"><a href="#passive-ftp">7.9. How do I tell <span><strong class="command">make fetch</strong></span> to do passive FTP?</a></span></dt>
! 2491: <dt><span class="sect1"><a href="#fetching-all-distfiles">7.10. How to fetch all distfiles at once</a></span></dt>
! 2492: <dt><span class="sect1"><a href="#tmac.andoc-missing">7.11. What does “<span class="quote">Don't know how to make
! 2493: /usr/share/tmac/tmac.andoc</span>” mean?</a></span></dt>
! 2494: <dt><span class="sect1"><a href="#bsd.own.mk-missing">7.12. What does “<span class="quote">Could not find bsd.own.mk</span>” mean?</a></span></dt>
! 2495: <dt><span class="sect1"><a href="#using-sudo-with-pkgsrc">7.13. Using 'sudo' with pkgsrc</a></span></dt>
! 2496: <dt><span class="sect1"><a href="#faq.conf">7.14. How do I change the location of configuration files?</a></span></dt>
! 2497: <dt><span class="sect1"><a href="#audit-packages">7.15. Automated security checks</a></span></dt>
! 2498: <dt><span class="sect1"><a href="#ufaq-cflags">7.16. Why do some packages ignore my <code class="varname">CFLAGS</code>?</a></span></dt>
! 2499: </dl>
! 2500: </div>
! 2501: <p>This section contains hints, tips & tricks on special things in
! 2502: pkgsrc that we didn't find a better place for in the previous chapters, and
! 2503: it contains items for both pkgsrc users and developers.</p>
! 2504: <div class="sect1" lang="en">
! 2505: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2506: <a name="mailing-list-pointers"></a>7.1. Are there any mailing lists for pkg-related discussion?</h2></div></div></div>
! 2507: <p>The following mailing lists may be of interest to pkgsrc users:</p>
! 2508: <div class="itemizedlist"><ul type="disc">
! 2509: <li><p><a href="http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bugs" target="_top">pkgsrc-bugs</a>:
! 2510: All bug reports in category "pkg" sent 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> appear
! 2511: here. Please do not report your bugs here directly; use one
! 2512: of the other mailing lists.
! 2513: discussed.</p></li>
! 2514: <li><p><a href="http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bulk" target="_top">pkgsrc-bulk</a>:
! 2515: A list where the results of pkgsrc bulk builds are sent and
! 2516: discussed.</p></li>
! 2517: <li><p><a href="http://www.NetBSD.org/MailingLists/index.html#pkgsrc-changes" target="_top">pkgsrc-changes</a>:
! 2518: This list is for those who are interested in getting a
! 2519: commit message for every change committed to pkgsrc. It is
! 2520: also available in digest form, meaning one daily message
! 2521: containing all commit messages for changes to the package
! 2522: source tree in that 24 hour period.</p></li>
! 2523: <li><p><a href="http://www.NetBSD.org/MailingLists/index.html#tech-pkg" target="_top">pkgsrc-users</a>:
! 2524: This is a general purpose list for most issues regarding
! 2525: pkgsrc, regardless of platform, e.g. soliciting user help
! 2526: for pkgsrc configuration, unexpected build failures, using
! 2527: particular packages, upgrading pkgsrc installations,
! 2528: questions regarding the pkgsrc release branches, etc. General announcements or
! 2529: proposals for changes that impact the pkgsrc user community,
! 2530: e.g. major infrastructure changes, new features, package
! 2531: removals, etc., may also be posted.</p></li>
! 2532: <li><p><a href="http://www.NetBSD.org/MailingLists/index.html#tech-pkg" target="_top">tech-pkg</a>:
! 2533: This is a list for technical discussions related to pkgsrc
! 2534: development, e.g. soliciting feedback for changes to pkgsrc
! 2535: infrastructure, proposed new features, questions related
! 2536: to porting pkgsrc to a new platform, advice for maintaining
! 2537: a package, patches that affect many packages, help requests
! 2538: moved from pkgsrc-users when an infrastructure bug is found,
! 2539: etc.</p></li>
! 2540: </ul></div>
! 2541: <p>To subscribe, do:</p>
! 2542: <pre class="programlisting">
! 2543: <code class="prompt">%</code> echo subscribe <em class="replaceable"><code>listname</code></em> | mail majordomo@NetBSD.org
! 2544: </pre>
! 2545: <p>Archives for all these mailing lists are available from
! 2546: <a href="http://mail-index.NetBSD.org/" target="_top">http://mail-index.NetBSD.org/</a>.</p>
! 2547: </div>
! 2548: <div class="sect1" lang="en">
! 2549: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2550: <a name="pkgviews-docs"></a>7.2. Where's the pkgviews documentation?</h2></div></div></div>
! 2551: <p>Pkgviews is tightly integrated with buildlink. You can find a
! 2552: pkgviews User's guide in
! 2553: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/buildlink3/PKGVIEWS_UG</code>.</p>
! 2554: </div>
! 2555: <div class="sect1" lang="en">
! 2556: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2557: <a name="faq-pkgtools"></a>7.3. Utilities for package management (pkgtools)</h2></div></div></div>
! 2558: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/pkgtools</code> directory pkgtools contains
! 2559: a number of useful utilities for both users and developers of pkgsrc. This
! 2560: section attempts only to make the reader aware of the utilities and when
! 2561: they might be useful, and not to duplicate the documentation that comes
! 2562: with each package.</p>
! 2563: <p>Utilities used by pkgsrc (automatically installed when needed):</p>
! 2564: <div class="itemizedlist"><ul type="disc"><li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/x11-links/README.html" target="_top"><code xmlns="" class="filename">pkgtools/x11-links</code></a>:
! 2565: Symlinks for use by buildlink.</p></li></ul></div>
! 2566: <p>OS tool augmentation (automatically installed when needed):</p>
! 2567: <div class="itemizedlist"><ul type="disc">
! 2568: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/digest/README.html" target="_top"><code xmlns="" class="filename">pkgtools/digest</code></a>:
! 2569: Calculates various kinds of checksums (including SHA1).</p></li>
! 2570: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libnbcompat/README.html" target="_top"><code xmlns="" class="filename">pkgtools/libnbcompat</code></a>:
! 2571: Compatibility library for pkgsrc tools.</p></li>
! 2572: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/mtree/README.html" target="_top"><code xmlns="" class="filename">pkgtools/mtree</code></a>: Installed on
! 2573: non-BSD systems due to lack of native mtree.
! 2574: </p></li>
! 2575: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_install</code></a>:
! 2576: Up-to-date replacement for
! 2577: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/sbin/pkg_install</code>, or for use on operating
! 2578: systems where pkg_install is not present.</p></li>
! 2579: </ul></div>
! 2580: <p>Utilities used by pkgsrc (not automatically installed):</p>
! 2581: <div class="itemizedlist"><ul type="disc">
! 2582: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_tarup/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_tarup</code></a>:
! 2583: Create a binary package from an
! 2584: already-installed package. Used by <span><strong class="command">make replace</strong></span> to
! 2585: save the old package.</p></li>
! 2586: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/dfdisk/README.html" target="_top"><code xmlns="" class="filename">pkgtools/dfdisk</code></a>:
! 2587: Adds extra functionality to pkgsrc, allowing it to fetch distfiles
! 2588: from multiple locations. It currently supports the following
! 2589: methods: multiple CD-ROMs and network FTP/HTTP connections.</p></li>
! 2590: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html" target="_top"><code xmlns="" class="filename">pkgtools/xpkgwedge</code></a>: Put X11
! 2591: packages someplace else (enabled by default).</p></li>
! 2592: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html" target="_top"><code xmlns="" class="filename">devel/cpuflags</code></a>: Determine the
! 2593: best compiler flags to optimise code for your current CPU and
! 2594: compiler.</p></li>
! 2595: </ul></div>
! 2596: <p>Utilities for keeping track of installed packages, being up to date,
! 2597: etc:</p>
! 2598: <div class="itemizedlist"><ul type="disc">
! 2599: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_chk/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_chk</code></a>: Reports on
! 2600: packages whose installed versions do not match the latest pkgsrc
! 2601: entries.</p></li>
! 2602: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdep</code></a>: Makes
! 2603: dependency graphs of packages, to aid in choosing a strategy for
! 2604: updating.</p></li>
! 2605: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdepgraph/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdepgraph</code></a>: Makes
! 2606: graphs from the output of <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdep</code></a> (uses graphviz).</p></li>
! 2607: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkglint</code></a>: The
! 2608: pkglint(1) program checks a pkgsrc entry for errors, lintpkgsrc(1)
! 2609: does various checks on the complete pkgsrc system.</p></li>
! 2610: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgsurvey/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgsurvey</code></a>: Report what
! 2611: packages you have installed.</p></li>
! 2612: </ul></div>
! 2613: <p>Utilities for people maintaining or creating individual packages:</p>
! 2614: <div class="itemizedlist"><ul type="disc">
! 2615: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdiff</code></a>: Automate
! 2616: making and maintaining patches for a package (includes pkgdiff,
! 2617: pkgvi, mkpatches, etc.).</p></li>
! 2618: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/rpm2pkg/README.html" target="_top"><code xmlns="" class="filename">pkgtools/rpm2pkg</code></a>,
! 2619: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html" target="_top"><code xmlns="" class="filename">pkgtools/url2pkg</code></a>: Aids in
! 2620: converting to pkgsrc.</p></li>
! 2621: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/gensolpkg/README.html" target="_top"><code xmlns="" class="filename">pkgtools/gensolpkg</code></a>: Convert
! 2622: pkgsrc to a Solaris package.</p></li>
! 2623: </ul></div>
! 2624: <p>Utilities for people maintaining pkgsrc (or: more obscure pkg
! 2625: utilities)</p>
! 2626: <div class="itemizedlist"><ul type="disc">
! 2627: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_comp/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_comp</code></a>: Build
! 2628: packages in a chrooted area.</p></li>
! 2629: <li><p><a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libkver/README.html" target="_top"><code xmlns="" class="filename">pkgtools/libkver</code></a>: Spoof
! 2630: kernel version for chrooted cross builds.</p></li>
! 2631: </ul></div>
! 2632: </div>
! 2633: <div class="sect1" lang="en">
! 2634: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2635: <a name="non-root-pkgsrc"></a>7.4. How to use pkgsrc as non-root</h2></div></div></div>
! 2636: <p>If you want to use pkgsrc as non-root user, you can set some
! 2637: variables to make pkgsrc work under these conditions. At the very least,
! 2638: you need to set <code class="varname">UNPRIVILEGED</code> to “<span class="quote">yes</span>”; this
! 2639: will turn on unprivileged mode and set multiple related variables to allow
! 2640: installation of packages as non-root.</p>
! 2641: <p>In case the defaults are not enough, you may want to tune some other
! 2642: variables used. For example, if the automatic user/group detection leads
! 2643: to incorrect values (or not the ones you would like to use), you can change
! 2644: them by setting <code class="varname">UNPRIVILEGED_USER</code> and
! 2645: <code class="varname">UNPRIVILEGED_GROUP</code> respectively.</p>
! 2646: <p>As regards bootstrapping, please note that the
! 2647: <span><strong class="command">bootstrap</strong></span> script will ease non-root configuration when
! 2648: given the “<span class="quote">--ignore-user-check</span>” flag, as it will choose and
! 2649: use multiple default directories under <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">~/pkg</code> as the
! 2650: installation targets. These directories can be overriden by the
! 2651: “<span class="quote">--prefix</span>” flag provided by the script, as well as some others
! 2652: that allow finer tuning of the tree layout.</p>
! 2653: </div>
! 2654: <div class="sect1" lang="en">
! 2655: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2656: <a name="resume-transfers"></a>7.5. How to resume transfers when fetching distfiles?</h2></div></div></div>
! 2657: <p>By default, resuming transfers in pkgsrc is disabled, but you can
! 2658: enable this feature by adding the option
! 2659: <code class="varname">PKG_RESUME_TRANSFERS=YES</code> into
! 2660: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>. If, during a fetch step, an incomplete
! 2661: distfile is found, pkgsrc will try to resume it.</p>
! 2662: <p>You can also
! 2663: use a different program than the default <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ftp</span>(1)</span></a> by changing the
! 2664: <code class="varname">FETCH_CMD</code> variable. Don't forget to set
! 2665: <code class="varname">FETCH_RESUME_ARGS</code> and
! 2666: <code class="varname">FETCH_OUTPUT_ARGS</code> if you are not using default
! 2667: values.</p>
! 2668: <p>For example, if you want to use
! 2669: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">wget</code> to resume downloads, you'll have to use something
! 2670: like:</p>
! 2671: <pre class="programlisting">
! 2672: FETCH_CMD= wget
! 2673: FETCH_BEFORE_ARGS= --passive-ftp
! 2674: FETCH_RESUME_ARGS= -c
! 2675: FETCH_OUTPUT_ARGS= -O
1.1 grant 2676: </pre>
1.75 ! rillig 2677: </div>
! 2678: <div class="sect1" lang="en">
! 2679: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2680: <a name="XFree86-from-pkgsrc"></a>7.6. How can I install/use XFree86 from pkgsrc?</h2></div></div></div>
! 2681: <p>If you want to use XFree86 from pkgsrc instead of your system's own
! 2682: X11 (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/X11R6</code>, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/openwin</code>,
! 2683: ...), you will have to add the following line into
! 2684: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>:</p>
! 2685: <pre class="programlisting">
! 2686: X11_TYPE=XFree86
1.1 grant 2687: </pre>
1.75 ! rillig 2688: </div>
! 2689: <div class="sect1" lang="en">
! 2690: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2691: <a name="x.org-from-pkgsrc"></a>7.7. How can I install/use X.org from pkgsrc?</h2></div></div></div>
! 2692: <p>If you want to use X.org from pkgsrc instead of your system's own X11
! 2693: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/X11R6</code>, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/openwin</code>, ...)
! 2694: you will have to add the following line into
! 2695: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>:</p>
! 2696: <pre class="programlisting">
! 2697: X11_TYPE=xorg
1.1 grant 2698: </pre>
1.75 ! rillig 2699: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 2700: <h3 class="title">Note</h3>
! 2701: <p>The DragonFly operating system defaults to using
! 2702: this X.org X11 implementation from pkgsrc.
! 2703: </p>
! 2704: </div>
! 2705: </div>
! 2706: <div class="sect1" lang="en">
! 2707: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2708: <a name="fetch-behind-firewall"></a>7.8. How to fetch files from behind a firewall</h2></div></div></div>
! 2709: <p>If you are sitting behind a firewall which does not allow direct
! 2710: connections to Internet hosts (i.e. non-NAT), you may specify the
! 2711: relevant proxy hosts. This is done using an environment variable in the
! 2712: form of a URL, e.g. in Amdahl, the machine
! 2713: “<span class="quote">orpheus.amdahl.com</span>” is one of the firewalls, and it uses
! 2714: port 80 as the proxy port number. So the proxy environment variables
! 2715: are:</p>
! 2716: <pre class="programlisting">
! 2717: ftp_proxy=ftp://orpheus.amdahl.com:80/
! 2718: http_proxy=http://orpheus.amdahl.com:80/
1.1 grant 2719: </pre>
1.75 ! rillig 2720: </div>
! 2721: <div class="sect1" lang="en">
! 2722: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2723: <a name="passive-ftp"></a>7.9. How do I tell <span><strong class="command">make fetch</strong></span> to do passive FTP?</h2></div></div></div>
! 2724: <p>This depends on which utility is used to retrieve distfiles. From
! 2725: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.pkg.mk</code>, <code class="varname">FETCH_CMD</code> is assigned
! 2726: the first available command from the following list:</p>
! 2727: <div class="itemizedlist"><ul type="disc">
! 2728: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${LOCALBASE}/bin/ftp</code></p></li>
! 2729: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/bin/ftp</code></p></li>
! 2730: </ul></div>
! 2731: <p>On a default NetBSD installation, this will be
! 2732: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/bin/ftp</code>, which automatically tries passive
! 2733: connections first, and falls back to active connections if the server
! 2734: refuses to do passive. For the other tools, add the following to your
! 2735: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> file:
! 2736: <code class="varname">PASSIVE_FETCH=1</code>.</p>
! 2737: <p>Having that option present will prevent
! 2738: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/bin/ftp</code> from falling back to active
! 2739: transfers.</p>
! 2740: </div>
! 2741: <div class="sect1" lang="en">
! 2742: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2743: <a name="fetching-all-distfiles"></a>7.10. How to fetch all distfiles at once</h2></div></div></div>
! 2744: <p>You would like to download all the distfiles in a single batch from
! 2745: work or university, where you can't run a <span><strong class="command">make fetch</strong></span>.
! 2746: There is an archive of distfiles on <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/" target="_top">ftp.NetBSD.org</a>,
! 2747: but downloading the entire directory may not be appropriate.</p>
! 2748: <p>The answer here is to do a <span><strong class="command">make fetch-list</strong></span> in
! 2749: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc</code> or one of its subdirectories, carry the
! 2750: resulting list to your machine at work/school and use it there. If you
! 2751: don't have a NetBSD-compatible <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ftp</span>(1)</span></a> (like tnftp) at work, don't
! 2752: forget to set <code class="varname">FETCH_CMD</code> to something that fetches a
! 2753: URL:</p>
! 2754: <p>At home:</p>
! 2755: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
! 2756: <code class="prompt">%</code> <strong class="userinput"><code>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh</code></strong>
! 2757: <code class="prompt">%</code> <strong class="userinput"><code>scp /tmp/fetch.sh work:/tmp</code></strong></pre>
! 2758: <p>At work:</p>
! 2759: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>sh /tmp/fetch.sh</code></strong></pre>
! 2760: <p>then tar up <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/tmp/distfiles</code> and take it
! 2761: home.</p>
! 2762: <p>If you have a machine running NetBSD, and you want to get
! 2763: <span class="emphasis"><em>all</em></span> distfiles (even ones that aren't for your machine
! 2764: architecture), you can do so by using the above-mentioned <span><strong class="command">make
! 2765: fetch-list</strong></span> approach, or fetch the distfiles directly by
! 2766: running:</p>
! 2767: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>make mirror-distfiles</code></strong></pre>
! 2768: <p>If you even decide to ignore
! 2769: <code class="varname">NO_{SRC,BIN}_ON_{FTP,CDROM}</code>, then you can get everything
! 2770: by running:</p>
! 2771: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>make fetch NO_SKIP=yes</code></strong></pre>
! 2772: </div>
! 2773: <div class="sect1" lang="en">
! 2774: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2775: <a name="tmac.andoc-missing"></a>7.11. What does “<span class="quote">Don't know how to make
! 2776: /usr/share/tmac/tmac.andoc</span>” mean?</h2></div></div></div>
! 2777: <p>When compiling the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_install</code></a>
! 2778: package, you get the error from make that it doesn't know how to make
! 2779: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/share/tmac/tmac.andoc</code>? This indicates that
! 2780: you don't have installed the “<span class="quote">text</span>” set (nroff, ...) from
! 2781: the NetBSD base distribution on your machine. It is recommended to do
! 2782: that to format man pages.</p>
! 2783: <p>In the case of the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_install</code></a> package, you
! 2784: can get away with setting <code class="varname">NOMAN=YES</code> either in the
! 2785: environment or in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>.</p>
! 2786: </div>
! 2787: <div class="sect1" lang="en">
! 2788: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2789: <a name="bsd.own.mk-missing"></a>7.12. What does “<span class="quote">Could not find bsd.own.mk</span>” mean?</h2></div></div></div>
! 2790: <p> You didn't install the compiler set, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">comp.tgz</code>,
! 2791: when you installed your NetBSD machine. Please get and install it, by
! 2792: extracting it in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/</code>:</p>
! 2793: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /</code></strong>
! 2794: <code class="prompt">#</code> <strong class="userinput"><code>tar --unlink -zxvpf .../comp.tgz</code></strong></pre>
! 2795: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">comp.tgz</code> is part of every NetBSD release. Get
! 2796: the one that corresponds to your release (determine via <span><strong class="command">uname
! 2797: -r</strong></span>).</p>
! 2798: </div>
! 2799: <div class="sect1" lang="en">
! 2800: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2801: <a name="using-sudo-with-pkgsrc"></a>7.13. Using 'sudo' with pkgsrc</h2></div></div></div>
! 2802: <p>When installing packages as non-root user and using the just-in-time
! 2803: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">su</span>(1)</span></a> feature of pkgsrc, it can become annoying to type in the root
! 2804: password for each required package installed. To avoid this, the sudo
! 2805: package can be used, which does password caching over a limited time. To
! 2806: use it, install sudo (either as binary package or from
! 2807: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/sudo/README.html" target="_top"><code xmlns="" class="filename">security/sudo</code></a>) and then put the following
! 2808: into your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>:</p>
! 2809: <pre class="programlisting">
! 2810: .if exists(${LOCALBASE}/bin/sudo)
! 2811: SU_CMD= ${LOCALBASE}/bin/sudo /bin/sh -c
! 2812: .endif
1.1 grant 2813: </pre>
1.75 ! rillig 2814: </div>
! 2815: <div class="sect1" lang="en">
! 2816: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2817: <a name="faq.conf"></a>7.14. How do I change the location of configuration files?</h2></div></div></div>
! 2818: <p>As the system administrator, you can choose where configuration files
! 2819: are installed. The default settings make all these files go into
! 2820: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/etc</code> or some of its subdirectories; this may
! 2821: be suboptimal depending on your expectations (e.g., a read-only,
! 2822: NFS-exported <code class="varname">PREFIX</code> with a need of per-machine
! 2823: configuration of the provided packages).</p>
! 2824: <p>In order to change the defaults, you can modify the
! 2825: <code class="varname">PKG_SYSCONFBASE</code> variable (in
! 2826: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>) to point to your preferred configuration
! 2827: directory; some common examples include <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc</code> or
! 2828: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/pkg</code>.</p>
! 2829: <p>Furthermore, you can change this value on a per-package basis by
! 2830: setting the <code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> variable.
! 2831: <code class="varname">PKG_SYSCONFVAR</code>'s value usually matches the name of the
! 2832: package you would like to modify, that is, the contents of
! 2833: <code class="varname">PKGBASE</code>.</p>
! 2834: <p>Note that after changing these settings, you must rebuild and
! 2835: reinstall any affected packages.</p>
! 2836: </div>
! 2837: <div class="sect1" lang="en">
! 2838: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2839: <a name="audit-packages"></a>7.15. Automated security checks</h2></div></div></div>
! 2840: <p>Please be aware that there can often be bugs in third-party software,
! 2841: and some of these bugs can leave a machine vulnerable to exploitation by
! 2842: attackers. In an effort to lessen the exposure, the NetBSD packages team
! 2843: maintains a database of known-exploits to packages which have at one time
! 2844: been included in pkgsrc. The database can be downloaded automatically, and
! 2845: a security audit of all packages installed on a system can take place. To
! 2846: do this, install the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html" target="_top"><code xmlns="" class="filename">security/audit-packages</code></a> package. It has two
! 2847: components:</p>
! 2848: <div class="orderedlist"><ol type="1">
! 2849: <li>
! 2850: <p><span><strong class="command">download-vulnerability-list</strong></span>, an easy way to
! 2851: download a list of the security vulnerabilities information. This list
! 2852: is kept up to date by the NetBSD security officer and the NetBSD
! 2853: packages team, and is distributed from the NetBSD ftp server:</p>
! 2854: <p><a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities" target="_top">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</a></p>
! 2855: </li>
! 2856: <li><p><span><strong class="command">audit-packages</strong></span>, an easy way to audit the
! 2857: current machine, checking each vulnerability which is known. If a
! 2858: vulnerable package is installed, it will be shown by output to stdout,
! 2859: including a description of the type of vulnerability, and a URL
! 2860: containing more information.</p></li>
! 2861: </ol></div>
! 2862: <p>Use of the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html" target="_top"><code xmlns="" class="filename">security/audit-packages</code></a>
! 2863: package is strongly recommended! After
! 2864: “<span class="quote">audit-packages</span>” is installed, please read
! 2865: the package's message, which you can get by running <strong class="userinput"><code>pkg_info -D
! 2866: audit-packages</code></strong>.</p>
! 2867: <p>If this package is installed, pkgsrc builds will use it to perform
! 2868: a security check before building any package. See
! 2869: <a href="#variables-affecting-build" title="5.2. Variables affecting the build process">Section 5.2, “Variables affecting the build process”</a> for ways to control this check.
! 2870: </p>
! 2871: </div>
! 2872: <div class="sect1" lang="en">
! 2873: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 2874: <a name="ufaq-cflags"></a>7.16. Why do some packages ignore my <code class="varname">CFLAGS</code>?</h2></div></div></div>
! 2875: <p>When you add your own preferences to the
! 2876: <code class="varname">CFLAGS</code> variable in your
! 2877: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk.conf</code>, these flags are passed in
! 2878: environment variables to the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">./configure</code>
! 2879: scripts and to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>. Some package authors ignore the
! 2880: <code class="varname">CFLAGS</code> from the environment variable by
! 2881: overriding them in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s of their
! 2882: package.</p>
! 2883: <p>Currently there is no solution to this problem. If you
! 2884: really need the package to use your <code class="varname">CFLAGS</code>
! 2885: you should run <span><strong class="command">make patch</strong></span> in the package
! 2886: directory and then inspect any <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> and
! 2887: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile.in</code> for whether they define
! 2888: <code class="varname">CFLAGS</code> explicitly. Usually you can remove
! 2889: these lines. But be aware that some “<span class="quote">smart</span>”
! 2890: programmers write so bad code that it only works for the
! 2891: specific combination of <code class="varname">CFLAGS</code> they have
! 2892: chosen.</p>
! 2893: </div>
! 2894: </div>
! 2895: </div>
! 2896: <div class="part" lang="en">
! 2897: <div class="titlepage"><div><div><h1 class="title">
! 2898: <a name="developers-guide"></a>Part II. The pkgsrc developer's guide</h1></div></div></div>
! 2899: <div class="toc">
! 2900: <p><b>Table of Contents</b></p>
! 2901: <dl>
! 2902: <dt><span class="chapter"><a href="#components">8. Package components - files, directories and contents</a></span></dt>
! 2903: <dd><dl>
! 2904: <dt><span class="sect1"><a href="#components.Makefile">8.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code></a></span></dt>
! 2905: <dt><span class="sect1"><a href="#components.distinfo">8.2. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code></a></span></dt>
! 2906: <dt><span class="sect1"><a href="#components.patches">8.3. patches/*</a></span></dt>
! 2907: <dt><span class="sect1"><a href="#other-mandatory-files">8.4. Other mandatory files</a></span></dt>
! 2908: <dt><span class="sect1"><a href="#components.optional">8.5. Optional files</a></span></dt>
! 2909: <dt><span class="sect1"><a href="#work-dir">8.6. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work*</code></a></span></dt>
! 2910: <dt><span class="sect1"><a href="#files-dir">8.7. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">files/*</code></a></span></dt>
! 2911: </dl></dd>
! 2912: <dt><span class="chapter"><a href="#makefile">9. Programming in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s</a></span></dt>
! 2913: <dd><dl>
! 2914: <dt><span class="sect1"><a href="#makefile.variables">9.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> variables</a></span></dt>
! 2915: <dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">9.1.1. Naming conventions</a></span></dt></dl></dd>
! 2916: <dt><span class="sect1"><a href="#makefile.code">9.2. Code snippets</a></span></dt>
! 2917: <dd><dl>
! 2918: <dt><span class="sect2"><a href="#adding-to-list">9.2.1. Adding things to a list</a></span></dt>
! 2919: <dt><span class="sect2"><a href="#converting-internal-to-external">9.2.2. Converting an internal list into an external list</a></span></dt>
! 2920: <dt><span class="sect2"><a href="#passing-variable-to-shell">9.2.3. Passing variables to a shell command</a></span></dt>
! 2921: <dt><span class="sect2"><a href="#quoting-guideline">9.2.4. Quoting guideline</a></span></dt>
! 2922: <dt><span class="sect2"><a href="#bsd-make-bug-workaround">9.2.5. Workaround for a bug in BSD Make</a></span></dt>
! 2923: </dl></dd>
! 2924: </dl></dd>
! 2925: <dt><span class="chapter"><a href="#plist">10. PLIST issues</a></span></dt>
! 2926: <dd><dl>
! 2927: <dt><span class="sect1"><a href="#rcs-id">10.1. RCS ID</a></span></dt>
! 2928: <dt><span class="sect1"><a href="#automatic-plist-generation">10.2. Semi-automatic <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> generation</a></span></dt>
! 2929: <dt><span class="sect1"><a href="#print-PLIST">10.3. Tweaking output of <span><strong class="command">make print-PLIST</strong></span></a></span></dt>
! 2930: <dt><span class="sect1"><a href="#plist.misc">10.4. Variable substitution in PLIST</a></span></dt>
! 2931: <dt><span class="sect1"><a href="#manpage-compression">10.5. Man page compression</a></span></dt>
! 2932: <dt><span class="sect1"><a href="#using-PLIST_SRC">10.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
! 2933: <dt><span class="sect1"><a href="#platform-specific-plist">10.7. Platform-specific and differing PLISTs</a></span></dt>
! 2934: <dt><span class="sect1"><a href="#faq.common-dirs">10.8. Sharing directories between packages</a></span></dt>
! 2935: </dl></dd>
! 2936: <dt><span class="chapter"><a href="#buildlink">11. Buildlink methodology</a></span></dt>
! 2937: <dd><dl>
! 2938: <dt><span class="sect1"><a href="#converting-to-buildlink3">11.1. Converting packages to use buildlink3</a></span></dt>
! 2939: <dt><span class="sect1"><a href="#creating-buildlink3.mk">11.2. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 2940: <dd><dl>
! 2941: <dt><span class="sect2"><a href="#anatomy-of-bl3">11.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
! 2942: <dt><span class="sect2"><a href="#updating-buildlink-depends">11.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 2943: </dl></dd>
! 2944: <dt><span class="sect1"><a href="#writing-builtin.mk">11.3. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> files</a></span></dt>
! 2945: <dd><dl>
! 2946: <dt><span class="sect2"><a href="#anatomy-of-builtin.mk">11.3.1. Anatomy of a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file</a></span></dt>
! 2947: <dt><span class="sect2"><a href="#native-or-pkgsrc-preference">11.3.2. Global preferences for native or pkgsrc software</a></span></dt>
! 2948: </dl></dd>
! 2949: </dl></dd>
! 2950: <dt><span class="chapter"><a href="#pkginstall">12. The pkginstall framework</a></span></dt>
! 2951: <dd><dl>
! 2952: <dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">12.1. Files and directories outside the installation prefix</a></span></dt>
! 2953: <dd><dl>
! 2954: <dt><span class="sect2"><a href="#dirs-outside-prefix">12.1.1. Directory manipulation</a></span></dt>
! 2955: <dt><span class="sect2"><a href="#files-outside-prefix">12.1.2. File manipulation</a></span></dt>
! 2956: </dl></dd>
! 2957: <dt><span class="sect1"><a href="#conf-files">12.2. Configuration files</a></span></dt>
! 2958: <dd><dl>
! 2959: <dt><span class="sect2"><a href="#conf-files-sysconfdir">12.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
! 2960: <dt><span class="sect2"><a href="#conf-files-configure">12.2.2. Telling the software where configuration files are</a></span></dt>
! 2961: <dt><span class="sect2"><a href="#conf-files-patching">12.2.3. Patching installations</a></span></dt>
! 2962: <dt><span class="sect2"><a href="#conf-files-disable">12.2.4. Disabling handling of configuration files</a></span></dt>
! 2963: </dl></dd>
! 2964: <dt><span class="sect1"><a href="#rcd-scripts">12.3. System startup scripts</a></span></dt>
! 2965: <dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">12.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
! 2966: <dt><span class="sect1"><a href="#users-and-groups">12.4. System users and groups</a></span></dt>
! 2967: <dt><span class="sect1"><a href="#shells">12.5. System shells</a></span></dt>
! 2968: <dd><dl><dt><span class="sect2"><a href="#shells-disable">12.5.1. Disabling shell registration</a></span></dt></dl></dd>
! 2969: <dt><span class="sect1"><a href="#fonts">12.6. Fonts</a></span></dt>
! 2970: <dd><dl><dt><span class="sect2"><a href="#fonts-disable">12.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
! 2971: </dl></dd>
! 2972: <dt><span class="chapter"><a href="#options">13. Options handling</a></span></dt>
! 2973: <dd><dl>
! 2974: <dt><span class="sect1"><a href="#global-default-options">13.1. Global default options</a></span></dt>
! 2975: <dt><span class="sect1"><a href="#converting-to-options">13.2. Converting packages to use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code></a></span></dt>
! 2976: <dt><span class="sect1"><a href="#option-names">13.3. Option Names</a></span></dt>
! 2977: </dl></dd>
! 2978: <dt><span class="chapter"><a href="#build">14. The build process</a></span></dt>
! 2979: <dd><dl>
! 2980: <dt><span class="sect1"><a href="#build.intro">14.1. Introduction</a></span></dt>
! 2981: <dt><span class="sect1"><a href="#build.prefix">14.2. Program location</a></span></dt>
! 2982: <dt><span class="sect1"><a href="#build.builddirs">14.3. Directories used during the build process</a></span></dt>
! 2983: <dt><span class="sect1"><a href="#build.running">14.4. Running a phase</a></span></dt>
! 2984: <dt><span class="sect1"><a href="#build.fetch">14.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
! 2985: <dt><span class="sect1"><a href="#build.checksum">14.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
! 2986: <dt><span class="sect1"><a href="#build.extract">14.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
! 2987: <dt><span class="sect1"><a href="#build.patch">14.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
! 2988: <dt><span class="sect1"><a href="#build.tools">14.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
! 2989: <dt><span class="sect1"><a href="#build.wrapper">14.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
! 2990: <dt><span class="sect1"><a href="#build.configure">14.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
! 2991: <dt><span class="sect1"><a href="#build.build">14.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
! 2992: <dt><span class="sect1"><a href="#build.test">14.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
! 2993: <dt><span class="sect1"><a href="#build.install">14.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
! 2994: <dt><span class="sect1"><a href="#build.package">14.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
! 2995: <dt><span class="sect1"><a href="#build.helpful-targets">14.16. Other helpful targets</a></span></dt>
! 2996: </dl></dd>
! 2997: <dt><span class="chapter"><a href="#tools">15. Tools needed for building or running</a></span></dt>
! 2998: <dd><dl>
! 2999: <dt><span class="sect1"><a href="#pkgsrc-tools">15.1. Tools for pkgsrc builds</a></span></dt>
! 3000: <dt><span class="sect1"><a href="#package-tools">15.2. Tools needed by packages</a></span></dt>
! 3001: <dt><span class="sect1"><a href="#platform-tools">15.3. Tools provided by platforms</a></span></dt>
! 3002: </dl></dd>
! 3003: <dt><span class="chapter"><a href="#fixes">16. Making your package work</a></span></dt>
! 3004: <dd><dl>
! 3005: <dt><span class="sect1"><a href="#general-operation">16.1. General operation</a></span></dt>
! 3006: <dd><dl>
! 3007: <dt><span class="sect2"><a href="#pulling-vars-from-etc-mk.conf">16.1.1. How to pull in variables from /etc/mk.conf</a></span></dt>
! 3008: <dt><span class="sect2"><a href="#where-to-install-documentation">16.1.2. Where to install documentation</a></span></dt>
! 3009: <dt><span class="sect2"><a href="#restricted-packages">16.1.3. Restricted packages</a></span></dt>
! 3010: <dt><span class="sect2"><a href="#dependencies">16.1.4. Handling dependencies</a></span></dt>
! 3011: <dt><span class="sect2"><a href="#conflicts">16.1.5. Handling conflicts with other packages</a></span></dt>
! 3012: <dt><span class="sect2"><a href="#not-building-packages">16.1.6. Packages that cannot or should not be built</a></span></dt>
! 3013: <dt><span class="sect2"><a href="#undeletable-packages">16.1.7. Packages which should not be deleted, once installed</a></span></dt>
! 3014: <dt><span class="sect2"><a href="#security-handling">16.1.8. Handling packages with security problems</a></span></dt>
! 3015: <dt><span class="sect2"><a href="#compiler-bugs">16.1.9. How to handle compiler bugs</a></span></dt>
! 3016: <dt><span class="sect2"><a href="#bumping-pkgrevision">16.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt>
! 3017: <dt><span class="sect2"><a href="#portability-of-packages">16.1.11. Portability of packages</a></span></dt>
! 3018: </dl></dd>
! 3019: <dt><span class="sect1"><a href="#downloading-issues">16.2. Possible downloading issues</a></span></dt>
! 3020: <dd><dl>
! 3021: <dt><span class="sect2"><a href="#no-plain-download">16.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt>
! 3022: <dt><span class="sect2"><a href="#modified-distfiles-same-name">16.2.2. How to handle modified distfiles with the 'old' name</a></span></dt>
! 3023: </dl></dd>
! 3024: <dt><span class="sect1"><a href="#configuration-gotchas">16.3. Configuration gotchas</a></span></dt>
! 3025: <dd><dl>
! 3026: <dt><span class="sect2"><a href="#fixes.libtool">16.3.1. Shared libraries - libtool</a></span></dt>
! 3027: <dt><span class="sect2"><a href="#using-libtool">16.3.2. Using libtool on GNU packages that already support libtool</a></span></dt>
! 3028: <dt><span class="sect2"><a href="#autoconf-automake">16.3.3. GNU Autoconf/Automake</a></span></dt>
! 3029: </dl></dd>
! 3030: <dt><span class="sect1"><a href="#fixes-build">16.4. Building the package</a></span></dt>
! 3031: <dd><dl>
! 3032: <dt><span class="sect2"><a href="#cpp-defines">16.4.1. CPP defines</a></span></dt>
! 3033: <dt><span class="sect2"><a href="#cpp-list-examples">16.4.2. Examples of CPP defines for some platforms</a></span></dt>
! 3034: <dt><span class="sect2"><a href="#cpp-list">16.4.3. Getting a list of CPP defines</a></span></dt>
! 3035: </dl></dd>
! 3036: <dt><span class="sect1"><a href="#package-specific-actions">16.5. Package specific actions</a></span></dt>
! 3037: <dd><dl>
! 3038: <dt><span class="sect2"><a href="#user-interaction">16.5.1. User interaction</a></span></dt>
! 3039: <dt><span class="sect2"><a href="#handling-licenses">16.5.2. Handling licenses</a></span></dt>
! 3040: <dt><span class="sect2"><a href="#installing-score-files">16.5.3. Installing score files</a></span></dt>
! 3041: <dt><span class="sect2"><a href="#perl-scripts">16.5.4. Packages containing perl scripts</a></span></dt>
! 3042: <dt><span class="sect2"><a href="#hardcoded-paths">16.5.5. Packages with hardcoded paths to other interpreters</a></span></dt>
! 3043: <dt><span class="sect2"><a href="#perl-modules">16.5.6. Packages installing perl modules</a></span></dt>
! 3044: <dt><span class="sect2"><a href="#faq.info-files">16.5.7. Packages installing info files</a></span></dt>
! 3045: <dt><span class="sect2"><a href="#manpages">16.5.8. Packages installing man pages</a></span></dt>
! 3046: <dt><span class="sect2"><a href="#gconf2-data-files">16.5.9. Packages installing GConf2 data files</a></span></dt>
! 3047: <dt><span class="sect2"><a href="#scrollkeeper-data-files">16.5.10. Packages installing scrollkeeper data files</a></span></dt>
! 3048: <dt><span class="sect2"><a href="#x11-fonts">16.5.11. Packages installing X11 fonts</a></span></dt>
! 3049: <dt><span class="sect2"><a href="#gtk2-modules">16.5.12. Packages installing GTK2 modules</a></span></dt>
! 3050: <dt><span class="sect2"><a href="#sgml-xml-data">16.5.13. Packages installing SGML or XML data</a></span></dt>
! 3051: <dt><span class="sect2"><a href="#mime-database">16.5.14. Packages installing extensions to the MIME database</a></span></dt>
! 3052: <dt><span class="sect2"><a href="#intltool">16.5.15. Packages using intltool</a></span></dt>
! 3053: <dt><span class="sect2"><a href="#startup-scripts">16.5.16. Packages installing startup scripts</a></span></dt>
! 3054: <dt><span class="sect2"><a href="#tex-packages">16.5.17. Packages installing TeX modules</a></span></dt>
! 3055: </dl></dd>
! 3056: <dt><span class="sect1"><a href="#feedback-to-author">16.6. Feedback to the author</a></span></dt>
! 3057: </dl></dd>
! 3058: <dt><span class="chapter"><a href="#debug">17. Debugging</a></span></dt>
! 3059: <dt><span class="chapter"><a href="#submit">18. Submitting and Committing</a></span></dt>
! 3060: <dd><dl>
! 3061: <dt><span class="sect1"><a href="#submitting-binary-packages">18.1. Submitting binary packages</a></span></dt>
! 3062: <dt><span class="sect1"><a href="#submitting-your-package">18.2. Submitting source packages (for non-NetBSD-developers)</a></span></dt>
! 3063: <dt><span class="sect1"><a href="#general-notes-for-changes">18.3. General notes when adding, updating, or removing packages</a></span></dt>
! 3064: <dt><span class="sect1"><a href="#committing-importing">18.4. Committing: Importing a package into CVS</a></span></dt>
! 3065: <dt><span class="sect1"><a href="#updating-package">18.5. Updating a package to a newer version</a></span></dt>
! 3066: <dt><span class="sect1"><a href="#moving-package">18.6. Moving a package in pkgsrc</a></span></dt>
! 3067: </dl></dd>
! 3068: <dt><span class="chapter"><a href="#devfaq">19. Frequently Asked Questions</a></span></dt>
! 3069: </dl>
! 3070: </div>
! 3071: <div class="chapter" lang="en">
! 3072: <div class="titlepage"><div><div><h2 class="title">
! 3073: <a name="components"></a>Chapter 8. Package components - files, directories and contents</h2></div></div></div>
! 3074: <div class="toc">
! 3075: <p><b>Table of Contents</b></p>
! 3076: <dl>
! 3077: <dt><span class="sect1"><a href="#components.Makefile">8.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code></a></span></dt>
! 3078: <dt><span class="sect1"><a href="#components.distinfo">8.2. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code></a></span></dt>
! 3079: <dt><span class="sect1"><a href="#components.patches">8.3. patches/*</a></span></dt>
! 3080: <dt><span class="sect1"><a href="#other-mandatory-files">8.4. Other mandatory files</a></span></dt>
! 3081: <dt><span class="sect1"><a href="#components.optional">8.5. Optional files</a></span></dt>
! 3082: <dt><span class="sect1"><a href="#work-dir">8.6. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work*</code></a></span></dt>
! 3083: <dt><span class="sect1"><a href="#files-dir">8.7. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">files/*</code></a></span></dt>
! 3084: </dl>
! 3085: </div>
! 3086: <p> Whenever you're preparing a package, there are a number of
! 3087: files involved which are described in the following
! 3088: sections. </p>
! 3089: <div class="sect1" lang="en">
! 3090: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3091: <a name="components.Makefile"></a>8.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code></h2></div></div></div>
! 3092: <p>Building, installation and creation of a binary package are all
! 3093: controlled by the package's <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>.
! 3094: The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> describes various things about
! 3095: a package, for example from where to get it, how to configure,
! 3096: build, and install it.
! 3097: </p>
! 3098: <p>A package <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> contains several
! 3099: sections that describe the package.</p>
! 3100: <p>In the first section there are the following variables, which
! 3101: should appear exactly in the order given here.
! 3102: </p>
! 3103: <div class="itemizedlist"><ul type="disc">
! 3104: <li><p><code class="varname">DISTNAME</code> is the basename of the
! 3105: distribution file to be downloaded from the package's
! 3106: website.</p></li>
! 3107: <li><p><code class="varname">PKGNAME</code> is the name of the
! 3108: package, as used by pkgsrc. You only need to provide it if it
! 3109: differs from <code class="varname">DISTNAME</code>. Usually it is the directory name together
! 3110: with the version number. It must match the regular expression
! 3111: <code class="varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>, that is, it
! 3112: starts with a letter or digit, and contains only letters, digits,
! 3113: dashes, underscores, dots and plus signs.</p></li>
! 3114: <li>
! 3115: <p><code class="varname">CATEGORIES</code> is a list of categories
! 3116: which the package fits in. You can choose any of the top-level
! 3117: directories of pkgsrc for it.</p>
! 3118: <p>Currently the following values are available for
! 3119: <code class="varname">CATEGORIES</code>. If more than
! 3120: one is used, they need to be separated by spaces:</p>
! 3121: <pre class="programlisting">
! 3122: archivers cross geography meta-pkgs security
! 3123: audio databases graphics misc shells
! 3124: benchmarks devel ham multimedia sysutils
! 3125: biology editors inputmethod net textproc
! 3126: cad emulators lang news time
! 3127: chat finance mail parallel wm
! 3128: comms fonts math pkgtools www
! 3129: converters games mbone print x11
1.1 grant 3130: </pre>
1.75 ! rillig 3131: </li>
! 3132: <li>
! 3133: <p><code class="varname">MASTER_SITES</code> is a list of URLs where
! 3134: the distribution files can be downloaded. Each URL must end with a
! 3135: slash.</p>
! 3136: <p>The <code class="varname">MASTER_SITES</code> may make use of
! 3137: the following predefined sites:</p>
! 3138: <pre class="programlisting">
! 3139: ${MASTER_SITE_APACHE}
! 3140: ${MASTER_SITE_BACKUP}
! 3141: ${MASTER_SITE_CYGWIN}
! 3142: ${MASTER_SITE_DEBIAN}
! 3143: ${MASTER_SITE_FREEBSD}
! 3144: ${MASTER_SITE_FREEBSD_LOCAL}
! 3145: ${MASTER_SITE_GNOME}
! 3146: ${MASTER_SITE_GNU}
! 3147: ${MASTER_SITE_GNUSTEP}
! 3148: ${MASTER_SITE_IFARCHIVE}
! 3149: ${MASTER_SITE_MOZILLA}
! 3150: ${MASTER_SITE_OPENOFFICE}
! 3151: ${MASTER_SITE_PERL_CPAN}
! 3152: ${MASTER_SITE_R_CRAN}
! 3153: ${MASTER_SITE_SOURCEFORGE}
! 3154: ${MASTER_SITE_SUNSITE}
! 3155: ${MASTER_SITE_SUSE}
! 3156: ${MASTER_SITE_TEX_CTAN}
! 3157: ${MASTER_SITE_XCONTRIB}
! 3158: ${MASTER_SITE_XEMACS}
1.74 rillig 3159: </pre>
1.75 ! rillig 3160: <p>If one of these predefined sites is chosen, you may
! 3161: want to specify a subdirectory of that
! 3162: site. Since these macros may expand to more than one
! 3163: actual site, you <span class="emphasis"><em>must</em></span> use the
! 3164: following construct to specify a subdirectory:</p>
! 3165: <pre class="programlisting">
! 3166: ${MASTER_SITE_GNU:=subdirectory/name/}
! 3167: ${MASTER_SITE_SOURCEFORGE:=project_name/}
1.1 grant 3168: </pre>
1.75 ! rillig 3169: <p>Note the trailing slash after the subdirectory name.</p>
! 3170: <p>If the package has multiple
! 3171: <code class="varname">DISTFILES</code> or multiple
! 3172: <code class="varname">PATCHFILES</code> from different
! 3173: sites, set <code class="varname">SITES.foo</code> to a list of URIs
! 3174: where file “<span class="quote">foo</span>” may be
! 3175: found. “<span class="quote">foo</span>” includes the suffix, e.g.:</p>
! 3176: <pre class="programlisting">
! 3177: DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
! 3178: DISTFILES+= foo-file.tar.gz
! 3179: SITES.foo-file.tar.gz= \
! 3180: http://www.somewhere.com/somehow/ \
! 3181: http://www.somewhereelse.com/mirror/somehow/
1.1 grant 3182: </pre>
1.75 ! rillig 3183: </li>
! 3184: <li>
! 3185: <p><code class="varname">DISTFILES</code>: Name(s)
! 3186: of archive file(s) containing distribution. The default is
! 3187: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${DISTNAME}${EXTRACT_SUFX}</code>. Should only
! 3188: be set if you have more than one distfile.</p>
! 3189: <p>Note that the normal default setting of
! 3190: <code class="varname">DISTFILES</code> must be made explicit if you
! 3191: want to add to it (rather than replace it), as you usually
! 3192: would.</p>
! 3193: </li>
! 3194: <li><p><code class="varname">EXTRACT_SUFX</code>: Suffix of the
! 3195: distribution file, will be appended to
! 3196: <code class="varname">DISTNAME</code>. Defaults to
! 3197: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.tar.gz</code>.
! 3198: </p></li>
! 3199: </ul></div>
! 3200: <p>
! 3201: </p>
! 3202: <p>The second section contains information about separately
! 3203: downloaded patches, if any.
! 3204: </p>
! 3205: <div class="itemizedlist"><ul type="disc">
! 3206: <li><p><code class="varname">PATCHFILES:</code>
! 3207: Name(s) of additional files that contain distribution patches.
! 3208: There is no default. pkgsrc will look for them at
! 3209: <code class="varname">PATCH_SITES</code>.
! 3210: They will automatically be uncompressed before patching if
! 3211: the names end with <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.gz</code> or
! 3212: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.Z</code>.</p></li>
! 3213: <li><p><code class="varname">PATCH_SITES</code>:
! 3214: Primary location(s) for distribution patch files (see
! 3215: <code class="varname">PATCHFILES</code> below) if not found locally.</p></li>
! 3216: </ul></div>
! 3217: <p>
! 3218: </p>
! 3219: <p>The third section contains the following variables.
! 3220: </p>
! 3221: <div class="itemizedlist"><ul type="disc">
! 3222: <li><p><code class="varname">MAINTAINER</code> is the email address
! 3223: of the person who feels responsible for this package, and who is
! 3224: most likely to look at problems or questions regarding this
! 3225: 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
! 3226: developers should contact the <code class="varname">MAINTAINER</code> before
! 3227: making major changes to the package. When packaging a new program,
! 3228: set <code class="varname">MAINTAINER</code> to yourself. If you really can't
! 3229: maintain the package for future updates, set it to
! 3230: <code class="email"><<a href="mailto:pkgsrc-users@NetBSD.org">pkgsrc-users@NetBSD.org</a>></code>.</p></li>
! 3231: <li><p><code class="varname">HOMEPAGE</code> is a URL where users can
! 3232: find more information about the package.</p></li>
! 3233: <li><p><code class="varname">COMMENT</code> is a one-line
! 3234: description of the package (should not include the package
! 3235: name).</p></li>
! 3236: </ul></div>
! 3237: <p>
! 3238: </p>
! 3239: <p>Other variables that affect the build:
! 3240: </p>
! 3241: <div class="itemizedlist"><ul type="disc"><li>
! 3242: <p><code class="varname">WRKSRC</code>: The directory where the
! 3243: interesting distribution files of the package are found. The
! 3244: default is <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKDIR}/${DISTNAME}</code>, which
! 3245: works for most packages.</p>
! 3246: <p>If a package doesn't create a subdirectory for itself
! 3247: (most GNU software does, for instance), but extracts itself in
! 3248: the current directory, you should set <code class="varname">WRKSRC=
! 3249: ${WRKDIR}</code>.</p>
! 3250: <p>If a package doesn't create a subdirectory with the name
! 3251: of <code class="varname">DISTNAME</code> but some different name, set
! 3252: <code class="varname">WRKSRC</code> to point to the proper name in
! 3253: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKDIR}</code>, for example <code class="varname">WRKSRC=
! 3254: ${WRKDIR}/${DISTNAME}/unix</code>. See <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/tcl/README.html" target="_top"><code xmlns="" class="filename">lang/tcl</code></a> and <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/tk/README.html" target="_top"><code xmlns="" class="filename">x11/tk</code></a> for other examples.</p>
! 3255: <p>The name of the working directory created by pkgsrc is
! 3256: taken from the <code class="varname">WRKDIR_BASENAME</code> variable. By
! 3257: default, its value is <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work</code>. If you want
! 3258: to use the same pkgsrc tree for building different kinds of
! 3259: binary packages, you can change the variable according to your
! 3260: needs. Two other variables handle common cases of setting
! 3261: <code class="varname">WRKDIR_BASENAME</code> individually. If
! 3262: <code class="varname">OBJHOSTNAME</code> is defined in
! 3263: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>, the first component of the
! 3264: host's name is attached to the directory name. If
! 3265: <code class="varname">OBJMACHINE</code> is defined, the platform name is
! 3266: attached, which might look like <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work.i386</code>
! 3267: or <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work.sparc</code>.</p>
! 3268: </li></ul></div>
! 3269: <p>
! 3270: </p>
! 3271: <p>Please pay attention to the following gotchas:</p>
! 3272: <div class="itemizedlist"><ul type="disc">
! 3273: <li><p>Add <code class="varname">MANCOMPRESSED</code> if man pages are installed in
! 3274: compressed form by the package; see comment in
! 3275: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.pkg.mk</code>.</p></li>
! 3276: <li><p>Replace <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/local</code> with
! 3277: “<span class="quote">${PREFIX}</span>” in all files (see patches, below).</p></li>
! 3278: <li><p>If the package installs any info files, see
! 3279: <a href="#faq.info-files" title="16.5.7. Packages installing info files">Section 16.5.7, “Packages installing info files”</a>.</p></li>
! 3280: </ul></div>
! 3281: </div>
! 3282: <div class="sect1" lang="en">
! 3283: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3284: <a name="components.distinfo"></a>8.2. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code></h2></div></div></div>
! 3285: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code> file contains the message
! 3286: digest, or checksum, of each distfile needed for the package. This
! 3287: ensures that the distfiles retrieved from the Internet have not been
! 3288: corrupted during transfer or altered by a malign force to introduce
! 3289: a security hole. Due to recent rumor about weaknesses of digest
! 3290: algorithms, all distfiles are protected using both SHA1 and RMD160
! 3291: message digests, as well as the file size.</p>
! 3292: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code> file also contains the
! 3293: checksums for all the patches found in the
! 3294: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">patches</code> directory (see <a href="#components.patches" title="8.3. patches/*">Section 8.3, “patches/*”</a>).</p>
! 3295: <p>To regenerate the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code> file, use the
! 3296: <span><strong class="command">make makedistinfo</strong></span> or <span><strong class="command">make mdi</strong></span>
! 3297: command.</p>
! 3298: <p>Some packages have different sets of distfiles depending on
! 3299: the platform, for example <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/navigator/README.html" target="_top"><code xmlns="" class="filename">www/navigator</code></a>). These are kept in the same
! 3300: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code> file and care should be taken when
! 3301: upgrading such a package to ensure distfile information is not
! 3302: lost.</p>
! 3303: </div>
! 3304: <div class="sect1" lang="en">
! 3305: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3306: <a name="components.patches"></a>8.3. patches/*</h2></div></div></div>
! 3307: <p>This directory contains files that are used by the
! 3308: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> command to
! 3309: modify the sources as distributed in the distribution file into a form
! 3310: that will compile and run perfectly on NetBSD. The files are applied
! 3311: successively in alphabetic order (as returned by a shell
! 3312: “<span class="quote">patches/patch-*</span>” glob expansion), so
! 3313: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">patch-aa</code> is applied before
! 3314: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">patch-ab</code>, etc.</p>
! 3315: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">patch-*</code> files should be in
! 3316: <span><strong class="command">diff -bu</strong></span> format, and apply without a fuzz to avoid
! 3317: problems. (To force patches to apply
! 3318: with fuzz you can set <code class="varname">PATCH_FUZZ_FACTOR=-F2</code>).
! 3319: Furthermore, do not put changes for more than one file into a single
! 3320: patch file, as this will make future modifications more difficult.</p>
! 3321: <p>Similar, a file should be patched at most once, not several times by
! 3322: several different patches. If a file needs several patches, they should
! 3323: be combined into one file.</p>
! 3324: <p>One important thing to mention is to pay attention that no RCS IDs
! 3325: get stored in the patch files, as these will cause problems when
! 3326: later checked into the NetBSD CVS tree. Use the
! 3327: <span><strong class="command">pkgdiff</strong></span> from the
! 3328: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdiff</code></a> package to avoid
! 3329: these problems.</p>
! 3330: <p>For even more automation, we recommend using <span><strong class="command">mkpatches</strong></span> from the same
! 3331: package to make a whole set of patches. You just have to backup files
! 3332: before you edit them to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">filename.orig</code>, e.g. with
! 3333: <span><strong class="command">cp -p filename filename.orig</strong></span> or, easier, by using
! 3334: <span><strong class="command">pkgvi</strong></span> again from the same package. If you upgrade a package
! 3335: this way, you can easily compare the new set of patches with the
! 3336: previously existing one with <span><strong class="command">patchdiff</strong></span>.</p>
! 3337: <p>When you have finished a package, remember to generate the checksums
! 3338: for the patch files by using the <span><strong class="command">make makepatchsum</strong></span>
! 3339: command, see <a href="#components.distinfo" title="8.2. distinfo">Section 8.2, “<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code>”</a>.</p>
! 3340: <p>When adding a patch that corrects a problem in the distfile (rather
! 3341: than e.g. enforcing pkgsrc's view of where man pages should go), send
! 3342: the patch as a bug report to the maintainer. This benefits
! 3343: non-pkgsrc users of the package, and usually enables removing
! 3344: the patch in future version.</p>
! 3345: <p>Patch files that are distributed by the author or other
! 3346: maintainers can be listed in
! 3347: <code class="varname">$PATCHFILES</code>. </p>
! 3348: <p>If it is desired to store any patches that should not be committed into
! 3349: pkgsrc, they can be kept outside the pkgsrc tree in the
! 3350: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">$LOCALPATCHES</code>
! 3351: directory. The directory tree there is expected to have the same
! 3352: “<span class="quote">category/package</span>” structure as pkgsrc, and patches are
! 3353: expected to be stored inside these dirs (also known as
! 3354: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">$LOCALPATCHES/$PKGPATH</code>). For
! 3355: example, if you want to keep a private patch for
! 3356: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/graphics/png</code>, keep
! 3357: it in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
! 3358: files in the named directory are expected to be patch files, and
! 3359: <span class="emphasis"><em>they are applied after pkgsrc patches are applied</em></span>.</p>
! 3360: </div>
! 3361: <div class="sect1" lang="en">
! 3362: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3363: <a name="other-mandatory-files"></a>8.4. Other mandatory files</h2></div></div></div>
! 3364: <div class="variablelist"><dl>
! 3365: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DESCR</code></span></dt>
! 3366: <dd><p>A multi-line description of the piece of software. This should include
! 3367: any credits where they are due. Please bear in mind that others do not
! 3368: share your sense of humour (or spelling idiosyncrasies), and that others
! 3369: will read everything that you write here.</p></dd>
! 3370: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code></span></dt>
! 3371: <dd><p>
! 3372: This file governs the files that are installed on your system: all the
! 3373: binaries, manual pages, etc. There are other directives which may be
! 3374: entered in this file, to control the creation and deletion of
! 3375: directories, and the location of inserted files.
! 3376: See <a href="#plist" title="Chapter 10. PLIST issues">Chapter 10, <i>PLIST issues</i></a> for more information. </p></dd>
! 3377: </dl></div>
! 3378: </div>
! 3379: <div class="sect1" lang="en">
! 3380: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3381: <a name="components.optional"></a>8.5. Optional files</h2></div></div></div>
! 3382: <div class="variablelist"><dl>
! 3383: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">INSTALL</code></span></dt>
! 3384: <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>.
! 3385: First time after package
! 3386: extraction and before files are moved in place, the second time after
! 3387: the files to install are moved in place. This can be used to do any
! 3388: custom procedures not possible with @exec commands in
! 3389: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>. See
! 3390: <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 <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>
! 3391: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DEINSTALL</code></span></dt>
! 3392: <dd><p>This script is executed before and after any files are removed. It is
! 3393: this script's responsibility to clean up any additional messy details
! 3394: around the package's installation, since all pkg_delete knows is how to
! 3395: delete the files created in the original distribution.
! 3396: 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>
! 3397: 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>
! 3398: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">MESSAGE</code></span></dt>
! 3399: <dd>
! 3400: <p>This file is displayed after installation of the package.
! 3401: Useful for things like legal notices on almost-free
! 3402: software and hints for updating config files after
! 3403: installing modules for apache, PHP etc.
! 3404: Please note that you can modify variables in it easily by using
! 3405: <code class="varname">MESSAGE_SUBST</code> in the package's
! 3406: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>:</p>
! 3407: <pre class="programlisting">
! 3408: MESSAGE_SUBST+= SOMEVAR="somevalue"
1.1 grant 3409: </pre>
1.75 ! rillig 3410: <p>replaces "${SOMEVAR}" with “<span class="quote">somevalue</span>” in
! 3411: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">MESSAGE</code>.</p>
! 3412: </dd>
! 3413: </dl></div>
! 3414: </div>
! 3415: <div class="sect1" lang="en">
! 3416: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3417: <a name="work-dir"></a>8.6. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">work*</code></h2></div></div></div>
! 3418: <p>When you type <span><strong class="command">make</strong></span>, the distribution files are
! 3419: unpacked into the directory denoted by
! 3420: <code class="varname">WRKDIR</code>. It can be removed by running
! 3421: <span><strong class="command">make clean</strong></span>. Besides the sources, this
! 3422: directory is also used to keep various timestamp files.
! 3423: The directory gets <span class="emphasis"><em>removed completely</em></span> on clean.
! 3424: The default is <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${.CURDIR}/work</code>
! 3425: or <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${.CURDIR}/work.${MACHINE_ARCH}</code>
! 3426: if <code class="varname">OBJMACHINE</code> is set.</p>
! 3427: </div>
! 3428: <div class="sect1" lang="en">
! 3429: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3430: <a name="files-dir"></a>8.7. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">files/*</code></h2></div></div></div>
! 3431: <p>If you have any files that you wish to be placed in the package prior
! 3432: to configuration or building, you could place these files here and use
! 3433: a “<span class="quote">${CP}</span>” command in the
! 3434: “<span class="quote">pre-configure</span>” target to achieve
! 3435: this. Alternatively, you could simply diff the file against
! 3436: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/dev/null</code> and use the patch mechanism to manage
! 3437: the creation of this file.</p>
! 3438: </div>
! 3439: </div>
! 3440: <div class="chapter" lang="en">
! 3441: <div class="titlepage"><div><div><h2 class="title">
! 3442: <a name="makefile"></a>Chapter 9. Programming in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s</h2></div></div></div>
! 3443: <div class="toc">
! 3444: <p><b>Table of Contents</b></p>
! 3445: <dl>
! 3446: <dt><span class="sect1"><a href="#makefile.variables">9.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> variables</a></span></dt>
! 3447: <dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">9.1.1. Naming conventions</a></span></dt></dl></dd>
! 3448: <dt><span class="sect1"><a href="#makefile.code">9.2. Code snippets</a></span></dt>
! 3449: <dd><dl>
! 3450: <dt><span class="sect2"><a href="#adding-to-list">9.2.1. Adding things to a list</a></span></dt>
! 3451: <dt><span class="sect2"><a href="#converting-internal-to-external">9.2.2. Converting an internal list into an external list</a></span></dt>
! 3452: <dt><span class="sect2"><a href="#passing-variable-to-shell">9.2.3. Passing variables to a shell command</a></span></dt>
! 3453: <dt><span class="sect2"><a href="#quoting-guideline">9.2.4. Quoting guideline</a></span></dt>
! 3454: <dt><span class="sect2"><a href="#bsd-make-bug-workaround">9.2.5. Workaround for a bug in BSD Make</a></span></dt>
! 3455: </dl></dd>
! 3456: </dl>
! 3457: </div>
! 3458: <p>Pkgsrc consists of many <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> fragments,
! 3459: each of which forms a well-defined part of the pkgsrc system. Using
! 3460: the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> system as a programming language for a big system
! 3461: like pkgsrc requires some discipline to keep the code correct and
! 3462: understandable.</p>
! 3463: <p>The basic ingredients for <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>
! 3464: programming are variables (which are actually macros) and shell
! 3465: commands. Among these shell commands may even be more complex ones
! 3466: like <a href="http://netbsd.gw.com/cgi-bin/man-cgi?awk+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">awk</span>(1)</span></a> programs. To make sure that every shell command runs
! 3467: as intended it is necessary to quote all variables correctly when they
! 3468: are used.</p>
! 3469: <p>This chapter describes some patterns, that appear quite often in
! 3470: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s, including the pitfalls that come along
! 3471: with them.</p>
! 3472: <div class="sect1" lang="en">
! 3473: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3474: <a name="makefile.variables"></a>9.1. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> variables</h2></div></div></div>
! 3475: <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> variables contain strings that
! 3476: can be processed using the five operators ``='', ``+='', ``?='',
! 3477: ``:='', and ``!='', which are described in the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man
! 3478: page.</p>
! 3479: <p>When a variable's value is parsed from a
! 3480: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, the hash character ``#'' and the
! 3481: backslash character ``\'' are handled specially. If a backslash is
! 3482: followed by a newline, any whitespace immediately in front of the
! 3483: backslash, the backslash, the newline, and any whitespace
! 3484: immediately behind the newline are replaced with a single space. A
! 3485: backslash character and an immediately following hash character are
! 3486: replaced with a single hash character. Otherwise, the backslash is
! 3487: passed as is. In a variable assignment, any hash character that is
! 3488: not preceded by a backslash starts a comment that continues upto the
! 3489: end of the logical line.</p>
! 3490: <p><span class="emphasis"><em>Note:</em></span> Because of this parsing algorithm
! 3491: the only way to create a variable consisting of a single backslash
! 3492: is using the ``!='' operator, for example: <code class="varname">BACKSLASH!=echo "\\"</code>.</p>
! 3493: <p>So far for defining variables. The other thing you can do with
! 3494: variables is evaluating them. A variable is evaluated when it is
! 3495: part of the right side of the ``:='' or the ``!='' operator, or
! 3496: directly before executing a shell command which the variable is part
! 3497: of. In all other cases, <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> performs lazy evaluation, that
! 3498: is, variables are not evaluated until there's no other way. The
! 3499: ``modifiers'' mentioned in the man page also evaluate the
! 3500: variable.</p>
! 3501: <p>Some of the modifiers split the string into words and then
! 3502: operate on the words, others operate on the string as a whole. When
! 3503: a string is split into words, it is split as you would expect
! 3504: it from <a href="http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">sh</span>(1)</span></a>.</p>
! 3505: <p>No rule without exception—the <span><strong class="command">.for</strong></span>
! 3506: loop does not follow the shell quoting rules but splits at sequences
! 3507: of whitespace.</p>
! 3508: <p>There are several types of variables that should be handled
! 3509: differently. Strings and two types of lists.</p>
! 3510: <div class="itemizedlist"><ul type="disc">
! 3511: <li><p><span class="emphasis"><em>Strings</em></span> can contain arbitrary
! 3512: characters. Nevertheless, you should restrict yourself to only
! 3513: using printable characters. Examples are
! 3514: <code class="varname">PREFIX</code> and
! 3515: <code class="varname">COMMENT</code>.</p></li>
! 3516: <li><p><span class="emphasis"><em>Internal lists</em></span> are lists that
! 3517: are never exported to any shell command. Their elements are
! 3518: separated by whitespace. Therefore, the elements themselves cannot
! 3519: have embedded whitespace. Any other characters are allowed.
! 3520: Internal lists can be used in <span><strong class="command">.for</strong></span> loops.
! 3521: Examples are <code class="varname">DEPENDS</code> and
! 3522: <code class="varname">BUILD_DEPENDS</code>.</p></li>
! 3523: <li><p><span class="emphasis"><em>External lists</em></span> are lists that
! 3524: may be exported to a shell command. Their elements can contain any
! 3525: characters, including whitespace. That's why they cannot be used
! 3526: in <span><strong class="command">.for</strong></span> loops. Examples are
! 3527: <code class="varname">DISTFILES</code> and
! 3528: <code class="varname">MASTER_SITES</code>.</p></li>
! 3529: </ul></div>
! 3530: <div class="sect2" lang="en">
! 3531: <div class="titlepage"><div><div><h3 class="title">
! 3532: <a name="makefile.variables.names"></a>9.1.1. Naming conventions</h3></div></div></div>
! 3533: <div class="itemizedlist"><ul type="disc">
! 3534: <li><p>All variable names starting with an underscore
! 3535: are reserved for use by the pkgsrc infrastructure. They shall
! 3536: not be used by package
! 3537: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s.</p></li>
! 3538: <li><p>In <span><strong class="command">.for</strong></span> loops you should use
! 3539: lowercase variable names for the iteration
! 3540: variables.</p></li>
! 3541: <li><p>All list variables should have a ``plural''
! 3542: name, e.g. <code class="varname">PKG_OPTIONS</code> or
! 3543: <code class="varname">DISTFILES</code>.</p></li>
! 3544: </ul></div>
! 3545: </div>
! 3546: </div>
! 3547: <div class="sect1" lang="en">
! 3548: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3549: <a name="makefile.code"></a>9.2. Code snippets</h2></div></div></div>
! 3550: <p>This section presents you with some code snippets you should
! 3551: use in your own code. If you don't find anything appropriate here,
! 3552: you should test your code and add it here.</p>
! 3553: <div class="sect2" lang="en">
! 3554: <div class="titlepage"><div><div><h3 class="title">
! 3555: <a name="adding-to-list"></a>9.2.1. Adding things to a list</h3></div></div></div>
! 3556: <pre class="programlisting">
! 3557: STRING= foo * bar `date`
! 3558: INT_LIST= # empty
! 3559: ANOTHER_INT_LIST= apache-[0-9]*:../../www/apache
! 3560: EXT_LIST= # empty
! 3561: ANOTHER_EXT_LIST= a=b c=d
1.1 grant 3562:
1.75 ! rillig 3563: INT_LIST+= ${STRING} # 1
! 3564: INT_LIST+= ${ANOTHER_INT_LIST} # 2
! 3565: EXT_LIST+= ${STRING:Q} # 3
! 3566: EXT_LIST+= ${ANOTHER_EXT_LIST} # 4
1.1 grant 3567: </pre>
1.75 ! rillig 3568: <p>When you add a string to an external list (example 3), it
! 3569: must be quoted. In all other cases, you must not add a quoting
! 3570: level. You must not merge internal and external lists, unless you
! 3571: are sure that all entries are correctly interpreted in both
! 3572: lists.</p>
! 3573: </div>
! 3574: <div class="sect2" lang="en">
! 3575: <div class="titlepage"><div><div><h3 class="title">
! 3576: <a name="converting-internal-to-external"></a>9.2.2. Converting an internal list into an external list</h3></div></div></div>
! 3577: <pre class="programlisting">
! 3578: EXT_LIST= # empty
! 3579: .for i in ${INT_LIST}
! 3580: EXT_LIST+= ${i:Q}""
! 3581: .endfor
1.1 grant 3582: </pre>
1.75 ! rillig 3583: <p>This code converts the internal list
! 3584: <code class="varname">INT_LIST</code> into the external list
! 3585: <code class="varname">EXT_LIST</code>. As the elements of an internal list
! 3586: are unquoted they must be quoted here. The reason for appending
! 3587: <code class="varname">""</code> is explained below.</p>
! 3588: </div>
! 3589: <div class="sect2" lang="en">
! 3590: <div class="titlepage"><div><div><h3 class="title">
! 3591: <a name="passing-variable-to-shell"></a>9.2.3. Passing variables to a shell command</h3></div></div></div>
! 3592: <pre class="programlisting">
! 3593: STRING= foo bar < > * `date` $$HOME ' "
! 3594: EXT_LIST= string=${STRING:Q} x=second\ item
1.1 grant 3595:
1.75 ! rillig 3596: all:
! 3597: echo ${STRING} # 1
! 3598: echo "${STRING}" # 2
! 3599: echo "${STRING:Q}" # 3
! 3600: echo ${STRING:Q} # 4
! 3601: echo x${STRING:Q} | sed 1s,.,, # 5
! 3602: env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
1.1 grant 3603: </pre>
1.75 ! rillig 3604: <p>Example 1 leads to a syntax error in the shell, as the
! 3605: characters are just copied.</p>
! 3606: <p>Example 2 leads to a syntax error too, and if you leave out
! 3607: the last " character from <code class="varname">${STRING}</code>,
! 3608: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?date+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">date</span>(1)</span></a> will be executed. The <code class="varname">$HOME</code> shell
! 3609: variable would be evaluated, too.</p>
! 3610: <p>Example 3 outputs each space character preceded by a
! 3611: backslash (or not), depending on the implementation of the
! 3612: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">echo</span>(1)</span></a> command.</p>
! 3613: <p>Example 4 handles correctly every string that does not start
! 3614: with a dash. In that case, the result depends on the
! 3615: implementation of the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">echo</span>(1)</span></a> command. As long as you can
! 3616: guarantee that your input does not start with a dash, this form is
! 3617: appropriate.</p>
! 3618: <p>Example 5 handles even the case of a leading dash
! 3619: correctly.</p>
! 3620: <p>The <code class="varname">EXT_LIST</code> does not need to be quoted
! 3621: because the quoting has already been done when adding elements to
! 3622: the list.</p>
! 3623: <p>As internal lists shall not be passed to the shell, there is
! 3624: no example for it.</p>
! 3625: </div>
! 3626: <div class="sect2" lang="en">
! 3627: <div class="titlepage"><div><div><h3 class="title">
! 3628: <a name="quoting-guideline"></a>9.2.4. Quoting guideline</h3></div></div></div>
! 3629: <p>There are many possible sources of wrongly quoted variables.
! 3630: This section lists some of the commonly known ones.</p>
! 3631: <div class="itemizedlist"><ul type="disc">
! 3632: <li>
! 3633: <p>Whenever you use the value of a list, think
! 3634: about what happens to leading or trailing whitespace. If the
! 3635: list is a well-formed shell expression, you can apply the
! 3636: <code class="varname">:M*</code> modifier to strip leading and trailing
! 3637: whitespace from each word. The <code class="varname">:M</code> operator
! 3638: first splits its argument according to the rules of the shell,
! 3639: and then creates a new list consisting of all words that match
! 3640: the shell glob expression <code class="varname">*</code>, that is: all.
! 3641: One class of situations where this is needed is when adding a
! 3642: variable like <code class="varname">CPPFLAGS</code> to
! 3643: <code class="varname">CONFIGURE_ARGS</code>. If the configure script
! 3644: invokes other configure scripts, it strips the leading and
! 3645: trailing whitespace from the variable and then passes it to the
! 3646: other configure scripts. But these configure scripts expect the
! 3647: (child) <code class="varname">CPPFLAGS</code> variable to be the same as
! 3648: the parent <code class="varname">CPPFLAGS</code>. That's why we better
! 3649: pass the <code class="varname">CPPFLAGS</code> value properly trimmed. And
! 3650: here is how we do it:</p>
! 3651: <pre class="programlisting">
! 3652: CPPFLAGS= # empty
! 3653: CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX:Q}\"
! 3654: CPPFLAGS+= ${MY_CPPFLAGS}
1.1 grant 3655:
1.75 ! rillig 3656: CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
1.1 grant 3657:
1.75 ! rillig 3658: all:
! 3659: echo x${CPPFLAGS:Q}x # leading and trailing whitespace
! 3660: echo x${CONFIGURE_ARGS}x # properly trimmed
1.1 grant 3661: </pre>
1.75 ! rillig 3662: </li>
! 3663: <li><p>The example above contains one bug: The
! 3664: <code class="varname">${PREFIX}</code> is a properly quoted shell
! 3665: expression, but there is the C compiler after it, which also
! 3666: expects a properly quoted string (this time in C syntax). The
! 3667: version above is therefore only correct if
! 3668: <code class="varname">${PREFIX}</code> does not have embedded backslashes
! 3669: or double quotes. If you want to allow these, you have to add
! 3670: another layer of quoting to each variable that is used as a C
! 3671: string literal. You cannot use the <code class="varname">:Q</code>
! 3672: operator for it, as this operator only works for the
! 3673: shell.</p></li>
! 3674: <li>
! 3675: <p>Whenever a variable can be empty, the
! 3676: <code class="varname">:Q</code> operator can have surprising results. Here
! 3677: are two completely different cases which can be solved with the
! 3678: same trick.</p>
! 3679: <pre class="programlisting">
! 3680: EMPTY= # empty
! 3681: empty_test:
! 3682: for i in a ${EMPTY:Q} c; do \
! 3683: echo "$$i"; \
! 3684: done
1.1 grant 3685:
1.75 ! rillig 3686: for_test:
! 3687: .for i in a:\ a:\test.txt
! 3688: echo ${i:Q}
! 3689: echo "foo"
! 3690: .endfor
1.1 grant 3691: </pre>
1.75 ! rillig 3692: <p>The first example will only print two of the three lines
! 3693: we might have expected. This is because
! 3694: <code class="varname">${EMPTY:Q}</code> expands to the empty string, which
! 3695: the shell cannot see. The workaround is to write
! 3696: <code class="varname">${EMPTY:Q}""</code>. This pattern can be often found
! 3697: as <code class="varname">${TEST} -z ${VAR:Q}</code> or as <code class="varname">${TEST}
! 3698: -f ${FNAME:Q}</code> (both of these are wrong).</p>
! 3699: <p>The second example will only print three lines instead of
! 3700: four. The first line looks like <code class="varname">a:\ echo foo</code>.
! 3701: This is because the backslash of the value
! 3702: <code class="varname">a:\</code> is interpreted as a line-continuation by
! 3703: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>, which makes the second line the arguments of the
! 3704: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">echo</span>(1)</span></a> command from the first line. To avoid this, write
! 3705: <code class="varname">${i:Q}""</code>.</p>
! 3706: </li>
! 3707: </ul></div>
! 3708: </div>
! 3709: <div class="sect2" lang="en">
! 3710: <div class="titlepage"><div><div><h3 class="title">
! 3711: <a name="bsd-make-bug-workaround"></a>9.2.5. Workaround for a bug in BSD Make</h3></div></div></div>
! 3712: <p>The pkgsrc bmake program does not handle the following
! 3713: assignment correctly. In case <code class="varname">_othervar_</code>
! 3714: contains a ``-'' character, one of the closing braces is included
! 3715: in <code class="varname">${VAR}</code> after this code executes.</p>
! 3716: <pre class="programlisting">
! 3717: VAR:= ${VAR:N${_othervar_:C/-//}}
1.1 grant 3718: </pre>
1.75 ! rillig 3719: <p>For a more complex code snippet and a workaround, see the
! 3720: package <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/regress/make-quoting/README.html" target="_top"><code xmlns="" class="filename">regress/make-quoting</code></a>, testcase
! 3721: <code class="varname">bug1</code>.</p>
! 3722: </div>
! 3723: </div>
! 3724: </div>
! 3725: <div class="chapter" lang="en">
! 3726: <div class="titlepage"><div><div><h2 class="title">
! 3727: <a name="plist"></a>Chapter 10. PLIST issues</h2></div></div></div>
! 3728: <div class="toc">
! 3729: <p><b>Table of Contents</b></p>
! 3730: <dl>
! 3731: <dt><span class="sect1"><a href="#rcs-id">10.1. RCS ID</a></span></dt>
! 3732: <dt><span class="sect1"><a href="#automatic-plist-generation">10.2. Semi-automatic <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> generation</a></span></dt>
! 3733: <dt><span class="sect1"><a href="#print-PLIST">10.3. Tweaking output of <span><strong class="command">make print-PLIST</strong></span></a></span></dt>
! 3734: <dt><span class="sect1"><a href="#plist.misc">10.4. Variable substitution in PLIST</a></span></dt>
! 3735: <dt><span class="sect1"><a href="#manpage-compression">10.5. Man page compression</a></span></dt>
! 3736: <dt><span class="sect1"><a href="#using-PLIST_SRC">10.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
! 3737: <dt><span class="sect1"><a href="#platform-specific-plist">10.7. Platform-specific and differing PLISTs</a></span></dt>
! 3738: <dt><span class="sect1"><a href="#faq.common-dirs">10.8. Sharing directories between packages</a></span></dt>
! 3739: </dl>
! 3740: </div>
! 3741: <p> The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file contains a package's
! 3742: “<span class="quote">packing list</span>”, i.e. a list of files that belong to
! 3743: the package (relative to the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}</code>
! 3744: directory it's been installed in) plus some additional statements
! 3745: - see the <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> man page for a full list.
! 3746: This chapter addresses some issues that need attention when
! 3747: dealing with the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file (or files, see
! 3748: below!).</p>
! 3749: <div class="sect1" lang="en">
! 3750: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3751: <a name="rcs-id"></a>10.1. RCS ID</h2></div></div></div>
! 3752: <p>
! 3753: Be sure to add a RCS ID line as the first thing in any
! 3754: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file you write:
! 3755: </p>
! 3756: <pre class="programlisting">
! 3757: @comment $NetBSD$
1.55 rillig 3758: </pre>
1.75 ! rillig 3759: </div>
! 3760: <div class="sect1" lang="en">
! 3761: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3762: <a name="automatic-plist-generation"></a>10.2. Semi-automatic <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> generation</h2></div></div></div>
! 3763: <p>You can use the <span><strong class="command">make print-PLIST</strong></span> command
! 3764: to output a PLIST that matches any new files since the package
! 3765: was extracted. See <a href="#build.helpful-targets" title="14.16. Other helpful targets">Section 14.16, “Other helpful targets”</a> for
! 3766: more information on this target.</p>
! 3767: </div>
! 3768: <div class="sect1" lang="en">
! 3769: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3770: <a name="print-PLIST"></a>10.3. Tweaking output of <span><strong class="command">make print-PLIST</strong></span></h2></div></div></div>
! 3771: <p> If you have used any of the *-dirs packages, as explained in
! 3772: <a href="#faq.common-dirs" title="10.8. Sharing directories between packages">Section 10.8, “Sharing directories between packages”</a>, you may have noticed that
! 3773: <span><strong class="command">make print-PLIST</strong></span> outputs a set of
! 3774: <code class="varname">@comment</code>s instead of real
! 3775: <code class="varname">@dirrm</code> lines. You can also do this for
! 3776: specific directories and files, so that the results of that
! 3777: command are very close to reality. This helps <span class="emphasis"><em>a
! 3778: lot</em></span> during the update of packages. </p>
! 3779: <p> The <code class="varname">PRINT_PLIST_AWK</code> variable takes a set
! 3780: of AWK patterns and actions that are used to filter the output of
! 3781: print-PLIST. You can <span class="emphasis"><em>append</em></span> any chunk of AWK
! 3782: scripting you like to it, but be careful with quoting. </p>
! 3783: <p> For example, to get all files inside the
! 3784: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libdata/foo</code> directory removed from the
! 3785: resulting PLIST:</p>
! 3786: <pre class="programlisting">
! 3787: PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
1.55 rillig 3788: </pre>
1.75 ! rillig 3789: <p> And to get all the <code class="varname">@dirrm</code> lines referring
! 3790: to a specific (shared) directory converted to
! 3791: <code class="varname">@comment</code>s: </p>
! 3792: <pre class="programlisting">
! 3793: PRINT_PLIST_AWK+= /^@dirrm share\/specific/ { print "@comment " $$0; next; }
1.51 rillig 3794: </pre>
1.75 ! rillig 3795: </div>
! 3796: <div class="sect1" lang="en">
! 3797: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3798: <a name="plist.misc"></a>10.4. Variable substitution in PLIST</h2></div></div></div>
! 3799: <p>
! 3800: A number of variables are substituted automatically in PLISTs
! 3801: when a package is installed on a system. This includes the
! 3802: following variables: </p>
! 3803: <div class="variablelist"><dl>
! 3804: <dt><span class="term"><code class="varname">${MACHINE_ARCH}</code>, <code class="varname">${MACHINE_GNU_ARCH}</code></span></dt>
! 3805: <dd>
! 3806: <p>Some packages like emacs and perl embed information
! 3807: about which architecture they were built on into the
! 3808: pathnames where they install their files. To handle this
! 3809: case, PLIST will be preprocessed before actually used, and
! 3810: the symbol
! 3811: “<span class="quote"><code class="varname">${MACHINE_ARCH}</code></span>” will be
! 3812: replaced by what <span><strong class="command">uname -p</strong></span> gives. The
! 3813: same is done if the string
! 3814: <code class="varname">${MACHINE_GNU_ARCH}</code> is embedded in
! 3815: PLIST somewhere - use this on packages that have GNU
! 3816: autoconf-created configure scripts.</p>
! 3817: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 3818: <h3 class="title">Legacy note</h3>
! 3819: <p>There used to be a symbol
! 3820: “<span class="quote"><code class="varname">$ARCH</code></span>” that
! 3821: was replaced by the output of <span><strong class="command">uname
! 3822: -m</strong></span>, but that's no longer supported and has
! 3823: been removed.</p>
! 3824: </div>
! 3825: </dd>
! 3826: <dt><span class="term"><code class="varname">${OPSYS}</code>, <code class="varname">${LOWER_OPSYS}</code>, <code class="varname">${OS_VERSION}</code></span></dt>
! 3827: <dd>
! 3828: <p>Some packages want to embed the OS name and version
! 3829: into some paths. To do this, use these variables in the
! 3830: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>:
! 3831: </p>
! 3832: <div class="itemizedlist"><ul type="disc">
! 3833: <li><p><code class="varname">${OPSYS}</code> - output of “<span class="quote"><span><strong class="command">uname -s</strong></span></span>”</p></li>
! 3834: <li><p><code class="varname">${LOWER_OPSYS}</code> - lowercase common name (eg. “<span class="quote">solaris</span>”)</p></li>
! 3835: <li><p><code class="varname">${OS_VERSION}</code> - “<span class="quote"><span><strong class="command">uname -r</strong></span></span>”</p></li>
! 3836: </ul></div>
! 3837: </dd>
! 3838: </dl></div>
! 3839: <p> For a complete list of values which are replaced by
! 3840: default, please look in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.pkg.mk</code> (and
! 3841: search for <span class="emphasis"><em>PLIST_SUBST</em></span>). </p>
! 3842: <p> If you want to change other variables not listed above, you
! 3843: can add variables and their expansions to this variable in the
! 3844: following way, similar to <code class="varname">MESSAGE_SUBST</code> (see <a href="#components.optional" title="8.5. Optional files">Section 8.5, “Optional files”</a>): </p>
! 3845: <pre class="programlisting">
! 3846: PLIST_SUBST+= SOMEVAR="somevalue"
1.1 grant 3847: </pre>
1.75 ! rillig 3848: <p>This replaces all occurrences of “<span class="quote">${SOMEVAR}</span>”
! 3849: in the PLIST with “<span class="quote">somevalue</span>”. </p>
! 3850: </div>
! 3851: <div class="sect1" lang="en">
! 3852: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3853: <a name="manpage-compression"></a>10.5. Man page compression</h2></div></div></div>
! 3854: <p>Man pages should be installed in compressed form if
! 3855: <code class="varname">MANZ</code> is set (in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.own.mk</code>),
! 3856: and uncompressed otherwise. To handle this in the
! 3857: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file, the suffix “<span class="quote">.gz</span>” is
! 3858: appended/removed automatically for man pages according to
! 3859: <code class="varname">MANZ</code> and <code class="varname">MANCOMPRESSED</code> being set
! 3860: or not, see above for details. This modification of the
! 3861: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file is done on a copy of it, not
! 3862: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> itself.</p>
! 3863: </div>
! 3864: <div class="sect1" lang="en">
! 3865: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3866: <a name="using-PLIST_SRC"></a>10.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></h2></div></div></div>
! 3867: <p>To use one or more files as source for the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> used
! 3868: in generating the binary package, set the variable
! 3869: <code class="varname">PLIST_SRC</code> to the names of that file(s).
! 3870: The files are later concatenated using <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cat+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cat</span>(1)</span></a>, and order of things is
! 3871: important.</p>
! 3872: </div>
! 3873: <div class="sect1" lang="en">
! 3874: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3875: <a name="platform-specific-plist"></a>10.7. Platform-specific and differing PLISTs</h2></div></div></div>
! 3876: <p>Some packages decide to install a different set of files based on
! 3877: the operating system being used. These differences can be
! 3878: automatically handled by using the following files:</p>
! 3879: <div class="itemizedlist"><ul type="disc">
! 3880: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST.common</code></p></li>
! 3881: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST.${OPSYS}</code></p></li>
! 3882: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST.${MACHINE_ARCH}</code></p></li>
! 3883: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST.${OPSYS}-${MACHINE_ARCH}</code></p></li>
! 3884: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST.common_end</code></p></li>
! 3885: </ul></div>
! 3886: </div>
! 3887: <div class="sect1" lang="en">
! 3888: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3889: <a name="faq.common-dirs"></a>10.8. Sharing directories between packages</h2></div></div></div>
! 3890: <p> A “<span class="quote">shared directory</span>” is a directory where
! 3891: multiple (and unrelated) packages install files. These
! 3892: directories are problematic because you have to add special tricks
! 3893: in the PLIST to conditionally remove them, or have some
! 3894: centralized package handle them. </p>
! 3895: <p> Within pkgsrc, you'll find both approaches. If a directory
! 3896: is shared by a few unrelated packages, it's often not worth to add
! 3897: an extra package to remove it. Therefore, one simply does:
! 3898: </p>
! 3899: <pre class="programlisting">
! 3900: @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE}
1.1 grant 3901: </pre>
1.75 ! rillig 3902: <p> in the PLISTs of all affected packages, instead of the
! 3903: regular "@dirrm" line. </p>
! 3904: <p> However, if the directory is shared across many packages, two
! 3905: different solutions are available: </p>
! 3906: <div class="orderedlist"><ol type="1">
! 3907: <li><p> If the packages have a common dependency, the directory
! 3908: can be removed in that. For example, see
! 3909: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/textproc/scrollkeeper/README.html" target="_top"><code xmlns="" class="filename">textproc/scrollkeeper</code></a>, which
! 3910: removes the shared directory
! 3911: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/omf</code>. </p></li>
! 3912: <li><p> If the packages using the directory are not related at
! 3913: all (they have no common dependencies), a *-dirs package is
! 3914: used. </p></li>
! 3915: </ol></div>
! 3916: <p> From now on, we'll discuss the second solution. To get an
! 3917: idea of the *-dirs packages available, issue: </p>
! 3918: <pre class="programlisting">
! 3919: <code class="prompt">%</code> cd .../pkgsrc
! 3920: <code class="prompt">%</code> ls -d */*-dirs
1.1 grant 3921: </pre>
1.75 ! rillig 3922: <p> Their use from other packages is very simple. The
! 3923: <code class="varname">USE_DIRS</code> variable takes a list of package names
! 3924: (without the “<span class="quote">-dirs</span>” part) together with the required
! 3925: version number (always pick the latest one when writing new
! 3926: packages). </p>
! 3927: <p> For example, if a package installs files under
! 3928: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/applications</code>, it should have the
! 3929: following line in it:
! 3930: </p>
! 3931: <pre class="programlisting">
! 3932: USE_DIRS+= xdg-1.1
1.1 grant 3933: </pre>
1.75 ! rillig 3934: <p> After regenerating the PLIST using <span><strong class="command">make
! 3935: print-PLIST</strong></span>, you should get the right (commented out)
! 3936: lines. </p>
! 3937: <p> Note that even if your package is using
! 3938: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">$X11BASE</code>, it must not depend on the
! 3939: *-x11-dirs packages. Just specify the name without that part and
! 3940: pkgsrc (in particular, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/dirs.mk</code>) will take
! 3941: care of it. </p>
! 3942: </div>
! 3943: </div>
! 3944: <div class="chapter" lang="en">
! 3945: <div class="titlepage"><div><div><h2 class="title">
! 3946: <a name="buildlink"></a>Chapter 11. Buildlink methodology</h2></div></div></div>
! 3947: <div class="toc">
! 3948: <p><b>Table of Contents</b></p>
! 3949: <dl>
! 3950: <dt><span class="sect1"><a href="#converting-to-buildlink3">11.1. Converting packages to use buildlink3</a></span></dt>
! 3951: <dt><span class="sect1"><a href="#creating-buildlink3.mk">11.2. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 3952: <dd><dl>
! 3953: <dt><span class="sect2"><a href="#anatomy-of-bl3">11.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
! 3954: <dt><span class="sect2"><a href="#updating-buildlink-depends">11.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</a></span></dt>
! 3955: </dl></dd>
! 3956: <dt><span class="sect1"><a href="#writing-builtin.mk">11.3. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> files</a></span></dt>
! 3957: <dd><dl>
! 3958: <dt><span class="sect2"><a href="#anatomy-of-builtin.mk">11.3.1. Anatomy of a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file</a></span></dt>
! 3959: <dt><span class="sect2"><a href="#native-or-pkgsrc-preference">11.3.2. Global preferences for native or pkgsrc software</a></span></dt>
! 3960: </dl></dd>
! 3961: </dl>
! 3962: </div>
! 3963: <p>Buildlink is a framework in pkgsrc that controls what headers and libraries
! 3964: are seen by a package's configure and build processes. This is implemented
! 3965: in a two step process:</p>
! 3966: <div class="orderedlist"><ol type="1">
! 3967: <li><p>Symlink headers and libraries for dependencies into
! 3968: <code class="varname">BUILDLINK_DIR</code>, which by default is a subdirectory
! 3969: of <code class="varname">WRKDIR</code>.</p></li>
! 3970: <li><p>Create wrapper scripts that are used in place of the normal compiler
! 3971: tools that translate <code class="option">-I${LOCALBASE}/include</code> and
! 3972: <code class="option">-L${LOCALBASE}/lib</code> into references to
! 3973: <code class="varname">BUILDLINK_DIR</code>. The wrapper scripts also make
! 3974: native compiler on some operating systems look like GCC, so that
! 3975: packages that expect GCC won't require modifications to build with
! 3976: those native compilers.</p></li>
! 3977: </ol></div>
! 3978: <p>This normalizes the environment in which a package is built so that the
! 3979: package may be built consistently despite what other software may be
! 3980: installed. Please note that the normal system header and library paths,
! 3981: e.g. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/include</code>,
! 3982: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/lib</code>, etc., are always searched -- buildlink3 is
! 3983: designed to insulate the package build from non-system-supplied
! 3984: software. </p>
! 3985: <div class="sect1" lang="en">
! 3986: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 3987: <a name="converting-to-buildlink3"></a>11.1. Converting packages to use buildlink3</h2></div></div></div>
! 3988: <p>The process of converting packages to use the buildlink3
! 3989: framework (“<span class="quote">bl3ifying</span>”) is fairly straightforward.
! 3990: The things to keep in mind are:</p>
! 3991: <div class="orderedlist"><ol type="1">
! 3992: <li><p> Ensure that the build always calls the wrapper scripts
! 3993: instead of the actual toolchain. Some packages are tricky,
! 3994: and the only way to know for sure is the check
! 3995: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKDIR}/.work.log</code> to see if the
! 3996: wrappers are being invoked. </p></li>
! 3997: <li><p> Don't override <code class="varname">PREFIX</code> from within
! 3998: the package Makefile, e.g. Java VMs, standalone shells,
! 3999: etc., because the code to symlink files into
! 4000: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code> looks for files
! 4001: relative to “<span class="quote">pkg_info -qp <em class="replaceable"><code>pkgname</code></em></span>”.
! 4002: </p></li>
! 4003: <li><p> Remember that <span class="emphasis"><em>only</em></span> the
! 4004: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files that you list in a
! 4005: package's Makefile are added as dependencies for that package.
! 4006: </p></li>
! 4007: </ol></div>
! 4008: <p> If a dependency on a particular package is required for its libraries and
! 4009: headers, then we replace: </p>
! 4010: <pre class="programlisting">
! 4011: DEPENDS+= foo>=1.1.0:../../category/foo
1.1 grant 4012: </pre>
1.75 ! rillig 4013: <p>with</p>
! 4014: <pre class="programlisting">
! 4015: .include "../../category/foo/buildlink3.mk"
1.1 grant 4016: </pre>
1.75 ! rillig 4017: <p>The buildlink3.mk files usually define the required dependencies.
! 4018: If you need a newer version of the dependency when using buildlink3.mk
! 4019: files, then you can define it in your Makefile; for example:
! 4020: </p>
! 4021: <pre class="programlisting">
! 4022: BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0
! 4023: .include "../../category/foo/buildlink3.mk"
1.1 grant 4024: </pre>
1.75 ! rillig 4025: <p>There are several <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4026: files in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk</code>
! 4027: that handle special package issues:</p>
! 4028: <div class="itemizedlist"><ul type="disc">
! 4029: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bdb.buildlink3.mk</code> chooses either
! 4030: the native or a pkgsrc Berkeley DB implementation based on
! 4031: the values of <code class="varname">BDB_ACCEPTED</code> and
! 4032: <code class="varname">BDB_DEFAULT</code>.</p></li>
! 4033: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">curses.buildlink3.mk</code>: If the system
! 4034: comes with neither Curses nor NCurses, this will take care
! 4035: to install the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/ncurses/README.html" target="_top"><code xmlns="" class="filename">devel/ncurses</code></a> package.</p></li>
! 4036: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">krb5.buildlink3.mk</code> uses the value
! 4037: of <code class="varname">KRB5_ACCEPTED</code> to choose between
! 4038: adding a dependency on Heimdal or MIT-krb5 for packages that
! 4039: require a Kerberos 5 implementation.</p></li>
! 4040: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">motif.buildlink3.mk</code> checks
! 4041: for a system-provided
! 4042: Motif installation or adds a dependency on <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/lesstif/README.html" target="_top"><code xmlns="" class="filename">x11/lesstif</code></a> or
! 4043: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/openmotif/README.html" target="_top"><code xmlns="" class="filename">x11/openmotif</code></a>.</p></li>
! 4044: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">oss.buildlink3.mk</code> defines several
! 4045: variables that may be used by packages that use the
! 4046: Open Sound System (OSS) API.</p></li>
! 4047: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pgsql.buildlink3.mk</code> will accept
! 4048: either Postgres 7.3 or 7.4, whichever is found installed. See
! 4049: the file for more information. </p></li>
! 4050: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pthread.buildlink3.mk</code> uses the value of
! 4051: <code class="varname">PTHREAD_OPTS</code> and checks for native pthreads or adds
! 4052: a dependency on <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/pth/README.html" target="_top"><code xmlns="" class="filename">devel/pth</code></a> as needed.</p></li>
! 4053: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">xaw.buildlink3.mk</code> uses the value of
! 4054: <code class="varname">XAW_TYPE</code> to choose a particular Athena widgets
! 4055: library.</p></li>
! 4056: </ul></div>
! 4057: <p>The comments in those <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4058: files provide a more complete
! 4059: description of how to use them properly.</p>
! 4060: </div>
! 4061: <div class="sect1" lang="en">
! 4062: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4063: <a name="creating-buildlink3.mk"></a>11.2. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</h2></div></div></div>
! 4064: <p> A package's <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file is
! 4065: included by Makefiles to indicate the need to compile and link
! 4066: against header files and libraries provided by the package. A
! 4067: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file should always provide
! 4068: enough information to add the correct type of dependency
! 4069: relationship and include any other
! 4070: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files that it needs to find
! 4071: headers and libraries that it needs in turn.</p>
! 4072: <p> To generate an initial <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4073: file for further editing, Rene Hexel's <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/createbuildlink/README.html" target="_top"><code xmlns="" class="filename">pkgtools/createbuildlink</code></a>
! 4074: package is highly recommended. For most packages, the following
! 4075: command will generate a good starting point for
! 4076: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files:</p>
! 4077: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd pkgsrc/<em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>pkgdir</code></em>
! 4078: <code class="prompt">%</code> createbuildlink >buildlink3.mk</code></strong></pre>
! 4079: <div class="sect2" lang="en">
! 4080: <div class="titlepage"><div><div><h3 class="title">
! 4081: <a name="anatomy-of-bl3"></a>11.2.1. Anatomy of a buildlink3.mk file</h3></div></div></div>
! 4082: <p>The following real-life example
! 4083: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> is taken
! 4084: from <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/graphics/tiff</code>:</p>
! 4085: <pre class="programlisting">
! 4086: # $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $
1.1 grant 4087:
1.75 ! rillig 4088: BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH}+
! 4089: TIFF_BUILDLINK3_MK:= ${TIFF_BUILDLINK3_MK}+
1.1 grant 4090:
1.75 ! rillig 4091: .if !empty(BUILDLINK_DEPTH:M+)
! 4092: BUILDLINK_DEPENDS+= tiff
! 4093: .endif
1.1 grant 4094:
1.75 ! rillig 4095: BUILDLINK_PACKAGES:= ${BUILDLINK_PACKAGES:Ntiff}
! 4096: BUILDLINK_PACKAGES+= tiff
1.1 grant 4097:
1.75 ! rillig 4098: .if !empty(TIFF_BUILDLINK3_MK:M+)
! 4099: BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1
! 4100: BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
! 4101: .endif # TIFF_BUILDLINK3_MK
1.1 grant 4102:
1.75 ! rillig 4103: .include "../../devel/zlib/buildlink3.mk"
! 4104: .include "../../graphics/jpeg/buildlink3.mk"
1.1 grant 4105:
1.75 ! rillig 4106: BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH:S/+$//}
1.1 grant 4107: </pre>
1.75 ! rillig 4108: <p> The header and footer manipulate
! 4109: <code class="varname">BUILDLINK_DEPTH</code>, which is common across all
! 4110: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files and is used to track
! 4111: at what depth we are including
! 4112: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files.</p>
! 4113: <p> The first section controls if the dependency on
! 4114: <em class="replaceable"><code>pkg</code></em> is added.
! 4115: <code class="varname">BUILDLINK_DEPENDS</code> is the global list of
! 4116: packages for which dependencies are added by
! 4117: buildlink3.</p>
! 4118: <p> The second section advises pkgsrc that the
! 4119: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file for
! 4120: <em class="replaceable"><code>pkg</code></em> has been included at some point.
! 4121: <code class="varname">BUILDLINK_PACKAGES</code> is the global list of
! 4122: packages for which <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files
! 4123: have been included. It must <span class="emphasis"><em>always</em></span> be
! 4124: appended to within a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4125: file. </p>
! 4126: <p> The third section is protected from multiple inclusion
! 4127: and controls how the dependency on <em class="replaceable"><code>pkg</code></em> is
! 4128: added. Several important variables are set in the section:
! 4129: </p>
! 4130: <div class="itemizedlist"><ul type="disc">
! 4131: <li><p> <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4132: is the actual dependency recorded in the installed
! 4133: package; this should always be set using
! 4134: <span><strong class="command">+=</strong></span> to ensure that
! 4135: we're appending to any pre-existing list of values. This
! 4136: variable should be set to the first version of the
! 4137: package that had an API change.
! 4138: </p></li>
! 4139: <li><p> <code class="varname">BUILDLINK_PKGSRCDIR.<em class="replaceable"><code>pkg</code></em></code>
! 4140: is the location of the <em class="replaceable"><code>pkg</code></em>
! 4141: pkgsrc directory.</p></li>
! 4142: <li><p>
! 4143: <code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
! 4144: (not shown above) controls whether we use
! 4145: <code class="varname">BUILD_DEPENDS</code> or
! 4146: <code class="varname">DEPENDS</code> to add the dependency on
! 4147: <em class="replaceable"><code>pkg</code></em>.
! 4148: The build dependency is selected by setting
! 4149: <code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
! 4150: to “<span class="quote">build</span>”. By default, the
! 4151: full dependency is used.
! 4152: </p></li>
! 4153: <li><p>
! 4154: <code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code>
! 4155: and
! 4156: <code class="varname">BUILDLINK_LIBDIRS.<em class="replaceable"><code>pkg</code></em></code>
! 4157: (not shown above) are lists of subdirectories of
! 4158: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
! 4159: to add to the header and library search paths. These
! 4160: default to “<span class="quote">include</span>” and “<span class="quote">lib</span>”
! 4161: respectively. </p></li>
! 4162: <li><p>
! 4163: <code class="varname">BUILDLINK_CPPFLAGS.<em class="replaceable"><code>pkg</code></em></code>
! 4164: (not shown above) is the list of preprocessor flags to add
! 4165: to <code class="varname">CPPFLAGS</code>, which are passed on to the
! 4166: configure and build phases. The “<span class="quote">-I</span>” option
! 4167: should be avoided and instead be handled using
! 4168: <code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code> as
! 4169: above.</p></li>
! 4170: </ul></div>
! 4171: <p> The following variables are all optionally defined within
! 4172: this second section (protected against multiple inclusion) and
! 4173: control which package files are symlinked into
! 4174: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code> and how their names are
! 4175: transformed during the symlinking: </p>
! 4176: <div class="itemizedlist"><ul type="disc">
! 4177: <li><p>
! 4178: <code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>
! 4179: (not shown above) is a shell glob pattern relative to
! 4180: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
! 4181: to be symlinked into
! 4182: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code>,
! 4183: e.g. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">include/*.h</code>. </p></li>
! 4184: <li><p>
! 4185: <code class="varname">BUILDLINK_FILES_CMD.<em class="replaceable"><code>pkg</code></em></code>
! 4186: (not shown above) is a shell pipeline that
! 4187: outputs to stdout a list of files relative to
! 4188: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>.
! 4189: The resulting files are to be symlinked
! 4190: into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code>. By default,
! 4191: this takes the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">+CONTENTS</code> of a
! 4192: <em class="replaceable"><code>pkg</code></em> and filters it through
! 4193: <code class="varname">${BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em>}</code>.
! 4194: </p></li>
! 4195: <li><p>
! 4196: <code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
! 4197: (not shown above) is a filter command that filters
! 4198: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">+CONTENTS</code> input into a list of files
! 4199: relative to
! 4200: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
! 4201: on stdout. By default for overwrite packages,
! 4202: <code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
! 4203: outputs the contents of the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">include</code>
! 4204: and <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">lib</code> directories in the package
! 4205: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">+CONTENTS</code>, and for pkgviews packages,
! 4206: it outputs any libtool archives in
! 4207: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">lib</code> directories.
! 4208: </p></li>
! 4209: <li><p>
! 4210: <code class="varname">BUILDLINK_TRANSFORM.<em class="replaceable"><code>pkg</code></em></code>
! 4211: (not shown above) is a list of sed arguments used to
! 4212: transform the name of the source filename into a
! 4213: destination filename, e.g. <span><strong class="command">-e
! 4214: "s|/curses.h|/ncurses.h|g"</strong></span>.
! 4215: </p></li>
! 4216: </ul></div>
! 4217: <p> The last section includes any
! 4218: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> needed for
! 4219: <em class="replaceable"><code>pkg</code></em>'s library dependencies.
! 4220: Including these <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files
! 4221: means that the headers and libraries for these
! 4222: dependencies are also symlinked into
! 4223: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code>
! 4224: whenever the <em class="replaceable"><code>pkg</code></em>
! 4225: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4226: file is included.
! 4227: </p>
! 4228: </div>
! 4229: <div class="sect2" lang="en">
! 4230: <div class="titlepage"><div><div><h3 class="title">
! 4231: <a name="updating-buildlink-depends"></a>11.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files</h3></div></div></div>
! 4232: <p>
! 4233: The situation that requires increasing the dependency listed in
! 4234: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4235: after a package update is when the API or interface to the
! 4236: header files change.</p>
! 4237: <p> In this case,
! 4238: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4239: should be adjusted to require at least the new package
! 4240: version. In some cases, the packages that depend on this new
! 4241: version may need their <code class="varname">PKGREVISION</code>s
! 4242: increased and, if they have <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 4243: files, their
! 4244: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4245: adjusted, too. This is needed so pkgsrc will require the
! 4246: correct package dependency and not settle for an older one
! 4247: when building the source.</p>
! 4248: <p>
! 4249: <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4250: should be increased when the binary interface or sonames
! 4251: (major number of the library version) of any installed
! 4252: shared libraries change. This is needed so that binary
! 4253: packages made using it will require the correct package
! 4254: dependency and not settle for an older one which will not
! 4255: contain the necessary shared libraries. </p>
! 4256: <p>
! 4257: See <a href="#dependencies" title="16.1.4. Handling dependencies">Section 16.1.4, “Handling dependencies”</a> for
! 4258: more information about dependencies on other packages,
! 4259: including the <code class="varname">BUILDLINK_ABI_DEPENDS</code> and
! 4260: <code class="varname">ABI_DEPENDS</code> definitions. </p>
! 4261: <p> Please take careful consideration before adjusting
! 4262: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4263: or
! 4264: <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4265: as we don't want to cause unneeded package deletions and
! 4266: rebuilds. In many cases, new versions of packages work just
! 4267: fine with older dependencies.</p>
! 4268: <p>
! 4269: Also it is not needed to set
! 4270: <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
! 4271: when it is identical to
! 4272: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>. </p>
! 4273: </div>
! 4274: </div>
! 4275: <div class="sect1" lang="en">
! 4276: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4277: <a name="writing-builtin.mk"></a>11.3. Writing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> files</h2></div></div></div>
! 4278: <p>
! 4279: Some packages in pkgsrc install headers and libraries that
! 4280: coincide with headers and libraries present in the base system.
! 4281: Aside from a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file, these
! 4282: packages should also include a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code>
! 4283: file that includes the necessary checks to decide whether using
! 4284: the built-in software or the pkgsrc software is
! 4285: appropriate. </p>
! 4286: <p> The only requirements of a builtin.mk file for
! 4287: <em class="replaceable"><code>pkg</code></em> are:
! 4288: </p>
! 4289: <div class="orderedlist"><ol type="1">
! 4290: <li><p> It should set
! 4291: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4292: to either “<span class="quote">yes</span>” or “<span class="quote">no</span>”
! 4293: after it is included.
! 4294: </p></li>
! 4295: <li><p> It should <span class="emphasis"><em>not</em></span> override any
! 4296: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4297: which is already set before the
! 4298: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file is included.
! 4299: </p></li>
! 4300: <li><p> It should be written to allow multiple inclusion. This
! 4301: is <span class="emphasis"><em>very</em></span> important and takes careful
! 4302: attention to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> coding.
! 4303: </p></li>
! 4304: </ol></div>
! 4305: <div class="sect2" lang="en">
! 4306: <div class="titlepage"><div><div><h3 class="title">
! 4307: <a name="anatomy-of-builtin.mk"></a>11.3.1. Anatomy of a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file</h3></div></div></div>
! 4308: <p>The following is the recommended template for builtin.mk
! 4309: files: </p>
! 4310: <pre class="programlisting">
! 4311: .if !defined(IS_BUILTIN.foo)
! 4312: #
! 4313: # IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
! 4314: # genuinely exists in the system or not.
! 4315: #
! 4316: IS_BUILTIN.foo?= no
1.1 grant 4317:
1.75 ! rillig 4318: # BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
! 4319: # version can be determined.
! 4320: #
! 4321: . if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
! 4322: BUILTIN_PKG.foo?= foo-1.0
! 4323: . endif
! 4324: .endif # IS_BUILTIN.foo
1.1 grant 4325:
1.75 ! rillig 4326: .if !defined(USE_BUILTIN.foo)
! 4327: USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
! 4328: . if defined(BUILTIN_PKG.foo)
! 4329: . for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
! 4330: . if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
! 4331: USE_BUILTIN.foo!= \
! 4332: if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \
! 4333: ${ECHO} "yes"; \
! 4334: else \
! 4335: ${ECHO} "no"; \
! 4336: fi
! 4337: . endif
! 4338: . endfor
! 4339: . endif
! 4340: .endif # USE_BUILTIN.foo
1.1 grant 4341:
1.75 ! rillig 4342: CHECK_BUILTIN.foo?= no
! 4343: .if !empty(CHECK_BUILTIN.foo:M[nN][oO])
! 4344: #
! 4345: # Here we place code that depends on whether USE_BUILTIN.foo is set to
! 4346: # "yes" or "no".
! 4347: #
! 4348: .endif # CHECK_BUILTIN.foo
1.1 grant 4349: </pre>
1.75 ! rillig 4350: <p> The first section sets
! 4351: <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4352: depending on if <em class="replaceable"><code>pkg</code></em> really exists
! 4353: in the base system. This should not be a base system software
! 4354: with similar functionality to <em class="replaceable"><code>pkg</code></em>;
! 4355: it should only be “<span class="quote">yes</span>” if the actual package is
! 4356: included as part of the base system. This variable is only
! 4357: used internally within the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code>
! 4358: file. </p>
! 4359: <p> The second section sets
! 4360: <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
! 4361: to the version of <em class="replaceable"><code>pkg</code></em> in the base
! 4362: system if it exists (if
! 4363: <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4364: is “<span class="quote">yes</span>”). This variable is only used internally
! 4365: within the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file. </p>
! 4366: <p> The third section sets
! 4367: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4368: and is <span class="emphasis"><em>required</em></span> in all
! 4369: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> files. The code in this
! 4370: section must make the determination whether the built-in
! 4371: software is adequate to satisfy the dependencies listed in
! 4372: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
! 4373: This is typically done by comparing
! 4374: <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
! 4375: against each of the dependencies in
! 4376: <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
! 4377: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4378: <span class="emphasis"><em>must</em></span> be set to the correct value by the
! 4379: end of the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code> file. Note that
! 4380: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4381: may be “<span class="quote">yes</span>” even if
! 4382: <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4383: is “<span class="quote">no</span>” because we may make the determination
! 4384: that the built-in version of the software is similar enough to
! 4385: be used as a replacement. </p>
! 4386: <p> The last section is guarded by
! 4387: <code class="varname">CHECK_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>,
! 4388: and includes code that uses the value of
! 4389: <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
! 4390: set in the previous section. This typically includes, e.g.,
! 4391: adding additional dependency restrictions and listing
! 4392: additional files to symlink into
! 4393: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${BUILDLINK_DIR}</code> (via
! 4394: <code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>).
! 4395: </p>
! 4396: </div>
! 4397: <div class="sect2" lang="en">
! 4398: <div class="titlepage"><div><div><h3 class="title">
! 4399: <a name="native-or-pkgsrc-preference"></a>11.3.2. Global preferences for native or pkgsrc software</h3></div></div></div>
! 4400: <p>
! 4401: When building packages, it's possible to choose whether to set
! 4402: a global preference for using either the built-in (native)
! 4403: version or the pkgsrc version of software to satisfy a
! 4404: dependency. This is controlled by setting
! 4405: <code class="varname">PREFER_PKGSRC</code> and
! 4406: <code class="varname">PREFER_NATIVE</code>. These variables take values
! 4407: of either “<span class="quote">yes</span>”, “<span class="quote">no</span>”, or a list of
! 4408: packages. <code class="varname">PREFER_PKGSRC</code> tells pkgsrc to
! 4409: use the pkgsrc versions of software, while
! 4410: <code class="varname">PREFER_NATIVE</code> tells pkgsrc to use the
! 4411: built-in versions. Preferences are determined by the most
! 4412: specific instance of the package in either
! 4413: <code class="varname">PREFER_PKGSRC</code> or
! 4414: <code class="varname">PREFER_NATIVE</code>. If a package is specified
! 4415: in neither or in both variables, then
! 4416: <code class="varname">PREFER_PKGSRC</code> has precedence over
! 4417: <code class="varname">PREFER_NATIVE</code>. For example, to require
! 4418: using pkgsrc versions of software for all but the most basic
! 4419: bits on a NetBSD system, you can set: </p>
! 4420: <pre class="programlisting">
! 4421: PREFER_PKGSRC= yes
! 4422: PREFER_NATIVE= getopt skey tcp_wrappers
1.1 grant 4423: </pre>
1.75 ! rillig 4424: <p> A package <span class="emphasis"><em>must</em></span> have a
! 4425: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">builtin.mk</code>
! 4426: file to be listed in <code class="varname">PREFER_NATIVE</code>,
! 4427: otherwise it is simply ignored in that list.
! 4428: </p>
! 4429: </div>
! 4430: </div>
! 4431: </div>
! 4432: <div class="chapter" lang="en">
! 4433: <div class="titlepage"><div><div><h2 class="title">
! 4434: <a name="pkginstall"></a>Chapter 12. The pkginstall framework</h2></div></div></div>
! 4435: <div class="toc">
! 4436: <p><b>Table of Contents</b></p>
! 4437: <dl>
! 4438: <dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">12.1. Files and directories outside the installation prefix</a></span></dt>
! 4439: <dd><dl>
! 4440: <dt><span class="sect2"><a href="#dirs-outside-prefix">12.1.1. Directory manipulation</a></span></dt>
! 4441: <dt><span class="sect2"><a href="#files-outside-prefix">12.1.2. File manipulation</a></span></dt>
! 4442: </dl></dd>
! 4443: <dt><span class="sect1"><a href="#conf-files">12.2. Configuration files</a></span></dt>
! 4444: <dd><dl>
! 4445: <dt><span class="sect2"><a href="#conf-files-sysconfdir">12.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
! 4446: <dt><span class="sect2"><a href="#conf-files-configure">12.2.2. Telling the software where configuration files are</a></span></dt>
! 4447: <dt><span class="sect2"><a href="#conf-files-patching">12.2.3. Patching installations</a></span></dt>
! 4448: <dt><span class="sect2"><a href="#conf-files-disable">12.2.4. Disabling handling of configuration files</a></span></dt>
! 4449: </dl></dd>
! 4450: <dt><span class="sect1"><a href="#rcd-scripts">12.3. System startup scripts</a></span></dt>
! 4451: <dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">12.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
! 4452: <dt><span class="sect1"><a href="#users-and-groups">12.4. System users and groups</a></span></dt>
! 4453: <dt><span class="sect1"><a href="#shells">12.5. System shells</a></span></dt>
! 4454: <dd><dl><dt><span class="sect2"><a href="#shells-disable">12.5.1. Disabling shell registration</a></span></dt></dl></dd>
! 4455: <dt><span class="sect1"><a href="#fonts">12.6. Fonts</a></span></dt>
! 4456: <dd><dl><dt><span class="sect2"><a href="#fonts-disable">12.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
! 4457: </dl>
! 4458: </div>
! 4459: <p>This chapter describes the framework known as
! 4460: <code class="literal">pkginstall</code>, whose key features are:</p>
! 4461: <div class="itemizedlist"><ul type="disc">
! 4462: <li><p>Generic installation and manipulation of directories and files
! 4463: outside the pkgsrc-handled tree, <code class="varname">LOCALBASE</code>.</p></li>
! 4464: <li><p>Automatic handling of configuration files during installation,
! 4465: provided that packages are correctly designed.</p></li>
! 4466: <li><p>Generation and installation of system startup scripts.</p></li>
! 4467: <li><p>Registration of system users and groups.</p></li>
! 4468: <li><p>Registration of system shells.</p></li>
! 4469: <li><p>Automatic updating of fonts databases.</p></li>
! 4470: </ul></div>
! 4471: <p>The following sections inspect each of the above points in detail.</p>
! 4472: <p>You may be thinking that many of the things described here could be
! 4473: easily done with simple code in the package's post-installation target
! 4474: (<code class="literal">post-install</code>). <span class="emphasis"><em>This is incorrect</em></span>,
! 4475: as the code in them is only executed when building from source. Machines
! 4476: using binary packages could not benefit from it at all (as the code itself
! 4477: could be unavailable). Therefore, the only way to achieve any of the items
! 4478: described above is by means of the installation scripts, which are
! 4479: automatically generated by pkginstall.</p>
! 4480: <div class="sect1" lang="en">
! 4481: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4482: <a name="files-and-dirs-outside-prefix"></a>12.1. Files and directories outside the installation prefix</h2></div></div></div>
! 4483: <p>As you already know, the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file holds a list
! 4484: of files and directories that belong to a package. The names used in it
! 4485: are relative to the installation prefix (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}</code>),
! 4486: which means that it cannot register files outside this directory (absolute
! 4487: path names are not allowed). Despite this restriction, some packages need
! 4488: to install files outside this location; e.g., under
! 4489: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${VARBASE}</code> or
! 4490: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFDIR}</code>.</p>
! 4491: <p>The only way to achieve this is to create such files during
! 4492: installation time by using the installation scripts. These scripts can run
! 4493: arbitrary commands, so they have the potential to create and manage files
! 4494: anywhere in the file system. Here is where pkginstall comes into play: it
! 4495: provides generic scripts to abstract the manipulation of such files and
! 4496: directories based on variables set in the package's
! 4497: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>. The rest of this section describes these
! 4498: variables.</p>
! 4499: <div class="sect2" lang="en">
! 4500: <div class="titlepage"><div><div><h3 class="title">
! 4501: <a name="dirs-outside-prefix"></a>12.1.1. Directory manipulation</h3></div></div></div>
! 4502: <p>The following variables can be set to request the creation of
! 4503: directories anywhere in the file system:</p>
! 4504: <div class="itemizedlist"><ul type="disc">
! 4505: <li><p><code class="varname">MAKE_DIRS</code> and <code class="varname">OWN_DIRS</code>
! 4506: contain a list of directories that should be created and should attempt
! 4507: to be destroyed by the installation scripts. The difference between
! 4508: the two is that the latter prompts the administrator to remove any
! 4509: directories that may be left after deinstallation (because they were
! 4510: not empty), while the former does not.</p></li>
! 4511: <li>
! 4512: <p><code class="varname">MAKE_DIRS_PERMS</code> and
! 4513: <code class="varname">OWN_DIRS_PERMS</code> contain a list of tuples describing
! 4514: which directories should be created and should attempt to be destroyed
! 4515: by the installation scripts. Each tuple holds the following values,
! 4516: separated by spaces: the directory name, its owner, its group and its
! 4517: numerical mode. For example:</p>
! 4518: <pre class="programlisting">
! 4519: MAKE_DIRS_PERMS+= ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700
1.1 grant 4520: </pre>
1.75 ! rillig 4521: <p>The difference between the two is exactly the same as their
! 4522: non-<code class="varname">PERMS</code> counterparts.</p>
! 4523: </li>
! 4524: </ul></div>
! 4525: </div>
! 4526: <div class="sect2" lang="en">
! 4527: <div class="titlepage"><div><div><h3 class="title">
! 4528: <a name="files-outside-prefix"></a>12.1.2. File manipulation</h3></div></div></div>
! 4529: <p>Creating non-empty files outside the installation prefix is tricky
! 4530: because the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> forces all files to be inside it.
! 4531: To overcome this problem, the only solution is to extract the file in the
! 4532: known place (i.e., inside the installation prefix) and copy it to the
! 4533: appropriate location during installation (done by the installation scripts
! 4534: generated by pkginstall). We will call the former the <span class="emphasis"><em>master
! 4535: file</em></span> in the following paragraphs, which describe the variables
! 4536: that can be used to automatically and consistently handle files outside the
! 4537: installation prefix:</p>
! 4538: <div class="itemizedlist"><ul type="disc">
! 4539: <li>
! 4540: <p><code class="varname">CONF_FILES</code> and
! 4541: <code class="varname">SUPPORT_FILES</code> are pairs of master and target files.
! 4542: During installation time, the master file is copied to the target one
! 4543: if and only if the latter does not exist. Upon deinstallation, the
! 4544: target file is removed provided that it was not modified by the
! 4545: installation.</p>
! 4546: <p>The difference between the two is that the latter prompts the
! 4547: administrator to remove any files that may be left after
! 4548: deinstallation (because they were not empty), while the former does
! 4549: not.</p>
! 4550: </li>
! 4551: <li>
! 4552: <p><code class="varname">CONF_FILES_PERMS</code> and
! 4553: <code class="varname">SUPPORT_FILES_PERMS</code> contain tuples describing master
! 4554: files as well as their target locations. For each of them, it also
! 4555: specifies their owner, their group and their numeric permissions, in
! 4556: this order. For example:</p>
! 4557: <pre class="programlisting">
! 4558: SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700
1.1 grant 4559: </pre>
1.75 ! rillig 4560: <p>The difference between the two is exactly the same as their
! 4561: non-<code class="varname">PERMS</code> counterparts.</p>
! 4562: </li>
! 4563: </ul></div>
! 4564: </div>
! 4565: </div>
! 4566: <div class="sect1" lang="en">
! 4567: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4568: <a name="conf-files"></a>12.2. Configuration files</h2></div></div></div>
! 4569: <p>Configuration files are special in the sense that they are installed
! 4570: in their own specific directory, <code class="varname">PKG_SYSCONFDIR</code>, and
! 4571: need special treatment during installation (most of which is automated by
! 4572: pkginstall). The main concept you must bear in mind is that files marked
! 4573: as configuration files are automatically copied to the right place (somewhere
! 4574: inside <code class="varname">PKG_SYSCONFDIR</code>) during installation <span class="emphasis"><em>if
! 4575: and only if</em></span> they didn't exist before. Similarly, they will not
! 4576: be removed if they have local modifications. This ensures that
! 4577: administrators never lose any custom changes they may have made.</p>
! 4578: <div class="sect2" lang="en">
! 4579: <div class="titlepage"><div><div><h3 class="title">
! 4580: <a name="conf-files-sysconfdir"></a>12.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</h3></div></div></div>
! 4581: <p>As said before, the <code class="varname">PKG_SYSCONFDIR</code> variable
! 4582: specifies where configuration files shall be installed. Its contents are
! 4583: set based upon the following variables:</p>
! 4584: <div class="itemizedlist"><ul type="disc">
! 4585: <li><p><code class="varname">PKG_SYSCONFBASE</code>: The configuration's root
! 4586: directory. Defaults to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/etc</code> although it may
! 4587: be overridden by the user to point to his preferred location (e.g.,
! 4588: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc</code>, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/pkg</code>, etc.).
! 4589: Packages must not use it directly.</p></li>
! 4590: <li>
! 4591: <p><code class="varname">PKG_SYSCONFSUBDIR</code>: A subdirectory of
! 4592: <code class="varname">PKG_SYSCONFBASE</code> under which the configuration files
! 4593: for the package being built shall be installed. The definition of this
! 4594: variable only makes sense in the package's
! 4595: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> (i.e., it is not user-customizable).</p>
! 4596: <p>As an example, consider the Apache package,
! 4597: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache2/README.html" target="_top"><code xmlns="" class="filename">www/apache2</code></a>, which places its
! 4598: configuration files under the
! 4599: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">httpd/</code> subdirectory of
! 4600: <code class="varname">PKG_SYSCONFBASE</code>. This should be set in the package
! 4601: Makefile.</p>
! 4602: </li>
! 4603: <li><p><code class="varname">PKG_SYSCONFVAR</code>: Specifies the name of the
! 4604: variable that holds this package's configuration directory (if
! 4605: different from <code class="varname">PKG_SYSCONFBASE</code>). It defaults to
! 4606: <code class="varname">PKGBASE</code>'s value, and is always prefixed with
! 4607: <code class="literal">PKG_SYSCONFDIR</code>.</p></li>
! 4608: <li><p><code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>: Holds the
! 4609: directory where the configuration files for the package identified by
! 4610: <code class="varname">PKG_SYSCONFVAR</code>'s shall be placed.</p></li>
! 4611: </ul></div>
! 4612: <p>Based on the above variables, pkginstall determines the value of
! 4613: <code class="varname">PKG_SYSCONFDIR</code>, which is the <span class="emphasis"><em>only</em></span>
! 4614: variable that can be used within a package to refer to its configuration
! 4615: directory. The algorithm used to set its value is basically the
! 4616: following:</p>
! 4617: <div class="orderedlist"><ol type="1">
! 4618: <li><p>If <code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> is set,
! 4619: its value is used.</p></li>
! 4620: <li><p>If the previous variable is not defined but
! 4621: <code class="varname">PKG_SYSCONFSUBDIR</code> is set in the package's
! 4622: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, the resulting value is
! 4623: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p></li>
! 4624: <li><p>Otherwise, it is set to
! 4625: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFBASE}</code>.</p></li>
! 4626: </ol></div>
! 4627: <p>It is worth mentioning that <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFDIR}</code> is
! 4628: automatically added to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">OWN_DIRS</code>. See <a href="#dirs-outside-prefix" title="12.1.1. Directory manipulation">Section 12.1.1, “Directory manipulation”</a> what this means.</p>
! 4629: </div>
! 4630: <div class="sect2" lang="en">
! 4631: <div class="titlepage"><div><div><h3 class="title">
! 4632: <a name="conf-files-configure"></a>12.2.2. Telling the software where configuration files are</h3></div></div></div>
! 4633: <p>Given that pkgsrc (and users!) expect configuration files to be in a
! 4634: known place, you need to teach each package where it shall install its
! 4635: files. In some cases you will have to patch the package Makefiles to
! 4636: achieve it. If you are lucky, though, it may be as easy as passing an
! 4637: extra flag to the configuration script; this is the case of GNU Autoconf-
! 4638: generated files:</p>
! 4639: <pre class="programlisting">
! 4640: CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
1.1 grant 4641: </pre>
1.75 ! rillig 4642: <p>Note that this specifies where the package has to <span class="emphasis"><em>look
! 4643: for</em></span> its configuration files, not where they will be originally
! 4644: installed (although the difference is never explicit,
! 4645: unfortunately).</p>
! 4646: </div>
! 4647: <div class="sect2" lang="en">
! 4648: <div class="titlepage"><div><div><h3 class="title">
! 4649: <a name="conf-files-patching"></a>12.2.3. Patching installations</h3></div></div></div>
! 4650: <p>As said before, pkginstall automatically handles configuration files.
! 4651: This means that <span class="strong"><strong>the packages themselves must not
! 4652: touch the contents of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFDIR}</code>
! 4653: directly</strong></span>. Bad news is that many software installation scripts
! 4654: will, out of the box, mess with the contents of that directory. So what is
! 4655: the correct procedure to fix this issue?</p>
! 4656: <p>You must teach the package (usually by manually patching it) to
! 4657: install any configuration files under the examples hierarchy,
! 4658: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/examples/${PKGBASE}/</code>. This way, the
! 4659: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> registers them and the administrator always
! 4660: has the original copies available.</p>
! 4661: <p>Once the required configuration files are in place (i.e., under the
! 4662: examples hierarchy), the pkginstall framework can use them as master copies
! 4663: during the package installation to update what is in
! 4664: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PKG_SYSCONFDIR}</code>. To achieve this, the variables
! 4665: <code class="varname">CONF_FILES</code> and <code class="varname">CONF_FILES_PERMS</code> are
! 4666: used. Check out <a href="#files-outside-prefix" title="12.1.2. File manipulation">Section 12.1.2, “File manipulation”</a> for information
! 4667: about their syntax and their purpose. Here is an example, taken from the
! 4668: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/mail/mutt/README.html" target="_top"><code xmlns="" class="filename">mail/mutt</code></a> package:</p>
! 4669: <pre class="programlisting">
! 4670: EGDIR= ${PREFIX}/share/doc/mutt/samples
! 4671: CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
1.1 grant 4672: </pre>
1.75 ! rillig 4673: <p>Note that the <code class="varname">EGDIR</code> variable is specific to that
! 4674: package and has no meaning outside it.</p>
! 4675: </div>
! 4676: <div class="sect2" lang="en">
! 4677: <div class="titlepage"><div><div><h3 class="title">
! 4678: <a name="conf-files-disable"></a>12.2.4. Disabling handling of configuration files</h3></div></div></div>
! 4679: <p>The automatic copying of config files can be toggled by setting the
! 4680: environment variable <code class="varname">PKG_CONFIG</code> prior to package
! 4681: installation.</p>
! 4682: </div>
! 4683: </div>
! 4684: <div class="sect1" lang="en">
! 4685: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4686: <a name="rcd-scripts"></a>12.3. System startup scripts</h2></div></div></div>
! 4687: <p>System startup scripts are special files because they must be
! 4688: installed in a place known by the underlying OS, usually outside the
! 4689: installation prefix. Therefore, the same rules described in <a href="#files-and-dirs-outside-prefix" title="12.1. Files and directories outside the installation prefix">Section 12.1, “Files and directories outside the installation prefix”</a> apply, and the same solutions
! 4690: can be used. However, pkginstall provides a special mechanism to handle
! 4691: these files.</p>
! 4692: <p>In order to provide system startup scripts, the package has
! 4693: to:</p>
! 4694: <div class="orderedlist"><ol type="1">
! 4695: <li><p>Store the script inside <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${FILESDIR}</code>, with
! 4696: the <code class="literal">.sh</code> suffix appended. Considering the
! 4697: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/cups/README.html" target="_top"><code xmlns="" class="filename">print/cups</code></a> package as an example, it has a
! 4698: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">cupsd.sh</code> in its files directory.</p></li>
! 4699: <li>
! 4700: <p>Tell pkginstall to handle it, appending the name of the script,
! 4701: without its extension, to the <code class="varname">RCD_SCRIPTS</code> variable.
! 4702: Continuing the previous example:</p>
! 4703: <pre class="programlisting">
! 4704: RCD_SCRIPTS+= cupsd
1.1 grant 4705: </pre>
1.75 ! rillig 4706: </li>
! 4707: </ol></div>
! 4708: <p>Once this is done, pkginstall will do the following steps for each
! 4709: script in an automated fashion:</p>
! 4710: <div class="orderedlist"><ol type="1">
! 4711: <li><p>Process the file found in the files directory applying all the
! 4712: substitutions described in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">FILES_SUBST</code>
! 4713: variable.</p></li>
! 4714: <li><p>Copy the script from the files directory to the examples
! 4715: hierarchy, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/examples/rc.d/</code>. Note
! 4716: that this master file must be explicitly registered in the
! 4717: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>.</p></li>
! 4718: <li><p>Add code to the installation scripts to copy the startup script
! 4719: from the examples hierarchy into the system-wide startup scripts
! 4720: directory.</p></li>
! 4721: </ol></div>
! 4722: <div class="sect2" lang="en">
! 4723: <div class="titlepage"><div><div><h3 class="title">
! 4724: <a name="rcd-scripts-disable"></a>12.3.1. Disabling handling of system startup scripts</h3></div></div></div>
! 4725: <p>The automatic copying of config files can be toggled by setting the
! 4726: environment variable <code class="varname">PKG_RCD_SCRIPTS</code> prior to package
! 4727: installation. Note that the scripts will be always copied inside the
! 4728: examples hierarchy, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/examples/rc.d/</code>, no
! 4729: matter what the value of this variable is.</p>
! 4730: </div>
! 4731: </div>
! 4732: <div class="sect1" lang="en">
! 4733: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4734: <a name="users-and-groups"></a>12.4. System users and groups</h2></div></div></div>
! 4735: <p>If a package needs to create special users and/or groups during
! 4736: installation, it can do so by using the pkginstall framework.</p>
! 4737: <p>Users can be created by adding entries to the
! 4738: <code class="varname">PKG_USERS</code> variable. Each entry has the following
! 4739: syntax:</p>
! 4740: <pre class="programlisting">
! 4741: user:group
1.1 grant 4742: </pre>
1.75 ! rillig 4743: <p>Further specification of user details may be done by setting per-user
! 4744: variables.
! 4745: <code class="varname">PKG_UID.<em class="replaceable"><code>user</code></em></code> is the numeric
! 4746: UID for the user.
! 4747: <code class="varname">PKG_GECOS.<em class="replaceable"><code>user</code></em></code> is the user's
! 4748: description or comment.
! 4749: <code class="varname">PKG_HOME.<em class="replaceable"><code>user</code></em></code> is the user's
! 4750: home directory, and defaults to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/nonexistent</code> if not
! 4751: specified.
! 4752: <code class="varname">PKG_SHELL.<em class="replaceable"><code>user</code></em></code> is the user's
! 4753: shell, and defaults to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/sbinno/login</code> if not specified.
! 4754: </p>
! 4755: <p>Similarly, groups can be created by adding entries to the
! 4756: <code class="varname">PKG_GROUPS</code> variable, whose syntax is:</p>
! 4757: <pre class="programlisting">
! 4758: group
1.1 grant 4759: </pre>
1.75 ! rillig 4760: <p>The numeric GID of the group may be set by defining
! 4761: <code class="varname">PKG_GID.<em class="replaceable"><code>group</code></em></code>.</p>
! 4762: <p>If a package needs to create the users and groups at an earlier
! 4763: stage, then it can set <code class="varname">USERGROUP_PHASE</code> to
! 4764: either <code class="literal">configure</code> or <code class="literal">build</code> to
! 4765: indicate the phase before which the users and groups are created. In
! 4766: this case, the numeric UIDs and GIDs of the created users and groups
! 4767: are automatically hardcoded into the final installation scripts.</p>
! 4768: </div>
! 4769: <div class="sect1" lang="en">
! 4770: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4771: <a name="shells"></a>12.5. System shells</h2></div></div></div>
! 4772: <p>Packages that install system shells should register them in the shell
! 4773: database, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/shells</code>, to make things easier to the
! 4774: administrator. This must be done from the installation scripts to keep
! 4775: binary packages working on any system. pkginstall provides an easy way to
! 4776: accomplish this task.</p>
! 4777: <p>When a package provides a shell interpreter, it has to set the
! 4778: <code class="varname">PKG_SHELL</code> variable to its absolute file name. This will
! 4779: add some hooks to the installation scripts to handle it. Consider the
! 4780: following example, taken from <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/zsh/README.html" target="_top"><code xmlns="" class="filename">shells/zsh</code></a>:</p>
! 4781: <pre class="programlisting">
! 4782: PKG_SHELL= ${PREFIX}/bin/zsh
1.1 grant 4783: </pre>
1.75 ! rillig 4784: <div class="sect2" lang="en">
! 4785: <div class="titlepage"><div><div><h3 class="title">
! 4786: <a name="shells-disable"></a>12.5.1. Disabling shell registration</h3></div></div></div>
! 4787: <p>The automatic registration of shell interpreters can be disabled by
! 4788: the administrator by setting the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PKG_REGISTER_SHELLS</code>
! 4789: environment variable to <code class="literal">NO</code>.</p>
! 4790: </div>
! 4791: </div>
! 4792: <div class="sect1" lang="en">
! 4793: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4794: <a name="fonts"></a>12.6. Fonts</h2></div></div></div>
! 4795: <p>Packages that install X11 fonts should update the database files
! 4796: that index the fonts within each fonts directory. This can easily be
! 4797: accomplished within the pkginstall framework.</p>
! 4798: <p>When a package installs X11 fonts, it must list the directories in
! 4799: which fonts are installed in the
! 4800: <code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code> variables,
! 4801: where <em class="replaceable"><code>type</code></em> can be one of “<span class="quote">ttf</span>”,
! 4802: “<span class="quote">type1</span>” or “<span class="quote">x11</span>”. This will add hooks to the
! 4803: installation scripts to run the appropriate commands to update the fonts
! 4804: database files within each of those directories. For convenience, if the
! 4805: directory path is relative, it is taken to be relative to the package's
! 4806: installation prefix. Consider the following example, taken from <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/fonts/dbz-ttf/README.html" target="_top"><code xmlns="" class="filename">fonts/dbz-ttf</code></a>:</p>
! 4807: <pre class="programlisting">
! 4808: FONTS_DIRS.ttf= ${PREFIX}/lib/X11/fonts/TTF
1.1 grant 4809: </pre>
1.75 ! rillig 4810: <div class="sect2" lang="en">
! 4811: <div class="titlepage"><div><div><h3 class="title">
! 4812: <a name="fonts-disable"></a>12.6.1. Disabling automatic update of the fonts databases</h3></div></div></div>
! 4813: <p>The automatic update of fonts databases can be disabled by
! 4814: the administrator by setting the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PKG_UPDATE_FONTS_DB</code>
! 4815: environment variable to <code class="literal">NO</code>.</p>
! 4816: </div>
! 4817: </div>
! 4818: </div>
! 4819: <div class="chapter" lang="en">
! 4820: <div class="titlepage"><div><div><h2 class="title">
! 4821: <a name="options"></a>Chapter 13. Options handling</h2></div></div></div>
! 4822: <div class="toc">
! 4823: <p><b>Table of Contents</b></p>
! 4824: <dl>
! 4825: <dt><span class="sect1"><a href="#global-default-options">13.1. Global default options</a></span></dt>
! 4826: <dt><span class="sect1"><a href="#converting-to-options">13.2. Converting packages to use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code></a></span></dt>
! 4827: <dt><span class="sect1"><a href="#option-names">13.3. Option Names</a></span></dt>
! 4828: </dl>
! 4829: </div>
! 4830: <p>Many packages have the ability to be built to support different
! 4831: sets of features. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code> is a framework
! 4832: in pkgsrc that provides generic handling of those options that
! 4833: determine different ways in which the packages can be built. It's
! 4834: possible for the user to specify exactly which sets of options will be
! 4835: built into a package or to allow a set of global default options
! 4836: apply.</p>
! 4837: <div class="sect1" lang="en">
! 4838: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4839: <a name="global-default-options"></a>13.1. Global default options</h2></div></div></div>
! 4840: <p>Global default options are listed in
! 4841: <code class="varname">PKG_DEFAULT_OPTIONS</code>, which is a list of the options
! 4842: that should be built into every package if that option is supported.
! 4843: This variable should be set in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>.</p>
! 4844: </div>
! 4845: <div class="sect1" lang="en">
! 4846: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4847: <a name="converting-to-options"></a>13.2. Converting packages to use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code></h2></div></div></div>
! 4848: <p>The following example shows how
! 4849: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code> should be used
! 4850: by the hypothetical ``wibble'' package, either in the package
! 4851: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, or in a file,
! 4852: e.g. <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">options.mk</code>, that is included by the
! 4853: main package <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>.</p>
! 4854: <pre class="programlisting">
! 4855: PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
! 4856: PKG_SUPPORTED_OPTIONS= wibble-foo ldap
! 4857: PKG_OPTIONS_OPTIONAL_GROUPS= database
! 4858: PKG_OPTIONS_GROUP.database= mysql pgsql
! 4859: PKG_SUGGESTED_OPTIONS= wibble-foo
! 4860: PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
! 4861: PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
1.1 grant 4862:
1.75 ! rillig 4863: .include "../../mk/bsd.prefs.mk"
1.69 rillig 4864:
1.75 ! rillig 4865: # this package was previously named wibble2
! 4866: .if defined(PKG_OPTIONS.wibble2)
! 4867: PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
! 4868: PKG_OPTIONS_DEPRECATED_WARNINGS+= \
! 4869: "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR instead."
! 4870: .endif
1.69 rillig 4871:
1.75 ! rillig 4872: .include "../../mk/bsd.options.mk"
1.69 rillig 4873:
1.75 ! rillig 4874: # Package-specific option-handling
1.69 rillig 4875:
1.75 ! rillig 4876: ###
! 4877: ### FOO support
! 4878: ###
! 4879: .if !empty(PKG_OPTIONS:Mwibble-foo)
! 4880: CONFIGURE_ARGS+= --enable-foo
! 4881: .endif
1.69 rillig 4882:
1.75 ! rillig 4883: ###
! 4884: ### LDAP support
! 4885: ###
! 4886: .if !empty(PKG_OPTIONS:Mldap)
! 4887: . include "../../databases/openldap/buildlink3.mk"
! 4888: CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap}
! 4889: .endif
1.69 rillig 4890:
1.75 ! rillig 4891: ###
! 4892: ### database support
! 4893: ###
! 4894: .if !empty(PKG_OPTIONS:Mmysql)
! 4895: . include "../../mk/mysql.buildlink3.mk"
! 4896: .endif
! 4897: .if !empty(PKG_OPTIONS:Mpgsql)
! 4898: . include "../../mk/pgsql.buildlink3.mk"
! 4899: .endif
! 4900: </pre>
! 4901: <p>The first section contains the information about which build
! 4902: options are supported by the package, and any default options settings
! 4903: if needed.</p>
! 4904: <div class="orderedlist"><ol type="1">
! 4905: <li><p><code class="varname">PKG_OPTIONS_VAR</code> is the name of the
! 4906: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable that the user can set to override the default
! 4907: options. It should be set to
! 4908: PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em>. Do not set it to
! 4909: PKG_OPTIONS.${PKGBASE}, since <code class="varname">PKGBASE</code> is set after
! 4910: <code class="varname">PKG_OPTIONS_VAR</code> is used.</p></li>
! 4911: <li><p><code class="varname">PKG_SUPPORTED_OPTIONS</code> is a list of
! 4912: build options supported by the package.</p></li>
! 4913: <li><p><code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
! 4914: list of names of groups of mutually exclusive options. The options in
! 4915: each group are listed in
! 4916: <code class="varname">PKG_OPTIONS_GROUP.<em class="replaceable"><code>groupname</code></em></code>.
! 4917: The most specific setting of any option from the group takes
! 4918: precedence over all other options in the group. Options from the
! 4919: groups will be automatically added to
! 4920: <code class="varname">PKG_SUPPORTED_OPTIONS</code>.</p></li>
! 4921: <li><p><code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is like
! 4922: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but building the
! 4923: packages will fail if no option from the group is
! 4924: selected.</p></li>
! 4925: <li><p><code class="varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a list
! 4926: of names of sets of options. At least one option from each set must
! 4927: be selected. The options in each set are listed in
! 4928: <code class="varname">PKG_OPTIONS_SET.<em class="replaceable"><code>setname</code></em></code>.
! 4929: Options from the sets will be automatically added to
! 4930: <code class="varname">PKG_SUPPORTED_OPTIONS</code>. Building the package will
! 4931: fail if no option from the set is selected.</p></li>
! 4932: <li><p><code class="varname">PKG_SUGGESTED_OPTIONS</code> is a list of
! 4933: build options which are enabled by default.</p></li>
! 4934: <li><p><code class="varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
! 4935: of
! 4936: “<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>”
! 4937: pairs that map legacy <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> variables to
! 4938: their option counterparts. Pairs should be added with
! 4939: “<span class="quote">+=</span>” to keep the listing of global legacy variables. A
! 4940: warning will be issued if the user uses a legacy
! 4941: variable.</p></li>
! 4942: <li><p><code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
! 4943: of
! 4944: “<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>”
! 4945: pairs that map options that have been renamed to their new
! 4946: counterparts. Pairs should be added with “<span class="quote">+=</span>” to keep
! 4947: the listing of global legacy options. A warning will be issued if
! 4948: the user uses a legacy option.</p></li>
! 4949: <li><p><code class="varname">PKG_LEGACY_OPTIONS</code> is a list of
! 4950: options implied by deprecated variables used. This can be used for
! 4951: cases that neither <code class="varname">PKG_OPTIONS_LEGACY_VARS</code> nor
! 4952: <code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> can handle, e. g. when
! 4953: <code class="varname">PKG_OPTIONS_VAR</code> is renamed.</p></li>
! 4954: <li><p><code class="varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
! 4955: a list of warnings about deprecated variables or options used, and
! 4956: what to use instead.</p></li>
! 4957: </ol></div>
! 4958: <p>A package should never modify
! 4959: <code class="varname">PKG_DEFAULT_OPTIONS</code> or the variable named in
! 4960: <code class="varname">PKG_OPTIONS_VAR</code>. These are strictly user-settable.
! 4961: To suggest a default set of options, use
! 4962: <code class="varname">PKG_SUGGESTED_OPTIONS</code>.</p>
! 4963: <p><code class="varname">PKG_OPTIONS_VAR</code> must be defined before
! 4964: including <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code>. If none of
! 4965: <code class="varname">PKG_SUPPORTED_OPTIONS</code>,
! 4966: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
! 4967: <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> are defined (as can
! 4968: happen with platform-specific options if none of them is supported on
! 4969: the current platform), <code class="varname">PKG_OPTIONS</code> is set to the
! 4970: empty list and the package is otherwise treated as not using the
! 4971: options framework.</p>
! 4972: <p>After the inclusion of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.options.mk</code>, the
! 4973: variable <code class="varname">PKG_OPTIONS</code> contains the list of selected
! 4974: build options, properly filtered to remove unsupported and duplicate
! 4975: options.</p>
! 4976: <p>The remaining sections contain the logic that is specific to
! 4977: each option. The correct way to check for an option is to check
! 4978: whether it is listed in <code class="varname">PKG_OPTIONS</code>:</p>
! 4979: <pre class="programlisting">
! 4980: .if !empty(PKG_OPTIONS:M<em class="replaceable"><code>option</code></em>)
! 4981: </pre>
! 4982: </div>
! 4983: <div class="sect1" lang="en">
! 4984: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 4985: <a name="option-names"></a>13.3. Option Names</h2></div></div></div>
! 4986: <p>Options that enable similar features in different packages (like
! 4987: optional support for a library) should use a common name in all
! 4988: packages that support it (like the name of the library). If another
! 4989: package already has an option with the same meaning, use the same
! 4990: name.</p>
! 4991: <p>Options that enable features specific to one package, where it's
! 4992: unlikely that another (unrelated) package has the same (or a similar)
! 4993: optional feature, should use a name prefixed with
! 4994: <code class="varname"><em class="replaceable"><code>pkgname</code></em>-</code>.</p>
! 4995: <p>If a group of related packages share an optional feature
! 4996: specific to that group, prefix it with the name of the
! 4997: “<span class="quote">main</span>” package
! 4998: (e. g. <code class="varname">djbware-errno-hack</code>).</p>
! 4999: <p>For new options, add a line to
! 5000: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/defaults/options.description</code>. Lines have two
! 5001: fields, separated by tab. The first field is the option name, the
! 5002: second its description. The description should be a whole sentence
! 5003: (starting with an uppercase letter and ending with a period) that
! 5004: describes what enabling the option does. E. g. “<span class="quote">Enable ispell
! 5005: support.</span>” The file is sorted by option names.</p>
! 5006: </div>
! 5007: </div>
! 5008: <div class="chapter" lang="en">
! 5009: <div class="titlepage"><div><div><h2 class="title">
! 5010: <a name="build"></a>Chapter 14. The build process</h2></div></div></div>
! 5011: <div class="toc">
! 5012: <p><b>Table of Contents</b></p>
! 5013: <dl>
! 5014: <dt><span class="sect1"><a href="#build.intro">14.1. Introduction</a></span></dt>
! 5015: <dt><span class="sect1"><a href="#build.prefix">14.2. Program location</a></span></dt>
! 5016: <dt><span class="sect1"><a href="#build.builddirs">14.3. Directories used during the build process</a></span></dt>
! 5017: <dt><span class="sect1"><a href="#build.running">14.4. Running a phase</a></span></dt>
! 5018: <dt><span class="sect1"><a href="#build.fetch">14.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
! 5019: <dt><span class="sect1"><a href="#build.checksum">14.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
! 5020: <dt><span class="sect1"><a href="#build.extract">14.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
! 5021: <dt><span class="sect1"><a href="#build.patch">14.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
! 5022: <dt><span class="sect1"><a href="#build.tools">14.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
! 5023: <dt><span class="sect1"><a href="#build.wrapper">14.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
! 5024: <dt><span class="sect1"><a href="#build.configure">14.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
! 5025: <dt><span class="sect1"><a href="#build.build">14.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
! 5026: <dt><span class="sect1"><a href="#build.test">14.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
! 5027: <dt><span class="sect1"><a href="#build.install">14.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
! 5028: <dt><span class="sect1"><a href="#build.package">14.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
! 5029: <dt><span class="sect1"><a href="#build.helpful-targets">14.16. Other helpful targets</a></span></dt>
! 5030: </dl>
! 5031: </div>
! 5032: <div class="sect1" lang="en">
! 5033: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5034: <a name="build.intro"></a>14.1. Introduction</h2></div></div></div>
! 5035: <p>This chapter gives a detailed description on how a package is
! 5036: built. Building a package is separated into different
! 5037: <span class="emphasis"><em>phases</em></span> (for example <code class="varname">fetch</code>,
! 5038: <code class="varname">build</code>, <code class="varname">install</code>), all of which are
! 5039: described in the following sections. Each phase is splitted into
! 5040: so-called <span class="emphasis"><em>stages</em></span>, which take the name of the
! 5041: containing phase, prefixed by one of <code class="varname">pre-</code>,
! 5042: <code class="varname">do-</code> or <code class="varname">post-</code>. (Examples are
! 5043: <code class="varname">pre-configure</code>, <code class="varname">post-build</code>.) Most
! 5044: of the actual work is done in the <code class="varname">do-*</code> stages.</p>
! 5045: <p>The basic steps for building a program are always the same. First
! 5046: the program's source (<span class="emphasis"><em>distfile</em></span>) must be brought to
! 5047: the local system and then extracted. After any pkgsrc-specific patches
! 5048: to compile properly are applied, the software can be configured, then
! 5049: built (usually by compiling), and finally the generated binaries, etc.
! 5050: can be put into place on the system.</p>
! 5051: </div>
! 5052: <div class="sect1" lang="en">
! 5053: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5054: <a name="build.prefix"></a>14.2. Program location</h2></div></div></div>
! 5055: <p>Before outlining the process performed by the NetBSD package system in
! 5056: the next section, here's a brief discussion on where programs are
! 5057: installed, and which variables influence this.</p>
! 5058: <p>The automatic variable <code class="varname">PREFIX</code> indicates
! 5059: where all files of the final program shall be installed. It is
! 5060: usually set to <code class="varname">LOCALBASE</code>
! 5061: (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg</code>), or <code class="varname">CROSSBASE</code>
! 5062: for pkgs in the “<span class="quote">cross</span>” category. The value of
! 5063: <code class="varname">PREFIX</code> needs to be put
! 5064: into the various places in the program's source where paths to
! 5065: these files are encoded. See <a href="#components.patches" title="8.3. patches/*">Section 8.3, “patches/*”</a> and <a href="#fixes.libtool" title="16.3.1. Shared libraries - libtool">Section 16.3.1, “Shared libraries - libtool”</a> for more details.</p>
! 5066: <p>When choosing which of these variables to use,
! 5067: follow the following rules:</p>
! 5068: <div class="itemizedlist"><ul type="disc">
! 5069: <li><p><code class="varname">PREFIX</code> always points to the location where the current
! 5070: pkg will be installed. When referring to a pkg's own installation path,
! 5071: use “<span class="quote">${PREFIX}</span>”.</p></li>
! 5072: <li><p><code class="varname">LOCALBASE</code> is where all non-X11 pkgs are installed.
! 5073: If you need to construct a -I or -L argument to the compiler to find
! 5074: includes and libraries installed by another non-X11 pkg, use
! 5075: “<span class="quote">${LOCALBASE}</span>”.</p></li>
! 5076: <li><p><code class="varname">X11BASE</code> is where the actual X11 distribution (from
! 5077: xsrc, etc.) is installed. When looking for
! 5078: <span class="emphasis"><em>standard</em></span> X11 includes (not
! 5079: those installed by a pkg), use “<span class="quote">${X11BASE}</span>”.</p></li>
! 5080: <li>
! 5081: <p>X11-based packages are special in that they may be installed in
! 5082: either <code class="varname">X11BASE</code> or <code class="varname">LOCALBASE</code>.</p>
! 5083: <p>Usually, X11 packages should be installed under
! 5084: <code class="varname">LOCALBASE</code> whenever possible. Note that you will
! 5085: need to include <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../mk/x11.buildlink3.mk</code>
! 5086: in them to request the
! 5087: presence of X11 and to get the right compilation flags.</p>
! 5088: <p>Even though, there are some packages that cannot be installed
! 5089: under <code class="varname">LOCALBASE</code>: those that come with app-defaults
! 5090: files. These packages are special and they must be placed under
! 5091: <code class="varname">X11BASE</code>. To accomplish this, set either
! 5092: <code class="varname">USE_X11BASE</code> or <code class="varname">USE_IMAKE</code> in
! 5093: your package.</p>
! 5094: <p>Some notes: If you need
! 5095: to find includes or libraries installed by a pkg that has
! 5096: <code class="varname">USE_IMAKE</code> or <code class="varname">USE_X11BASE</code> in
! 5097: its pkg <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, you need to look in
! 5098: <span class="emphasis"><em>both</em></span> <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${X11BASE}</code> and
! 5099: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${LOCALBASE}</code>. To force installation of
! 5100: all X11 packages in <code class="varname">LOCALBASE</code>, the
! 5101: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html" target="_top"><code xmlns="" class="filename">pkgtools/xpkgwedge</code></a> package
! 5102: is enabled by default.</p>
! 5103: </li>
! 5104: <li><p><code class="varname">X11PREFIX</code> should be used to refer to the installed
! 5105: location of an X11 package. <code class="varname">X11PREFIX</code> will be set to
! 5106: <code class="varname">X11BASE</code> if xpkgwedge is not installed,
! 5107: and to <code class="varname">LOCALBASE</code> if xpkgwedge is installed.</p></li>
! 5108: <li>
! 5109: <p>If xpkgwedge is installed, it is possible to have some packages installed
! 5110: in <code class="varname">X11BASE</code> and some in <code class="varname">LOCALBASE</code>.
! 5111: To determine the prefix of an installed package, the
! 5112: <code class="varname">EVAL_PREFIX</code> definition can be used. It takes pairs in the
! 5113: format “<span class="quote">DIRNAME=<package></span>”, and the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable
! 5114: <code class="varname">DIRNAME</code> will be set to the prefix of the installed
! 5115: package <package>, or “<span class="quote">${X11PREFIX}</span>” if the package is
! 5116: not installed.</p>
! 5117: <p>This is best illustrated by example.</p>
! 5118: <p>The following lines are taken from
! 5119: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/wm/scwm/Makefile</code>:</p>
! 5120: <pre class="programlisting">
! 5121: EVAL_PREFIX+= GTKDIR=gtk+
! 5122: CONFIGURE_ARGS+= --with-guile-prefix=${LOCALBASE:Q}
! 5123: CONFIGURE_ARGS+= --with-gtk-prefix=${GTKDIR:Q}
! 5124: CONFIGURE_ARGS+= --enable-multibyte
! 5125: </pre>
! 5126: <p>Specific defaults can be defined for the packages evaluated using
! 5127: <code class="varname">EVAL_PREFIX</code>, by using a definition of the form:</p>
! 5128: <pre class="programlisting">
! 5129: GTKDIR_DEFAULT= ${LOCALBASE}
! 5130: </pre>
! 5131: <p>where <code class="varname">GTKDIR</code> corresponds
! 5132: to the first definition in
! 5133: the <code class="varname">EVAL_PREFIX</code> pair.</p>
! 5134: </li>
! 5135: <li><p>Within <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}</code>, packages should
! 5136: install files according to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?hier+7+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">hier</span>(7)</span></a>, with the exception that
! 5137: manual pages go into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/man</code>, not
! 5138: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/man</code>.</p></li>
! 5139: </ul></div>
! 5140: </div>
! 5141: <div class="sect1" lang="en">
! 5142: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5143: <a name="build.builddirs"></a>14.3. Directories used during the build process</h2></div></div></div>
! 5144: <p>When building a package, a number of directories is used to store
! 5145: source files, temporary files, pkgsrc-internal files, and so on. These
! 5146: directories are explained here.</p>
! 5147: <p>Some of the directory variables contain relative pathnames. There
! 5148: are two common base directories for these relative directories:
! 5149: <code class="varname">PKGSRCDIR/PKGPATH</code> is used for directories that are
! 5150: pkgsrc-specific. <code class="varname">WRKSRC</code> is used for directories
! 5151: inside the package itself.</p>
! 5152: <div class="variablelist"><dl>
! 5153: <dt><span class="term"><code class="varname">PKGSRCDIR</code></span></dt>
! 5154: <dd><p>This is an absolute pathname that points to the pkgsrc
! 5155: root directory. Generally, you don't need
! 5156: it.</p></dd>
! 5157: <dt><span class="term"><code class="varname">PKGPATH</code></span></dt>
! 5158: <dd><p>This is a pathname relative to
! 5159: <code class="varname">PKGSRCDIR</code> that points to the current
! 5160: package.</p></dd>
! 5161: <dt><span class="term"><code class="varname">WRKDIR</code></span></dt>
! 5162: <dd><p>This is an absolute pathname pointing to the directory
! 5163: where all work takes place. The distfiles are extraced to this
! 5164: directory. It also contains temporary directories and log files used by
! 5165: the various pkgsrc frameworks, like <span class="emphasis"><em>buildlink</em></span> or
! 5166: the <span class="emphasis"><em>wrappers</em></span>.</p></dd>
! 5167: <dt><span class="term"><code class="varname">WRKSRC</code></span></dt>
! 5168: <dd><p>This is an absolute pathname pointing to the directory
! 5169: where the distfiles are extracted. It is usually a direct subdirectory
! 5170: of <code class="varname">WRKDIR</code>, and often it's the only directory entry
! 5171: that isn't hidden. This variable may be changed by a package
! 5172: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>.</p></dd>
! 5173: </dl></div>
! 5174: </div>
! 5175: <div class="sect1" lang="en">
! 5176: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5177: <a name="build.running"></a>14.4. Running a phase</h2></div></div></div>
! 5178: <p>You can run a particular phase by typing <span><strong class="command">make
! 5179: phase</strong></span>, where <span class="emphasis"><em>phase</em></span> is the name of the
! 5180: phase. This will automatically run all phases that are required for this
! 5181: phase. The default phase is <code class="varname">build</code>, that is, when you
! 5182: run <span><strong class="command">make</strong></span> without parameters in a package directory,
! 5183: the package will be built, but not installed.</p>
! 5184: </div>
! 5185: <div class="sect1" lang="en">
! 5186: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5187: <a name="build.fetch"></a>14.5. The <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
! 5188: <p>This will check if the file(s) given in the variables
! 5189: <code class="varname">DISTFILES</code> and <code class="varname">PATCHFILES</code> (as
! 5190: defined in the package's Makefile) are present on the
! 5191: local system in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkgsrc/distfiles</code>. If they
! 5192: are not present, an attempt will be made to fetch them using commands
! 5193: of the form:</p>
! 5194: <pre class="programlisting">
! 5195: ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
! 5196: </pre>
! 5197: <p>where ${site} varies through several possibilities in turn: first,
! 5198: <code class="varname">MASTER_SITE_OVERRIDE</code> is tried, then the sites
! 5199: specified in either <code class="varname">SITES.file</code> if defined, else
! 5200: <code class="varname">MASTER_SITES</code> or <code class="varname">PATCH_SITES</code>, as
! 5201: applies, then finally the value of
! 5202: <code class="varname">MASTER_SITE_BACKUP</code>. The order of all except the
! 5203: first can be optionally sorted by the user, via setting either
! 5204: <code class="varname">MASTER_SORT_AWK</code> or
! 5205: <code class="varname">MASTER_SORT_REGEX</code>.</p>
! 5206: </div>
! 5207: <div class="sect1" lang="en">
! 5208: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5209: <a name="build.checksum"></a>14.6. The <span class="emphasis"><em>checksum</em></span> phase</h2></div></div></div>
! 5210: <p>After the distfile(s) are fetched, their checksum is generated and
! 5211: compared with the checksums stored in the distinfo file. If the
! 5212: checksums don't match, the build is aborted. This is to ensure the same
! 5213: distfile is used for building, and that the distfile wasn't changed,
! 5214: e.g. by some malign force, deliberately changed distfiles on the master
! 5215: distribution site or network lossage.</p>
! 5216: </div>
! 5217: <div class="sect1" lang="en">
! 5218: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5219: <a name="build.extract"></a>14.7. The <span class="emphasis"><em>extract</em></span> phase</h2></div></div></div>
! 5220: <p>When the distfiles are present on the local system, they
! 5221: need to be extracted, as they usually come in the form of some
! 5222: compressed archive format.</p>
! 5223: <p>By default, all <code class="varname">DISTFILES</code> are
! 5224: extracted. If you only need some of them, you can set the
! 5225: <code class="varname">EXTRACT_ONLY</code> variable to the list of those
! 5226: files.</p>
! 5227: <p>Extracting the files is usually done by a little program,
! 5228: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/scripts/extract</code>, which already knows how
! 5229: to extract various archive formats, so most likely you will not
! 5230: need to change anything here. But if you need, the following
! 5231: variables may help you:</p>
! 5232: <div class="variablelist"><dl>
! 5233: <dt><span class="term"><code class="varname">EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</code></span></dt>
! 5234: <dd><p>Use these variables to override the default
! 5235: options for an extract command, which are defined in
! 5236: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/scripts/extract</code>.</p></dd>
! 5237: <dt><span class="term"><code class="varname">EXTRACT_USING</code></span></dt>
! 5238: <dd><p>This variable can be set to
! 5239: <code class="literal">pax</code>, <code class="literal">tar</code> or an absolute
! 5240: pathname pointing to the command with which tar archives should
! 5241: be extracted.</p></dd>
! 5242: </dl></div>
! 5243: <p>If the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">extract</code> program doesn't serve
! 5244: your needs, you can also override the
! 5245: <code class="varname">EXTRACT_CMD</code> variable, which holds the command
! 5246: used for extracting the files. This command is executed in the
! 5247: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${WRKSRC}</code> directory. During execution of
! 5248: this command, the shell variable <code class="varname">extract_file</code>
! 5249: holds the absolute pathname of the file that is going to be
! 5250: extracted.</p>
! 5251: <p>And if that still does not suffice, you can override the
! 5252: <code class="varname">do-extract</code> target in the package
! 5253: Makefile.</p>
! 5254: </div>
! 5255: <div class="sect1" lang="en">
! 5256: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5257: <a name="build.patch"></a>14.8. The <span class="emphasis"><em>patch</em></span> phase</h2></div></div></div>
! 5258: <p>After extraction, all the patches named by the
! 5259: <code class="varname">PATCHFILES</code>, those present in the patches
! 5260: subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
! 5261: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/local/patches/graphics/png</code>) are applied.
! 5262: Patchfiles ending in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.Z</code> or
! 5263: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.gz</code> are uncompressed before they are applied,
! 5264: files ending in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.orig</code> or
! 5265: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.rej</code> are ignored. Any special options to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a>
! 5266: can be handed in <code class="varname">PATCH_DIST_ARGS</code>.
! 5267: See <a href="#components.patches" title="8.3. patches/*">Section 8.3, “patches/*”</a> for more details.</p>
! 5268: <p>By default <a href="http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given special args to make it fail if the
! 5269: patches apply with some lines of fuzz. Please fix (regen) the patches
! 5270: so that they apply cleanly. The rationale behind this is that
! 5271: patches that don't apply cleanly may end up being applied in the wrong
! 5272: place, and cause severe harm there.</p>
! 5273: </div>
! 5274: <div class="sect1" lang="en">
! 5275: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5276: <a name="build.tools"></a>14.9. The <span class="emphasis"><em>tools</em></span> phase</h2></div></div></div>
! 5277: <p>This is covered in
! 5278: <a href="#tools" title="Chapter 15. Tools needed for building or running">Chapter 15, <i>Tools needed for building or running</i></a>.
! 5279: </p>
! 5280: </div>
! 5281: <div class="sect1" lang="en">
! 5282: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5283: <a name="build.wrapper"></a>14.10. The <span class="emphasis"><em>wrapper</em></span> phase</h2></div></div></div>
! 5284: <p>This phase creates wrapper programs for the compilers and
! 5285: linkers. The following variables can be used to tweak the
! 5286: wrappers.</p>
! 5287: <div class="variablelist"><dl>
! 5288: <dt><span class="term"><code class="varname">ECHO_WRAPPER_MSG</code></span></dt>
! 5289: <dd><p>The command used to print progress
! 5290: messages. Does nothing by default. Set to
! 5291: <code class="literal">${ECHO}</code> to see the progress
! 5292: messages.</p></dd>
! 5293: <dt><span class="term"><code class="varname">WRAPPER_DEBUG</code></span></dt>
! 5294: <dd><p>This variable can be set to
! 5295: <code class="literal">yes</code> (default) or
! 5296: <code class="literal">no</code>, depending on whether you want
! 5297: additional information in the wrapper log
! 5298: file.</p></dd>
! 5299: <dt><span class="term"><code class="varname">WRAPPER_UPDATE_CACHE</code></span></dt>
! 5300: <dd><p>This variable can be set to
! 5301: <code class="literal">yes</code> or <code class="literal">no</code>,
! 5302: depending on whether the wrapper should use its cache,
! 5303: which will improve the speed. The default value is
! 5304: <code class="literal">yes</code>, but is forced to
! 5305: <code class="literal">no</code> if the platform does not support
! 5306: it.</p></dd>
! 5307: <dt><span class="term"><code class="varname">WRAPPER_REORDER_CMDS</code></span></dt>
! 5308: <dd><p>A list of reordering commands. A
! 5309: reordering command has the form
! 5310: <code class="literal">reorder:l:<em class="replaceable"><code>lib1</code></em>:<em class="replaceable"><code>lib2</code></em></code>.
! 5311: It ensures that that
! 5312: <code class="literal">-l<em class="replaceable"><code>lib1</code></em></code>
! 5313: occurs before
! 5314: <code class="literal">-l<em class="replaceable"><code>lib2</code></em></code>.
! 5315: </p></dd>
! 5316: <dt><span class="term"><code class="varname">WRAPPER_TRANSFORM_CMDS</code></span></dt>
! 5317: <dd><p>A list of transformation commands. [TODO:
! 5318: investigate further]</p></dd>
! 5319: </dl></div>
! 5320: </div>
! 5321: <div class="sect1" lang="en">
! 5322: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5323: <a name="build.configure"></a>14.11. The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
! 5324: <p>Most pieces of software need information on the header files,
! 5325: system calls, and library routines which are available on the platform
! 5326: they run on. The process of determining this information is known as
! 5327: configuration, and is usually automated. In most cases, a script is
! 5328: supplied with the distfiles, and its invocation results in generation of
! 5329: header files, Makefiles, etc.</p>
! 5330: <p>If the package contains a configure script, this can be invoked by
! 5331: setting <code class="varname">HAS_CONFIGURE</code> to “<span class="quote">yes</span>”. If the
! 5332: configure script is a GNU autoconf script, you should set
! 5333: <code class="varname">GNU_CONFIGURE</code> to “<span class="quote">yes</span>” instead. What
! 5334: happens in the <span class="emphasis"><em>configure</em></span> phase is roughly:</p>
! 5335: <pre class="programlisting">
! 5336: .for d in ${CONFIGURE_DIRS}
! 5337: cd ${WRKSRC} && cd ${d} && env ${CONFIGURE_ENV} \
! 5338: ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
! 5339: .endfor
! 5340: </pre>
! 5341: <p><code class="varname">CONFIGURE_DIRS</code> (default: “<span class="quote">.</span>”) is a
! 5342: list of pathnames relative to <code class="varname">WRKSRC</code>. In each of
! 5343: these directories, the configure script is run with the environment
! 5344: <code class="varname">CONFIGURE_ENV</code> and arguments
! 5345: <code class="varname">CONFIGURE_ARGS</code>. The variables
! 5346: <code class="varname">CONFIGURE_ENV</code>, <code class="varname">CONFIGURE_SCRIPT</code>
! 5347: (default: “<span class="quote">./configure</span>”) and
! 5348: <code class="varname">CONFIGURE_ARGS</code> may all be changed by the
! 5349: package.</p>
! 5350: <p>If the program uses an <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Imakefile</code> for
! 5351: configuration, the appropriate steps can be invoked by setting
! 5352: <code class="varname">USE_IMAKE</code> to “<span class="quote">yes</span>”. (If you only want
! 5353: the package installed in <code class="varname">${X11PREFIX}</code> but xmkmf not
! 5354: being run, set <code class="varname">USE_X11BASE</code> instead.)</p>
! 5355: </div>
! 5356: <div class="sect1" lang="en">
! 5357: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5358: <a name="build.build"></a>14.12. The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
! 5359: <p>For building a package, a rough equivalent of the following code
! 5360: is executed.</p>
! 5361: <pre class="programlisting">
! 5362: .for d in ${BUILD_DIRS}
! 5363: cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
! 5364: ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
! 5365: -f ${MAKEFILE} ${BUILD_TARGET}
! 5366: .endfor
! 5367: </pre>
! 5368: <p><code class="varname">BUILD_DIRS</code> (default: “<span class="quote">.</span>”) is a
! 5369: list of pathnames relative to <code class="varname">WRKSRC</code>. In each of
! 5370: these directories, <code class="varname">MAKE_PROGRAM</code> is run with the
! 5371: environment <code class="varname">MAKE_ENV</code> and arguments
! 5372: <code class="varname">BUILD_MAKE_FLAGS</code>. The variables
! 5373: <code class="varname">MAKE_ENV</code>, <code class="varname">BUILD_MAKE_FLAGS</code>,
! 5374: <code class="varname">MAKEFILE</code> and <code class="varname">BUILD_TARGET</code> may all
! 5375: be changed by the package.</p>
! 5376: <p>The default value of <code class="varname">MAKE_PROGRAM</code> is
! 5377: “<span class="quote">gmake</span>” if <code class="varname">USE_TOOLS</code> contains
! 5378: “<span class="quote">gmake</span>”, “<span class="quote">make</span>” otherwise. The default value
! 5379: of <code class="varname">MAKEFILE</code> is “<span class="quote">Makefile</span>”, and
! 5380: <code class="varname">BUILD_TARGET</code> defaults to “<span class="quote">all</span>”.</p>
! 5381: </div>
! 5382: <div class="sect1" lang="en">
! 5383: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5384: <a name="build.test"></a>14.13. The <span class="emphasis"><em>test</em></span> phase</h2></div></div></div>
! 5385: <p>[TODO]</p>
! 5386: </div>
! 5387: <div class="sect1" lang="en">
! 5388: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5389: <a name="build.install"></a>14.14. The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
! 5390: <p>Once the build stage has completed, the final step is to
! 5391: install the software in public directories, so users can access
! 5392: the programs and files.</p>
! 5393: <p>In the <span class="emphasis"><em>install</em></span> phase, a rough
! 5394: equivalent of the following code is executed. Additionally,
! 5395: before and after this code, much magic is performed to do
! 5396: consistency checks, registering the package, and so on.</p>
! 5397: <pre class="programlisting">
! 5398: .for d in ${INSTALL_DIRS}
! 5399: cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
! 5400: ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
! 5401: -f ${MAKEFILE} ${BUILD_TARGET}
! 5402: .endfor
! 5403: </pre>
! 5404: <p>The variable's meanings are analogous to the ones in the
! 5405: <span class="emphasis"><em>build</em></span> phase.
! 5406: <code class="varname">INSTALL_DIRS</code> defaults to
! 5407: <code class="varname">BUILD_DIRS</code>. <code class="varname">INSTALL_TARGET</code>
! 5408: is “<span class="quote">install</span>” by default, plus
! 5409: “<span class="quote">install.man</span>” if <code class="varname">USE_IMAKE</code> is
! 5410: defined.</p>
! 5411: <p>In the <span class="emphasis"><em>install</em></span> phase, the following
! 5412: variables are useful. They are all variations of the
! 5413: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a> command that have the owner, group and
! 5414: permissions preset. <code class="varname">INSTALL</code> is the plain
! 5415: install command. The specialized variants, together with their
! 5416: intended use, are:</p>
! 5417: <div class="variablelist"><dl>
! 5418: <dt><span class="term"><code class="varname">INSTALL_PROGRAM_DIR</code></span></dt>
! 5419: <dd><p>directories that contain binaries</p></dd>
! 5420: <dt><span class="term"><code class="varname">INSTALL_SCRIPT_DIR</code></span></dt>
! 5421: <dd><p>directories that contain scripts</p></dd>
! 5422: <dt><span class="term"><code class="varname">INSTALL_LIB_DIR</code></span></dt>
! 5423: <dd><p>directories that contain shared and static libraries</p></dd>
! 5424: <dt><span class="term"><code class="varname">INSTALL_DATA_DIR</code></span></dt>
! 5425: <dd><p>directories that contain data files</p></dd>
! 5426: <dt><span class="term"><code class="varname">INSTALL_MAN_DIR</code></span></dt>
! 5427: <dd><p>directories that contain man pages</p></dd>
! 5428: <dt><span class="term"><code class="varname">INSTALL_PROGRAM</code></span></dt>
! 5429: <dd><p>binaries that can be stripped from debugging symbols</p></dd>
! 5430: <dt><span class="term"><code class="varname">INSTALL_SCRIPT</code></span></dt>
! 5431: <dd><p>binaries that cannot be stripped</p></dd>
! 5432: <dt><span class="term"><code class="varname">INSTALL_GAME</code></span></dt>
! 5433: <dd><p>game binaries</p></dd>
! 5434: <dt><span class="term"><code class="varname">INSTALL_LIB</code></span></dt>
! 5435: <dd><p>shared and static libraries</p></dd>
! 5436: <dt><span class="term"><code class="varname">INSTALL_DATA</code></span></dt>
! 5437: <dd><p>data files</p></dd>
! 5438: <dt><span class="term"><code class="varname">INSTALL_GAME_DATA</code></span></dt>
! 5439: <dd><p>data files for games</p></dd>
! 5440: <dt><span class="term"><code class="varname">INSTALL_MAN</code></span></dt>
! 5441: <dd><p>man pages</p></dd>
! 5442: </dl></div>
! 5443: <p>Some other variables are:</p>
! 5444: <div class="variablelist"><dl>
! 5445: <dt><span class="term"><code class="varname">INSTALLATION_DIRS</code></span></dt>
! 5446: <dd><p>A list of directories relative to
! 5447: <code class="varname">PREFIX</code> that are created by pkgsrc at
! 5448: the beginning of the <span class="emphasis"><em>install</em></span> phase. If
! 5449: this variable is set,
! 5450: <code class="varname">NO_MTREE</code>=“<span class="quote">yes</span>” is
! 5451: assumed, which means that the package claims to create
! 5452: all needed directories itself before installing files to
! 5453: it. Therefore this variable should only be set in
! 5454: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s that are under control of
! 5455: the package's author.</p></dd>
! 5456: </dl></div>
! 5457: </div>
! 5458: <div class="sect1" lang="en">
! 5459: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5460: <a name="build.package"></a>14.15. The <span class="emphasis"><em>package</em></span> phase</h2></div></div></div>
! 5461: <p>[TODO]</p>
! 5462: </div>
! 5463: <div class="sect1" lang="en">
! 5464: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5465: <a name="build.helpful-targets"></a>14.16. Other helpful targets</h2></div></div></div>
! 5466: <div class="variablelist"><dl>
! 5467: <dt><span class="term">pre/post-*</span></dt>
! 5468: <dd><p>For any of the main targets described in the previous section, two
! 5469: auxiliary targets exist with “<span class="quote">pre-</span>” and
! 5470: “<span class="quote">post-</span>” used as a prefix
! 5471: for the main target's name. These targets are invoked before and
! 5472: after the main target is called, allowing extra configuration or
! 5473: installation steps be performed from a package's Makefile, for
! 5474: example, which a program's configure script
! 5475: or install target omitted.</p></dd>
! 5476: <dt><span class="term">do-*</span></dt>
! 5477: <dd><p>Should one of the main targets do the wrong thing, and should there
! 5478: be no variable to fix this, you can redefine it with the do-*
! 5479: target. (Note that redefining the target itself instead of the
! 5480: do-* target is a bad idea, as the pre-* and post-* targets won't be
! 5481: called anymore, etc.) You will not usually need to do this.</p></dd>
! 5482: <dt><span class="term">reinstall</span></dt>
! 5483: <dd><p>If you did a <span><strong class="command">make install</strong></span> and you noticed some file
! 5484: was not installed properly, you can repeat the installation with this
! 5485: target, which will ignore the “<span class="quote">already installed</span>” flag.</p></dd>
! 5486: <dt><span class="term">deinstall</span></dt>
! 5487: <dd>
! 5488: <p>This target does a <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> in the current directory,
! 5489: effectively de-installing the package. The following variables can
! 5490: be used to tune the behaviour:</p>
! 5491: <div class="variablelist"><dl>
! 5492: <dt><span class="term"><code class="varname">PKG_VERBOSE</code></span></dt>
! 5493: <dd><p>Add a "-v" to the <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> command.</p></dd>
! 5494: <dt><span class="term"><code class="varname">DEINSTALLDEPENDS</code></span></dt>
! 5495: <dd><p>Remove all packages that require (depend on) the given package.
! 5496: This can be used to remove any packages that may have been pulled in
! 5497: by a given package, e.g. if <span><strong class="command">make deinstall
! 5498: DEINSTALLDEPENDS=1</strong></span> is done in
! 5499: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/x11/kde</code>, this is likely to remove whole
! 5500: KDE. Works by adding “<span class="quote">-R</span>” to the <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> command line.</p></dd>
! 5501: </dl></div>
! 5502: </dd>
! 5503: <dt><span class="term">update</span></dt>
! 5504: <dd>
! 5505: <p>This target causes the current package to be updated to the latest
! 5506: version. The package and all depending packages first get de-installed,
! 5507: then current versions of the corresponding packages get compiled and
! 5508: installed. This is similar to manually noting which packages are
! 5509: currently installed, then performing a series of <span><strong class="command">make
! 5510: deinstall</strong></span> and <span><strong class="command">make install</strong></span> (or whatever
! 5511: <code class="varname">UPDATE_TARGET</code> is set to) for these packages.</p>
! 5512: <p>You can use the “<span class="quote">update</span>” target to resume package
! 5513: updating in case a previous <span><strong class="command">make update</strong></span> was interrupted
! 5514: for some reason. However, in this case, make sure you don't call
! 5515: <span><strong class="command">make clean</strong></span> or otherwise remove the list of dependent
! 5516: packages in <code class="varname">WRKDIR</code>. Otherwise, you lose the
! 5517: ability to automatically update the current package along with the
! 5518: dependent packages you have installed.</p>
! 5519: <p>Resuming an interrupted <span><strong class="command">make update</strong></span> will only work as
! 5520: long as the package tree remains unchanged. If the source code for
! 5521: one of the packages to be updated has been changed, resuming
! 5522: <span><strong class="command">make update</strong></span> will most certainly fail!</p>
! 5523: <p>The following variables can be used either on the command line or in
! 5524: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to alter the behaviour of
! 5525: <span><strong class="command">make update</strong></span>:</p>
! 5526: <div class="variablelist"><dl>
! 5527: <dt><span class="term"><code class="varname">UPDATE_TARGET</code></span></dt>
! 5528: <dd><p>Install target to recursively use for the updated package and the
! 5529: dependent packages. Defaults to <code class="varname">DEPENDS_TARGET</code> if set,
! 5530: “<span class="quote">install</span>” otherwise for <span><strong class="command">make update</strong></span>.
! 5531: e.g. <span><strong class="command">make update UPDATE_TARGET=package</strong></span></p></dd>
! 5532: <dt><span class="term"><code class="varname">NOCLEAN</code></span></dt>
! 5533: <dd><p>Don't clean up after updating. Useful if you want to leave the
! 5534: work sources of the updated packages around for inspection or
! 5535: other purposes. Be sure you eventually clean up the source
! 5536: tree (see the “<span class="quote">clean-update</span>” target below) or you may
! 5537: run into troubles with old source code still lying around on your
! 5538: next <span><strong class="command">make</strong></span> or <span><strong class="command">make update</strong></span>.</p></dd>
! 5539: <dt><span class="term"><code class="varname">REINSTALL</code></span></dt>
! 5540: <dd><p>Deinstall each package before installing (making
! 5541: <code class="varname">DEPENDS_TARGET</code>). This may be necessary if the
! 5542: “<span class="quote">clean-update</span>” target (see below) was called after
! 5543: interrupting a running <span><strong class="command">make update</strong></span>.</p></dd>
! 5544: <dt><span class="term"><code class="varname">DEPENDS_TARGET</code></span></dt>
! 5545: <dd><p>Allows you to disable recursion and hardcode the target for
! 5546: packages. The default is “<span class="quote">update</span>” for the update target,
! 5547: facilitating a recursive update of prerequisite packages.
! 5548: Only set <code class="varname">DEPENDS_TARGET</code> if you want to disable
! 5549: recursive updates. Use <code class="varname">UPDATE_TARGET</code> instead to just
! 5550: set a specific target for each package to be installed during
! 5551: <span><strong class="command">make update</strong></span> (see above).</p></dd>
! 5552: </dl></div>
! 5553: </dd>
! 5554: <dt><span class="term">clean-update</span></dt>
! 5555: <dd>
! 5556: <p>Clean the source tree for all packages that would get updated if
! 5557: <span><strong class="command">make update</strong></span> was called from the current directory.
! 5558: This target should not be used if the current package (or any of its
! 5559: depending packages) have already been de-installed (e.g., after calling
! 5560: <span><strong class="command">make update</strong></span>) or you may lose some packages you intended
! 5561: to update. As a rule of thumb: only use this target
! 5562: <span class="emphasis"><em>before</em></span> the first time you run
! 5563: <span><strong class="command">make update</strong></span> and only if you have a dirty package tree
! 5564: (e.g., if you used <code class="varname">NOCLEAN</code>).</p>
! 5565: <p>If you are unsure about whether your tree is clean, you can either
! 5566: perform a <span><strong class="command">make clean</strong></span> at the top of the tree, or use
! 5567: the following sequence of commands from the directory of the package
! 5568: you want to update (<span class="emphasis"><em>before</em></span> running
! 5569: <span><strong class="command">make update</strong></span> for the first time, otherwise you lose
! 5570: all the packages you wanted to update!):</p>
! 5571: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make clean-update</code></strong>
! 5572: <code class="prompt">#</code> <strong class="userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
! 5573: <code class="prompt">#</code> <strong class="userinput"><code>make update</code></strong></pre>
! 5574: <p>The following variables can be used either on the command line or in
! 5575: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to alter the behaviour of
! 5576: <span><strong class="command">make clean-update</strong></span>:</p>
! 5577: <div class="variablelist"><dl>
! 5578: <dt><span class="term"><code class="varname">CLEAR_DIRLIST</code></span></dt>
! 5579: <dd><p>After <span><strong class="command">make clean</strong></span>, do not reconstruct the list of
! 5580: directories to update for this package. Only use this if <span><strong class="command">make
! 5581: update</strong></span> successfully installed all packages you wanted to
! 5582: update. Normally, this is done automatically on <span><strong class="command">make
! 5583: update</strong></span>, but may have been suppressed by the
! 5584: <code class="varname">NOCLEAN</code> variable (see above).</p></dd>
! 5585: </dl></div>
! 5586: </dd>
! 5587: <dt><span class="term">info</span></dt>
! 5588: <dd><p>This target invokes <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_info</span>(1)</span></a> for the current
! 5589: package. You can use this to check which version of a package is
! 5590: installed.</p></dd>
! 5591: <dt><span class="term">readme</span></dt>
! 5592: <dd><p>This target generates a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README.html</code> file, which
! 5593: can be viewed using a browser such as
! 5594: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html" target="_top"><code xmlns="" class="filename">www/mozilla</code></a> or
! 5595: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/links/README.html" target="_top"><code xmlns="" class="filename">www/links</code></a>.
! 5596: The generated files contain references to any
! 5597: packages which are in the <code class="varname">PACKAGES</code> directory on
! 5598: the local host. The generated files can be made to refer to URLs based on
! 5599: <code class="varname">FTP_PKG_URL_HOST</code> and
! 5600: <code class="varname">FTP_PKG_URL_DIR</code>. For example, if I wanted to generate
! 5601: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README.html</code> files which pointed to binary packages
! 5602: on the local machine, in the directory
! 5603: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/packages</code>, set
! 5604: <code class="varname">FTP_PKG_URL_HOST=file://localhost</code> and
! 5605: <code class="varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
! 5606: <code class="varname">${PACKAGES}</code> directory and its subdirectories will be
! 5607: searched for all the binary packages.</p></dd>
! 5608: <dt><span class="term">readme-all</span></dt>
! 5609: <dd><p>Use this target to create a file <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README-all.html</code>
! 5610: which contains a list of all packages currently available in the NetBSD
! 5611: Packages Collection, together with the category they belong to and a
! 5612: short description. This file is compiled from the
! 5613: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/*/README.html</code> files, so be sure to run
! 5614: this <span class="emphasis"><em>after</em></span> a <span><strong class="command">make readme</strong></span>.</p></dd>
! 5615: <dt><span class="term">cdrom-readme</span></dt>
! 5616: <dd><p>This is very much the same as the “<span class="quote">readme</span>” target (see
! 5617: above), but is to be used when generating a pkgsrc tree to be written
! 5618: to a CD-ROM. This target also produces
! 5619: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">README.html</code> files, and can be made to refer
! 5620: to URLs based on <code class="varname">CDROM_PKG_URL_HOST</code> and
! 5621: <code class="varname">CDROM_PKG_URL_DIR</code>.</p></dd>
! 5622: <dt><span class="term">show-distfiles</span></dt>
! 5623: <dd><p>This target shows which distfiles and patchfiles are needed to build
! 5624: the package. (<code class="varname">DISTFILES</code> and
! 5625: <code class="varname">PATCHFILES</code>, but not <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">patches/*</code>)</p></dd>
! 5626: <dt><span class="term">show-downlevel</span></dt>
! 5627: <dd><p>This target shows nothing if the package is not installed. If a version
! 5628: of this package is installed, but is not the version provided in this
! 5629: version of pkgsrc, then a warning message is displayed. This target can
! 5630: be used to show which of your installed packages are downlevel, and so
! 5631: the old versions can be deleted, and the current ones added.</p></dd>
! 5632: <dt><span class="term">show-pkgsrc-dir</span></dt>
! 5633: <dd><p>This target shows the directory in the pkgsrc hierarchy from which the
! 5634: package can be built and installed. This may not be the same directory
! 5635: as the one from which the package was installed. This target is intended
! 5636: to be used by people who may wish to upgrade many packages on a single
! 5637: host, and can be invoked from the top-level pkgsrc Makefile by using the
! 5638: “<span class="quote">show-host-specific-pkgs</span>” target.</p></dd>
! 5639: <dt><span class="term">show-installed-depends</span></dt>
! 5640: <dd><p>This target shows which installed packages match the current package's
! 5641: <code class="varname">DEPENDS</code>. Useful if out of date dependencies are
! 5642: causing build problems.</p></dd>
! 5643: <dt><span class="term">check-shlibs</span></dt>
! 5644: <dd><p>After a package is installed, check all its binaries and (on ELF
! 5645: platforms) shared libraries to see if they find the shared libs they need.
! 5646: Run by default if <code class="varname">PKG_DEVELOPER</code> is set in
! 5647: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>.</p></dd>
! 5648: <dt><span class="term">print-PLIST</span></dt>
! 5649: <dd>
! 5650: <p>After a “<span class="quote">make install</span>” from a new or
! 5651: upgraded pkg, this prints out an attempt to generate a new
! 5652: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> from a <span><strong class="command">find -newer
! 5653: work/.extract_done</strong></span>. An attempt is made to care
! 5654: for shared libs etc., but it is
! 5655: <span class="emphasis"><em>strongly</em></span> recommended to review the
! 5656: result before putting it into
! 5657: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>. On upgrades, it's useful to
! 5658: diff the output of this command against an already
! 5659: existing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file.</p>
! 5660: <p>If the package installs files via <a href="http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">tar</span>(1)</span></a> or other
! 5661: methods that don't update file access times, be sure to
! 5662: add these files manually to your
! 5663: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>, as the “<span class="quote">find
! 5664: -newer</span>” command used by this target won't catch
! 5665: them!</p>
! 5666: <p> See <a href="#print-PLIST" title="10.3. Tweaking output of make print-PLIST">Section 10.3, “Tweaking output of <span><strong class="command">make print-PLIST</strong></span>”</a> for more
! 5667: information on this target.</p>
! 5668: </dd>
! 5669: <dt><span class="term">bulk-package</span></dt>
! 5670: <dd>
! 5671: <p>Used to do bulk builds. If an appropriate binary package already exists,
! 5672: no action is taken. If not, this target will compile, install and
! 5673: package it (and its depends, if <code class="varname">PKG_DEPENDS</code> is
! 5674: set properly. See <a href="#binary.configuration" title="6.3.1. Configuration">Section 6.3.1, “Configuration”</a>).
! 5675: After creating the binary
! 5676: package, the sources, the just-installed package and its required
! 5677: packages are removed, preserving free disk space.</p>
! 5678: <p><span class="emphasis"><em>Beware that this target may deinstall all
! 5679: packages installed on a system!</em></span></p>
! 5680: </dd>
! 5681: <dt><span class="term">bulk-install</span></dt>
! 5682: <dd>
! 5683: <p>Used during bulk-installs to install required packages. If an
! 5684: up-to-date binary package is available, it will be installed via
! 5685: <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>. If not, <span><strong class="command">make bulk-package</strong></span> will be executed,
! 5686: but the installed binary won't be removed. </p>
! 5687: <p> A binary package is considered “<span class="quote">up-to-date</span>” to be
! 5688: installed via <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> if:</p>
! 5689: <div class="itemizedlist"><ul type="disc">
! 5690: <li><p>None of the package's files (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>,
! 5691: ...) were modified since it was built.</p></li>
! 5692: <li><p>None of the package's required (binary) packages were
! 5693: modified since it was built.</p></li>
! 5694: </ul></div>
! 5695: <p><span class="emphasis"><em>Beware that this target may deinstall all
! 5696: packages installed on a system!</em></span></p>
! 5697: </dd>
! 5698: </dl></div>
! 5699: </div>
! 5700: </div>
! 5701: <div class="chapter" lang="en">
! 5702: <div class="titlepage"><div><div><h2 class="title">
! 5703: <a name="tools"></a>Chapter 15. Tools needed for building or running</h2></div></div></div>
! 5704: <div class="toc">
! 5705: <p><b>Table of Contents</b></p>
! 5706: <dl>
! 5707: <dt><span class="sect1"><a href="#pkgsrc-tools">15.1. Tools for pkgsrc builds</a></span></dt>
! 5708: <dt><span class="sect1"><a href="#package-tools">15.2. Tools needed by packages</a></span></dt>
! 5709: <dt><span class="sect1"><a href="#platform-tools">15.3. Tools provided by platforms</a></span></dt>
! 5710: </dl>
! 5711: </div>
! 5712: <p>
! 5713: The <code class="varname">USE_TOOLS</code> definition is used both internally
! 5714: by pkgsrc and also for individual packages to define what commands
! 5715: are needed for building a package (like <code class="varname">BUILD_DEPENDS</code>)
! 5716: or for later run-time of an installed packaged (such as
! 5717: <code class="varname">DEPENDS</code>).
! 5718: If the native system provides an adequate tool, then in many cases, a pkgsrc
! 5719: package will not be used.
! 5720: </p>
! 5721: <p>
! 5722: When building a package, the replacement tools are
! 5723: made available in a directory (as symlinks or wrapper scripts)
! 5724: that is early in the executable search path. Just like the buildlink
! 5725: system, this helps with consistent builds.
! 5726: </p>
! 5727: <p>
! 5728: A tool may be needed to help build a specific package. For example,
! 5729: perl, GNU make (gmake) or yacc may be needed.
! 5730: </p>
! 5731: <p>
! 5732: Also a tool may be needed, for example, because the native system's supplied
! 5733: tool may be inefficient for building a package with pkgsrc.
! 5734: For example, a package may need GNU awk, bison (instead of
! 5735: yacc) or a better sed.
! 5736: </p>
! 5737: <p>
! 5738: The tools used by a package can be listed by running
! 5739: <span><strong class="command">make show-tools</strong></span>.
! 5740: </p>
! 5741: <div class="sect1" lang="en">
! 5742: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5743: <a name="pkgsrc-tools"></a>15.1. Tools for pkgsrc builds</h2></div></div></div>
! 5744: <p>
! 5745: The default set of tools used by pkgsrc is defined in
! 5746: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bsd.pkg.mk</code>. This includes standard Unix tools,
! 5747: such as: <span><strong class="command">cat</strong></span>, <span><strong class="command">awk</strong></span>,
! 5748: <span><strong class="command">chmod</strong></span>, <span><strong class="command">test</strong></span>, and so on.
! 5749: These can be seen by running:
! 5750: <span><strong class="command">make show-var VARNAME=USE_TOOLS</strong></span>.
! 5751: </p>
! 5752: <p>
! 5753: If a package needs a specific program to build
! 5754: then the <code class="varname">USE_TOOLS</code> variable can be used
! 5755: to define the tools needed.
! 5756: </p>
! 5757: </div>
! 5758: <div class="sect1" lang="en">
! 5759: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5760: <a name="package-tools"></a>15.2. Tools needed by packages</h2></div></div></div>
! 5761: <p>
! 5762: In the following examples, the :pkgsrc means to use the pkgsrc version
! 5763: and not the native version for a build dependency.
! 5764: And the :run means that it is used for a
! 5765: run-time dependencies also (and becomes a DEPENDS).
! 5766: The default is a build dependency which can be set with
! 5767: :build. (So in this example, it is the same as gmake:build
! 5768: and pkg-config:build.)
! 5769: </p>
! 5770: <pre class="programlisting">
! 5771: USE_TOOLS+= mktemp:pkgsrc
! 5772: USE_TOOLS+= gmake perl:run pkg-config
! 5773: </pre>
! 5774: <p>
! 5775: When using the tools framework, a
! 5776: <code class="varname">TOOLS_PATH.foo</code> variable is defined
! 5777: which contains the full path to the appropriate tool. For example,
! 5778: <code class="varname">TOOLS_PATH.bash</code> could be “<span class="quote">/bin/bash</span>”
! 5779: on Linux systems.
! 5780: </p>
! 5781: <p>
! 5782: If you always need a pkgsrc version of the
! 5783: tool at run-time, then just use <code class="varname">DEPENDS</code> instead.
! 5784:
! 5785: </p>
! 5786: </div>
! 5787: <div class="sect1" lang="en">
! 5788: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5789: <a name="platform-tools"></a>15.3. Tools provided by platforms</h2></div></div></div>
! 5790: <p>
! 5791: When improving or porting pkgsrc to a new platform, have a look
! 5792: at (or create) the corresponding platform specific make file fragment under
! 5793: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/tools/tools.${OPSYS}.mk</code> which defines
! 5794: the name of the common tools. For example:</p>
! 5795: <pre class="programlisting">
! 5796: .if exists(/usr/bin/bzcat)
! 5797: TOOLS_PLATFORM.bzcat?= /usr/bin/bzcat
! 5798: .elif exists(/usr/bin/bzip2)
! 5799: TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd
! 5800: .endif
1.69 rillig 5801:
1.75 ! rillig 5802: TOOLS_PLATFORM.true?= true # shell builtin
! 5803: </pre>
! 5804: </div>
! 5805: </div>
! 5806: <div class="chapter" lang="en">
! 5807: <div class="titlepage"><div><div><h2 class="title">
! 5808: <a name="fixes"></a>Chapter 16. Making your package work</h2></div></div></div>
! 5809: <div class="toc">
! 5810: <p><b>Table of Contents</b></p>
! 5811: <dl>
! 5812: <dt><span class="sect1"><a href="#general-operation">16.1. General operation</a></span></dt>
! 5813: <dd><dl>
! 5814: <dt><span class="sect2"><a href="#pulling-vars-from-etc-mk.conf">16.1.1. How to pull in variables from /etc/mk.conf</a></span></dt>
! 5815: <dt><span class="sect2"><a href="#where-to-install-documentation">16.1.2. Where to install documentation</a></span></dt>
! 5816: <dt><span class="sect2"><a href="#restricted-packages">16.1.3. Restricted packages</a></span></dt>
! 5817: <dt><span class="sect2"><a href="#dependencies">16.1.4. Handling dependencies</a></span></dt>
! 5818: <dt><span class="sect2"><a href="#conflicts">16.1.5. Handling conflicts with other packages</a></span></dt>
! 5819: <dt><span class="sect2"><a href="#not-building-packages">16.1.6. Packages that cannot or should not be built</a></span></dt>
! 5820: <dt><span class="sect2"><a href="#undeletable-packages">16.1.7. Packages which should not be deleted, once installed</a></span></dt>
! 5821: <dt><span class="sect2"><a href="#security-handling">16.1.8. Handling packages with security problems</a></span></dt>
! 5822: <dt><span class="sect2"><a href="#compiler-bugs">16.1.9. How to handle compiler bugs</a></span></dt>
! 5823: <dt><span class="sect2"><a href="#bumping-pkgrevision">16.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt>
! 5824: <dt><span class="sect2"><a href="#portability-of-packages">16.1.11. Portability of packages</a></span></dt>
! 5825: </dl></dd>
! 5826: <dt><span class="sect1"><a href="#downloading-issues">16.2. Possible downloading issues</a></span></dt>
! 5827: <dd><dl>
! 5828: <dt><span class="sect2"><a href="#no-plain-download">16.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt>
! 5829: <dt><span class="sect2"><a href="#modified-distfiles-same-name">16.2.2. How to handle modified distfiles with the 'old' name</a></span></dt>
! 5830: </dl></dd>
! 5831: <dt><span class="sect1"><a href="#configuration-gotchas">16.3. Configuration gotchas</a></span></dt>
! 5832: <dd><dl>
! 5833: <dt><span class="sect2"><a href="#fixes.libtool">16.3.1. Shared libraries - libtool</a></span></dt>
! 5834: <dt><span class="sect2"><a href="#using-libtool">16.3.2. Using libtool on GNU packages that already support libtool</a></span></dt>
! 5835: <dt><span class="sect2"><a href="#autoconf-automake">16.3.3. GNU Autoconf/Automake</a></span></dt>
! 5836: </dl></dd>
! 5837: <dt><span class="sect1"><a href="#fixes-build">16.4. Building the package</a></span></dt>
! 5838: <dd><dl>
! 5839: <dt><span class="sect2"><a href="#cpp-defines">16.4.1. CPP defines</a></span></dt>
! 5840: <dt><span class="sect2"><a href="#cpp-list-examples">16.4.2. Examples of CPP defines for some platforms</a></span></dt>
! 5841: <dt><span class="sect2"><a href="#cpp-list">16.4.3. Getting a list of CPP defines</a></span></dt>
! 5842: </dl></dd>
! 5843: <dt><span class="sect1"><a href="#package-specific-actions">16.5. Package specific actions</a></span></dt>
! 5844: <dd><dl>
! 5845: <dt><span class="sect2"><a href="#user-interaction">16.5.1. User interaction</a></span></dt>
! 5846: <dt><span class="sect2"><a href="#handling-licenses">16.5.2. Handling licenses</a></span></dt>
! 5847: <dt><span class="sect2"><a href="#installing-score-files">16.5.3. Installing score files</a></span></dt>
! 5848: <dt><span class="sect2"><a href="#perl-scripts">16.5.4. Packages containing perl scripts</a></span></dt>
! 5849: <dt><span class="sect2"><a href="#hardcoded-paths">16.5.5. Packages with hardcoded paths to other interpreters</a></span></dt>
! 5850: <dt><span class="sect2"><a href="#perl-modules">16.5.6. Packages installing perl modules</a></span></dt>
! 5851: <dt><span class="sect2"><a href="#faq.info-files">16.5.7. Packages installing info files</a></span></dt>
! 5852: <dt><span class="sect2"><a href="#manpages">16.5.8. Packages installing man pages</a></span></dt>
! 5853: <dt><span class="sect2"><a href="#gconf2-data-files">16.5.9. Packages installing GConf2 data files</a></span></dt>
! 5854: <dt><span class="sect2"><a href="#scrollkeeper-data-files">16.5.10. Packages installing scrollkeeper data files</a></span></dt>
! 5855: <dt><span class="sect2"><a href="#x11-fonts">16.5.11. Packages installing X11 fonts</a></span></dt>
! 5856: <dt><span class="sect2"><a href="#gtk2-modules">16.5.12. Packages installing GTK2 modules</a></span></dt>
! 5857: <dt><span class="sect2"><a href="#sgml-xml-data">16.5.13. Packages installing SGML or XML data</a></span></dt>
! 5858: <dt><span class="sect2"><a href="#mime-database">16.5.14. Packages installing extensions to the MIME database</a></span></dt>
! 5859: <dt><span class="sect2"><a href="#intltool">16.5.15. Packages using intltool</a></span></dt>
! 5860: <dt><span class="sect2"><a href="#startup-scripts">16.5.16. Packages installing startup scripts</a></span></dt>
! 5861: <dt><span class="sect2"><a href="#tex-packages">16.5.17. Packages installing TeX modules</a></span></dt>
! 5862: </dl></dd>
! 5863: <dt><span class="sect1"><a href="#feedback-to-author">16.6. Feedback to the author</a></span></dt>
! 5864: </dl>
! 5865: </div>
! 5866: <div class="sect1" lang="en">
! 5867: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 5868: <a name="general-operation"></a>16.1. General operation</h2></div></div></div>
! 5869: <div class="sect2" lang="en">
! 5870: <div class="titlepage"><div><div><h3 class="title">
! 5871: <a name="pulling-vars-from-etc-mk.conf"></a>16.1.1. How to pull in variables from /etc/mk.conf</h3></div></div></div>
! 5872: <p>The problem with package-defined variables that can be
! 5873: overridden via <code class="varname">MAKECONF</code> or
! 5874: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> is that <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> expands a
! 5875: variable as it is used, but evaluates preprocessor-like
! 5876: statements (.if, .ifdef and .ifndef) as they are read. So, to
! 5877: use any variable (which may be set in
! 5878: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>) in one of the .if*
! 5879: statements, the file <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> must be
! 5880: included before that .if* statement.</p>
! 5881: <p>Rather than having a number of ad-hoc ways of including
! 5882: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>, should it exist, or
! 5883: <code class="varname">MAKECONF</code>, should it exist, include the
! 5884: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/bsd.prefs.mk</code> file in the package
! 5885: Makefile before any preprocessor-like .if, .ifdef, or .ifndef
! 5886: statements:</p>
! 5887: <pre class="programlisting">
! 5888: .include "../../mk/bsd.prefs.mk"
1.69 rillig 5889:
1.75 ! rillig 5890: .if defined(USE_MENUS)
! 5891: # ...
! 5892: .endif
! 5893: </pre>
! 5894: <p>If you wish to set the <code class="varname">CFLAGS</code> variable
! 5895: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>, please make sure to use:
1.69 rillig 5896:
1.75 ! rillig 5897: </p>
! 5898: <pre class="programlisting">
! 5899: CFLAGS+= -your -flags
! 5900: </pre>
! 5901: <p>
1.69 rillig 5902:
1.75 ! rillig 5903: Using <code class="varname">CFLAGS=</code> (i.e. without the
! 5904: “<span class="quote">+</span>”) may lead to problems with packages that need
! 5905: to add their own flags. Also, you may want to take a look at
! 5906: the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html" target="_top"><code xmlns="" class="filename">devel/cpuflags</code></a> package if
! 5907: you're interested in optimization for the current CPU.</p>
! 5908: </div>
! 5909: <div class="sect2" lang="en">
! 5910: <div class="titlepage"><div><div><h3 class="title">
! 5911: <a name="where-to-install-documentation"></a>16.1.2. Where to install documentation</h3></div></div></div>
! 5912: <p>Documentation should be installed into
! 5913: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/doc/${PKGBASE}</code> or
! 5914: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/doc/${PKGNAME}</code> (the
! 5915: latter includes the version number of the package).</p>
! 5916: </div>
! 5917: <div class="sect2" lang="en">
! 5918: <div class="titlepage"><div><div><h3 class="title">
! 5919: <a name="restricted-packages"></a>16.1.3. Restricted packages</h3></div></div></div>
! 5920: <p>Some licenses restrict how software may be re-distributed.
! 5921: In order to satisfy these restrictions, the package system
! 5922: defines five make variables that can be set to note these
! 5923: restrictions:</p>
! 5924: <div class="itemizedlist"><ul type="disc">
! 5925: <li>
! 5926: <p><code class="varname">RESTRICTED</code></p>
! 5927: <p>This variable should be set whenever a restriction
! 5928: exists (regardless of its kind). Set this variable to a
! 5929: string containing the reason for the restriction.</p>
! 5930: </li>
! 5931: <li>
! 5932: <p><code class="varname">NO_BIN_ON_CDROM</code></p>
! 5933: <p>Binaries may not be placed on CD-ROM. Set this
! 5934: variable to <code class="varname">${RESTRICTED}</code> whenever a
! 5935: binary package may not be included on a CD-ROM.</p>
! 5936: </li>
! 5937: <li>
! 5938: <p><code class="varname">NO_BIN_ON_FTP</code></p>
! 5939: <p>Binaries may not be placed on an FTP server. Set
! 5940: this variable to <code class="varname">${RESTRICTED}</code>
! 5941: whenever a binary package may not not be made available
! 5942: on the Internet.</p>
! 5943: </li>
! 5944: <li>
! 5945: <p><code class="varname">NO_SRC_ON_CDROM</code></p>
! 5946: <p>Distfiles may not be placed on CD-ROM. Set this
! 5947: variable to <code class="varname">${RESTRICTED}</code> if
! 5948: re-distribution of the source code or other distfile(s) is
! 5949: not allowed on CD-ROMs.</p>
! 5950: </li>
! 5951: <li>
! 5952: <p><code class="varname">NO_SRC_ON_FTP</code></p>
! 5953: <p>Distfiles may not be placed on FTP. Set this variable
! 5954: to <code class="varname">${RESTRICTED}</code> if re-distribution of
! 5955: the source code or other distfile(s) via the Internet is not
! 5956: allowed.</p>
! 5957: </li>
! 5958: </ul></div>
! 5959: <p>Please note that the use of <code class="varname">NO_PACKAGE</code>,
! 5960: <code class="varname">IGNORE</code>, <code class="varname">NO_CDROM</code>, or other
! 5961: generic make variables to denote restrictions is deprecated,
! 5962: because they unconditionally prevent users from generating
! 5963: binary packages!</p>
! 5964: </div>
! 5965: <div class="sect2" lang="en">
! 5966: <div class="titlepage"><div><div><h3 class="title">
! 5967: <a name="dependencies"></a>16.1.4. Handling dependencies</h3></div></div></div>
! 5968: <p>Your package may depend on some other package being present
! 5969: - and there are various ways of expressing this
! 5970: dependency. pkgsrc supports the <code class="varname">BUILD_DEPENDS</code>
! 5971: and <code class="varname">DEPENDS</code> definitions, the
! 5972: <code class="varname">USE_TOOLS</code> definition, as well as
! 5973: dependencies via <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>, which is
! 5974: the preferred way to handle dependencies, and which uses the
! 5975: variables named above. See <a href="#buildlink" title="Chapter 11. Buildlink methodology">Chapter 11, <i>Buildlink methodology</i></a> for more
! 5976: information.</p>
! 5977: <p>The basic difference between the two variables is as
! 5978: follows: The <code class="varname">DEPENDS</code> definition registers
! 5979: that pre-requisite in the binary package so it will be pulled in
! 5980: when the binary package is later installed, whilst the
! 5981: <code class="varname">BUILD_DEPENDS</code> definition does not, marking a
! 5982: dependency that is only needed for building the package.
! 5983: </p>
! 5984: <p>This means that if you only need a package present whilst
! 5985: you are building, it should be noted as a
! 5986: <code class="varname">BUILD_DEPENDS</code>.</p>
! 5987: <p>The format for a <code class="varname">BUILD_DEPENDS</code> and a
! 5988: <code class="varname">DEPENDS</code> definition is:</p>
! 5989: <pre class="programlisting">
! 5990: <pre-req-package-name>:../../<category>/<pre-req-package>
! 5991: </pre>
! 5992: <p>Please note that the “<span class="quote">pre-req-package-name</span>”
! 5993: may include any of the wildcard version numbers recognized by
! 5994: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_info</span>(1)</span></a>.</p>
! 5995: <div class="orderedlist"><ol type="1">
! 5996: <li>
! 5997: <p>If your package needs another package's binaries or
! 5998: libraries to build or run, and if that package has a
! 5999: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file available, use it:
! 6000: </p>
! 6001: <pre class="programlisting">
! 6002: .include "../../graphics/jpeg/buildlink3.mk"
! 6003: </pre>
! 6004: </li>
! 6005: <li>
! 6006: <p>If your package needs to use another package to build
! 6007: itself and there is no <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code>
! 6008: file available, use the <code class="varname">BUILD_DEPENDS</code>
! 6009: definition:</p>
! 6010: <pre class="programlisting">
! 6011: BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
! 6012: </pre>
! 6013: </li>
! 6014: <li>
! 6015: <p>If your package needs a library with which to link and
! 6016: again there is no <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file
! 6017: available, this is specified using the
! 6018: <code class="varname">DEPENDS</code> definition. For example:</p>
! 6019: <pre class="programlisting">
! 6020: DEPENDS+= xpm-3.4j:../../graphics/xpm
! 6021: </pre>
! 6022: <p>You can also use wildcards in package dependences:</p>
! 6023: <pre class="programlisting">
! 6024: DEPENDS+= xpm-[0-9]*:../../graphics/xpm
! 6025: </pre>
! 6026: <p>Note that such wildcard dependencies are retained when
! 6027: creating binary packages. The dependency is checked when
! 6028: installing the binary package and any package which matches
! 6029: the pattern will be used. Wildcard dependencies should be
! 6030: used with care.</p>
! 6031: <p>The “<span class="quote">-[0-9]*</span>” should be used instead of
! 6032: “<span class="quote">-*</span>” to avoid potentially ambiguous matches
! 6033: such as “<span class="quote">tk-postgresql</span>” matching a
! 6034: “<span class="quote">tk-*</span>” <code class="varname">DEPENDS</code>.</p>
! 6035: <p>Wildcards can also be used to specify that a package
! 6036: will only build against a certain minimum version of a
! 6037: pre-requisite:</p>
! 6038: <pre class="programlisting">
! 6039: DEPENDS+= tiff>=3.5.4:../../graphics/tiff
! 6040: </pre>
! 6041: <p>This means that the package will build against version
! 6042: 3.5.4 of the tiff library or newer. Such a dependency may
! 6043: be warranted if, for example, the API of the library has
! 6044: changed with version 3.5.4 and a package would not compile
! 6045: against an earlier version of tiff.</p>
! 6046: <p>Please note that such dependencies should only be
! 6047: updated if a package requires a newer pre-requisite, but
! 6048: not to denote recommendations such as
! 6049: ABI changes that do not prevent a package from building
! 6050: correctly. Such recommendations can be expressed using
! 6051: <code class="varname">ABI_DEPENDS</code>:</p>
! 6052: <pre class="programlisting">
! 6053: ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff
! 6054: </pre>
! 6055: <p>In addition to the above <code class="varname">DEPENDS</code>
! 6056: line, this denotes that while a package will build against
! 6057: tiff>=3.5.4, at least version 3.6.1 is recommended.
! 6058: <code class="varname">ABI_DEPENDS</code> entries will be turned into
! 6059: dependencies unless explicitly ignored (in which case a
! 6060: warning will be printed).</p>
! 6061: <p>To ignore these ABI dependency recommendations and just
! 6062: use the required <code class="varname">DEPENDS</code>, set
! 6063: <code class="varname">USE_ABI_DEPENDS=NO</code>. This may make
! 6064: it easier and faster to update packages built using pkgsrc,
! 6065: since older compatible dependencies can continue to be
! 6066: used. This is useful for people who watch their rebuilds
! 6067: very carefully; it is not very good as a general-purpose
! 6068: hammer. If you use it, you need to be mindful of possible
! 6069: ABI changes, including those from the underlying OS.
! 6070: </p>
! 6071: <p>Packages that are built with recommendations ignored
! 6072: may not be uploaded to ftp.NetBSD.org by developers and
! 6073: should not be used across different systems that may have
! 6074: different versions of binary packages installed.</p>
! 6075: <p>For security fixes, please update the package
! 6076: vulnerabilities file. See <a href="#security-handling" title="16.1.8. Handling packages with security problems">Section 16.1.8, “Handling packages with security problems”</a> for more
! 6077: information.</p>
! 6078: </li>
! 6079: <li>
! 6080: <p>If your package needs some executable to be able to run
! 6081: correctly and if there's no
! 6082: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file, this is specified
! 6083: using the <code class="varname">DEPENDS</code> variable. The
! 6084: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/lyx/README.html" target="_top"><code xmlns="" class="filename">print/lyx</code></a> package needs to
! 6085: be able to execute the latex binary from the teTeX package
! 6086: when it runs, and that is specified:</p>
! 6087: <pre class="programlisting">
! 6088: DEPENDS+= teTeX-[0-9]*:../../print/teTeX
! 6089: </pre>
! 6090: <p>The comment about wildcard dependencies from previous
! 6091: paragraph applies here, too.</p>
! 6092: </li>
! 6093: </ol></div>
! 6094: <p>If your package needs files from another package to build,
! 6095: add the relevant distribution files to
! 6096: <code class="varname">DISTFILES</code>, so they will be extracted
! 6097: automatically. See the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/ghostscript/README.html" target="_top"><code xmlns="" class="filename">print/ghostscript</code></a> package for an example.
! 6098: (It relies on the jpeg sources being present in source form
! 6099: during the build.)</p>
! 6100: <p>Please also note the <code class="varname">BUILD_USES_MSGFMT</code>
! 6101: and <code class="varname">BUILD_USES_GETTEXT_M4</code> definitions, which
! 6102: are provided as convenience definitions. The former works out
! 6103: whether <a href="http://netbsd.gw.com/cgi-bin/man-cgi?msgfmt+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">msgfmt</span>(1)</span></a> is part of the base system, and, if it isn't,
! 6104: installs the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext/README.html" target="_top"><code xmlns="" class="filename">devel/gettext</code></a> package.
! 6105: The latter adds a build dependency on either an installed
! 6106: version of an older gettext package, or if it isn't, installs the
! 6107: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext-m4/README.html" target="_top"><code xmlns="" class="filename">devel/gettext-m4</code></a> package.</p>
! 6108: </div>
! 6109: <div class="sect2" lang="en">
! 6110: <div class="titlepage"><div><div><h3 class="title">
! 6111: <a name="conflicts"></a>16.1.5. Handling conflicts with other packages</h3></div></div></div>
! 6112: <p>Your package may conflict with other packages a user might
! 6113: already have installed on his system, e.g. if your package
! 6114: installs the same set of files like another package in our
! 6115: pkgsrc tree.</p>
! 6116: <p>In this case you can set <code class="varname">CONFLICTS</code> to a
! 6117: space-separated list of packages (including version string) your
! 6118: package conflicts with.</p>
! 6119: <p>For example, <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw3d/README.html" target="_top"><code xmlns="" class="filename">x11/Xaw3d</code></a>
! 6120: and <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw-Xpm/README.html" target="_top"><code xmlns="" class="filename">x11/Xaw-Xpm</code></a>
! 6121: install the same shared library, thus you set in
! 6122: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/x11/Xaw3d/Makefile</code>:</p>
! 6123: <pre class="programlisting">
! 6124: CONFLICTS= Xaw-Xpm-[0-9]*
! 6125: </pre>
! 6126: <p>and in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/x11/Xaw-Xpm/Makefile</code>:
! 6127: </p>
! 6128: <pre class="programlisting">
! 6129: CONFLICTS= Xaw3d-[0-9]*
! 6130: </pre>
! 6131: <p>Packages will automatically conflict with other packages
! 6132: with the name prefix and a different version
! 6133: string. “<span class="quote">Xaw3d-1.5</span>” e.g. will automatically
! 6134: conflict with the older version “<span class="quote">Xaw3d-1.3</span>”.
! 6135: </p>
! 6136: </div>
! 6137: <div class="sect2" lang="en">
! 6138: <div class="titlepage"><div><div><h3 class="title">
! 6139: <a name="not-building-packages"></a>16.1.6. Packages that cannot or should not be built</h3></div></div></div>
! 6140: <p>There are several reasons why a package might be
! 6141: instructed to not build under certain circumstances. If the
! 6142: package builds and runs on most platforms, the exceptions
! 6143: should be noted with <code class="varname">NOT_FOR_PLATFORM</code>. If
! 6144: the package builds and runs on a small handful of platforms,
! 6145: set <code class="varname">ONLY_FOR_PLATFORM</code> instead.
! 6146: Both <code class="varname">ONLY_FOR_PLATFORM</code> and
! 6147: <code class="varname">NOT_FOR_PLATFORM</code> are OS triples
! 6148: (OS-version-platform) that can use glob-style
! 6149: wildcards.</p>
! 6150: <p>If the package should be skipped (for example, because it
! 6151: provides functionality already provided by the system), set
! 6152: <code class="varname">PKG_SKIP_REASON</code> to a descriptive message.
! 6153: If the package should fail because some preconditions are not
! 6154: met, set <code class="varname">PKG_FAIL_REASON</code> to a descriptive
! 6155: message.</p>
! 6156: </div>
! 6157: <div class="sect2" lang="en">
! 6158: <div class="titlepage"><div><div><h3 class="title">
! 6159: <a name="undeletable-packages"></a>16.1.7. Packages which should not be deleted, once installed</h3></div></div></div>
! 6160: <p>To ensure that a package may not be deleted, once it has been
! 6161: installed, the <code class="varname">PKG_PRESERVE</code> definition should
! 6162: be set in the package Makefile. This will be carried into any
! 6163: binary package that is made from this pkgsrc entry. A
! 6164: “<span class="quote">preserved</span>” package will
! 6165: not be deleted using <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> unless the
! 6166: “<span class="quote">-f</span>” option is used.</p>
! 6167: </div>
! 6168: <div class="sect2" lang="en">
! 6169: <div class="titlepage"><div><div><h3 class="title">
! 6170: <a name="security-handling"></a>16.1.8. Handling packages with security problems</h3></div></div></div>
! 6171: <p>When a vulnerability is found, this should be noted in
! 6172: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">localsrc/security/advisories/pkg-vulnerabilities</code>,
! 6173: and after committing that file, use <span><strong class="command">make upload</strong></span>
! 6174: in the same directory to update the file on ftp.NetBSD.org.</p>
! 6175: <p>After fixing the vulnerability by a patch, its
! 6176: <code class="varname">PKGREVISION</code> should be increased (this
! 6177: is of course not necessary if the problem is fixed by using
! 6178: a newer release of the software).</p>
! 6179: <p>Also, if the fix should be applied to the stable pkgsrc
! 6180: branch, be sure to submit a pullup request!</p>
! 6181: <p>Binary packages already on ftp.NetBSD.org will be handled
! 6182: semi-automatically by a weekly cron job.</p>
! 6183: </div>
! 6184: <div class="sect2" lang="en">
! 6185: <div class="titlepage"><div><div><h3 class="title">
! 6186: <a name="compiler-bugs"></a>16.1.9. How to handle compiler bugs</h3></div></div></div>
! 6187: <p>Some source files trigger bugs in the compiler, based on
! 6188: combinations of compiler version and architecture and almost
! 6189: always relation to optimisation being enabled. Common symptoms
! 6190: are gcc internal errors or never finishing compiling a file.
! 6191: </p>
! 6192: <p>Typically, a workaround involves testing the
! 6193: <code class="varname">MACHINE_ARCH</code> and compiler version, disabling
! 6194: optimisation for that
! 6195: file/<code class="varname">MACHINE_ARCH</code>/compiler combination, and
! 6196: documenting it in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/HACKS</code>. See
! 6197: that file for a number of examples!</p>
! 6198: </div>
! 6199: <div class="sect2" lang="en">
! 6200: <div class="titlepage"><div><div><h3 class="title">
! 6201: <a name="bumping-pkgrevision"></a>16.1.10. How to handle incrementing versions when fixing an existing package</h3></div></div></div>
! 6202: <p>When making fixes to an existing package it can be useful
! 6203: to change the version number in <code class="varname">PKGNAME</code>. To
! 6204: avoid conflicting with future versions by the original author, a
! 6205: “<span class="quote">nb1</span>”, “<span class="quote">nb2</span>”, ... suffix can be used
! 6206: on package versions by setting <code class="varname">PKGREVISION=1</code>
! 6207: (2, ...). The “<span class="quote">nb</span>” is treated like a
! 6208: “<span class="quote">.</span>” by the pkg tools. e.g.</p>
! 6209: <pre class="programlisting">
! 6210: DISTNAME= foo-17.42
! 6211: PKGREVISION= 9
! 6212: </pre>
! 6213: <p>will result in a <code class="varname">PKGNAME</code> of
! 6214: “<span class="quote">foo-17.42nb9</span>”.</p>
! 6215: <p>When a new release of the package is released, the
! 6216: <code class="varname">PKGREVISION</code> should be removed, e.g. on a new
! 6217: minor release of the above package, things should be like:</p>
! 6218: <pre class="programlisting">
! 6219: DISTNAME= foo-17.43
! 6220: </pre>
! 6221: </div>
! 6222: <div class="sect2" lang="en">
! 6223: <div class="titlepage"><div><div><h3 class="title">
! 6224: <a name="portability-of-packages"></a>16.1.11. Portability of packages</h3></div></div></div>
! 6225: <p>One appealing feature of pkgsrc is that it runs on many different
! 6226: platforms. As a result, it is important to ensure, where possible,
! 6227: that packages in pkgsrc are portable. There are some particular
! 6228: details you should pay attention to while working on pkgsrc.</p>
! 6229: <div class="sect3" lang="en">
! 6230: <div class="titlepage"><div><div><h4 class="title">
! 6231: <a name="install-scripts"></a>16.1.11.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ...</h4></div></div></div>
! 6232: <p>The BSD-compatible <span><strong class="command">install</strong></span> supplied with some
! 6233: operating systems will not perform more than one operation at a time.
! 6234: As such, you should call “<span class="quote">${INSTALL}</span>”, etc. like this:</p>
! 6235: <pre class="programlisting">
! 6236: ${INSTALL_DATA_DIR} ${PREFIX}/dir1
! 6237: ${INSTALL_DATA_DIR} ${PREFIX}/dir2
! 6238: </pre>
! 6239: </div>
! 6240: </div>
! 6241: </div>
! 6242: <div class="sect1" lang="en">
! 6243: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 6244: <a name="downloading-issues"></a>16.2. Possible downloading issues</h2></div></div></div>
! 6245: <div class="sect2" lang="en">
! 6246: <div class="titlepage"><div><div><h3 class="title">
! 6247: <a name="no-plain-download"></a>16.2.1. Packages whose distfiles aren't available for plain downloading</h3></div></div></div>
! 6248: <p>If you need to download from a dynamic URL you can set
! 6249: <code class="varname">DYNAMIC_MASTER_SITES</code> and a <span><strong class="command">make
! 6250: fetch</strong></span> will call <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">files/getsite.sh</code>
! 6251: with the name of each file to download as an argument, expecting
! 6252: it to output the URL of the directory from which to download
! 6253: it. <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/ns-cult3d/README.html" target="_top"><code xmlns="" class="filename">graphics/ns-cult3d</code></a> is an
! 6254: example of this usage.
! 6255: </p>
! 6256: <p>If the download can't be automated, because the user must
! 6257: submit personal information to apply for a password, or must pay
! 6258: for the source, or whatever, you can set
! 6259: <code class="varname">FETCH_MESSAGE</code> to a list of lines that are
! 6260: displayed to the user before aborting the build. Example:</p>
! 6261: <pre class="programlisting">
! 6262: FETCH_MESSAGE= "Please download the files"
! 6263: FETCH_MESSAGE+= " "${DISTFILES:Q}
! 6264: FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
! 6265: </pre>
! 6266: </div>
! 6267: <div class="sect2" lang="en">
! 6268: <div class="titlepage"><div><div><h3 class="title">
! 6269: <a name="modified-distfiles-same-name"></a>16.2.2. How to handle modified distfiles with the 'old' name</h3></div></div></div>
! 6270: <p>Sometimes authors of a software package make some
! 6271: modifications after the software was released, and they put up a
! 6272: new distfile without changing the package's version number. If a
! 6273: package is already in pkgsrc at that time, the checksum will
! 6274: no longer match. The contents of the new distfile should be
! 6275: compared against the old one before changing anything, to make
! 6276: sure the distfile was really updated on purpose, and that
! 6277: no trojan horse or so crept in.
! 6278: Then, the correct way to work around this is to
! 6279: set <code class="varname">DIST_SUBDIR</code> to a unique directory name,
! 6280: usually based on <code class="varname">PKGNAME_NOREV</code>. In case this
! 6281: happens more often, <code class="varname">PKGNAME</code> can be used (thus
! 6282: including the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">nbX</code> suffix) or a date stamp
! 6283: can be appended, like <code class="varname">${PKGNAME_NOREV}-YYYYMMDD</code>.
! 6284: Do not forget regenerating the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code> file
! 6285: after that, since it contains the <code class="varname">DIST_SUBDIR</code>
! 6286: path in the filenames.
! 6287: Furthermore, a mail to the package's authors seems appropriate
! 6288: telling them that changing distfiles after releases without
! 6289: changing the file names is not good practice.</p>
! 6290: </div>
! 6291: </div>
! 6292: <div class="sect1" lang="en">
! 6293: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 6294: <a name="configuration-gotchas"></a>16.3. Configuration gotchas</h2></div></div></div>
! 6295: <div class="sect2" lang="en">
! 6296: <div class="titlepage"><div><div><h3 class="title">
! 6297: <a name="fixes.libtool"></a>16.3.1. Shared libraries - libtool</h3></div></div></div>
! 6298: <p>pkgsrc supports many different machines, with different
! 6299: object formats like a.out and ELF, and varying abilities to do
! 6300: shared library and dynamic loading at all. To accompany this,
! 6301: varying commands and options have to be passed to the
! 6302: compiler, linker, etc. to get the Right Thing, which can be
! 6303: pretty annoying especially if you don't have all the machines
! 6304: at your hand to test things. The
! 6305: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool/README.html" target="_top"><code xmlns="" class="filename">devel/libtool</code></a> pkg
! 6306: can help here, as it just “<span class="quote">knows</span>” how to build
! 6307: both static and dynamic libraries from a set of source files,
! 6308: thus being platform-independent.</p>
! 6309: <p>Here's how to use libtool in a pkg in seven simple
! 6310: steps:</p>
! 6311: <div class="orderedlist"><ol type="1">
! 6312: <li><p>Add <code class="varname">USE_LIBTOOL=yes</code> to the package
! 6313: Makefile.</p></li>
! 6314: <li><p>For library objects, use “<span class="quote">${LIBTOOL} --mode=compile
! 6315: ${CC}</span>” in place of “<span class="quote">${CC}</span>”. You could even
! 6316: add it to the definition of <code class="varname">CC</code>, if only
! 6317: libraries are being built in a given Makefile. This one command
! 6318: will build both PIC and non-PIC library objects, so you need not
! 6319: have separate shared and non-shared library rules.</p></li>
! 6320: <li>
! 6321: <p>For the linking of the library, remove any
! 6322: “<span class="quote">ar</span>”, “<span class="quote">ranlib</span>”, and “<span class="quote">ld
! 6323: -Bshareable</span>” commands, and instead use:</p>
! 6324: <pre class="programlisting">
! 6325: ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \
! 6326: -rpath ${PREFIX}/lib -version-info major:minor
! 6327: </pre>
! 6328: <p>Note that the library is changed to have a
! 6329: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.la</code> extension, and the objects are
! 6330: changed to have a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.lo</code>
! 6331: extension. Change <code class="varname">OBJS</code> as
! 6332: necessary. This automatically creates all of the
! 6333: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.a</code>,
! 6334: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.so.major.minor</code>, and ELF symlinks (if
! 6335: necessary) in the build directory. Be sure to include
! 6336: “<span class="quote">-version-info</span>”, especially when major and
! 6337: minor are zero, as libtool will otherwise strip off the
! 6338: shared library version.</p>
! 6339: <p>From the libtool manual:</p>
! 6340: <pre class="programlisting">
! 6341: So, libtool library versions are described by three integers:
1.69 rillig 6342:
1.75 ! rillig 6343: CURRENT
! 6344: The most recent interface number that this library implements.
1.69 rillig 6345:
1.75 ! rillig 6346: REVISION
! 6347: The implementation number of the CURRENT interface.
1.69 rillig 6348:
1.75 ! rillig 6349: AGE
! 6350: The difference between the newest and oldest interfaces that
! 6351: this library implements. In other words, the library implements
! 6352: all the interface numbers in the range from number `CURRENT -
! 6353: AGE' to `CURRENT'.
1.1 grant 6354:
1.75 ! rillig 6355: If two libraries have identical CURRENT and AGE numbers, then the
! 6356: dynamic linker chooses the library with the greater REVISION number.
! 6357: </pre>
! 6358: <p>The “<span class="quote">-release</span>” option will produce
! 6359: different results for a.out and ELF (excluding symlinks)
! 6360: in only one case. An ELF library of the form
! 6361: “<span class="quote">libfoo-release.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”
! 6362: will have a symlink of
! 6363: “<span class="quote">libfoo.so.<span class="emphasis"><em>x</em></span>.<span class="emphasis"><em>y</em></span></span>”
! 6364: on an a.out platform. This is handled
! 6365: automatically.</p>
! 6366: <p>The “<span class="quote">-rpath argument</span>” is the install
! 6367: directory of the library being built.</p>
! 6368: <p>In the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>, include only the
! 6369: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.la</code> file, the other files will be
! 6370: added automatically.</p>
! 6371: </li>
! 6372: <li>
! 6373: <p>When linking shared object (<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.so</code>)
! 6374: files, i.e. files that are loaded via <a href="http://netbsd.gw.com/cgi-bin/man-cgi?dlopen+3+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">dlopen</span>(3)</span></a>, NOT
! 6375: shared libraries, use “<span class="quote">-module
! 6376: -avoid-version</span>” to prevent them getting version
! 6377: tacked on.</p>
! 6378: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> file gets the
! 6379: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">foo.so</code> entry.</p>
! 6380: </li>
! 6381: <li>
! 6382: <p>When linking programs that depend on these libraries
! 6383: <span class="emphasis"><em>before</em></span> they are installed, preface
! 6384: the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cc+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cc</span>(1)</span></a> or <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ld</span>(1)</span></a> line with “<span class="quote">${LIBTOOL}
! 6385: --mode=link</span>”, and it will find the correct
! 6386: libraries (static or shared), but please be aware that
! 6387: libtool will not allow you to specify a relative path in
! 6388: -L (such as “<span class="quote">-L../somelib</span>”), because it
! 6389: expects you to change that argument to be the
! 6390: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.la</code> file. e.g.</p>
! 6391: <pre class="programlisting">
! 6392: ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
! 6393: </pre>
! 6394: <p>should be changed to:</p>
! 6395: <pre class="programlisting">
! 6396: ${LIBTOOL} --mode=link ${CC} -o <em class="replaceable"><code>someprog</code></em> <em class="replaceable"><code>../somelib/somelib.la</code></em>
! 6397: </pre>
! 6398: <p>and it will do the right thing with the libraries.</p>
! 6399: </li>
! 6400: <li>
! 6401: <p>When installing libraries, preface the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a>
! 6402: or <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cp+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">cp</span>(1)</span></a> command with “<span class="quote">${LIBTOOL}
! 6403: --mode=install</span>”, and change the library name to
! 6404: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.la</code>. e.g.</p>
! 6405: <pre class="programlisting">
! 6406: ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
! 6407: </pre>
! 6408: <p>This will install the static <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.a</code>,
! 6409: shared library, any needed symlinks, and run
! 6410: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ldconfig+8+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">ldconfig</span>(8)</span></a>.</p>
! 6411: </li>
! 6412: <li><p>In your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>, include only
! 6413: the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.la</code>
! 6414: file (this is a change from previous behaviour).</p></li>
! 6415: </ol></div>
! 6416: </div>
! 6417: <div class="sect2" lang="en">
! 6418: <div class="titlepage"><div><div><h3 class="title">
! 6419: <a name="using-libtool"></a>16.3.2. Using libtool on GNU packages that already support libtool</h3></div></div></div>
! 6420: <p>Add <code class="varname">USE_LIBTOOL=yes</code> to the
! 6421: package Makefile. This will override the package's own libtool
! 6422: in most cases. For older libtool using packages, libtool is
! 6423: made by ltconfig script during the do-configure step; you can
! 6424: check the libtool script location by doing <span><strong class="command">make
! 6425: configure; find work*/ -name libtool</strong></span>.</p>
! 6426: <p><code class="varname">LIBTOOL_OVERRIDE</code> specifies which libtool
! 6427: scripts, relative to <code class="varname">WRKSRC</code>, to override. By
! 6428: default, it is set to “<span class="quote">libtool */libtool
! 6429: */*/libtool</span>”. If this does not match the location of the
! 6430: package's libtool script(s), set it as appropriate.</p>
! 6431: <p>If you do not need <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">*.a</code> static
! 6432: libraries built and installed, then use
! 6433: <code class="varname">SHLIBTOOL_OVERRIDE</code> instead.</p>
! 6434: <p>If your package makes use of the platform-independent library
! 6435: for loading dynamic shared objects, that comes with libtool
! 6436: (libltdl), you should include devel/libltdl/buildlink3.mk.</p>
! 6437: <p>Some packages use libtool incorrectly so that the package may not work or
! 6438: build in some circumstances. Some of the more common errors are:</p>
! 6439: <div class="itemizedlist"><ul type="disc">
! 6440: <li>
! 6441: <p>The inclusion of a shared object (-module) as a dependent library in an
! 6442: executable or library. This in itself isn't a problem if one of two things
! 6443: has been done:</p>
! 6444: <div class="orderedlist"><ol type="1">
! 6445: <li><p>The shared object is named correctly, i.e.
! 6446: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libfoo.la</code>, not
! 6447: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">foo.la</code></p></li>
! 6448: <li><p>The -dlopen option is used when linking an executable.</p></li>
! 6449: </ol></div>
! 6450: </li>
! 6451: <li><p>The use of libltdl without the correct calls to initialisation routines.
! 6452: The function lt_dlinit() should be called and the macro
! 6453: <code class="varname">LTDL_SET_PRELOADED_SYMBOLS</code> included in
! 6454: executables.</p></li>
! 6455: </ul></div>
! 6456: </div>
! 6457: <div class="sect2" lang="en">
! 6458: <div class="titlepage"><div><div><h3 class="title">
! 6459: <a name="autoconf-automake"></a>16.3.3. GNU Autoconf/Automake</h3></div></div></div>
! 6460: <p>If a package needs GNU autoconf or automake to be executed
! 6461: to regenerate the configure script and Makefile.in makefile
! 6462: templates, then they should be executed in a pre-configure
! 6463: target.</p>
! 6464: <p>For packages that need only autoconf:</p>
! 6465: <pre class="programlisting">
! 6466: AUTOCONF_REQD= 2.50 # if default version is not good enough
! 6467: USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
! 6468: ...
1.1 grant 6469:
1.75 ! rillig 6470: pre-configure:
! 6471: cd ${WRKSRC}; autoconf
1.1 grant 6472:
1.75 ! rillig 6473: ...
! 6474: </pre>
! 6475: <p>and for packages that need automake and autoconf:</p>
! 6476: <pre class="programlisting">
! 6477: AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
! 6478: USE_TOOLS+= automake # use "automake14" for automake-1.4
! 6479: ...
1.1 grant 6480:
1.75 ! rillig 6481: pre-configure:
! 6482: cd ${WRKSRC}; \
! 6483: aclocal; autoheader; \
! 6484: automake -a --foreign -i; autoconf
1.1 grant 6485:
1.75 ! rillig 6486: ...
! 6487: </pre>
! 6488: <p>Packages which use GNU Automake will almost certainly
! 6489: require GNU Make.</p>
! 6490: <p>There are times when the configure process makes
! 6491: additional changes to the generated files, which then causes
! 6492: the build process to try to re-execute the automake sequence.
! 6493: This is prevented by touching various files in the configure
! 6494: stage. If this causes problems with your package you can set
! 6495: <code class="varname">AUTOMAKE_OVERRIDE=NO</code> in the package
! 6496: Makefile.</p>
! 6497: </div>
! 6498: </div>
! 6499: <div class="sect1" lang="en">
! 6500: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 6501: <a name="fixes-build"></a>16.4. Building the package</h2></div></div></div>
! 6502: <div class="sect2" lang="en">
! 6503: <div class="titlepage"><div><div><h3 class="title">
! 6504: <a name="cpp-defines"></a>16.4.1. CPP defines</h3></div></div></div>
! 6505: <p>Sometimes you need to compile different code depending on
! 6506: the target platform. The C preprocessor has a set of predefined
! 6507: macros that can be queried by using <code class="varname">#ifdef FOO</code>
! 6508: or <code class="varname">#if defined(FOO)</code>. Among these macros are
! 6509: usually ones that describe the target CPU and operating system.
! 6510: Depending of which of the macros are defined, you can write code
! 6511: that uses features unique to a specific platform. Generally you
! 6512: should rather use the GNU autotools (automake, autoconf, etc.) to
! 6513: check for specific features (like the existence of a header file,
! 6514: a function or a library), but sometimes this is not possible or
! 6515: desired.</p>
! 6516: <p>In that case you can use the predefined macros
! 6517: below to configure your code to the platform it runs on. Almost
! 6518: every operating system, hardware architecture and compiler has its
! 6519: own macro. For example, if the macros <code class="varname">__GNUC__</code>,
! 6520: <code class="varname">__i386__</code> and <code class="varname">__NetBSD__</code> are
! 6521: all defined, you know that you are using NetBSD on an i386
! 6522: compatible CPU, and your compiler is GCC.</p>
! 6523: <div class="sect3" lang="en">
! 6524: <div class="titlepage"><div><div><h4 class="title">
! 6525: <a name="fixes-build-cpp-opsys"></a>16.4.1.1. CPP defines for operating systems</h4></div></div></div>
! 6526: <p>To distinguish between 4.4 BSD-derived systems and the
! 6527: rest of the world, you should use the following code.</p>
! 6528: <pre class="programlisting">
! 6529: #include <sys/param.h>
! 6530: #if (defined(BSD) && BSD >= 199306)
! 6531: /* BSD-specific code goes here */
! 6532: #else
! 6533: /* non-BSD-specific code goes here */
! 6534: #endif
! 6535: </pre>
! 6536: <p>If this distinction is not fine enough, you can also use
! 6537: the following defines.</p>
! 6538: <pre class="programlisting">
! 6539: FreeBSD __FreeBSD__
! 6540: DragonFly __DragonFly__
! 6541: Interix __INTERIX
! 6542: Linux linux, __linux, __linux__
! 6543: NetBSD __NetBSD__
! 6544: OpenBSD __OpenBSD__
! 6545: Solaris sun, __sun
! 6546: </pre>
! 6547: </div>
! 6548: <div class="sect3" lang="en">
! 6549: <div class="titlepage"><div><div><h4 class="title">
! 6550: <a name="fixes-build-cpp-cpu"></a>16.4.1.2. CPP defines for CPUs</h4></div></div></div>
! 6551: <pre class="programlisting">
! 6552: i386 i386, __i386, __i386__
! 6553: MIPS __mips
! 6554: SPARC sparc, __sparc
! 6555: </pre>
! 6556: </div>
! 6557: <div class="sect3" lang="en">
! 6558: <div class="titlepage"><div><div><h4 class="title">
! 6559: <a name="fixes-build-cpp-compiler"></a>16.4.1.3. CPP defines for compilers</h4></div></div></div>
! 6560: <pre class="programlisting">
! 6561: GCC __GNUC__ (major version), __GNUC_MINOR__
! 6562: SunPro __SUNPRO_C (0x570 for version 5.7)
! 6563: </pre>
! 6564: </div>
! 6565: </div>
! 6566: <div class="sect2" lang="en">
! 6567: <div class="titlepage"><div><div><h3 class="title">
! 6568: <a name="cpp-list-examples"></a>16.4.2. Examples of CPP defines for some platforms</h3></div></div></div>
! 6569: <p>The list of the CPP identification macros for hardware and
! 6570: operating system may depend on the compiler that is used. The
! 6571: following list contains some examples that may help you to choose
! 6572: the right ones. For example, if you want to conditionally compile
! 6573: code on Solaris, don't use <code class="varname">__sun__</code>, as the
! 6574: SunPro compiler does not define it. Use <code class="varname">__sun</code>
! 6575: instead.</p>
! 6576: <div class="variablelist"><dl>
! 6577: <dt><span class="term">GCC 3.3.3 + SuSE Linux 9.1 + i386</span></dt>
! 6578: <dd><p>__ELF__, __gnu_linux__, __i386, __i386__,
! 6579: __linux, __linux__, __unix, __unix__, i386, linux,
! 6580: unix.</p></dd>
! 6581: <dt><span class="term">GCC 2.95 + NetBSD 1.6.2 + i386</span></dt>
! 6582: <dd><p>__ELF__, __NetBSD__, __i386, __i386__,
! 6583: i386.</p></dd>
! 6584: <dt><span class="term">GCC 3.3.3 + NetBSD 2.0 + i386</span></dt>
! 6585: <dd><p>__ELF__, __NetBSD__, __i386, __i386__,
! 6586: i386.</p></dd>
! 6587: <dt><span class="term">GCC 4 + Solaris 8 + SPARC</span></dt>
! 6588: <dd><p>__ELF__, __sparc, __sparc__, __sun, __sun__,
! 6589: __SVR4, __svr4__, __unix, __unix__, sparc, sun,
! 6590: unix.</p></dd>
! 6591: <dt><span class="term">SunPro 5.7 + Solaris 8 + SPARC</span></dt>
! 6592: <dd><p>__SVR4, __sparc, __sun, __unix, sparc, sun,
! 6593: unix.</p></dd>
! 6594: </dl></div>
! 6595: </div>
! 6596: <div class="sect2" lang="en">
! 6597: <div class="titlepage"><div><div><h3 class="title">
! 6598: <a name="cpp-list"></a>16.4.3. Getting a list of CPP defines</h3></div></div></div>
! 6599: <p>If your system uses the GNU C Compiler, you can get a list
! 6600: of symbols that are defined by default, e.g. to identify the
! 6601: platform, with the following command:</p>
! 6602: <pre class="programlisting">
! 6603: gcc -E -dM - < /dev/null
! 6604: </pre>
! 6605: <p>On other systems you may get the list by using the system's
! 6606: syscall trace utility (ktrace, truss, strace) to have a look which
! 6607: arguments are passed to the actual compiler.</p>
! 6608: </div>
! 6609: </div>
! 6610: <div class="sect1" lang="en">
! 6611: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 6612: <a name="package-specific-actions"></a>16.5. Package specific actions</h2></div></div></div>
! 6613: <div class="sect2" lang="en">
! 6614: <div class="titlepage"><div><div><h3 class="title">
! 6615: <a name="user-interaction"></a>16.5.1. User interaction</h3></div></div></div>
! 6616: <p>Occasionally, packages require interaction from the user, and this can be
! 6617: in a number of ways:</p>
! 6618: <div class="itemizedlist"><ul type="disc">
! 6619: <li><p>help in fetching the distfiles</p></li>
! 6620: <li><p>help to configure the package before it is built</p></li>
! 6621: <li><p>help during the build process</p></li>
! 6622: <li><p>help during the installation of a package</p></li>
! 6623: </ul></div>
! 6624: <p>The <code class="varname">INTERACTIVE_STAGE</code> definition is provided to notify
! 6625: the pkgsrc mechanism of an interactive stage which will be needed, and
! 6626: this should be set in the package's <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, e.g.:</p>
! 6627: <pre class="programlisting">
! 6628: INTERACTIVE_STAGE= build
! 6629: </pre>
! 6630: <p>Multiple interactive stages can be specified:</p>
! 6631: <pre class="programlisting">
! 6632: INTERACTIVE_STAGE= configure install
! 6633: </pre>
! 6634: </div>
! 6635: <div class="sect2" lang="en">
! 6636: <div class="titlepage"><div><div><h3 class="title">
! 6637: <a name="handling-licenses"></a>16.5.2. Handling licenses</h3></div></div></div>
! 6638: <p>A package may be covered by a license which the user has
! 6639: or has not agreed to accept. For these cases, pkgsrc contains
! 6640: a mechanism to note that a package is covered by a particular
! 6641: license, and the package cannot be built unless the user has
! 6642: accepted the license. (Installation of binary packages are
! 6643: not currently subject to this mechanism.) Packages with
! 6644: licenses that are either Open Source according to the Open
! 6645: Source Initiative or Free according to the Free Software
! 6646: Foundation will not be marked with a license tag. Packages
! 6647: with licenses that have not been determined to meet either
! 6648: definition will be marked with a license tag referring to the
! 6649: license. This will prevent building unless pkgsrc is informed
! 6650: that the license is acceptable, and enables displaying the
! 6651: license.</p>
! 6652: <p>The license tag mechanism is intended to address
! 6653: copyright-related issues surrounding building, installing and
! 6654: using a package, and not to address redistribution issues (see
! 6655: <code class="varname">RESTRICTED</code> and
! 6656: <code class="varname">NO_SRC_ON_FTP</code>, etc.). However, the above
! 6657: definition of licenses for which tags are not needed implies
! 6658: that packages with redistribution restrictions should have
! 6659: tags.</p>
! 6660: <p>
! 6661: Denoting that a package is covered by a particular license is
! 6662: done by placing the license in
! 6663: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/licenses</code> and setting the
! 6664: <code class="varname">LICENSE</code> variable to a string identifying
! 6665: the license, e.g. in
! 6666: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/xv/README.html" target="_top"><code xmlns="" class="filename">graphics/xv</code></a>: </p>
! 6667: <pre class="programlisting">
! 6668: LICENSE= xv-license
! 6669: </pre>
! 6670: <p>
! 6671: When trying to build, the user will get a notice that the
! 6672: package is covered by a license which has not been
! 6673: accepted:</p>
! 6674: <pre class="programlisting">
! 6675: <code class="prompt">%</code> <strong class="userinput"><code>make</code></strong>
! 6676: ===> xv-3.10anb9 has an unacceptable license: xv-license.
! 6677: ===> To view the license, enter "/usr/bin/make show-license".
! 6678: ===> To indicate acceptance, add this line to your /etc/mk.conf:
! 6679: ===> ACCEPTABLE_LICENSES+=xv-license
! 6680: *** Error code 1
! 6681: </pre>
! 6682: <p>The license can be viewed with <span><strong class="command">make
! 6683: show-license</strong></span>, and if it is considered appropriate,
! 6684: the line printed above can be added to
! 6685: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> to indicate acceptance of
! 6686: the particular license:</p>
! 6687: <pre class="programlisting">
! 6688: ACCEPTABLE_LICENSES+=xv-license
! 6689: </pre>
! 6690: <p>When adding a package with a new license, the license
! 6691: text should be added to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/licenses</code>
! 6692: for displaying. A list of known licenses can be seen in this
! 6693: directory as well as by looking at the list of (commented
! 6694: out) <code class="varname">ACCEPTABLE_LICENSES</code> variable
! 6695: settings in
! 6696: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/mk/defaults/mk.conf</code>.</p>
! 6697: <p>The use of <code class="varname">LICENSE=shareware</code>,
! 6698: <code class="varname">LICENSE=no-commercial-use</code>, and similar
! 6699: language is deprecated because it does not crisply refer to
! 6700: a particular license text. Another problem with such usage
! 6701: is that it does not enable a user to denote acceptance of
! 6702: the license for a single package without accepting the same
! 6703: license text for another package. In particular, this can
! 6704: be inappropriate when e.g. one accepts a particular license to
! 6705: indicate to pkgsrc that a fee has been paid.</p>
! 6706: </div>
! 6707: <div class="sect2" lang="en">
! 6708: <div class="titlepage"><div><div><h3 class="title">
! 6709: <a name="installing-score-files"></a>16.5.3. Installing score files</h3></div></div></div>
! 6710: <p>Certain packages, most of them in the games category, install
! 6711: a score file that allows all users on the system to record their
! 6712: highscores. In order for this to work, the binaries need to be
! 6713: installed setgid and the score files owned by the appropriate
! 6714: group and/or owner (traditionally the "games" user/group). The
! 6715: following variables, documented in more detail in
! 6716: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/defaults/mk.conf</code>, control this
! 6717: behaviour: <code class="varname">SETGIDGAME</code>,
! 6718: <code class="varname">GAMEDATAMODE</code>, <code class="varname">GAMEGRP</code>,
! 6719: <code class="varname">GAMEMODE</code>, <code class="varname">GAMEOWN</code>.</p>
! 6720: <p>Note that per default, setgid installation of games is
! 6721: disabled; setting <code class="varname">SETGIDGAME=YES</code> will set all
! 6722: the other variables accordingly.</p>
! 6723: <p>A package should therefor never hard code file ownership or
! 6724: access permissions but rely on <code class="varname">INSTALL_GAME</code> and
! 6725: <code class="varname">INSTALL_GAME_DATA</code> to set these
! 6726: correctly.</p>
! 6727: </div>
! 6728: <div class="sect2" lang="en">
! 6729: <div class="titlepage"><div><div><h3 class="title">
! 6730: <a name="perl-scripts"></a>16.5.4. Packages containing perl scripts</h3></div></div></div>
! 6731: <p>
! 6732: If your package contains interpreted perl scripts, set
! 6733: <code class="varname">REPLACE_PERL</code> to ensure that the proper
! 6734: interpreter path is set. <code class="varname">REPLACE_PERL</code> should
! 6735: contain a list of scripts, relative to
! 6736: <code class="varname">WRKSRC</code>, that you want adjusted.</p>
! 6737: </div>
! 6738: <div class="sect2" lang="en">
! 6739: <div class="titlepage"><div><div><h3 class="title">
! 6740: <a name="hardcoded-paths"></a>16.5.5. Packages with hardcoded paths to other interpreters</h3></div></div></div>
! 6741: <p>
! 6742: Your package may also contain scripts with hardcoded paths to
! 6743: other interpreters besides (or as well as) perl. To correct the
! 6744: full pathname to the script interpreter, you need to set the
! 6745: following definitions in your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> (we
! 6746: shall use <span><strong class="command">tclsh</strong></span> in this example):</p>
! 6747: <pre class="programlisting">
! 6748: REPLACE_INTERPRETER+= tcl
! 6749: REPLACE.tcl.old= .*/bin/tclsh
! 6750: REPLACE.tcl.new= ${PREFIX}/bin/tclsh
! 6751: REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed,
! 6752: # relative to ${WRKSRC}, just as in REPLACE_PERL
! 6753: </pre>
! 6754: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 6755: <h3 class="title">Note</h3>
! 6756: <p>Before March 2006, these variables were called
! 6757: <code class="varname">_REPLACE.*</code> and
! 6758: <code class="varname">_REPLACE_FILES.*</code>.</p>
! 6759: </div>
! 6760: </div>
! 6761: <div class="sect2" lang="en">
! 6762: <div class="titlepage"><div><div><h3 class="title">
! 6763: <a name="perl-modules"></a>16.5.6. Packages installing perl modules</h3></div></div></div>
! 6764: <p>Makefiles of packages providing perl5 modules should include
! 6765: the Makefile fragment
! 6766: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../lang/perl5/module.mk</code>. It provides a
! 6767: <span><strong class="command">do-configure</strong></span> target for the standard perl
! 6768: configuration for such modules as well as various hooks to tune
! 6769: this configuration. See comments in this file for
! 6770: details.</p>
! 6771: <p>Perl5 modules will install into different places depending
! 6772: on the version of perl used during the build process. To
! 6773: address this, pkgsrc will append lines to the
! 6774: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> corresponding to the files listed in
! 6775: the installed <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.packlist</code> file generated by
! 6776: most perl5 modules. This is invoked by defining
! 6777: <code class="varname">PERL5_PACKLIST</code> to a space-separated list of
! 6778: paths to packlist files, e.g.:</p>
! 6779: <pre class="programlisting">
! 6780: PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
! 6781: </pre>
! 6782: <p>The variables <code class="varname">PERL5_SITELIB</code>,
! 6783: <code class="varname">PERL5_SITEARCH</code>, and
! 6784: <code class="varname">PERL5_ARCHLIB</code> represent the three locations
! 6785: in which perl5 modules may be installed, and may be used by
! 6786: perl5 packages that don't have a packlist. These three
! 6787: variables are also substituted for in the
! 6788: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>.</p>
! 6789: </div>
! 6790: <div class="sect2" lang="en">
! 6791: <div class="titlepage"><div><div><h3 class="title">
! 6792: <a name="faq.info-files"></a>16.5.7. Packages installing info files</h3></div></div></div>
! 6793: <p>Some packages install info files or use the
! 6794: “<span class="quote">makeinfo</span>” or “<span class="quote">install-info</span>”
! 6795: commands. <code class="varname">INFO_FILES</code> should be defined in
! 6796: the package Makefile so that <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">INSTALL</code> and
! 6797: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DEINSTALL</code> scripts will be generated to
! 6798: handle registration of the info files in the Info directory
! 6799: file. The “<span class="quote">install-info</span>” command used for the info
! 6800: files registration is either provided by the system, or by a
! 6801: special purpose package automatically added as dependency if
! 6802: needed.</p>
! 6803: <p><code class="varname">PKGINFODIR</code> is the directory under
! 6804: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}</code> where info files are primarily
! 6805: located. <code class="varname">PKGINFODIR</code> defaults to
! 6806: “<span class="quote">info</span>” and can be overridden by the user.</p>
! 6807: <p>The info files for the package should be listed in the
! 6808: package <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>; however any split info files
! 6809: need not be listed.</p>
! 6810: <p>A package which needs the “<span class="quote">makeinfo</span>” command
! 6811: at build time must add “<span class="quote">makeinfo</span>” to
! 6812: <code class="varname">USE_TOOLS</code> in its Makefile. If a minimum
! 6813: version of the “<span class="quote">makeinfo</span>” command is needed it
! 6814: should be noted with the <code class="varname">TEXINFO_REQD</code>
! 6815: variable in the package <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>. By
! 6816: default, a minimum version of 3.12 is required. If the system
! 6817: does not provide a <span><strong class="command">makeinfo</strong></span> command or if it
! 6818: does not match the required minimum, a build dependency on the
! 6819: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gtexinfo/README.html" target="_top"><code xmlns="" class="filename">devel/gtexinfo</code></a> package will
! 6820: be added automatically.</p>
! 6821: <p>The build and installation process of the software provided
! 6822: by the package should not use the
! 6823: <span><strong class="command">install-info</strong></span> command as the registration of
! 6824: info files is the task of the package
! 6825: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">INSTALL</code> script, and it must use the
! 6826: appropriate <span><strong class="command">makeinfo</strong></span> command.</p>
! 6827: <p>To achieve this goal, the pkgsrc infrastructure creates
! 6828: overriding scripts for the <span><strong class="command">install-info</strong></span> and
! 6829: <span><strong class="command">makeinfo</strong></span> commands in a directory listed early
! 6830: in <code class="varname">PATH</code>.</p>
! 6831: <p>The script overriding <span><strong class="command">install-info</strong></span> has
! 6832: no effect except the logging of a message. The script overriding
! 6833: <span><strong class="command">makeinfo</strong></span> logs a message and according to the
! 6834: value of <code class="varname">TEXINFO_REQD</code> either runs the appropriate
! 6835: <span><strong class="command">makeinfo</strong></span> command or exit on error.</p>
! 6836: </div>
! 6837: <div class="sect2" lang="en">
! 6838: <div class="titlepage"><div><div><h3 class="title">
! 6839: <a name="manpages"></a>16.5.8. Packages installing man pages</h3></div></div></div>
! 6840: <p>Many packages install manual pages. The man pages
! 6841: are installed under <code class="varname">${PREFIX}/${PKGMANDIR}</code>
! 6842: which is <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg/man</code> by default.
! 6843: <code class="varname">PKGMANDIR</code> defaults to “<span class="quote">man</span>”.
! 6844: For example, you can set <code class="varname">PKGMANDIR</code> to
! 6845: “<span class="quote">share/man</span>” to have man pages install under
! 6846: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/usr/pkg/share/man/</code> by default.
! 6847: </p>
! 6848: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 6849: <h3 class="title">Note</h3>
! 6850: <p>The support for a custom <code class="varname">PKGMANDIR</code>
! 6851: is not complete.
! 6852: </p>
! 6853: </div>
! 6854: <p>The <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> files can just
! 6855: use <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">man/</code> as the top level directory
! 6856: for the man page file entries
! 6857: and the pkgsrc framework will convert as needed.
! 6858: </p>
! 6859: <p> Packages that are
! 6860: configured with <code class="varname">GNU_CONFIGURE</code> set as
! 6861: “<span class="quote">yes</span>”, by default will use the
! 6862: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">./configure</code>
! 6863: --mandir switch to set where the man pages should be installed.
! 6864: The path is <code class="varname">GNU_CONFIGURE_MANDIR</code> which defaults
! 6865: to <code class="varname">${PREFIX}/${PKGMANDIR}</code>.
! 6866: </p>
! 6867: <p>
! 6868: Packages that use <code class="varname">GNU_CONFIGURE</code> but do not
! 6869: use --mandir, can set <code class="varname">CONFIGURE_HAS_MANDIR</code>
! 6870: to “<span class="quote">no</span>”.
! 6871: Or if the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">./configure</code> script uses
! 6872: a non-standard use of --mandir, you can set
! 6873: <code class="varname">GNU_CONFIGURE_MANDIR</code> as needed.
! 6874: </p>
! 6875: <p>See <a href="#manpage-compression" title="10.5. Man page compression">Section 10.5, “Man page compression”</a> for
! 6876: information on installation of compressed manual pages.
! 6877: </p>
! 6878: </div>
! 6879: <div class="sect2" lang="en">
! 6880: <div class="titlepage"><div><div><h3 class="title">
! 6881: <a name="gconf2-data-files"></a>16.5.9. Packages installing GConf2 data files</h3></div></div></div>
! 6882: <p>
! 6883: If a package installs <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.schemas</code> or
! 6884: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.entries</code> files, used by GConf2,
! 6885: you need to take some extra steps to make sure they get registered
! 6886: in the database:
! 6887: </p>
! 6888: <div class="orderedlist"><ol type="1">
! 6889: <li><p>Include <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../devel/GConf2/schemas.mk</code>
! 6890: instead of its <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file. This
! 6891: takes care of rebuilding the GConf2 database at installation and
! 6892: deinstallation time, and tells the package where to install
! 6893: GConf2 data files using some standard configure arguments. It
! 6894: also disallows any access to the database directly from the
! 6895: package.</p></li>
! 6896: <li><p>Ensure that the package installs its
! 6897: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.schemas</code> files under
! 6898: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/gconf/schemas</code>. If they get
! 6899: installed under <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/etc</code>, you will
! 6900: need to manually patch the package.</p></li>
! 6901: <li><p>Check the PLIST and remove any entries under the etc/gconf
! 6902: directory, as they will be handled automatically. See
! 6903: <a href="#faq.conf" title="7.14. How do I change the location of configuration files?">Section 7.14, “How do I change the location of configuration files?”</a> for more information.</p></li>
! 6904: <li><p>Define the <code class="varname">GCONF2_SCHEMAS</code> variable in
! 6905: your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> with a list of all
! 6906: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.schemas</code> files installed by the package, if
! 6907: any. Names must not contain any directories in them.</p></li>
! 6908: <li><p>Define the <code class="varname">GCONF2_ENTRIES</code> variable in
! 6909: your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> with a
! 6910: list of all <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.entries</code> files installed by the
! 6911: package, if any. Names must not contain any directories in
! 6912: them.</p></li>
! 6913: </ol></div>
! 6914: </div>
! 6915: <div class="sect2" lang="en">
! 6916: <div class="titlepage"><div><div><h3 class="title">
! 6917: <a name="scrollkeeper-data-files"></a>16.5.10. Packages installing scrollkeeper data files</h3></div></div></div>
! 6918: <p>
! 6919: If a package installs <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.omf</code> files, used by
! 6920: scrollkeeper, you need to take some extra steps to make sure they
! 6921: get registered in the database:
! 6922: </p>
! 6923: <div class="orderedlist"><ol type="1">
! 6924: <li><p>Include
! 6925: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../textproc/scrollkeeper/omf.mk</code>
! 6926: instead of its <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file. This
! 6927: takes care of rebuilding the scrollkeeper database at
! 6928: installation and deinstallation time, and disallows any access
! 6929: to it directly from the package.
! 6930: </p></li>
! 6931: <li><p>Check the PLIST and remove any entries under the
! 6932: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libdata/scrollkeeper</code> directory, as they
! 6933: will be handled automatically.</p></li>
! 6934: <li><p>Remove the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/omf</code> directory from
! 6935: the PLIST. It will be handled by scrollkeeper.</p></li>
! 6936: </ol></div>
! 6937: </div>
! 6938: <div class="sect2" lang="en">
! 6939: <div class="titlepage"><div><div><h3 class="title">
! 6940: <a name="x11-fonts"></a>16.5.11. Packages installing X11 fonts</h3></div></div></div>
! 6941: <p>If a package installs font files, you will need to rebuild
! 6942: the fonts database in the directory where they get installed at
! 6943: installation and deinstallation time. This can be automatically
! 6944: done by using the pkginstall framework.</p>
! 6945: <p>You can list the directories where fonts are installed in the
! 6946: <code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code>
! 6947: variables, where <em class="replaceable"><code>type</code></em> can be one of
! 6948: “<span class="quote">ttf</span>”, “<span class="quote">type1</span>” or “<span class="quote">x11</span>”.
! 6949: Also make sure that the database file
! 6950: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">fonts.dir</code> is not listed in the PLIST.</p>
! 6951: <p>Note that you should not create new directories for fonts;
! 6952: instead use the standard ones to avoid that the user needs to
! 6953: manually configure his X server to find them.</p>
! 6954: </div>
! 6955: <div class="sect2" lang="en">
! 6956: <div class="titlepage"><div><div><h3 class="title">
! 6957: <a name="gtk2-modules"></a>16.5.12. Packages installing GTK2 modules</h3></div></div></div>
! 6958: <p>If a package installs GTK2 immodules or loaders, you need to
! 6959: take some extra steps to get them registered in the GTK2 database
! 6960: properly:</p>
! 6961: <div class="orderedlist"><ol type="1">
! 6962: <li><p>Include
! 6963: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../x11/gtk2/modules.mk</code> instead of its
! 6964: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file. This takes care of
! 6965: rebuilding the database at installation and deinstallation time.
! 6966: </p></li>
! 6967: <li><p>
! 6968: Set <code class="varname">GTK2_IMMODULES=YES</code> if
! 6969: your package installs GTK2 immodules.</p></li>
! 6970: <li><p>
! 6971: Set <code class="varname">GTK2_LOADERS=YES</code> if your package installs
! 6972: GTK2 loaders.</p></li>
! 6973: <li>
! 6974: <p>
! 6975: Patch the package to not touch any of the GTK2 databases directly.
! 6976: These are:
! 6977:
! 6978: </p>
! 6979: <div class="itemizedlist"><ul type="disc">
! 6980: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p></li>
! 6981: <li><p><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libdata/gtk-2.0/gtk.immodules</code></p></li>
! 6982: </ul></div>
! 6983: <p>
! 6984: </p>
! 6985: </li>
! 6986: <li><p>
! 6987: Check the PLIST and remove any entries under the
! 6988: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">libdata/gtk-2.0</code> directory, as they will be
! 6989: handled automatically.</p></li>
! 6990: </ol></div>
! 6991: </div>
! 6992: <div class="sect2" lang="en">
! 6993: <div class="titlepage"><div><div><h3 class="title">
! 6994: <a name="sgml-xml-data"></a>16.5.13. Packages installing SGML or XML data</h3></div></div></div>
! 6995: <p>If a package installs SGML or XML data files that need to be
! 6996: registered in system-wide catalogs (like DTDs, sub-catalogs,
! 6997: etc.), you need to take some extra steps:
! 6998: </p>
! 6999: <div class="orderedlist"><ol type="1">
! 7000: <li><p>Include
! 7001: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../textproc/xmlcatmgr/catalogs.mk</code> in
! 7002: your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, which takes care of
! 7003: registering those files in system-wide catalogs at
! 7004: installation and deinstallation time.</p></li>
! 7005: <li><p>Set <code class="varname">SGML_CATALOGS</code> to the full path of
! 7006: any SGML catalogs installed by the package.</p></li>
! 7007: <li><p>Set <code class="varname">XML_CATALOGS</code> to the full path of
! 7008: any XML catalogs installed by the package.</p></li>
! 7009: <li><p>Set <code class="varname">SGML_ENTRIES</code> to individual entries
! 7010: to be added to the SGML catalog. These come in groups of
! 7011: three strings; see xmlcatmgr(1) for more information
! 7012: (specifically, arguments recognized by the 'add' action).
! 7013: Note that you will normally not use this variable.</p></li>
! 7014: <li><p>Set <code class="varname">XML_ENTRIES</code> to individual entries
! 7015: to be added to the XML catalog. These come in groups of three
! 7016: strings; see xmlcatmgr(1) for more information (specifically,
! 7017: arguments recognized by the 'add' action). Note that you will
! 7018: normally not use this variable.
! 7019: </p></li>
! 7020: </ol></div>
! 7021: </div>
! 7022: <div class="sect2" lang="en">
! 7023: <div class="titlepage"><div><div><h3 class="title">
! 7024: <a name="mime-database"></a>16.5.14. Packages installing extensions to the MIME database</h3></div></div></div>
! 7025: <p>If a package provides extensions to the MIME database by
! 7026: installing <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.xml</code> files inside
! 7027: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">${PREFIX}/share/mime/packages</code>, you
! 7028: need to take some extra steps to ensure that the database is kept
! 7029: consistent with respect to these new files:
! 7030: </p>
! 7031: <div class="orderedlist"><ol type="1">
! 7032: <li><p>Include
! 7033: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../databases/shared-mime-info/mimedb.mk</code>
! 7034: (avoid using the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> file from
! 7035: this same directory, which is reserved for inclusion from
! 7036: other <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">buildlink3.mk</code> files). It takes
! 7037: care of rebuilding the MIME database at installation and
! 7038: deinstallation time, and disallows any access to it directly
! 7039: from the package.</p></li>
! 7040: <li><p>Check the PLIST and remove any entries under the
! 7041: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/mime</code> directory,
! 7042: <span class="emphasis"><em>except</em></span> for files saved under
! 7043: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/mime/packages</code>. The former are
! 7044: handled automatically by
! 7045: the update-mime-database program, but the latter are
! 7046: package-dependent and must be removed by the package that
! 7047: installed them in the first place.</p></li>
! 7048: <li><p>Remove any <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">share/mime/*</code> directories
! 7049: from the PLIST. They will be handled by the shared-mime-info
! 7050: package.</p></li>
! 7051: </ol></div>
! 7052: </div>
! 7053: <div class="sect2" lang="en">
! 7054: <div class="titlepage"><div><div><h3 class="title">
! 7055: <a name="intltool"></a>16.5.15. Packages using intltool</h3></div></div></div>
! 7056: <p>If a package uses intltool during its build, include the
! 7057: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../textproc/intltool/buildlink3.mk</code> file,
! 7058: which forces it to use the intltool package provided by pkgsrc,
! 7059: instead of the one bundled with the distribution file.
! 7060: </p>
! 7061: <p>This tracks intltool's build-time dependencies and uses the
! 7062: latest available version; this way, the package benefits of any
! 7063: bug fixes that may have appeared since it was released.
! 7064: </p>
! 7065: </div>
! 7066: <div class="sect2" lang="en">
! 7067: <div class="titlepage"><div><div><h3 class="title">
! 7068: <a name="startup-scripts"></a>16.5.16. Packages installing startup scripts</h3></div></div></div>
! 7069: <p>If a package contains a rc.d script, it won't be copied into
! 7070: the startup directory by default, but you can enable it, by adding
! 7071: the option <code class="varname">PKG_RCD_SCRIPTS=YES</code> in
! 7072: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code>. This option will copy the scripts
! 7073: into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/rc.d</code> when a package is installed, and
! 7074: it will automatically remove the scripts when the package is
! 7075: deinstalled.</p>
! 7076: </div>
! 7077: <div class="sect2" lang="en">
! 7078: <div class="titlepage"><div><div><h3 class="title">
! 7079: <a name="tex-packages"></a>16.5.17. Packages installing TeX modules</h3></div></div></div>
! 7080: <p>If a package installs TeX packages into the texmf tree,
! 7081: the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ls-R</code> database of the tree needs to be
! 7082: updated.</p>
! 7083: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
! 7084: <h3 class="title">Note</h3>
! 7085: <p>Except the main TeX packages such as teTeX-texmf,
! 7086: packages should install files
! 7087: into <code class="varname">PKG_LOCALTEXMFPREFIX</code>,
! 7088: not <code class="varname">PKG_TEXMFPREFIX</code>.</p>
! 7089: </div>
! 7090: <div class="orderedlist"><ol type="1">
! 7091: <li><p>Include
! 7092: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../print/teTeX/module.mk</code> instead
! 7093: of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">../../mk/tex.buildlink3.mk</code>. This
! 7094: takes care of rebuilding the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ls-R</code>
! 7095: database at installation and deinstallation time.</p></li>
! 7096: <li>
! 7097: <p>If your package installs files into a texmf
! 7098: tree other than the one
! 7099: at <code class="varname">PKG_LOCALTEXMFPREFIX</code>,
! 7100: set <code class="varname">TEXMFDIRS</code> to the list of all texmf
! 7101: trees that need database update.</p>
! 7102: <p>If your package also installs font map files that need
! 7103: to be registered using <span><strong class="command">updmap</strong></span>,
! 7104: set <code class="varname">TEX_FONTMAPS</code> to the list of all
! 7105: such font map files. Then <span><strong class="command">updmap</strong></span> will
! 7106: be run automatically at installation/deinstallation to
! 7107: enable/disable font map files for TeX output
! 7108: drivers.</p>
! 7109: </li>
! 7110: <li><p>Make sure that none of <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">ls-R</code>
! 7111: databases are included in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>, as
! 7112: they will be removed only by the teTeX-bin package.</p></li>
! 7113: </ol></div>
! 7114: </div>
! 7115: </div>
! 7116: <div class="sect1" lang="en">
! 7117: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7118: <a name="feedback-to-author"></a>16.6. Feedback to the author</h2></div></div></div>
! 7119: <p>If you have found any bugs in the package you make available,
! 7120: if you had to do special steps to make it run under NetBSD or
! 7121: if you enhanced the software in various other ways, be sure
! 7122: to report these changes back to the original author of the
! 7123: program! With that kind of support, the next release of the
! 7124: program can incorporate these fixes, and people not using the
! 7125: NetBSD packages system can win from your efforts.</p>
! 7126: <p>Support the idea of free software!</p>
! 7127: </div>
! 7128: </div>
! 7129: <div class="chapter" lang="en">
! 7130: <div class="titlepage"><div><div><h2 class="title">
! 7131: <a name="debug"></a>Chapter 17. Debugging</h2></div></div></div>
! 7132: <p>To check out all the gotchas when building a package, here are the steps
! 7133: that I do in order to get a package working. Please note this is basically
! 7134: the same as what was explained in the previous sections, only with some
! 7135: debugging aids.</p>
! 7136: <div class="itemizedlist"><ul type="disc">
! 7137: <li><p>Be sure to set <code class="varname">PKG_DEVELOPER=1</code>
! 7138: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code></p></li>
! 7139: <li>
! 7140: <p>Install <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html" target="_top"><code xmlns="" class="filename">pkgtools/url2pkg</code></a>,
! 7141: create a directory for a new package, change into it, then run
! 7142: <span><strong class="command">url2pkg</strong></span>:</p>
! 7143: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>mkdir /usr/pkgsrc/<em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>examplepkg</code></em></code></strong>
! 7144: <code class="prompt">%</code> <strong class="userinput"><code>cd /usr/pkgsrc/<em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>examplepkg</code></em></code></strong>
! 7145: <code class="prompt">%</code> <strong class="userinput"><code>url2pkg http://www.example.com/path/to/distfile.tar.gz</code></strong></pre>
! 7146: </li>
! 7147: <li><p>Edit the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code> as requested.</p></li>
! 7148: <li><p>Fill in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DESCR</code> file</p></li>
! 7149: <li><p>Run <span><strong class="command">make configure</strong></span>
! 7150: </p></li>
! 7151: <li><p>Add any dependencies glimpsed from documentation and the
! 7152: configure step to the package's
! 7153: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>.</p></li>
! 7154: <li>
! 7155: <p>Make the package compile, doing multiple rounds of</p>
! 7156: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>make</code></strong>
! 7157: <code class="prompt">%</code> <strong class="userinput"><code>pkgvi ${WRKSRC}/some/file/that/does/not/compile</code></strong>
! 7158: <code class="prompt">%</code> <strong class="userinput"><code>mkpatches</code></strong>
! 7159: <code class="prompt">%</code> <strong class="userinput"><code>patchdiff</code></strong>
! 7160: <code class="prompt">%</code> <strong class="userinput"><code>mv ${WRKDIR}/.newpatches/* patches</code></strong>
! 7161: <code class="prompt">%</code> <strong class="userinput"><code>make mps</code></strong>
! 7162: <code class="prompt">%</code> <strong class="userinput"><code>make clean</code></strong></pre>
! 7163: <p>Doing as non-root user will ensure that no files are modified that
! 7164: shouldn't be, especially during the build
! 7165: phase. <span><strong class="command">mkpatches</strong></span>,
! 7166: <span><strong class="command">patchdiff</strong></span> and <span><strong class="command">pkgvi</strong></span> are
! 7167: from the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkgdiff</code></a>
! 7168: package. </p>
! 7169: </li>
! 7170: <li><p>Look at the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, fix if necessary;
! 7171: see <a href="#components.Makefile" title="8.1. Makefile">Section 8.1, “<code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>”</a>.</p></li>
! 7172: <li>
! 7173: <p>Generate a <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>:</p>
! 7174: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
! 7175: <code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST >PLIST</code></strong>
! 7176: <code class="prompt">#</code> <strong class="userinput"><code>make deinstall</code></strong>
! 7177: <code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
! 7178: <code class="prompt">#</code> <strong class="userinput"><code>make deinstall</code></strong></pre>
! 7179: <p>You usually need to be <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="username">root</code> to do this.
! 7180: Look if there are any files left:</p>
! 7181: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST</code></strong></pre>
! 7182: <p>If this reveals any files that are missing in
! 7183: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code>, add them.</p>
! 7184: </li>
! 7185: <li>
! 7186: <p>Now that the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> is OK,
! 7187: install the package again and make a binary package:</p>
! 7188: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make reinstall</code></strong>
! 7189: <code class="prompt">#</code> <strong class="userinput"><code>make package</code></strong></pre>
! 7190: </li>
! 7191: <li>
! 7192: <p>Delete the installed package:</p>
! 7193: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg_delete blub</code></strong></pre>
! 7194: </li>
! 7195: <li>
! 7196: <p>Repeat the above <span><strong class="command">make print-PLIST</strong></span> command,
! 7197: which shouldn't find anything now:</p>
! 7198: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST</code></strong></pre>
! 7199: </li>
! 7200: <li>
! 7201: <p>Reinstall the binary package:</p>
! 7202: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkgadd .../blub.tgz</code></strong></pre>
! 7203: </li>
! 7204: <li><p>Play with it. Make sure everything works.</p></li>
! 7205: <li>
! 7206: <p>Run <span><strong class="command">pkglint</strong></span> from
! 7207: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkglint</code></a>,
! 7208: and fix the problems it reports:</p>
! 7209: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkglint</code></strong></pre>
! 7210: </li>
! 7211: <li><p>Submit (or commit, if you have cvs access);
! 7212: see <a href="#submit" title="Chapter 18. Submitting and Committing">Chapter 18, <i>Submitting and Committing</i></a>.</p></li>
! 7213: </ul></div>
! 7214: </div>
! 7215: <div class="chapter" lang="en">
! 7216: <div class="titlepage"><div><div><h2 class="title">
! 7217: <a name="submit"></a>Chapter 18. Submitting and Committing</h2></div></div></div>
! 7218: <div class="toc">
! 7219: <p><b>Table of Contents</b></p>
! 7220: <dl>
! 7221: <dt><span class="sect1"><a href="#submitting-binary-packages">18.1. Submitting binary packages</a></span></dt>
! 7222: <dt><span class="sect1"><a href="#submitting-your-package">18.2. Submitting source packages (for non-NetBSD-developers)</a></span></dt>
! 7223: <dt><span class="sect1"><a href="#general-notes-for-changes">18.3. General notes when adding, updating, or removing packages</a></span></dt>
! 7224: <dt><span class="sect1"><a href="#committing-importing">18.4. Committing: Importing a package into CVS</a></span></dt>
! 7225: <dt><span class="sect1"><a href="#updating-package">18.5. Updating a package to a newer version</a></span></dt>
! 7226: <dt><span class="sect1"><a href="#moving-package">18.6. Moving a package in pkgsrc</a></span></dt>
! 7227: </dl>
! 7228: </div>
! 7229: <div class="sect1" lang="en">
! 7230: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7231: <a name="submitting-binary-packages"></a>18.1. Submitting binary packages</h2></div></div></div>
! 7232: <p>Our policy is that we accept binaries only from pkgsrc
! 7233: developers to guarantee that the packages don't contain any
! 7234: trojan horses etc. This is not to annoy anyone but rather to
! 7235: protect our users! You're still free to put up your home-made
! 7236: binary packages and tell the world where to get them. NetBSD
! 7237: developers doing bulk builds and wanting to upload them please
! 7238: see <a href="#bulk-upload" title="6.3.8. Uploading results of a bulk build">Section 6.3.8, “Uploading results of a bulk build”</a>.</p>
! 7239: </div>
! 7240: <div class="sect1" lang="en">
! 7241: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7242: <a name="submitting-your-package"></a>18.2. Submitting source packages (for non-NetBSD-developers)</h2></div></div></div>
! 7243: <p>First, check that your package is complete, compiles and
! 7244: runs well; see <a href="#debug" title="Chapter 17. Debugging">Chapter 17, <i>Debugging</i></a> and the rest of this
! 7245: document. Next, generate an uuencoded gzipped <a href="http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">tar</span>(1)</span></a>
! 7246: archive, preferably with all files in a single directory.
! 7247: Finally, <span><strong class="command">send-pr</strong></span> with category
! 7248: “<span class="quote">pkg</span>”, a synopsis which includes the package name
! 7249: and version number, a short description of your package
! 7250: (contents of the COMMENT variable or DESCR file are OK) and
! 7251: attach the archive to your PR.</p>
! 7252: <p>If you want to submit several packages, please send a
! 7253: separate PR for each one, it's easier for us to track things
! 7254: that way.</p>
! 7255: <p>Alternatively, you can also import new packages into
! 7256: pkgsrc-wip (“<span class="quote">pkgsrc work-in-progress</span>”); see the
! 7257: homepage at <a href="http://pkgsrc-wip.sourceforge.net/" target="_top">http://pkgsrc-wip.sourceforge.net/</a>
! 7258: for details.</p>
! 7259: </div>
! 7260: <div class="sect1" lang="en">
! 7261: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7262: <a name="general-notes-for-changes"></a>18.3. General notes when adding, updating, or removing packages</h2></div></div></div>
! 7263: <p>Please note all package additions, updates, moves, and
! 7264: removals in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/CHANGES</code>. It's very
! 7265: important to keep this file up to date and conforming to the
! 7266: existing format, because it will be used by scripts to
! 7267: automatically update pages on <a href="http://www.NetBSD.org/" target="_top">www.NetBSD.org</a> and other
! 7268: sites. Additionally, check the
! 7269: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/TODO</code> file and remove the entry
! 7270: for the package you updated or removed, in case it was mentioned
! 7271: there.</p>
! 7272: <p>When the <code class="varname">PKGREVISION</code> of a package is
! 7273: bumped, the change should appear in
! 7274: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/CHANGES</code> if it is security
! 7275: related or otherwise relevant. Mass bumps that result from a
! 7276: dependency being updated should not be mentioned. In all other
! 7277: cases it's the developer's decision.</p>
! 7278: <p>There is a make target that helps in creating proper
! 7279: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">CHANGES</code> entries: <span><strong class="command">make
! 7280: changes-entry</strong></span>. It uses the optional <code class="varname">CTYPE</code>
! 7281: and <code class="varname">NETBSD_LOGIN_NAME</code> variables. The general
! 7282: usage is to first make sure that your <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">CHANGES</code>
! 7283: file is up-to-date (to avoid having to resolve conflicts later-on)
! 7284: and then to <span><strong class="command">cd</strong></span> to the package directory. For
! 7285: package updates, <span><strong class="command">make changes-entry</strong></span> is enough.
! 7286: For new packages, or package moves or removals, set the
! 7287: <code class="varname">CTYPE</code> variable on the command line to "Added",
! 7288: "Moved", or "Removed". You can set <code class="varname">NETBSD_LOGIN_NAME</code>
! 7289: in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">/etc/mk.conf</code> if your local login name is
! 7290: not the same as your NetBSD login name. Don't forget to commit
! 7291: the changes to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/CHANGES</code>!</p>
! 7292: </div>
! 7293: <div class="sect1" lang="en">
! 7294: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7295: <a name="committing-importing"></a>18.4. Committing: Importing a package into CVS</h2></div></div></div>
! 7296: <p>
! 7297: This section is only of interest for pkgsrc developers with write
! 7298: access to the pkgsrc repository. Please remember that cvs
! 7299: imports files relative to the current working directory, and that
! 7300: the pathname that you
! 7301: give the <span><strong class="command">cvs import</strong></span> command is so that it knows where
! 7302: to place the files in the repository. Newly created packages should be
! 7303: imported with a vendor tag of “<span class="quote">TNF</span>” and a release tag of
! 7304: “<span class="quote">pkgsrc-base</span>”, e.g:
! 7305: </p>
! 7306: <pre class="programlisting">
! 7307: <code class="prompt">$</code> cd .../pkgsrc/category/pkgname
! 7308: <code class="prompt">$</code> cvs import pkgsrc/category/pkgname TNF pkgsrc-base
! 7309: </pre>
! 7310: <p>
! 7311: Remember to move the directory from which you imported out of
! 7312: the way, or cvs will complain the next time you “<span class="quote">cvs
! 7313: update</span>” your source tree. Also don't forget to add the new
! 7314: package to the category's <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>.
! 7315: </p>
! 7316: <p>
! 7317: The commit message of the initial import should include part of the
! 7318: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DESCR</code> file, so people reading the mailing lists know
! 7319: what the package is/does.
! 7320: </p>
! 7321: <p>
! 7322: For new packages, “<span class="quote">cvs import</span>” is preferred to “<span class="quote">cvs
! 7323: add</span>” because the former gets everything with a single command,
! 7324: and provides a consistent tag.
! 7325: </p>
! 7326: </div>
! 7327: <div class="sect1" lang="en">
! 7328: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7329: <a name="updating-package"></a>18.5. Updating a package to a newer version</h2></div></div></div>
! 7330: <p>
! 7331: Please always put a concise, appropriate and relevant summary of the
! 7332: changes between old and new versions into the commit log when updating
! 7333: a package. There are various reasons for this:
! 7334: </p>
! 7335: <div class="itemizedlist"><ul type="disc">
! 7336: <li><p>
! 7337: A URL is volatile, and can change over time. It may go away completely
! 7338: or its information may be overwritten by newer information.
! 7339: </p></li>
! 7340: <li><p>
! 7341: Having the change information between old and new versions in our CVS
! 7342: repository is very useful for people who use either cvs or anoncvs.
! 7343: </p></li>
! 7344: <li><p>
! 7345: Having the change information between old and new versions in our CVS
! 7346: repository is very useful for people who read the pkgsrc-changes mailing
! 7347: list, so that they can make tactical decisions about when to upgrade
! 7348: the package.
! 7349: </p></li>
! 7350: </ul></div>
! 7351: <p>
! 7352: Please also recognize that, just because a new version of a package
! 7353: has been released, it should not automatically be upgraded in the CVS
! 7354: repository. We prefer to be conservative in the packages that are
! 7355: included in pkgsrc - development or beta packages are not really the
! 7356: best thing for most places in which pkgsrc is used. Please use your
! 7357: judgement about what should go into pkgsrc, and bear in mind that
! 7358: stability is to be preferred above new and possibly untested features.
! 7359: </p>
! 7360: </div>
! 7361: <div class="sect1" lang="en">
! 7362: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7363: <a name="moving-package"></a>18.6. Moving a package in pkgsrc</h2></div></div></div>
! 7364: <div class="orderedlist"><ol type="1">
! 7365: <li><p>Make a copy of the directory somewhere else.</p></li>
! 7366: <li>
! 7367: <p>Remove all CVS dirs.</p>
! 7368: <p>
! 7369: Alternatively to the first two steps you can also do:
! 7370: </p>
! 7371: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</code></strong></pre>
! 7372: <p>
! 7373: and use that for further work.
! 7374: </p>
! 7375: </li>
! 7376: <li><p>Fix <code class="varname">CATEGORIES</code> and any
! 7377: <code class="varname">DEPENDS</code> paths that just did “<span class="quote">../package</span>”
! 7378: instead of “<span class="quote">../../category/package</span>”.</p></li>
! 7379: <li><p><span><strong class="command">cvs import</strong></span> the modified package in the new
! 7380: place.</p></li>
! 7381: <li>
! 7382: <p>Check if any package depends on it:
! 7383: </p>
! 7384: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
! 7385: <code class="prompt">%</code> <strong class="userinput"><code>grep /package */*/Makefile* */*/buildlink*</code></strong></pre>
! 7386: <p>
! 7387: </p>
! 7388: </li>
! 7389: <li><p>Fix paths in packages from step 5 to point to new location.</p></li>
! 7390: <li><p><span><strong class="command">cvs rm (-f)</strong></span> the package at the old location.</p></li>
! 7391: <li><p>Remove from <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">oldcategory/Makefile</code>.</p></li>
! 7392: <li><p>Add to <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">newcategory/Makefile</code>.</p></li>
! 7393: <li>
! 7394: <p>Commit the changed and removed files:</p>
! 7395: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</code></strong></pre>
! 7396: <p>
! 7397: (and any packages from step 5, of course).
! 7398: </p>
! 7399: </li>
! 7400: </ol></div>
! 7401: </div>
! 7402: </div>
! 7403: <div class="chapter" lang="en">
! 7404: <div class="titlepage"><div><div><h2 class="title">
! 7405: <a name="devfaq"></a>Chapter 19. Frequently Asked Questions</h2></div></div></div>
! 7406: <p>This section contains the answers to questions that may
! 7407: arise when you are writing a package. If you don't find your
! 7408: question answered here, first have a look in the other chapters,
! 7409: and if you still don't have the answer, ask on the
! 7410: <code class="literal">pkgsrc-users</code> mailing list.</p>
! 7411: <div class="qandaset">
! 7412: <dl>
! 7413: <dt>19.1. <a href="#id2654769">What is the difference between
! 7414: MAKEFLAGS, .MAKEFLAGS and
! 7415: MAKE_FLAGS?</a>
! 7416: </dt>
! 7417: <dt>19.2. <a href="#id2654805">What is the difference between
! 7418: MAKE, GMAKE and
! 7419: MAKE_PROGRAM?</a>
! 7420: </dt>
! 7421: <dt>19.3. <a href="#id2654843">What is the difference between
! 7422: CC, PKG_CC and
! 7423: PKGSRC_COMPILER?</a>
! 7424: </dt>
! 7425: <dt>19.4. <a href="#id2654881">What is the difference between
! 7426: BUILDLINK_LDFLAGS,
! 7427: BUILDLINK_LDADD and
! 7428: BUILDLINK_LIBS?</a>
! 7429: </dt>
! 7430: <dt>19.5. <a href="#id2654899">Why does make show-var
! 7431: VARNAME=BUILDLINK_PREFIX.foo
! 7432: say it's empty?</a>
! 7433: </dt>
! 7434: </dl>
! 7435: <table border="0" summary="Q and A Set">
! 7436: <col align="left" width="1%">
! 7437: <tbody>
! 7438: <tr class="question">
! 7439: <td align="left" valign="top">
! 7440: <a name="id2654769"></a><a name="id2654770"></a><b>19.1.</b>
! 7441: </td>
! 7442: <td align="left" valign="top"><p>What is the difference between
! 7443: <code class="varname">MAKEFLAGS</code>, <code class="varname">.MAKEFLAGS</code> and
! 7444: <code class="varname">MAKE_FLAGS</code>?</p></td>
! 7445: </tr>
! 7446: <tr class="answer">
! 7447: <td align="left" valign="top"><b></b></td>
! 7448: <td align="left" valign="top"><p><code class="varname">MAKEFLAGS</code> are the flags passed
! 7449: to the pkgsrc-internal invocations of <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>, while
! 7450: <code class="varname">MAKE_FLAGS</code> are the flags that are passed to
! 7451: the <code class="varname">MAKE_PROGRAM</code> when building the
! 7452: package. [FIXME: What is .MAKEFLAGS for?]</p></td>
! 7453: </tr>
! 7454: <tr class="question">
! 7455: <td align="left" valign="top">
! 7456: <a name="id2654805"></a><a name="id2654806"></a><b>19.2.</b>
! 7457: </td>
! 7458: <td align="left" valign="top"><p>What is the difference between
! 7459: <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and
! 7460: <code class="varname">MAKE_PROGRAM</code>?</p></td>
! 7461: </tr>
! 7462: <tr class="answer">
! 7463: <td align="left" valign="top"><b></b></td>
! 7464: <td align="left" valign="top"><p><code class="varname">MAKE</code> is the path to the
! 7465: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> program that is used in the pkgsrc
! 7466: infrastructure. <code class="varname">GMAKE</code> is the path to GNU
! 7467: Make, but you need to say <code class="varname">USE_TOOLS+=gmake</code> to
! 7468: use that. <code class="varname">MAKE_PROGRAM</code> is the path to the
! 7469: Make program that is used for building the
! 7470: package.</p></td>
! 7471: </tr>
! 7472: <tr class="question">
! 7473: <td align="left" valign="top">
! 7474: <a name="id2654843"></a><a name="id2654844"></a><b>19.3.</b>
! 7475: </td>
! 7476: <td align="left" valign="top"><p>What is the difference between
! 7477: <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and
! 7478: <code class="varname">PKGSRC_COMPILER</code>?</p></td>
! 7479: </tr>
! 7480: <tr class="answer">
! 7481: <td align="left" valign="top"><b></b></td>
! 7482: <td align="left" valign="top"><p><code class="varname">CC</code> is the path to the real C
! 7483: compiler, which can be configured by the pkgsrc user.
! 7484: <code class="varname">PKG_CC</code> is the path to the compiler wrapper.
! 7485: <code class="varname">PKGSRC_COMPILER</code> is <span class="emphasis"><em>not</em></span> a
! 7486: path to a compiler, but the type of compiler that should be
! 7487: used. See <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/compiler.mk</code> for more
! 7488: information about the latter variable.</p></td>
! 7489: </tr>
! 7490: <tr class="question">
! 7491: <td align="left" valign="top">
! 7492: <a name="id2654881"></a><a name="id2654882"></a><b>19.4.</b>
! 7493: </td>
! 7494: <td align="left" valign="top"><p>What is the difference between
! 7495: <code class="varname">BUILDLINK_LDFLAGS</code>,
! 7496: <code class="varname">BUILDLINK_LDADD</code> and
! 7497: <code class="varname">BUILDLINK_LIBS</code>?</p></td>
! 7498: </tr>
! 7499: <tr class="answer">
! 7500: <td align="left" valign="top"><b></b></td>
! 7501: <td align="left" valign="top"><p>[FIXME]</p></td>
! 7502: </tr>
! 7503: <tr class="question">
! 7504: <td align="left" valign="top">
! 7505: <a name="id2654899"></a><a name="id2654900"></a><b>19.5.</b>
! 7506: </td>
! 7507: <td align="left" valign="top"><p>Why does <span><strong class="command">make show-var
! 7508: VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span>
! 7509: say it's empty?</p></td>
! 7510: </tr>
! 7511: <tr class="answer">
! 7512: <td align="left" valign="top"><b></b></td>
! 7513: <td align="left" valign="top"><p>For optimization reasons, some variables are only
! 7514: available in the “<span class="quote">wrapper</span>” phase and later. To
! 7515: “<span class="quote">simulate</span>” the wrapper phase, append
! 7516: <span><strong class="command">PKG_PHASE=wrapper</strong></span> to the above
! 7517: command.</p></td>
! 7518: </tr>
! 7519: </tbody>
! 7520: </table>
! 7521: </div>
! 7522: </div>
! 7523: </div>
! 7524: <div class="part" lang="en">
! 7525: <div class="titlepage"><div><div><h1 class="title">
! 7526: <a name="infrastructure"></a>Part III. The pkgsrc infrastructure internals</h1></div></div></div>
! 7527: <div class="partintro" lang="en">
! 7528: <div></div>
! 7529: <p>This part of the guide deals with everything
! 7530: from the infrastructure that is behind the interfaces described
! 7531: in the developer's guide. A casual package maintainer should not
! 7532: need anything from this part.</p>
! 7533: <div class="toc">
! 7534: <p><b>Table of Contents</b></p>
! 7535: <dl>
! 7536: <dt><span class="chapter"><a href="#infr.design">20. Design of the pkgsrc infrastructure</a></span></dt>
! 7537: <dd><dl>
! 7538: <dt><span class="sect1"><a href="#infr.var">20.1. Variable evaluation</a></span></dt>
! 7539: <dd><dl>
! 7540: <dt><span class="sect2"><a href="#infr.var.load">20.1.1. At load time</a></span></dt>
! 7541: <dt><span class="sect2"><a href="#infr.var.run">20.1.2. At runtime</a></span></dt>
! 7542: </dl></dd>
! 7543: <dt><span class="sect1"><a href="#infr.design.intf">20.2. Designing interfaces for Makefile fragments</a></span></dt>
! 7544: <dd><dl>
! 7545: <dt><span class="sect2"><a href="#infr.design.intf.proc">20.2.1. Procedures with parameters</a></span></dt>
! 7546: <dt><span class="sect2"><a href="#infr.design.intf.action">20.2.2. Actions taken on behalf of parameters</a></span></dt>
! 7547: </dl></dd>
! 7548: </dl></dd>
! 7549: <dt><span class="chapter"><a href="#regression">21. Regression tests</a></span></dt>
! 7550: <dd><dl>
! 7551: <dt><span class="sect1"><a href="#regression.descr">21.1. The regression tests framework</a></span></dt>
! 7552: <dt><span class="sect1"><a href="#regression.run">21.2. Running the regression tests</a></span></dt>
! 7553: <dt><span class="sect1"><a href="#regression.new">21.3. Adding a new regression test</a></span></dt>
! 7554: <dd><dl>
! 7555: <dt><span class="sect2"><a href="#regression.fun.override">21.3.1. Overridable functions</a></span></dt>
! 7556: <dt><span class="sect2"><a href="#regression.fun.helper">21.3.2. Helper functions</a></span></dt>
! 7557: </dl></dd>
! 7558: </dl></dd>
! 7559: <dt><span class="chapter"><a href="#porting">22. Porting pkgsrc</a></span></dt>
! 7560: <dd><dl>
! 7561: <dt><span class="sect1"><a href="#porting.opsys">22.1. Porting pkgsrc to a new operating system</a></span></dt>
! 7562: <dt><span class="sect1"><a href="#porting.compiler">22.2. Adding support for a new compiler</a></span></dt>
! 7563: </dl></dd>
! 7564: </dl>
! 7565: </div>
! 7566: </div>
! 7567: <div class="chapter" lang="en">
! 7568: <div class="titlepage"><div><div><h2 class="title">
! 7569: <a name="infr.design"></a>Chapter 20. Design of the pkgsrc infrastructure</h2></div></div></div>
! 7570: <div class="toc">
! 7571: <p><b>Table of Contents</b></p>
! 7572: <dl>
! 7573: <dt><span class="sect1"><a href="#infr.var">20.1. Variable evaluation</a></span></dt>
! 7574: <dd><dl>
! 7575: <dt><span class="sect2"><a href="#infr.var.load">20.1.1. At load time</a></span></dt>
! 7576: <dt><span class="sect2"><a href="#infr.var.run">20.1.2. At runtime</a></span></dt>
! 7577: </dl></dd>
! 7578: <dt><span class="sect1"><a href="#infr.design.intf">20.2. Designing interfaces for Makefile fragments</a></span></dt>
! 7579: <dd><dl>
! 7580: <dt><span class="sect2"><a href="#infr.design.intf.proc">20.2.1. Procedures with parameters</a></span></dt>
! 7581: <dt><span class="sect2"><a href="#infr.design.intf.action">20.2.2. Actions taken on behalf of parameters</a></span></dt>
! 7582: </dl></dd>
! 7583: </dl>
! 7584: </div>
! 7585: <p>The pkgsrc infrastructure consists of many small Makefile
! 7586: fragments. Each such fragment needs a properly specified
! 7587: interface. This chapter explains how such an interface looks
! 7588: like.</p>
! 7589: <div class="sect1" lang="en">
! 7590: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7591: <a name="infr.var"></a>20.1. Variable evaluation</h2></div></div></div>
! 7592: <div class="sect2" lang="en">
! 7593: <div class="titlepage"><div><div><h3 class="title">
! 7594: <a name="infr.var.load"></a>20.1.1. At load time</h3></div></div></div>
! 7595: <p>Variable evaluation takes place either at load time or at
! 7596: runtime, depending on the context in which they occur. The
! 7597: contexts where variables are evaluated at load time are:</p>
! 7598: <div class="itemizedlist"><ul type="disc">
! 7599: <li><p>The right hand side of the <code class="literal">:=</code>
! 7600: and <code class="literal">!=</code> operators,</p></li>
! 7601: <li><p>Make directives like <code class="literal">.if</code> or
! 7602: <code class="literal">.for</code>,</p></li>
! 7603: <li><p>Dependency lines.</p></li>
! 7604: </ul></div>
! 7605: <p>A special exception are references to the iteration
! 7606: variables of <code class="literal">.for</code> loops, which are expanded
! 7607: inline, no matter in which context they appear.</p>
! 7608: <p>As the values of variables may change during load time,
! 7609: care must be taken not to evaluate them by accident. Typical
! 7610: examples for variables that should not be evaluated at load time
! 7611: are <code class="varname">DEPENDS</code> and
! 7612: <code class="varname">CONFIGURE_ARGS</code>. To make the effect more
! 7613: clear, here is an example:</p>
! 7614: <pre class="programlisting">
! 7615: CONFIGURE_ARGS= # none
! 7616: CFLAGS= -O
! 7617: CONFIGURE_ARGS+= CFLAGS=${CFLAGS:Q}
1.1 grant 7618:
1.75 ! rillig 7619: CONFIGURE_ARGS:= ${CONFIGURE_ARGS}
1.1 grant 7620:
1.75 ! rillig 7621: CFLAGS+= -Wall
! 7622: </pre>
! 7623: <p>This code shows how the use of the <code class="literal">:=</code>
! 7624: operator can quickly lead to unexpected results. The first
! 7625: paragraph is fairly common code. The second paragraph evaluates
! 7626: the <code class="varname">CONFIGURE_ARGS</code> variable, which results in
! 7627: <code class="literal">CFLAGS=-O</code>. In the third paragraph, the
! 7628: <code class="literal">-Wall</code> is appended to the
! 7629: <code class="varname">CFLAGS</code>, but this addition will not appear in
! 7630: <code class="varname">CONFIGURE_ARGS</code>. In actual code, the three
! 7631: paragraphs from above typically occur in completely unrelated
! 7632: files.</p>
! 7633: </div>
! 7634: <div class="sect2" lang="en">
! 7635: <div class="titlepage"><div><div><h3 class="title">
! 7636: <a name="infr.var.run"></a>20.1.2. At runtime</h3></div></div></div>
! 7637: <p>After all the files have been loaded, the values of the
! 7638: variables cannot be changed anymore. Variables that are used in
! 7639: the shell commands are expanded at this point.</p>
! 7640: </div>
! 7641: </div>
! 7642: <div class="sect1" lang="en">
! 7643: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7644: <a name="infr.design.intf"></a>20.2. Designing interfaces for Makefile fragments</h2></div></div></div>
! 7645: <p>Most of the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.mk</code> files fall into one
! 7646: of the following classes. Cases where a file falls into more
! 7647: than one class should be avoided as it often leads to subtle
! 7648: bugs.</p>
! 7649: <div class="sect2" lang="en">
! 7650: <div class="titlepage"><div><div><h3 class="title">
! 7651: <a name="infr.design.intf.proc"></a>20.2.1. Procedures with parameters</h3></div></div></div>
! 7652: <p>In a traditional imperative programming language some of
! 7653: the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">.mk</code> files could be described as
! 7654: procedures. They take some input parameters and—after
! 7655: inclusion—provide a result in output parameters. Since all
! 7656: variables in <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>s have global scope
! 7657: care must be taken not to use parameter names that have already
! 7658: another meaning. For example, <code class="varname">PKGNAME</code> is a
! 7659: bad choice for a parameter name.</p>
! 7660: <p>Procedures are completely evaluated at preprocessing time.
! 7661: That is, when calling a procedure all input parameters must be
! 7662: completely resolvable. For example,
! 7663: <code class="varname">CONFIGURE_ARGS</code> should never be an input
! 7664: parameter since it is very likely that further text will be
! 7665: added after calling the procedure, which would effectively apply
! 7666: the procedure to only a part of the variable. Also, references
! 7667: to other variables wit will be modified after calling the
! 7668: procedure.</p>
! 7669: <p>A procedure can declare its output parameters either as
! 7670: suitable for use in preprocessing directives or as only
! 7671: available at runtime. The latter alternative is for variables
! 7672: that contain references to other runtime variables.</p>
! 7673: <p>Procedures shall be written such that it is possible to
! 7674: call the procedure more than once. That is, the file must not
! 7675: contain multiple-inclusion guards.</p>
! 7676: <p>Examples for procedures are
! 7677: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bsd.options.mk</code> and
! 7678: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/buildlink3/bsd.builtin.mk</code>. To express
! 7679: that the parameters are evaluated at load time, they should be
! 7680: assigned using the <code class="literal">:=</code> operator, which should
! 7681: be used only for this purpose.</p>
! 7682: </div>
! 7683: <div class="sect2" lang="en">
! 7684: <div class="titlepage"><div><div><h3 class="title">
! 7685: <a name="infr.design.intf.action"></a>20.2.2. Actions taken on behalf of parameters</h3></div></div></div>
! 7686: <p>Action files take some input parameters and may define
! 7687: runtime variables. They shall not define loadtime variables.
! 7688: There are action files that are included implicitly by the
! 7689: pkgsrc infrastructure, while other must be included
! 7690: explicitly.</p>
! 7691: <p>An example for action files is
! 7692: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/subst.mk</code>.</p>
! 7693: </div>
! 7694: </div>
! 7695: </div>
! 7696: <div class="chapter" lang="en">
! 7697: <div class="titlepage"><div><div><h2 class="title">
! 7698: <a name="regression"></a>Chapter 21. Regression tests</h2></div></div></div>
! 7699: <div class="toc">
! 7700: <p><b>Table of Contents</b></p>
! 7701: <dl>
! 7702: <dt><span class="sect1"><a href="#regression.descr">21.1. The regression tests framework</a></span></dt>
! 7703: <dt><span class="sect1"><a href="#regression.run">21.2. Running the regression tests</a></span></dt>
! 7704: <dt><span class="sect1"><a href="#regression.new">21.3. Adding a new regression test</a></span></dt>
! 7705: <dd><dl>
! 7706: <dt><span class="sect2"><a href="#regression.fun.override">21.3.1. Overridable functions</a></span></dt>
! 7707: <dt><span class="sect2"><a href="#regression.fun.helper">21.3.2. Helper functions</a></span></dt>
! 7708: </dl></dd>
! 7709: </dl>
! 7710: </div>
! 7711: <p>The pkgsrc infrastructure consists of a large codebase,
! 7712: and there are many corners where every little bit of a file is
! 7713: well thought out, making pkgsrc likely to fail as soon as
! 7714: anything is changed near those parts. To prevent most changes
! 7715: from breaking anything, a suite of regression tests should go
! 7716: along with every important part of the pkgsrc infrastructure.
! 7717: This chapter describes how regression tests work in pkgsrc and
! 7718: how you can add new tests.</p>
! 7719: <div class="sect1" lang="en">
! 7720: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7721: <a name="regression.descr"></a>21.1. The regression tests framework</h2></div></div></div>
! 7722: <p></p>
! 7723: </div>
! 7724: <div class="sect1" lang="en">
! 7725: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7726: <a name="regression.run"></a>21.2. Running the regression tests</h2></div></div></div>
! 7727: <p>You first need to install the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_regress/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkg_regress</code></a> package, which
! 7728: provides the <span><strong class="command">pkg_regress</strong></span> command. Then you
! 7729: can simply run that command, which will run all tests in the
! 7730: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">regress</code> category.</p>
! 7731: </div>
! 7732: <div class="sect1" lang="en">
! 7733: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7734: <a name="regression.new"></a>21.3. Adding a new regression test</h2></div></div></div>
! 7735: <p>Every directory in the <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">regress</code>
! 7736: category that contains a file called <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">spec</code>
! 7737: is considered a regression test. This file is a shell program
! 7738: that is included by the <span><strong class="command">pkg_regress</strong></span> command.
! 7739: The following functions can be overridden to suit your
! 7740: needs.</p>
! 7741: <div class="sect2" lang="en">
! 7742: <div class="titlepage"><div><div><h3 class="title">
! 7743: <a name="regression.fun.override"></a>21.3.1. Overridable functions</h3></div></div></div>
! 7744: <p>These functions do not take any parameters. They are all
! 7745: called in “<span class="quote">set -e</span>” mode, so you should be careful
! 7746: to check the exitcodes of any commands you run in the
! 7747: test.</p>
! 7748: <div class="variablelist"><dl>
! 7749: <dt><span class="term"><code class="varname">do_setup()</code></span></dt>
! 7750: <dd><p>This function prepares the environment for the
! 7751: test. By default it does nothing.</p></dd>
! 7752: <dt><span class="term"><code class="varname">do_test()</code></span></dt>
! 7753: <dd><p>This function runs the actual test. By default,
! 7754: it calls <code class="varname">TEST_MAKE</code> with the arguments
! 7755: <code class="varname">MAKEARGS_TEST</code> and writes its output including
! 7756: error messages into the file
! 7757: <code class="varname">TEST_OUTFILE</code>.</p></dd>
! 7758: <dt><span class="term"><code class="varname">check_result()</code></span></dt>
! 7759: <dd><p>This function is run after the test and is
! 7760: typically used to compare the actual output from the one that is
! 7761: expected. It can make use of the various helper functions from
! 7762: the next section.</p></dd>
! 7763: <dt><span class="term"><code class="varname">do_cleanup()</code></span></dt>
! 7764: <dd><p>This function cleans everything up after the
! 7765: test has been run. By default it does nothing.</p></dd>
! 7766: </dl></div>
! 7767: </div>
! 7768: <div class="sect2" lang="en">
! 7769: <div class="titlepage"><div><div><h3 class="title">
! 7770: <a name="regression.fun.helper"></a>21.3.2. Helper functions</h3></div></div></div>
! 7771: <div class="variablelist"><dl>
! 7772: <dt><span class="term"><code class="varname">exit_status(expected)</code></span></dt>
! 7773: <dd><p>This function compares the exitcode of the
! 7774: <span><strong class="command">do_test()</strong></span> function with its first parameter.
! 7775: If they differ, the test will fail.</p></dd>
! 7776: <dt><span class="term"><code class="varname">output_require(regex...)</code></span></dt>
! 7777: <dd><p>This function checks for each of its parameters
! 7778: if the output from <span><strong class="command">do_test()</strong></span> matches the
! 7779: extended regular expression. If it does not, the test will
! 7780: fail.</p></dd>
! 7781: <dt><span class="term"><code class="varname">output_prohibit(regex...)</code></span></dt>
! 7782: <dd><p>This function checks for each of its parameters
! 7783: if the output from <span><strong class="command">do_test()</strong></span> does
! 7784: <span class="emphasis"><em>not</em></span> match the extended regular expression.
! 7785: If any of the regular expressions matches, the test will
! 7786: fail.</p></dd>
! 7787: </dl></div>
! 7788: </div>
! 7789: </div>
! 7790: </div>
! 7791: <div class="chapter" lang="en">
! 7792: <div class="titlepage"><div><div><h2 class="title">
! 7793: <a name="porting"></a>Chapter 22. Porting pkgsrc</h2></div></div></div>
! 7794: <div class="toc">
! 7795: <p><b>Table of Contents</b></p>
! 7796: <dl>
! 7797: <dt><span class="sect1"><a href="#porting.opsys">22.1. Porting pkgsrc to a new operating system</a></span></dt>
! 7798: <dt><span class="sect1"><a href="#porting.compiler">22.2. Adding support for a new compiler</a></span></dt>
! 7799: </dl>
! 7800: </div>
! 7801: <p>The pkgsrc system has already been ported to many
! 7802: operating systems, hardware architectures and compilers. This
! 7803: chapter explains the necessary steps to make pkgsrc even more
! 7804: portable.</p>
! 7805: <div class="sect1" lang="en">
! 7806: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7807: <a name="porting.opsys"></a>22.1. Porting pkgsrc to a new operating system</h2></div></div></div>
! 7808: <p>To port pkgsrc to a new operating system (called
! 7809: <code class="literal">MyOS</code> in this example), you need to touch the
! 7810: following files:</p>
! 7811: <div class="variablelist"><dl>
! 7812: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">bootstrap/mods/mk/<em class="replaceable"><code>MyOS</code></em>.sys.mk</code></span></dt>
! 7813: <dd><p>This file contains some basic definitions, for
! 7814: example the name of the C
! 7815: compiler.</p></dd>
! 7816: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/bsd.prefs.mk</code></span></dt>
! 7817: <dd><p>Insert code that defines the variables
! 7818: <code class="varname">OPSYS</code>, <code class="varname">OS_VERSION</code>,
! 7819: <code class="varname">LOWER_OS_VERSION</code>,
! 7820: <code class="varname">LOWER_VENDOR</code>,
! 7821: <code class="varname">MACHINE_ARCH</code>, <code class="varname">OBJECT_FMT</code>,
! 7822: <code class="varname">APPEND_ELF</code>, and the other variables that
! 7823: appear in this file.</p></dd>
! 7824: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/platform/MyOS.mk</code></span></dt>
! 7825: <dd><p>This file contains the platform-specific
! 7826: definitions that are used by pkgsrc. Start by copying one of the
! 7827: other files and edit it to your
! 7828: needs.</p></dd>
! 7829: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/platform/MyOS.pkg.dist</code></span></dt>
! 7830: <dd><p>This file contains a list of directories,
! 7831: together with their permission bits and ownership. These
! 7832: directories will be created automatically with every package
! 7833: that does not explicitly set <code class="varname">NO_MTREE</code>. There
! 7834: have been some discussions about whether this file is needed at
! 7835: all, but with no result.</p></dd>
! 7836: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/platform/MyOS.x11.dist</code></span></dt>
! 7837: <dd><p>Just copy one of the pre-existing x11.dist files
! 7838: to your
! 7839: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename"><em class="replaceable"><code>MyOS</code></em>.x11.dist</code>.</p></dd>
! 7840: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/tools/bootstrap.mk</code></span></dt>
! 7841: <dd><p>On some operating systems, the tools that are
! 7842: provided with the base system are not good enough for pkgsrc.
! 7843: For example, there are many versions of <a href="http://netbsd.gw.com/cgi-bin/man-cgi?sed+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> that have a
! 7844: narrow limit on the line length they can process. Therefore
! 7845: pkgsrc brings its own tools, which can be enabled
! 7846: here.</p></dd>
! 7847: <dt><span class="term"><code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">mk/tools/<em class="replaceable"><code>MyOS</code></em>.mk</code></span></dt>
! 7848: <dd><p>This file defines the paths to all the tools
! 7849: that are needed by one or the other package in pkgsrc, as well
! 7850: as by pkgsrc itself. Find out where these tools are on your
! 7851: platform and add them.</p></dd>
! 7852: </dl></div>
! 7853: <p>Now, you should be able to build some basic packages, like
! 7854: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/perl5/README.html" target="_top"><code xmlns="" class="filename">lang/perl5</code></a>, <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/bash/README.html" target="_top"><code xmlns="" class="filename">shells/bash</code></a>.</p>
! 7855: </div>
! 7856: <div class="sect1" lang="en">
! 7857: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7858: <a name="porting.compiler"></a>22.2. Adding support for a new compiler</h2></div></div></div>
! 7859: <p>TODO</p>
! 7860: </div>
! 7861: </div>
! 7862: </div>
! 7863: <div class="appendix" lang="en">
! 7864: <div class="titlepage"><div><div><h2 class="title">
! 7865: <a name="examples"></a>Appendix A. A simple example package: bison</h2></div></div></div>
! 7866: <div class="toc">
! 7867: <p><b>Table of Contents</b></p>
! 7868: <dl>
! 7869: <dt><span class="sect1"><a href="#example-files">A.1. files</a></span></dt>
! 7870: <dd><dl>
! 7871: <dt><span class="sect2"><a href="#example-Makefile">A.1.1. Makefile</a></span></dt>
! 7872: <dt><span class="sect2"><a href="#example-descr">A.1.2. DESCR</a></span></dt>
! 7873: <dt><span class="sect2"><a href="#example-plist">A.1.3. PLIST</a></span></dt>
! 7874: <dt><span class="sect2"><a href="#checking-package-with-pkglint">A.1.4. Checking a package with <span><strong class="command">pkglint</strong></span></a></span></dt>
! 7875: </dl></dd>
! 7876: <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2. Steps for building, installing, packaging</a></span></dt>
! 7877: </dl>
! 7878: </div>
! 7879: <p>We checked to find a piece of software that wasn't in the packages
! 7880: collection, and picked GNU bison. Quite why someone would want to have
! 7881: <span><strong class="command">bison</strong></span> when Berkeley <span><strong class="command">yacc</strong></span> is already
! 7882: present in the tree is beyond us, but it's useful for the purposes of
! 7883: this exercise.</p>
! 7884: <div class="sect1" lang="en">
! 7885: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7886: <a name="example-files"></a>A.1. files</h2></div></div></div>
! 7887: <div class="sect2" lang="en">
! 7888: <div class="titlepage"><div><div><h3 class="title">
! 7889: <a name="example-Makefile"></a>A.1.1. Makefile</h3></div></div></div>
! 7890: <pre class="programlisting">
1.51 rillig 7891: # $NetBSD$
7892: #
1.1 grant 7893:
1.51 rillig 7894: DISTNAME= bison-1.25
7895: CATEGORIES= devel
7896: MASTER_SITES= ${MASTER_SITE_GNU}
1.1 grant 7897:
1.51 rillig 7898: MAINTAINER= thorpej@NetBSD.org
7899: HOMEPAGE= http://www.gnu.org/software/bison/bison.html
7900: COMMENT= GNU yacc clone
1.1 grant 7901:
1.51 rillig 7902: GNU_CONFIGURE= yes
7903: INFO_FILES= bison.info
1.1 grant 7904:
1.51 rillig 7905: .include "../../mk/bsd.pkg.mk"
1.1 grant 7906: </pre>
1.75 ! rillig 7907: </div>
! 7908: <div class="sect2" lang="en">
! 7909: <div class="titlepage"><div><div><h3 class="title">
! 7910: <a name="example-descr"></a>A.1.2. DESCR</h3></div></div></div>
! 7911: <pre class="programlisting">
1.51 rillig 7912: GNU version of yacc. Can make re-entrant parsers, and numerous other
1.75 ! rillig 7913: improvements. Why you would want this when Berkeley <a href="http://netbsd.gw.com/cgi-bin/man-cgi?yacc+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">yacc</span>(1)</span></a> is part
1.51 rillig 7914: of the NetBSD source tree is beyond me.
1.1 grant 7915: </pre>
1.75 ! rillig 7916: </div>
! 7917: <div class="sect2" lang="en">
! 7918: <div class="titlepage"><div><div><h3 class="title">
! 7919: <a name="example-plist"></a>A.1.3. PLIST</h3></div></div></div>
! 7920: <pre class="programlisting">
1.51 rillig 7921: @comment $NetBSD$
7922: bin/bison
7923: man/man1/bison.1.gz
7924: share/bison.simple
7925: share/bison.hairy
1.1 grant 7926: </pre>
1.75 ! rillig 7927: </div>
! 7928: <div class="sect2" lang="en">
! 7929: <div class="titlepage"><div><div><h3 class="title">
! 7930: <a name="checking-package-with-pkglint"></a>A.1.4. Checking a package with <span><strong class="command">pkglint</strong></span></h3></div></div></div>
! 7931: <p>The NetBSD package system comes with
! 7932: <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html" target="_top"><code xmlns="" class="filename">pkgtools/pkglint</code></a>
! 7933: which helps to check the contents of these
! 7934: files. After installation it is quite easy to use, just change to the
! 7935: directory of the package you wish to examine and execute
! 7936: <span><strong class="command">pkglint</strong></span>:</p>
! 7937: <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pkglint</code></strong>
! 7938: looks fine.</pre>
! 7939: <p>Depending on the supplied command line arguments (see pkglint(1)),
! 7940: more checks will be performed. Use e.g. <span><strong class="command">pkglint -Call
! 7941: -Wall</strong></span> for a very thorough check.</p>
! 7942: </div>
! 7943: </div>
! 7944: <div class="sect1" lang="en">
! 7945: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 7946: <a name="steps-for-b-i-p"></a>A.2. Steps for building, installing, packaging</h2></div></div></div>
! 7947: <p>Create the directory where the package lives,
! 7948: plus any auxiliary directories:</p>
! 7949: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/pkgsrc/lang</code></strong>
! 7950: <code class="prompt">#</code> <strong class="userinput"><code>mkdir bison</code></strong>
! 7951: <code class="prompt">#</code> <strong class="userinput"><code>cd bison</code></strong>
! 7952: <code class="prompt">#</code> <strong class="userinput"><code>mkdir patches</code></strong></pre>
! 7953: <p>Create <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">Makefile</code>, <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">DESCR</code> and
! 7954: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">PLIST</code> (see <a href="#components" title="Chapter 8. Package components - files, directories and contents">Chapter 8, <i>Package components - files, directories and contents</i></a>)
! 7955: then continue with fetching the distfile:</p>
! 7956: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make fetch</code></strong>
1.1 grant 7957: >> bison-1.25.tar.gz doesn't seem to exist on this system.
7958: >> Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//.
7959: Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
7960: ftp: Error retrieving file: 500 Internal error
7961:
7962: >> Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//.
7963: Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
7964: ftp: Error retrieving file: 500 Internal error
7965:
7966: >> Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//.
7967: Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
1.75 ! rillig 7968: Successfully retrieved file.</pre>
! 7969: <p>Generate the checksum of the distfile into
! 7970: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">distinfo</code>:</p>
! 7971: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make makesum</code></strong></pre>
! 7972: <p>Now compile:</p>
! 7973: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make</code></strong>
1.1 grant 7974: >> Checksum OK for bison-1.25.tar.gz.
7975: ===> Extracting for bison-1.25
7976: ===> Patching for bison-1.25
7977: ===> Ignoring empty patch directory
7978: ===> Configuring for bison-1.25
7979: creating cache ./config.cache
7980: checking for gcc... cc
7981: checking whether we are using GNU C... yes
7982: checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin
7983: checking how to run the C preprocessor... cc -E
7984: checking for minix/config.h... no
7985: checking for POSIXized ISC... no
7986: checking whether cross-compiling... no
7987: checking for ANSI C header files... yes
7988: checking for string.h... yes
7989: checking for stdlib.h... yes
7990: checking for memory.h... yes
7991: checking for working const... yes
7992: checking for working alloca.h... no
7993: checking for alloca... yes
7994: checking for strerror... yes
7995: updating cache ./config.cache
7996: creating ./config.status
7997: creating Makefile
7998: ===> Building for bison-1.25
7999: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g LR0.c
8000: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g allocate.c
8001: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g closure.c
8002: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g conflicts.c
8003: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g derives.c
1.68 rillig 8004: cc -c -DXPFILE=\"/usr/pkg/share/bison.simple\" -DXPFILE1=\"/usr/pkg/share/bison.hairy\" -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -g ./files.c
1.1 grant 8005: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getargs.c
8006: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g gram.c
8007: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g lalr.c
8008: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g lex.c
8009: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g main.c
8010: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g nullable.c
8011: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g output.c
8012: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g print.c
8013: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g reader.c
8014: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g reduce.c
8015: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g symtab.c
8016: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g warshall.c
8017: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g version.c
8018: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getopt.c
8019: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getopt1.c
8020: cc -g -o bison LR0.o allocate.o closure.o conflicts.o derives.o files.o getargs.o gram.o lalr.o lex.o main.o nullable.o output.o print.o reader.o reduce.o symtab.o warshall.o version.o getopt.o getopt1.o
8021: ./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp()
8022: rm -f bison.s1
1.75 ! rillig 8023: sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" < ./bison.simple > bison.s1</pre>
! 8024: <p>Everything seems OK, so install the files:</p>
! 8025: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
1.1 grant 8026: >> Checksum OK for bison-1.25.tar.gz.
8027: ===> Installing for bison-1.25
8028: sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share /usr/pkg/info /usr/pkg/man/man1
8029: rm -f /usr/pkg/bin/bison
8030: cd /usr/pkg/share; rm -f bison.simple bison.hairy
8031: rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info*
8032: install -c -o bin -g bin -m 555 bison /usr/pkg/bin/bison
8033: /usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple
8034: /usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy
8035: cd .; for f in bison.info*; do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done
8036: /usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1
1.75 ! rillig 8037: ===> Registering installation for bison-1.25</pre>
! 8038: <p>You can now use bison, and also - if you decide so - remove it with
! 8039: <span><strong class="command">pkg_delete bison</strong></span>. Should you decide that you want a
! 8040: binary package, do this now:</p>
! 8041: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make package</code></strong>
1.1 grant 8042: >> Checksum OK for bison-1.25.tar.gz.
8043: ===> Building package for bison-1.25
8044: Creating package bison-1.25.tgz
8045: Registering depends:.
1.75 ! rillig 8046: Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'</pre>
! 8047: <p>Now that you don't need the source and object files
! 8048: any more, clean up:</p>
! 8049: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make clean</code></strong>
! 8050: ===> Cleaning for bison-1.25</pre>
! 8051: </div>
! 8052: </div>
! 8053: <div class="appendix" lang="en">
! 8054: <div class="titlepage"><div><div><h2 class="title">
! 8055: <a name="logs"></a>Appendix B. Build logs</h2></div></div></div>
! 8056: <div class="toc">
! 8057: <p><b>Table of Contents</b></p>
! 8058: <dl>
! 8059: <dt><span class="sect1"><a href="#logs.building">B.1. Building figlet</a></span></dt>
! 8060: <dt><span class="sect1"><a href="#logs.package">B.2. Packaging figlet</a></span></dt>
! 8061: </dl>
! 8062: </div>
! 8063: <div class="sect1" lang="en">
! 8064: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 8065: <a name="logs.building"></a>B.1. Building figlet</h2></div></div></div>
! 8066: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make</code></strong>
1.1 grant 8067: ===> Checking for vulnerabilities in figlet-2.2.1nb2
8068: => figlet221.tar.gz doesn't seem to exist on this system.
8069: => Attempting to fetch figlet221.tar.gz from ftp://ftp.figlet.org/pub/figlet/program/unix/.
8070: => [172219 bytes]
8071: Connected to ftp.plig.net.
8072: 220 ftp.plig.org NcFTPd Server (licensed copy) ready.
8073: 331 Guest login ok, send your complete e-mail address as password.
8074: 230-You are user #5 of 500 simultaneous users allowed.
8075: 230-
1.68 rillig 8076: 230- ___ _ _ _
8077: 230- | _| |_ ___ ___| |_|___ ___ ___ ___
1.1 grant 8078: 230- | _| _| . |_| . | | | . |_| . | _| . |
8079: 230- |_| |_| | _|_| _|_|_|_ |_|___|_| |_ |
8080: 230- |_| |_| |___| |___|
8081: 230-
8082: 230-** Welcome to ftp.plig.org **
8083: 230-
8084: 230-Please note that all transfers from this FTP site are logged. If you
8085: 230-do not like this, please disconnect now.
8086: 230-
8087: 230-This arhive is available via
8088: 230-
8089: 230-HTTP: http://ftp.plig.org/
8090: 230-FTP: ftp://ftp.plig.org/ (max 500 connections)
8091: 230-RSYNC: rsync://ftp.plig.org/ (max 30 connections)
8092: 230-
8093: 230-Please email comments, bug reports and requests for packages to be
1.68 rillig 8094: 230-mirrored to ftp-admin@plig.org.
1.1 grant 8095: 230-
8096: 230-
8097: 230 Logged in anonymously.
8098: Remote system type is UNIX.
8099: Using binary mode to transfer files.
8100: 200 Type okay.
8101: 250 "/pub" is new cwd.
8102: 250-"/pub/figlet" is new cwd.
8103: 250-
8104: 250-Welcome to the figlet archive at ftp.figlet.org
1.68 rillig 8105: 250-
1.75 ! rillig 8106: 250- ftp://ftp.figlet.org/pub/figlet/
1.1 grant 8107: 250-
8108: 250-The official FIGlet web page is:
1.75 ! rillig 8109: 250- http://www.figlet.org/
1.1 grant 8110: 250-
8111: 250-If you have questions, please mailto:info@figlet.org. If you want to
8112: 250-contribute a font or something else, you can email us.
1.68 rillig 8113: 250
1.1 grant 8114: 250 "/pub/figlet/program" is new cwd.
8115: 250 "/pub/figlet/program/unix" is new cwd.
8116: local: figlet221.tar.gz remote: figlet221.tar.gz
8117: 502 Unimplemented command.
8118: 227 Entering Passive Mode (195,40,6,41,246,104)
8119: 150 Data connection accepted from 84.128.86.72:65131; transfer starting for figlet221.tar.gz (172219 bytes).
8120: 38% |************** | 65800 64.16 KB/s 00:01 ETA
8121: 226 Transfer completed.
8122: 172219 bytes received in 00:02 (75.99 KB/s)
8123: 221 Goodbye.
8124: => Checksum OK for figlet221.tar.gz.
8125: ===> Extracting for figlet-2.2.1nb2
8126: ===> Required installed package ccache-[0-9]*: ccache-2.3nb1 found
8127: ===> Patching for figlet-2.2.1nb2
8128: ===> Applying pkgsrc patches for figlet-2.2.1nb2
8129: ===> Overriding tools for figlet-2.2.1nb2
8130: ===> Creating toolchain wrappers for figlet-2.2.1nb2
8131: ===> Configuring for figlet-2.2.1nb2
8132: ===> Building for figlet-2.2.1nb2
8133: gcc -O2 -DDEFAULTFONTDIR=\"/usr/pkg/share/figlet\" -DDEFAULTFONTFILE=\"standard.flf\" figlet.c zipio.c crc.c inflate.c -o figlet
8134: chmod a+x figlet
8135: gcc -O2 -o chkfont chkfont.c
8136: => Unwrapping files-to-be-installed.
1.14 xtraeme 8137: <code class="prompt">#</code>
1.75 ! rillig 8138: <code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
1.1 grant 8139: ===> Checking for vulnerabilities in figlet-2.2.1nb2
8140: ===> Installing for figlet-2.2.1nb2
8141: install -d -o root -g wheel -m 755 /usr/pkg/bin
8142: install -d -o root -g wheel -m 755 /usr/pkg/man/man6
8143: mkdir -p /usr/pkg/share/figlet
8144: cp figlet /usr/pkg/bin
8145: cp chkfont /usr/pkg/bin
8146: chmod 555 figlist showfigfonts
8147: cp figlist /usr/pkg/bin
8148: cp showfigfonts /usr/pkg/bin
8149: cp fonts/*.flf /usr/pkg/share/figlet
8150: cp fonts/*.flc /usr/pkg/share/figlet
8151: cp figlet.6 /usr/pkg/man/man6
8152: ===> Registering installation for figlet-2.2.1nb2
1.75 ! rillig 8153: <code class="prompt">#</code></pre>
! 8154: </div>
! 8155: <div class="sect1" lang="en">
! 8156: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 8157: <a name="logs.package"></a>B.2. Packaging figlet</h2></div></div></div>
! 8158: <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make package</code></strong>
1.1 grant 8159: ===> Checking for vulnerabilities in figlet-2.2.1nb2
8160: ===> Packaging figlet-2.2.1nb2
8161: ===> Building binary package for figlet-2.2.1nb2
8162: Creating package /home/cvs/pkgsrc/packages/i386/All/figlet-2.2.1nb2.tgz
8163: Using SrcDir value of /usr/pkg
1.68 rillig 8164: Registering depends:.
1.75 ! rillig 8165: <code class="prompt">#</code></pre>
! 8166: </div>
! 8167: </div>
! 8168: <div class="appendix" lang="en">
! 8169: <div class="titlepage"><div><div><h2 class="title">
! 8170: <a name="ftp-layout"></a>Appendix C. Layout of the FTP server's package archive</h2></div></div></div>
! 8171: <p>Layout for precompiled binary packages on ftp.NetBSD.org:</p>
! 8172: <pre class="programlisting">
1.51 rillig 8173: /pub/NetBSD/packages/
8174: distfiles/
1.1 grant 8175:
1.51 rillig 8176: # Unpacked pkgsrc trees
8177: pkgsrc-current -> /pub/NetBSD/NetBSD-current/pkgsrc
8178: pkgsrc-2003Q4 -> N/A
8179: pkgsrc-2004Q1/pkgsrc
8180:
8181: # pkgsrc archives
8182: pkgsrc-current.tar.gz -> ../NetBSD-current/tar_files/pkgsrc.tar.gz
8183: pkgsrc-2003Q4.tar.gz -> N/A
8184: pkgsrc-2004Q1.tar.gz -> N/A
8185:
8186: # Per pkgsrc-release/OS-release/arch package archives
8187: pkgsrc-2003Q4/
8188: NetBSD-1.6.2/
8189: i386/
8190: All/
8191: archivers/
8192: foo -> ../All/foo
8193: ...
8194: pkgsrc-2004Q1/
8195: NetBSD-1.6.2/
8196: i386/
8197: All/
8198: ...
8199: NetBSD-2.0/
8200: i386/
8201: All/
8202: ...
8203: SunOS-5.9/
8204: sparc/
8205: All/
8206: ...
8207: x86/
8208: All/
8209: ...
8210:
8211: # Per os-release package archive convenience links
8212: NetBSD-1.6.2 -> 1.6.2
8213: 1.6.2/
8214: i386 -> ../pkgsrc-2004Q1/NetBSD-1.6.2/i386
8215: m68k/
8216: All/
8217: archivers/
8218: foo -> ../All/foo
8219: ...
8220: amiga -> m68k
8221: atari -> m68k
8222: ...
8223:
8224: 2.0 -> NetBSD-2.0 # backward compat, historic
8225: NetBSD-2.0/
8226: i386 -> ../pkgsrc-2004Q1/NetBSD-2.0/i386
8227: SunOS-5.9/
8228: sparc -> ../pkgsrc-2004Q1/SunOS-5.9/sparc
8229: x86 -> ../pkgsrc-2004Q1/SunOS-5.9/x86
1.1 grant 8230: </pre>
1.75 ! rillig 8231: <p>
! 8232: To create:</p>
! 8233: <div class="orderedlist"><ol type="1">
! 8234: <li><p> Run bulk build, see <a href="#bulkbuild" title="6.3. Doing a bulk build of all packages">Section 6.3, “Doing a bulk build of all packages”</a> </p></li>
! 8235: <li>
! 8236: <p> Upload /usr/pkgsrc/packages to </p>
! 8237: <pre class="programlisting">
1.1 grant 8238: ftp://ftp.NetBSD.org/pub/NetBSD/packages/\
1.51 rillig 8239: pkgsrc-2004Q4/\ # pkgsrc-branch
8240: `uname -s`-`uname -r`/\ # OS & version
8241: `uname -p` # architecture
1.1 grant 8242: </pre>
1.75 ! rillig 8243: </li>
! 8244: <li><p> If necessary, create a symlink <span><strong class="command">ln -s `uname -m` `uname
! 8245: -p`</strong></span> (amiga -> m68k, ...) </p></li>
! 8246: </ol></div>
! 8247: </div>
! 8248: <div class="appendix" lang="en">
! 8249: <div class="titlepage"><div><div><h2 class="title">
! 8250: <a name="editing"></a>Appendix D. Editing guidelines for the pkgsrc guide</h2></div></div></div>
! 8251: <div class="toc">
! 8252: <p><b>Table of Contents</b></p>
! 8253: <dl>
! 8254: <dt><span class="sect1"><a href="#targets">D.1. Targets</a></span></dt>
! 8255: <dt><span class="sect1"><a href="#procedure">D.2. Procedure</a></span></dt>
! 8256: </dl>
! 8257: </div>
! 8258: <p>
! 8259: This section contains information on editing the pkgsrc guide
! 8260: itself.
! 8261: </p>
! 8262: <div class="sect1" lang="en">
! 8263: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 8264: <a name="targets"></a>D.1. Targets</h2></div></div></div>
! 8265: <p>
! 8266: The pkgsrc guide's source code is stored in
! 8267: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/guide/files</code>, and several files are
! 8268: created from it:
! 8269: </p>
! 8270: <div class="itemizedlist"><ul type="disc">
! 8271: <li><p>
! 8272: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/pkgsrc.txt</code>
! 8273: </p></li>
! 8274: <li><p>
! 8275: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/pkgsrc.html</code>
! 8276: </p></li>
! 8277: <li><p>
! 8278: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">http://www.NetBSD.org/Documentation/pkgsrc/</code>:
! 8279: the documentation on the NetBSD website will be built from
! 8280: pkgsrc and kept up to date on the web server itself. This
! 8281: means you <span class="emphasis"><em>must</em></span> make sure that your
! 8282: changes haven't broken the build!
! 8283: </p></li>
! 8284: <li><p>
! 8285: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf</code>:
! 8286: PDF version of the pkgsrc guide.
! 8287: </p></li>
! 8288: <li><p>
! 8289: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps</code>:
! 8290: PostScript version of the pkgsrc guide.
! 8291: </p></li>
! 8292: </ul></div>
! 8293: </div>
! 8294: <div class="sect1" lang="en">
! 8295: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
! 8296: <a name="procedure"></a>D.2. Procedure</h2></div></div></div>
! 8297: <p>
! 8298: The procedure to edit the pkgsrc guide is:
! 8299: </p>
! 8300: <div class="itemizedlist"><ul type="disc">
! 8301: <li><p>
! 8302: Make sure you have the packages needed to re-generate the
! 8303: pkgsrc guide (and other XML-based NetBSD documentation)
! 8304: installed. These are “<span class="quote">netbsd-doc</span>” for creating the
! 8305: ASCII and HTML versions, and
! 8306: “<span class="quote">netbsd-doc-print</span>” for the PostScript and PDF
! 8307: versions. You will need both packages installed, to make sure
! 8308: documentation is consistent across all formats. The packages
! 8309: can be found in
! 8310: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/meta-pkgs/netbsd-doc</code> and
! 8311: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/meta-pkgs/netbsd-doc-print</code>.
! 8312: </p></li>
! 8313: <li><p>
! 8314: Edit the XML file(s) in
! 8315: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/guide/files</code>.
! 8316: </p></li>
! 8317: <li><p>
! 8318: Run <span><strong class="command">make extract && make do-lint</strong></span> in
! 8319: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/guide</code> to check the XML
! 8320: syntax, and fix it if needed.
! 8321: </p></li>
! 8322: <li><p>
! 8323: Run <span><strong class="command">make</strong></span> in
! 8324: <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc/guide</code> to build the HTML and
! 8325: ASCII version.
! 8326: </p></li>
! 8327: <li><p>
! 8328: If all is well, run <span><strong class="command">make install-doc</strong></span> to put
! 8329: the generated files into <code xmlns="http://www.w3.org/TR/xhtml1/transitional" class="filename">pkgsrc/doc</code>.
! 8330: </p></li>
! 8331: <li><p>
! 8332: <span><strong class="command">cvs commit pkgsrc/doc/guide/files</strong></span>
! 8333: </p></li>
! 8334: <li><p>
! 8335: <span><strong class="command">cvs commit -m re-generate pkgsrc/doc/pkgsrc.{html,txt}</strong></span>
! 8336: </p></li>
! 8337: <li><p>
! 8338: Until the webserver on www.NetBSD.org is really updated
! 8339: automatically to pick up changes to the pkgsrc guide
! 8340: automatically, also run <span><strong class="command">make install-htdocs
! 8341: HTDOCSDIR=../../../htdocs</strong></span> (or similar, adjust
! 8342: <code class="varname">HTDOCSDIR</code>!).
! 8343: </p></li>
! 8344: <li><p>
! 8345: <span><strong class="command">cvs commit htdocs/Documentation/pkgsrc</strong></span>
! 8346: </p></li>
! 8347: </ul></div>
! 8348: </div>
! 8349: </div>
! 8350: </div></body>
1.1 grant 8351: </html>
CVSweb <webmaster@jp.NetBSD.org>