pkgsrc-Changes archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
CVS commit: pkgsrc/doc
Module Name: pkgsrc
Committed By: rillig
Date: Sat Jun 20 05:32:11 UTC 2020
Modified Files:
pkgsrc/doc: pkgsrc.html pkgsrc.txt
Log Message:
doc/pkgsrc.*: regen
To generate a diff of this commit:
cvs rdiff -u -r1.298 -r1.299 pkgsrc/doc/pkgsrc.html
cvs rdiff -u -r1.296 -r1.297 pkgsrc/doc/pkgsrc.txt
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: pkgsrc/doc/pkgsrc.html
diff -u pkgsrc/doc/pkgsrc.html:1.298 pkgsrc/doc/pkgsrc.html:1.299
--- pkgsrc/doc/pkgsrc.html:1.298 Thu Jun 18 20:31:14 2020
+++ pkgsrc/doc/pkgsrc.html Sat Jun 20 05:32:11 2020
@@ -31,7 +31,7 @@
</h3>
</div></div>
<div><p class="copyright">Copyright � 1994-2020 The NetBSD Foundation, Inc</p></div>
-<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.36 2020/01/03 15:55:24 leot Exp $</p></div>
+<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $</p></div>
<div><div class="abstract">
<p class="title"><b>Abstract</b></p>
<p>pkgsrc is a centralized package management system for
@@ -170,141 +170,141 @@ builds)</a></span></dt>
<dt><span class="part"><a href="#developers-guide">II. The pkgsrc developer's guide</a></span></dt>
<dd><dl>
<dt><span class="chapter"><a href="#help-devel">11. Getting help</a></span></dt>
-<dt><span class="chapter"><a href="#creating">12. Creating a new pkgsrc package from scratch</a></span></dt>
+<dt><span class="chapter"><a href="#components">12. Package components - files, directories and contents</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#creating.common">12.1. Common types of packages</a></span></dt>
+<dt><span class="sect1"><a href="#components.Makefile">12.1. <code class="filename">Makefile</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.distinfo">12.2. <code class="filename">distinfo</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.patches">12.3. <code class="filename">patches/*</code></a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#creating.perl-module">12.1.1. Perl modules</a></span></dt>
-<dt><span class="sect2"><a href="#creating.python-module">12.1.2. Python modules and programs</a></span></dt>
-<dt><span class="sect2"><a href="#creating.R-package">12.1.3. R packages</a></span></dt>
-<dt><span class="sect2"><a href="#creating.TeX-package">12.1.4. TeXlive packages</a></span></dt>
+<dt><span class="sect2"><a href="#components.patch.structure">12.3.1. Structure of a single patch file</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.caveats">12.3.2. Creating patch files</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.sources">12.3.3. Sources where the patch files come from</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.guidelines">12.3.4. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">12.3.5. Feedback to the author</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#creating.examples">12.2. Examples</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#creating.nvu">12.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#other-mandatory-files">12.4. Other mandatory files</a></span></dt>
+<dt><span class="sect1"><a href="#components.optional">12.5. Optional files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.optional.bin">12.5.1. Files affecting the binary package</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.build">12.5.2. Files affecting the build process</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.none">12.5.3. Files affecting nothing at all</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#work-dir">12.6. <code class="filename">work*</code></a></span></dt>
+<dt><span class="sect1"><a href="#files-dir">12.7. <code class="filename">files/*</code></a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#components">13. Package components - files, directories and contents</a></span></dt>
+<dt><span class="chapter"><a href="#build">13. The build process</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#components.Makefile">13.1. <code class="filename">Makefile</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.distinfo">13.2. <code class="filename">distinfo</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.patches">13.3. <code class="filename">patches/*</code></a></span></dt>
+<dt><span class="sect1"><a href="#build.intro">13.1. Introduction</a></span></dt>
+<dt><span class="sect1"><a href="#build.prefix">13.2. Program location</a></span></dt>
+<dt><span class="sect1"><a href="#build.builddirs">13.3. Directories used during the build process</a></span></dt>
+<dt><span class="sect1"><a href="#build.running">13.4. Running a phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.fetch">13.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#components.patch.structure">13.3.1. Structure of a single patch file</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.caveats">13.3.2. Creating patch files</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.sources">13.3.3. Sources where the patch files come from</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.guidelines">13.3.4. Patching guidelines</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.feedback">13.3.5. Feedback to the author</a></span></dt>
+<dt><span class="sect2"><a href="#build.fetch.what">13.5.1. What to fetch and where to get it from</a></span></dt>
+<dt><span class="sect2"><a href="#build.fetch.how">13.5.2. How are the files fetched?</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#other-mandatory-files">13.4. Other mandatory files</a></span></dt>
-<dt><span class="sect1"><a href="#components.optional">13.5. Optional files</a></span></dt>
+<dt><span class="sect1"><a href="#build.checksum">13.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.extract">13.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.patch">13.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.tools">13.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.wrapper">13.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.configure">13.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.build">13.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.test">13.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.install">13.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.package">13.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.clean">13.16. Cleaning up</a></span></dt>
+<dt><span class="sect1"><a href="#build.helpful-targets">13.17. Other helpful targets</a></span></dt>
+</dl></dd>
+<dt><span class="chapter"><a href="#creating">14. Creating a new pkgsrc package from scratch</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#creating.common">14.1. Common types of packages</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#components.optional.bin">13.5.1. Files affecting the binary package</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.build">13.5.2. Files affecting the build process</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.none">13.5.3. Files affecting nothing at all</a></span></dt>
+<dt><span class="sect2"><a href="#creating.perl-module">14.1.1. Perl modules</a></span></dt>
+<dt><span class="sect2"><a href="#creating.python-module">14.1.2. Python modules and programs</a></span></dt>
+<dt><span class="sect2"><a href="#creating.R-package">14.1.3. R packages</a></span></dt>
+<dt><span class="sect2"><a href="#creating.TeX-package">14.1.4. TeXlive packages</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#work-dir">13.6. <code class="filename">work*</code></a></span></dt>
-<dt><span class="sect1"><a href="#files-dir">13.7. <code class="filename">files/*</code></a></span></dt>
+<dt><span class="sect1"><a href="#creating.examples">14.2. Examples</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#creating.nvu">14.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#makefile">14. Programming in <code class="filename">Makefile</code>s</a></span></dt>
+<dt><span class="chapter"><a href="#makefile">15. Programming in <code class="filename">Makefile</code>s</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#makefile.style">14.1. Caveats</a></span></dt>
-<dt><span class="sect1"><a href="#makefile.variables">14.2. <code class="filename">Makefile</code> variables</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">14.2.1. Naming conventions</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#makefile.code">14.3. Code snippets</a></span></dt>
+<dt><span class="sect1"><a href="#makefile.style">15.1. Caveats</a></span></dt>
+<dt><span class="sect1"><a href="#makefile.variables">15.2. <code class="filename">Makefile</code> variables</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">15.2.1. Naming conventions</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#makefile.code">15.3. Code snippets</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#adding-to-list">14.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#echo-literal">14.3.2. Echoing a string exactly as-is</a></span></dt>
-<dt><span class="sect2"><a href="#cflags-gnu-configure">14.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
-<dt><span class="sect2"><a href="#empty-variables">14.3.4. Handling possibly empty variables</a></span></dt>
+<dt><span class="sect2"><a href="#adding-to-list">15.3.1. Adding things to a list</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">15.3.2. Echoing a string exactly as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">15.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">15.3.4. Handling possibly empty variables</a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#plist">15. PLIST issues</a></span></dt>
+<dt><span class="chapter"><a href="#options">16. Options handling</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#rcs-id">15.1. RCS ID</a></span></dt>
-<dt><span class="sect1"><a href="#automatic-plist-generation">15.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
-<dt><span class="sect1"><a href="#print-PLIST">15.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
-<dt><span class="sect1"><a href="#plist.misc">15.4. Variable substitution in PLIST</a></span></dt>
-<dt><span class="sect1"><a href="#manpage-compression">15.5. Man page compression</a></span></dt>
-<dt><span class="sect1"><a href="#using-PLIST_SRC">15.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
-<dt><span class="sect1"><a href="#platform-specific-plist">15.7. Platform-specific and differing PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#build-plist">15.8. Build-specific PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#faq.common-dirs">15.9. Sharing directories between packages</a></span></dt>
+<dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt>
+<dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
+<dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt>
+<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#buildlink">16. Buildlink methodology</a></span></dt>
+<dt><span class="chapter"><a href="#tools">17. Tools needed for building or running</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#converting-to-buildlink3">16.1. Converting packages to use buildlink3</a></span></dt>
-<dt><span class="sect1"><a href="#creating-buildlink3.mk">16.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
+<dt><span class="sect1"><a href="#pkgsrc-tools">17.1. Tools for pkgsrc builds</a></span></dt>
+<dt><span class="sect1"><a href="#package-tools">17.2. Tools needed by packages</a></span></dt>
+<dt><span class="sect1"><a href="#platform-tools">17.3. Tools provided by platforms</a></span></dt>
+</dl></dd>
+<dt><span class="chapter"><a href="#buildlink">18. Buildlink methodology</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#converting-to-buildlink3">18.1. Converting packages to use buildlink3</a></span></dt>
+<dt><span class="sect1"><a href="#creating-buildlink3.mk">18.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-bl3">16.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
-<dt><span class="sect2"><a href="#updating-buildlink-depends">16.2.2. Updating
+<dt><span class="sect2"><a href="#anatomy-of-bl3">18.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
+<dt><span class="sect2"><a href="#updating-buildlink-depends">18.2.2. Updating
<code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
and
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
in <code class="filename">buildlink3.mk</code> files</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#writing-builtin.mk">16.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
+<dt><span class="sect1"><a href="#writing-builtin.mk">18.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">18.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
+<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">18.3.2. Global preferences for native or pkgsrc software</a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="chapter"><a href="#plist">19. PLIST issues</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">16.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
-<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">16.3.2. Global preferences for native or pkgsrc software</a></span></dt>
+<dt><span class="sect1"><a href="#rcs-id">19.1. RCS ID</a></span></dt>
+<dt><span class="sect1"><a href="#automatic-plist-generation">19.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
+<dt><span class="sect1"><a href="#print-PLIST">19.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
+<dt><span class="sect1"><a href="#plist.misc">19.4. Variable substitution in PLIST</a></span></dt>
+<dt><span class="sect1"><a href="#manpage-compression">19.5. Man page compression</a></span></dt>
+<dt><span class="sect1"><a href="#using-PLIST_SRC">19.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
+<dt><span class="sect1"><a href="#platform-specific-plist">19.7. Platform-specific and differing PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#build-plist">19.8. Build-specific PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#faq.common-dirs">19.9. Sharing directories between packages</a></span></dt>
</dl></dd>
+<dt><span class="chapter"><a href="#pkginstall">20. The pkginstall framework</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">20.1. Files and directories outside the installation prefix</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#dirs-outside-prefix">20.1.1. Directory manipulation</a></span></dt>
+<dt><span class="sect2"><a href="#files-outside-prefix">20.1.2. File manipulation</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#pkginstall">17. The pkginstall framework</a></span></dt>
+<dt><span class="sect1"><a href="#conf-files">20.2. Configuration files</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">17.1. Files and directories outside the installation prefix</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#dirs-outside-prefix">17.1.1. Directory manipulation</a></span></dt>
-<dt><span class="sect2"><a href="#files-outside-prefix">17.1.2. File manipulation</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#conf-files">17.2. Configuration files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#conf-files-sysconfdir">17.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-configure">17.2.2. Telling the software where configuration files are</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-patching">17.2.3. Patching installations</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-disable">17.2.4. Disabling handling of configuration files</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#rcd-scripts">17.3. System startup scripts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">17.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#users-and-groups">17.4. System users and groups</a></span></dt>
-<dt><span class="sect1"><a href="#shells">17.5. System shells</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#shells-disable">17.5.1. Disabling shell registration</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#fonts">17.6. Fonts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#fonts-disable">17.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
-</dl></dd>
-<dt><span class="chapter"><a href="#options">18. Options handling</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#global-default-options">18.1. Global default options</a></span></dt>
-<dt><span class="sect1"><a href="#converting-to-options">18.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
-<dt><span class="sect1"><a href="#option-names">18.3. Option Names</a></span></dt>
-<dt><span class="sect1"><a href="#option-build">18.4. Determining the options of dependencies</a></span></dt>
-</dl></dd>
-<dt><span class="chapter"><a href="#build">19. The build process</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#build.intro">19.1. Introduction</a></span></dt>
-<dt><span class="sect1"><a href="#build.prefix">19.2. Program location</a></span></dt>
-<dt><span class="sect1"><a href="#build.builddirs">19.3. Directories used during the build process</a></span></dt>
-<dt><span class="sect1"><a href="#build.running">19.4. Running a phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.fetch">19.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#build.fetch.what">19.5.1. What to fetch and where to get it from</a></span></dt>
-<dt><span class="sect2"><a href="#build.fetch.how">19.5.2. How are the files fetched?</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#build.checksum">19.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.extract">19.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.patch">19.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.tools">19.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.wrapper">19.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.configure">19.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.build">19.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.test">19.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.install">19.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.package">19.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.clean">19.16. Cleaning up</a></span></dt>
-<dt><span class="sect1"><a href="#build.helpful-targets">19.17. Other helpful targets</a></span></dt>
-</dl></dd>
-<dt><span class="chapter"><a href="#tools">20. Tools needed for building or running</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#pkgsrc-tools">20.1. Tools for pkgsrc builds</a></span></dt>
-<dt><span class="sect1"><a href="#package-tools">20.2. Tools needed by packages</a></span></dt>
-<dt><span class="sect1"><a href="#platform-tools">20.3. Tools provided by platforms</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-sysconfdir">20.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-configure">20.2.2. Telling the software where configuration files are</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-patching">20.2.3. Patching installations</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-disable">20.2.4. Disabling handling of configuration files</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#rcd-scripts">20.3. System startup scripts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">20.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#users-and-groups">20.4. System users and groups</a></span></dt>
+<dt><span class="sect1"><a href="#shells">20.5. System shells</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#shells-disable">20.5.1. Disabling shell registration</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#fonts">20.6. Fonts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#fonts-disable">20.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#fixes">21. Making your package work</a></span></dt>
<dd><dl>
@@ -376,7 +376,13 @@ builds)</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#punting">21.7. Marking packages as having problems</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#debug">22. Debugging</a></span></dt>
+<dt><span class="chapter"><a href="#gnome">22. GNOME packaging and porting</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#meta-packages">22.1. Meta packages</a></span></dt>
+<dt><span class="sect1"><a href="#new-package">22.2. Packaging a GNOME application</a></span></dt>
+<dt><span class="sect1"><a href="#full-update">22.3. Updating GNOME to a newer version</a></span></dt>
+<dt><span class="sect1"><a href="#patching">22.4. Patching guidelines</a></span></dt>
+</dl></dd>
<dt><span class="chapter"><a href="#submit">23. Submitting and Committing</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#submitting-binary-packages">23.1. Submitting binary packages</a></span></dt>
@@ -389,48 +395,41 @@ builds)</a></span></dt>
<dt><span class="sect1"><a href="#moving-package">23.8. Moving a package in pkgsrc</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#devfaq">24. Frequently Asked Questions</a></span></dt>
-<dt><span class="chapter"><a href="#gnome">25. GNOME packaging and porting</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#meta-packages">25.1. Meta packages</a></span></dt>
-<dt><span class="sect1"><a href="#new-package">25.2. Packaging a GNOME application</a></span></dt>
-<dt><span class="sect1"><a href="#full-update">25.3. Updating GNOME to a newer version</a></span></dt>
-<dt><span class="sect1"><a href="#patching">25.4. Patching guidelines</a></span></dt>
-</dl></dd>
</dl></dd>
<dt><span class="part"><a href="#infrastructure">III. The pkgsrc infrastructure internals</a></span></dt>
<dd><dl>
-<dt><span class="chapter"><a href="#infr.design">26. Design of the pkgsrc infrastructure</a></span></dt>
+<dt><span class="chapter"><a href="#infr.design">25. Design of the pkgsrc infrastructure</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#infr.vardef">26.1. The meaning of variable definitions</a></span></dt>
-<dt><span class="sect1"><a href="#infr.vardef.problems">26.2. Avoiding problems before they arise</a></span></dt>
-<dt><span class="sect1"><a href="#infr.var">26.3. Variable evaluation</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef">25.1. The meaning of variable definitions</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef.problems">25.2. Avoiding problems before they arise</a></span></dt>
+<dt><span class="sect1"><a href="#infr.var">25.3. Variable evaluation</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.var.load">26.3.1. At load time</a></span></dt>
-<dt><span class="sect2"><a href="#infr.var.run">26.3.2. At runtime</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.load">25.3.1. At load time</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.run">25.3.2. At runtime</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.varspec">26.4. How can variables be specified?</a></span></dt>
-<dt><span class="sect1"><a href="#infr.design.intf">26.5. Designing interfaces for Makefile fragments</a></span></dt>
+<dt><span class="sect1"><a href="#infr.varspec">25.4. How can variables be specified?</a></span></dt>
+<dt><span class="sect1"><a href="#infr.design.intf">25.5. Designing interfaces for Makefile fragments</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.design.intf.proc">26.5.1. Procedures with parameters</a></span></dt>
-<dt><span class="sect2"><a href="#infr.design.intf.action">26.5.2. Actions taken on behalf of parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.proc">25.5.1. Procedures with parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.action">25.5.2. Actions taken on behalf of parameters</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.order">26.6. The order in which files are loaded</a></span></dt>
+<dt><span class="sect1"><a href="#infr.order">25.6. The order in which files are loaded</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.order.prefs">26.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
-<dt><span class="sect2"><a href="#infr.order.pkg">26.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.prefs">25.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.pkg">25.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#regression">27. Regression tests</a></span></dt>
+<dt><span class="chapter"><a href="#regression">26. Regression tests</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#regression.run">27.1. Running the regression tests</a></span></dt>
-<dt><span class="sect1"><a href="#regression.new">27.2. Adding a new regression test</a></span></dt>
+<dt><span class="sect1"><a href="#regression.run">26.1. Running the regression tests</a></span></dt>
+<dt><span class="sect1"><a href="#regression.new">26.2. Adding a new regression test</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#regression.fun.override">27.2.1. Overridable functions</a></span></dt>
-<dt><span class="sect2"><a href="#regression.fun.helper">27.2.2. Helper functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.override">26.2.1. Overridable functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.helper">26.2.2. Helper functions</a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#porting">28. Porting pkgsrc</a></span></dt>
-<dd><dl><dt><span class="sect1"><a href="#porting.opsys">28.1. Porting pkgsrc to a new operating system</a></span></dt></dl></dd>
+<dt><span class="chapter"><a href="#porting">27. Porting pkgsrc</a></span></dt>
+<dd><dl><dt><span class="sect1"><a href="#porting.opsys">27.1. Porting pkgsrc to a new operating system</a></span></dt></dl></dd>
</dl></dd>
<dt><span class="appendix"><a href="#examples">A. A simple example package: bison</a></span></dt>
<dd><dl>
@@ -472,9 +471,9 @@ source packages</a></span></dt>
<dl>
<dt>1.1. <a href="#supported-platforms">Platforms supported by pkgsrc</a>
</dt>
-<dt>13.1. <a href="#patch-examples">Patching examples</a>
+<dt>12.1. <a href="#patch-examples">Patching examples</a>
</dt>
-<dt>25.1. <a href="#plist-handling">PLIST handling for GNOME packages</a>
+<dt>22.1. <a href="#plist-handling">PLIST handling for GNOME packages</a>
</dt>
</dl>
</div>
@@ -1753,7 +1752,7 @@ spelling mistakes) takes place.</p>
pkgsrc tree instances.)</p></li>
<li class="listitem"><p><code class="varname">LOCALPATCHES</code>:
Directory for local patches that aren't part of pkgsrc.
- See <a class="xref" href="#components.patches" title="13.3.�patches/*">Section�13.3, “<code class="filename">patches/*</code>”</a> for more
+ See <a class="xref" href="#components.patches" title="12.3.�patches/*">Section�12.3, “<code class="filename">patches/*</code>”</a> for more
information.</p></li>
<li class="listitem"><p><code class="varname">PKGMAKECONF</code>: Location of
the <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> file used by a package's
@@ -2077,7 +2076,7 @@ PKG_OPTIONS.apache= suexec </pre>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="settings-for-creationg-of-binary-packages"></a>7.2.�Settings for creation of binary packages</h2></div></div></div>
-<p>See <a class="xref" href="#build.helpful-targets" title="19.17.�Other helpful targets">Section�19.17, “Other helpful targets”</a>.</p>
+<p>See <a class="xref" href="#build.helpful-targets" title="13.17.�Other helpful targets">Section�13.17, “Other helpful targets”</a>.</p>
</div>
</div>
<div class="chapter">
@@ -3059,7 +3058,7 @@ most cases, the flags from the original
with <code class="literal">[*]</code>) are passed unmodified to the actual compiler
(the lines starting with <code class="literal"><.></code>). If the flag is
missing from the actual compiler command, it must have been removed by
-the <a class="link" href="#build.wrapper" title="19.10.�The wrapper phase">pkgsrc compiler wrappers</a>.</p>
+the <a class="link" href="#build.wrapper" title="13.10.�The wrapper phase">pkgsrc compiler wrappers</a>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -3112,141 +3111,141 @@ anymore, you can remove that file and ru
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="chapter"><a href="#help-devel">11. Getting help</a></span></dt>
-<dt><span class="chapter"><a href="#creating">12. Creating a new pkgsrc package from scratch</a></span></dt>
+<dt><span class="chapter"><a href="#components">12. Package components - files, directories and contents</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#creating.common">12.1. Common types of packages</a></span></dt>
+<dt><span class="sect1"><a href="#components.Makefile">12.1. <code class="filename">Makefile</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.distinfo">12.2. <code class="filename">distinfo</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.patches">12.3. <code class="filename">patches/*</code></a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#creating.perl-module">12.1.1. Perl modules</a></span></dt>
-<dt><span class="sect2"><a href="#creating.python-module">12.1.2. Python modules and programs</a></span></dt>
-<dt><span class="sect2"><a href="#creating.R-package">12.1.3. R packages</a></span></dt>
-<dt><span class="sect2"><a href="#creating.TeX-package">12.1.4. TeXlive packages</a></span></dt>
+<dt><span class="sect2"><a href="#components.patch.structure">12.3.1. Structure of a single patch file</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.caveats">12.3.2. Creating patch files</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.sources">12.3.3. Sources where the patch files come from</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.guidelines">12.3.4. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">12.3.5. Feedback to the author</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#creating.examples">12.2. Examples</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#creating.nvu">12.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#other-mandatory-files">12.4. Other mandatory files</a></span></dt>
+<dt><span class="sect1"><a href="#components.optional">12.5. Optional files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.optional.bin">12.5.1. Files affecting the binary package</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.build">12.5.2. Files affecting the build process</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.none">12.5.3. Files affecting nothing at all</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#work-dir">12.6. <code class="filename">work*</code></a></span></dt>
+<dt><span class="sect1"><a href="#files-dir">12.7. <code class="filename">files/*</code></a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#components">13. Package components - files, directories and contents</a></span></dt>
+<dt><span class="chapter"><a href="#build">13. The build process</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#components.Makefile">13.1. <code class="filename">Makefile</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.distinfo">13.2. <code class="filename">distinfo</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.patches">13.3. <code class="filename">patches/*</code></a></span></dt>
+<dt><span class="sect1"><a href="#build.intro">13.1. Introduction</a></span></dt>
+<dt><span class="sect1"><a href="#build.prefix">13.2. Program location</a></span></dt>
+<dt><span class="sect1"><a href="#build.builddirs">13.3. Directories used during the build process</a></span></dt>
+<dt><span class="sect1"><a href="#build.running">13.4. Running a phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.fetch">13.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#components.patch.structure">13.3.1. Structure of a single patch file</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.caveats">13.3.2. Creating patch files</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.sources">13.3.3. Sources where the patch files come from</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.guidelines">13.3.4. Patching guidelines</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.feedback">13.3.5. Feedback to the author</a></span></dt>
+<dt><span class="sect2"><a href="#build.fetch.what">13.5.1. What to fetch and where to get it from</a></span></dt>
+<dt><span class="sect2"><a href="#build.fetch.how">13.5.2. How are the files fetched?</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#other-mandatory-files">13.4. Other mandatory files</a></span></dt>
-<dt><span class="sect1"><a href="#components.optional">13.5. Optional files</a></span></dt>
+<dt><span class="sect1"><a href="#build.checksum">13.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.extract">13.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.patch">13.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.tools">13.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.wrapper">13.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.configure">13.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.build">13.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.test">13.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.install">13.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.package">13.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.clean">13.16. Cleaning up</a></span></dt>
+<dt><span class="sect1"><a href="#build.helpful-targets">13.17. Other helpful targets</a></span></dt>
+</dl></dd>
+<dt><span class="chapter"><a href="#creating">14. Creating a new pkgsrc package from scratch</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#creating.common">14.1. Common types of packages</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#components.optional.bin">13.5.1. Files affecting the binary package</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.build">13.5.2. Files affecting the build process</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.none">13.5.3. Files affecting nothing at all</a></span></dt>
+<dt><span class="sect2"><a href="#creating.perl-module">14.1.1. Perl modules</a></span></dt>
+<dt><span class="sect2"><a href="#creating.python-module">14.1.2. Python modules and programs</a></span></dt>
+<dt><span class="sect2"><a href="#creating.R-package">14.1.3. R packages</a></span></dt>
+<dt><span class="sect2"><a href="#creating.TeX-package">14.1.4. TeXlive packages</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#work-dir">13.6. <code class="filename">work*</code></a></span></dt>
-<dt><span class="sect1"><a href="#files-dir">13.7. <code class="filename">files/*</code></a></span></dt>
+<dt><span class="sect1"><a href="#creating.examples">14.2. Examples</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#creating.nvu">14.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#makefile">14. Programming in <code class="filename">Makefile</code>s</a></span></dt>
+<dt><span class="chapter"><a href="#makefile">15. Programming in <code class="filename">Makefile</code>s</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#makefile.style">14.1. Caveats</a></span></dt>
-<dt><span class="sect1"><a href="#makefile.variables">14.2. <code class="filename">Makefile</code> variables</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">14.2.1. Naming conventions</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#makefile.code">14.3. Code snippets</a></span></dt>
+<dt><span class="sect1"><a href="#makefile.style">15.1. Caveats</a></span></dt>
+<dt><span class="sect1"><a href="#makefile.variables">15.2. <code class="filename">Makefile</code> variables</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">15.2.1. Naming conventions</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#makefile.code">15.3. Code snippets</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#adding-to-list">14.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#echo-literal">14.3.2. Echoing a string exactly as-is</a></span></dt>
-<dt><span class="sect2"><a href="#cflags-gnu-configure">14.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
-<dt><span class="sect2"><a href="#empty-variables">14.3.4. Handling possibly empty variables</a></span></dt>
+<dt><span class="sect2"><a href="#adding-to-list">15.3.1. Adding things to a list</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">15.3.2. Echoing a string exactly as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">15.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">15.3.4. Handling possibly empty variables</a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#plist">15. PLIST issues</a></span></dt>
+<dt><span class="chapter"><a href="#options">16. Options handling</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#rcs-id">15.1. RCS ID</a></span></dt>
-<dt><span class="sect1"><a href="#automatic-plist-generation">15.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
-<dt><span class="sect1"><a href="#print-PLIST">15.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
-<dt><span class="sect1"><a href="#plist.misc">15.4. Variable substitution in PLIST</a></span></dt>
-<dt><span class="sect1"><a href="#manpage-compression">15.5. Man page compression</a></span></dt>
-<dt><span class="sect1"><a href="#using-PLIST_SRC">15.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
-<dt><span class="sect1"><a href="#platform-specific-plist">15.7. Platform-specific and differing PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#build-plist">15.8. Build-specific PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#faq.common-dirs">15.9. Sharing directories between packages</a></span></dt>
+<dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt>
+<dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
+<dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt>
+<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#buildlink">16. Buildlink methodology</a></span></dt>
+<dt><span class="chapter"><a href="#tools">17. Tools needed for building or running</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#converting-to-buildlink3">16.1. Converting packages to use buildlink3</a></span></dt>
-<dt><span class="sect1"><a href="#creating-buildlink3.mk">16.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
+<dt><span class="sect1"><a href="#pkgsrc-tools">17.1. Tools for pkgsrc builds</a></span></dt>
+<dt><span class="sect1"><a href="#package-tools">17.2. Tools needed by packages</a></span></dt>
+<dt><span class="sect1"><a href="#platform-tools">17.3. Tools provided by platforms</a></span></dt>
+</dl></dd>
+<dt><span class="chapter"><a href="#buildlink">18. Buildlink methodology</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#converting-to-buildlink3">18.1. Converting packages to use buildlink3</a></span></dt>
+<dt><span class="sect1"><a href="#creating-buildlink3.mk">18.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-bl3">16.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
-<dt><span class="sect2"><a href="#updating-buildlink-depends">16.2.2. Updating
+<dt><span class="sect2"><a href="#anatomy-of-bl3">18.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
+<dt><span class="sect2"><a href="#updating-buildlink-depends">18.2.2. Updating
<code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
and
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
in <code class="filename">buildlink3.mk</code> files</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#writing-builtin.mk">16.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
+<dt><span class="sect1"><a href="#writing-builtin.mk">18.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">18.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
+<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">18.3.2. Global preferences for native or pkgsrc software</a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="chapter"><a href="#plist">19. PLIST issues</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">16.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
-<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">16.3.2. Global preferences for native or pkgsrc software</a></span></dt>
+<dt><span class="sect1"><a href="#rcs-id">19.1. RCS ID</a></span></dt>
+<dt><span class="sect1"><a href="#automatic-plist-generation">19.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
+<dt><span class="sect1"><a href="#print-PLIST">19.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
+<dt><span class="sect1"><a href="#plist.misc">19.4. Variable substitution in PLIST</a></span></dt>
+<dt><span class="sect1"><a href="#manpage-compression">19.5. Man page compression</a></span></dt>
+<dt><span class="sect1"><a href="#using-PLIST_SRC">19.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
+<dt><span class="sect1"><a href="#platform-specific-plist">19.7. Platform-specific and differing PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#build-plist">19.8. Build-specific PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#faq.common-dirs">19.9. Sharing directories between packages</a></span></dt>
</dl></dd>
+<dt><span class="chapter"><a href="#pkginstall">20. The pkginstall framework</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">20.1. Files and directories outside the installation prefix</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#dirs-outside-prefix">20.1.1. Directory manipulation</a></span></dt>
+<dt><span class="sect2"><a href="#files-outside-prefix">20.1.2. File manipulation</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#pkginstall">17. The pkginstall framework</a></span></dt>
+<dt><span class="sect1"><a href="#conf-files">20.2. Configuration files</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">17.1. Files and directories outside the installation prefix</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#dirs-outside-prefix">17.1.1. Directory manipulation</a></span></dt>
-<dt><span class="sect2"><a href="#files-outside-prefix">17.1.2. File manipulation</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#conf-files">17.2. Configuration files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#conf-files-sysconfdir">17.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-configure">17.2.2. Telling the software where configuration files are</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-patching">17.2.3. Patching installations</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-disable">17.2.4. Disabling handling of configuration files</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#rcd-scripts">17.3. System startup scripts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">17.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#users-and-groups">17.4. System users and groups</a></span></dt>
-<dt><span class="sect1"><a href="#shells">17.5. System shells</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#shells-disable">17.5.1. Disabling shell registration</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#fonts">17.6. Fonts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#fonts-disable">17.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
-</dl></dd>
-<dt><span class="chapter"><a href="#options">18. Options handling</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#global-default-options">18.1. Global default options</a></span></dt>
-<dt><span class="sect1"><a href="#converting-to-options">18.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
-<dt><span class="sect1"><a href="#option-names">18.3. Option Names</a></span></dt>
-<dt><span class="sect1"><a href="#option-build">18.4. Determining the options of dependencies</a></span></dt>
-</dl></dd>
-<dt><span class="chapter"><a href="#build">19. The build process</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#build.intro">19.1. Introduction</a></span></dt>
-<dt><span class="sect1"><a href="#build.prefix">19.2. Program location</a></span></dt>
-<dt><span class="sect1"><a href="#build.builddirs">19.3. Directories used during the build process</a></span></dt>
-<dt><span class="sect1"><a href="#build.running">19.4. Running a phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.fetch">19.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#build.fetch.what">19.5.1. What to fetch and where to get it from</a></span></dt>
-<dt><span class="sect2"><a href="#build.fetch.how">19.5.2. How are the files fetched?</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#build.checksum">19.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.extract">19.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.patch">19.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.tools">19.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.wrapper">19.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.configure">19.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.build">19.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.test">19.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.install">19.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.package">19.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.clean">19.16. Cleaning up</a></span></dt>
-<dt><span class="sect1"><a href="#build.helpful-targets">19.17. Other helpful targets</a></span></dt>
-</dl></dd>
-<dt><span class="chapter"><a href="#tools">20. Tools needed for building or running</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#pkgsrc-tools">20.1. Tools for pkgsrc builds</a></span></dt>
-<dt><span class="sect1"><a href="#package-tools">20.2. Tools needed by packages</a></span></dt>
-<dt><span class="sect1"><a href="#platform-tools">20.3. Tools provided by platforms</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-sysconfdir">20.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-configure">20.2.2. Telling the software where configuration files are</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-patching">20.2.3. Patching installations</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-disable">20.2.4. Disabling handling of configuration files</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#rcd-scripts">20.3. System startup scripts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">20.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#users-and-groups">20.4. System users and groups</a></span></dt>
+<dt><span class="sect1"><a href="#shells">20.5. System shells</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#shells-disable">20.5.1. Disabling shell registration</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#fonts">20.6. Fonts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#fonts-disable">20.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#fixes">21. Making your package work</a></span></dt>
<dd><dl>
@@ -3318,7 +3317,13 @@ anymore, you can remove that file and ru
</dl></dd>
<dt><span class="sect1"><a href="#punting">21.7. Marking packages as having problems</a></span></dt>
</dl></dd>
-<dt><span class="chapter"><a href="#debug">22. Debugging</a></span></dt>
+<dt><span class="chapter"><a href="#gnome">22. GNOME packaging and porting</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#meta-packages">22.1. Meta packages</a></span></dt>
+<dt><span class="sect1"><a href="#new-package">22.2. Packaging a GNOME application</a></span></dt>
+<dt><span class="sect1"><a href="#full-update">22.3. Updating GNOME to a newer version</a></span></dt>
+<dt><span class="sect1"><a href="#patching">22.4. Patching guidelines</a></span></dt>
+</dl></dd>
<dt><span class="chapter"><a href="#submit">23. Submitting and Committing</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#submitting-binary-packages">23.1. Submitting binary packages</a></span></dt>
@@ -3331,13 +3336,6 @@ anymore, you can remove that file and ru
<dt><span class="sect1"><a href="#moving-package">23.8. Moving a package in pkgsrc</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#devfaq">24. Frequently Asked Questions</a></span></dt>
-<dt><span class="chapter"><a href="#gnome">25. GNOME packaging and porting</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#meta-packages">25.1. Meta packages</a></span></dt>
-<dt><span class="sect1"><a href="#new-package">25.2. Packaging a GNOME application</a></span></dt>
-<dt><span class="sect1"><a href="#full-update">25.3. Updating GNOME to a newer version</a></span></dt>
-<dt><span class="sect1"><a href="#patching">25.4. Patching guidelines</a></span></dt>
-</dl></dd>
</dl>
</div>
</div>
@@ -3386,922 +3384,462 @@ anymore, you can remove that file and ru
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="creating"></a>Chapter�12.�Creating a new pkgsrc package from scratch</h2></div></div></div>
+<a name="components"></a>Chapter�12.�Package components - files, directories and contents</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="#creating.common">12.1. Common types of packages</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#creating.perl-module">12.1.1. Perl modules</a></span></dt>
-<dt><span class="sect2"><a href="#creating.python-module">12.1.2. Python modules and programs</a></span></dt>
-<dt><span class="sect2"><a href="#creating.R-package">12.1.3. R packages</a></span></dt>
-<dt><span class="sect2"><a href="#creating.TeX-package">12.1.4. TeXlive packages</a></span></dt>
+<dt><span class="sect1"><a href="#components.Makefile">12.1. <code class="filename">Makefile</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.distinfo">12.2. <code class="filename">distinfo</code></a></span></dt>
+<dt><span class="sect1"><a href="#components.patches">12.3. <code class="filename">patches/*</code></a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.patch.structure">12.3.1. Structure of a single patch file</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.caveats">12.3.2. Creating patch files</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.sources">12.3.3. Sources where the patch files come from</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.guidelines">12.3.4. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">12.3.5. Feedback to the author</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#other-mandatory-files">12.4. Other mandatory files</a></span></dt>
+<dt><span class="sect1"><a href="#components.optional">12.5. Optional files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.optional.bin">12.5.1. Files affecting the binary package</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.build">12.5.2. Files affecting the build process</a></span></dt>
+<dt><span class="sect2"><a href="#components.optional.none">12.5.3. Files affecting nothing at all</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#creating.examples">12.2. Examples</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#creating.nvu">12.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#work-dir">12.6. <code class="filename">work*</code></a></span></dt>
+<dt><span class="sect1"><a href="#files-dir">12.7. <code class="filename">files/*</code></a></span></dt>
</dl>
</div>
-<p>When you find a package that is not yet in pkgsrc, you
-most likely have a URL from where you can download the source
-code. Starting with this URL, creating a package involves only a
-few steps.</p>
-<div class="procedure"><ol class="procedure" type="1">
-<li class="step"><p>First, install the packages <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/url2pkg/README.html"; target="_top"><code
class="filename">pkgtools/url2pkg</code></a> and <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkglint/README.html"; target="_top"><code
class="filename">pkgtools/pkglint</code></a>.</p></li>
-<li class="step"><p>Then, choose one of the top-level directories as the
-category in which you want to place your package. You can also create a
-directory of your own (maybe called <code class="filename">local</code>). In that
-category directory, create another directory for your package and change
-into it.</p></li>
-<li class="step"><p>Run the program <span class="command"><strong>url2pkg</strong></span>, which will ask
-you for a URL. Enter the URL of the distribution file (in most cases a
-<code class="filename">.tar.gz</code> file) and watch how the basic ingredients
-of your package are created automatically. The distribution file is
-extracted automatically to fill in some details in the
-<code class="filename">Makefile</code> that would otherwise have to be done
-manually.</p></li>
-<li class="step">
-<p>Examine the extracted files to determine the dependencies of
-your package. Ideally, this is mentioned in some
-<code class="filename">README</code> file, but things may differ. For each of
-these dependencies, look where it exists in pkgsrc, and if there is a
-file called <code class="filename">buildlink3.mk</code> in that directory, add a
-line to your package <code class="filename">Makefile</code> which includes that
-file just before the last line. If the
-<code class="filename">buildlink3.mk</code> file does not exist, it must be
-created first. The <code class="filename">buildlink3.mk</code> file makes sure
-that the package's include files and libraries are provided.</p>
-<p>If you just need binaries from a package, add a
-<code class="varname">DEPENDS</code> line to the Makefile, which specifies the
-version of the dependency and where it can be found in pkgsrc. This line
-should be placed in the third paragraph. If the dependency is only
-needed for building the package, but not when using it, use
-<code class="varname">TOOL_DEPENDS</code> or <code class="varname">BUILD_DEPENDS</code>
-instead of <code class="varname">DEPENDS</code>.
-The difference between <code class="varname">TOOL_DEPENDS</code> and
-<code class="varname">BUILD_DEPENDS</code> occurs when cross-compiling:
-<code class="varname">TOOL_DEPENDS</code> are <span class="emphasis"><em>native</em></span>
-packages, i.e. packages for the architecture where the package
-is built;
-<code class="varname">BUILD_DEPENDS</code> are <span class="emphasis"><em>target</em></span>
-packages, i.e. packages for the architecture for which the package
-is built. There is also <code class="varname">TEST_DEPENDS</code>, which is used
-to specify a dependency used only for testing the resulting package
-built, using the upstream project's included test suite.
-Your package may then look like this:</p>
+<p>Whenever you're preparing a package, there are a number of
+files involved which are described in the following
+sections.</p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="components.Makefile"></a>12.1.�<code class="filename">Makefile</code>
+</h2></div></div></div>
+<p>Building, installation and creation of a binary package are all
+ controlled by the package's <code class="filename">Makefile</code>.
+ The <code class="filename">Makefile</code> describes various things about
+ a package, for example from where to get it, how to configure,
+ build, and install it.</p>
+<p>A package <code class="filename">Makefile</code> contains several
+ sections that describe the package.</p>
+<p>In the first section there are the following variables, which
+ should appear exactly in the order given here. The order and
+ grouping of the variables is mostly historical and has no further
+ meaning.</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">DISTNAME</code> is the basename of the
+ distribution file to be downloaded from the package's
+ website.</p></li>
+<li class="listitem"><p><code class="varname">PKGNAME</code> is the name of the
+ package, as used by pkgsrc. You need to provide it if
+ <code class="varname">DISTNAME</code> (which is the default) is not a good
+ name for the package in pkgsrc or <code class="varname">DISTNAME</code> is not
+ provided (no distribution file is required). Usually it is the pkgsrc
+ directory name together with the version number. It must match the
+ regular expression
+ <code class="varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>, that is, it
+ starts with a letter or digit, and contains only letters, digits,
+ dashes, underscores, dots and plus signs.</p></li>
+<li class="listitem">
+<p><code class="varname">CATEGORIES</code> is a list of categories
+ which the package fits in. You can choose any of the top-level
+ directories of pkgsrc for it.</p>
+<p>Currently the following values are available for
+ <code class="varname">CATEGORIES</code>. If more than
+ one is used, they need to be separated by spaces:</p>
<pre class="programlisting">
-[...]
-
-TOOL_DEPENDS+= libxslt-[0-9]*:../../textproc/libxslt
-DEPENDS+= screen-[0-9]*:../../misc/screen
-DEPENDS+= screen>=4.0:../../misc/screen
-
-[...]
-
-.include "../../<em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>package</code></em>/buildlink3.mk"
-.include "../../devel/glib2/buildlink3.mk"
-.include "../../mk/bsd.pkg.mk"
+archivers cross geography meta-pkgs security
+audio databases graphics misc shells
+benchmarks devel ham multimedia sysutils
+biology editors inputmethod net textproc
+cad emulators lang news time
+chat finance mail parallel wm
+comms fonts math pkgtools www
+converters games mbone print x11
</pre>
</li>
-<li class="step"><p>Run <span class="command"><strong>pkglint</strong></span> to see what things still need
-to be done to make your package a <span class="quote">“<span class="quote">good</span>”</span> one. If you don't
-know what pkglint's warnings want to tell you, try <span class="command"><strong>pkglint
---explain</strong></span> or <span class="command"><strong>pkglint
--e</strong></span>, which outputs additional
-explanations.</p></li>
-<li class="step"><p>In many cases the package is not yet ready to build. You can
-find instructions for the most common cases in the next section, <a class="xref" href="#creating.common" title="12.1.�Common types of packages">Section�12.1, “Common types of
packages”</a>. After you have followed the instructions
-over there, you can hopefully continue here.</p></li>
-<li class="step"><p>Run <span class="command"><strong>bmake clean</strong></span> to clean the working
-directory from the extracted files. Besides these files, a lot of cache
-files and other system information has been saved in the working
-directory, which may become wrong after you edited the
-<code class="filename">Makefile</code>.</p></li>
-<li class="step"><p>Now, run <span class="command"><strong>bmake</strong></span> to build the package. For
-the various things that can go wrong in this phase, consult <a class="xref" href="#fixes" title="Chapter�21.�Making your package work">Chapter�21, <i>Making your package work</i></a>.</p></li>
-<li class="step"><p>When the package builds fine, the next step is to install
-the package. Run <span class="command"><strong>bmake install</strong></span> and hope that
-everything works.</p></li>
-<li class="step"><p>Up to now, the file <code class="filename">PLIST</code>, which
-contains a list of the files that are installed by the package, is
-nearly empty. Run <span class="command"><strong>bmake print-PLIST
->PLIST</strong></span> to generate a probably correct list. Check
-the file using your preferred text editor to see if the list of
-files looks plausible.</p></li>
-<li class="step"><p>Run <span class="command"><strong>pkglint</strong></span> again to see if the generated
-<code class="filename">PLIST</code> contains garbage or not.</p></li>
-<li class="step"><p>When you ran <span class="command"><strong>bmake install</strong></span>, the package
-has been registered in the database of installed files, but with an
-empty list of files. To fix this, run <span class="command"><strong>bmake deinstall</strong></span>
-and <span class="command"><strong>bmake install</strong></span> again. Now the package is
-registered with the list of files from
-<code class="filename">PLIST</code>.</p></li>
-<li class="step"><p>Run <span class="command"><strong>bmake package</strong></span> to create a binary
-package from the set of installed files.</p></li>
-</ol></div>
+<li class="listitem"><p><code class="varname">MASTER_SITES</code>,
+ <code class="varname">DYNAMIC_MASTER_SITES</code>,
+ <code class="varname">DIST_SUBDIR</code>, <code class="varname">EXTRACT_SUFX</code>
+ and <code class="varname">DISTFILES</code> are discussed in detail in
+ <a class="xref" href="#build.fetch" title="13.5.�The fetch phase">Section�13.5, “The <span class="emphasis"><em>fetch</em></span> phase”</a>.</p></li>
+</ul></div>
+<p>The second section contains information about separately
+ downloaded patches, if any.
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">PATCHFILES</code>:
+ Name(s) of additional files that contain distribution patches.
+ There is no default. pkgsrc will look for them at
+ <code class="varname">PATCH_SITES</code>.
+ They will automatically be uncompressed before patching if
+ the names end with <code class="filename">.gz</code> or
+ <code class="filename">.Z</code>.</p></li>
+<li class="listitem"><p><code class="varname">PATCH_SITES</code>:
+ Primary location(s) for distribution patch files (see
+ <code class="varname">PATCHFILES</code> above) if not found locally.</p></li>
+<li class="listitem"><p><code class="varname">PATCH_DIST_STRIP</code>:
+ an argument to <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> that
sets the pathname strip count to
+ help find the correct files to patch. It defaults to
+ <span class="command"><strong>-p0</strong></span>.</p></li>
+</ul></div>
+<p>The third section contains the following variables.
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">MAINTAINER</code> is the email
+ address of the person who feels responsible for this package,
+ and who is most likely to look at problems or questions regarding
+ this package which have been reported with <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">send-pr</span>(1)</span></a>.
+ Other developers may contact the <code class="varname">MAINTAINER</code>
+ before making changes to the package, but are not required to
+ do so. When packaging a new program, set <code class="varname">MAINTAINER</code>
+ to yourself. If you really can't maintain the package for future
+ updates, set it to
+ <code class="email"><<a class="email" href="mailto:pkgsrc-users%NetBSD.org@localhost";>pkgsrc-users%NetBSD.org@localhost</a>></code>.</p></li>
+<li class="listitem"><p><code class="varname">OWNER</code> should be used instead
+ of <code class="varname">MAINTAINER</code> when you do not want other
+ developers to update or change the package without contacting
+ you first. A package Makefile should contain one of
+ <code class="varname">MAINTAINER</code> or <code class="varname">OWNER</code>, but
+ not both. </p></li>
+<li class="listitem"><p><code class="varname">HOMEPAGE</code> is a URL where users can
+ find more information about the package.</p></li>
+<li class="listitem"><p><code class="varname">COMMENT</code> is a one-line
+ description of the package (should not include the package
+ name).</p></li>
+<li class="listitem"><p><code class="varname">LICENSE</code> indicates the license(s)
+ applicable for the package. See <a class="xref" href="#handling-licenses" title="21.1.3.�Handling licenses">Section�21.1.3, “Handling licenses”</a> for further details.</p></li>
+</ul></div>
+<p>Other variables that affect the build:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+<p><code class="varname">WRKSRC</code>: The directory where the
+ interesting distribution files of the package are found. The
+ default is <code class="filename">${WRKDIR}/${DISTNAME}</code>, which
+ works for most packages.</p>
+<p>If a package doesn't create a subdirectory for itself
+ (most GNU software does, for instance), but extracts itself in
+ the current directory, you should set
+ <code class="varname">WRKSRC=${WRKDIR}</code>.</p>
+<p>If a package doesn't create a subdirectory with the
+ name of <code class="varname">DISTNAME</code> but some different name,
+ set <code class="varname">WRKSRC</code> to point to the proper name in
+ <code class="filename">${WRKDIR}</code>, for example
+ <code class="varname">WRKSRC=${WRKDIR}/${DISTNAME}/unix</code>. See
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/tcl/README.html"; target="_top"><code class="filename">lang/tcl</code></a> and <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/tk/README.html"; target="_top"><code class="filename">x11/tk</code></a> for other examples.</p>
+<p>The name of the working directory created by pkgsrc is
+ taken from the <code class="varname">WRKDIR_BASENAME</code>
+ variable. By default, its value is
+ <code class="filename">work</code>. If you want to use the same
+ pkgsrc tree for building different kinds of binary packages,
+ you can change the variable according to your needs. Two
+ other variables handle common cases of setting
+ <code class="varname">WRKDIR_BASENAME</code> individually. If
+ <code class="varname">OBJHOSTNAME</code> is defined in
+ <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>, the first component of
+ the host's name is attached to the directory name. If
+ <code class="varname">OBJMACHINE</code> is defined, the platform name
+ is attached, which might look like
+ <code class="filename">work.i386</code> or
+ <code class="filename">work.sparc</code>.</p>
+</li></ul></div>
+<p>Please pay attention to the following gotchas:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Add <code class="varname">MANCOMPRESSED</code> if man pages are
+ installed in compressed form by the package. For packages using
+ BSD-style makefiles which honor MANZ, there is
+ <code class="varname">MANCOMPRESSED_IF_MANZ</code>.</p></li>
+<li class="listitem"><p>Replace <code class="filename">/usr/local</code> with
+ <span class="quote">“<span class="quote">${PREFIX}</span>”</span> in all files (see patches,
+ below).</p></li>
+<li class="listitem"><p>If the package installs any info files, see <a class="xref" href="#faq.info-files" title="21.6.7.�Packages installing info files">Section�21.6.7, “Packages installing
info files”</a>.</p></li>
+</ul></div>
+</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="creating.common"></a>12.1.�Common types of packages</h2></div></div></div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="creating.perl-module"></a>12.1.1.�Perl modules</h3></div></div></div>
-<p>Simple Perl modules are handled automatically by
-<span class="command"><strong>url2pkg</strong></span>, including dependencies.</p>
+<a name="components.distinfo"></a>12.2.�<code class="filename">distinfo</code>
+</h2></div></div></div>
+<p>The <code class="filename">distinfo</code> file contains the message
+ digest, or checksum, of each distfile needed for the package. This
+ ensures that the distfiles retrieved from the Internet have not been
+ corrupted during transfer or altered by a malign force to introduce
+ a security hole. To provide maximum security, all distfiles are
+ protected using three different message digest algorithms (SHA1,
+ RMD160, SHA512), as well as the file size.</p>
+<p>The <code class="filename">distinfo</code> file also contains the
+ checksums for all the patches found in the
+ <code class="filename">patches</code> directory (see <a class="xref" href="#components.patches" title="12.3.�patches/*">Section�12.3, “<code class="filename">patches/*</code>”</a>).
These checksums ensure that patches
+ are only applied intentionally and that they don't accidentally change,
+ e.g. when merging different changes together. They also make sure that
+ new patches are actually added to CVS and old ones are removed.
+ Too see whether the patches and the <code class="filename">distinfo</code> file
+ match, run <span class="command"><strong>pkglint</strong></span> after changing the patches.</p>
+<p>To regenerate the <code class="filename">distinfo</code> file, use the
+ <span class="command"><strong>make distinfo</strong></span> command.</p>
+<p>Some packages have different sets of distfiles depending on
+ the platform, for example <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/openjdk8/README.html"; target="_top"><code class="filename">lang/openjdk8</code></a>. These are kept in the
same
+ <code class="filename">distinfo</code> file and care should be taken when
+ upgrading such a package to ensure distfile information is not
+ lost.</p>
</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="components.patches"></a>12.3.�<code class="filename">patches/*</code>
+</h2></div></div></div>
+<p>Some packages don't work out-of-the box on the various
+ platforms that are supported by pkgsrc. These packages need
+ to be patched to make them work. The patch files can be
+ found in the <code class="filename">patches/</code> directory.</p>
+<p>In the <span class="emphasis"><em>patch</em></span> phase, these patches are
+ applied to the files in <code class="varname">WRKSRC</code> directory after
+ extracting them, in alphabetic order.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="creating.python-module"></a>12.1.2.�Python modules and programs</h3></div></div></div>
-<p>Python modules and programs packages are easily created using a
-set of predefined variables.</p>
-<p>
-If some Python versions are not supported by the software, set the
-<code class="varname">PYTHON_VERSIONS_INCOMPATIBLE</code> variable to the Python versions
-that are not supported, e.g.
-</p>
-<pre class="programlisting">
-PYTHON_VERSIONS_INCOMPATIBLE= 27
-</pre>
-<p>
-If the packaged software is a Python module, include one of
-<code class="filename">../../lang/python/egg.mk</code>,
-<code class="filename">../../lang/python/distutils.mk</code>, or
-<code class="filename">../../lang/python/extension.mk</code>.</p>
-<p>Most Python packages use either <span class="quote">“<span class="quote">distutils</span>”</span> or
-easy-setup/setuptools (<span class="quote">“<span class="quote">eggs</span>”</span>).
-If the packaged software is using setuptools, you only need
-to include <span class="quote">“<span class="quote"><code class="filename">../../lang/python/egg.mk</code></span>”</span>.
-Otherwise, if the software uses <span class="quote">“<span class="quote">distutils</span>”</span>, include
-<span class="quote">“<span class="quote"><code class="filename">../../lang/python/distutils.mk</code></span>”</span>,
-so pkgsrc will use this framework.
-<span class="quote">“<span class="quote">distutils</span>”</span> uses a script called <code class="filename">setup.py</code>;
-if the <span class="quote">“<span class="quote">distutils</span>”</span> driver is not called
-<code class="filename">setup.py</code>, set the <code class="varname">PYSETUP</code> variable
-to the name of the script.</p>
-<p>Either way, the package directory should be called
-<span class="quote">“<span class="quote">py-software</span>”</span> and <code class="varname">PKGNAME</code> should be set to
-<span class="quote">“<span class="quote">${PYPKGPREFIX}-${DISTNAME}</span>”</span>, e.g.
-</p>
-<pre class="programlisting">
-DISTNAME= foopymodule-1.2.10
-PKGNAME= ${PYPKGPREFIX}-${DISTNAME}
-</pre>
-<p>If it is an application, include
-<span class="quote">“<span class="quote"><code class="filename">../../lang/python/application.mk</code></span>”</span>.
-In order to correctly set the path to the Python interpreter, use the
-<code class="varname">REPLACE_PYTHON</code> variable and set it to the list of files
-(paths relative to <code class="varname">WRKSRC</code>) that must be corrected.
-For example:
-</p>
-<pre class="programlisting">
-REPLACE_PYTHON= *.py
-</pre>
-<p>Some Python modules have separate distributions for Python-2.x
-and Python-3.x support. In pkgsrc this is handled by the
-<code class="filename">versioned_dependencies.mk</code> file. Set
-<code class="varname">PYTHON_VERSIONED_DEPENDENCIES</code> to the list of
-packages that should be depended upon and include
-<span class="quote">“<span class="quote"><code class="filename">../../lang/python/versioned_dependencies.mk</code></span>”</span>,
-then the pkgsrc infrastructure will depend on the appropriate package
-version. For example:
-</p>
-<pre class="programlisting">
-PYTHON_VERSIONED_DEPENDENCIES=dialog
-</pre>
-<p>
-Look inside <code class="filename">versioned_dependencies.mk</code> for a list
-of supported packages.</p>
+<a name="components.patch.structure"></a>12.3.1.�Structure of a single patch file</h3></div></div></div>
+<p>The <code class="filename">patch-*</code> files should be in
+ <span class="command"><strong>diff -bu</strong></span> format, and apply without a fuzz to avoid
+ problems. (To force patches to apply with fuzz you can set
+ <code class="varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, each patch
+ should contain only changes for a single file, and no file should be
+ patched by more than one patch file. This helps to keep future
+ modifications simple.</p>
+<p>Each patch file is structured as follows: In the first line,
+ there is the RCS Id of the patch itself. The second line should be
+ empty for aesthetic reasons. After that, there should be a comment for
+ each change that the patch does. There are a number of standard
+ cases:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Patches for commonly known vulnerabilities should
+ mention the vulnerability ID (CAN, CVE).</p></li>
+<li class="listitem"><p>Patches that change source code should mention the
+ platform and other environment (for example, the compiler) that the
+ patch is needed for.</p></li>
+</ul></div>
+<p>The patch should be commented so that any
+ developer who knows the code of the application can make some use of
+ the patch. Special care should be taken for the upstream developers,
+ since we generally want that they accept our patches, so we have less
+ work in the future.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="creating.R-package"></a>12.1.3.�R packages</h3></div></div></div>
-<p>Simple R packages from <a class="ulink" href="https://cran.r-project.org/web/packages/available_packages_by_name.html"; target="_top">CRAN</a>
-are handled automatically by <span class="command"><strong>R2pkg</strong></span>, which is
-available in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/R2pkg/README.html"; target="_top"><code class="filename">pkgtools/R2pkg</code></a>.
-Individual packages (and optionally their dependencies) may be created
-and updated. R packages generally follow the same form, and most of
-the relevant information needed is contained in a
-<code class="filename">DESCRIPTION</code> file as part of each R package on
-<a class="ulink" href="https://cran.r-project.org/web/packages/available_packages_by_name.html"; target="_top">CRAN</a>.
-Consequently, <span class="command"><strong>R2pkg</strong></span> downloads that information and
-creates or updates a package in the canonical form. The resulting
-package should be reviewed for correctness.</p>
+<a name="components.patches.caveats"></a>12.3.2.�Creating patch files</h3></div></div></div>
+<p>One important thing to mention is to pay attention that no RCS
+ IDs get stored in the patch files, as these will cause problems when
+ later checked into the NetBSD CVS tree. Use the
+ <span class="command"><strong>pkgdiff</strong></span> command from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code
class="filename">pkgtools/pkgdiff</code></a> package to avoid these
+ problems.</p>
+<p>For even more automation, we recommend using
+ <span class="command"><strong>mkpatches</strong></span> from the same package to make a
+ whole set of patches. You just have to backup files before you
+ edit them to <code class="filename">filename.orig</code>, e.g. with
+ <span class="command"><strong>cp -p filename filename.orig</strong></span> or, easier, by
+ using <span class="command"><strong>pkgvi</strong></span> again from the same package. If
+ you upgrade a package this way, you can easily compare the new
+ set of patches with the previously existing one with
+ <span class="command"><strong>patchdiff</strong></span>. The files in <code class="filename">patches</code>
+ are replaced by new files, so carefully check if you want to take all
+ the changes.</p>
+<p>When you have finished a package, remember to generate
+ the checksums for the patch files by using the <span class="command"><strong>make
+ makepatchsum</strong></span> command, see <a class="xref" href="#components.distinfo" title="12.2.�distinfo">Section�12.2, “<code class="filename">distinfo</code>”</a>.</p>
+<p>When adding a patch that corrects a problem in the
+ distfile (rather than e.g. enforcing pkgsrc's view of where
+ man pages should go), send the patch as a bug report to the
+ maintainer. This benefits non-pkgsrc users of the package,
+ and usually makes it possible to remove the patch in future
+ version.</p>
+<p>The file names of the patch files are usually of the form
+ <code class="filename">patch-<em class="replaceable"><code>path_to_file__with__underscores.c</code></em></code>.
+ Many packages still use the previous convention
+ <code class="filename">patch-<em class="replaceable"><code>[a-z][a-z]</code></em></code>,
+ but new patches should be of the form containing the filename.
+ <span class="command"><strong>mkpatches</strong></span> included in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code
class="filename">pkgtools/pkgdiff</code></a> takes care of the name
+ automatically.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="creating.TeX-package"></a>12.1.4.�TeXlive packages</h3></div></div></div>
-<p>TeXlive packages from <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a> are handled automatically by
-<span class="command"><strong>texlive2pkg</strong></span>, which is available in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/texlive2pkg/README.html"; target="_top"><code
class="filename">pkgtools/texlive2pkg</code></a>.</p>
-<p>If the TeXlive package name is not known, it may be useful to
-search <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a>. A
-<span class="quote">“<span class="quote">Contained in</span>”</span> field on the package page typically
-identifies the basename of the package file in the <a class="ulink" href="https://www.ctan.org/tex-archive/systems/texlive/tlnet/archive"; target="_top">TeXlive
-archive</a>.</p>
-<p>If the TeXlive package name is known, download the files from
-the <a class="ulink" href="https://www.ctan.org/tex-archive/systems/texlive/tlnet/archive"; target="_top">TeXlive
-archive</a>. For package <code class="filename">foo</code>, you will need
-to download <code class="filename">foo.tar.xz</code>. Most TeXlive packages
-also have associated documentation packages, so download
-<code class="filename">foo.doc.tar.xz</code> at the same time. These files
-should be placed in the appropriate category directory, which is often
-but not always <code class="filename">print</code>. Then run the following
-command in the category directory.</p>
-<pre class="programlisting">
-texlive2pkg foo.tar.xz foo.doc.tar.xz
-</pre>
-<p>This will create two packages, <code class="filename">tex-foo</code> and
-<code class="filename">tex-foo-doc</code>. Be sure to check that both packages
-are correct.</p>
-<p>Finally, <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a>
-currently does not include version information in package filenames
-and changes their contents periodically when updates occur.
-Consequently, pkgsrc avoids downloading distfiles directly from <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a> and instead relies on the
-pkgsrc archives. For each new or updated TeXlive package, e.g., the
-main one and the corresponding documentation, upload the distfiles
-with the following command in each package directory.</p>
+<a name="components.patches.sources"></a>12.3.3.�Sources where the patch files come from</h3></div></div></div>
+<p>If you want to share patches between multiple packages
+ in pkgsrc, e.g. because they use the same distfiles, set
+ <code class="varname">PATCHDIR</code> to the path where the patch files
+ can be found, e.g.:</p>
<pre class="programlisting">
-make upload-distfiles
+PATCHDIR= ../../editors/xemacs/patches
</pre>
+<p>Patch files that are distributed by the author or other
+ maintainers can be listed in
+ <code class="varname">PATCHFILES</code>.</p>
+<p>If it is desired to store any patches that should not be
+ committed into pkgsrc, they can be kept outside the pkgsrc
+ tree in the <code class="filename">$LOCALPATCHES</code> directory. The
+ directory tree there is expected to have the same
+ <span class="quote">“<span class="quote">category/package</span>”</span> structure as pkgsrc, and
+ patches are expected to be stored inside these dirs (also
+ known as <code class="filename">$LOCALPATCHES/$PKGPATH</code>). For
+ example, if you want to keep a private patch for
+ <code class="filename">pkgsrc/graphics/png</code>, keep it in
+ <code class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
+ files in the named directory are expected to be patch files,
+ and <span class="emphasis"><em>they are applied after pkgsrc patches are
+ applied</em></span>.</p>
</div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="creating.examples"></a>12.2.�Examples</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="creating.nvu"></a>12.2.1.�How the www/nvu package came into pkgsrc</h3></div></div></div>
-<div class="sect3">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="creating.nvu.init"></a>12.2.1.1.�The initial package</h4></div></div></div>
-<p>Looking at the file <code class="filename">pkgsrc/doc/TODO</code>, I saw
-that the <span class="quote">“<span class="quote">nvu</span>”</span> package has not yet been imported into
-pkgsrc. As the description says it has to do with the web, the obvious
-choice for the category is <span class="quote">“<span class="quote">www</span>”</span>.</p>
-<pre class="programlisting">
-<code class="prompt">$</code> mkdir www/nvu
-<code class="prompt">$</code> cd www/nvu
-</pre>
-<p>The web site says that the sources are available as a tar file, so
-I fed that URL to the <span class="command"><strong>url2pkg</strong></span> program:</p>
-<pre class="programlisting">
-<code class="prompt">$</code> url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
-</pre>
-<p>My editor popped up, and I added a <code class="varname">PKGNAME</code> line
-below the <code class="varname">DISTNAME</code> line, as the package name should
-not have the word <span class="quote">“<span class="quote">sources</span>”</span> in it. I also filled in the
-<code class="varname">MAINTAINER</code>, <code class="varname">HOMEPAGE</code> and
-<code class="varname">COMMENT</code> fields. Then the package
-<code class="filename">Makefile</code> looked like that:</p>
-<pre class="programlisting">
-# $NetBSD $
-#
-
-DISTNAME= nvu-1.0-sources
-PKGNAME= nvu-1.0
-CATEGORIES= www
-MASTER_SITES= http://cvs.nvu.com/download/
-EXTRACT_SUFX= .tar.bz2
-
-MAINTAINER= rillig%NetBSD.org@localhost
-HOMEPAGE= http://cvs.nvu.com/
-COMMENT= Web Authoring System
-
-# url2pkg-marker (please do not remove this line.)
-.include "../../mk/bsd.pkg.mk"
-</pre>
-<p>On the first line of output above, an artificial space has been added between NetBSD and $,
-this is a workaround to prevent CVS expanding to the filename of the
-guide.</p>
-<p>Then, I quit the editor and watched pkgsrc downloading a large
-source archive:</p>
-<pre class="programlisting">
-url2pkg> Running "make makesum" ...
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Fetching nvu-1.0-sources.tar.bz2
-Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
-100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA
-29687976 bytes retrieved in 03:12 (150.77 KB/s)
-url2pkg> Running "make extract" ...
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
-=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
-work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
-===> Installing dependencies for nvu-1.0
-===> Overriding tools for nvu-1.0
-===> Extracting for nvu-1.0
-url2pkg> Adjusting the Makefile.
-
-Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
-
-Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
-</pre>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="creating.nvu.problems"></a>12.2.1.2.�Fixing all kinds of problems to make the package work</h4></div></div></div>
-<p>Now that the package has been extracted, let's see what's inside
-it. The package has a <code class="filename">README.txt</code>, but that only
-says something about mozilla, so it's probably useless for seeing what
-dependencies this package has. But since there is a GNU configure script
-in the package, let's hope that it will complain about everything it
-needs.</p>
-<pre class="programlisting">
-<code class="prompt">$</code> bmake
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
-=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
-===> Patching for nvu-1.0
-===> Creating toolchain wrappers for nvu-1.0
-===> Configuring for nvu-1.0
-[...]
-configure: error: Perl 5.004 or higher is required.
-[...]
-WARNING: Please add USE_TOOLS+=perl to the package Makefile.
-[...]
-</pre>
-<p>That worked quite well. So I opened the package Makefile in my
-editor, and since it already has a <code class="varname">USE_TOOLS</code> line, I
-just appended <span class="quote">“<span class="quote">perl</span>”</span> to it. Since the dependencies of the
-package have changed now, and since a perl wrapper is automatically
-installed in the <span class="quote">“<span class="quote">tools</span>”</span> phase, I need to build the package
-from scratch.</p>
-<pre class="programlisting">
-<code class="prompt">$</code> bmake clean
-===> Cleaning for nvu-1.0
-<code class="prompt">$</code> bmake
-[...]
-*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
-GNU Make. You will not be able to build Mozilla without GNU Make.
-[...]
-</pre>
-<p>So I added <span class="quote">“<span class="quote">gmake</span>”</span> to the
-<code class="varname">USE_TOOLS</code> line and tried again (from scratch).</p>
-<pre class="programlisting">
-[...]
-checking for GTK - version >= 1.2.0... no
-*** Could not run GTK test program, checking why...
-[...]
-</pre>
-<p>Now to the other dependencies. The first question is: Where is the
-GTK package hidden in pkgsrc?</p>
-<pre class="programlisting">
-<code class="prompt">$</code> echo ../../*/gtk*
-[many packages ...]
-<code class="prompt">$</code> echo ../../*/gtk
-../../x11/gtk
-<code class="prompt">$</code> echo ../../*/gtk2
-../../x11/gtk2
-<code class="prompt">$</code> echo ../../*/gtk2/bui*
-../../x11/gtk2/buildlink3.mk
-</pre>
-<p>The first try was definitely too broad. The second one had exactly
-one result, which is very good. But there is one pitfall with GNOME
-packages. Before GNOME 2 had been released, there were already many
-GNOME 1 packages in pkgsrc. To be able to continue to use these
-packages, the GNOME 2 packages were imported as separate packages, and
-their names usually have a <span class="quote">“<span class="quote">2</span>”</span> appended. So I checked
-whether this was the case here, and indeed it was.</p>
-<p>Since the GTK2 package has a <code class="filename">buildlink3.mk</code>
-file, adding the dependency is very easy. I just inserted an
-<code class="literal">.include</code> line before the last line of the package
-<code class="filename">Makefile</code>, so that it now looks like this:</p>
+<a name="components.patches.guidelines"></a>12.3.4.�Patching guidelines</h3></div></div></div>
+<p>When fixing a portability issue in the code do not use
+ preprocessor magic to check for the current operating system nor
+ platform. Doing so hurts portability to other platforms because
+ the OS-specific details are not abstracted appropriately.</p>
+<p>The general rule to follow is: instead of checking for the
+ operating system the application is being built on, check for the
+ specific <span class="emphasis"><em>features</em></span> you need. For example,
+ instead of assuming that kqueue is available under NetBSD and
+ using the <code class="varname">__NetBSD__</code> macro to conditionalize
+ kqueue support, add a check that detects kqueue itself —
+ yes, this generally involves patching the
+ <span class="command"><strong>configure</strong></span> script. There is absolutely nothing
+ that prevents some OSes from adopting interfaces from other OSes
+ (e.g. Linux implementing kqueue), something that the above checks
+ cannot take into account.</p>
+<p>Of course, checking for features generally involves more
+ work on the developer's side, but the resulting changes are
+ cleaner and there are chances they will work on many other
+ platforms. Not to mention that there are higher chances of being
+ later integrated into the mainstream sources. Remember:
+ <span class="emphasis"><em>It doesn't work unless it is right!</em></span></p>
+<p>Some typical examples:</p>
+<div class="table">
+<a name="patch-examples"></a><p class="title"><b>Table�12.1.�Patching examples</b></p>
+<div class="table-contents"><table class="table" summary="Patching examples" border="1">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>Where</th>
+<th>Incorrect</th>
+<th>Correct</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>configure script</td>
+<td>
<pre class="programlisting">
-[...]
-.include "../../x11/gtk2/buildlink3.mk"
-.include "../../mk/bsd.pkg.mk
+case ${target_os} in
+netbsd*) have_kvm=yes ;;
+*) have_kvm=no ;;
+esac
</pre>
-<p>After another <span class="command"><strong>bmake clean && bmake</strong></span>, the answer
-was:</p>
+ </td>
+<td>
<pre class="programlisting">
-[...]
-checking for gtk-config... /home/roland/pkg/bin/gtk-config
-checking for GTK - version >= 1.2.0... no
-*** Could not run GTK test program, checking why...
-*** The test program failed to compile or link. See the file config.log for the
-*** exact error that occured. This usually means GTK was incorrectly installed
-*** or that you have moved GTK since it was installed. In the latter case, you
-*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
-configure: error: Test for GTK failed.
-[...]
+AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)
</pre>
-<p>In this particular case, the assumption that <span class="quote">“<span class="quote">every package
-prefers GNOME 2</span>”</span> had been wrong. The first of the lines above
-told me that this package really wanted to have the GNOME 1 version of
-GTK. If the package had looked for GTK2, it would have looked for
-<span class="command"><strong>pkg-config</strong></span> instead of <span class="command"><strong>gtk-config</strong></span>.
-So I changed the <code class="literal">x11/gtk2</code> to
-<code class="literal">x11/gtk</code> in the package <code class="filename">Makefile</code>,
-and tried again.</p>
+ </td>
+</tr>
+<tr>
+<td>C source file</td>
+<td>
<pre class="programlisting">
-[...]
-cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" [...]
-In file included from xpidl.c:42:
-xpidl.h:53:24: libIDL/IDL.h: No such file or directory
-In file included from xpidl.c:42:
-xpidl.h:132: error: parse error before "IDL_ns"
-[...]
+#if defined(__NetBSD__)
+# include <sys/event.h>
+#endif
</pre>
-<p>The package still does not find all of its dependencies. Now the
-question is: Which package provides the
-<code class="filename">libIDL/IDL.h</code> header file?</p>
+ </td>
+<td>
<pre class="programlisting">
-<code class="prompt">$</code> echo ../../*/*idl*
-../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
-<code class="prompt">$</code> echo ../../*/*IDL*
-../../net/libIDL
+#if defined(HAVE_SYS_EVENT_H)
+# include <sys/event.h>
+#endif
</pre>
-<p>Let's take the one from the second try. So I included the
-<code class="filename">../../net/libIDL/buildlink3.mk</code> file and tried
-again. But the error didn't change. After digging through some of the
-code, I concluded that the build process of the package was broken and
-couldn't have ever worked, but since the Mozilla source tree is quite
-large, I didn't want to fix it. So I added the following to the package
-<code class="filename">Makefile</code> and tried again:</p>
+ </td>
+</tr>
+<tr>
+<td>C source file</td>
+<td>
<pre class="programlisting">
-CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
-BUILDLINK_TRANSFORM+= l:IDL:IDL-2
+int
+monitor_file(...)
+{
+#if defined(__NetBSD__)
+ int fd = kqueue();
+ ...
+#else
+ ...
+#endif
+}
</pre>
-<p>The latter line is needed because the package expects the library
-<code class="filename">libIDL.so</code>, but only
-<code class="filename">libIDL-2.so</code> is available. So I told the compiler
-wrapper to rewrite that on the fly.</p>
-<p>The next problem was related to a recent change of the FreeType
-interface. I looked up in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/seamonkey/README.html"; target="_top"><code class="filename">www/seamonkey</code></a>
-which patch files were relevant for this issue and copied them to the
-<code class="filename">patches</code> directory. Then I retried, fixed the
-patches so that they applied cleanly and retried again. This time,
-everything worked.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="creating.nvu.inst"></a>12.2.1.3.�Installing the package</h4></div></div></div>
+ </td>
+<td>
<pre class="programlisting">
-<code class="prompt">$</code> bmake CHECK_FILES=no install
-[...]
-<code class="prompt">$</code> bmake print-PLIST >PLIST
-<code class="prompt">$</code> bmake deinstall
-<code class="prompt">$</code> bmake install
+int
+monitor_file(...)
+{
+#if defined(HAVE_KQUEUE)
+ int fd = kqueue();
+ ...
+#else
+ ...
+#endif
+}
</pre>
+ </td>
+</tr>
+</tbody>
+</table></div>
</div>
+<br class="table-break">
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="components.patches.feedback"></a>12.3.5.�Feedback to the author</h3></div></div></div>
+<p>Always, always, <span class="strong"><strong>always</strong></span>
+ feed back any <span class="emphasis"><em>portability fixes</em></span> or
+ improvements you do to a package to the mainstream developers.
+ This is the only way to get their attention on portability issues
+ and to ensure that future versions can be built out-of-the box on
+ NetBSD. Furthermore, any user that gets newer distfiles will get
+ the fixes straight from the packaged code.</p>
+<p>This generally involves cleaning up the patches
+ (because sometimes the patches that are
+ added to pkgsrc are quick hacks), filing bug reports in the
+ appropriate trackers for the projects and working with the
+ mainstream authors to accept your changes. It is
+ <span class="emphasis"><em>extremely important</em></span> that you do it so that
+ the packages in pkgsrc are kept simple and thus further changes
+ can be done without much hassle.</p>
+<p>When you have done this, please add a URL to the upstream
+ bug report to the patch comment.</p>
+<p>Support the idea of free software!</p>
</div>
</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="components"></a>Chapter�13.�Package components - files, directories and contents</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#components.Makefile">13.1. <code class="filename">Makefile</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.distinfo">13.2. <code class="filename">distinfo</code></a></span></dt>
-<dt><span class="sect1"><a href="#components.patches">13.3. <code class="filename">patches/*</code></a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#components.patch.structure">13.3.1. Structure of a single patch file</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.caveats">13.3.2. Creating patch files</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.sources">13.3.3. Sources where the patch files come from</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.guidelines">13.3.4. Patching guidelines</a></span></dt>
-<dt><span class="sect2"><a href="#components.patches.feedback">13.3.5. Feedback to the author</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#other-mandatory-files">13.4. Other mandatory files</a></span></dt>
-<dt><span class="sect1"><a href="#components.optional">13.5. Optional files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#components.optional.bin">13.5.1. Files affecting the binary package</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.build">13.5.2. Files affecting the build process</a></span></dt>
-<dt><span class="sect2"><a href="#components.optional.none">13.5.3. Files affecting nothing at all</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#work-dir">13.6. <code class="filename">work*</code></a></span></dt>
-<dt><span class="sect1"><a href="#files-dir">13.7. <code class="filename">files/*</code></a></span></dt>
-</dl>
-</div>
-<p>Whenever you're preparing a package, there are a number of
-files involved which are described in the following
-sections.</p>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="components.Makefile"></a>13.1.�<code class="filename">Makefile</code>
-</h2></div></div></div>
-<p>Building, installation and creation of a binary package are all
- controlled by the package's <code class="filename">Makefile</code>.
- The <code class="filename">Makefile</code> describes various things about
- a package, for example from where to get it, how to configure,
- build, and install it.</p>
-<p>A package <code class="filename">Makefile</code> contains several
- sections that describe the package.</p>
-<p>In the first section there are the following variables, which
- should appear exactly in the order given here. The order and
- grouping of the variables is mostly historical and has no further
- meaning.</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">DISTNAME</code> is the basename of the
- distribution file to be downloaded from the package's
- website.</p></li>
-<li class="listitem"><p><code class="varname">PKGNAME</code> is the name of the
- package, as used by pkgsrc. You need to provide it if
- <code class="varname">DISTNAME</code> (which is the default) is not a good
- name for the package in pkgsrc or <code class="varname">DISTNAME</code> is not
- provided (no distribution file is required). Usually it is the pkgsrc
- directory name together with the version number. It must match the
- regular expression
- <code class="varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>, that is, it
- starts with a letter or digit, and contains only letters, digits,
- dashes, underscores, dots and plus signs.</p></li>
-<li class="listitem">
-<p><code class="varname">CATEGORIES</code> is a list of categories
- which the package fits in. You can choose any of the top-level
- directories of pkgsrc for it.</p>
-<p>Currently the following values are available for
- <code class="varname">CATEGORIES</code>. If more than
- one is used, they need to be separated by spaces:</p>
-<pre class="programlisting">
-archivers cross geography meta-pkgs security
-audio databases graphics misc shells
-benchmarks devel ham multimedia sysutils
-biology editors inputmethod net textproc
-cad emulators lang news time
-chat finance mail parallel wm
-comms fonts math pkgtools www
-converters games mbone print x11
-</pre>
-</li>
-<li class="listitem"><p><code class="varname">MASTER_SITES</code>,
- <code class="varname">DYNAMIC_MASTER_SITES</code>,
- <code class="varname">DIST_SUBDIR</code>, <code class="varname">EXTRACT_SUFX</code>
- and <code class="varname">DISTFILES</code> are discussed in detail in
- <a class="xref" href="#build.fetch" title="19.5.�The fetch phase">Section�19.5, “The <span class="emphasis"><em>fetch</em></span> phase”</a>.</p></li>
-</ul></div>
-<p>The second section contains information about separately
- downloaded patches, if any.
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">PATCHFILES</code>:
- Name(s) of additional files that contain distribution patches.
- There is no default. pkgsrc will look for them at
- <code class="varname">PATCH_SITES</code>.
- They will automatically be uncompressed before patching if
- the names end with <code class="filename">.gz</code> or
- <code class="filename">.Z</code>.</p></li>
-<li class="listitem"><p><code class="varname">PATCH_SITES</code>:
- Primary location(s) for distribution patch files (see
- <code class="varname">PATCHFILES</code> above) if not found locally.</p></li>
-<li class="listitem"><p><code class="varname">PATCH_DIST_STRIP</code>:
- an argument to <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> that
sets the pathname strip count to
- help find the correct files to patch. It defaults to
- <span class="command"><strong>-p0</strong></span>.</p></li>
-</ul></div>
-<p>The third section contains the following variables.
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">MAINTAINER</code> is the email
- address of the person who feels responsible for this package,
- and who is most likely to look at problems or questions regarding
- this package which have been reported with <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">send-pr</span>(1)</span></a>.
- Other developers may contact the <code class="varname">MAINTAINER</code>
- before making changes to the package, but are not required to
- do so. When packaging a new program, set <code class="varname">MAINTAINER</code>
- to yourself. If you really can't maintain the package for future
- updates, set it to
- <code class="email"><<a class="email" href="mailto:pkgsrc-users%NetBSD.org@localhost";>pkgsrc-users%NetBSD.org@localhost</a>></code>.</p></li>
-<li class="listitem"><p><code class="varname">OWNER</code> should be used instead
- of <code class="varname">MAINTAINER</code> when you do not want other
- developers to update or change the package without contacting
- you first. A package Makefile should contain one of
- <code class="varname">MAINTAINER</code> or <code class="varname">OWNER</code>, but
- not both. </p></li>
-<li class="listitem"><p><code class="varname">HOMEPAGE</code> is a URL where users can
- find more information about the package.</p></li>
-<li class="listitem"><p><code class="varname">COMMENT</code> is a one-line
- description of the package (should not include the package
- name).</p></li>
-<li class="listitem"><p><code class="varname">LICENSE</code> indicates the license(s)
- applicable for the package. See <a class="xref" href="#handling-licenses" title="21.1.3.�Handling licenses">Section�21.1.3, “Handling licenses”</a> for further details.</p></li>
-</ul></div>
-<p>Other variables that affect the build:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
-<p><code class="varname">WRKSRC</code>: The directory where the
- interesting distribution files of the package are found. The
- default is <code class="filename">${WRKDIR}/${DISTNAME}</code>, which
- works for most packages.</p>
-<p>If a package doesn't create a subdirectory for itself
- (most GNU software does, for instance), but extracts itself in
- the current directory, you should set
- <code class="varname">WRKSRC=${WRKDIR}</code>.</p>
-<p>If a package doesn't create a subdirectory with the
- name of <code class="varname">DISTNAME</code> but some different name,
- set <code class="varname">WRKSRC</code> to point to the proper name in
- <code class="filename">${WRKDIR}</code>, for example
- <code class="varname">WRKSRC=${WRKDIR}/${DISTNAME}/unix</code>. See
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/tcl/README.html"; target="_top"><code class="filename">lang/tcl</code></a> and <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/tk/README.html"; target="_top"><code class="filename">x11/tk</code></a> for other examples.</p>
-<p>The name of the working directory created by pkgsrc is
- taken from the <code class="varname">WRKDIR_BASENAME</code>
- variable. By default, its value is
- <code class="filename">work</code>. If you want to use the same
- pkgsrc tree for building different kinds of binary packages,
- you can change the variable according to your needs. Two
- other variables handle common cases of setting
- <code class="varname">WRKDIR_BASENAME</code> individually. If
- <code class="varname">OBJHOSTNAME</code> is defined in
- <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>, the first component of
- the host's name is attached to the directory name. If
- <code class="varname">OBJMACHINE</code> is defined, the platform name
- is attached, which might look like
- <code class="filename">work.i386</code> or
- <code class="filename">work.sparc</code>.</p>
-</li></ul></div>
-<p>Please pay attention to the following gotchas:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Add <code class="varname">MANCOMPRESSED</code> if man pages are
- installed in compressed form by the package. For packages using
- BSD-style makefiles which honor MANZ, there is
- <code class="varname">MANCOMPRESSED_IF_MANZ</code>.</p></li>
-<li class="listitem"><p>Replace <code class="filename">/usr/local</code> with
- <span class="quote">“<span class="quote">${PREFIX}</span>”</span> in all files (see patches,
- below).</p></li>
-<li class="listitem"><p>If the package installs any info files, see <a class="xref" href="#faq.info-files" title="21.6.7.�Packages installing info files">Section�21.6.7, “Packages installing
info files”</a>.</p></li>
-</ul></div>
-</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="components.distinfo"></a>13.2.�<code class="filename">distinfo</code>
-</h2></div></div></div>
-<p>The <code class="filename">distinfo</code> file contains the message
- digest, or checksum, of each distfile needed for the package. This
- ensures that the distfiles retrieved from the Internet have not been
- corrupted during transfer or altered by a malign force to introduce
- a security hole. To provide maximum security, all distfiles are
- protected using three different message digest algorithms (SHA1,
- RMD160, SHA512), as well as the file size.</p>
-<p>The <code class="filename">distinfo</code> file also contains the
- checksums for all the patches found in the
- <code class="filename">patches</code> directory (see <a class="xref" href="#components.patches" title="13.3.�patches/*">Section�13.3, “<code class="filename">patches/*</code>”</a>).
These checksums ensure that patches
- are only applied intentionally and that they don't accidentally change,
- e.g. when merging different changes together. They also make sure that
- new patches are actually added to CVS and old ones are removed.
- Too see whether the patches and the <code class="filename">distinfo</code> file
- match, run <span class="command"><strong>pkglint</strong></span> after changing the patches.</p>
-<p>To regenerate the <code class="filename">distinfo</code> file, use the
- <span class="command"><strong>make distinfo</strong></span> command.</p>
-<p>Some packages have different sets of distfiles depending on
- the platform, for example <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/openjdk8/README.html"; target="_top"><code class="filename">lang/openjdk8</code></a>. These are kept in the
same
- <code class="filename">distinfo</code> file and care should be taken when
- upgrading such a package to ensure distfile information is not
- lost.</p>
+<a name="other-mandatory-files"></a>12.4.�Other mandatory files</h2></div></div></div>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="filename">DESCR</code></span></dt>
+<dd><p>A multi-line description of the piece of software. This should include
+ any credits where they are due. Please bear in mind that others do not
+ share your sense of humour (or spelling idiosyncrasies), and that others
+ will read everything that you write here.</p></dd>
+<dt><span class="term"><code class="filename">PLIST</code></span></dt>
+<dd><p>This file governs the files that are installed on your
+ system: all the binaries, manual pages, etc. There are other
+ directives which may be entered in this file, to control the
+ creation and deletion of directories, and the location of
+ inserted files. See <a class="xref" href="#plist" title="Chapter�19.�PLIST issues">Chapter�19, <i>PLIST issues</i></a> for more
+ information.</p></dd>
+</dl></div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="components.patches"></a>13.3.�<code class="filename">patches/*</code>
-</h2></div></div></div>
-<p>Some packages don't work out-of-the box on the various
- platforms that are supported by pkgsrc. These packages need
- to be patched to make them work. The patch files can be
- found in the <code class="filename">patches/</code> directory.</p>
-<p>In the <span class="emphasis"><em>patch</em></span> phase, these patches are
- applied to the files in <code class="varname">WRKSRC</code> directory after
- extracting them, in alphabetic order.</p>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="components.patch.structure"></a>13.3.1.�Structure of a single patch file</h3></div></div></div>
-<p>The <code class="filename">patch-*</code> files should be in
- <span class="command"><strong>diff -bu</strong></span> format, and apply without a fuzz to avoid
- problems. (To force patches to apply with fuzz you can set
- <code class="varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, each patch
- should contain only changes for a single file, and no file should be
- patched by more than one patch file. This helps to keep future
- modifications simple.</p>
-<p>Each patch file is structured as follows: In the first line,
- there is the RCS Id of the patch itself. The second line should be
- empty for aesthetic reasons. After that, there should be a comment for
- each change that the patch does. There are a number of standard
- cases:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Patches for commonly known vulnerabilities should
- mention the vulnerability ID (CAN, CVE).</p></li>
-<li class="listitem"><p>Patches that change source code should mention the
- platform and other environment (for example, the compiler) that the
- patch is needed for.</p></li>
-</ul></div>
-<p>The patch should be commented so that any
- developer who knows the code of the application can make some use of
- the patch. Special care should be taken for the upstream developers,
- since we generally want that they accept our patches, so we have less
- work in the future.</p>
-</div>
+<a name="components.optional"></a>12.5.�Optional files</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="components.patches.caveats"></a>13.3.2.�Creating patch files</h3></div></div></div>
-<p>One important thing to mention is to pay attention that no RCS
- IDs get stored in the patch files, as these will cause problems when
- later checked into the NetBSD CVS tree. Use the
- <span class="command"><strong>pkgdiff</strong></span> command from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code
class="filename">pkgtools/pkgdiff</code></a> package to avoid these
- problems.</p>
-<p>For even more automation, we recommend using
- <span class="command"><strong>mkpatches</strong></span> from the same package to make a
- whole set of patches. You just have to backup files before you
- edit them to <code class="filename">filename.orig</code>, e.g. with
- <span class="command"><strong>cp -p filename filename.orig</strong></span> or, easier, by
- using <span class="command"><strong>pkgvi</strong></span> again from the same package. If
- you upgrade a package this way, you can easily compare the new
- set of patches with the previously existing one with
- <span class="command"><strong>patchdiff</strong></span>. The files in <code class="filename">patches</code>
- are replaced by new files, so carefully check if you want to take all
- the changes.</p>
-<p>When you have finished a package, remember to generate
- the checksums for the patch files by using the <span class="command"><strong>make
- makepatchsum</strong></span> command, see <a class="xref" href="#components.distinfo" title="13.2.�distinfo">Section�13.2, “<code class="filename">distinfo</code>”</a>.</p>
-<p>When adding a patch that corrects a problem in the
- distfile (rather than e.g. enforcing pkgsrc's view of where
- man pages should go), send the patch as a bug report to the
- maintainer. This benefits non-pkgsrc users of the package,
- and usually makes it possible to remove the patch in future
- version.</p>
-<p>The file names of the patch files are usually of the form
- <code class="filename">patch-<em class="replaceable"><code>path_to_file__with__underscores.c</code></em></code>.
- Many packages still use the previous convention
- <code class="filename">patch-<em class="replaceable"><code>[a-z][a-z]</code></em></code>,
- but new patches should be of the form containing the filename.
- <span class="command"><strong>mkpatches</strong></span> included in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code
class="filename">pkgtools/pkgdiff</code></a> takes care of the name
- automatically.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="components.patches.sources"></a>13.3.3.�Sources where the patch files come from</h3></div></div></div>
-<p>If you want to share patches between multiple packages
- in pkgsrc, e.g. because they use the same distfiles, set
- <code class="varname">PATCHDIR</code> to the path where the patch files
- can be found, e.g.:</p>
-<pre class="programlisting">
-PATCHDIR= ../../editors/xemacs/patches
-</pre>
-<p>Patch files that are distributed by the author or other
- maintainers can be listed in
- <code class="varname">PATCHFILES</code>.</p>
-<p>If it is desired to store any patches that should not be
- committed into pkgsrc, they can be kept outside the pkgsrc
- tree in the <code class="filename">$LOCALPATCHES</code> directory. The
- directory tree there is expected to have the same
- <span class="quote">“<span class="quote">category/package</span>”</span> structure as pkgsrc, and
- patches are expected to be stored inside these dirs (also
- known as <code class="filename">$LOCALPATCHES/$PKGPATH</code>). For
- example, if you want to keep a private patch for
- <code class="filename">pkgsrc/graphics/png</code>, keep it in
- <code class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
- files in the named directory are expected to be patch files,
- and <span class="emphasis"><em>they are applied after pkgsrc patches are
- applied</em></span>.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="components.patches.guidelines"></a>13.3.4.�Patching guidelines</h3></div></div></div>
-<p>When fixing a portability issue in the code do not use
- preprocessor magic to check for the current operating system nor
- platform. Doing so hurts portability to other platforms because
- the OS-specific details are not abstracted appropriately.</p>
-<p>The general rule to follow is: instead of checking for the
- operating system the application is being built on, check for the
- specific <span class="emphasis"><em>features</em></span> you need. For example,
- instead of assuming that kqueue is available under NetBSD and
- using the <code class="varname">__NetBSD__</code> macro to conditionalize
- kqueue support, add a check that detects kqueue itself —
- yes, this generally involves patching the
- <span class="command"><strong>configure</strong></span> script. There is absolutely nothing
- that prevents some OSes from adopting interfaces from other OSes
- (e.g. Linux implementing kqueue), something that the above checks
- cannot take into account.</p>
-<p>Of course, checking for features generally involves more
- work on the developer's side, but the resulting changes are
- cleaner and there are chances they will work on many other
- platforms. Not to mention that there are higher chances of being
- later integrated into the mainstream sources. Remember:
- <span class="emphasis"><em>It doesn't work unless it is right!</em></span></p>
-<p>Some typical examples:</p>
-<div class="table">
-<a name="patch-examples"></a><p class="title"><b>Table�13.1.�Patching examples</b></p>
-<div class="table-contents"><table class="table" summary="Patching examples" border="1">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Where</th>
-<th>Incorrect</th>
-<th>Correct</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>configure script</td>
-<td>
-<pre class="programlisting">
-case ${target_os} in
-netbsd*) have_kvm=yes ;;
-*) have_kvm=no ;;
-esac
-</pre>
- </td>
-<td>
-<pre class="programlisting">
-AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)
-</pre>
- </td>
-</tr>
-<tr>
-<td>C source file</td>
-<td>
-<pre class="programlisting">
-#if defined(__NetBSD__)
-# include <sys/event.h>
-#endif
-</pre>
- </td>
-<td>
-<pre class="programlisting">
-#if defined(HAVE_SYS_EVENT_H)
-# include <sys/event.h>
-#endif
-</pre>
- </td>
-</tr>
-<tr>
-<td>C source file</td>
-<td>
-<pre class="programlisting">
-int
-monitor_file(...)
-{
-#if defined(__NetBSD__)
- int fd = kqueue();
- ...
-#else
- ...
-#endif
-}
-</pre>
- </td>
-<td>
-<pre class="programlisting">
-int
-monitor_file(...)
-{
-#if defined(HAVE_KQUEUE)
- int fd = kqueue();
- ...
-#else
- ...
-#endif
-}
-</pre>
- </td>
-</tr>
-</tbody>
-</table></div>
-</div>
-<br class="table-break">
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="components.patches.feedback"></a>13.3.5.�Feedback to the author</h3></div></div></div>
-<p>Always, always, <span class="strong"><strong>always</strong></span>
- feed back any <span class="emphasis"><em>portability fixes</em></span> or
- improvements you do to a package to the mainstream developers.
- This is the only way to get their attention on portability issues
- and to ensure that future versions can be built out-of-the box on
- NetBSD. Furthermore, any user that gets newer distfiles will get
- the fixes straight from the packaged code.</p>
-<p>This generally involves cleaning up the patches
- (because sometimes the patches that are
- added to pkgsrc are quick hacks), filing bug reports in the
- appropriate trackers for the projects and working with the
- mainstream authors to accept your changes. It is
- <span class="emphasis"><em>extremely important</em></span> that you do it so that
- the packages in pkgsrc are kept simple and thus further changes
- can be done without much hassle.</p>
-<p>When you have done this, please add a URL to the upstream
- bug report to the patch comment.</p>
-<p>Support the idea of free software!</p>
-</div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="other-mandatory-files"></a>13.4.�Other mandatory files</h2></div></div></div>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="filename">DESCR</code></span></dt>
-<dd><p>A multi-line description of the piece of software. This should include
- any credits where they are due. Please bear in mind that others do not
- share your sense of humour (or spelling idiosyncrasies), and that others
- will read everything that you write here.</p></dd>
-<dt><span class="term"><code class="filename">PLIST</code></span></dt>
-<dd><p>This file governs the files that are installed on your
- system: all the binaries, manual pages, etc. There are other
- directives which may be entered in this file, to control the
- creation and deletion of directories, and the location of
- inserted files. See <a class="xref" href="#plist" title="Chapter�15.�PLIST issues">Chapter�15, <i>PLIST issues</i></a> for more
- information.</p></dd>
-</dl></div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="components.optional"></a>13.5.�Optional files</h2></div></div></div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="components.optional.bin"></a>13.5.1.�Files affecting the binary package</h3></div></div></div>
+<a name="components.optional.bin"></a>12.5.1.�Files affecting the binary package</h3></div></div></div>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="filename">INSTALL</code></span></dt>
<dd>
@@ -4311,7 +3849,7 @@ monitor_file(...)
are moved in place. This can be used to do any custom
procedures not possible with @exec commands in
<code class="filename">PLIST</code>. See <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_add</span>(1)</span></a> and
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a>
for more information. See also <a class="xref" href="#files-and-dirs-outside-prefix" title="17.1.�Files and directories outside the installation prefix">Section�17.1, “Files and directories
outside the installation prefix”</a>.
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a>
for more information. See also <a class="xref" href="#files-and-dirs-outside-prefix" title="20.1.�Files and directories outside the installation prefix">Section�20.1, “Files and directories
outside the installation prefix”</a>.
Please note that you can modify variables in it easily by using
<code class="varname">FILES_SUBST</code> in the package's
<code class="filename">Makefile</code>:</p>
@@ -4375,7 +3913,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="components.optional.build"></a>13.5.2.�Files affecting the build process</h3></div></div></div>
+<a name="components.optional.build"></a>12.5.2.�Files affecting the build process</h3></div></div></div>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="filename">Makefile.common</code></span></dt>
<dd><p>This file contains arbitrary things that could
@@ -4387,7 +3925,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
describes what it does.</p></dd>
<dt><span class="term"><code class="filename">buildlink3.mk</code></span></dt>
<dd><p>This file contains the dependency information
- for the buildlink3 framework (see <a class="xref" href="#buildlink" title="Chapter�16.�Buildlink methodology">Chapter�16, <i>Buildlink methodology</i></a>).</p></dd>
+ for the buildlink3 framework (see <a class="xref" href="#buildlink" title="Chapter�18.�Buildlink methodology">Chapter�18, <i>Buildlink methodology</i></a>).</p></dd>
<dt><span class="term"><code class="filename">hacks.mk</code></span></dt>
<dd><p>This file contains workarounds for compiler bugs
and similar things. It is included automatically by the pkgsrc
@@ -4396,7 +3934,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
it.</p></dd>
<dt><span class="term"><code class="filename">options.mk</code></span></dt>
<dd><p>This file contains the code for the
- package-specific options (see <a class="xref" href="#options" title="Chapter�18.�Options handling">Chapter�18, <i>Options handling</i></a>) that can be
+ package-specific options (see <a class="xref" href="#options" title="Chapter�16.�Options handling">Chapter�16, <i>Options handling</i></a>) that can be
selected by the user. If a package has only one or two options,
it is equally acceptable to put the code directly into the
<code class="filename">Makefile</code>.</p></dd>
@@ -4404,7 +3942,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="components.optional.none"></a>13.5.3.�Files affecting nothing at all</h3></div></div></div>
+<a name="components.optional.none"></a>12.5.3.�Files affecting nothing at all</h3></div></div></div>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="filename">README*</code></span></dt>
<dd><p>These files do not take place in the creation of
@@ -4419,7 +3957,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="work-dir"></a>13.6.�<code class="filename">work*</code>
+<a name="work-dir"></a>12.6.�<code class="filename">work*</code>
</h2></div></div></div>
<p>When you type <span class="command"><strong>make</strong></span>, the distribution files are
unpacked into the directory denoted by
@@ -4433,7 +3971,7 @@ MESSAGE_SUBST+= SOMEVAR="somevalue"
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="files-dir"></a>13.7.�<code class="filename">files/*</code>
+<a name="files-dir"></a>12.7.�<code class="filename">files/*</code>
</h2></div></div></div>
<p>If you have any files that you wish to be placed in the package
prior to configuration or building, you can place these files here
@@ -4450,2703 +3988,3185 @@ FILESDIR= ../../editors/xemacs/fil
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="makefile"></a>Chapter�14.�Programming in <code class="filename">Makefile</code>s</h2></div></div></div>
+<a name="build"></a>Chapter�13.�The build process</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="#makefile.style">14.1. Caveats</a></span></dt>
-<dt><span class="sect1"><a href="#makefile.variables">14.2. <code class="filename">Makefile</code> variables</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">14.2.1. Naming conventions</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#makefile.code">14.3. Code snippets</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#adding-to-list">14.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#echo-literal">14.3.2. Echoing a string exactly as-is</a></span></dt>
-<dt><span class="sect2"><a href="#cflags-gnu-configure">14.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
-<dt><span class="sect2"><a href="#empty-variables">14.3.4. Handling possibly empty variables</a></span></dt>
-</dl></dd>
+<dt><span class="sect1"><a href="#build.intro">13.1. Introduction</a></span></dt>
+<dt><span class="sect1"><a href="#build.prefix">13.2. Program location</a></span></dt>
+<dt><span class="sect1"><a href="#build.builddirs">13.3. Directories used during the build process</a></span></dt>
+<dt><span class="sect1"><a href="#build.running">13.4. Running a phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.fetch">13.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#build.fetch.what">13.5.1. What to fetch and where to get it from</a></span></dt>
+<dt><span class="sect2"><a href="#build.fetch.how">13.5.2. How are the files fetched?</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#build.checksum">13.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.extract">13.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.patch">13.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.tools">13.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.wrapper">13.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.configure">13.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.build">13.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.test">13.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.install">13.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.package">13.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
+<dt><span class="sect1"><a href="#build.clean">13.16. Cleaning up</a></span></dt>
+<dt><span class="sect1"><a href="#build.helpful-targets">13.17. Other helpful targets</a></span></dt>
</dl>
</div>
-<p>Pkgsrc consists of many <code class="filename">Makefile</code> fragments,
- each of which forms a well-defined part of the pkgsrc system. Using
- the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> system as a
programming language for a big system
- like pkgsrc requires some discipline to keep the code correct and
- understandable.</p>
-<p>The basic ingredients for <code class="filename">Makefile</code>
- programming are variables and shell
- commands. Among these shell commands may even be more complex ones
- like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?awk+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">awk</span>(1)</span></a> programs. To make
sure that every shell command runs
- as intended it is necessary to quote all variables correctly when they
- are used.</p>
-<p>This chapter describes some patterns that appear quite often in
- <code class="filename">Makefile</code>s, including the pitfalls that come along
- with them.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="makefile.style"></a>14.1.�Caveats</h2></div></div></div>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
-<p>When you are creating a file as a
- target of a rule, always write the data to a temporary file first
- and finally rename that file. Otherwise there might occur an error
- in the middle of generating the file, and when the user runs
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> for the second time,
the file exists and will not be
- regenerated properly. Example:</p>
-<pre class="programlisting">
-wrong:
- @echo "line 1" > ${.TARGET}
- @echo "line 2" >> ${.TARGET}
- @false
-
-correct:
- @echo "line 1" > ${.TARGET}.tmp
- @echo "line 2" >> ${.TARGET}.tmp
- @false
- @mv ${.TARGET}.tmp ${.TARGET}
-</pre>
-<p>When you run <span class="command"><strong>make wrong</strong></span> twice, the file
- <code class="filename">wrong</code> will exist, although there was an error
- message in the first run. On the other hand, running <span class="command"><strong>make
- correct</strong></span> gives an error message twice, as expected.</p>
-<p>You might remember that <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> sometimes removes
- <code class="literal">${.TARGET}</code> in case of error, but this only
- happens when it is interrupted, for example by pressing
- <code class="literal">Ctrl+C</code>. This does <span class="emphasis"><em>not</em></span> happen
- when one of the commands fails (like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?false+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">false</span>(1)</span></a> above).</p>
-</li></ul></div>
+<a name="build.intro"></a>13.1.�Introduction</h2></div></div></div>
+<p>This chapter gives a detailed description on how a package is
+ built. Building a package is separated into different
+ <span class="emphasis"><em>phases</em></span> (for example <code class="varname">fetch</code>,
+ <code class="varname">build</code>, <code class="varname">install</code>), all of which are
+ described in the following sections. Each phase is split into
+ so-called <span class="emphasis"><em>stages</em></span>, which take the name of the
+ containing phase, prefixed by one of <code class="varname">pre-</code>,
+ <code class="varname">do-</code> or <code class="varname">post-</code>. (Examples are
+ <code class="varname">pre-configure</code>, <code class="varname">post-build</code>.) Most
+ of the actual work is done in the <code class="varname">do-*</code> stages.</p>
+<p>Never override the regular targets (like
+ <code class="varname">fetch</code>), if you have to, override the
+ <code class="varname">do-*</code> ones instead.</p>
+<p>The basic steps for building a program are always the same. First
+ the program's source (<span class="emphasis"><em>distfile</em></span>) must be brought to
+ the local system and then extracted. After any pkgsrc-specific patches
+ to compile properly are applied, the software can be configured, then
+ built (usually by compiling), and finally the generated binaries, etc.
+ can be put into place on the system.</p>
+<p>To get more details about what is happening at each step,
+ you can set the <code class="varname">PKG_VERBOSE</code> variable, or the
+ <code class="varname">PATCH_DEBUG</code> variable if you are just interested
+ in more details about the <span class="emphasis"><em>patch</em></span> step.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="makefile.variables"></a>14.2.�<code class="filename">Makefile</code> variables</h2></div></div></div>
-<p><code class="filename">Makefile</code> variables contain strings that
- can be processed using the five operators <code class="code">=</code>,
- <code class="code">+=</code>, <code class="code">?=</code>, <code class="code">:=</code> and
- <code class="code">!=</code>, which are described in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> man
- page.</p>
-<p>When a variable's value is parsed from a
- <code class="filename">Makefile</code>, the hash character <code class="code">#</code> and
- the backslash character <code class="code">\</code> are handled specially. If a
- backslash is the last character in a line, that backslash is removed
- from the line and the line continues with the next line of the file.</p>
-<p>The <code class="code">#</code> character starts a comment that reaches
- until the end of the line. To get an actual <code class="code">#</code> character,
- such as in a URL, write <code class="code">\#</code> instead.</p>
-<p>The evaluation of variables either happens immediately or lazy.
- It happens immediately when the variable occurs on the right-hand
- side of the <code class="code">:=</code> or the <code class="code">!=</code> operator, in a
- <code class="varname">.if</code> condition or a <code class="varname">.for</code> loop.
- In the other cases, it is evaluated lazily.</p>
-<p>Some of the modifiers split the string into words and then
- operate on the words, others operate on the string as a whole. When a
- string is split into words, double quotes and single quotes are
- interpreted as delimiters, just like in <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sh+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">sh</span>(1)</span></a>.</p>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="makefile.variables.names"></a>14.2.1.�Naming conventions</h3></div></div></div>
+<a name="build.prefix"></a>13.2.�Program location</h2></div></div></div>
+<p>Before outlining the process performed by the NetBSD package system in
+ the next section, here's a brief discussion on where programs are
+ installed, and which variables influence this.</p>
+<p>The automatic variable <code class="varname">PREFIX</code> indicates
+ where all files of the final program shall be installed. It is
+ usually set to <code class="varname">LOCALBASE</code>
+ (<code class="filename">/usr/pkg</code>), or <code class="varname">CROSSBASE</code>
+ for pkgs in the <code class="filename">cross</code> category. The value of
+ <code class="varname">PREFIX</code> needs to be put
+ into the various places in the program's source where paths to
+ these files are encoded. See <a class="xref" href="#components.patches" title="12.3.�patches/*">Section�12.3, “<code class="filename">patches/*</code>”</a> and <a class="xref"
href="#fixes.libtool" title="21.3.1.�Shared libraries - libtool">Section�21.3.1, “Shared libraries - libtool”</a> for more details.</p>
+<p>When choosing which of these variables to use,
+ follow the following rules:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>All variable names starting with an underscore
- are reserved for use by the pkgsrc infrastructure. They shall
- not be used by packages.</p></li>
-<li class="listitem"><p>In <span class="command"><strong>.for</strong></span> loops you should use
- lowercase variable names for the iteration
- variables.</p></li>
-<li class="listitem"><p>All list variables should have a plural name,
- such as <code class="varname">PKG_OPTIONS</code> or
- <code class="varname">DISTFILES</code>.</p></li>
+<li class="listitem"><p><code class="varname">PREFIX</code> always points to the location
+ where the current pkg will be installed. When referring to a
+ pkg's own installation path, use
+ <span class="quote">“<span class="quote">${PREFIX}</span>”</span>.</p></li>
+<li class="listitem"><p><code class="varname">LOCALBASE</code> is where all non-X11 pkgs
+ are installed. If you need to construct a -I or -L argument
+ to the compiler to find includes and libraries installed by
+ another non-X11 pkg, use <span class="quote">“<span class="quote">${LOCALBASE}</span>”</span>. The name
+ <code class="varname">LOCALBASE</code> stems from FreeBSD, which
+ installed all packages in <code class="filename">/usr/local</code>. As
+ pkgsrc leaves <code class="filename">/usr/local</code> for the system
+ administrator, this variable is a misnomer.</p></li>
+<li class="listitem"><p><code class="varname">X11BASE</code> is where the actual X11
+ distribution (from xsrc, etc.) is installed. When looking for
+ <span class="emphasis"><em>standard</em></span> X11 includes (not those
+ installed by a package), use <span class="quote">“<span class="quote">${X11BASE}</span>”</span>.</p></li>
+<li class="listitem"><p>X11-based packages using imake must set
+ <code class="varname">USE_IMAKE</code> to be installed correctly under
+ <code class="varname">LOCALBASE</code>.</p></li>
+<li class="listitem"><p>Within <code class="filename">${PREFIX}</code>, packages should
+ install files according to <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?hier+7.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">hier</span>(7)</span></a>, with the exception that
+ manual pages go into <code class="filename">${PREFIX}/man</code>, not
+ <code class="filename">${PREFIX}/share/man</code>.</p></li>
</ul></div>
</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="build.builddirs"></a>13.3.�Directories used during the build process</h2></div></div></div>
+<p>When building a package, various directories are used to store
+ source files, temporary files, pkgsrc-internal files, and so on. These
+ directories are explained here.</p>
+<p>Some of the directory variables contain relative pathnames. There
+ are two common base directories for these relative directories:
+ <code class="varname">PKGSRCDIR/PKGPATH</code> is used for directories that are
+ pkgsrc-specific. <code class="varname">WRKSRC</code> is used for directories
+ inside the package itself.</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">PKGSRCDIR</code></span></dt>
+<dd><p>This is an absolute pathname that points to the pkgsrc
+ root directory. Generally, you don't need
+ it.</p></dd>
+<dt><span class="term"><code class="varname">PKGDIR</code></span></dt>
+<dd><p>This is an absolute pathname that points to the
+ current package.</p></dd>
+<dt><span class="term"><code class="varname">PKGPATH</code></span></dt>
+<dd><p>This is a pathname relative to
+ <code class="varname">PKGSRCDIR</code> that points to the current
+ package.</p></dd>
+<dt><span class="term"><code class="varname">WRKDIR</code></span></dt>
+<dd><p>This is an absolute pathname pointing to the directory
+ where all work takes place. The distfiles are extracted to this
+ directory. It also contains temporary directories and log files used by
+ the various pkgsrc frameworks, like <span class="emphasis"><em>buildlink</em></span> or
+ the <span class="emphasis"><em>wrappers</em></span>.</p></dd>
+<dt><span class="term"><code class="varname">WRKSRC</code></span></dt>
+<dd><p>This is an absolute pathname pointing to the directory
+ where the distfiles are extracted. It is usually a direct subdirectory
+ of <code class="varname">WRKDIR</code>, and often it's the only directory entry
+ that isn't hidden. This variable may be changed by a package
+ <code class="filename">Makefile</code>.</p></dd>
+</dl></div>
+<p>The <code class="varname">CREATE_WRKDIR_SYMLINK</code> definition takes either
+ the value <span class="emphasis"><em>yes</em></span> or <span class="emphasis"><em>no</em></span> and defaults
+ to <span class="emphasis"><em>no</em></span>. It indicates whether a symbolic link to the
+ <code class="varname">WRKDIR</code> is to be created in the pkgsrc entry's directory.
+ If users would like to have their pkgsrc trees behave in a
+ read-only manner, then the value of
+ <code class="varname">CREATE_WRKDIR_SYMLINK</code> should be set to
+ <span class="emphasis"><em>no</em></span>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="makefile.code"></a>14.3.�Code snippets</h2></div></div></div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="adding-to-list"></a>14.3.1.�Adding things to a list</h3></div></div></div>
-<p>When adding a string that possibly contains whitespace or quotes to
-a list (example 1), it must be quoted using the <code class="code">:Q</code>
-modifier.</p>
-<p>When adding another list to a list (example 2), it must not be
-quoted, since its elements are already quoted.</p>
-<pre class="programlisting">
-STRING= foo * bar `date`
-LIST= # empty
-ANOTHER_LIST= a=b c=d
-
-LIST+= ${STRING:Q} # 1
-LIST+= ${ANOTHER_LIST} # 2
-</pre>
+<a name="build.running"></a>13.4.�Running a phase</h2></div></div></div>
+<p>You can run a particular phase by typing <span class="command"><strong>make
+ phase</strong></span>, where <span class="emphasis"><em>phase</em></span> is the name of the
+ phase. This will automatically run all phases that are required for this
+ phase. The default phase is <code class="varname">build</code>, that is, when you
+ run <span class="command"><strong>make</strong></span> without parameters in a package directory,
+ the package will be built, but not installed.</p>
</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="build.fetch"></a>13.5.�The <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
+<p>The first step in building a package is to fetch the
+ distribution files (distfiles) from the sites that are providing
+ them. This is the task of the <span class="emphasis"><em>fetch</em></span>
+ phase.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="echo-literal"></a>14.3.2.�Echoing a string exactly as-is</h3></div></div></div>
-<p>Echoing a string containing special characters needs special
-work.</p>
+<a name="build.fetch.what"></a>13.5.1.�What to fetch and where to get it from</h3></div></div></div>
+<p>In simple cases, <code class="varname">MASTER_SITES</code>
+ defines all URLs from where the distfile, whose name is
+ derived from the <code class="varname">DISTNAME</code> variable, is
+ fetched. The more complicated cases are described
+ below.</p>
+<p>The variable <code class="varname">DISTFILES</code> specifies
+ the list of distfiles that have to be fetched. Its value
+ defaults to <code class="literal">${DEFAULT_DISTFILES}</code> and
+ its value is <code class="literal">${DISTNAME}${EXTRACT_SUFX}</code>,
+ so that most packages don't need to define it at all.
+ <code class="varname">EXTRACT_SUFX</code> is
+ <code class="literal">.tar.gz</code> by default, but can be changed
+ freely. Note that if your package requires additional
+ distfiles to the default one, you cannot just append the
+ additional filenames using the <code class="literal">+=</code>
+ operator, but you have write for example:</p>
<pre class="programlisting">
-STRING= foo bar < > * `date` $$HOME ' "
-EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
-
-all:
- echo ${STRING} # 1
- echo ${STRING:Q} # 2
- printf '%s\n' ${STRING:Q}'' # 3
- env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
+DISTFILES= ${DEFAULT_DISTFILES} additional-files.tar.gz
</pre>
-<p>Example 1 leads to a syntax error in the shell, as the characters
-are just copied.</p>
-<p>Example 2 quotes the string so that the shell interprets it
-correctly. But the echo command may additionally interpret strings with a
-leading dash or those containing backslashes.</p>
-<p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">printf</span>(1)</span></a> only
-interprets the format string, but not the next argument. The trailing
-single quotes handle the case when the string is empty. In that case, the
-:Q modifier would result in an empty string too, which would then be
-skipped by the shell. For <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">printf</span>(1)</span></a> this doesn't make a difference,
-but other programs may care.</p>
-<p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
-need to be quoted because the quoting has already been done
-when adding elements to the list.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="cflags-gnu-configure"></a>14.3.3.�Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
-<p>When passing <code class="varname">CFLAGS</code> or similar variables to a
-GNU-style configure script (especially those that call other configure
-scripts), it must not have leading or trailing whitespace, since
-otherwise the configure script gets confused. To trim leading and
-trailing whitespace, use the <code class="code">:M</code> modifier, as in the
-following example:</p>
+<p>Each distfile is fetched from a list of sites, usually
+ <code class="varname">MASTER_SITES</code>. If the package has multiple
+ <code class="varname">DISTFILES</code> or multiple
+ <code class="varname">PATCHFILES</code> from different sites, you can
+ set
+ <code class="varname">SITES.<em class="replaceable"><code>distfile</code></em></code>
+ to the list of URLs where the file
+ <code class="filename"><em class="replaceable"><code>distfile</code></em></code>
+ (including the suffix) can be found.</p>
<pre class="programlisting">
-CPPFLAGS= # empty
-CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
-CPPFLAGS+= ${MY_CPPFLAGS}
-
-CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
-
-all:
- echo x${CPPFLAGS:Q}x # leading and trailing whitespace
- echo x${CONFIGURE_ARGS:Q}x # properly trimmed
+DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
+DISTFILES+= foo-file.tar.gz
+SITES.foo-file.tar.gz= \
+https://www.somewhere.com/somehow/ \
+https://www.somewhereelse.com/mirror/somehow/
</pre>
-<p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
-trailing whitespace because the <code class="code">+=</code> operator always adds a
-space.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="empty-variables"></a>14.3.4.�Handling possibly empty variables</h3></div></div></div>
-<p>When a possibly empty variable is used in a shell program, it may
-lead to a syntax error.</p>
+<p>When actually fetching the distfiles, each item from
+ <code class="varname">MASTER_SITES</code> or
+ <code class="varname">SITES.*</code> gets the name of each distfile
+ appended to it, without an intermediate slash. Therefore,
+ all site values have to end with a slash or other separator
+ character. This allows for example to set
+ <code class="varname">MASTER_SITES</code> to a URL of a CGI script
+ that gets the name of the distfile as a parameter. In this
+ case, the definition would look like:</p>
<pre class="programlisting">
-EGFILES= # empty
-
-install-examples: # produces a syntax error in the shell
- for egfile in ${EGFILES}; do \
- echo "Installing $$egfile"; \
- done
+MASTER_SITES= https://www.example.com/download.cgi?file=
</pre>
-<p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
-<code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a>.
-To fix this syntax error, use one of the snippets below.</p>
+<p> The exception to this rule are URLs starting with a dash.
+ In that case the URL is taken as is, fetched and the result
+ stored under the name of the distfile. You can use this style
+ for the case when the download URL style does not match the
+ above common case. For example, if permanent download URL is a
+ redirector to the real download URL, or the download file name
+ is offered by an HTTP Content-Disposition header. In the
+ following example, <code class="filename">foo-1.0.0.tar.gz</code> will be
+ created instead of the default
+ <code class="filename">v1.0.0.tar.gz</code>.</p>
<pre class="programlisting">
-EMPTY= # empty
-
-install-examples:
- for egfile in ${EGFILES} ""; do \
- [ -n "$$egfile" ] || continue; \
- echo "Installing $$egfile"; \
- done
+DISTNAME= foo-1.0.0
+MASTER_SITES= -https://www.example.com/archive/v1.0.0.tar.gz
</pre>
-<p>In this case, an empty string is appended to the iteration list (to
-prevent the syntax error) and filtered out later.</p>
-<pre class="programlisting">
-EGFILES= # empty
-
-install-examples:
-.for egfile in ${EGFILES}
- echo "Installing ${egfile}"
-.endfor
+<p>There are some predefined values for
+ <code class="varname">MASTER_SITES</code>, which can be used in
+ packages. The names of the variables should speak for
+ themselves.</p>
+<table border="0" summary="Simple list" class="simplelist">
+<tr>
+<td>MASTER_SITE_APACHE</td>
+<td>MASTER_SITE_BACKUP</td>
+</tr>
+<tr>
+<td>MASTER_SITE_CRATESIO</td>
+<td>MASTER_SITE_CYGWIN</td>
+</tr>
+<tr>
+<td>MASTER_SITE_DEBIAN</td>
+<td>MASTER_SITE_FREEBSD</td>
+</tr>
+<tr>
+<td>MASTER_SITE_FREEBSD_LOCAL</td>
+<td>MASTER_SITE_GENTOO</td>
+</tr>
+<tr>
+<td>MASTER_SITE_GITHUB</td>
+<td>MASTER_SITE_GNOME</td>
+</tr>
+<tr>
+<td>MASTER_SITE_GNU</td>
+<td>MASTER_SITE_GNUSTEP</td>
+</tr>
+<tr>
+<td>MASTER_SITE_HASKELL_HACKAGE</td>
+<td>MASTER_SITE_IFARCHIVE</td>
+</tr>
+<tr>
+<td>MASTER_SITE_KDE</td>
+<td>MASTER_SITE_MOZILLA</td>
+</tr>
+<tr>
+<td>MASTER_SITE_MOZILLA_ALL</td>
+<td>MASTER_SITE_MYSQL</td>
+</tr>
+<tr>
+<td>MASTER_SITE_NETLIB</td>
+<td>MASTER_SITE_OPENBSD</td>
+</tr>
+<tr>
+<td>MASTER_SITE_OPENOFFICE</td>
+<td>MASTER_SITE_OSDN</td>
+</tr>
+<tr>
+<td>MASTER_SITE_PERL_CPAN</td>
+<td>MASTER_SITE_PGSQL</td>
+</tr>
+<tr>
+<td>MASTER_SITE_PYPI</td>
+<td>MASTER_SITE_RUBYGEMS</td>
+</tr>
+<tr>
+<td>MASTER_SITE_R_CRAN</td>
+<td>MASTER_SITE_SOURCEFORGE</td>
+</tr>
+<tr>
+<td>MASTER_SITE_SUNSITE</td>
+<td>MASTER_SITE_SUSE</td>
+</tr>
+<tr>
+<td>MASTER_SITE_TEX_CTAN</td>
+<td>MASTER_SITE_XCONTRIB</td>
+</tr>
+<tr>
+<td>MASTER_SITE_XEMACS</td>
+<td>MASTER_SITE_XORG</td>
+</tr>
+</table>
+<p>Some explanations for the less self-explaining ones:
+ <code class="varname">MASTER_SITE_BACKUP</code> contains backup sites
+ for packages that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/%24%7BDIST_SUBDIR%7D";
target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/${DIST_SUBDIR}</a>. <code class="varname">MASTER_SITE_LOCAL</code> contains local
+ package source distributions that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/";
target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/</a>.</p>
+<p>If you choose one of these predefined sites, you may
+ want to specify a subdirectory of that site. Since these
+ macros may expand to more than one actual site, you
+ <span class="emphasis"><em>must</em></span> use the following construct to
+ specify a subdirectory:</p>
+<pre class="programlisting">
+MASTER_SITES= ${MASTER_SITE_GNU:=subdirectory/name/}
+MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/}
</pre>
-<p>If one of the filenames contains special characters, it should be
-enclosed in single or double quotes.</p>
-<p>To have a shell command test whether a make variable is empty, use
-the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
+<p>Note the trailing slash after the subdirectory
+ name.</p>
</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="build.fetch.how"></a>13.5.2.�How are the files fetched?</h3></div></div></div>
+<p>The <span class="emphasis"><em>fetch</em></span> phase makes sure that
+ all the distfiles exist in a local directory
+ (<code class="varname">DISTDIR</code>, which can be set by the pkgsrc
+ user). If the files do not exist, they are fetched using
+ commands of the form</p>
+<pre class="programlisting">
+${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
+</pre>
+<p>where <code class="literal">${site}</code> varies through
+ several possibilities in turn: first,
+ <code class="varname">MASTER_SITE_OVERRIDE</code> is tried, then the
+ sites specified in either <code class="varname">SITES.file</code> if
+ defined, else <code class="varname">MASTER_SITES</code> or
+ <code class="varname">PATCH_SITES</code>, as applies, then finally the
+ value of <code class="varname">MASTER_SITE_BACKUP</code>. The order of
+ all except the first and the last can be optionally sorted
+ by the user, via setting either
+ <code class="varname">MASTER_SORT_RANDOM</code>, and
+ <code class="varname">MASTER_SORT_AWK</code> or
+ <code class="varname">MASTER_SORT_REGEX</code>.</p>
+<p> The specific command and arguments used depend on the
+ <code class="varname">FETCH_USING</code> parameter. The example above is
+ for <code class="literal">FETCH_USING=custom</code>.</p>
+<p>The distfiles mirror run by the NetBSD Foundation uses the
+ <span class="emphasis"><em>mirror-distfiles</em></span> target to mirror the
+ distfiles, if they are freely distributable. Packages setting
+ <code class="varname">NO_SRC_ON_FTP</code> (usually to
+ <span class="quote">“<span class="quote">${RESTRICTED}</span>”</span>) will not have their distfiles
+ mirrored.</p>
</div>
</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="plist"></a>Chapter�15.�PLIST issues</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#rcs-id">15.1. RCS ID</a></span></dt>
-<dt><span class="sect1"><a href="#automatic-plist-generation">15.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
-<dt><span class="sect1"><a href="#print-PLIST">15.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
-<dt><span class="sect1"><a href="#plist.misc">15.4. Variable substitution in PLIST</a></span></dt>
-<dt><span class="sect1"><a href="#manpage-compression">15.5. Man page compression</a></span></dt>
-<dt><span class="sect1"><a href="#using-PLIST_SRC">15.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
-<dt><span class="sect1"><a href="#platform-specific-plist">15.7. Platform-specific and differing PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#build-plist">15.8. Build-specific PLISTs</a></span></dt>
-<dt><span class="sect1"><a href="#faq.common-dirs">15.9. Sharing directories between packages</a></span></dt>
-</dl>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="build.checksum"></a>13.6.�The <span class="emphasis"><em>checksum</em></span> phase</h2></div></div></div>
+<p>After the distfile(s) are fetched, their checksum is
+ generated and compared with the checksums stored in the
+ distinfo file. If the checksums don't match, the build is
+ aborted. This is to ensure the same distfile is used for
+ building, and that the distfile wasn't changed, e.g. by some
+ malign force, deliberately changed distfiles on the master
+ distribution site or network lossage.</p>
</div>
-<p>The <code class="filename">PLIST</code> file contains a package's
- <span class="quote">“<span class="quote">packing list</span>”</span>, i.e. a list of files that belong to
- the package (relative to the <code class="filename">${PREFIX}</code>
- directory it's been installed in) plus some additional statements
- - see the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a>
man page for a full list.
- This chapter addresses some issues that need attention when
- dealing with the <code class="filename">PLIST</code> file (or files, see
- below!).</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="rcs-id"></a>15.1.�RCS ID</h2></div></div></div>
-<p>Be sure to add a RCS ID line as the first thing in any
- <code class="filename">PLIST</code> file you write:</p>
-<pre class="programlisting">
-@comment $NetBSD $
-</pre>
-<p>An artificial space has been added between NetBSD and $, this is a
-workaround here to prevent CVS expanding to the filename of the guide. When
-adding the RCS ID the space should be omitted.</p>
+<a name="build.extract"></a>13.7.�The <span class="emphasis"><em>extract</em></span> phase</h2></div></div></div>
+<p>When the distfiles are present on the local system, they
+ need to be extracted, as they usually come in the form of some
+ compressed archive format.</p>
+<p>By default, all <code class="varname">DISTFILES</code> are
+ extracted. If you only need some of them, you can set the
+ <code class="varname">EXTRACT_ONLY</code> variable to the list of those
+ files.</p>
+<p>Extracting the files is usually done by a little
+ program, <code class="filename">mk/extract/extract</code>, which
+ already knows how to extract various archive formats, so most
+ likely you will not need to change anything here. But if you
+ need, the following variables may help you:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</code></span></dt>
+<dd><p>Use these variables to override the default
+ options for an extract command, which are defined in
+ <code class="filename">mk/extract/extract</code>.</p></dd>
+<dt><span class="term"><code class="varname">EXTRACT_USING</code></span></dt>
+<dd><p>This variable can be set to
+ <code class="literal">bsdtar</code>, <code class="literal">gtar</code>, <code class="literal">nbtar</code>
+ (which is the default value), <code class="literal">pax</code>, or an
+ absolute pathname pointing to the command with which tar
+ archives should be extracted. It is preferred to choose bsdtar over gtar
+ if NetBSD's pax-as-tar is not good enough.</p></dd>
+</dl></div>
+<p>If the <code class="filename">extract</code> program doesn't
+ serve your needs, you can also override the
+ <code class="varname">EXTRACT_CMD</code> variable, which holds the
+ command used for extracting the files. This command is
+ executed in the <code class="filename">${WRKSRC}</code>
+ directory. During execution of this command, the shell
+ variable <code class="varname">extract_file</code> holds the absolute
+ pathname of the file that is going to be extracted.</p>
+<p>And if that still does not suffice, you can override the
+ <code class="varname">do-extract</code> target in the package
+ Makefile.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="automatic-plist-generation"></a>15.2.�Semi-automatic <code class="filename">PLIST</code> generation</h2></div></div></div>
-<p>You can use the <span class="command"><strong>make print-PLIST</strong></span> command
- to output a PLIST that matches any new files since the package
- was extracted. See <a class="xref" href="#build.helpful-targets" title="19.17.�Other helpful targets">Section�19.17, “Other helpful targets”</a> for
- more information on this target.</p>
+<a name="build.patch"></a>13.8.�The <span class="emphasis"><em>patch</em></span> phase</h2></div></div></div>
+<p>After extraction, all the patches named by the
+ <code class="varname">PATCHFILES</code>, those present in the patches
+ subdirectory of the package as well as in
+ $LOCALPATCHES/$PKGPATH (e.g.
+ <code class="filename">/usr/local/patches/graphics/png</code>) are
+ applied. Patchfiles ending in <code class="filename">.Z</code> or
+ <code class="filename">.gz</code> are uncompressed before they are
+ applied, files ending in <code class="filename">.orig</code> or
+ <code class="filename">.rej</code> are ignored. Any special options to
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> can be handed in
+ <code class="varname">PATCH_DIST_ARGS</code>. See <a class="xref" href="#components.patches" title="12.3.�patches/*">Section�12.3, “<code class="filename">patches/*</code>”</a> for
more details.</p>
+<p>By default <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given
special arguments to make it
+ fail if the expected text from the patch context is not found in the
+ patched file. If that happens, fix the patch file by comparing it
+ with the actual text in the file to be patched.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="print-PLIST"></a>15.3.�Tweaking output of <span class="command"><strong>make print-PLIST</strong></span>
-</h2></div></div></div>
-<p>The <code class="varname">PRINT_PLIST_AWK</code> variable takes a set
- of AWK patterns and actions that are used to filter the output of
- print-PLIST. You can <span class="emphasis"><em>append</em></span> any chunk of AWK
- scripting you like to it, but be careful with quoting.</p>
-<p>For example, to get all files inside the
- <code class="filename">libdata/foo</code> directory removed from the
- resulting PLIST:</p>
-<pre class="programlisting">
-PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
-</pre>
-<p>The <code class="varname">PRINT_PLIST_AWK</code> transformations are
- evaluated after the file list and directory list are sorted.
- <code class="varname">EARLY_PRINT_PLIST_AWK</code> is like
- <code class="varname">PRINT_PLIST_AWK</code> except it operates before the file
- list and directory list are sorted.</p>
+<a name="build.tools"></a>13.9.�The <span class="emphasis"><em>tools</em></span> phase</h2></div></div></div>
+<p>This is covered in <a class="xref" href="#tools" title="Chapter�17.�Tools needed for building or running">Chapter�17, <i>Tools needed for building or running</i></a>.
+ </p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="plist.misc"></a>15.4.�Variable substitution in PLIST</h2></div></div></div>
-<p>A number of variables are substituted automatically in
- PLISTs when a package is installed on a system. This includes the
- following variables:</p>
+<a name="build.wrapper"></a>13.10.�The <span class="emphasis"><em>wrapper</em></span> phase</h2></div></div></div>
+<p>This phase creates wrapper programs for the compilers and
+ linkers. The following variables can be used to tweak the
+ wrappers.</p>
<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">${MACHINE_ARCH}</code>, <code class="varname">${MACHINE_GNU_ARCH}</code></span></dt>
-<dd>
-<p>Some packages like emacs and perl embed information
- about which architecture they were built on into the
- pathnames where they install their files. To handle this
- case, PLIST will be preprocessed before actually used, and
- the symbol
- <span class="quote">“<span class="quote"><code class="varname">${MACHINE_ARCH}</code></span>”</span> will be
- replaced by what <span class="command"><strong>uname -p</strong></span> gives. The
- same is done if the string
- <code class="varname">${MACHINE_GNU_ARCH}</code> is embedded in
- PLIST somewhere - use this on packages that have GNU
- autoconf-created configure scripts.</p>
-<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
-<h3 class="title">Legacy note</h3>
-<p>There used to be a symbol
- <span class="quote">“<span class="quote"><code class="varname">$ARCH</code></span>”</span> that
- was replaced by the output of <span class="command"><strong>uname
- -m</strong></span>, but that's no longer supported and has
- been removed.</p>
-</div>
-</dd>
-<dt><span class="term"><code class="varname">${OPSYS}</code>, <code class="varname">${LOWER_OPSYS}</code>, <code class="varname">${OS_VERSION}</code></span></dt>
-<dd>
-<p>Some packages want to embed the OS name and version
- into some paths. To do this, use these variables in the
- <code class="filename">PLIST</code>:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">${OPSYS}</code> - output of <span class="quote">“<span class="quote"><span class="command"><strong>uname
-s</strong></span></span>”</span></p></li>
-<li class="listitem"><p><code class="varname">${LOWER_OPSYS}</code> - lowercase common name (eg. <span class="quote">“<span class="quote">solaris</span>”</span>)</p></li>
-<li class="listitem"><p><code class="varname">${OS_VERSION}</code> - <span class="quote">“<span class="quote"><span class="command"><strong>uname
-r</strong></span></span>”</span></p></li>
-</ul></div>
-</dd>
+<dt><span class="term"><code class="varname">ECHO_WRAPPER_MSG</code></span></dt>
+<dd><p>The command used to print progress
+ messages. Does nothing by default. Set to
+ <code class="literal">${ECHO}</code> to see the progress
+ messages.</p></dd>
+<dt><span class="term"><code class="varname">WRAPPER_DEBUG</code></span></dt>
+<dd><p>This variable can be set to
+ <code class="literal">yes</code> (default) or <code class="literal">no</code>,
+ depending on whether you want additional information in the
+ wrapper log file.</p></dd>
+<dt><span class="term"><code class="varname">WRAPPER_UPDATE_CACHE</code></span></dt>
+<dd><p>This variable can be set to
+ <code class="literal">yes</code> or <code class="literal">no</code>, depending
+ on whether the wrapper should use its cache, which will
+ improve the speed. The default value is
+ <code class="literal">yes</code>, but is forced to
+ <code class="literal">no</code> if the platform does not support
+ it.</p></dd>
+<dt><span class="term"><code class="varname">WRAPPER_REORDER_CMDS</code></span></dt>
+<dd><p>A list of reordering commands. A reordering
+ command has the form
+ <code class="literal">reorder:l:<em class="replaceable"><code>lib1</code></em>:<em class="replaceable"><code>lib2</code></em></code>.
+ It ensures that that
+ <code class="literal">-l<em class="replaceable"><code>lib1</code></em></code> occurs
+ before <code class="literal">-l<em class="replaceable"><code>lib2</code></em></code>.
+ </p></dd>
</dl></div>
-<p>For a list of values which are replaced by
- default, the output of <span class="command"><strong>make help topic=PLIST_SUBST</strong></span> as
-well as searching the <code class="filename">pkgsrc/mk</code> directory with <span class="command"><strong>grep</strong></span> for
-<code class="varname">PLIST_SUBST</code> should help.</p>
-<p>If you want to change other variables not listed above, you
- can add variables and their expansions to this variable in the
- following way, similar to <code class="varname">MESSAGE_SUBST</code> (see <a class="xref" href="#components.optional" title="13.5.�Optional files">Section�13.5, “Optional
files”</a>):</p>
-<pre class="programlisting">
-PLIST_SUBST+= SOMEVAR="somevalue"
-</pre>
-<p>This replaces all occurrences of <span class="quote">“<span class="quote">${SOMEVAR}</span>”</span>
- in the <code class="filename">PLIST</code> with
- <span class="quote">“<span class="quote">somevalue</span>”</span>.</p>
-<p>The <code class="varname">PLIST_VARS</code> variable can be used to simplify
- the common case of conditionally including some
- <code class="filename">PLIST</code> entries. It can be done by adding
- <code class="literal"><code class="varname">PLIST_VARS</code>+=foo</code> and
- setting the corresponding <code class="varname">PLIST.foo</code> variable
- to <code class="literal">yes</code> if the entry should be included.
- This will substitute <span class="quote">“<span class="quote"><code class="varname">${PLIST.foo}</code></span>”</span>
- in the <code class="filename">PLIST</code> with either
- <span class="quote">“<span class="quote"><code class="literal">""</code></span>”</span> or
- <span class="quote">“<span class="quote"><code class="literal">"@comment "</code></span>”</span>.
- For example, in <code class="filename">Makefile</code>:</p>
-<pre class="programlisting">
-PLIST_VARS+= foo
-.if <em class="replaceable"><code>condition</code></em>
-PLIST.foo= yes
-.else
-</pre>
-<p>And then in <code class="filename">PLIST</code>:</p>
-<pre class="programlisting">
-@comment $NetBSD $
-bin/bar
-man/man1/bar.1
-${PLIST.foo}bin/foo
-${PLIST.foo}man/man1/foo.1
-${PLIST.foo}share/bar/foo.data
-</pre>
-<p>An artificial space has been added between NetBSD and $, this is a
-workaround here to prevent CVS expanding to the filename of the guide. When
-adding the RCS ID the space should be ommited.</p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="manpage-compression"></a>15.5.�Man page compression</h2></div></div></div>
-<p>Man pages should be installed in compressed form if
- <code class="varname">MANZ</code> is set (in <code class="filename">bsd.own.mk</code>),
- and uncompressed otherwise. To handle this in the
- <code class="filename">PLIST</code> file, the suffix <span class="quote">“<span class="quote">.gz</span>”</span> is
- appended/removed automatically for man pages according to
- <code class="varname">MANZ</code> and <code class="varname">MANCOMPRESSED</code> being set
- or not, see above for details. This modification of the
- <code class="filename">PLIST</code> file is done on a copy of it, not
- <code class="filename">PLIST</code> itself.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="using-PLIST_SRC"></a>15.6.�Changing PLIST source with <code class="varname">PLIST_SRC</code>
-</h2></div></div></div>
-<p>To use one or more files as source for the <code class="filename">PLIST</code> used
- in generating the binary package, set the variable
- <code class="varname">PLIST_SRC</code> to the names of that file(s).
- The files are later concatenated using <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?cat+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">cat</span>(1)</span></a>, and the order of things is
- important. The default for <code class="varname">PLIST_SRC</code> is
- <code class="filename">${PKGDIR}/PLIST</code>.</p>
+<a name="build.configure"></a>13.11.�The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
+<p>Most pieces of software need information on the header
+ files, system calls, and library routines which are available
+ on the platform they run on. The process of determining this
+ information is known as configuration, and is usually
+ automated. In most cases, a script is supplied with the
+ distfiles, and its invocation results in generation of header
+ files, Makefiles, etc.</p>
+<p>If the package contains a configure script, this can be
+ invoked by setting <code class="varname">HAS_CONFIGURE</code> to
+ <span class="quote">“<span class="quote">yes</span>”</span>. If the configure script is a GNU autoconf
+ script, you should set <code class="varname">GNU_CONFIGURE</code> to
+ <span class="quote">“<span class="quote">yes</span>”</span> instead. What happens in the
+ <span class="emphasis"><em>configure</em></span> phase is roughly:</p>
+<pre class="programlisting">
+.for d in ${CONFIGURE_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
+.endfor
+</pre>
+<p><code class="varname">CONFIGURE_DIRS</code> (default:
+ <span class="quote">“<span class="quote">.</span>”</span>) is a list of pathnames relative to
+ <code class="varname">WRKSRC</code>. In each of these directories, the
+ configure script is run with the environment
+ <code class="varname">CONFIGURE_ENV</code> and arguments
+ <code class="varname">CONFIGURE_ARGS</code>. The variables
+ <code class="varname">CONFIGURE_ENV</code>,
+ <code class="varname">CONFIGURE_SCRIPT</code> (default:
+ <span class="quote">“<span class="quote">./configure</span>”</span>) and
+ <code class="varname">CONFIGURE_ARGS</code> may all be changed by the
+ package.</p>
+<p>If the program uses the Perl way of configuration (mainly Perl
+ modules, but not only), i.e. a file called
+ <code class="filename">Makefile.PL</code>, it should include
+ <code class="filename">../../lang/perl5/module.mk</code>. To set any parameter for
+ <code class="filename">Makefile.PL</code> use the <code class="varname">MAKE_PARAMS</code>
+ variable (e.g., <code class="literal">MAKE_PARAMS+=foo=bar</code></p>
+<p>If the program uses an <code class="filename">Imakefile</code>
+ for configuration, the appropriate steps can be invoked by
+ setting <code class="varname">USE_IMAKE</code> to
+ <span class="quote">“<span class="quote">yes</span>”</span>. If you only need xmkmf, add it to <code class="varname">USE_TOOLS</code>.
+ You can add variables to xmkmf's environment by adding them to the
+ <code class="varname">SCRIPTS_ENV</code> variable.</p>
+<p>If the program uses <code class="filename">cmake</code>
+ for configuration, the appropriate steps can be invoked by
+ setting <code class="varname">USE_CMAKE</code> to <span class="quote">“<span class="quote">yes</span>”</span>.
+ You can add variables to cmake's environment by adding them to the
+ <code class="varname">CONFIGURE_ENV</code> variable and arguments to cmake
+ by adding them to the <code class="varname">CMAKE_ARGS</code> variable.
+ The top directory argument is given by the
+ <code class="varname">CMAKE_ARG_PATH</code> variable, that defaults to
+ <span class="quote">“<span class="quote">.</span>”</span> (relative to <code class="varname">CONFIGURE_DIRS</code>)</p>
+<p>If there is no configure step at all, set
+ <code class="varname">NO_CONFIGURE</code> to <span class="quote">“<span class="quote">yes</span>”</span>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="platform-specific-plist"></a>15.7.�Platform-specific and differing PLISTs</h2></div></div></div>
-<p>Some packages decide to install a different set of files based on
- the operating system being used. These differences can be
- automatically handled by using the following files:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="filename">PLIST.common</code></p></li>
-<li class="listitem"><p><code class="filename">PLIST.${OPSYS}</code></p></li>
-<li class="listitem"><p><code class="filename">PLIST.${MACHINE_ARCH}</code></p></li>
-<li class="listitem"><p><code class="filename">PLIST.${OPSYS}-${MACHINE_ARCH}</code></p></li>
-<li class="listitem"><p><code class="filename">PLIST.common_end</code></p></li>
-</ul></div>
+<a name="build.build"></a>13.12.�The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
+<p>For building a package, a rough equivalent of the
+ following code is executed.</p>
+<pre class="programlisting">
+.for d in ${BUILD_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${MAKE_ENV} \
+ ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
+ -f ${MAKE_FILE} \
+ ${BUILD_TARGET}
+.endfor
+</pre>
+<p><code class="varname">BUILD_DIRS</code> (default:
+ <span class="quote">“<span class="quote">.</span>”</span>) is a list of pathnames relative to
+ <code class="varname">WRKSRC</code>. In each of these directories,
+ <code class="varname">MAKE_PROGRAM</code> is run with the environment
+ <code class="varname">MAKE_ENV</code> and arguments
+ <code class="varname">BUILD_MAKE_FLAGS</code>. The variables
+ <code class="varname">MAKE_ENV</code>,
+ <code class="varname">BUILD_MAKE_FLAGS</code>,
+ <code class="varname">MAKE_FILE</code> and
+ <code class="varname">BUILD_TARGET</code> may all be changed by the
+ package.</p>
+<p>The default value of <code class="varname">MAKE_PROGRAM</code> is
+ <span class="quote">“<span class="quote">gmake</span>”</span> if <code class="varname">USE_TOOLS</code> contains
+ <span class="quote">“<span class="quote">gmake</span>”</span>, <span class="quote">“<span class="quote">make</span>”</span> otherwise. The
+ default value of <code class="varname">MAKE_FILE</code> is
+ <span class="quote">“<span class="quote">Makefile</span>”</span>, and <code class="varname">BUILD_TARGET</code>
+ defaults to <span class="quote">“<span class="quote">all</span>”</span>.</p>
+<p>If there is no build step at all, set
+ <code class="varname">NO_BUILD</code> to <span class="quote">“<span class="quote">yes</span>”</span>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build-plist"></a>15.8.�Build-specific PLISTs</h2></div></div></div>
-<p>Some packages decide to generate hard-to-guess file names
- during installation that are hard to wire down.</p>
-<p>In such cases, you can set the
- <code class="varname">GENERATE_PLIST</code> variable to shell code
- terminated (with a semicolon) that will output PLIST entries which
- will be appended to the PLIST</p>
-<p>You can find one example in editors/xemacs:</p>
-<pre class="programlisting">
-GENERATE_PLIST+= ${ECHO} bin/${DISTNAME}-`${WRKSRC}/src/xemacs -sd`.dmp ;
-</pre>
-<p>which will append something like
- <code class="filename">bin/xemacs-21.4.23-54e8ea71.dmp</code> to the
- <code class="filename">PLIST</code>.
- </p>
+<a name="build.test"></a>13.13.�The <span class="emphasis"><em>test</em></span> phase</h2></div></div></div>
+<p>[TODO]</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="faq.common-dirs"></a>15.9.�Sharing directories between packages</h2></div></div></div>
-<p>A <span class="quote">“<span class="quote">shared directory</span>”</span> is a directory where
- multiple (and unrelated) packages install files. These
- directories were problematic because you had to add special
- tricks in the PLIST to conditionally remove them, or have some
- centralized package handle them.</p>
-<p>In pkgsrc, it is now easy: Each package should create
- directories and install files as needed; <span class="command"><strong>pkg_delete</strong></span>
- will remove any directories left empty after uninstalling a
- package.</p>
-<p>If a package needs an empty directory to work, create
- the directory during installation as usual, and also add an
- entry to the PLIST:
-
-</p>
+<a name="build.install"></a>13.14.�The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
+<p>Once the build stage has completed, the final step is to
+ install the software in public directories, so users can
+ access the programs and files.</p>
+<p>In the <span class="emphasis"><em>install</em></span> phase, a rough
+ equivalent of the following code is executed. Additionally,
+ before and after this code, much magic is performed to do
+ consistency checks, registering the package, and so on.</p>
<pre class="programlisting">
-@pkgdir path/to/empty/directory
+.for d in ${INSTALL_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${MAKE_ENV} \
+ ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
+ -f ${MAKE_FILE} \
+ ${INSTALL_TARGET}
+.endfor
</pre>
-<p>
-
- or take a look at <code class="varname">MAKE_DIRS</code> and
- <code class="varname">OWN_DIRS</code>.
- </p>
-</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="buildlink"></a>Chapter�16.�Buildlink methodology</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#converting-to-buildlink3">16.1. Converting packages to use buildlink3</a></span></dt>
-<dt><span class="sect1"><a href="#creating-buildlink3.mk">16.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-bl3">16.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
-<dt><span class="sect2"><a href="#updating-buildlink-depends">16.2.2. Updating
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- and
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- in <code class="filename">buildlink3.mk</code> files</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#writing-builtin.mk">16.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">16.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
-<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">16.3.2. Global preferences for native or pkgsrc software</a></span></dt>
-</dl></dd>
-</dl>
-</div>
-<p>Buildlink is a framework in pkgsrc that controls what headers and libraries
- are seen by a package's configure and build processes. This is implemented
- in a two step process:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>Symlink headers and libraries for dependencies into
- <code class="varname">BUILDLINK_DIR</code>, which by default is a subdirectory
- of <code class="varname">WRKDIR</code>.</p></li>
-<li class="listitem"><p>Create wrapper scripts that are used in place of the normal compiler
- tools that translate <code class="option">-I${LOCALBASE}/include</code> and
- <code class="option">-L${LOCALBASE}/lib</code> into references to
- <code class="varname">BUILDLINK_DIR</code>. The wrapper scripts also make
- native compiler on some operating systems look like GCC, so that
- packages that expect GCC won't require modifications to build with
- those native compilers.</p></li>
-</ol></div>
-<p>This normalizes the environment in which a package is built so that the
- package may be built consistently despite what other software may be
- installed. Please note that the normal system header and library paths,
- e.g. <code class="filename">/usr/include</code>,
- <code class="filename">/usr/lib</code>, etc., are always searched -- buildlink3 is
- designed to insulate the package build from non-system-supplied
- software.</p>
+<p>The variable's meanings are analogous to the ones in the
+ <span class="emphasis"><em>build</em></span> phase.
+ <code class="varname">INSTALL_DIRS</code> defaults to
+ <code class="varname">BUILD_DIRS</code>. <code class="varname">INSTALL_TARGET</code>
+ is <span class="quote">“<span class="quote">install</span>”</span> by default, plus
+ <span class="quote">“<span class="quote">install.man</span>”</span> if <code class="varname">USE_IMAKE</code> is
+ defined and <code class="varname">NO_INSTALL_MANPAGES</code> is not
+ defined.</p>
+<p>In the <span class="emphasis"><em>install</em></span> phase, the following
+ variables are useful. They are all variations of the
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?install+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a> command that
have the owner, group and
+ permissions preset. <code class="varname">INSTALL</code> is the plain
+ install command. The specialized variants, together with their
+ intended use, are:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">INSTALL_PROGRAM_DIR</code></span></dt>
+<dd><p>directories that contain
+ binaries</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_SCRIPT_DIR</code></span></dt>
+<dd><p>directories that contain
+ scripts</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_LIB_DIR</code></span></dt>
+<dd><p>directories that contain shared and static
+ libraries</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_DATA_DIR</code></span></dt>
+<dd><p>directories that contain data
+ files</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_MAN_DIR</code></span></dt>
+<dd><p>directories that contain man
+ pages</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_GAME_DIR</code></span></dt>
+<dd><p>directories that contain data files for games
+ </p></dd>
+<dt><span class="term"><code class="varname">INSTALL_PROGRAM</code></span></dt>
+<dd><p>binaries that can be stripped from debugging
+ symbols</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_SCRIPT</code></span></dt>
+<dd><p>binaries that cannot be
+ stripped</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_GAME</code></span></dt>
+<dd><p>game
+ binaries</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_LIB</code></span></dt>
+<dd><p>shared and static
+ libraries</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_DATA</code></span></dt>
+<dd><p>data files</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_GAME_DATA</code></span></dt>
+<dd><p>data files for
+ games</p></dd>
+<dt><span class="term"><code class="varname">INSTALL_MAN</code></span></dt>
+<dd><p>man pages</p></dd>
+</dl></div>
+<p>Some other variables are:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">INSTALL_UNSTRIPPED</code></span></dt>
+<dd><p>If set to <code class="literal">yes</code>, do not run <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?strip+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">strip</span>(1)</span></a>
+ when installing binaries. Any debugging sections and symbols present in
+ binaries will be preserved.
+ </p></dd>
+<dt><span class="term"><code class="varname">INSTALLATION_DIRS</code></span></dt>
+<dd><p>A list of directories relative to
+ <code class="varname">PREFIX</code> that are created by pkgsrc at the
+ beginning of the <span class="emphasis"><em>install</em></span> phase.
+ The package is supposed to create all needed directories itself
+ before installing files to it and list all other directories here.
+ </p></dd>
+</dl></div>
+<p>In the rare cases that a package shouldn't install anything,
+ set <code class="varname">NO_INSTALL</code> to <span class="quote">“<span class="quote">yes</span>”</span>. This is
+ mostly relevant for packages in the <code class="filename">regress</code>
+ category.</p>
+</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="converting-to-buildlink3"></a>16.1.�Converting packages to use buildlink3</h2></div></div></div>
-<p>The process of converting packages to use the buildlink3
- framework (<span class="quote">“<span class="quote">bl3ifying</span>”</span>) is fairly straightforward.
- The things to keep in mind are:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>Ensure that the build always calls the wrapper scripts
- instead of the actual toolchain. Some packages are tricky,
- and the only way to know for sure is the check
- <code class="filename">${WRKDIR}/.work.log</code> to see if the
- wrappers are being invoked.</p></li>
-<li class="listitem"><p>Don't override <code class="varname">PREFIX</code> from within
- the package Makefile, e.g. Java VMs, standalone shells,
- etc., because the code to symlink files into
- <code class="filename">${BUILDLINK_DIR}</code> looks for files
- relative to <span class="quote">“<span class="quote">pkg_info -qp <em class="replaceable"><code>pkgname</code></em></span>”</span>.
- </p></li>
-<li class="listitem"><p>Remember that <span class="emphasis"><em>only</em></span> the
- <code class="filename">buildlink3.mk</code> files that you list in a
- package's Makefile are added as dependencies for that package.
- </p></li>
-</ol></div>
-<p>If a dependency on a particular package is required for its libraries and
- headers, then we replace:</p>
-<pre class="programlisting">
-DEPENDS+= foo>=1.1.0:../../category/foo
-</pre>
-<p>with</p>
-<pre class="programlisting">
-.include "../../category/foo/buildlink3.mk"
-</pre>
-<p>The buildlink3.mk files usually define the required dependencies.
- If you need a newer version of the dependency when using buildlink3.mk
- files, then you can define it in your Makefile; for example:</p>
-<pre class="programlisting">
-BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0
-.include "../../category/foo/buildlink3.mk"
-</pre>
-<p>There are several <code class="filename">buildlink3.mk</code>
- files in <code class="filename">pkgsrc/mk</code>
- that handle special package issues:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="filename">bdb.buildlink3.mk</code> chooses either
- the native or a pkgsrc Berkeley DB implementation based on
- the values of <code class="varname">BDB_ACCEPTED</code> and
- <code class="varname">BDB_DEFAULT</code>.</p></li>
-<li class="listitem"><p><code class="filename">curses.buildlink3.mk</code>: If the system
- comes with neither Curses nor NCurses, this will take care
- to install the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/ncurses/README.html"; target="_top"><code class="filename">devel/ncurses</code></a> package.</p></li>
-<li class="listitem"><p><code class="filename">krb5.buildlink3.mk</code> uses the value
- of <code class="varname">KRB5_ACCEPTED</code> to choose between
- adding a dependency on Heimdal or MIT-krb5 for packages that
- require a Kerberos 5 implementation.</p></li>
-<li class="listitem"><p><code class="filename">motif.buildlink3.mk</code> checks for a
- system-provided Motif installation or adds a dependency on
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/lesstif/README.html"; target="_top"><code class="filename">x11/lesstif</code></a> or <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/motif/README.html"; target="_top"><code class="filename">x11/motif</code></a>. The user can set
- <code class="varname">MOTIF_TYPE</code> to <span class="quote">“<span class="quote">dt</span>”</span>,
- <span class="quote">“<span class="quote">lesstif</span>”</span> or <span class="quote">“<span class="quote">motif</span>”</span>
- to choose which Motif version will be used.</p></li>
-<li class="listitem"><p><code class="filename">readline.buildlink3.mk</code> checks for a
- system-provided GNU readline or editline (libedit) installation,
- or adds a dependency on <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/readline/README.html"; target="_top"><code class="filename">devel/readline</code></a>,
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/editline/README.html"; target="_top"><code class="filename">devel/editline</code></a>. The user can set
- <code class="varname">READLINE_DEFAULT</code> to choose readline implementation.
- If your package really needs GNU readline library, its Makefile
- should include <code class="filename">devel/readline/buildlink3.mk</code>
- instead of <code class="filename">readline.buildlink3.mk</code>.</p></li>
-<li class="listitem"><p><code class="filename">oss.buildlink3.mk</code> defines several
- variables that may be used by packages that use the
- Open Sound System (OSS) API.</p></li>
-<li class="listitem"><p><code class="filename">pgsql.buildlink3.mk</code> will accept
- any of the Postgres versions in the variable
- <code class="varname">PGSQL_VERSIONS_ACCEPTED</code> and default to
- the version <code class="varname">PGSQL_VERSION_DEFAULT</code>. See
- the file for more information.</p></li>
-<li class="listitem"><p><code class="filename">pthread.buildlink3.mk</code> uses the value of
- <code class="varname">PTHREAD_OPTS</code> and checks for native pthreads or adds
- a dependency on <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/pth/README.html"; target="_top"><code class="filename">devel/pth</code></a> as needed.</p></li>
-<li class="listitem"><p><code class="filename">xaw.buildlink3.mk</code> uses the value of
- <code class="varname">XAW_TYPE</code> to choose a particular Athena widgets
- library.</p></li>
-</ul></div>
-<p>The comments in those <code class="filename">buildlink3.mk</code>
- files provide a more complete
- description of how to use them properly.</p>
+<a name="build.package"></a>13.15.�The <span class="emphasis"><em>package</em></span> phase</h2></div></div></div>
+<p>Once the install stage has completed, a binary package of
+ the installed files can be built. These binary packages can be
+ used for quick installation without previous compilation, e.g. by
+ the <span class="command"><strong>make bin-install</strong></span> or by using
+ <span class="command"><strong>pkg_add</strong></span>.</p>
+<p>By default, the binary packages are created in
+ <code class="filename">${PACKAGES}/All</code> and symlinks are created in
+ <code class="filename">${PACKAGES}/<em class="replaceable"><code>category</code></em></code>,
+ one for each category in the <code class="varname">CATEGORIES</code>
+ variable. <code class="varname">PACKAGES</code> defaults to
+ <code class="filename">pkgsrc/packages</code>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="creating-buildlink3.mk"></a>16.2.�Writing <code class="filename">buildlink3.mk</code> files</h2></div></div></div>
-<a name="buildlink3.mk"></a><p>A package's <code class="filename">buildlink3.mk</code> file is
- included by Makefiles to indicate the need to compile and link
- against header files and libraries provided by the package. A
- <code class="filename">buildlink3.mk</code> file should always provide
- enough information to add the correct type of dependency
- relationship and include any other
- <code class="filename">buildlink3.mk</code> files that it needs to find
- headers and libraries that it needs in turn.</p>
-<p>To generate an initial <code class="filename">buildlink3.mk</code>
- file for further editing, Rene Hexel's <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/createbuildlink/README.html"; target="_top"><code
class="filename">pkgtools/createbuildlink</code></a>
- package is highly recommended. For most packages, the following
- command will generate a good starting point for
- <code class="filename">buildlink3.mk</code> files:</p>
-<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>
-<code class="prompt">%</code> createbuildlink >buildlink3.mk</code></strong>
- </pre>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="anatomy-of-bl3"></a>16.2.1.�Anatomy of a buildlink3.mk file</h3></div></div></div>
-<p>The following real-life example
- <code class="filename">buildlink3.mk</code> is taken
- from <code class="filename">pkgsrc/graphics/tiff</code>:</p>
-<pre class="programlisting">
-# $NetBSD: buildlink3.mk,v 1.16 2009/03/20 19:24:45 joerg Exp $
-
-BUILDLINK_TREE+= tiff
-
-.if !defined(TIFF_BUILDLINK3_MK)
-TIFF_BUILDLINK3_MK:=
-
-BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1
-BUILDLINK_ABI_DEPENDS.tiff+= tiff>=3.7.2nb1
-BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
-
-.include "../../devel/zlib/buildlink3.mk"
-.include "../../graphics/jpeg/buildlink3.mk"
-.endif # TIFF_BUILDLINK3_MK
-
-BUILDLINK_TREE+= -tiff
-</pre>
-<p>The header and footer manipulate
- <code class="varname">BUILDLINK_TREE</code>, which is common across all
- <code class="filename">buildlink3.mk</code> files and is used to track
- the dependency tree.</p>
-<p>The main section is protected from multiple inclusion
- and controls how the dependency on <em class="replaceable"><code>pkg</code></em> is
- added. Several important variables are set in the section:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- is the dependency version recorded in the installed
- package; this should always be set using
- <span class="command"><strong>+=</strong></span> to ensure that
- we're appending to any pre-existing list of values. This
- variable should be set to the last version of the
- package that had an backwards-incompatible API change.
- </p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_PKGSRCDIR.<em class="replaceable"><code>pkg</code></em></code>
- is the location of the <em class="replaceable"><code>pkg</code></em>
- pkgsrc directory.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) controls whether we use
- <code class="varname">BUILD_DEPENDS</code> or
- <code class="varname">DEPENDS</code> to add the dependency on
- <em class="replaceable"><code>pkg</code></em>. The build dependency is
- selected by setting
- <code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
- to <span class="quote">“<span class="quote">build</span>”</span>. By default, the full dependency is
- used.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code>
- and
- <code class="varname">BUILDLINK_LIBDIRS.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) are lists of subdirectories of
- <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
- to add to the header and library search paths. These
- default to <span class="quote">“<span class="quote">include</span>”</span> and <span class="quote">“<span class="quote">lib</span>”</span>
- respectively.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_CPPFLAGS.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) is the list of preprocessor flags to add
- to <code class="varname">CPPFLAGS</code>, which are passed on to the
- configure and build phases. The <span class="quote">“<span class="quote">-I</span>”</span> option
- should be avoided and instead be handled using
- <code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code> as
- above.</p></li>
-</ul></div>
-<p>The following variables are all optionally defined within
- this second section (protected against multiple inclusion) and
- control which package files are symlinked into
- <code class="filename">${BUILDLINK_DIR}</code> and how their names are
- transformed during the symlinking:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) is a shell glob pattern relative to
- <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
- to be symlinked into
- <code class="filename">${BUILDLINK_DIR}</code>,
- e.g. <code class="filename">include/*.h</code>.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_FILES_CMD.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) is a shell pipeline that
- outputs to stdout a list of files relative to
- <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>.
- The resulting files are to be symlinked
- into <code class="filename">${BUILDLINK_DIR}</code>. By default,
- this takes the <code class="filename">+CONTENTS</code> of a
- <em class="replaceable"><code>pkg</code></em> and filters it through
- <code class="varname">${BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em>}</code>.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) is a filter command that filters
- <code class="filename">+CONTENTS</code> input into a list of files
- relative to
- <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
- on stdout. By default,
- <code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
- outputs the contents of the <code class="filename">include</code>
- and <code class="filename">lib</code> directories in the package
- <code class="filename">+CONTENTS</code>.</p></li>
-<li class="listitem"><p><code class="varname">BUILDLINK_FNAME_TRANSFORM.<em class="replaceable"><code>pkg</code></em></code>
- (not shown above) is a list of sed arguments used to
- transform the name of the source filename into a
- destination filename, e.g. <span class="command"><strong>-e
- "s|/curses.h|/ncurses.h|g"</strong></span>.</p></li>
-</ul></div>
-<p>This section can additionally include any
- <code class="filename">buildlink3.mk</code> needed for
- <em class="replaceable"><code>pkg</code></em>'s library dependencies.
- Including these <code class="filename">buildlink3.mk</code> files
- means that the headers and libraries for these
- dependencies are also symlinked into
- <code class="filename">${BUILDLINK_DIR}</code>
- whenever the <em class="replaceable"><code>pkg</code></em>
- <code class="filename">buildlink3.mk</code>
- file is included. Dependencies are only added for directly
- include <code class="filename">buildlink3.mk</code> files.</p>
-<p>When providing a <code class="filename">buildlink3.mk</code> and
- including other <code class="filename">buildlink3.mk</code> files in it,
- please only add necessary ones, i.e., those whose libraries or
- header files are automatically exposed when the package is
- use.</p>
-<p>In particular, if only an executable
- (<code class="filename">bin/foo</code>) is linked against a library, that
- library does not need to be propagated in the
- <code class="filename">buildlink3.mk</code> file.</p>
-<p>The following steps should help you decide if a
- <code class="filename">buildlink3.mk</code> file needs to be included:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Look at the installed header files: What
- headers do they include? The packages providing these files
- must be buildlinked.</p></li>
-<li class="listitem"><p>Run <code class="filename">ldd</code> on all installed
- libraries and look against what other libraries they link.
- Some of the packages providing these probably need to be
- buildlinked; however, it's not automatic, since e.g. GTK on
- some systems pulls in the X libraries, so they will show up in
- the <code class="filename">ldd</code> output, while on others (like OS
- X) it won't. <code class="filename">ldd</code> output can thus only be
- used as a hint.</p></li>
-</ul></div>
-<p>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="updating-buildlink-depends"></a>16.2.2.�Updating
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- and
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- in <code class="filename">buildlink3.mk</code> files</h3></div></div></div>
-<p>Both variables set lower bounds for a version of this package.
- The two variables differ in that one describes source
- compatibility (API) and the other binary compatibility (ABI).
- The difference is that a change in the API breaks compilation of
- programs while changes in the ABI stop compiled programs from
- running.</p>
-<p>The
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- variable in a <code class="filename">buildlink3.mk</code> should be
- changed very rarely. (One possible scenario: If all packages
- using this package need a higher version than defined in the
- <code class="filename">buildlink3.mk</code>,
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- could be updated to that higher version.)</p>
-<p>On the other hand, changes to
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- are more common. The variable will need to be updated every
- time the major version of one of its shared libraries is changed,
- or any other change where a binary built against the previous
- version of the package will not run against the new version any
- longer.</p>
-<p>In such a case, the package's
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- must be increased to require the new package version. Then the
- <code class="varname">PKGREVISION</code> of all packages that depend on
- this package need to be increased, and if they have
- <code class="filename">buildlink3.mk</code> files, their
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- must be increased to the new version as well. This is required
- so that a package will pull in the versions of the packages that
- use the new ABI and that the packages'
- <code class="varname">PKGREVISION</code>s uniquely identify the packages
- built against the new ABI. The <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/revbump/README.html"; target="_top"><code class="filename">pkgtools/revbump</code></a> package
can help with
- these updates.</p>
-<p>See <a class="xref" href="#dependencies" title="21.1.5.�Handling dependencies">Section�21.1.5, “Handling dependencies”</a> for more information
- about dependencies on other packages, including the
- <code class="varname">BUILDLINK_API_DEPENDS</code> definitions.</p>
-<p>Please take careful consideration before adjusting
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- or
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- in a <code class="filename">buildlink3.mk</code> file as we don't want to
- cause unneeded package deletions and rebuilds. In many cases,
- new versions of packages work just fine with older
- dependencies.</p>
-<p>Also it is not needed to set
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- when it is identical to
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>. </p>
-</div>
+<a name="build.clean"></a>13.16.�Cleaning up</h2></div></div></div>
+<p>Once you're finished with a package, you can clean the work
+ directory by running <span class="command"><strong>make clean</strong></span>. If you want
+ to clean the work directories of all dependencies too, use
+ <span class="command"><strong>make clean-depends</strong></span>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="writing-builtin.mk"></a>16.3.�Writing <code class="filename">builtin.mk</code> files</h2></div></div></div>
-<p>Some packages in pkgsrc install headers and libraries that
- coincide with headers and libraries present in the base system.
- Aside from a <code class="filename">buildlink3.mk</code> file, these
- packages should also include a <code class="filename">builtin.mk</code>
- file that includes the necessary checks to decide whether using
- the built-in software or the pkgsrc software is
- appropriate.</p>
-<p>The only requirements of a builtin.mk file for
- <em class="replaceable"><code>pkg</code></em> are:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>It should set
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- to either <span class="quote">“<span class="quote">yes</span>”</span> or <span class="quote">“<span class="quote">no</span>”</span>
- after it is included.</p></li>
-<li class="listitem"><p>It should <span class="emphasis"><em>not</em></span> override any
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- which is already set before the
- <code class="filename">builtin.mk</code> file is included.</p></li>
-<li class="listitem"><p>It should be written to allow multiple inclusion. This
- is <span class="emphasis"><em>very</em></span> important and takes careful
- attention to <code class="filename">Makefile</code> coding.</p></li>
-</ol></div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="anatomy-of-builtin.mk"></a>16.3.1.�Anatomy of a <code class="filename">builtin.mk</code> file</h3></div></div></div>
-<p>The following is the recommended template for builtin.mk
- files:</p>
-<pre class="programlisting">
-.if !defined(IS_BUILTIN.foo)
-#
-# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
-# genuinely exists in the system or not.
-#
-IS_BUILTIN.foo?= no
-
-# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
-# version can be determined.
-#
-. if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
-BUILTIN_PKG.foo?= foo-1.0
-. endif
-.endif # IS_BUILTIN.foo
-
-.if !defined(USE_BUILTIN.foo)
-USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
-. if defined(BUILTIN_PKG.foo)
-. for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
-. if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
-USE_BUILTIN.foo!= \
- ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo} \
- && ${ECHO} "yes" || ${ECHO} "no"
-. endif
-. endfor
-. endif
-.endif # USE_BUILTIN.foo
-
-CHECK_BUILTIN.foo?= no
-.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
-#
-# Here we place code that depends on whether USE_BUILTIN.foo is set to
-# "yes" or "no".
-#
-.endif # CHECK_BUILTIN.foo
-</pre>
-<p>The first section sets
- <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- depending on if <em class="replaceable"><code>pkg</code></em> really exists
- in the base system. This should not be a base system software
- with similar functionality to <em class="replaceable"><code>pkg</code></em>;
- it should only be <span class="quote">“<span class="quote">yes</span>”</span> if the actual package is
- included as part of the base system. This variable is only
- used internally within the <code class="filename">builtin.mk</code>
- file.</p>
-<p>The second section sets
- <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
- to the version of <em class="replaceable"><code>pkg</code></em> in the base
- system if it exists (if
- <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- is <span class="quote">“<span class="quote">yes</span>”</span>). This variable is only used internally
- within the <code class="filename">builtin.mk</code> file.</p>
-<p>The third section sets
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- and is <span class="emphasis"><em>required</em></span> in all
- <code class="filename">builtin.mk</code> files. The code in this
- section must make the determination whether the built-in
- software is adequate to satisfy the dependencies listed in
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
- This is typically done by comparing
- <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
- against each of the dependencies in
- <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- <span class="emphasis"><em>must</em></span> be set to the correct value by the
- end of the <code class="filename">builtin.mk</code> file. Note that
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- may be <span class="quote">“<span class="quote">yes</span>”</span> even if
- <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- is <span class="quote">“<span class="quote">no</span>”</span> because we may make the determination
- that the built-in version of the software is similar enough to
- be used as a replacement.</p>
-<p>The last section is guarded by
- <code class="varname">CHECK_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>,
- and includes code that uses the value of
- <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
- set in the previous section. This typically includes, e.g.,
- adding additional dependency restrictions and listing additional
- files to symlink into <code class="filename">${BUILDLINK_DIR}</code> (via
- <code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>).</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="native-or-pkgsrc-preference"></a>16.3.2.�Global preferences for native or pkgsrc software</h3></div></div></div>
-<p>When building packages, it's possible to choose whether to set
- a global preference for using either the built-in (native)
- version or the pkgsrc version of software to satisfy a
- dependency. This is controlled by setting
- <code class="varname">PREFER_PKGSRC</code> and
- <code class="varname">PREFER_NATIVE</code>. These variables take values
- of either <span class="quote">“<span class="quote">yes</span>”</span>, <span class="quote">“<span class="quote">no</span>”</span>, or a list of
- packages. <code class="varname">PREFER_PKGSRC</code> tells pkgsrc to
- use the pkgsrc versions of software, while
- <code class="varname">PREFER_NATIVE</code> tells pkgsrc to use the
- built-in versions. Preferences are determined by the most
- specific instance of the package in either
- <code class="varname">PREFER_PKGSRC</code> or
- <code class="varname">PREFER_NATIVE</code>. If a package is specified
- in neither or in both variables, then
- <code class="varname">PREFER_PKGSRC</code> has precedence over
- <code class="varname">PREFER_NATIVE</code>. For example, to require
- using pkgsrc versions of software for all but the most basic
- bits on a NetBSD system, you can set:</p>
-<pre class="programlisting">
-PREFER_PKGSRC= yes
-PREFER_NATIVE= getopt skey tcp_wrappers
-</pre>
-<p>A package <span class="emphasis"><em>must</em></span> have a
- <code class="filename">builtin.mk</code>
- file to be listed in <code class="varname">PREFER_NATIVE</code>,
- otherwise it is simply ignored in that list.</p>
-<p>Setting <code class="varname">PREFER_NATIVE</code> should be performed
- straight after bootstrap and <code class="varname">PREFER_PKGSRC</code> during
- bootstrap.
- Switching between settings globally at a later date can introduce
- complications with dependency resolution. This is caused by packages
- built with the opposite preference being installed alongside each other.</p>
+<a name="build.helpful-targets"></a>13.17.�Other helpful targets</h2></div></div></div>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term">pre/post-*</span></dt>
+<dd>
+<p>For any of the main targets described in the previous
+ section (configure, build, install, etc.), two auxiliary
+ targets exist with
+ <span class="quote">“<span class="quote">pre-</span>”</span> and <span class="quote">“<span class="quote">post-</span>”</span> used as a
+ prefix for the main target's name. These targets are
+ invoked before and after the main target is called,
+ allowing extra configuration or installation steps be
+ performed from a package's Makefile, for example, which
+ a program's configure script or install target
+ omitted.</p>
+<p>About 5% of the pkgsrc packages define their custom
+ post-extract target, another 5% define pre-configure, and 10%
+ define post-install. The other pre/post-* targets are defined
+ even less often.</p>
+</dd>
+<dt><span class="term">do-*</span></dt>
+<dd>
+<p>Should one of the main targets do the wrong thing,
+ and should there be no variable to fix this, you can
+ redefine it with the do-* target. (Note that redefining
+ the target itself instead of the do-* target is a bad
+ idea, as the pre-* and post-* targets won't be called
+ anymore, etc.)</p>
+<p>About 15% of the pkgsrc packages override the default
+ do-install, the other do-* targets are overridden even less
+ often.</p>
+</dd>
+<dt><span class="term">reinstall</span></dt>
+<dd>
+<p>If you did a <span class="command"><strong>make install</strong></span> and
+ you noticed some file was not installed properly, you
+ can repeat the installation with this target, which will
+ ignore the <span class="quote">“<span class="quote">already installed</span>”</span> flag.</p>
+<p>This is the default value of
+ <code class="varname">DEPENDS_TARGET</code> except in the case of
+ <span class="command"><strong>make update</strong></span> and <span class="command"><strong>make
+ package</strong></span>, where the defaults are
+ <span class="quote">“<span class="quote">package</span>”</span> and <span class="quote">“<span class="quote">update</span>”</span>,
+ respectively.</p>
+</dd>
+<dt><span class="term">deinstall</span></dt>
+<dd>
+<p>This target does a <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_delete</span>(1)</span></a> in the
+ current directory, effectively de-installing the
+ package. The following variables can be used to tune the
+ behaviour:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">PKG_VERBOSE</code></span></dt>
+<dd><p>Add a "-v" to the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_delete</span>(1)</span></a> command.</p></dd>
+<dt><span class="term"><code class="varname">DEINSTALLDEPENDS</code></span></dt>
+<dd><p>Remove all packages that require (depend on)
+ the given package. This can be used to remove any
+ packages that may have been pulled in by a given
+ package, e.g. if <span class="command"><strong>make deinstall
+ DEINSTALLDEPENDS=1</strong></span> is done in
+ <code class="filename">pkgsrc/x11/kde</code>, this is
+ likely to remove whole KDE. Works by adding
+ <span class="quote">“<span class="quote">-R</span>”</span> to the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span
class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a>
+ command line.</p></dd>
+</dl></div>
+</dd>
+<dt><span class="term">bin-install</span></dt>
+<dd><p>Install a binary package from local disk and via FTP
+ from a list of sites (see the
+ <code class="varname">BINPKG_SITES</code> variable), and do a
+ <span class="command"><strong>make package</strong></span> if no binary package is
+ available anywhere. The arguments given to
+ <span class="command"><strong>pkg_add</strong></span> can be set via
+ <code class="varname">BIN_INSTALL_FLAGS</code> e.g., to do verbose
+ operation, etc.</p></dd>
+<dt><span class="term">install-clean</span></dt>
+<dd><p>This target removes the state files for the "install" and later
+ phases so that the "install" target may be re-invoked. This can be
+ used after editing the PLIST to install the package without
+ rebuilding it.</p></dd>
+<dt><span class="term">build-clean</span></dt>
+<dd><p>This target removes the state files for the "build" and later
+ phases so that the "build" target may be re-invoked.</p></dd>
+<dt><span class="term">update</span></dt>
+<dd>
+<p>This target causes the current package to be
+ updated to the latest version. The package and all
+ depending packages first get de-installed, then current
+ versions of the corresponding packages get compiled and
+ installed. This is similar to manually noting which
+ packages are currently installed, then performing a
+ series of <span class="command"><strong>make deinstall</strong></span> and
+ <span class="command"><strong>make install</strong></span> (or whatever
+ <code class="varname">UPDATE_TARGET</code> is set to) for these
+ packages.</p>
+<p>You can use the <span class="quote">“<span class="quote">update</span>”</span> target to
+ resume package updating in case a previous <span class="command"><strong>make
+ update</strong></span> was interrupted for some reason.
+ However, in this case, make sure you don't call
+ <span class="command"><strong>make clean</strong></span> or otherwise remove the
+ list of dependent packages in <code class="varname">WRKDIR</code>.
+ Otherwise, you lose the ability to automatically update
+ the current package along with the dependent packages
+ you have installed.</p>
+<p>Resuming an interrupted <span class="command"><strong>make
+ update</strong></span> will only work as long as the package
+ tree remains unchanged. If the source code for one of
+ the packages to be updated has been changed, resuming
+ <span class="command"><strong>make update</strong></span> will most certainly
+ fail!</p>
+<p>The following variables can be used either on the
+ command line or in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> to
+ alter the behaviour of <span class="command"><strong>make
+ update</strong></span>:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">UPDATE_TARGET</code></span></dt>
+<dd><p>Install target to recursively use for the
+ updated package and the dependent packages.
+ Defaults to <code class="varname">DEPENDS_TARGET</code> if
+ set, <span class="quote">“<span class="quote">install</span>”</span> otherwise for
+ <span class="command"><strong>make update</strong></span>. Other good
+ targets are <span class="quote">“<span class="quote">package</span>”</span> or
+ <span class="quote">“<span class="quote">bin-install</span>”</span>. Do not set this to
+ <span class="quote">“<span class="quote">update</span>”</span> or you will get stuck in an
+ endless loop!</p></dd>
+<dt><span class="term"><code class="varname">NOCLEAN</code></span></dt>
+<dd><p>Don't clean up after updating. Useful if
+ you want to leave the work sources of the updated
+ packages around for inspection or other purposes.
+ Be sure you eventually clean up the source tree
+ (see the <span class="quote">“<span class="quote">clean-update</span>”</span> target below)
+ or you may run into troubles with old source code
+ still lying around on your next
+ <span class="command"><strong>make</strong></span> or <span class="command"><strong>make
+ update</strong></span>.</p></dd>
+<dt><span class="term"><code class="varname">REINSTALL</code></span></dt>
+<dd><p>Deinstall each package before installing
+ (making <code class="varname">DEPENDS_TARGET</code>). This
+ may be necessary if the
+ <span class="quote">“<span class="quote">clean-update</span>”</span> target (see below) was
+ called after interrupting a running <span class="command"><strong>make
+ update</strong></span>.</p></dd>
+<dt><span class="term"><code class="varname">DEPENDS_TARGET</code></span></dt>
+<dd><p>Allows you to disable recursion and hardcode
+ the target for packages. The default is
+ <span class="quote">“<span class="quote">update</span>”</span> for the update target,
+ facilitating a recursive update of prerequisite
+ packages. Only set
+ <code class="varname">DEPENDS_TARGET</code> if you want to
+ disable recursive updates. Use
+ <code class="varname">UPDATE_TARGET</code> instead to just
+ set a specific target for each package to be
+ installed during <span class="command"><strong>make update</strong></span>
+ (see above).</p></dd>
+</dl></div>
+</dd>
+<dt><span class="term">clean-update</span></dt>
+<dd>
+<p>Clean the source tree for all packages that would
+ get updated if <span class="command"><strong>make update</strong></span> was called
+ from the current directory. This target should not be
+ used if the current package (or any of its depending
+ packages) have already been de-installed (e.g., after
+ calling <span class="command"><strong>make update</strong></span>) or you may lose
+ some packages you intended to update. As a rule of
+ thumb: only use this target <span class="emphasis"><em>before</em></span>
+ the first time you run <span class="command"><strong>make update</strong></span>
+ and only if you have a dirty package tree (e.g., if you
+ used <code class="varname">NOCLEAN</code>).</p>
+<p>If you are unsure about whether your tree is
+ clean, you can either perform a <span class="command"><strong>make
+ clean</strong></span> at the top of the tree, or use the
+ following sequence of commands from the directory of the
+ package you want to update (<span class="emphasis"><em>before</em></span>
+ running <span class="command"><strong>make update</strong></span> for the first
+ time, otherwise you lose all the packages you wanted to
+ update!):</p>
<pre class="screen">
-<code class="prompt">#</code> <strong class="userinput"><code>./bootstrap --prefer-pkgsrc yes</code></strong>
-</pre>
-</div>
+<code class="prompt">#</code> <strong class="userinput"><code>make clean-update</code></strong>
+<code class="prompt">#</code> <strong class="userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
+<code class="prompt">#</code> <strong class="userinput"><code>make update</code></strong>
+ </pre>
+<p>The following variables can be used either on the
+ command line or in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> to alter the behaviour of
+ <span class="command"><strong>make clean-update</strong></span>:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">CLEAR_DIRLIST</code></span></dt>
+<dd><p>After <span class="command"><strong>make clean</strong></span>, do not
+ reconstruct the list of directories to update for
+ this package. Only use this if <span class="command"><strong>make
+ update</strong></span> successfully installed all
+ packages you wanted to update. Normally, this is
+ done automatically on <span class="command"><strong>make
+ update</strong></span>, but may have been suppressed by
+ the <code class="varname">NOCLEAN</code> variable (see
+ above).</p></dd>
+</dl></div>
+</dd>
+<dt><span class="term">replace</span></dt>
+<dd>
+<p>Update the installation of the current package. This
+ differs from update in that it does not replace dependent
+ packages. You will need to install <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_tarup/README.html"; target="_top"><code
class="filename">pkgtools/pkg_tarup</code></a> for this
+ target to work.</p>
+<p><span class="emphasis"><em>Be careful when using this
+ target!</em></span> There are no guarantees that dependent
+ packages will still work, in particular they will most
+ certainly break if you <span class="command"><strong>make replace</strong></span> a
+ library package whose shared library major version changed
+ between your installed version and the new one. For this
+ reason, this target is not officially supported and only
+ recommended for advanced users.</p>
+</dd>
+<dt><span class="term">info</span></dt>
+<dd><p>This target invokes <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_info</span>(1)</span></a> for the current
+ package. You can use this to check which version of a
+ package is installed.</p></dd>
+<dt><span class="term">index</span></dt>
+<dd>
+<p>This is a top-level command, i.e. it should be used in
+ the <code class="filename">pkgsrc</code> directory. It creates a
+ database of all packages in the local pkgsrc tree, including
+ dependencies, comment, maintainer, and some other useful
+ information. Individual entries are created by running
+ <span class="command"><strong>make describe</strong></span> in the packages'
+ directories. This index file is saved as
+ <code class="filename">pkgsrc/INDEX</code>. It can be displayed in
+ verbose format by running <span class="command"><strong>make
+ print-index</strong></span>. You can search in it with
+ <span class="command"><strong>make search
+ key=<em class="replaceable"><code>something</code></em></strong></span>. You can
+ extract a list of all packages that depend on a particular
+ one by running <span class="command"><strong>make show-deps
+ PKG=<em class="replaceable"><code>somepackage</code></em></strong></span>.</p>
+<p>Running this command takes a very long time, some
+ hours even on fast machines!</p>
+</dd>
+<dt><span class="term">readme</span></dt>
+<dd>
+<p>This target generates a
+ <code class="filename">README.html</code> file, which can be
+ viewed using a browser such as <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a> or <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/links/README.html"; target="_top"><code class="filename">www/links</code></a>. The generated files
+ contain references to any packages which are in the
+ <code class="varname">PACKAGES</code> directory on the local
+ host. The generated files can be made to refer to URLs
+ based on <code class="varname">FTP_PKG_URL_HOST</code> and
+ <code class="varname">FTP_PKG_URL_DIR</code>. For example, if I
+ wanted to generate <code class="filename">README.html</code>
+ files which pointed to binary packages on the local
+ machine, in the directory
+ <code class="filename">/usr/packages</code>, set
+ <code class="varname">FTP_PKG_URL_HOST=file://localhost</code> and
+ <code class="varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
+ <code class="varname">${PACKAGES}</code> directory and its
+ subdirectories will be searched for all the binary
+ packages.</p>
+<p>The target can be run at the toplevel or in category
+ directories, in which case it descends recursively.</p>
+</dd>
+<dt><span class="term">readme-all</span></dt>
+<dd><p>This is a top-level command, run it in
+ <code class="filename">pkgsrc</code>. Use this target to create a
+ file <code class="filename">README-all.html</code> which contains a
+ list of all packages currently available in the NetBSD
+ Packages Collection, together with the category they belong
+ to and a short description. This file is compiled from the
+ <code class="filename">pkgsrc/*/README.html</code> files, so be sure
+ to run this <span class="emphasis"><em>after</em></span> a <span class="command"><strong>make
+ readme</strong></span>.</p></dd>
+<dt><span class="term">cdrom-readme</span></dt>
+<dd><p>This is very much the same as the
+ <span class="quote">“<span class="quote">readme</span>”</span> target (see above), but is to be
+ used when generating a pkgsrc tree to be written to a
+ CD-ROM. This target also produces
+ <code class="filename">README.html</code> files, and can be made
+ to refer to URLs based on
+ <code class="varname">CDROM_PKG_URL_HOST</code> and
+ <code class="varname">CDROM_PKG_URL_DIR</code>.</p></dd>
+<dt><span class="term">show-distfiles</span></dt>
+<dd><p>This target shows which distfiles and patchfiles
+ are needed to build the package
+ (<code class="varname">ALLFILES</code>, which contains all
+ <code class="varname">DISTFILES</code> and
+ <code class="varname">PATCHFILES</code>, but not
+ <code class="filename">patches/*</code>).</p></dd>
+<dt><span class="term">show-downlevel</span></dt>
+<dd><p>This target shows nothing if the package is not
+ installed. If a version of this package is installed,
+ but is not the version provided in this version of
+ pkgsrc, then a warning message is displayed. This target
+ can be used to show which of your installed packages are
+ downlevel, and so the old versions can be deleted, and
+ the current ones added.</p></dd>
+<dt><span class="term">show-pkgsrc-dir</span></dt>
+<dd><p>This target shows the directory in the pkgsrc
+ hierarchy from which the package can be built and
+ installed. This may not be the same directory as the one
+ from which the package was installed. This target is
+ intended to be used by people who may wish to upgrade
+ many packages on a single host, and can be invoked from
+ the top-level pkgsrc Makefile by using the
+ <span class="quote">“<span class="quote">show-host-specific-pkgs</span>”</span> target.</p></dd>
+<dt><span class="term">show-installed-depends</span></dt>
+<dd><p>This target shows which installed packages match
+ the current package's <code class="varname">DEPENDS</code>. Useful
+ if out of date dependencies are causing build
+ problems.</p></dd>
+<dt><span class="term">print-build-depends-list</span></dt>
+<dd><p>This target shows the list of packages that the current package
+ depends on for building.</p></dd>
+<dt><span class="term">print-run-depends-list</span></dt>
+<dd><p>This target shows the list of packages that the current package
+ depends on for running.</p></dd>
+<dt><span class="term">check-shlibs</span></dt>
+<dd><p>After a package is installed, check all its
+ binaries and (on ELF platforms) shared libraries to see
+ if they find the shared libs they need. Run by default
+ if <code class="varname">PKG_DEVELOPER</code> is set in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p></dd>
+<dt><span class="term">print-PLIST</span></dt>
+<dd>
+<p>After a <span class="quote">“<span class="quote">make install</span>”</span> from a new or
+ upgraded pkg, this prints out an attempt to generate a
+ new <code class="filename">PLIST</code> from a <span class="command"><strong>find
+ -newer work/.extract_done</strong></span>. An attempt is made
+ to care for shared libs etc., but it is
+ <span class="emphasis"><em>strongly</em></span> recommended to review the
+ result before putting it into
+ <code class="filename">PLIST</code>. On upgrades, it's useful to
+ diff the output of this command against an already
+ existing <code class="filename">PLIST</code> file.</p>
+<p>If the package installs files via <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?tar+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">tar</span>(1)</span></a> or
+ other methods that don't update file access times, be
+ sure to add these files manually to your
+ <code class="filename">PLIST</code>, as the <span class="quote">“<span class="quote">find
+ -newer</span>”</span> command used by this target won't catch
+ them!</p>
+<p>See <a class="xref" href="#print-PLIST" title="19.3.�Tweaking output of make print-PLIST">Section�19.3, “Tweaking output of <span class="command"><strong>make
print-PLIST</strong></span>”</a> for more
+ information on this target.</p>
+</dd>
+</dl></div>
</div>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="pkginstall"></a>Chapter�17.�The pkginstall framework</h2></div></div></div>
+<a name="creating"></a>Chapter�14.�Creating a new pkgsrc package from scratch</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">17.1. Files and directories outside the installation prefix</a></span></dt>
+<dt><span class="sect1"><a href="#creating.common">14.1. Common types of packages</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#dirs-outside-prefix">17.1.1. Directory manipulation</a></span></dt>
-<dt><span class="sect2"><a href="#files-outside-prefix">17.1.2. File manipulation</a></span></dt>
+<dt><span class="sect2"><a href="#creating.perl-module">14.1.1. Perl modules</a></span></dt>
+<dt><span class="sect2"><a href="#creating.python-module">14.1.2. Python modules and programs</a></span></dt>
+<dt><span class="sect2"><a href="#creating.R-package">14.1.3. R packages</a></span></dt>
+<dt><span class="sect2"><a href="#creating.TeX-package">14.1.4. TeXlive packages</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#conf-files">17.2. Configuration files</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#conf-files-sysconfdir">17.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-configure">17.2.2. Telling the software where configuration files are</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-patching">17.2.3. Patching installations</a></span></dt>
-<dt><span class="sect2"><a href="#conf-files-disable">17.2.4. Disabling handling of configuration files</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#rcd-scripts">17.3. System startup scripts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">17.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#users-and-groups">17.4. System users and groups</a></span></dt>
-<dt><span class="sect1"><a href="#shells">17.5. System shells</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#shells-disable">17.5.1. Disabling shell registration</a></span></dt></dl></dd>
-<dt><span class="sect1"><a href="#fonts">17.6. Fonts</a></span></dt>
-<dd><dl><dt><span class="sect2"><a href="#fonts-disable">17.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#creating.examples">14.2. Examples</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#creating.nvu">14.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
</dl>
</div>
-<p>This chapter describes the framework known as
-<code class="literal">pkginstall</code>, whose key features are:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Generic installation and manipulation of directories and files
- outside the pkgsrc-handled tree, <code class="varname">LOCALBASE</code>.</p></li>
-<li class="listitem"><p>Automatic handling of configuration files during installation,
- provided that packages are correctly designed.</p></li>
-<li class="listitem"><p>Generation and installation of system startup scripts.</p></li>
-<li class="listitem"><p>Registration of system users and groups.</p></li>
-<li class="listitem"><p>Registration of system shells.</p></li>
-<li class="listitem"><p>Automatic updating of fonts databases.</p></li>
-</ul></div>
-<p>The following sections inspect each of the above points in detail.</p>
-<p>You may be thinking that many of the things described here could be
-easily done with simple code in the package's post-installation target
-(<code class="literal">post-install</code>). <span class="emphasis"><em>This is incorrect</em></span>,
-as the code in them is only executed when building from source. Machines
-using binary packages could not benefit from it at all (as the code itself
-could be unavailable). Therefore, the only way to achieve any of the items
-described above is by means of the installation scripts, which are
-automatically generated by pkginstall.</p>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="files-and-dirs-outside-prefix"></a>17.1.�Files and directories outside the installation prefix</h2></div></div></div>
-<p>As you already know, the <code class="filename">PLIST</code> file holds a list
-of files and directories that belong to a package. The names used in it
-are relative to the installation prefix (<code class="filename">${PREFIX}</code>),
-which means that it cannot register files outside this directory (absolute
-path names are not allowed). Despite this restriction, some packages need
-to install files outside this location; e.g., under
-<code class="filename">${VARBASE}</code> or
-<code class="filename">${PKG_SYSCONFDIR}</code>. The only way to achieve this
-is to create such files during installation time by using
-installation scripts.</p>
-<p>The generic installation scripts are shell scripts that can
-contain arbitrary code. The list of scripts to execute is taken from
-the <code class="varname">INSTALL_FILE</code> variable, which defaults to
-<code class="filename">INSTALL</code>. A similar variable exists for package
-removal (<code class="varname">DEINSTALL_FILE</code>, whose default is
-<code class="filename">DEINSTALL</code>). These scripts can run arbitrary
-commands, so they have the potential to create and manage files
-anywhere in the file system.</p>
-<p>Using these general installation files is not recommended, but
-may be needed in some special cases. One reason for avoiding them is
-that the user has to trust the packager that there is no unwanted or
-simply erroneous code included in the installation script. Also,
-previously there were many similar scripts for the same functionality,
-and fixing a common error involved finding and changing all of
-them.</p>
-<p>The pkginstall framework offers another, standardized way. It
-provides generic scripts to abstract the manipulation of such files
-and directories based on variables set in the package's
-<code class="filename">Makefile</code>. The rest of this section describes
-these variables.</p>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="dirs-outside-prefix"></a>17.1.1.�Directory manipulation</h3></div></div></div>
-<p>The following variables can be set to request the creation of
-directories anywhere in the file system:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
-<p><code class="varname">MAKE_DIRS</code> and <code class="varname">OWN_DIRS</code>
- contain a list of directories that should be created and should attempt
- to be destroyed by the installation scripts. The difference between
- the two is that the latter prompts the administrator to remove any
- directories that may be left after deinstallation (because they were
- not empty), while the former does not. Example:</p>
-<pre class="programlisting">
-MAKE_DIRS+= ${VARBASE}/foo/private
-</pre>
+<p>When you find a package that is not yet in pkgsrc, you
+most likely have a URL from where you can download the source
+code. Starting with this URL, creating a package involves only a
+few steps.</p>
+<div class="procedure"><ol class="procedure" type="1">
+<li class="step"><p>In your <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>, set <code class="code">PKG_DEVELOPER=yes</code> to
+enable the basic quality checks.</p></li>
+<li class="step">
+<p>Install the package <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/pkg_developer/README.html"; target="_top"><code class="filename">meta-pkgs/pkg_developer</code></a>, which
among others will
+install the utilities <span class="command"><strong>url2pkg</strong></span>,
+<span class="command"><strong>pkglint</strong></span>, <span class="command"><strong>pkgvi</strong></span> and
+<span class="command"><strong>mkpatches</strong></span>:</p>
+<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>(cd meta-pkgs/pkg_developer && bmake update)</code></strong></pre>
</li>
-<li class="listitem">
-<p><code class="varname">MAKE_DIRS_PERMS</code> and
- <code class="varname">OWN_DIRS_PERMS</code> contain a list of tuples describing
- which directories should be created and should attempt to be destroyed
- by the installation scripts. Each tuple holds the following values,
- separated by spaces: the directory name, its owner, its group and its
- numerical mode. For example:</p>
-<pre class="programlisting">
-MAKE_DIRS_PERMS+= ${VARBASE}/foo/private \
- ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
-</pre>
-<p>The difference between the two is exactly the same as their
- non-<code class="varname">PERMS</code> counterparts.</p>
+<li class="step">
+<p>Choose one of the top-level directories as the category in
+which you want to place your package. You can also create a directory of
+your own (maybe called <code class="filename">local</code>). In that category
+directory, create another directory for your package and change into
+it:</p>
+<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>mkdir <em class="replaceable"><code>category</code></em>/<em
class="replaceable"><code>package</code></em></code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>cd <em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>package</code></em></code></strong></pre>
</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="files-outside-prefix"></a>17.1.2.�File manipulation</h3></div></div></div>
-<p>Creating non-empty files outside the installation prefix is tricky
-because the <code class="filename">PLIST</code> forces all files to be inside it.
-To overcome this problem, the only solution is to extract the file in the
-known place (i.e., inside the installation prefix) and copy it to the
-appropriate location during installation (done by the installation scripts
-generated by pkginstall). We will call the former the <span class="emphasis"><em>master
-file</em></span> in the following paragraphs, which describe the variables
-that can be used to automatically and consistently handle files outside the
-installation prefix:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
-<p><code class="varname">CONF_FILES</code> and
- <code class="varname">REQD_FILES</code> are pairs of master and target files.
- During installation time, the master file is copied to the target one
- if and only if the latter does not exist. Upon deinstallation, the
- target file is removed provided that it was not modified by the
- installation.</p>
-<p>The difference between the two is that the latter prompts the
- administrator to remove any files that may be left after
- deinstallation (because they were not empty), while the former does
- not.</p>
+<li class="step">
+<p>Run the program <span class="command"><strong>url2pkg</strong></span>, which will ask
+you for a URL. Enter the URL of the distribution file (in most cases a
+<code class="filename">.tar.gz</code> file) and watch how the basic ingredients
+of your package are created automatically. The distribution file is
+extracted automatically to fill in some details in the
+<code class="filename">Makefile</code> that would otherwise have to be done
+manually:</p>
+<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>url2pkg <em
class="replaceable"><code>https://www.example.org/packages/package-1.0.tar.gz</code></em></code></strong></pre>
</li>
-<li class="listitem">
-<p><code class="varname">CONF_FILES_PERMS</code> and
- <code class="varname">REQD_FILES_PERMS</code> contain tuples describing master
- files as well as their target locations. For each of them, it also
- specifies their owner, their group and their numeric permissions, in
- this order. For example:</p>
+<li class="step">
+<p>Examine the extracted files to determine the dependencies of
+your package. Ideally, this is mentioned in some
+<code class="filename">README</code> file, but things may differ. For each of
+these dependencies, look where it exists in pkgsrc, and if there is a
+file called <code class="filename">buildlink3.mk</code> in that directory, add a
+line to your package <code class="filename">Makefile</code> which includes that
+file just before the last line. If the
+<code class="filename">buildlink3.mk</code> file does not exist, it must be
+created first. The <code class="filename">buildlink3.mk</code> file makes sure
+that the package's include files and libraries are provided.</p>
+<p>If you just need binaries from a package, add a
+<code class="varname">DEPENDS</code> line to the Makefile, which specifies the
+version of the dependency and where it can be found in pkgsrc. This line
+should be placed in the third paragraph. If the dependency is only
+needed for building the package, but not when using it, use
+<code class="varname">TOOL_DEPENDS</code> or <code class="varname">BUILD_DEPENDS</code>
+instead of <code class="varname">DEPENDS</code>.
+The difference between <code class="varname">TOOL_DEPENDS</code> and
+<code class="varname">BUILD_DEPENDS</code> occurs when cross-compiling:
+<code class="varname">TOOL_DEPENDS</code> are <span class="emphasis"><em>native</em></span>
+packages, i.e. packages for the architecture where the package
+is built;
+<code class="varname">BUILD_DEPENDS</code> are <span class="emphasis"><em>target</em></span>
+packages, i.e. packages for the architecture for which the package
+is built. There is also <code class="varname">TEST_DEPENDS</code>, which is used
+to specify a dependency used only for testing the resulting package
+built, using the upstream project's included test suite.
+Your package may then look like this:</p>
<pre class="programlisting">
-REQD_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile \
- ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
-</pre>
-<p>The difference between the two is exactly the same as their
- non-<code class="varname">PERMS</code> counterparts.</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="conf-files"></a>17.2.�Configuration files</h2></div></div></div>
-<p>Configuration files are special in the sense that they are installed
-in their own specific directory, <code class="varname">PKG_SYSCONFDIR</code>, and
-need special treatment during installation (most of which is automated by
-pkginstall). The main concept you must bear in mind is that files marked
-as configuration files are automatically copied to the right place (somewhere
-inside <code class="varname">PKG_SYSCONFDIR</code>) during installation <span class="emphasis"><em>if
-and only if</em></span> they didn't exist before. Similarly, they will not
-be removed if they have local modifications. This ensures that
-administrators never lose any custom changes they may have made.</p>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="conf-files-sysconfdir"></a>17.2.1.�How <code class="varname">PKG_SYSCONFDIR</code> is set</h3></div></div></div>
-<p>As said before, the <code class="varname">PKG_SYSCONFDIR</code> variable
-specifies where configuration files shall be installed. Its contents are
-set based upon the following variables:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">PKG_SYSCONFBASE</code>: The configuration's root
- directory. Defaults to <code class="filename">${PREFIX}/etc</code> although it may
- be overridden by the user to point to his preferred location (e.g.,
- <code class="filename">/etc</code>, <code class="filename">/etc/pkg</code>, etc.).
- Packages must not use it directly.</p></li>
-<li class="listitem">
-<p><code class="varname">PKG_SYSCONFSUBDIR</code>: A subdirectory of
- <code class="varname">PKG_SYSCONFBASE</code> under which the configuration files
- for the package being built shall be installed. The definition of this
- variable only makes sense in the package's
- <code class="filename">Makefile</code> (i.e., it is not user-customizable).</p>
-<p>As an example, consider the Apache package,
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/apache24/README.html"; target="_top"><code class="filename">www/apache24</code></a>, which places its
- configuration files under the
- <code class="filename">httpd/</code> subdirectory of
- <code class="varname">PKG_SYSCONFBASE</code>. This should be set in the package
- Makefile.</p>
-</li>
-<li class="listitem"><p><code class="varname">PKG_SYSCONFVAR</code>: Specifies the name of the
- variable that holds this package's configuration directory (if
- different from <code class="varname">PKG_SYSCONFBASE</code>). It defaults to
- <code class="varname">PKGBASE</code>'s value, and is always prefixed with
- <code class="literal">PKG_SYSCONFDIR</code>.</p></li>
-<li class="listitem"><p><code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>: Holds the
- directory where the configuration files for the package identified by
- <code class="varname">PKG_SYSCONFVAR</code>'s shall be placed.</p></li>
-</ul></div>
-<p>Based on the above variables, pkginstall determines the value of
-<code class="varname">PKG_SYSCONFDIR</code>, which is the <span class="emphasis"><em>only</em></span>
-variable that can be used within a package to refer to its configuration
-directory. The algorithm used to set its value is basically the
-following:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>If <code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> is set,
- its value is used.</p></li>
-<li class="listitem"><p>If the previous variable is not defined but
- <code class="varname">PKG_SYSCONFSUBDIR</code> is set in the package's
- <code class="filename">Makefile</code>, the resulting value is
- <code class="filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p></li>
-<li class="listitem"><p>Otherwise, it is set to
- <code class="filename">${PKG_SYSCONFBASE}</code>.</p></li>
+[...]
+
+TOOL_DEPENDS+= libxslt-[0-9]*:../../textproc/libxslt
+DEPENDS+= screen-[0-9]*:../../misc/screen
+DEPENDS+= screen>=4.0:../../misc/screen
+
+[...]
+
+.include "../../<em class="replaceable"><code>category</code></em>/<em class="replaceable"><code>package</code></em>/buildlink3.mk"
+.include "../../devel/glib2/buildlink3.mk"
+.include "../../mk/bsd.pkg.mk"
+</pre>
+</li>
+<li class="step"><p>Run <span class="command"><strong>pkglint</strong></span> to see what things still need
+to be done to make your package a <span class="quote">“<span class="quote">good</span>”</span> one. If you don't
+know what pkglint's warnings want to tell you, try <span class="command"><strong>pkglint
+--explain</strong></span> or <span class="command"><strong>pkglint -e</strong></span>, which outputs
+additional explanations.</p></li>
+<li class="step"><p>In many cases the package is not yet ready to build. You can
+find instructions for the most common cases in the next section, <a class="xref" href="#creating.common" title="14.1.�Common types of packages">Section�14.1, “Common types of
packages”</a>. After you have followed the instructions
+over there, you can hopefully continue here.</p></li>
+<li class="step"><p>Run <span class="command"><strong>bmake clean</strong></span> to clean the working
+directory from the extracted files. Besides these files, a lot of cache
+files and other system information has been saved in the working
+directory, which may become wrong after you edited the
+<code class="filename">Makefile</code>.</p></li>
+<li class="step">
+<p>Now, run <span class="command"><strong>bmake</strong></span> to build the package. For
+the various things that can go wrong in this phase, consult <a class="xref" href="#fixes" title="Chapter�21.�Making your package work">Chapter�21, <i>Making your package work</i></a>.</p>
+<p>If the extracted files from the package need to be fixed, run multiple rounds of these commands:</p>
+<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>make</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pkgvi ${WRKSRC}/some/file/that/does/not/compile</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>mkpatches</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>make mps</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>make clean</code></strong></pre>
+</li>
+<li class="step"><p>When the package builds fine, the next step is to install
+the package. Run <span class="command"><strong>bmake install</strong></span> and hope that
+everything works.</p></li>
+<li class="step"><p>Up to now, the file <code class="filename">PLIST</code>, which
+contains a list of the files that are installed by the package, is
+nearly empty. Run <span class="command"><strong>bmake print-PLIST
+>PLIST</strong></span> to generate a probably correct list. Check
+the file using your preferred text editor to see if the list of
+files looks plausible.</p></li>
+<li class="step"><p>Run <span class="command"><strong>pkglint</strong></span> again to see if the generated
+<code class="filename">PLIST</code> contains garbage or not.</p></li>
+<li class="step"><p>When you ran <span class="command"><strong>bmake install</strong></span>, the package
+had been registered in the database of installed files, but with an
+empty list of files. To fix this, run <span class="command"><strong>bmake deinstall</strong></span>
+and <span class="command"><strong>bmake install</strong></span> again. Now the package is
+registered with the list of files from
+<code class="filename">PLIST</code>.</p></li>
+<li class="step"><p>Run <span class="command"><strong>bmake package</strong></span> to create a binary
+package from the set of installed files.</p></li>
+<li class="step"><p>Run <span class="command"><strong>bmake clean update</strong></span> to run everything
+from above again in a single step, making sure that the PLIST is correct
+and the whole package is created as intended.</p></li>
+<li class="step"><p>Run <span class="command"><strong>pkglint</strong></span> to see if there's anything left to do.</p></li>
+<li class="step"><p>Commit the package to pkgsrc-wip or main pkgsrc; see <a class="xref" href="#submit" title="Chapter�23.�Submitting and Committing">Chapter�23, <i>Submitting and
Committing</i></a>.</p></li>
</ol></div>
-<p>It is worth mentioning that <code class="filename">${PKG_SYSCONFDIR}</code> is
-automatically added to <code class="filename">OWN_DIRS</code>. See <a class="xref" href="#dirs-outside-prefix" title="17.1.1.�Directory manipulation">Section�17.1.1, “Directory
manipulation”</a> what this means. This does not apply to
-subdirectories of <code class="filename">${PKG_SYSCONFDIR}</code>, they still have to
-be created with OWN_DIRS or MAKE_DIRS.</p>
-</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="creating.common"></a>14.1.�Common types of packages</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="conf-files-configure"></a>17.2.2.�Telling the software where configuration files are</h3></div></div></div>
-<p>Given that pkgsrc (and users!) expect configuration files to be in a
-known place, you need to teach each package where it shall install its
-files. In some cases you will have to patch the package Makefiles to
-achieve it. If you are lucky, though, it may be as easy as passing an
-extra flag to the configuration script; this is the case of GNU Autoconf-
-generated files:</p>
-<pre class="programlisting">
-CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
-</pre>
-<p>Note that this specifies where the package has to <span class="emphasis"><em>look
-for</em></span> its configuration files, not where they will be originally
-installed (although the difference is never explicit,
-unfortunately).</p>
+<a name="creating.perl-module"></a>14.1.1.�Perl modules</h3></div></div></div>
+<p>Simple Perl modules are handled automatically by
+<span class="command"><strong>url2pkg</strong></span>, including dependencies.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="conf-files-patching"></a>17.2.3.�Patching installations</h3></div></div></div>
-<p>As said before, pkginstall automatically handles configuration files.
-This means that <span class="strong"><strong>the packages themselves must not
-touch the contents of <code class="filename">${PKG_SYSCONFDIR}</code>
-directly</strong></span>. Bad news is that many software installation scripts
-will, out of the box, mess with the contents of that directory. So what is
-the correct procedure to fix this issue?</p>
-<p>You must teach the package (usually by manually patching it) to
-install any configuration files under the examples hierarchy,
-<code class="filename">share/examples/${PKGBASE}/</code>. This way, the
-<code class="filename">PLIST</code> registers them and the administrator always
-has the original copies available.</p>
-<p>Once the required configuration files are in place (i.e., under the
-examples hierarchy), the pkginstall framework can use them as master copies
-during the package installation to update what is in
-<code class="filename">${PKG_SYSCONFDIR}</code>. To achieve this, the variables
-<code class="varname">CONF_FILES</code> and <code class="varname">CONF_FILES_PERMS</code> are
-used. Check out <a class="xref" href="#files-outside-prefix" title="17.1.2.�File manipulation">Section�17.1.2, “File manipulation”</a> for information
-about their syntax and their purpose. Here is an example, taken from the
-<a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/mail/mutt/README.html"; target="_top"><code class="filename">mail/mutt</code></a> package:</p>
+<a name="creating.python-module"></a>14.1.2.�Python modules and programs</h3></div></div></div>
+<p>Python modules and programs packages are easily created using a
+set of predefined variables.</p>
+<p>
+If some Python versions are not supported by the software, set the
+<code class="varname">PYTHON_VERSIONS_INCOMPATIBLE</code> variable to the Python versions
+that are not supported, e.g.
+</p>
<pre class="programlisting">
-EGDIR= ${PREFIX}/share/doc/mutt/samples
-CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
+PYTHON_VERSIONS_INCOMPATIBLE= 27
</pre>
-<p>Note that the <code class="varname">EGDIR</code> variable is specific to that
-package and has no meaning outside it.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="conf-files-disable"></a>17.2.4.�Disabling handling of configuration files</h3></div></div></div>
-<p>The automatic copying of config files can be toggled by setting the
-environment variable <code class="varname">PKG_CONFIG</code> prior to package
-installation.</p>
-</div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="rcd-scripts"></a>17.3.�System startup scripts</h2></div></div></div>
-<p>System startup scripts are special files because they must be
-installed in a place known by the underlying OS, usually outside the
-installation prefix. Therefore, the same rules described in <a class="xref" href="#files-and-dirs-outside-prefix" title="17.1.�Files and directories outside the installation prefix">Section�17.1,
“Files and directories outside the installation prefix”</a> apply, and the same solutions
-can be used. However, pkginstall provides a special mechanism to handle
-these files.</p>
-<p>In order to provide system startup scripts, the package has
-to:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>Store the script inside <code class="filename">${FILESDIR}</code>, with
- the <code class="literal">.sh</code> suffix appended. Considering the
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/cups/README.html"; target="_top"><code class="filename">print/cups</code></a> package as an example, it has a
- <code class="filename">cupsd.sh</code> in its files directory.</p></li>
-<li class="listitem">
-<p>Tell pkginstall to handle it, appending the name of the script,
- without its extension, to the <code class="varname">RCD_SCRIPTS</code> variable.
- Continuing the previous example:</p>
+<p>
+If the packaged software is a Python module, include one of
+<code class="filename">../../lang/python/egg.mk</code>,
+<code class="filename">../../lang/python/distutils.mk</code>, or
+<code class="filename">../../lang/python/extension.mk</code>.</p>
+<p>Most Python packages use either <span class="quote">“<span class="quote">distutils</span>”</span> or
+easy-setup/setuptools (<span class="quote">“<span class="quote">eggs</span>”</span>).
+If the packaged software is using setuptools, you only need
+to include <span class="quote">“<span class="quote"><code class="filename">../../lang/python/egg.mk</code></span>”</span>.
+Otherwise, if the software uses <span class="quote">“<span class="quote">distutils</span>”</span>, include
+<span class="quote">“<span class="quote"><code class="filename">../../lang/python/distutils.mk</code></span>”</span>,
+so pkgsrc will use this framework.
+<span class="quote">“<span class="quote">distutils</span>”</span> uses a script called <code class="filename">setup.py</code>;
+if the <span class="quote">“<span class="quote">distutils</span>”</span> driver is not called
+<code class="filename">setup.py</code>, set the <code class="varname">PYSETUP</code> variable
+to the name of the script.</p>
+<p>Either way, the package directory should be called
+<span class="quote">“<span class="quote">py-software</span>”</span> and <code class="varname">PKGNAME</code> should be set to
+<span class="quote">“<span class="quote">${PYPKGPREFIX}-${DISTNAME}</span>”</span>, e.g.
+</p>
<pre class="programlisting">
-RCD_SCRIPTS+= cupsd
+DISTNAME= foopymodule-1.2.10
+PKGNAME= ${PYPKGPREFIX}-${DISTNAME}
</pre>
-</li>
-</ol></div>
-<p>Once this is done, pkginstall will do the following steps for each
-script in an automated fashion:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>Process the file found in the files directory applying all the
- substitutions described in the <code class="filename">FILES_SUBST</code>
- variable.</p></li>
-<li class="listitem"><p>Copy the script from the files directory to the examples
- hierarchy, <code class="filename">${PREFIX}/share/examples/rc.d/</code>. Note
- that this master file must be explicitly registered in the
- <code class="filename">PLIST</code>.</p></li>
-<li class="listitem"><p>Add code to the installation scripts to copy the startup script
- from the examples hierarchy into the system-wide startup scripts
- directory.</p></li>
-</ol></div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="rcd-scripts-disable"></a>17.3.1.�Disabling handling of system startup scripts</h3></div></div></div>
-<p>The automatic copying of config files can be toggled by setting the
-environment variable <code class="varname">PKG_RCD_SCRIPTS</code> prior to package
-installation. Note that the scripts will be always copied inside the
-examples hierarchy, <code class="filename">${PREFIX}/share/examples/rc.d/</code>, no
-matter what the value of this variable is.</p>
-</div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="users-and-groups"></a>17.4.�System users and groups</h2></div></div></div>
-<p>If a package needs to create special users and/or groups during
-installation, it can do so by using the pkginstall framework.</p>
-<p>Users can be created by adding entries to the
-<code class="varname">PKG_USERS</code> variable. Each entry has the following
-syntax:</p>
+<p>If it is an application, include
+<span class="quote">“<span class="quote"><code class="filename">../../lang/python/application.mk</code></span>”</span>.
+In order to correctly set the path to the Python interpreter, use the
+<code class="varname">REPLACE_PYTHON</code> variable and set it to the list of files
+(paths relative to <code class="varname">WRKSRC</code>) that must be corrected.
+For example:
+</p>
<pre class="programlisting">
-user:group
+REPLACE_PYTHON= *.py
</pre>
-<p>Further specification of user details may be done by setting
-per-user variables.
-<code class="varname">PKG_UID.<em class="replaceable"><code>user</code></em></code> is the
-numeric UID for the user.
-<code class="varname">PKG_GECOS.<em class="replaceable"><code>user</code></em></code> is the
-user's description or comment.
-<code class="varname">PKG_HOME.<em class="replaceable"><code>user</code></em></code> is the
-user's home directory, and defaults to
-<code class="filename">/nonexistent</code> if not specified.
-<code class="varname">PKG_SHELL.<em class="replaceable"><code>user</code></em></code> is the
-user's shell, and defaults to <code class="filename">/sbin/nologin</code> if
-not specified.</p>
-<p>Similarly, groups can be created by adding entries to the
-<code class="varname">PKG_GROUPS</code> variable, whose syntax is:</p>
+<p>Some Python modules have separate distributions for Python-2.x
+and Python-3.x support. In pkgsrc this is handled by the
+<code class="filename">versioned_dependencies.mk</code> file. Set
+<code class="varname">PYTHON_VERSIONED_DEPENDENCIES</code> to the list of
+packages that should be depended upon and include
+<span class="quote">“<span class="quote"><code class="filename">../../lang/python/versioned_dependencies.mk</code></span>”</span>,
+then the pkgsrc infrastructure will depend on the appropriate package
+version. For example:
+</p>
<pre class="programlisting">
-group
+PYTHON_VERSIONED_DEPENDENCIES=dialog
</pre>
-<p>The numeric GID of the group may be set by defining
-<code class="varname">PKG_GID.<em class="replaceable"><code>group</code></em></code>.</p>
-<p>If a package needs to create the users and groups at an earlier
-stage, then it can set <code class="varname">USERGROUP_PHASE</code> to either
-<code class="literal">configure</code>,<code class="literal">build</code>, or
-<code class="literal">pre-install</code> to indicate the phase before which the
-users and groups are created. In this case, the numeric UIDs and GIDs
-of the created users and groups are automatically hardcoded into the
-final installation scripts.</p>
+<p>
+Look inside <code class="filename">versioned_dependencies.mk</code> for a list
+of supported packages.</p>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="shells"></a>17.5.�System shells</h2></div></div></div>
-<p>Packages that install system shells should register them in the shell
-database, <code class="filename">/etc/shells</code>, to make things easier to the
-administrator. This must be done from the installation scripts to keep
-binary packages working on any system. pkginstall provides an easy way to
-accomplish this task.</p>
-<p>When a package provides a shell interpreter, it has to set the
-<code class="varname">PKG_SHELL</code> variable to its absolute file name. This will
-add some hooks to the installation scripts to handle it. Consider the
-following example, taken from <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/shells/zsh/README.html"; target="_top"><code class="filename">shells/zsh</code></a>:</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="creating.R-package"></a>14.1.3.�R packages</h3></div></div></div>
+<p>Simple R packages from <a class="ulink" href="https://cran.r-project.org/web/packages/available_packages_by_name.html"; target="_top">CRAN</a>
+are handled automatically by <span class="command"><strong>R2pkg</strong></span>, which is
+available in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/R2pkg/README.html"; target="_top"><code class="filename">pkgtools/R2pkg</code></a>.
+Individual packages (and optionally their dependencies) may be created
+and updated. R packages generally follow the same form, and most of
+the relevant information needed is contained in a
+<code class="filename">DESCRIPTION</code> file as part of each R package on
+<a class="ulink" href="https://cran.r-project.org/web/packages/available_packages_by_name.html"; target="_top">CRAN</a>.
+Consequently, <span class="command"><strong>R2pkg</strong></span> downloads that information and
+creates or updates a package in the canonical form. The resulting
+package should be reviewed for correctness.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="creating.TeX-package"></a>14.1.4.�TeXlive packages</h3></div></div></div>
+<p>TeXlive packages from <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a> are handled automatically by
+<span class="command"><strong>texlive2pkg</strong></span>, which is available in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/texlive2pkg/README.html"; target="_top"><code
class="filename">pkgtools/texlive2pkg</code></a>.</p>
+<p>If the TeXlive package name is not known, it may be useful to
+search <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a>. A
+<span class="quote">“<span class="quote">Contained in</span>”</span> field on the package page typically
+identifies the basename of the package file in the <a class="ulink" href="https://www.ctan.org/tex-archive/systems/texlive/tlnet/archive"; target="_top">TeXlive
+archive</a>.</p>
+<p>If the TeXlive package name is known, download the files from
+the <a class="ulink" href="https://www.ctan.org/tex-archive/systems/texlive/tlnet/archive"; target="_top">TeXlive
+archive</a>. For package <code class="filename">foo</code>, you will need
+to download <code class="filename">foo.tar.xz</code>. Most TeXlive packages
+also have associated documentation packages, so download
+<code class="filename">foo.doc.tar.xz</code> at the same time. These files
+should be placed in the appropriate category directory, which is often
+but not always <code class="filename">print</code>. Then run the following
+command in the category directory.</p>
+<pre class="programlisting">
+texlive2pkg foo.tar.xz foo.doc.tar.xz
+</pre>
+<p>This will create two packages, <code class="filename">tex-foo</code> and
+<code class="filename">tex-foo-doc</code>. Be sure to check that both packages
+are correct.</p>
+<p>Finally, <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a>
+currently does not include version information in package filenames
+and changes their contents periodically when updates occur.
+Consequently, pkgsrc avoids downloading distfiles directly from <a class="ulink" href="https://www.ctan.org/"; target="_top">CTAN</a> and instead relies on the
+pkgsrc archives. For each new or updated TeXlive package, e.g., the
+main one and the corresponding documentation, upload the distfiles
+with the following command in each package directory.</p>
<pre class="programlisting">
-PKG_SHELL= ${PREFIX}/bin/zsh
+make upload-distfiles
</pre>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="shells-disable"></a>17.5.1.�Disabling shell registration</h3></div></div></div>
-<p>The automatic registration of shell interpreters can be disabled by
-the administrator by setting the <code class="filename">PKG_REGISTER_SHELLS</code>
-environment variable to <code class="literal">NO</code>.</p>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="fonts"></a>17.6.�Fonts</h2></div></div></div>
-<p>Packages that install X11 fonts should update the database files
-that index the fonts within each fonts directory. This can easily be
-accomplished within the pkginstall framework.</p>
-<p>When a package installs X11 fonts, it must list the directories in
-which fonts are installed in the
-<code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code> variables,
-where <em class="replaceable"><code>type</code></em> can be one of <span class="quote">“<span class="quote">ttf</span>”</span>,
-<span class="quote">“<span class="quote">type1</span>”</span> or <span class="quote">“<span class="quote">x11</span>”</span>. This will add hooks to the
-installation scripts to run the appropriate commands to update the fonts
-database files within each of those directories. For convenience, if the
-directory path is relative, it is taken to be relative to the package's
-installation prefix. Consider the following example, taken from <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/fonts/dbz-ttf/README.html"; target="_top"><code
class="filename">fonts/dbz-ttf</code></a>:</p>
-<pre class="programlisting">
-FONTS_DIRS.ttf= ${PREFIX}/share/fonts/X11/TTF
-</pre>
+<a name="creating.examples"></a>14.2.�Examples</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="fonts-disable"></a>17.6.1.�Disabling automatic update of the fonts databases</h3></div></div></div>
-<p>The automatic update of fonts databases can be disabled by
-the administrator by setting the <code class="filename">PKG_UPDATE_FONTS_DB</code>
-environment variable to <code class="literal">NO</code>.</p>
-</div>
-</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="options"></a>Chapter�18.�Options handling</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#global-default-options">18.1. Global default options</a></span></dt>
-<dt><span class="sect1"><a href="#converting-to-options">18.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
-<dt><span class="sect1"><a href="#option-names">18.3. Option Names</a></span></dt>
-<dt><span class="sect1"><a href="#option-build">18.4. Determining the options of dependencies</a></span></dt>
-</dl>
-</div>
-<p>Many packages have the ability to be built to support different
-sets of features. <code class="filename">bsd.options.mk</code> is a framework
-in pkgsrc that provides generic handling of those options that
-determine different ways in which the packages can be built. It's
-possible for the user to specify exactly which sets of options will be
-built into a package or to allow a set of global default options
-apply.</p>
-<p>There are two broad classes of behaviors that one might want to
-control via options. One is whether some particular feature is
-enabled in a program that will be built anyway, often by including or
-not including a dependency on some other package. The other is
-whether or not an additional program will be built as part of the
-package. Generally, it is better to make a split package for such
-additional programs instead of using options, because it enables
-binary packages to be built which can then be added separately. For
-example, the foo package might have minimal dependencies (those
-packages without which foo doesn't make sense), and then the foo-gfoo
-package might include the GTK frontend program gfoo. This is better
-than including a gtk option to foo that adds gfoo, because either that
-option is default, in which case binary users can't get foo without
-gfoo, or not default, in which case they can't get gfoo. With split
-packages, they can install foo without having GTK, and later decide to
-install gfoo (pulling in GTK at that time). This is an advantage to
-source users too, avoiding the need for rebuilds.</p>
-<p>Plugins with widely varying dependencies should usually be split
-instead of options.</p>
-<p>It is often more work to maintain split packages, especially if
-the upstream package does not support this. The decision of split
-vs. option should be made based on the likelihood that users will want
-or object to the various pieces, the size of the dependencies that are
-included, and the amount of work.</p>
-<p>A further consideration is licensing. Non-free parts, or parts
-that depend on non-free dependencies (especially plugins) should
-almost always be split if feasible.</p>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="global-default-options"></a>18.1.�Global default options</h2></div></div></div>
-<p>Global default options are listed in
-<code class="varname">PKG_DEFAULT_OPTIONS</code>, which is a list of the options
-that should be built into every package if that option is supported.
-This variable should be set in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="converting-to-options"></a>18.2.�Converting packages to use <code class="filename">bsd.options.mk</code>
-</h2></div></div></div>
-<p>The following example shows how
-<code class="filename">bsd.options.mk</code> should be used
-by the hypothetical ``wibble'' package, either in the package
-<code class="filename">Makefile</code>, or in a file,
-e.g. <code class="filename">options.mk</code>, that is included by the
-main package <code class="filename">Makefile</code>.</p>
+<a name="creating.nvu"></a>14.2.1.�How the www/nvu package came into pkgsrc</h3></div></div></div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="creating.nvu.init"></a>14.2.1.1.�The initial package</h4></div></div></div>
+<p>Looking at the file <code class="filename">pkgsrc/doc/TODO</code>, I saw
+that the <span class="quote">“<span class="quote">nvu</span>”</span> package has not yet been imported into
+pkgsrc. As the description says it has to do with the web, the obvious
+choice for the category is <span class="quote">“<span class="quote">www</span>”</span>.</p>
<pre class="programlisting">
-PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
-PKG_SUPPORTED_OPTIONS= wibble-foo ldap
-PKG_OPTIONS_OPTIONAL_GROUPS= database
-PKG_OPTIONS_GROUP.database= mysql pgsql
-PKG_SUGGESTED_OPTIONS= wibble-foo
-PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
-PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
-
-.include "../../mk/bsd.prefs.mk"
-
-# this package was previously named wibble2
-.if defined(PKG_OPTIONS.wibble2)
-PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
-PKG_OPTIONS_DEPRECATED_WARNINGS+= \
- "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR} instead."
-.endif
+<code class="prompt">$</code> mkdir www/nvu
+<code class="prompt">$</code> cd www/nvu
+</pre>
+<p>The web site says that the sources are available as a tar file, so
+I fed that URL to the <span class="command"><strong>url2pkg</strong></span> program:</p>
+<pre class="programlisting">
+<code class="prompt">$</code> url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
+</pre>
+<p>My editor popped up, and I added a <code class="varname">PKGNAME</code> line
+below the <code class="varname">DISTNAME</code> line, as the package name should
+not have the word <span class="quote">“<span class="quote">sources</span>”</span> in it. I also filled in the
+<code class="varname">MAINTAINER</code>, <code class="varname">HOMEPAGE</code> and
+<code class="varname">COMMENT</code> fields. Then the package
+<code class="filename">Makefile</code> looked like that:</p>
+<pre class="programlisting">
+# $NetBSD $
+#
-.include "../../mk/bsd.options.mk"
+DISTNAME= nvu-1.0-sources
+PKGNAME= nvu-1.0
+CATEGORIES= www
+MASTER_SITES= http://cvs.nvu.com/download/
+EXTRACT_SUFX= .tar.bz2
-# Package-specific option-handling
+MAINTAINER= rillig%NetBSD.org@localhost
+HOMEPAGE= http://cvs.nvu.com/
+COMMENT= Web Authoring System
-###
-### FOO support
-###
-.if !empty(PKG_OPTIONS:Mwibble-foo)
-CONFIGURE_ARGS+= --enable-foo
-.endif
+# url2pkg-marker (please do not remove this line.)
+.include "../../mk/bsd.pkg.mk"
+</pre>
+<p>On the first line of output above, an artificial space has been added between NetBSD and $,
+this is a workaround to prevent CVS expanding to the filename of the
+guide.</p>
+<p>Then, I quit the editor and watched pkgsrc downloading a large
+source archive:</p>
+<pre class="programlisting">
+url2pkg> Running "make makesum" ...
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Fetching nvu-1.0-sources.tar.bz2
+Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
+100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA
+29687976 bytes retrieved in 03:12 (150.77 KB/s)
+url2pkg> Running "make extract" ...
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
+===> Installing dependencies for nvu-1.0
+===> Overriding tools for nvu-1.0
+===> Extracting for nvu-1.0
+url2pkg> Adjusting the Makefile.
-###
-### LDAP support
-###
-.if !empty(PKG_OPTIONS:Mldap)
-. include "../../databases/openldap-client/buildlink3.mk"
-CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
-.endif
+Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
-###
-### database support
-###
-.if !empty(PKG_OPTIONS:Mmysql)
-. include "../../mk/mysql.buildlink3.mk"
-.endif
-.if !empty(PKG_OPTIONS:Mpgsql)
-. include "../../mk/pgsql.buildlink3.mk"
-.endif
+Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
+</pre>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="creating.nvu.problems"></a>14.2.1.2.�Fixing all kinds of problems to make the package work</h4></div></div></div>
+<p>Now that the package has been extracted, let's see what's inside
+it. The package has a <code class="filename">README.txt</code>, but that only
+says something about mozilla, so it's probably useless for seeing what
+dependencies this package has. But since there is a GNU configure script
+in the package, let's hope that it will complain about everything it
+needs.</p>
+<pre class="programlisting">
+<code class="prompt">$</code> bmake
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+===> Patching for nvu-1.0
+===> Creating toolchain wrappers for nvu-1.0
+===> Configuring for nvu-1.0
+[...]
+configure: error: Perl 5.004 or higher is required.
+[...]
+WARNING: Please add USE_TOOLS+=perl to the package Makefile.
+[...]
+</pre>
+<p>That worked quite well. So I opened the package Makefile in my
+editor, and since it already has a <code class="varname">USE_TOOLS</code> line, I
+just appended <span class="quote">“<span class="quote">perl</span>”</span> to it. Since the dependencies of the
+package have changed now, and since a perl wrapper is automatically
+installed in the <span class="quote">“<span class="quote">tools</span>”</span> phase, I need to build the package
+from scratch.</p>
+<pre class="programlisting">
+<code class="prompt">$</code> bmake clean
+===> Cleaning for nvu-1.0
+<code class="prompt">$</code> bmake
+[...]
+*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
+GNU Make. You will not be able to build Mozilla without GNU Make.
+[...]
+</pre>
+<p>So I added <span class="quote">“<span class="quote">gmake</span>”</span> to the
+<code class="varname">USE_TOOLS</code> line and tried again (from scratch).</p>
+<pre class="programlisting">
+[...]
+checking for GTK - version >= 1.2.0... no
+*** Could not run GTK test program, checking why...
+[...]
+</pre>
+<p>Now to the other dependencies. The first question is: Where is the
+GTK package hidden in pkgsrc?</p>
+<pre class="programlisting">
+<code class="prompt">$</code> echo ../../*/gtk*
+[many packages ...]
+<code class="prompt">$</code> echo ../../*/gtk
+../../x11/gtk
+<code class="prompt">$</code> echo ../../*/gtk2
+../../x11/gtk2
+<code class="prompt">$</code> echo ../../*/gtk2/bui*
+../../x11/gtk2/buildlink3.mk
+</pre>
+<p>The first try was definitely too broad. The second one had exactly
+one result, which is very good. But there is one pitfall with GNOME
+packages. Before GNOME 2 had been released, there were already many
+GNOME 1 packages in pkgsrc. To be able to continue to use these
+packages, the GNOME 2 packages were imported as separate packages, and
+their names usually have a <span class="quote">“<span class="quote">2</span>”</span> appended. So I checked
+whether this was the case here, and indeed it was.</p>
+<p>Since the GTK2 package has a <code class="filename">buildlink3.mk</code>
+file, adding the dependency is very easy. I just inserted an
+<code class="literal">.include</code> line before the last line of the package
+<code class="filename">Makefile</code>, so that it now looks like this:</p>
+<pre class="programlisting">
+[...]
+.include "../../x11/gtk2/buildlink3.mk"
+.include "../../mk/bsd.pkg.mk
</pre>
-<p>The first section contains the information about which build
-options are supported by the package, and any default options settings
-if needed.</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_VAR</code> is the name of the
-<a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable that the user
can set to override the default
-options. It should be set to
-PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em>. Do not set it to
-PKG_OPTIONS.${PKGBASE}, since <code class="varname">PKGBASE</code> is not defined
-at the point where the options are processed.</p></li>
-<li class="listitem"><p><code class="varname">PKG_SUPPORTED_OPTIONS</code> is a list of
-build options supported by the package.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
-list of names of groups of mutually exclusive options. The options in
-each group are listed in
-<code class="varname">PKG_OPTIONS_GROUP.<em class="replaceable"><code>groupname</code></em></code>.
-The most specific setting of any option from the group takes
-precedence over all other options in the group. Options from the
-groups will be automatically added to
-<code class="varname">PKG_SUPPORTED_OPTIONS</code>.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is like
-<code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but building the
-packages will fail if no option from the group is
-selected.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a list
-of names of sets of options. At least one option from each set must
-be selected. The options in each set are listed in
-<code class="varname">PKG_OPTIONS_SET.<em class="replaceable"><code>setname</code></em></code>.
-Options from the sets will be automatically added to
-<code class="varname">PKG_SUPPORTED_OPTIONS</code>. Building the package will
-fail if no option from the set is selected.</p></li>
-<li class="listitem"><p><code class="varname">PKG_SUGGESTED_OPTIONS</code> is a list of
-build options which are enabled by default.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
-of
-<span class="quote">“<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>”</span>
-pairs that map legacy <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> variables to
-their option counterparts. Pairs should be added with
-<span class="quote">“<span class="quote">+=</span>”</span> to keep the listing of global legacy variables. A
-warning will be issued if the user uses a legacy
-variable.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
-of
-<span class="quote">“<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>”</span>
-pairs that map options that have been renamed to their new
-counterparts. Pairs should be added with <span class="quote">“<span class="quote">+=</span>”</span> to keep
-the listing of global legacy options. A warning will be issued if
-the user uses a legacy option.</p></li>
-<li class="listitem"><p><code class="varname">PKG_LEGACY_OPTIONS</code> is a list of
-options implied by deprecated variables used. This can be used for
-cases that neither <code class="varname">PKG_OPTIONS_LEGACY_VARS</code> nor
-<code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> can handle, e. g. when
-<code class="varname">PKG_OPTIONS_VAR</code> is renamed.</p></li>
-<li class="listitem"><p><code class="varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
-a list of warnings about deprecated variables or options used, and
-what to use instead.</p></li>
-</ol></div>
-<p>A package should never modify
-<code class="varname">PKG_DEFAULT_OPTIONS</code> or the variable named in
-<code class="varname">PKG_OPTIONS_VAR</code>. These are strictly user-settable.
-To suggest a default set of options, use
-<code class="varname">PKG_SUGGESTED_OPTIONS</code>.</p>
-<p><code class="varname">PKG_OPTIONS_VAR</code> must be defined before
-including <code class="filename">bsd.options.mk</code>. If none of
-<code class="varname">PKG_SUPPORTED_OPTIONS</code>,
-<code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
-<code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> are defined (as can
-happen with platform-specific options if none of them is supported on
-the current platform), <code class="varname">PKG_OPTIONS</code> is set to the
-empty list and the package is otherwise treated as not using the
-options framework.</p>
-<p>After the inclusion of <code class="filename">bsd.options.mk</code>, the
-variable <code class="varname">PKG_OPTIONS</code> contains the list of selected
-build options, properly filtered to remove unsupported and duplicate
-options.</p>
-<p>The remaining sections contain the logic that is specific to
-each option. The correct way to check for an option is to check
-whether it is listed in <code class="varname">PKG_OPTIONS</code>:</p>
+<p>After another <span class="command"><strong>bmake clean && bmake</strong></span>, the answer
+was:</p>
<pre class="programlisting">
-.if !empty(PKG_OPTIONS:M<em class="replaceable"><code>option</code></em>)
+[...]
+checking for gtk-config... /home/roland/pkg/bin/gtk-config
+checking for GTK - version >= 1.2.0... no
+*** Could not run GTK test program, checking why...
+*** The test program failed to compile or link. See the file config.log for the
+*** exact error that occured. This usually means GTK was incorrectly installed
+*** or that you have moved GTK since it was installed. In the latter case, you
+*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
+configure: error: Test for GTK failed.
+[...]
</pre>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="option-names"></a>18.3.�Option Names</h2></div></div></div>
-<p>Options that enable similar features in different packages (like
-optional support for a library) should use a common name in all
-packages that support it (like the name of the library). If another
-package already has an option with the same meaning, use the same
-name.</p>
-<p>Options that enable features specific to one package, where it's
-unlikely that another (unrelated) package has the same (or a similar)
-optional feature, should use a name prefixed with
-<code class="varname"><em class="replaceable"><code>pkgname</code></em>-</code>.</p>
-<p>If a group of related packages share an optional feature
-specific to that group, prefix it with the name of the
-<span class="quote">“<span class="quote">main</span>”</span> package
-(e. g. <code class="varname">djbware-errno-hack</code>).</p>
-<p>For new options, add a line to
-<code class="filename">mk/defaults/options.description</code>. Lines have two
-fields, separated by tab. The first field is the option name, the
-second its description. The description should be a whole sentence
-(starting with an uppercase letter and ending with a period) that
-describes what enabling the option does. E. g. <span class="quote">“<span class="quote">Enable ispell
-support.</span>”</span> The file is sorted by option names.</p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="option-build"></a>18.4.�Determining the options of dependencies</h2></div></div></div>
-<p>When writing <a class="link" href="#buildlink3.mk"><code class="filename">buildlink3.mk</code></a> files, it is often necessary to list
-different dependencies based on the options with which the package was
-built. For querying these options, the file
-<code class="filename">pkgsrc/mk/pkg-build-options.mk</code> should be used. A
-typical example looks like this:</p>
+<p>In this particular case, the assumption that <span class="quote">“<span class="quote">every package
+prefers GNOME 2</span>”</span> had been wrong. The first of the lines above
+told me that this package really wanted to have the GNOME 1 version of
+GTK. If the package had looked for GTK2, it would have looked for
+<span class="command"><strong>pkg-config</strong></span> instead of <span class="command"><strong>gtk-config</strong></span>.
+So I changed the <code class="literal">x11/gtk2</code> to
+<code class="literal">x11/gtk</code> in the package <code class="filename">Makefile</code>,
+and tried again.</p>
<pre class="programlisting">
-pkgbase := libpurple
-.include "../../mk/pkg-build-options.mk"
-
-.if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus)
-...
-.endif
+[...]
+cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" [...]
+In file included from xpidl.c:42:
+xpidl.h:53:24: libIDL/IDL.h: No such file or directory
+In file included from xpidl.c:42:
+xpidl.h:132: error: parse error before "IDL_ns"
+[...]
</pre>
-<p>Including <code class="filename">pkg-build-options.mk</code> here will set
-the variable <code class="varname">PKG_BUILD_OPTIONS.libpurple</code> to the build
-options of the libpurple package, which can then be queried like
-<code class="varname">PKG_OPTIONS</code> in the <code class="filename">options.mk</code>
-file. See the file <code class="filename">pkg-build-options.mk</code> for more
-details.</p>
-</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="build"></a>Chapter�19.�The build process</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#build.intro">19.1. Introduction</a></span></dt>
-<dt><span class="sect1"><a href="#build.prefix">19.2. Program location</a></span></dt>
-<dt><span class="sect1"><a href="#build.builddirs">19.3. Directories used during the build process</a></span></dt>
-<dt><span class="sect1"><a href="#build.running">19.4. Running a phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.fetch">19.5. The <span class="emphasis"><em>fetch</em></span> phase</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#build.fetch.what">19.5.1. What to fetch and where to get it from</a></span></dt>
-<dt><span class="sect2"><a href="#build.fetch.how">19.5.2. How are the files fetched?</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#build.checksum">19.6. The <span class="emphasis"><em>checksum</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.extract">19.7. The <span class="emphasis"><em>extract</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.patch">19.8. The <span class="emphasis"><em>patch</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.tools">19.9. The <span class="emphasis"><em>tools</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.wrapper">19.10. The <span class="emphasis"><em>wrapper</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.configure">19.11. The <span class="emphasis"><em>configure</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.build">19.12. The <span class="emphasis"><em>build</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.test">19.13. The <span class="emphasis"><em>test</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.install">19.14. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.package">19.15. The <span class="emphasis"><em>package</em></span> phase</a></span></dt>
-<dt><span class="sect1"><a href="#build.clean">19.16. Cleaning up</a></span></dt>
-<dt><span class="sect1"><a href="#build.helpful-targets">19.17. Other helpful targets</a></span></dt>
-</dl>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.intro"></a>19.1.�Introduction</h2></div></div></div>
-<p>This chapter gives a detailed description on how a package is
- built. Building a package is separated into different
- <span class="emphasis"><em>phases</em></span> (for example <code class="varname">fetch</code>,
- <code class="varname">build</code>, <code class="varname">install</code>), all of which are
- described in the following sections. Each phase is split into
- so-called <span class="emphasis"><em>stages</em></span>, which take the name of the
- containing phase, prefixed by one of <code class="varname">pre-</code>,
- <code class="varname">do-</code> or <code class="varname">post-</code>. (Examples are
- <code class="varname">pre-configure</code>, <code class="varname">post-build</code>.) Most
- of the actual work is done in the <code class="varname">do-*</code> stages.</p>
-<p>Never override the regular targets (like
- <code class="varname">fetch</code>), if you have to, override the
- <code class="varname">do-*</code> ones instead.</p>
-<p>The basic steps for building a program are always the same. First
- the program's source (<span class="emphasis"><em>distfile</em></span>) must be brought to
- the local system and then extracted. After any pkgsrc-specific patches
- to compile properly are applied, the software can be configured, then
- built (usually by compiling), and finally the generated binaries, etc.
- can be put into place on the system.</p>
-<p>To get more details about what is happening at each step,
- you can set the <code class="varname">PKG_VERBOSE</code> variable, or the
- <code class="varname">PATCH_DEBUG</code> variable if you are just interested
- in more details about the <span class="emphasis"><em>patch</em></span> step.</p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.prefix"></a>19.2.�Program location</h2></div></div></div>
-<p>Before outlining the process performed by the NetBSD package system in
- the next section, here's a brief discussion on where programs are
- installed, and which variables influence this.</p>
-<p>The automatic variable <code class="varname">PREFIX</code> indicates
- where all files of the final program shall be installed. It is
- usually set to <code class="varname">LOCALBASE</code>
- (<code class="filename">/usr/pkg</code>), or <code class="varname">CROSSBASE</code>
- for pkgs in the <code class="filename">cross</code> category. The value of
- <code class="varname">PREFIX</code> needs to be put
- into the various places in the program's source where paths to
- these files are encoded. See <a class="xref" href="#components.patches" title="13.3.�patches/*">Section�13.3, “<code class="filename">patches/*</code>”</a> and <a class="xref"
href="#fixes.libtool" title="21.3.1.�Shared libraries - libtool">Section�21.3.1, “Shared libraries - libtool”</a> for more details.</p>
-<p>When choosing which of these variables to use,
- follow the following rules:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><code class="varname">PREFIX</code> always points to the location
- where the current pkg will be installed. When referring to a
- pkg's own installation path, use
- <span class="quote">“<span class="quote">${PREFIX}</span>”</span>.</p></li>
-<li class="listitem"><p><code class="varname">LOCALBASE</code> is where all non-X11 pkgs
- are installed. If you need to construct a -I or -L argument
- to the compiler to find includes and libraries installed by
- another non-X11 pkg, use <span class="quote">“<span class="quote">${LOCALBASE}</span>”</span>. The name
- <code class="varname">LOCALBASE</code> stems from FreeBSD, which
- installed all packages in <code class="filename">/usr/local</code>. As
- pkgsrc leaves <code class="filename">/usr/local</code> for the system
- administrator, this variable is a misnomer.</p></li>
-<li class="listitem"><p><code class="varname">X11BASE</code> is where the actual X11
- distribution (from xsrc, etc.) is installed. When looking for
- <span class="emphasis"><em>standard</em></span> X11 includes (not those
- installed by a package), use <span class="quote">“<span class="quote">${X11BASE}</span>”</span>.</p></li>
-<li class="listitem"><p>X11-based packages using imake must set
- <code class="varname">USE_IMAKE</code> to be installed correctly under
- <code class="varname">LOCALBASE</code>.</p></li>
-<li class="listitem"><p>Within <code class="filename">${PREFIX}</code>, packages should
- install files according to <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?hier+7.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">hier</span>(7)</span></a>, with the exception that
- manual pages go into <code class="filename">${PREFIX}/man</code>, not
- <code class="filename">${PREFIX}/share/man</code>.</p></li>
-</ul></div>
+<p>The package still does not find all of its dependencies. Now the
+question is: Which package provides the
+<code class="filename">libIDL/IDL.h</code> header file?</p>
+<pre class="programlisting">
+<code class="prompt">$</code> echo ../../*/*idl*
+../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
+<code class="prompt">$</code> echo ../../*/*IDL*
+../../net/libIDL
+</pre>
+<p>Let's take the one from the second try. So I included the
+<code class="filename">../../net/libIDL/buildlink3.mk</code> file and tried
+again. But the error didn't change. After digging through some of the
+code, I concluded that the build process of the package was broken and
+couldn't have ever worked, but since the Mozilla source tree is quite
+large, I didn't want to fix it. So I added the following to the package
+<code class="filename">Makefile</code> and tried again:</p>
+<pre class="programlisting">
+CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
+BUILDLINK_TRANSFORM+= l:IDL:IDL-2
+</pre>
+<p>The latter line is needed because the package expects the library
+<code class="filename">libIDL.so</code>, but only
+<code class="filename">libIDL-2.so</code> is available. So I told the compiler
+wrapper to rewrite that on the fly.</p>
+<p>The next problem was related to a recent change of the FreeType
+interface. I looked up in <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/seamonkey/README.html"; target="_top"><code class="filename">www/seamonkey</code></a>
+which patch files were relevant for this issue and copied them to the
+<code class="filename">patches</code> directory. Then I retried, fixed the
+patches so that they applied cleanly and retried again. This time,
+everything worked.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="creating.nvu.inst"></a>14.2.1.3.�Installing the package</h4></div></div></div>
+<pre class="programlisting">
+<code class="prompt">$</code> bmake CHECK_FILES=no install
+[...]
+<code class="prompt">$</code> bmake print-PLIST >PLIST
+<code class="prompt">$</code> bmake deinstall
+<code class="prompt">$</code> bmake install
+</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="makefile"></a>Chapter�15.�Programming in <code class="filename">Makefile</code>s</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#makefile.style">15.1. Caveats</a></span></dt>
+<dt><span class="sect1"><a href="#makefile.variables">15.2. <code class="filename">Makefile</code> variables</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#makefile.variables.names">15.2.1. Naming conventions</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#makefile.code">15.3. Code snippets</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#adding-to-list">15.3.1. Adding things to a list</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">15.3.2. Echoing a string exactly as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">15.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">15.3.4. Handling possibly empty variables</a></span></dt>
+</dl></dd>
+</dl>
</div>
+<p>Pkgsrc consists of many <code class="filename">Makefile</code> fragments,
+ each of which forms a well-defined part of the pkgsrc system. Using
+ the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> system as a
programming language for a big system
+ like pkgsrc requires some discipline to keep the code correct and
+ understandable.</p>
+<p>The basic ingredients for <code class="filename">Makefile</code>
+ programming are variables and shell
+ commands. Among these shell commands may even be more complex ones
+ like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?awk+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">awk</span>(1)</span></a> programs. To make
sure that every shell command runs
+ as intended it is necessary to quote all variables correctly when they
+ are used.</p>
+<p>This chapter describes some patterns that appear quite often in
+ <code class="filename">Makefile</code>s, including the pitfalls that come along
+ with them.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.builddirs"></a>19.3.�Directories used during the build process</h2></div></div></div>
-<p>When building a package, various directories are used to store
- source files, temporary files, pkgsrc-internal files, and so on. These
- directories are explained here.</p>
-<p>Some of the directory variables contain relative pathnames. There
- are two common base directories for these relative directories:
- <code class="varname">PKGSRCDIR/PKGPATH</code> is used for directories that are
- pkgsrc-specific. <code class="varname">WRKSRC</code> is used for directories
- inside the package itself.</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">PKGSRCDIR</code></span></dt>
-<dd><p>This is an absolute pathname that points to the pkgsrc
- root directory. Generally, you don't need
- it.</p></dd>
-<dt><span class="term"><code class="varname">PKGDIR</code></span></dt>
-<dd><p>This is an absolute pathname that points to the
- current package.</p></dd>
-<dt><span class="term"><code class="varname">PKGPATH</code></span></dt>
-<dd><p>This is a pathname relative to
- <code class="varname">PKGSRCDIR</code> that points to the current
- package.</p></dd>
-<dt><span class="term"><code class="varname">WRKDIR</code></span></dt>
-<dd><p>This is an absolute pathname pointing to the directory
- where all work takes place. The distfiles are extracted to this
- directory. It also contains temporary directories and log files used by
- the various pkgsrc frameworks, like <span class="emphasis"><em>buildlink</em></span> or
- the <span class="emphasis"><em>wrappers</em></span>.</p></dd>
-<dt><span class="term"><code class="varname">WRKSRC</code></span></dt>
-<dd><p>This is an absolute pathname pointing to the directory
- where the distfiles are extracted. It is usually a direct subdirectory
- of <code class="varname">WRKDIR</code>, and often it's the only directory entry
- that isn't hidden. This variable may be changed by a package
- <code class="filename">Makefile</code>.</p></dd>
-</dl></div>
-<p>The <code class="varname">CREATE_WRKDIR_SYMLINK</code> definition takes either
- the value <span class="emphasis"><em>yes</em></span> or <span class="emphasis"><em>no</em></span> and defaults
- to <span class="emphasis"><em>no</em></span>. It indicates whether a symbolic link to the
- <code class="varname">WRKDIR</code> is to be created in the pkgsrc entry's directory.
- If users would like to have their pkgsrc trees behave in a
- read-only manner, then the value of
- <code class="varname">CREATE_WRKDIR_SYMLINK</code> should be set to
- <span class="emphasis"><em>no</em></span>.</p>
+<a name="makefile.style"></a>15.1.�Caveats</h2></div></div></div>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+<p>When you are creating a file as a
+ target of a rule, always write the data to a temporary file first
+ and finally rename that file. Otherwise there might occur an error
+ in the middle of generating the file, and when the user runs
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> for the second time,
the file exists and will not be
+ regenerated properly. Example:</p>
+<pre class="programlisting">
+wrong:
+ @echo "line 1" > ${.TARGET}
+ @echo "line 2" >> ${.TARGET}
+ @false
+
+correct:
+ @echo "line 1" > ${.TARGET}.tmp
+ @echo "line 2" >> ${.TARGET}.tmp
+ @false
+ @mv ${.TARGET}.tmp ${.TARGET}
+</pre>
+<p>When you run <span class="command"><strong>make wrong</strong></span> twice, the file
+ <code class="filename">wrong</code> will exist, although there was an error
+ message in the first run. On the other hand, running <span class="command"><strong>make
+ correct</strong></span> gives an error message twice, as expected.</p>
+<p>You might remember that <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> sometimes removes
+ <code class="literal">${.TARGET}</code> in case of error, but this only
+ happens when it is interrupted, for example by pressing
+ <code class="literal">Ctrl+C</code>. This does <span class="emphasis"><em>not</em></span> happen
+ when one of the commands fails (like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?false+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">false</span>(1)</span></a> above).</p>
+</li></ul></div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.running"></a>19.4.�Running a phase</h2></div></div></div>
-<p>You can run a particular phase by typing <span class="command"><strong>make
- phase</strong></span>, where <span class="emphasis"><em>phase</em></span> is the name of the
- phase. This will automatically run all phases that are required for this
- phase. The default phase is <code class="varname">build</code>, that is, when you
- run <span class="command"><strong>make</strong></span> without parameters in a package directory,
- the package will be built, but not installed.</p>
+<a name="makefile.variables"></a>15.2.�<code class="filename">Makefile</code> variables</h2></div></div></div>
+<p><code class="filename">Makefile</code> variables contain strings that
+ can be processed using the five operators <code class="code">=</code>,
+ <code class="code">+=</code>, <code class="code">?=</code>, <code class="code">:=</code> and
+ <code class="code">!=</code>, which are described in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> man
+ page.</p>
+<p>When a variable's value is parsed from a
+ <code class="filename">Makefile</code>, the hash character <code class="code">#</code> and
+ the backslash character <code class="code">\</code> are handled specially. If a
+ backslash is the last character in a line, that backslash is removed
+ from the line and the line continues with the next line of the file.</p>
+<p>The <code class="code">#</code> character starts a comment that reaches
+ until the end of the line. To get an actual <code class="code">#</code> character,
+ such as in a URL, write <code class="code">\#</code> instead.</p>
+<p>The evaluation of variables either happens immediately or lazy.
+ It happens immediately when the variable occurs on the right-hand
+ side of the <code class="code">:=</code> or the <code class="code">!=</code> operator, in a
+ <code class="varname">.if</code> condition or a <code class="varname">.for</code> loop.
+ In the other cases, it is evaluated lazily.</p>
+<p>Some of the modifiers split the string into words and then
+ operate on the words, others operate on the string as a whole. When a
+ string is split into words, double quotes and single quotes are
+ interpreted as delimiters, just like in <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sh+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">sh</span>(1)</span></a>.</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="makefile.variables.names"></a>15.2.1.�Naming conventions</h3></div></div></div>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>All variable names starting with an underscore
+ are reserved for use by the pkgsrc infrastructure. They shall
+ not be used by packages.</p></li>
+<li class="listitem"><p>In <span class="command"><strong>.for</strong></span> loops you should use
+ lowercase variable names for the iteration
+ variables.</p></li>
+<li class="listitem"><p>All list variables should have a plural name,
+ such as <code class="varname">PKG_OPTIONS</code> or
+ <code class="varname">DISTFILES</code>.</p></li>
+</ul></div>
+</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.fetch"></a>19.5.�The <span class="emphasis"><em>fetch</em></span> phase</h2></div></div></div>
-<p>The first step in building a package is to fetch the
- distribution files (distfiles) from the sites that are providing
- them. This is the task of the <span class="emphasis"><em>fetch</em></span>
- phase.</p>
+<a name="makefile.code"></a>15.3.�Code snippets</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="build.fetch.what"></a>19.5.1.�What to fetch and where to get it from</h3></div></div></div>
-<p>In simple cases, <code class="varname">MASTER_SITES</code>
- defines all URLs from where the distfile, whose name is
- derived from the <code class="varname">DISTNAME</code> variable, is
- fetched. The more complicated cases are described
- below.</p>
-<p>The variable <code class="varname">DISTFILES</code> specifies
- the list of distfiles that have to be fetched. Its value
- defaults to <code class="literal">${DEFAULT_DISTFILES}</code> and
- its value is <code class="literal">${DISTNAME}${EXTRACT_SUFX}</code>,
- so that most packages don't need to define it at all.
- <code class="varname">EXTRACT_SUFX</code> is
- <code class="literal">.tar.gz</code> by default, but can be changed
- freely. Note that if your package requires additional
- distfiles to the default one, you cannot just append the
- additional filenames using the <code class="literal">+=</code>
- operator, but you have write for example:</p>
+<a name="adding-to-list"></a>15.3.1.�Adding things to a list</h3></div></div></div>
+<p>When adding a string that possibly contains whitespace or quotes to
+a list (example 1), it must be quoted using the <code class="code">:Q</code>
+modifier.</p>
+<p>When adding another list to a list (example 2), it must not be
+quoted, since its elements are already quoted.</p>
<pre class="programlisting">
-DISTFILES= ${DEFAULT_DISTFILES} additional-files.tar.gz
+STRING= foo * bar `date`
+LIST= # empty
+ANOTHER_LIST= a=b c=d
+
+LIST+= ${STRING:Q} # 1
+LIST+= ${ANOTHER_LIST} # 2
</pre>
-<p>Each distfile is fetched from a list of sites, usually
- <code class="varname">MASTER_SITES</code>. If the package has multiple
- <code class="varname">DISTFILES</code> or multiple
- <code class="varname">PATCHFILES</code> from different sites, you can
- set
- <code class="varname">SITES.<em class="replaceable"><code>distfile</code></em></code>
- to the list of URLs where the file
- <code class="filename"><em class="replaceable"><code>distfile</code></em></code>
- (including the suffix) can be found.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="echo-literal"></a>15.3.2.�Echoing a string exactly as-is</h3></div></div></div>
+<p>Echoing a string containing special characters needs special
+work.</p>
<pre class="programlisting">
-DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
-DISTFILES+= foo-file.tar.gz
-SITES.foo-file.tar.gz= \
-https://www.somewhere.com/somehow/ \
-https://www.somewhereelse.com/mirror/somehow/
+STRING= foo bar < > * `date` $$HOME ' "
+EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
+
+all:
+ echo ${STRING} # 1
+ echo ${STRING:Q} # 2
+ printf '%s\n' ${STRING:Q}'' # 3
+ env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
</pre>
-<p>When actually fetching the distfiles, each item from
- <code class="varname">MASTER_SITES</code> or
- <code class="varname">SITES.*</code> gets the name of each distfile
- appended to it, without an intermediate slash. Therefore,
- all site values have to end with a slash or other separator
- character. This allows for example to set
- <code class="varname">MASTER_SITES</code> to a URL of a CGI script
- that gets the name of the distfile as a parameter. In this
- case, the definition would look like:</p>
+<p>Example 1 leads to a syntax error in the shell, as the characters
+are just copied.</p>
+<p>Example 2 quotes the string so that the shell interprets it
+correctly. But the echo command may additionally interpret strings with a
+leading dash or those containing backslashes.</p>
+<p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">printf</span>(1)</span></a> only
+interprets the format string, but not the next argument. The trailing
+single quotes handle the case when the string is empty. In that case, the
+:Q modifier would result in an empty string too, which would then be
+skipped by the shell. For <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">printf</span>(1)</span></a> this doesn't make a difference,
+but other programs may care.</p>
+<p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
+need to be quoted because the quoting has already been done
+when adding elements to the list.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="cflags-gnu-configure"></a>15.3.3.�Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
+<p>When passing <code class="varname">CFLAGS</code> or similar variables to a
+GNU-style configure script (especially those that call other configure
+scripts), it must not have leading or trailing whitespace, since
+otherwise the configure script gets confused. To trim leading and
+trailing whitespace, use the <code class="code">:M</code> modifier, as in the
+following example:</p>
+<pre class="programlisting">
+CPPFLAGS= # empty
+CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
+CPPFLAGS+= ${MY_CPPFLAGS}
+
+CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
+
+all:
+ echo x${CPPFLAGS:Q}x # leading and trailing whitespace
+ echo x${CONFIGURE_ARGS:Q}x # properly trimmed
+</pre>
+<p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
+trailing whitespace because the <code class="code">+=</code> operator always adds a
+space.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="empty-variables"></a>15.3.4.�Handling possibly empty variables</h3></div></div></div>
+<p>When a possibly empty variable is used in a shell program, it may
+lead to a syntax error.</p>
<pre class="programlisting">
-MASTER_SITES= https://www.example.com/download.cgi?file=
+EGFILES= # empty
+
+install-examples: # produces a syntax error in the shell
+ for egfile in ${EGFILES}; do \
+ echo "Installing $$egfile"; \
+ done
</pre>
-<p> The exception to this rule are URLs starting with a dash.
- In that case the URL is taken as is, fetched and the result
- stored under the name of the distfile. You can use this style
- for the case when the download URL style does not match the
- above common case. For example, if permanent download URL is a
- redirector to the real download URL, or the download file name
- is offered by an HTTP Content-Disposition header. In the
- following example, <code class="filename">foo-1.0.0.tar.gz</code> will be
- created instead of the default
- <code class="filename">v1.0.0.tar.gz</code>.</p>
+<p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
+<code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a>.
+To fix this syntax error, use one of the snippets below.</p>
<pre class="programlisting">
-DISTNAME= foo-1.0.0
-MASTER_SITES= -https://www.example.com/archive/v1.0.0.tar.gz
+EMPTY= # empty
+
+install-examples:
+ for egfile in ${EGFILES} ""; do \
+ [ -n "$$egfile" ] || continue; \
+ echo "Installing $$egfile"; \
+ done
</pre>
-<p>There are some predefined values for
- <code class="varname">MASTER_SITES</code>, which can be used in
- packages. The names of the variables should speak for
- themselves.</p>
-<table border="0" summary="Simple list" class="simplelist">
-<tr>
-<td>MASTER_SITE_APACHE</td>
-<td>MASTER_SITE_BACKUP</td>
-</tr>
-<tr>
-<td>MASTER_SITE_CRATESIO</td>
-<td>MASTER_SITE_CYGWIN</td>
-</tr>
-<tr>
-<td>MASTER_SITE_DEBIAN</td>
-<td>MASTER_SITE_FREEBSD</td>
-</tr>
-<tr>
-<td>MASTER_SITE_FREEBSD_LOCAL</td>
-<td>MASTER_SITE_GENTOO</td>
-</tr>
-<tr>
-<td>MASTER_SITE_GITHUB</td>
-<td>MASTER_SITE_GNOME</td>
-</tr>
-<tr>
-<td>MASTER_SITE_GNU</td>
-<td>MASTER_SITE_GNUSTEP</td>
-</tr>
-<tr>
-<td>MASTER_SITE_HASKELL_HACKAGE</td>
-<td>MASTER_SITE_IFARCHIVE</td>
-</tr>
-<tr>
-<td>MASTER_SITE_KDE</td>
-<td>MASTER_SITE_MOZILLA</td>
-</tr>
-<tr>
-<td>MASTER_SITE_MOZILLA_ALL</td>
-<td>MASTER_SITE_MYSQL</td>
-</tr>
-<tr>
-<td>MASTER_SITE_NETLIB</td>
-<td>MASTER_SITE_OPENBSD</td>
-</tr>
-<tr>
-<td>MASTER_SITE_OPENOFFICE</td>
-<td>MASTER_SITE_OSDN</td>
-</tr>
-<tr>
-<td>MASTER_SITE_PERL_CPAN</td>
-<td>MASTER_SITE_PGSQL</td>
-</tr>
-<tr>
-<td>MASTER_SITE_PYPI</td>
-<td>MASTER_SITE_RUBYGEMS</td>
-</tr>
-<tr>
-<td>MASTER_SITE_R_CRAN</td>
-<td>MASTER_SITE_SOURCEFORGE</td>
-</tr>
-<tr>
-<td>MASTER_SITE_SUNSITE</td>
-<td>MASTER_SITE_SUSE</td>
-</tr>
-<tr>
-<td>MASTER_SITE_TEX_CTAN</td>
-<td>MASTER_SITE_XCONTRIB</td>
-</tr>
-<tr>
-<td>MASTER_SITE_XEMACS</td>
-<td>MASTER_SITE_XORG</td>
-</tr>
-</table>
-<p>Some explanations for the less self-explaining ones:
- <code class="varname">MASTER_SITE_BACKUP</code> contains backup sites
- for packages that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/%24%7BDIST_SUBDIR%7D";
target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/${DIST_SUBDIR}</a>. <code class="varname">MASTER_SITE_LOCAL</code> contains local
- package source distributions that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/";
target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/</a>.</p>
-<p>If you choose one of these predefined sites, you may
- want to specify a subdirectory of that site. Since these
- macros may expand to more than one actual site, you
- <span class="emphasis"><em>must</em></span> use the following construct to
- specify a subdirectory:</p>
+<p>In this case, an empty string is appended to the iteration list (to
+prevent the syntax error) and filtered out later.</p>
<pre class="programlisting">
-MASTER_SITES= ${MASTER_SITE_GNU:=subdirectory/name/}
-MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/}
+EGFILES= # empty
+
+install-examples:
+.for egfile in ${EGFILES}
+ echo "Installing ${egfile}"
+.endfor
</pre>
-<p>Note the trailing slash after the subdirectory
- name.</p>
+<p>If one of the filenames contains special characters, it should be
+enclosed in single or double quotes.</p>
+<p>To have a shell command test whether a make variable is empty, use
+the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="build.fetch.how"></a>19.5.2.�How are the files fetched?</h3></div></div></div>
-<p>The <span class="emphasis"><em>fetch</em></span> phase makes sure that
- all the distfiles exist in a local directory
- (<code class="varname">DISTDIR</code>, which can be set by the pkgsrc
- user). If the files do not exist, they are fetched using
- commands of the form</p>
+</div>
+</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="options"></a>Chapter�16.�Options handling</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt>
+<dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
+<dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt>
+<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt>
+</dl>
+</div>
+<p>Many packages have the ability to be built to support different
+sets of features. <code class="filename">bsd.options.mk</code> is a framework
+in pkgsrc that provides generic handling of those options that
+determine different ways in which the packages can be built. It's
+possible for the user to specify exactly which sets of options will be
+built into a package or to allow a set of global default options
+apply.</p>
+<p>There are two broad classes of behaviors that one might want to
+control via options. One is whether some particular feature is
+enabled in a program that will be built anyway, often by including or
+not including a dependency on some other package. The other is
+whether or not an additional program will be built as part of the
+package. Generally, it is better to make a split package for such
+additional programs instead of using options, because it enables
+binary packages to be built which can then be added separately. For
+example, the foo package might have minimal dependencies (those
+packages without which foo doesn't make sense), and then the foo-gfoo
+package might include the GTK frontend program gfoo. This is better
+than including a gtk option to foo that adds gfoo, because either that
+option is default, in which case binary users can't get foo without
+gfoo, or not default, in which case they can't get gfoo. With split
+packages, they can install foo without having GTK, and later decide to
+install gfoo (pulling in GTK at that time). This is an advantage to
+source users too, avoiding the need for rebuilds.</p>
+<p>Plugins with widely varying dependencies should usually be split
+instead of options.</p>
+<p>It is often more work to maintain split packages, especially if
+the upstream package does not support this. The decision of split
+vs. option should be made based on the likelihood that users will want
+or object to the various pieces, the size of the dependencies that are
+included, and the amount of work.</p>
+<p>A further consideration is licensing. Non-free parts, or parts
+that depend on non-free dependencies (especially plugins) should
+almost always be split if feasible.</p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="global-default-options"></a>16.1.�Global default options</h2></div></div></div>
+<p>Global default options are listed in
+<code class="varname">PKG_DEFAULT_OPTIONS</code>, which is a list of the options
+that should be built into every package if that option is supported.
+This variable should be set in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="converting-to-options"></a>16.2.�Converting packages to use <code class="filename">bsd.options.mk</code>
+</h2></div></div></div>
+<p>The following example shows how
+<code class="filename">bsd.options.mk</code> should be used
+by the hypothetical ``wibble'' package, either in the package
+<code class="filename">Makefile</code>, or in a file,
+e.g. <code class="filename">options.mk</code>, that is included by the
+main package <code class="filename">Makefile</code>.</p>
+<pre class="programlisting">
+PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
+PKG_SUPPORTED_OPTIONS= wibble-foo ldap
+PKG_OPTIONS_OPTIONAL_GROUPS= database
+PKG_OPTIONS_GROUP.database= mysql pgsql
+PKG_SUGGESTED_OPTIONS= wibble-foo
+PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
+PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
+
+.include "../../mk/bsd.prefs.mk"
+
+# this package was previously named wibble2
+.if defined(PKG_OPTIONS.wibble2)
+PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
+PKG_OPTIONS_DEPRECATED_WARNINGS+= \
+ "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR} instead."
+.endif
+
+.include "../../mk/bsd.options.mk"
+
+# Package-specific option-handling
+
+###
+### FOO support
+###
+.if !empty(PKG_OPTIONS:Mwibble-foo)
+CONFIGURE_ARGS+= --enable-foo
+.endif
+
+###
+### LDAP support
+###
+.if !empty(PKG_OPTIONS:Mldap)
+. include "../../databases/openldap-client/buildlink3.mk"
+CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
+.endif
+
+###
+### database support
+###
+.if !empty(PKG_OPTIONS:Mmysql)
+. include "../../mk/mysql.buildlink3.mk"
+.endif
+.if !empty(PKG_OPTIONS:Mpgsql)
+. include "../../mk/pgsql.buildlink3.mk"
+.endif
+</pre>
+<p>The first section contains the information about which build
+options are supported by the package, and any default options settings
+if needed.</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_VAR</code> is the name of the
+<a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable that the user
can set to override the default
+options. It should be set to
+PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em>. Do not set it to
+PKG_OPTIONS.${PKGBASE}, since <code class="varname">PKGBASE</code> is not defined
+at the point where the options are processed.</p></li>
+<li class="listitem"><p><code class="varname">PKG_SUPPORTED_OPTIONS</code> is a list of
+build options supported by the package.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
+list of names of groups of mutually exclusive options. The options in
+each group are listed in
+<code class="varname">PKG_OPTIONS_GROUP.<em class="replaceable"><code>groupname</code></em></code>.
+The most specific setting of any option from the group takes
+precedence over all other options in the group. Options from the
+groups will be automatically added to
+<code class="varname">PKG_SUPPORTED_OPTIONS</code>.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is like
+<code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but building the
+packages will fail if no option from the group is
+selected.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a list
+of names of sets of options. At least one option from each set must
+be selected. The options in each set are listed in
+<code class="varname">PKG_OPTIONS_SET.<em class="replaceable"><code>setname</code></em></code>.
+Options from the sets will be automatically added to
+<code class="varname">PKG_SUPPORTED_OPTIONS</code>. Building the package will
+fail if no option from the set is selected.</p></li>
+<li class="listitem"><p><code class="varname">PKG_SUGGESTED_OPTIONS</code> is a list of
+build options which are enabled by default.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
+of
+<span class="quote">“<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>”</span>
+pairs that map legacy <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> variables to
+their option counterparts. Pairs should be added with
+<span class="quote">“<span class="quote">+=</span>”</span> to keep the listing of global legacy variables. A
+warning will be issued if the user uses a legacy
+variable.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
+of
+<span class="quote">“<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>”</span>
+pairs that map options that have been renamed to their new
+counterparts. Pairs should be added with <span class="quote">“<span class="quote">+=</span>”</span> to keep
+the listing of global legacy options. A warning will be issued if
+the user uses a legacy option.</p></li>
+<li class="listitem"><p><code class="varname">PKG_LEGACY_OPTIONS</code> is a list of
+options implied by deprecated variables used. This can be used for
+cases that neither <code class="varname">PKG_OPTIONS_LEGACY_VARS</code> nor
+<code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> can handle, e. g. when
+<code class="varname">PKG_OPTIONS_VAR</code> is renamed.</p></li>
+<li class="listitem"><p><code class="varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
+a list of warnings about deprecated variables or options used, and
+what to use instead.</p></li>
+</ol></div>
+<p>A package should never modify
+<code class="varname">PKG_DEFAULT_OPTIONS</code> or the variable named in
+<code class="varname">PKG_OPTIONS_VAR</code>. These are strictly user-settable.
+To suggest a default set of options, use
+<code class="varname">PKG_SUGGESTED_OPTIONS</code>.</p>
+<p><code class="varname">PKG_OPTIONS_VAR</code> must be defined before
+including <code class="filename">bsd.options.mk</code>. If none of
+<code class="varname">PKG_SUPPORTED_OPTIONS</code>,
+<code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
+<code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> are defined (as can
+happen with platform-specific options if none of them is supported on
+the current platform), <code class="varname">PKG_OPTIONS</code> is set to the
+empty list and the package is otherwise treated as not using the
+options framework.</p>
+<p>After the inclusion of <code class="filename">bsd.options.mk</code>, the
+variable <code class="varname">PKG_OPTIONS</code> contains the list of selected
+build options, properly filtered to remove unsupported and duplicate
+options.</p>
+<p>The remaining sections contain the logic that is specific to
+each option. The correct way to check for an option is to check
+whether it is listed in <code class="varname">PKG_OPTIONS</code>:</p>
<pre class="programlisting">
-${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
+.if !empty(PKG_OPTIONS:M<em class="replaceable"><code>option</code></em>)
</pre>
-<p>where <code class="literal">${site}</code> varies through
- several possibilities in turn: first,
- <code class="varname">MASTER_SITE_OVERRIDE</code> is tried, then the
- sites specified in either <code class="varname">SITES.file</code> if
- defined, else <code class="varname">MASTER_SITES</code> or
- <code class="varname">PATCH_SITES</code>, as applies, then finally the
- value of <code class="varname">MASTER_SITE_BACKUP</code>. The order of
- all except the first and the last can be optionally sorted
- by the user, via setting either
- <code class="varname">MASTER_SORT_RANDOM</code>, and
- <code class="varname">MASTER_SORT_AWK</code> or
- <code class="varname">MASTER_SORT_REGEX</code>.</p>
-<p> The specific command and arguments used depend on the
- <code class="varname">FETCH_USING</code> parameter. The example above is
- for <code class="literal">FETCH_USING=custom</code>.</p>
-<p>The distfiles mirror run by the NetBSD Foundation uses the
- <span class="emphasis"><em>mirror-distfiles</em></span> target to mirror the
- distfiles, if they are freely distributable. Packages setting
- <code class="varname">NO_SRC_ON_FTP</code> (usually to
- <span class="quote">“<span class="quote">${RESTRICTED}</span>”</span>) will not have their distfiles
- mirrored.</p>
-</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.checksum"></a>19.6.�The <span class="emphasis"><em>checksum</em></span> phase</h2></div></div></div>
-<p>After the distfile(s) are fetched, their checksum is
- generated and compared with the checksums stored in the
- distinfo file. If the checksums don't match, the build is
- aborted. This is to ensure the same distfile is used for
- building, and that the distfile wasn't changed, e.g. by some
- malign force, deliberately changed distfiles on the master
- distribution site or network lossage.</p>
+<a name="option-names"></a>16.3.�Option Names</h2></div></div></div>
+<p>Options that enable similar features in different packages (like
+optional support for a library) should use a common name in all
+packages that support it (like the name of the library). If another
+package already has an option with the same meaning, use the same
+name.</p>
+<p>Options that enable features specific to one package, where it's
+unlikely that another (unrelated) package has the same (or a similar)
+optional feature, should use a name prefixed with
+<code class="varname"><em class="replaceable"><code>pkgname</code></em>-</code>.</p>
+<p>If a group of related packages share an optional feature
+specific to that group, prefix it with the name of the
+<span class="quote">“<span class="quote">main</span>”</span> package
+(e. g. <code class="varname">djbware-errno-hack</code>).</p>
+<p>For new options, add a line to
+<code class="filename">mk/defaults/options.description</code>. Lines have two
+fields, separated by tab. The first field is the option name, the
+second its description. The description should be a whole sentence
+(starting with an uppercase letter and ending with a period) that
+describes what enabling the option does. E. g. <span class="quote">“<span class="quote">Enable ispell
+support.</span>”</span> The file is sorted by option names.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.extract"></a>19.7.�The <span class="emphasis"><em>extract</em></span> phase</h2></div></div></div>
-<p>When the distfiles are present on the local system, they
- need to be extracted, as they usually come in the form of some
- compressed archive format.</p>
-<p>By default, all <code class="varname">DISTFILES</code> are
- extracted. If you only need some of them, you can set the
- <code class="varname">EXTRACT_ONLY</code> variable to the list of those
- files.</p>
-<p>Extracting the files is usually done by a little
- program, <code class="filename">mk/extract/extract</code>, which
- already knows how to extract various archive formats, so most
- likely you will not need to change anything here. But if you
- need, the following variables may help you:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</code></span></dt>
-<dd><p>Use these variables to override the default
- options for an extract command, which are defined in
- <code class="filename">mk/extract/extract</code>.</p></dd>
-<dt><span class="term"><code class="varname">EXTRACT_USING</code></span></dt>
-<dd><p>This variable can be set to
- <code class="literal">bsdtar</code>, <code class="literal">gtar</code>, <code class="literal">nbtar</code>
- (which is the default value), <code class="literal">pax</code>, or an
- absolute pathname pointing to the command with which tar
- archives should be extracted. It is preferred to choose bsdtar over gtar
- if NetBSD's pax-as-tar is not good enough.</p></dd>
-</dl></div>
-<p>If the <code class="filename">extract</code> program doesn't
- serve your needs, you can also override the
- <code class="varname">EXTRACT_CMD</code> variable, which holds the
- command used for extracting the files. This command is
- executed in the <code class="filename">${WRKSRC}</code>
- directory. During execution of this command, the shell
- variable <code class="varname">extract_file</code> holds the absolute
- pathname of the file that is going to be extracted.</p>
-<p>And if that still does not suffice, you can override the
- <code class="varname">do-extract</code> target in the package
- Makefile.</p>
+<a name="option-build"></a>16.4.�Determining the options of dependencies</h2></div></div></div>
+<p>When writing <a class="link" href="#buildlink3.mk"><code class="filename">buildlink3.mk</code></a> files, it is often necessary to list
+different dependencies based on the options with which the package was
+built. For querying these options, the file
+<code class="filename">pkgsrc/mk/pkg-build-options.mk</code> should be used. A
+typical example looks like this:</p>
+<pre class="programlisting">
+pkgbase := libpurple
+.include "../../mk/pkg-build-options.mk"
+
+.if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus)
+...
+.endif
+</pre>
+<p>Including <code class="filename">pkg-build-options.mk</code> here will set
+the variable <code class="varname">PKG_BUILD_OPTIONS.libpurple</code> to the build
+options of the libpurple package, which can then be queried like
+<code class="varname">PKG_OPTIONS</code> in the <code class="filename">options.mk</code>
+file. See the file <code class="filename">pkg-build-options.mk</code> for more
+details.</p>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.patch"></a>19.8.�The <span class="emphasis"><em>patch</em></span> phase</h2></div></div></div>
-<p>After extraction, all the patches named by the
- <code class="varname">PATCHFILES</code>, those present in the patches
- subdirectory of the package as well as in
- $LOCALPATCHES/$PKGPATH (e.g.
- <code class="filename">/usr/local/patches/graphics/png</code>) are
- applied. Patchfiles ending in <code class="filename">.Z</code> or
- <code class="filename">.gz</code> are uncompressed before they are
- applied, files ending in <code class="filename">.orig</code> or
- <code class="filename">.rej</code> are ignored. Any special options to
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> can be handed in
- <code class="varname">PATCH_DIST_ARGS</code>. See <a class="xref" href="#components.patches" title="13.3.�patches/*">Section�13.3, “<code class="filename">patches/*</code>”</a> for
more details.</p>
-<p>By default <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given
special arguments to make it
- fail if the expected text from the patch context is not found in the
- patched file. If that happens, fix the patch file by comparing it
- with the actual text in the file to be patched.</p>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.tools"></a>19.9.�The <span class="emphasis"><em>tools</em></span> phase</h2></div></div></div>
-<p>This is covered in <a class="xref" href="#tools" title="Chapter�20.�Tools needed for building or running">Chapter�20, <i>Tools needed for building or running</i></a>.
- </p>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="tools"></a>Chapter�17.�Tools needed for building or running</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#pkgsrc-tools">17.1. Tools for pkgsrc builds</a></span></dt>
+<dt><span class="sect1"><a href="#package-tools">17.2. Tools needed by packages</a></span></dt>
+<dt><span class="sect1"><a href="#platform-tools">17.3. Tools provided by platforms</a></span></dt>
+</dl>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.wrapper"></a>19.10.�The <span class="emphasis"><em>wrapper</em></span> phase</h2></div></div></div>
-<p>This phase creates wrapper programs for the compilers and
- linkers. The following variables can be used to tweak the
- wrappers.</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">ECHO_WRAPPER_MSG</code></span></dt>
-<dd><p>The command used to print progress
- messages. Does nothing by default. Set to
- <code class="literal">${ECHO}</code> to see the progress
- messages.</p></dd>
-<dt><span class="term"><code class="varname">WRAPPER_DEBUG</code></span></dt>
-<dd><p>This variable can be set to
- <code class="literal">yes</code> (default) or <code class="literal">no</code>,
- depending on whether you want additional information in the
- wrapper log file.</p></dd>
-<dt><span class="term"><code class="varname">WRAPPER_UPDATE_CACHE</code></span></dt>
-<dd><p>This variable can be set to
- <code class="literal">yes</code> or <code class="literal">no</code>, depending
- on whether the wrapper should use its cache, which will
- improve the speed. The default value is
- <code class="literal">yes</code>, but is forced to
- <code class="literal">no</code> if the platform does not support
- it.</p></dd>
-<dt><span class="term"><code class="varname">WRAPPER_REORDER_CMDS</code></span></dt>
-<dd><p>A list of reordering commands. A reordering
- command has the form
- <code class="literal">reorder:l:<em class="replaceable"><code>lib1</code></em>:<em class="replaceable"><code>lib2</code></em></code>.
- It ensures that that
- <code class="literal">-l<em class="replaceable"><code>lib1</code></em></code> occurs
- before <code class="literal">-l<em class="replaceable"><code>lib2</code></em></code>.
- </p></dd>
-</dl></div>
+<p>The <code class="varname">USE_TOOLS</code> definition is used both internally
+by pkgsrc and also for individual packages to define what commands
+are needed for building a package (like <code class="varname">TOOL_DEPENDS</code>)
+or for later run-time of an installed packaged (such as
+<code class="varname">DEPENDS</code>).
+If the native system provides an adequate tool, then in many cases, a pkgsrc
+package will not be used.</p>
+<p>When building a package, the replacement tools are
+made available in a directory (as symlinks or wrapper scripts)
+that is early in the executable search path. Just like the buildlink
+system, this helps with consistent builds.</p>
+<p>A tool may be needed to help build a specific package. For example,
+perl, GNU make (gmake) or yacc may be needed.</p>
+<p>Also a tool may be needed, for example, because the native system's supplied
+tool may be inefficient for building a package with pkgsrc.
+For example, a package may need GNU awk, bison (instead of
+yacc) or a better sed.</p>
+<p>The tools used by a package can be listed by running
+<span class="command"><strong>make show-tools</strong></span>.</p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="pkgsrc-tools"></a>17.1.�Tools for pkgsrc builds</h2></div></div></div>
+<p>The default set of tools used by pkgsrc is defined in
+<code class="filename">bsd.pkg.mk</code>. This includes standard Unix tools,
+such as: <span class="command"><strong>cat</strong></span>, <span class="command"><strong>awk</strong></span>,
+<span class="command"><strong>chmod</strong></span>, <span class="command"><strong>test</strong></span>, and so on.
+These can be seen by running:
+<span class="command"><strong>make show-var VARNAME=USE_TOOLS</strong></span>.</p>
+<p>If a package needs a specific program to build
+then the <code class="varname">USE_TOOLS</code> variable can be used
+to define the tools needed.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.configure"></a>19.11.�The <span class="emphasis"><em>configure</em></span> phase</h2></div></div></div>
-<p>Most pieces of software need information on the header
- files, system calls, and library routines which are available
- on the platform they run on. The process of determining this
- information is known as configuration, and is usually
- automated. In most cases, a script is supplied with the
- distfiles, and its invocation results in generation of header
- files, Makefiles, etc.</p>
-<p>If the package contains a configure script, this can be
- invoked by setting <code class="varname">HAS_CONFIGURE</code> to
- <span class="quote">“<span class="quote">yes</span>”</span>. If the configure script is a GNU autoconf
- script, you should set <code class="varname">GNU_CONFIGURE</code> to
- <span class="quote">“<span class="quote">yes</span>”</span> instead. What happens in the
- <span class="emphasis"><em>configure</em></span> phase is roughly:</p>
+<a name="package-tools"></a>17.2.�Tools needed by packages</h2></div></div></div>
+<p>In the following examples, the :run means that it is needed at
+run-time (and becomes a DEPENDS).
+The default is a build dependency which can be set with
+:build. (So in this example, it is the same as gmake:build
+and pkg-config:build.)</p>
<pre class="programlisting">
-.for d in ${CONFIGURE_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
-.endfor
+USE_TOOLS+= gmake perl:run pkg-config
</pre>
-<p><code class="varname">CONFIGURE_DIRS</code> (default:
- <span class="quote">“<span class="quote">.</span>”</span>) is a list of pathnames relative to
- <code class="varname">WRKSRC</code>. In each of these directories, the
- configure script is run with the environment
- <code class="varname">CONFIGURE_ENV</code> and arguments
- <code class="varname">CONFIGURE_ARGS</code>. The variables
- <code class="varname">CONFIGURE_ENV</code>,
- <code class="varname">CONFIGURE_SCRIPT</code> (default:
- <span class="quote">“<span class="quote">./configure</span>”</span>) and
- <code class="varname">CONFIGURE_ARGS</code> may all be changed by the
- package.</p>
-<p>If the program uses the Perl way of configuration (mainly Perl
- modules, but not only), i.e. a file called
- <code class="filename">Makefile.PL</code>, it should include
- <code class="filename">../../lang/perl5/module.mk</code>. To set any parameter for
- <code class="filename">Makefile.PL</code> use the <code class="varname">MAKE_PARAMS</code>
- variable (e.g., <code class="literal">MAKE_PARAMS+=foo=bar</code></p>
-<p>If the program uses an <code class="filename">Imakefile</code>
- for configuration, the appropriate steps can be invoked by
- setting <code class="varname">USE_IMAKE</code> to
- <span class="quote">“<span class="quote">yes</span>”</span>. If you only need xmkmf, add it to <code class="varname">USE_TOOLS</code>.
- You can add variables to xmkmf's environment by adding them to the
- <code class="varname">SCRIPTS_ENV</code> variable.</p>
-<p>If the program uses <code class="filename">cmake</code>
- for configuration, the appropriate steps can be invoked by
- setting <code class="varname">USE_CMAKE</code> to <span class="quote">“<span class="quote">yes</span>”</span>.
- You can add variables to cmake's environment by adding them to the
- <code class="varname">CONFIGURE_ENV</code> variable and arguments to cmake
- by adding them to the <code class="varname">CMAKE_ARGS</code> variable.
- The top directory argument is given by the
- <code class="varname">CMAKE_ARG_PATH</code> variable, that defaults to
- <span class="quote">“<span class="quote">.</span>”</span> (relative to <code class="varname">CONFIGURE_DIRS</code>)</p>
-<p>If there is no configure step at all, set
- <code class="varname">NO_CONFIGURE</code> to <span class="quote">“<span class="quote">yes</span>”</span>.</p>
+<p>When using the tools framework, a
+<code class="varname">TOOLS_PATH.foo</code> variable is defined
+which contains the full path to the appropriate tool. For example,
+<code class="varname">TOOLS_PATH.bash</code> could be <span class="quote">“<span class="quote">/bin/bash</span>”</span>
+on Linux systems.</p>
+<p>If you always need a pkgsrc version of the
+tool at run-time, then just use <code class="varname">DEPENDS</code> instead.
+</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.build"></a>19.12.�The <span class="emphasis"><em>build</em></span> phase</h2></div></div></div>
-<p>For building a package, a rough equivalent of the
- following code is executed.</p>
+<a name="platform-tools"></a>17.3.�Tools provided by platforms</h2></div></div></div>
+<p>When improving or porting pkgsrc to a new platform, have a look
+at (or create) the corresponding platform specific make file fragment under
+<code class="filename">pkgsrc/mk/tools/tools.${OPSYS}.mk</code> which defines
+the name of the common tools. For example:</p>
<pre class="programlisting">
-.for d in ${BUILD_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${MAKE_ENV} \
- ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
- -f ${MAKE_FILE} \
- ${BUILD_TARGET}
-.endfor
+.if exists(/usr/bin/bzcat)
+TOOLS_PLATFORM.bzcat?= /usr/bin/bzcat
+.elif exists(/usr/bin/bzip2)
+TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd
+.endif
+
+TOOLS_PLATFORM.true?= true # shell builtin
</pre>
-<p><code class="varname">BUILD_DIRS</code> (default:
- <span class="quote">“<span class="quote">.</span>”</span>) is a list of pathnames relative to
- <code class="varname">WRKSRC</code>. In each of these directories,
- <code class="varname">MAKE_PROGRAM</code> is run with the environment
- <code class="varname">MAKE_ENV</code> and arguments
- <code class="varname">BUILD_MAKE_FLAGS</code>. The variables
- <code class="varname">MAKE_ENV</code>,
- <code class="varname">BUILD_MAKE_FLAGS</code>,
- <code class="varname">MAKE_FILE</code> and
- <code class="varname">BUILD_TARGET</code> may all be changed by the
- package.</p>
-<p>The default value of <code class="varname">MAKE_PROGRAM</code> is
- <span class="quote">“<span class="quote">gmake</span>”</span> if <code class="varname">USE_TOOLS</code> contains
- <span class="quote">“<span class="quote">gmake</span>”</span>, <span class="quote">“<span class="quote">make</span>”</span> otherwise. The
- default value of <code class="varname">MAKE_FILE</code> is
- <span class="quote">“<span class="quote">Makefile</span>”</span>, and <code class="varname">BUILD_TARGET</code>
- defaults to <span class="quote">“<span class="quote">all</span>”</span>.</p>
-<p>If there is no build step at all, set
- <code class="varname">NO_BUILD</code> to <span class="quote">“<span class="quote">yes</span>”</span>.</p>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.test"></a>19.13.�The <span class="emphasis"><em>test</em></span> phase</h2></div></div></div>
-<p>[TODO]</p>
</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="buildlink"></a>Chapter�18.�Buildlink methodology</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#converting-to-buildlink3">18.1. Converting packages to use buildlink3</a></span></dt>
+<dt><span class="sect1"><a href="#creating-buildlink3.mk">18.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#anatomy-of-bl3">18.2.1. Anatomy of a buildlink3.mk file</a></span></dt>
+<dt><span class="sect2"><a href="#updating-buildlink-depends">18.2.2. Updating
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ and
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ in <code class="filename">buildlink3.mk</code> files</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#writing-builtin.mk">18.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#anatomy-of-builtin.mk">18.3.1. Anatomy of a <code class="filename">builtin.mk</code> file</a></span></dt>
+<dt><span class="sect2"><a href="#native-or-pkgsrc-preference">18.3.2. Global preferences for native or pkgsrc software</a></span></dt>
+</dl></dd>
+</dl>
+</div>
+<p>Buildlink is a framework in pkgsrc that controls what headers and libraries
+ are seen by a package's configure and build processes. This is implemented
+ in a two step process:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Symlink headers and libraries for dependencies into
+ <code class="varname">BUILDLINK_DIR</code>, which by default is a subdirectory
+ of <code class="varname">WRKDIR</code>.</p></li>
+<li class="listitem"><p>Create wrapper scripts that are used in place of the normal compiler
+ tools that translate <code class="option">-I${LOCALBASE}/include</code> and
+ <code class="option">-L${LOCALBASE}/lib</code> into references to
+ <code class="varname">BUILDLINK_DIR</code>. The wrapper scripts also make
+ native compiler on some operating systems look like GCC, so that
+ packages that expect GCC won't require modifications to build with
+ those native compilers.</p></li>
+</ol></div>
+<p>This normalizes the environment in which a package is built so that the
+ package may be built consistently despite what other software may be
+ installed. Please note that the normal system header and library paths,
+ e.g. <code class="filename">/usr/include</code>,
+ <code class="filename">/usr/lib</code>, etc., are always searched -- buildlink3 is
+ designed to insulate the package build from non-system-supplied
+ software.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.install"></a>19.14.�The <span class="emphasis"><em>install</em></span> phase</h2></div></div></div>
-<p>Once the build stage has completed, the final step is to
- install the software in public directories, so users can
- access the programs and files.</p>
-<p>In the <span class="emphasis"><em>install</em></span> phase, a rough
- equivalent of the following code is executed. Additionally,
- before and after this code, much magic is performed to do
- consistency checks, registering the package, and so on.</p>
-<pre class="programlisting">
-.for d in ${INSTALL_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${MAKE_ENV} \
- ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
- -f ${MAKE_FILE} \
- ${INSTALL_TARGET}
-.endfor
-</pre>
-<p>The variable's meanings are analogous to the ones in the
- <span class="emphasis"><em>build</em></span> phase.
- <code class="varname">INSTALL_DIRS</code> defaults to
- <code class="varname">BUILD_DIRS</code>. <code class="varname">INSTALL_TARGET</code>
- is <span class="quote">“<span class="quote">install</span>”</span> by default, plus
- <span class="quote">“<span class="quote">install.man</span>”</span> if <code class="varname">USE_IMAKE</code> is
- defined and <code class="varname">NO_INSTALL_MANPAGES</code> is not
- defined.</p>
-<p>In the <span class="emphasis"><em>install</em></span> phase, the following
- variables are useful. They are all variations of the
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?install+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">install</span>(1)</span></a> command that
have the owner, group and
- permissions preset. <code class="varname">INSTALL</code> is the plain
- install command. The specialized variants, together with their
- intended use, are:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">INSTALL_PROGRAM_DIR</code></span></dt>
-<dd><p>directories that contain
- binaries</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_SCRIPT_DIR</code></span></dt>
-<dd><p>directories that contain
- scripts</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_LIB_DIR</code></span></dt>
-<dd><p>directories that contain shared and static
- libraries</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_DATA_DIR</code></span></dt>
-<dd><p>directories that contain data
- files</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_MAN_DIR</code></span></dt>
-<dd><p>directories that contain man
- pages</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_GAME_DIR</code></span></dt>
-<dd><p>directories that contain data files for games
- </p></dd>
-<dt><span class="term"><code class="varname">INSTALL_PROGRAM</code></span></dt>
-<dd><p>binaries that can be stripped from debugging
- symbols</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_SCRIPT</code></span></dt>
-<dd><p>binaries that cannot be
- stripped</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_GAME</code></span></dt>
-<dd><p>game
- binaries</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_LIB</code></span></dt>
-<dd><p>shared and static
- libraries</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_DATA</code></span></dt>
-<dd><p>data files</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_GAME_DATA</code></span></dt>
-<dd><p>data files for
- games</p></dd>
-<dt><span class="term"><code class="varname">INSTALL_MAN</code></span></dt>
-<dd><p>man pages</p></dd>
-</dl></div>
-<p>Some other variables are:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">INSTALL_UNSTRIPPED</code></span></dt>
-<dd><p>If set to <code class="literal">yes</code>, do not run <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?strip+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">strip</span>(1)</span></a>
- when installing binaries. Any debugging sections and symbols present in
- binaries will be preserved.
- </p></dd>
-<dt><span class="term"><code class="varname">INSTALLATION_DIRS</code></span></dt>
-<dd><p>A list of directories relative to
- <code class="varname">PREFIX</code> that are created by pkgsrc at the
- beginning of the <span class="emphasis"><em>install</em></span> phase.
- The package is supposed to create all needed directories itself
- before installing files to it and list all other directories here.
- </p></dd>
-</dl></div>
-<p>In the rare cases that a package shouldn't install anything,
- set <code class="varname">NO_INSTALL</code> to <span class="quote">“<span class="quote">yes</span>”</span>. This is
- mostly relevant for packages in the <code class="filename">regress</code>
- category.</p>
+<a name="converting-to-buildlink3"></a>18.1.�Converting packages to use buildlink3</h2></div></div></div>
+<p>The process of converting packages to use the buildlink3
+ framework (<span class="quote">“<span class="quote">bl3ifying</span>”</span>) is fairly straightforward.
+ The things to keep in mind are:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Ensure that the build always calls the wrapper scripts
+ instead of the actual toolchain. Some packages are tricky,
+ and the only way to know for sure is the check
+ <code class="filename">${WRKDIR}/.work.log</code> to see if the
+ wrappers are being invoked.</p></li>
+<li class="listitem"><p>Don't override <code class="varname">PREFIX</code> from within
+ the package Makefile, e.g. Java VMs, standalone shells,
+ etc., because the code to symlink files into
+ <code class="filename">${BUILDLINK_DIR}</code> looks for files
+ relative to <span class="quote">“<span class="quote">pkg_info -qp <em class="replaceable"><code>pkgname</code></em></span>”</span>.
+ </p></li>
+<li class="listitem"><p>Remember that <span class="emphasis"><em>only</em></span> the
+ <code class="filename">buildlink3.mk</code> files that you list in a
+ package's Makefile are added as dependencies for that package.
+ </p></li>
+</ol></div>
+<p>If a dependency on a particular package is required for its libraries and
+ headers, then we replace:</p>
+<pre class="programlisting">
+DEPENDS+= foo>=1.1.0:../../category/foo
+</pre>
+<p>with</p>
+<pre class="programlisting">
+.include "../../category/foo/buildlink3.mk"
+</pre>
+<p>The buildlink3.mk files usually define the required dependencies.
+ If you need a newer version of the dependency when using buildlink3.mk
+ files, then you can define it in your Makefile; for example:</p>
+<pre class="programlisting">
+BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0
+.include "../../category/foo/buildlink3.mk"
+</pre>
+<p>There are several <code class="filename">buildlink3.mk</code>
+ files in <code class="filename">pkgsrc/mk</code>
+ that handle special package issues:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="filename">bdb.buildlink3.mk</code> chooses either
+ the native or a pkgsrc Berkeley DB implementation based on
+ the values of <code class="varname">BDB_ACCEPTED</code> and
+ <code class="varname">BDB_DEFAULT</code>.</p></li>
+<li class="listitem"><p><code class="filename">curses.buildlink3.mk</code>: If the system
+ comes with neither Curses nor NCurses, this will take care
+ to install the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/ncurses/README.html"; target="_top"><code class="filename">devel/ncurses</code></a> package.</p></li>
+<li class="listitem"><p><code class="filename">krb5.buildlink3.mk</code> uses the value
+ of <code class="varname">KRB5_ACCEPTED</code> to choose between
+ adding a dependency on Heimdal or MIT-krb5 for packages that
+ require a Kerberos 5 implementation.</p></li>
+<li class="listitem"><p><code class="filename">motif.buildlink3.mk</code> checks for a
+ system-provided Motif installation or adds a dependency on
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/lesstif/README.html"; target="_top"><code class="filename">x11/lesstif</code></a> or <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/x11/motif/README.html"; target="_top"><code class="filename">x11/motif</code></a>. The user can set
+ <code class="varname">MOTIF_TYPE</code> to <span class="quote">“<span class="quote">dt</span>”</span>,
+ <span class="quote">“<span class="quote">lesstif</span>”</span> or <span class="quote">“<span class="quote">motif</span>”</span>
+ to choose which Motif version will be used.</p></li>
+<li class="listitem"><p><code class="filename">readline.buildlink3.mk</code> checks for a
+ system-provided GNU readline or editline (libedit) installation,
+ or adds a dependency on <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/readline/README.html"; target="_top"><code class="filename">devel/readline</code></a>,
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/editline/README.html"; target="_top"><code class="filename">devel/editline</code></a>. The user can set
+ <code class="varname">READLINE_DEFAULT</code> to choose readline implementation.
+ If your package really needs GNU readline library, its Makefile
+ should include <code class="filename">devel/readline/buildlink3.mk</code>
+ instead of <code class="filename">readline.buildlink3.mk</code>.</p></li>
+<li class="listitem"><p><code class="filename">oss.buildlink3.mk</code> defines several
+ variables that may be used by packages that use the
+ Open Sound System (OSS) API.</p></li>
+<li class="listitem"><p><code class="filename">pgsql.buildlink3.mk</code> will accept
+ any of the Postgres versions in the variable
+ <code class="varname">PGSQL_VERSIONS_ACCEPTED</code> and default to
+ the version <code class="varname">PGSQL_VERSION_DEFAULT</code>. See
+ the file for more information.</p></li>
+<li class="listitem"><p><code class="filename">pthread.buildlink3.mk</code> uses the value of
+ <code class="varname">PTHREAD_OPTS</code> and checks for native pthreads or adds
+ a dependency on <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/pth/README.html"; target="_top"><code class="filename">devel/pth</code></a> as needed.</p></li>
+<li class="listitem"><p><code class="filename">xaw.buildlink3.mk</code> uses the value of
+ <code class="varname">XAW_TYPE</code> to choose a particular Athena widgets
+ library.</p></li>
+</ul></div>
+<p>The comments in those <code class="filename">buildlink3.mk</code>
+ files provide a more complete
+ description of how to use them properly.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.package"></a>19.15.�The <span class="emphasis"><em>package</em></span> phase</h2></div></div></div>
-<p>Once the install stage has completed, a binary package of
- the installed files can be built. These binary packages can be
- used for quick installation without previous compilation, e.g. by
- the <span class="command"><strong>make bin-install</strong></span> or by using
- <span class="command"><strong>pkg_add</strong></span>.</p>
-<p>By default, the binary packages are created in
- <code class="filename">${PACKAGES}/All</code> and symlinks are created in
- <code class="filename">${PACKAGES}/<em class="replaceable"><code>category</code></em></code>,
- one for each category in the <code class="varname">CATEGORIES</code>
- variable. <code class="varname">PACKAGES</code> defaults to
- <code class="filename">pkgsrc/packages</code>.</p>
+<a name="creating-buildlink3.mk"></a>18.2.�Writing <code class="filename">buildlink3.mk</code> files</h2></div></div></div>
+<a name="buildlink3.mk"></a><p>A package's <code class="filename">buildlink3.mk</code> file is
+ included by Makefiles to indicate the need to compile and link
+ against header files and libraries provided by the package. A
+ <code class="filename">buildlink3.mk</code> file should always provide
+ enough information to add the correct type of dependency
+ relationship and include any other
+ <code class="filename">buildlink3.mk</code> files that it needs to find
+ headers and libraries that it needs in turn.</p>
+<p>To generate an initial <code class="filename">buildlink3.mk</code>
+ file for further editing, Rene Hexel's <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/createbuildlink/README.html"; target="_top"><code
class="filename">pkgtools/createbuildlink</code></a>
+ package is highly recommended. For most packages, the following
+ command will generate a good starting point for
+ <code class="filename">buildlink3.mk</code> files:</p>
+<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>
+<code class="prompt">%</code> createbuildlink >buildlink3.mk</code></strong>
+ </pre>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="anatomy-of-bl3"></a>18.2.1.�Anatomy of a buildlink3.mk file</h3></div></div></div>
+<p>The following real-life example
+ <code class="filename">buildlink3.mk</code> is taken
+ from <code class="filename">pkgsrc/graphics/tiff</code>:</p>
+<pre class="programlisting">
+# $NetBSD: buildlink3.mk,v 1.16 2009/03/20 19:24:45 joerg Exp $
+
+BUILDLINK_TREE+= tiff
+
+.if !defined(TIFF_BUILDLINK3_MK)
+TIFF_BUILDLINK3_MK:=
+
+BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1
+BUILDLINK_ABI_DEPENDS.tiff+= tiff>=3.7.2nb1
+BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
+
+.include "../../devel/zlib/buildlink3.mk"
+.include "../../graphics/jpeg/buildlink3.mk"
+.endif # TIFF_BUILDLINK3_MK
+
+BUILDLINK_TREE+= -tiff
+</pre>
+<p>The header and footer manipulate
+ <code class="varname">BUILDLINK_TREE</code>, which is common across all
+ <code class="filename">buildlink3.mk</code> files and is used to track
+ the dependency tree.</p>
+<p>The main section is protected from multiple inclusion
+ and controls how the dependency on <em class="replaceable"><code>pkg</code></em> is
+ added. Several important variables are set in the section:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ is the actual dependency recorded in the installed
+ package; this should always be set using
+ <span class="command"><strong>+=</strong></span> to ensure that
+ we're appending to any pre-existing list of values. This
+ variable should be set to the first version of the
+ package that had an backwards-incompatible API change.
+ </p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_PKGSRCDIR.<em class="replaceable"><code>pkg</code></em></code>
+ is the location of the <em class="replaceable"><code>pkg</code></em>
+ pkgsrc directory.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) controls whether we use
+ <code class="varname">BUILD_DEPENDS</code> or
+ <code class="varname">DEPENDS</code> to add the dependency on
+ <em class="replaceable"><code>pkg</code></em>. The build dependency is
+ selected by setting
+ <code class="varname">BUILDLINK_DEPMETHOD.<em class="replaceable"><code>pkg</code></em></code>
+ to <span class="quote">“<span class="quote">build</span>”</span>. By default, the full dependency is
+ used.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code>
+ and
+ <code class="varname">BUILDLINK_LIBDIRS.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) are lists of subdirectories of
+ <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
+ to add to the header and library search paths. These
+ default to <span class="quote">“<span class="quote">include</span>”</span> and <span class="quote">“<span class="quote">lib</span>”</span>
+ respectively.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_CPPFLAGS.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) is the list of preprocessor flags to add
+ to <code class="varname">CPPFLAGS</code>, which are passed on to the
+ configure and build phases. The <span class="quote">“<span class="quote">-I</span>”</span> option
+ should be avoided and instead be handled using
+ <code class="varname">BUILDLINK_INCDIRS.<em class="replaceable"><code>pkg</code></em></code> as
+ above.</p></li>
+</ul></div>
+<p>The following variables are all optionally defined within
+ this second section (protected against multiple inclusion) and
+ control which package files are symlinked into
+ <code class="filename">${BUILDLINK_DIR}</code> and how their names are
+ transformed during the symlinking:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) is a shell glob pattern relative to
+ <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
+ to be symlinked into
+ <code class="filename">${BUILDLINK_DIR}</code>,
+ e.g. <code class="filename">include/*.h</code>.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_FILES_CMD.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) is a shell pipeline that
+ outputs to stdout a list of files relative to
+ <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>.
+ The resulting files are to be symlinked
+ into <code class="filename">${BUILDLINK_DIR}</code>. By default,
+ this takes the <code class="filename">+CONTENTS</code> of a
+ <em class="replaceable"><code>pkg</code></em> and filters it through
+ <code class="varname">${BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em>}</code>.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) is a filter command that filters
+ <code class="filename">+CONTENTS</code> input into a list of files
+ relative to
+ <code class="filename">${BUILDLINK_PREFIX.<em class="replaceable"><code>pkg</code></em>}</code>
+ on stdout. By default,
+ <code class="varname">BUILDLINK_CONTENTS_FILTER.<em class="replaceable"><code>pkg</code></em></code>
+ outputs the contents of the <code class="filename">include</code>
+ and <code class="filename">lib</code> directories in the package
+ <code class="filename">+CONTENTS</code>.</p></li>
+<li class="listitem"><p><code class="varname">BUILDLINK_FNAME_TRANSFORM.<em class="replaceable"><code>pkg</code></em></code>
+ (not shown above) is a list of sed arguments used to
+ transform the name of the source filename into a
+ destination filename, e.g. <span class="command"><strong>-e
+ "s|/curses.h|/ncurses.h|g"</strong></span>.</p></li>
+</ul></div>
+<p>This section can additionally include any
+ <code class="filename">buildlink3.mk</code> needed for
+ <em class="replaceable"><code>pkg</code></em>'s library dependencies.
+ Including these <code class="filename">buildlink3.mk</code> files
+ means that the headers and libraries for these
+ dependencies are also symlinked into
+ <code class="filename">${BUILDLINK_DIR}</code>
+ whenever the <em class="replaceable"><code>pkg</code></em>
+ <code class="filename">buildlink3.mk</code>
+ file is included. Dependencies are only added for directly
+ include <code class="filename">buildlink3.mk</code> files.</p>
+<p>When providing a <code class="filename">buildlink3.mk</code> and
+ including other <code class="filename">buildlink3.mk</code> files in it,
+ please only add necessary ones, i.e., those whose libraries or
+ header files are automatically exposed when the package is
+ use.</p>
+<p>In particular, if only an executable
+ (<code class="filename">bin/foo</code>) is linked against a library, that
+ library does not need to be propagated in the
+ <code class="filename">buildlink3.mk</code> file.</p>
+<p>The following steps should help you decide if a
+ <code class="filename">buildlink3.mk</code> file needs to be included:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Look at the installed header files: What
+ headers do they include? The packages providing these files
+ must be buildlinked.</p></li>
+<li class="listitem"><p>Run <code class="filename">ldd</code> on all installed
+ libraries and look against what other libraries they link.
+ Some of the packages providing these probably need to be
+ buildlinked; however, it's not automatic, since e.g. GTK on
+ some systems pulls in the X libraries, so they will show up in
+ the <code class="filename">ldd</code> output, while on others (like OS
+ X) it won't. <code class="filename">ldd</code> output can thus only be
+ used as a hint.</p></li>
+</ul></div>
+<p>
+ </p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="updating-buildlink-depends"></a>18.2.2.�Updating
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ and
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ in <code class="filename">buildlink3.mk</code> files</h3></div></div></div>
+<p>These two variables differ in that one describes source
+ compatibility (API) and the other binary compatibility (ABI).
+ The difference is that a change in the API breaks compilation of
+ programs while changes in the ABI stop compiled programs from
+ running.</p>
+<p>Changes to the
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ variable in a <code class="filename">buildlink3.mk</code> file happen
+ very rarely. One possible reason is that all packages depending
+ on this already need a newer version. In case it is bumped see
+ the description below.</p>
+<p>The most common example of an ABI change is that the major
+ version of a shared library is increased. In this case,
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ should be adjusted to require at least the new package version.
+ Then the packages that depend on this package need their
+ <code class="varname">PKGREVISION</code>s increased and, if they have
+ <code class="filename">buildlink3.mk</code> files, their
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ adjusted, too. This is needed so pkgsrc will require the correct
+ package dependency and not settle for an older one when building
+ the source.</p>
+<p>See <a class="xref" href="#dependencies" title="21.1.5.�Handling dependencies">Section�21.1.5, “Handling dependencies”</a> for
+ more information about dependencies on other packages,
+ including the <code class="varname">BUILDLINK_ABI_DEPENDS</code> and
+ <code class="varname">ABI_DEPENDS</code> definitions.</p>
+<p>Please take careful consideration before adjusting
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ or
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ as we don't want to cause unneeded package deletions and
+ rebuilds. In many cases, new versions of packages work just
+ fine with older dependencies.</p>
+<p>Also it is not needed to set
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ when it is identical to
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>. </p>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.clean"></a>19.16.�Cleaning up</h2></div></div></div>
-<p>Once you're finished with a package, you can clean the work
- directory by running <span class="command"><strong>make clean</strong></span>. If you want
- to clean the work directories of all dependencies too, use
- <span class="command"><strong>make clean-depends</strong></span>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="build.helpful-targets"></a>19.17.�Other helpful targets</h2></div></div></div>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term">pre/post-*</span></dt>
-<dd><p>For any of the main targets described in the
- previous section, two auxiliary targets exist with
- <span class="quote">“<span class="quote">pre-</span>”</span> and <span class="quote">“<span class="quote">post-</span>”</span> used as a
- prefix for the main target's name. These targets are
- invoked before and after the main target is called,
- allowing extra configuration or installation steps be
- performed from a package's Makefile, for example, which
- a program's configure script or install target
- omitted.</p></dd>
-<dt><span class="term">do-*</span></dt>
-<dd><p>Should one of the main targets do the wrong thing,
- and should there be no variable to fix this, you can
- redefine it with the do-* target. (Note that redefining
- the target itself instead of the do-* target is a bad
- idea, as the pre-* and post-* targets won't be called
- anymore, etc.) You will not usually need to do
- this.</p></dd>
-<dt><span class="term">reinstall</span></dt>
-<dd>
-<p>If you did a <span class="command"><strong>make install</strong></span> and
- you noticed some file was not installed properly, you
- can repeat the installation with this target, which will
- ignore the <span class="quote">“<span class="quote">already installed</span>”</span> flag.</p>
-<p>This is the default value of
- <code class="varname">DEPENDS_TARGET</code> except in the case of
- <span class="command"><strong>make update</strong></span> and <span class="command"><strong>make
- package</strong></span>, where the defaults are
- <span class="quote">“<span class="quote">package</span>”</span> and <span class="quote">“<span class="quote">update</span>”</span>,
- respectively.</p>
-</dd>
-<dt><span class="term">deinstall</span></dt>
-<dd>
-<p>This target does a <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_delete</span>(1)</span></a> in the
- current directory, effectively de-installing the
- package. The following variables can be used to tune the
- behaviour:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">PKG_VERBOSE</code></span></dt>
-<dd><p>Add a "-v" to the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_delete</span>(1)</span></a> command.</p></dd>
-<dt><span class="term"><code class="varname">DEINSTALLDEPENDS</code></span></dt>
-<dd><p>Remove all packages that require (depend on)
- the given package. This can be used to remove any
- packages that may have been pulled in by a given
- package, e.g. if <span class="command"><strong>make deinstall
- DEINSTALLDEPENDS=1</strong></span> is done in
- <code class="filename">pkgsrc/x11/kde</code>, this is
- likely to remove whole KDE. Works by adding
- <span class="quote">“<span class="quote">-R</span>”</span> to the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1.i386+NetBSD-9.0";><span
class="citerefentry"><span class="refentrytitle">pkg_delete</span>(1)</span></a>
- command line.</p></dd>
-</dl></div>
-</dd>
-<dt><span class="term">bin-install</span></dt>
-<dd><p>Install a binary package from local disk and via FTP
- from a list of sites (see the
- <code class="varname">BINPKG_SITES</code> variable), and do a
- <span class="command"><strong>make package</strong></span> if no binary package is
- available anywhere. The arguments given to
- <span class="command"><strong>pkg_add</strong></span> can be set via
- <code class="varname">BIN_INSTALL_FLAGS</code> e.g., to do verbose
- operation, etc.</p></dd>
-<dt><span class="term">install-clean</span></dt>
-<dd><p>This target removes the state files for the "install" and later
- phases so that the "install" target may be re-invoked. This can be
- used after editing the PLIST to install the package without
- rebuilding it.</p></dd>
-<dt><span class="term">build-clean</span></dt>
-<dd><p>This target removes the state files for the "build" and later
- phases so that the "build" target may be re-invoked.</p></dd>
-<dt><span class="term">update</span></dt>
-<dd>
-<p>This target causes the current package to be
- updated to the latest version. The package and all
- depending packages first get de-installed, then current
- versions of the corresponding packages get compiled and
- installed. This is similar to manually noting which
- packages are currently installed, then performing a
- series of <span class="command"><strong>make deinstall</strong></span> and
- <span class="command"><strong>make install</strong></span> (or whatever
- <code class="varname">UPDATE_TARGET</code> is set to) for these
- packages.</p>
-<p>You can use the <span class="quote">“<span class="quote">update</span>”</span> target to
- resume package updating in case a previous <span class="command"><strong>make
- update</strong></span> was interrupted for some reason.
- However, in this case, make sure you don't call
- <span class="command"><strong>make clean</strong></span> or otherwise remove the
- list of dependent packages in <code class="varname">WRKDIR</code>.
- Otherwise, you lose the ability to automatically update
- the current package along with the dependent packages
- you have installed.</p>
-<p>Resuming an interrupted <span class="command"><strong>make
- update</strong></span> will only work as long as the package
- tree remains unchanged. If the source code for one of
- the packages to be updated has been changed, resuming
- <span class="command"><strong>make update</strong></span> will most certainly
- fail!</p>
-<p>The following variables can be used either on the
- command line or in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> to
- alter the behaviour of <span class="command"><strong>make
- update</strong></span>:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">UPDATE_TARGET</code></span></dt>
-<dd><p>Install target to recursively use for the
- updated package and the dependent packages.
- Defaults to <code class="varname">DEPENDS_TARGET</code> if
- set, <span class="quote">“<span class="quote">install</span>”</span> otherwise for
- <span class="command"><strong>make update</strong></span>. Other good
- targets are <span class="quote">“<span class="quote">package</span>”</span> or
- <span class="quote">“<span class="quote">bin-install</span>”</span>. Do not set this to
- <span class="quote">“<span class="quote">update</span>”</span> or you will get stuck in an
- endless loop!</p></dd>
-<dt><span class="term"><code class="varname">NOCLEAN</code></span></dt>
-<dd><p>Don't clean up after updating. Useful if
- you want to leave the work sources of the updated
- packages around for inspection or other purposes.
- Be sure you eventually clean up the source tree
- (see the <span class="quote">“<span class="quote">clean-update</span>”</span> target below)
- or you may run into troubles with old source code
- still lying around on your next
- <span class="command"><strong>make</strong></span> or <span class="command"><strong>make
- update</strong></span>.</p></dd>
-<dt><span class="term"><code class="varname">REINSTALL</code></span></dt>
-<dd><p>Deinstall each package before installing
- (making <code class="varname">DEPENDS_TARGET</code>). This
- may be necessary if the
- <span class="quote">“<span class="quote">clean-update</span>”</span> target (see below) was
- called after interrupting a running <span class="command"><strong>make
- update</strong></span>.</p></dd>
-<dt><span class="term"><code class="varname">DEPENDS_TARGET</code></span></dt>
-<dd><p>Allows you to disable recursion and hardcode
- the target for packages. The default is
- <span class="quote">“<span class="quote">update</span>”</span> for the update target,
- facilitating a recursive update of prerequisite
- packages. Only set
- <code class="varname">DEPENDS_TARGET</code> if you want to
- disable recursive updates. Use
- <code class="varname">UPDATE_TARGET</code> instead to just
- set a specific target for each package to be
- installed during <span class="command"><strong>make update</strong></span>
- (see above).</p></dd>
-</dl></div>
-</dd>
-<dt><span class="term">clean-update</span></dt>
-<dd>
-<p>Clean the source tree for all packages that would
- get updated if <span class="command"><strong>make update</strong></span> was called
- from the current directory. This target should not be
- used if the current package (or any of its depending
- packages) have already been de-installed (e.g., after
- calling <span class="command"><strong>make update</strong></span>) or you may lose
- some packages you intended to update. As a rule of
- thumb: only use this target <span class="emphasis"><em>before</em></span>
- the first time you run <span class="command"><strong>make update</strong></span>
- and only if you have a dirty package tree (e.g., if you
- used <code class="varname">NOCLEAN</code>).</p>
-<p>If you are unsure about whether your tree is
- clean, you can either perform a <span class="command"><strong>make
- clean</strong></span> at the top of the tree, or use the
- following sequence of commands from the directory of the
- package you want to update (<span class="emphasis"><em>before</em></span>
- running <span class="command"><strong>make update</strong></span> for the first
- time, otherwise you lose all the packages you wanted to
- update!):</p>
+<a name="writing-builtin.mk"></a>18.3.�Writing <code class="filename">builtin.mk</code> files</h2></div></div></div>
+<p>Some packages in pkgsrc install headers and libraries that
+ coincide with headers and libraries present in the base system.
+ Aside from a <code class="filename">buildlink3.mk</code> file, these
+ packages should also include a <code class="filename">builtin.mk</code>
+ file that includes the necessary checks to decide whether using
+ the built-in software or the pkgsrc software is
+ appropriate.</p>
+<p>The only requirements of a builtin.mk file for
+ <em class="replaceable"><code>pkg</code></em> are:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>It should set
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ to either <span class="quote">“<span class="quote">yes</span>”</span> or <span class="quote">“<span class="quote">no</span>”</span>
+ after it is included.</p></li>
+<li class="listitem"><p>It should <span class="emphasis"><em>not</em></span> override any
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ which is already set before the
+ <code class="filename">builtin.mk</code> file is included.</p></li>
+<li class="listitem"><p>It should be written to allow multiple inclusion. This
+ is <span class="emphasis"><em>very</em></span> important and takes careful
+ attention to <code class="filename">Makefile</code> coding.</p></li>
+</ol></div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="anatomy-of-builtin.mk"></a>18.3.1.�Anatomy of a <code class="filename">builtin.mk</code> file</h3></div></div></div>
+<p>The following is the recommended template for builtin.mk
+ files:</p>
+<pre class="programlisting">
+.if !defined(IS_BUILTIN.foo)
+#
+# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
+# genuinely exists in the system or not.
+#
+IS_BUILTIN.foo?= no
+
+# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
+# version can be determined.
+#
+. if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
+BUILTIN_PKG.foo?= foo-1.0
+. endif
+.endif # IS_BUILTIN.foo
+
+.if !defined(USE_BUILTIN.foo)
+USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
+. if defined(BUILTIN_PKG.foo)
+. for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
+. if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
+USE_BUILTIN.foo!= \
+ ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo} \
+ && ${ECHO} "yes" || ${ECHO} "no"
+. endif
+. endfor
+. endif
+.endif # USE_BUILTIN.foo
+
+CHECK_BUILTIN.foo?= no
+.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
+#
+# Here we place code that depends on whether USE_BUILTIN.foo is set to
+# "yes" or "no".
+#
+.endif # CHECK_BUILTIN.foo
+</pre>
+<p>The first section sets
+ <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ depending on if <em class="replaceable"><code>pkg</code></em> really exists
+ in the base system. This should not be a base system software
+ with similar functionality to <em class="replaceable"><code>pkg</code></em>;
+ it should only be <span class="quote">“<span class="quote">yes</span>”</span> if the actual package is
+ included as part of the base system. This variable is only
+ used internally within the <code class="filename">builtin.mk</code>
+ file.</p>
+<p>The second section sets
+ <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
+ to the version of <em class="replaceable"><code>pkg</code></em> in the base
+ system if it exists (if
+ <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ is <span class="quote">“<span class="quote">yes</span>”</span>). This variable is only used internally
+ within the <code class="filename">builtin.mk</code> file.</p>
+<p>The third section sets
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ and is <span class="emphasis"><em>required</em></span> in all
+ <code class="filename">builtin.mk</code> files. The code in this
+ section must make the determination whether the built-in
+ software is adequate to satisfy the dependencies listed in
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
+ This is typically done by comparing
+ <code class="varname">BUILTIN_PKG.<em class="replaceable"><code>pkg</code></em></code>
+ against each of the dependencies in
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>.
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ <span class="emphasis"><em>must</em></span> be set to the correct value by the
+ end of the <code class="filename">builtin.mk</code> file. Note that
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ may be <span class="quote">“<span class="quote">yes</span>”</span> even if
+ <code class="varname">IS_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ is <span class="quote">“<span class="quote">no</span>”</span> because we may make the determination
+ that the built-in version of the software is similar enough to
+ be used as a replacement.</p>
+<p>The last section is guarded by
+ <code class="varname">CHECK_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>,
+ and includes code that uses the value of
+ <code class="varname">USE_BUILTIN.<em class="replaceable"><code>pkg</code></em></code>
+ set in the previous section. This typically includes, e.g.,
+ adding additional dependency restrictions and listing additional
+ files to symlink into <code class="filename">${BUILDLINK_DIR}</code> (via
+ <code class="varname">BUILDLINK_FILES.<em class="replaceable"><code>pkg</code></em></code>).</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="native-or-pkgsrc-preference"></a>18.3.2.�Global preferences for native or pkgsrc software</h3></div></div></div>
+<p>When building packages, it's possible to choose whether to set
+ a global preference for using either the built-in (native)
+ version or the pkgsrc version of software to satisfy a
+ dependency. This is controlled by setting
+ <code class="varname">PREFER_PKGSRC</code> and
+ <code class="varname">PREFER_NATIVE</code>. These variables take values
+ of either <span class="quote">“<span class="quote">yes</span>”</span>, <span class="quote">“<span class="quote">no</span>”</span>, or a list of
+ packages. <code class="varname">PREFER_PKGSRC</code> tells pkgsrc to
+ use the pkgsrc versions of software, while
+ <code class="varname">PREFER_NATIVE</code> tells pkgsrc to use the
+ built-in versions. Preferences are determined by the most
+ specific instance of the package in either
+ <code class="varname">PREFER_PKGSRC</code> or
+ <code class="varname">PREFER_NATIVE</code>. If a package is specified
+ in neither or in both variables, then
+ <code class="varname">PREFER_PKGSRC</code> has precedence over
+ <code class="varname">PREFER_NATIVE</code>. For example, to require
+ using pkgsrc versions of software for all but the most basic
+ bits on a NetBSD system, you can set:</p>
+<pre class="programlisting">
+PREFER_PKGSRC= yes
+PREFER_NATIVE= getopt skey tcp_wrappers
+</pre>
+<p>A package <span class="emphasis"><em>must</em></span> have a
+ <code class="filename">builtin.mk</code>
+ file to be listed in <code class="varname">PREFER_NATIVE</code>,
+ otherwise it is simply ignored in that list.</p>
+<p>Setting <code class="varname">PREFER_NATIVE</code> should be performed
+ straight after bootstrap and <code class="varname">PREFER_PKGSRC</code> during
+ bootstrap.
+ Switching between settings globally at a later date can introduce
+ complications with dependency resolution. This is caused by packages
+ built with the opposite preference being installed alongside each other.</p>
<pre class="screen">
-<code class="prompt">#</code> <strong class="userinput"><code>make clean-update</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make update</code></strong>
- </pre>
-<p>The following variables can be used either on the
- command line or in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> to alter the behaviour of
- <span class="command"><strong>make clean-update</strong></span>:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><code class="varname">CLEAR_DIRLIST</code></span></dt>
-<dd><p>After <span class="command"><strong>make clean</strong></span>, do not
- reconstruct the list of directories to update for
- this package. Only use this if <span class="command"><strong>make
- update</strong></span> successfully installed all
- packages you wanted to update. Normally, this is
- done automatically on <span class="command"><strong>make
- update</strong></span>, but may have been suppressed by
- the <code class="varname">NOCLEAN</code> variable (see
- above).</p></dd>
-</dl></div>
-</dd>
-<dt><span class="term">replace</span></dt>
-<dd>
-<p>Update the installation of the current package. This
- differs from update in that it does not replace dependent
- packages. You will need to install <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_tarup/README.html"; target="_top"><code
class="filename">pkgtools/pkg_tarup</code></a> for this
- target to work.</p>
-<p><span class="emphasis"><em>Be careful when using this
- target!</em></span> There are no guarantees that dependent
- packages will still work, in particular they will most
- certainly break if you <span class="command"><strong>make replace</strong></span> a
- library package whose shared library major version changed
- between your installed version and the new one. For this
- reason, this target is not officially supported and only
- recommended for advanced users.</p>
-</dd>
-<dt><span class="term">info</span></dt>
-<dd><p>This target invokes <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">pkg_info</span>(1)</span></a> for the current
- package. You can use this to check which version of a
- package is installed.</p></dd>
-<dt><span class="term">index</span></dt>
-<dd>
-<p>This is a top-level command, i.e. it should be used in
- the <code class="filename">pkgsrc</code> directory. It creates a
- database of all packages in the local pkgsrc tree, including
- dependencies, comment, maintainer, and some other useful
- information. Individual entries are created by running
- <span class="command"><strong>make describe</strong></span> in the packages'
- directories. This index file is saved as
- <code class="filename">pkgsrc/INDEX</code>. It can be displayed in
- verbose format by running <span class="command"><strong>make
- print-index</strong></span>. You can search in it with
- <span class="command"><strong>make search
- key=<em class="replaceable"><code>something</code></em></strong></span>. You can
- extract a list of all packages that depend on a particular
- one by running <span class="command"><strong>make show-deps
- PKG=<em class="replaceable"><code>somepackage</code></em></strong></span>.</p>
-<p>Running this command takes a very long time, some
- hours even on fast machines!</p>
-</dd>
-<dt><span class="term">readme</span></dt>
-<dd>
-<p>This target generates a
- <code class="filename">README.html</code> file, which can be
- viewed using a browser such as <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a> or <a
href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/links/README.html"; target="_top"><code class="filename">www/links</code></a>. The generated files
- contain references to any packages which are in the
- <code class="varname">PACKAGES</code> directory on the local
- host. The generated files can be made to refer to URLs
- based on <code class="varname">FTP_PKG_URL_HOST</code> and
- <code class="varname">FTP_PKG_URL_DIR</code>. For example, if I
- wanted to generate <code class="filename">README.html</code>
- files which pointed to binary packages on the local
- machine, in the directory
- <code class="filename">/usr/packages</code>, set
- <code class="varname">FTP_PKG_URL_HOST=file://localhost</code> and
- <code class="varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
- <code class="varname">${PACKAGES}</code> directory and its
- subdirectories will be searched for all the binary
- packages.</p>
-<p>The target can be run at the toplevel or in category
- directories, in which case it descends recursively.</p>
-</dd>
-<dt><span class="term">readme-all</span></dt>
-<dd><p>This is a top-level command, run it in
- <code class="filename">pkgsrc</code>. Use this target to create a
- file <code class="filename">README-all.html</code> which contains a
- list of all packages currently available in the NetBSD
- Packages Collection, together with the category they belong
- to and a short description. This file is compiled from the
- <code class="filename">pkgsrc/*/README.html</code> files, so be sure
- to run this <span class="emphasis"><em>after</em></span> a <span class="command"><strong>make
- readme</strong></span>.</p></dd>
-<dt><span class="term">cdrom-readme</span></dt>
-<dd><p>This is very much the same as the
- <span class="quote">“<span class="quote">readme</span>”</span> target (see above), but is to be
- used when generating a pkgsrc tree to be written to a
- CD-ROM. This target also produces
- <code class="filename">README.html</code> files, and can be made
- to refer to URLs based on
- <code class="varname">CDROM_PKG_URL_HOST</code> and
- <code class="varname">CDROM_PKG_URL_DIR</code>.</p></dd>
-<dt><span class="term">show-distfiles</span></dt>
-<dd><p>This target shows which distfiles and patchfiles
- are needed to build the package
- (<code class="varname">ALLFILES</code>, which contains all
- <code class="varname">DISTFILES</code> and
- <code class="varname">PATCHFILES</code>, but not
- <code class="filename">patches/*</code>).</p></dd>
-<dt><span class="term">show-downlevel</span></dt>
-<dd><p>This target shows nothing if the package is not
- installed. If a version of this package is installed,
- but is not the version provided in this version of
- pkgsrc, then a warning message is displayed. This target
- can be used to show which of your installed packages are
- downlevel, and so the old versions can be deleted, and
- the current ones added.</p></dd>
-<dt><span class="term">show-pkgsrc-dir</span></dt>
-<dd><p>This target shows the directory in the pkgsrc
- hierarchy from which the package can be built and
- installed. This may not be the same directory as the one
- from which the package was installed. This target is
- intended to be used by people who may wish to upgrade
- many packages on a single host, and can be invoked from
- the top-level pkgsrc Makefile by using the
- <span class="quote">“<span class="quote">show-host-specific-pkgs</span>”</span> target.</p></dd>
-<dt><span class="term">show-installed-depends</span></dt>
-<dd><p>This target shows which installed packages match
- the current package's <code class="varname">DEPENDS</code>. Useful
- if out of date dependencies are causing build
- problems.</p></dd>
-<dt><span class="term">print-build-depends-list</span></dt>
-<dd><p>This target shows the list of packages that the current package
- depends on for building.</p></dd>
-<dt><span class="term">print-run-depends-list</span></dt>
-<dd><p>This target shows the list of packages that the current package
- depends on for running.</p></dd>
-<dt><span class="term">check-shlibs</span></dt>
-<dd><p>After a package is installed, check all its
- binaries and (on ELF platforms) shared libraries to see
- if they find the shared libs they need. Run by default
- if <code class="varname">PKG_DEVELOPER</code> is set in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p></dd>
-<dt><span class="term">print-PLIST</span></dt>
+<code class="prompt">#</code> <strong class="userinput"><code>./bootstrap --prefer-pkgsrc yes</code></strong>
+</pre>
+</div>
+</div>
+</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="plist"></a>Chapter�19.�PLIST issues</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#rcs-id">19.1. RCS ID</a></span></dt>
+<dt><span class="sect1"><a href="#automatic-plist-generation">19.2. Semi-automatic <code class="filename">PLIST</code> generation</a></span></dt>
+<dt><span class="sect1"><a href="#print-PLIST">19.3. Tweaking output of <span class="command"><strong>make print-PLIST</strong></span></a></span></dt>
+<dt><span class="sect1"><a href="#plist.misc">19.4. Variable substitution in PLIST</a></span></dt>
+<dt><span class="sect1"><a href="#manpage-compression">19.5. Man page compression</a></span></dt>
+<dt><span class="sect1"><a href="#using-PLIST_SRC">19.6. Changing PLIST source with <code class="varname">PLIST_SRC</code></a></span></dt>
+<dt><span class="sect1"><a href="#platform-specific-plist">19.7. Platform-specific and differing PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#build-plist">19.8. Build-specific PLISTs</a></span></dt>
+<dt><span class="sect1"><a href="#faq.common-dirs">19.9. Sharing directories between packages</a></span></dt>
+</dl>
+</div>
+<p>The <code class="filename">PLIST</code> file contains a package's
+ <span class="quote">“<span class="quote">packing list</span>”</span>, i.e. a list of files that belong to
+ the package (relative to the <code class="filename">${PREFIX}</code>
+ directory it's been installed in) plus some additional statements
+ - see the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">pkg_create</span>(1)</span></a>
man page for a full list.
+ This chapter addresses some issues that need attention when
+ dealing with the <code class="filename">PLIST</code> file (or files, see
+ below!).</p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="rcs-id"></a>19.1.�RCS ID</h2></div></div></div>
+<p>Be sure to add a RCS ID line as the first thing in any
+ <code class="filename">PLIST</code> file you write:</p>
+<pre class="programlisting">
+@comment $NetBSD $
+</pre>
+<p>An artificial space has been added between NetBSD and $, this is a
+workaround here to prevent CVS expanding to the filename of the guide. When
+adding the RCS ID the space should be omitted.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="automatic-plist-generation"></a>19.2.�Semi-automatic <code class="filename">PLIST</code> generation</h2></div></div></div>
+<p>You can use the <span class="command"><strong>make print-PLIST</strong></span> command
+ to output a PLIST that matches any new files since the package
+ was extracted. See <a class="xref" href="#build.helpful-targets" title="13.17.�Other helpful targets">Section�13.17, “Other helpful targets”</a> for
+ more information on this target.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="print-PLIST"></a>19.3.�Tweaking output of <span class="command"><strong>make print-PLIST</strong></span>
+</h2></div></div></div>
+<p>The <code class="varname">PRINT_PLIST_AWK</code> variable takes a set
+ of AWK patterns and actions that are used to filter the output of
+ print-PLIST. You can <span class="emphasis"><em>append</em></span> any chunk of AWK
+ scripting you like to it, but be careful with quoting.</p>
+<p>For example, to get all files inside the
+ <code class="filename">libdata/foo</code> directory removed from the
+ resulting PLIST:</p>
+<pre class="programlisting">
+PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
+</pre>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="plist.misc"></a>19.4.�Variable substitution in PLIST</h2></div></div></div>
+<p>A number of variables are substituted automatically in
+ PLISTs when a package is installed on a system. This includes the
+ following variables:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="varname">${MACHINE_ARCH}</code>, <code class="varname">${MACHINE_GNU_ARCH}</code></span></dt>
<dd>
-<p>After a <span class="quote">“<span class="quote">make install</span>”</span> from a new or
- upgraded pkg, this prints out an attempt to generate a
- new <code class="filename">PLIST</code> from a <span class="command"><strong>find
- -newer work/.extract_done</strong></span>. An attempt is made
- to care for shared libs etc., but it is
- <span class="emphasis"><em>strongly</em></span> recommended to review the
- result before putting it into
- <code class="filename">PLIST</code>. On upgrades, it's useful to
- diff the output of this command against an already
- existing <code class="filename">PLIST</code> file.</p>
-<p>If the package installs files via <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?tar+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">tar</span>(1)</span></a> or
- other methods that don't update file access times, be
- sure to add these files manually to your
- <code class="filename">PLIST</code>, as the <span class="quote">“<span class="quote">find
- -newer</span>”</span> command used by this target won't catch
- them!</p>
-<p>See <a class="xref" href="#print-PLIST" title="15.3.�Tweaking output of make print-PLIST">Section�15.3, “Tweaking output of <span class="command"><strong>make
print-PLIST</strong></span>”</a> for more
- information on this target.</p>
+<p>Some packages like emacs and perl embed information
+ about which architecture they were built on into the
+ pathnames where they install their files. To handle this
+ case, PLIST will be preprocessed before actually used, and
+ the symbol
+ <span class="quote">“<span class="quote"><code class="varname">${MACHINE_ARCH}</code></span>”</span> will be
+ replaced by what <span class="command"><strong>uname -p</strong></span> gives. The
+ same is done if the string
+ <code class="varname">${MACHINE_GNU_ARCH}</code> is embedded in
+ PLIST somewhere - use this on packages that have GNU
+ autoconf-created configure scripts.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">Legacy note</h3>
+<p>There used to be a symbol
+ <span class="quote">“<span class="quote"><code class="varname">$ARCH</code></span>”</span> that
+ was replaced by the output of <span class="command"><strong>uname
+ -m</strong></span>, but that's no longer supported and has
+ been removed.</p>
+</div>
+</dd>
+<dt><span class="term"><code class="varname">${OPSYS}</code>, <code class="varname">${LOWER_OPSYS}</code>, <code class="varname">${OS_VERSION}</code></span></dt>
+<dd>
+<p>Some packages want to embed the OS name and version
+ into some paths. To do this, use these variables in the
+ <code class="filename">PLIST</code>:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">${OPSYS}</code> - output of <span class="quote">“<span class="quote"><span class="command"><strong>uname
-s</strong></span></span>”</span></p></li>
+<li class="listitem"><p><code class="varname">${LOWER_OPSYS}</code> - lowercase common name (eg. <span class="quote">“<span class="quote">solaris</span>”</span>)</p></li>
+<li class="listitem"><p><code class="varname">${OS_VERSION}</code> - <span class="quote">“<span class="quote"><span class="command"><strong>uname
-r</strong></span></span>”</span></p></li>
+</ul></div>
</dd>
</dl></div>
+<p>For a list of values which are replaced by
+ default, the output of <span class="command"><strong>make help topic=PLIST_SUBST</strong></span> as
+well as searching the <code class="filename">pkgsrc/mk</code> directory with <span class="command"><strong>grep</strong></span> for
+<code class="varname">PLIST_SUBST</code> should help.</p>
+<p>If you want to change other variables not listed above, you
+ can add variables and their expansions to this variable in the
+ following way, similar to <code class="varname">MESSAGE_SUBST</code> (see <a class="xref" href="#components.optional" title="12.5.�Optional files">Section�12.5, “Optional
files”</a>):</p>
+<pre class="programlisting">
+PLIST_SUBST+= SOMEVAR="somevalue"
+</pre>
+<p>This replaces all occurrences of <span class="quote">“<span class="quote">${SOMEVAR}</span>”</span>
+ in the <code class="filename">PLIST</code> with
+ <span class="quote">“<span class="quote">somevalue</span>”</span>.</p>
+<p>The <code class="varname">PLIST_VARS</code> variable can be used to simplify
+ the common case of conditionally including some
+ <code class="filename">PLIST</code> entries. It can be done by adding
+ <code class="literal"><code class="varname">PLIST_VARS</code>+=foo</code> and
+ setting the corresponding <code class="varname">PLIST.foo</code> variable
+ to <code class="literal">yes</code> if the entry should be included.
+ This will substitute <span class="quote">“<span class="quote"><code class="varname">${PLIST.foo}</code></span>”</span>
+ in the <code class="filename">PLIST</code> with either
+ <span class="quote">“<span class="quote"><code class="literal">""</code></span>”</span> or
+ <span class="quote">“<span class="quote"><code class="literal">"@comment "</code></span>”</span>.
+ For example, in <code class="filename">Makefile</code>:</p>
+<pre class="programlisting">
+PLIST_VARS+= foo
+.if <em class="replaceable"><code>condition</code></em>
+PLIST.foo= yes
+.else
+</pre>
+<p>And then in <code class="filename">PLIST</code>:</p>
+<pre class="programlisting">
+@comment $NetBSD $
+bin/bar
+man/man1/bar.1
+${PLIST.foo}bin/foo
+${PLIST.foo}man/man1/foo.1
+${PLIST.foo}share/bar/foo.data
+</pre>
+<p>An artificial space has been added between NetBSD and $, this is a
+workaround here to prevent CVS expanding to the filename of the guide. When
+adding the RCS ID the space should be ommited.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="manpage-compression"></a>19.5.�Man page compression</h2></div></div></div>
+<p>Man pages should be installed in compressed form if
+ <code class="varname">MANZ</code> is set (in <code class="filename">bsd.own.mk</code>),
+ and uncompressed otherwise. To handle this in the
+ <code class="filename">PLIST</code> file, the suffix <span class="quote">“<span class="quote">.gz</span>”</span> is
+ appended/removed automatically for man pages according to
+ <code class="varname">MANZ</code> and <code class="varname">MANCOMPRESSED</code> being set
+ or not, see above for details. This modification of the
+ <code class="filename">PLIST</code> file is done on a copy of it, not
+ <code class="filename">PLIST</code> itself.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="using-PLIST_SRC"></a>19.6.�Changing PLIST source with <code class="varname">PLIST_SRC</code>
+</h2></div></div></div>
+<p>To use one or more files as source for the <code class="filename">PLIST</code> used
+ in generating the binary package, set the variable
+ <code class="varname">PLIST_SRC</code> to the names of that file(s).
+ The files are later concatenated using <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?cat+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">cat</span>(1)</span></a>, and the order of things is
+ important. The default for <code class="varname">PLIST_SRC</code> is
+ <code class="filename">${PKGDIR}/PLIST</code>.</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="platform-specific-plist"></a>19.7.�Platform-specific and differing PLISTs</h2></div></div></div>
+<p>Some packages decide to install a different set of files based on
+ the operating system being used. These differences can be
+ automatically handled by using the following files:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="filename">PLIST.common</code></p></li>
+<li class="listitem"><p><code class="filename">PLIST.${OPSYS}</code></p></li>
+<li class="listitem"><p><code class="filename">PLIST.${MACHINE_ARCH}</code></p></li>
+<li class="listitem"><p><code class="filename">PLIST.${OPSYS}-${MACHINE_ARCH}</code></p></li>
+<li class="listitem"><p><code class="filename">PLIST.common_end</code></p></li>
+</ul></div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="build-plist"></a>19.8.�Build-specific PLISTs</h2></div></div></div>
+<p>Some packages decide to generate hard-to-guess file names
+ during installation that are hard to wire down.</p>
+<p>In such cases, you can set the
+ <code class="varname">GENERATE_PLIST</code> variable to shell code
+ terminated (with a semicolon) that will output PLIST entries which
+ will be appended to the PLIST</p>
+<p>You can find one example in editors/xemacs:</p>
+<pre class="programlisting">
+GENERATE_PLIST+= ${ECHO} bin/${DISTNAME}-`${WRKSRC}/src/xemacs -sd`.dmp ;
+</pre>
+<p>which will append something like
+ <code class="filename">bin/xemacs-21.4.23-54e8ea71.dmp</code> to the
+ <code class="filename">PLIST</code>.
+ </p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="faq.common-dirs"></a>19.9.�Sharing directories between packages</h2></div></div></div>
+<p>A <span class="quote">“<span class="quote">shared directory</span>”</span> is a directory where
+ multiple (and unrelated) packages install files. These
+ directories were problematic because you had to add special
+ tricks in the PLIST to conditionally remove them, or have some
+ centralized package handle them.</p>
+<p>In pkgsrc, it is now easy: Each package should create
+ directories and install files as needed; <span class="command"><strong>pkg_delete</strong></span>
+ will remove any directories left empty after uninstalling a
+ package.</p>
+<p>If a package needs an empty directory to work, create
+ the directory during installation as usual, and also add an
+ entry to the PLIST:
+
+</p>
+<pre class="programlisting">
+@pkgdir path/to/empty/directory
+</pre>
+<p>
+
+ or take a look at <code class="varname">MAKE_DIRS</code> and
+ <code class="varname">OWN_DIRS</code>.
+ </p>
+</div>
+</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="pkginstall"></a>Chapter�20.�The pkginstall framework</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#files-and-dirs-outside-prefix">20.1. Files and directories outside the installation prefix</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#dirs-outside-prefix">20.1.1. Directory manipulation</a></span></dt>
+<dt><span class="sect2"><a href="#files-outside-prefix">20.1.2. File manipulation</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#conf-files">20.2. Configuration files</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#conf-files-sysconfdir">20.2.1. How <code class="varname">PKG_SYSCONFDIR</code> is set</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-configure">20.2.2. Telling the software where configuration files are</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-patching">20.2.3. Patching installations</a></span></dt>
+<dt><span class="sect2"><a href="#conf-files-disable">20.2.4. Disabling handling of configuration files</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#rcd-scripts">20.3. System startup scripts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#rcd-scripts-disable">20.3.1. Disabling handling of system startup scripts</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#users-and-groups">20.4. System users and groups</a></span></dt>
+<dt><span class="sect1"><a href="#shells">20.5. System shells</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#shells-disable">20.5.1. Disabling shell registration</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="#fonts">20.6. Fonts</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#fonts-disable">20.6.1. Disabling automatic update of the fonts databases</a></span></dt></dl></dd>
+</dl>
+</div>
+<p>This chapter describes the framework known as
+<code class="literal">pkginstall</code>, whose key features are:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Generic installation and manipulation of directories and files
+ outside the pkgsrc-handled tree, <code class="varname">LOCALBASE</code>.</p></li>
+<li class="listitem"><p>Automatic handling of configuration files during installation,
+ provided that packages are correctly designed.</p></li>
+<li class="listitem"><p>Generation and installation of system startup scripts.</p></li>
+<li class="listitem"><p>Registration of system users and groups.</p></li>
+<li class="listitem"><p>Registration of system shells.</p></li>
+<li class="listitem"><p>Automatic updating of fonts databases.</p></li>
+</ul></div>
+<p>The following sections inspect each of the above points in detail.</p>
+<p>You may be thinking that many of the things described here could be
+easily done with simple code in the package's post-installation target
+(<code class="literal">post-install</code>). <span class="emphasis"><em>This is incorrect</em></span>,
+as the code in them is only executed when building from source. Machines
+using binary packages could not benefit from it at all (as the code itself
+could be unavailable). Therefore, the only way to achieve any of the items
+described above is by means of the installation scripts, which are
+automatically generated by pkginstall.</p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="files-and-dirs-outside-prefix"></a>20.1.�Files and directories outside the installation prefix</h2></div></div></div>
+<p>As you already know, the <code class="filename">PLIST</code> file holds a list
+of files and directories that belong to a package. The names used in it
+are relative to the installation prefix (<code class="filename">${PREFIX}</code>),
+which means that it cannot register files outside this directory (absolute
+path names are not allowed). Despite this restriction, some packages need
+to install files outside this location; e.g., under
+<code class="filename">${VARBASE}</code> or
+<code class="filename">${PKG_SYSCONFDIR}</code>. The only way to achieve this
+is to create such files during installation time by using
+installation scripts.</p>
+<p>The generic installation scripts are shell scripts that can
+contain arbitrary code. The list of scripts to execute is taken from
+the <code class="varname">INSTALL_FILE</code> variable, which defaults to
+<code class="filename">INSTALL</code>. A similar variable exists for package
+removal (<code class="varname">DEINSTALL_FILE</code>, whose default is
+<code class="filename">DEINSTALL</code>). These scripts can run arbitrary
+commands, so they have the potential to create and manage files
+anywhere in the file system.</p>
+<p>Using these general installation files is not recommended, but
+may be needed in some special cases. One reason for avoiding them is
+that the user has to trust the packager that there is no unwanted or
+simply erroneous code included in the installation script. Also,
+previously there were many similar scripts for the same functionality,
+and fixing a common error involved finding and changing all of
+them.</p>
+<p>The pkginstall framework offers another, standardized way. It
+provides generic scripts to abstract the manipulation of such files
+and directories based on variables set in the package's
+<code class="filename">Makefile</code>. The rest of this section describes
+these variables.</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="dirs-outside-prefix"></a>20.1.1.�Directory manipulation</h3></div></div></div>
+<p>The following variables can be set to request the creation of
+directories anywhere in the file system:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem">
+<p><code class="varname">MAKE_DIRS</code> and <code class="varname">OWN_DIRS</code>
+ contain a list of directories that should be created and should attempt
+ to be destroyed by the installation scripts. The difference between
+ the two is that the latter prompts the administrator to remove any
+ directories that may be left after deinstallation (because they were
+ not empty), while the former does not. Example:</p>
+<pre class="programlisting">
+MAKE_DIRS+= ${VARBASE}/foo/private
+</pre>
+</li>
+<li class="listitem">
+<p><code class="varname">MAKE_DIRS_PERMS</code> and
+ <code class="varname">OWN_DIRS_PERMS</code> contain a list of tuples describing
+ which directories should be created and should attempt to be destroyed
+ by the installation scripts. Each tuple holds the following values,
+ separated by spaces: the directory name, its owner, its group and its
+ numerical mode. For example:</p>
+<pre class="programlisting">
+MAKE_DIRS_PERMS+= ${VARBASE}/foo/private \
+ ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
+</pre>
+<p>The difference between the two is exactly the same as their
+ non-<code class="varname">PERMS</code> counterparts.</p>
+</li>
+</ul></div>
</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="files-outside-prefix"></a>20.1.2.�File manipulation</h3></div></div></div>
+<p>Creating non-empty files outside the installation prefix is tricky
+because the <code class="filename">PLIST</code> forces all files to be inside it.
+To overcome this problem, the only solution is to extract the file in the
+known place (i.e., inside the installation prefix) and copy it to the
+appropriate location during installation (done by the installation scripts
+generated by pkginstall). We will call the former the <span class="emphasis"><em>master
+file</em></span> in the following paragraphs, which describe the variables
+that can be used to automatically and consistently handle files outside the
+installation prefix:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem">
+<p><code class="varname">CONF_FILES</code> and
+ <code class="varname">REQD_FILES</code> are pairs of master and target files.
+ During installation time, the master file is copied to the target one
+ if and only if the latter does not exist. Upon deinstallation, the
+ target file is removed provided that it was not modified by the
+ installation.</p>
+<p>The difference between the two is that the latter prompts the
+ administrator to remove any files that may be left after
+ deinstallation (because they were not empty), while the former does
+ not.</p>
+</li>
+<li class="listitem">
+<p><code class="varname">CONF_FILES_PERMS</code> and
+ <code class="varname">REQD_FILES_PERMS</code> contain tuples describing master
+ files as well as their target locations. For each of them, it also
+ specifies their owner, their group and their numeric permissions, in
+ this order. For example:</p>
+<pre class="programlisting">
+REQD_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile \
+ ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
+</pre>
+<p>The difference between the two is exactly the same as their
+ non-<code class="varname">PERMS</code> counterparts.</p>
+</li>
+</ul></div>
</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="tools"></a>Chapter�20.�Tools needed for building or running</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#pkgsrc-tools">20.1. Tools for pkgsrc builds</a></span></dt>
-<dt><span class="sect1"><a href="#package-tools">20.2. Tools needed by packages</a></span></dt>
-<dt><span class="sect1"><a href="#platform-tools">20.3. Tools provided by platforms</a></span></dt>
-</dl>
</div>
-<p>The <code class="varname">USE_TOOLS</code> definition is used both internally
-by pkgsrc and also for individual packages to define what commands
-are needed for building a package (like <code class="varname">TOOL_DEPENDS</code>)
-or for later run-time of an installed packaged (such as
-<code class="varname">DEPENDS</code>).
-If the native system provides an adequate tool, then in many cases, a pkgsrc
-package will not be used.</p>
-<p>When building a package, the replacement tools are
-made available in a directory (as symlinks or wrapper scripts)
-that is early in the executable search path. Just like the buildlink
-system, this helps with consistent builds.</p>
-<p>A tool may be needed to help build a specific package. For example,
-perl, GNU make (gmake) or yacc may be needed.</p>
-<p>Also a tool may be needed, for example, because the native system's supplied
-tool may be inefficient for building a package with pkgsrc.
-For example, a package may need GNU awk, bison (instead of
-yacc) or a better sed.</p>
-<p>The tools used by a package can be listed by running
-<span class="command"><strong>make show-tools</strong></span>.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="pkgsrc-tools"></a>20.1.�Tools for pkgsrc builds</h2></div></div></div>
-<p>The default set of tools used by pkgsrc is defined in
-<code class="filename">bsd.pkg.mk</code>. This includes standard Unix tools,
-such as: <span class="command"><strong>cat</strong></span>, <span class="command"><strong>awk</strong></span>,
-<span class="command"><strong>chmod</strong></span>, <span class="command"><strong>test</strong></span>, and so on.
-These can be seen by running:
-<span class="command"><strong>make show-var VARNAME=USE_TOOLS</strong></span>.</p>
-<p>If a package needs a specific program to build
-then the <code class="varname">USE_TOOLS</code> variable can be used
-to define the tools needed.</p>
+<a name="conf-files"></a>20.2.�Configuration files</h2></div></div></div>
+<p>Configuration files are special in the sense that they are installed
+in their own specific directory, <code class="varname">PKG_SYSCONFDIR</code>, and
+need special treatment during installation (most of which is automated by
+pkginstall). The main concept you must bear in mind is that files marked
+as configuration files are automatically copied to the right place (somewhere
+inside <code class="varname">PKG_SYSCONFDIR</code>) during installation <span class="emphasis"><em>if
+and only if</em></span> they didn't exist before. Similarly, they will not
+be removed if they have local modifications. This ensures that
+administrators never lose any custom changes they may have made.</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="conf-files-sysconfdir"></a>20.2.1.�How <code class="varname">PKG_SYSCONFDIR</code> is set</h3></div></div></div>
+<p>As said before, the <code class="varname">PKG_SYSCONFDIR</code> variable
+specifies where configuration files shall be installed. Its contents are
+set based upon the following variables:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><code class="varname">PKG_SYSCONFBASE</code>: The configuration's root
+ directory. Defaults to <code class="filename">${PREFIX}/etc</code> although it may
+ be overridden by the user to point to his preferred location (e.g.,
+ <code class="filename">/etc</code>, <code class="filename">/etc/pkg</code>, etc.).
+ Packages must not use it directly.</p></li>
+<li class="listitem">
+<p><code class="varname">PKG_SYSCONFSUBDIR</code>: A subdirectory of
+ <code class="varname">PKG_SYSCONFBASE</code> under which the configuration files
+ for the package being built shall be installed. The definition of this
+ variable only makes sense in the package's
+ <code class="filename">Makefile</code> (i.e., it is not user-customizable).</p>
+<p>As an example, consider the Apache package,
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/apache24/README.html"; target="_top"><code class="filename">www/apache24</code></a>, which places its
+ configuration files under the
+ <code class="filename">httpd/</code> subdirectory of
+ <code class="varname">PKG_SYSCONFBASE</code>. This should be set in the package
+ Makefile.</p>
+</li>
+<li class="listitem"><p><code class="varname">PKG_SYSCONFVAR</code>: Specifies the name of the
+ variable that holds this package's configuration directory (if
+ different from <code class="varname">PKG_SYSCONFBASE</code>). It defaults to
+ <code class="varname">PKGBASE</code>'s value, and is always prefixed with
+ <code class="literal">PKG_SYSCONFDIR</code>.</p></li>
+<li class="listitem"><p><code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>: Holds the
+ directory where the configuration files for the package identified by
+ <code class="varname">PKG_SYSCONFVAR</code>'s shall be placed.</p></li>
+</ul></div>
+<p>Based on the above variables, pkginstall determines the value of
+<code class="varname">PKG_SYSCONFDIR</code>, which is the <span class="emphasis"><em>only</em></span>
+variable that can be used within a package to refer to its configuration
+directory. The algorithm used to set its value is basically the
+following:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>If <code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> is set,
+ its value is used.</p></li>
+<li class="listitem"><p>If the previous variable is not defined but
+ <code class="varname">PKG_SYSCONFSUBDIR</code> is set in the package's
+ <code class="filename">Makefile</code>, the resulting value is
+ <code class="filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p></li>
+<li class="listitem"><p>Otherwise, it is set to
+ <code class="filename">${PKG_SYSCONFBASE}</code>.</p></li>
+</ol></div>
+<p>It is worth mentioning that <code class="filename">${PKG_SYSCONFDIR}</code> is
+automatically added to <code class="filename">OWN_DIRS</code>. See <a class="xref" href="#dirs-outside-prefix" title="20.1.1.�Directory manipulation">Section�20.1.1, “Directory
manipulation”</a> what this means. This does not apply to
+subdirectories of <code class="filename">${PKG_SYSCONFDIR}</code>, they still have to
+be created with OWN_DIRS or MAKE_DIRS.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="conf-files-configure"></a>20.2.2.�Telling the software where configuration files are</h3></div></div></div>
+<p>Given that pkgsrc (and users!) expect configuration files to be in a
+known place, you need to teach each package where it shall install its
+files. In some cases you will have to patch the package Makefiles to
+achieve it. If you are lucky, though, it may be as easy as passing an
+extra flag to the configuration script; this is the case of GNU Autoconf-
+generated files:</p>
+<pre class="programlisting">
+CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
+</pre>
+<p>Note that this specifies where the package has to <span class="emphasis"><em>look
+for</em></span> its configuration files, not where they will be originally
+installed (although the difference is never explicit,
+unfortunately).</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="conf-files-patching"></a>20.2.3.�Patching installations</h3></div></div></div>
+<p>As said before, pkginstall automatically handles configuration files.
+This means that <span class="strong"><strong>the packages themselves must not
+touch the contents of <code class="filename">${PKG_SYSCONFDIR}</code>
+directly</strong></span>. Bad news is that many software installation scripts
+will, out of the box, mess with the contents of that directory. So what is
+the correct procedure to fix this issue?</p>
+<p>You must teach the package (usually by manually patching it) to
+install any configuration files under the examples hierarchy,
+<code class="filename">share/examples/${PKGBASE}/</code>. This way, the
+<code class="filename">PLIST</code> registers them and the administrator always
+has the original copies available.</p>
+<p>Once the required configuration files are in place (i.e., under the
+examples hierarchy), the pkginstall framework can use them as master copies
+during the package installation to update what is in
+<code class="filename">${PKG_SYSCONFDIR}</code>. To achieve this, the variables
+<code class="varname">CONF_FILES</code> and <code class="varname">CONF_FILES_PERMS</code> are
+used. Check out <a class="xref" href="#files-outside-prefix" title="20.1.2.�File manipulation">Section�20.1.2, “File manipulation”</a> for information
+about their syntax and their purpose. Here is an example, taken from the
+<a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/mail/mutt/README.html"; target="_top"><code class="filename">mail/mutt</code></a> package:</p>
+<pre class="programlisting">
+EGDIR= ${PREFIX}/share/doc/mutt/samples
+CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
+</pre>
+<p>Note that the <code class="varname">EGDIR</code> variable is specific to that
+package and has no meaning outside it.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="conf-files-disable"></a>20.2.4.�Disabling handling of configuration files</h3></div></div></div>
+<p>The automatic copying of config files can be toggled by setting the
+environment variable <code class="varname">PKG_CONFIG</code> prior to package
+installation.</p>
+</div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="rcd-scripts"></a>20.3.�System startup scripts</h2></div></div></div>
+<p>System startup scripts are special files because they must be
+installed in a place known by the underlying OS, usually outside the
+installation prefix. Therefore, the same rules described in <a class="xref" href="#files-and-dirs-outside-prefix" title="20.1.�Files and directories outside the installation prefix">Section�20.1,
“Files and directories outside the installation prefix”</a> apply, and the same solutions
+can be used. However, pkginstall provides a special mechanism to handle
+these files.</p>
+<p>In order to provide system startup scripts, the package has
+to:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Store the script inside <code class="filename">${FILESDIR}</code>, with
+ the <code class="literal">.sh</code> suffix appended. Considering the
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/print/cups/README.html"; target="_top"><code class="filename">print/cups</code></a> package as an example, it has a
+ <code class="filename">cupsd.sh</code> in its files directory.</p></li>
+<li class="listitem">
+<p>Tell pkginstall to handle it, appending the name of the script,
+ without its extension, to the <code class="varname">RCD_SCRIPTS</code> variable.
+ Continuing the previous example:</p>
+<pre class="programlisting">
+RCD_SCRIPTS+= cupsd
+</pre>
+</li>
+</ol></div>
+<p>Once this is done, pkginstall will do the following steps for each
+script in an automated fashion:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Process the file found in the files directory applying all the
+ substitutions described in the <code class="filename">FILES_SUBST</code>
+ variable.</p></li>
+<li class="listitem"><p>Copy the script from the files directory to the examples
+ hierarchy, <code class="filename">${PREFIX}/share/examples/rc.d/</code>. Note
+ that this master file must be explicitly registered in the
+ <code class="filename">PLIST</code>.</p></li>
+<li class="listitem"><p>Add code to the installation scripts to copy the startup script
+ from the examples hierarchy into the system-wide startup scripts
+ directory.</p></li>
+</ol></div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="rcd-scripts-disable"></a>20.3.1.�Disabling handling of system startup scripts</h3></div></div></div>
+<p>The automatic copying of config files can be toggled by setting the
+environment variable <code class="varname">PKG_RCD_SCRIPTS</code> prior to package
+installation. Note that the scripts will be always copied inside the
+examples hierarchy, <code class="filename">${PREFIX}/share/examples/rc.d/</code>, no
+matter what the value of this variable is.</p>
+</div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="users-and-groups"></a>20.4.�System users and groups</h2></div></div></div>
+<p>If a package needs to create special users and/or groups during
+installation, it can do so by using the pkginstall framework.</p>
+<p>Users can be created by adding entries to the
+<code class="varname">PKG_USERS</code> variable. Each entry has the following
+syntax:</p>
+<pre class="programlisting">
+user:group
+</pre>
+<p>Further specification of user details may be done by setting
+per-user variables.
+<code class="varname">PKG_UID.<em class="replaceable"><code>user</code></em></code> is the
+numeric UID for the user.
+<code class="varname">PKG_GECOS.<em class="replaceable"><code>user</code></em></code> is the
+user's description or comment.
+<code class="varname">PKG_HOME.<em class="replaceable"><code>user</code></em></code> is the
+user's home directory, and defaults to
+<code class="filename">/nonexistent</code> if not specified.
+<code class="varname">PKG_SHELL.<em class="replaceable"><code>user</code></em></code> is the
+user's shell, and defaults to <code class="filename">/sbin/nologin</code> if
+not specified.</p>
+<p>Similarly, groups can be created by adding entries to the
+<code class="varname">PKG_GROUPS</code> variable, whose syntax is:</p>
+<pre class="programlisting">
+group
+</pre>
+<p>The numeric GID of the group may be set by defining
+<code class="varname">PKG_GID.<em class="replaceable"><code>group</code></em></code>.</p>
+<p>If a package needs to create the users and groups at an earlier
+stage, then it can set <code class="varname">USERGROUP_PHASE</code> to either
+<code class="literal">configure</code>,<code class="literal">build</code>, or
+<code class="literal">pre-install</code> to indicate the phase before which the
+users and groups are created. In this case, the numeric UIDs and GIDs
+of the created users and groups are automatically hardcoded into the
+final installation scripts.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="package-tools"></a>20.2.�Tools needed by packages</h2></div></div></div>
-<p>In the following examples, the :run means that it is needed at
-run-time (and becomes a DEPENDS).
-The default is a build dependency which can be set with
-:build. (So in this example, it is the same as gmake:build
-and pkg-config:build.)</p>
+<a name="shells"></a>20.5.�System shells</h2></div></div></div>
+<p>Packages that install system shells should register them in the shell
+database, <code class="filename">/etc/shells</code>, to make things easier to the
+administrator. This must be done from the installation scripts to keep
+binary packages working on any system. pkginstall provides an easy way to
+accomplish this task.</p>
+<p>When a package provides a shell interpreter, it has to set the
+<code class="varname">PKG_SHELL</code> variable to its absolute file name. This will
+add some hooks to the installation scripts to handle it. Consider the
+following example, taken from <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/shells/zsh/README.html"; target="_top"><code class="filename">shells/zsh</code></a>:</p>
<pre class="programlisting">
-USE_TOOLS+= gmake perl:run pkg-config
+PKG_SHELL= ${PREFIX}/bin/zsh
</pre>
-<p>When using the tools framework, a
-<code class="varname">TOOLS_PATH.foo</code> variable is defined
-which contains the full path to the appropriate tool. For example,
-<code class="varname">TOOLS_PATH.bash</code> could be <span class="quote">“<span class="quote">/bin/bash</span>”</span>
-on Linux systems.</p>
-<p>If you always need a pkgsrc version of the
-tool at run-time, then just use <code class="varname">DEPENDS</code> instead.
-</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="shells-disable"></a>20.5.1.�Disabling shell registration</h3></div></div></div>
+<p>The automatic registration of shell interpreters can be disabled by
+the administrator by setting the <code class="filename">PKG_REGISTER_SHELLS</code>
+environment variable to <code class="literal">NO</code>.</p>
+</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="platform-tools"></a>20.3.�Tools provided by platforms</h2></div></div></div>
-<p>When improving or porting pkgsrc to a new platform, have a look
-at (or create) the corresponding platform specific make file fragment under
-<code class="filename">pkgsrc/mk/tools/tools.${OPSYS}.mk</code> which defines
-the name of the common tools. For example:</p>
+<a name="fonts"></a>20.6.�Fonts</h2></div></div></div>
+<p>Packages that install X11 fonts should update the database files
+that index the fonts within each fonts directory. This can easily be
+accomplished within the pkginstall framework.</p>
+<p>When a package installs X11 fonts, it must list the directories in
+which fonts are installed in the
+<code class="varname">FONTS_DIRS.<em class="replaceable"><code>type</code></em></code> variables,
+where <em class="replaceable"><code>type</code></em> can be one of <span class="quote">“<span class="quote">ttf</span>”</span>,
+<span class="quote">“<span class="quote">type1</span>”</span> or <span class="quote">“<span class="quote">x11</span>”</span>. This will add hooks to the
+installation scripts to run the appropriate commands to update the fonts
+database files within each of those directories. For convenience, if the
+directory path is relative, it is taken to be relative to the package's
+installation prefix. Consider the following example, taken from <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/fonts/dbz-ttf/README.html"; target="_top"><code
class="filename">fonts/dbz-ttf</code></a>:</p>
<pre class="programlisting">
-.if exists(/usr/bin/bzcat)
-TOOLS_PLATFORM.bzcat?= /usr/bin/bzcat
-.elif exists(/usr/bin/bzip2)
-TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd
-.endif
-
-TOOLS_PLATFORM.true?= true # shell builtin
+FONTS_DIRS.ttf= ${PREFIX}/share/fonts/X11/TTF
</pre>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="fonts-disable"></a>20.6.1.�Disabling automatic update of the fonts databases</h3></div></div></div>
+<p>The automatic update of fonts databases can be disabled by
+the administrator by setting the <code class="filename">PKG_UPDATE_FONTS_DB</code>
+environment variable to <code class="literal">NO</code>.</p>
+</div>
</div>
</div>
<div class="chapter">
@@ -7469,14 +7489,14 @@ ACCEPTABLE_LICENSES+=xv-license
<code class="varname">USE_TOOLS</code> definition, as well as dependencies
via <code class="filename">buildlink3.mk</code>, which is the preferred way
to handle dependencies, and which uses the variables named above.
- See <a class="xref" href="#buildlink" title="Chapter�16.�Buildlink methodology">Chapter�16, <i>Buildlink methodology</i></a> for more information.</p>
+ See <a class="xref" href="#buildlink" title="Chapter�18.�Buildlink methodology">Chapter�18, <i>Buildlink methodology</i></a> for more information.</p>
<p>The basic difference is that the <code class="varname">DEPENDS</code>
definition registers that pre-requisite in the binary package so it
will be pulled in when the binary package is later installed, whilst
the <code class="varname">BUILD_DEPENDS</code>, <code class="varname">TOOL_DEPENDS</code>,
and <code class="varname">TEST_DEPENDS</code> definitions do not, marking a
dependency that is only needed for building or testing the resulting
- package. See also <a class="xref" href="#creating" title="Chapter�12.�Creating a new pkgsrc package from scratch">Chapter�12, <i>Creating a new pkgsrc package from scratch</i></a> for more
information.</p>
+ package. See also <a class="xref" href="#creating" title="Chapter�14.�Creating a new pkgsrc package from scratch">Chapter�14, <i>Creating a new pkgsrc package from scratch</i></a> for more
information.</p>
<p>This means that if you only need a package present whilst
you are building or testing, it should be noted as a
<code class="varname">TOOL_DEPENDS</code>,
@@ -8305,7 +8325,7 @@ pre-configure:
<p>Compilers for the C, C++, and Fortran languages comes with
the NetBSD base system. By default, pkgsrc assumes that a package
is written in C and will hide all other compilers (via the wrapper
- framework, see <a class="xref" href="#buildlink" title="Chapter�16.�Buildlink methodology">Chapter�16, <i>Buildlink methodology</i></a>).</p>
+ framework, see <a class="xref" href="#buildlink" title="Chapter�18.�Buildlink methodology">Chapter�18, <i>Buildlink methodology</i></a>).</p>
<p>To declare which language's compiler a package needs, set
the <code class="varname">USE_LANGUAGES</code> variable. Allowed values
currently are <span class="quote">“<span class="quote">c</span>”</span>, <span class="quote">“<span class="quote">c++</span>”</span>, and
@@ -8982,7 +9002,7 @@ PERL5_PACKLIST= auto/Pg/.packlist
Or if the <code class="filename">./configure</code> script uses
a non-standard use of --mandir, you can set
<code class="varname">GNU_CONFIGURE_MANDIR</code> as needed.</p>
-<p>See <a class="xref" href="#manpage-compression" title="15.5.�Man page compression">Section�15.5, “Man page compression”</a> for
+<p>See <a class="xref" href="#manpage-compression" title="19.5.�Man page compression">Section�19.5, “Man page compression”</a> for
information on installation of compressed manual pages.</p>
</div>
<div class="sect2">
@@ -9264,99 +9284,317 @@ PERL5_PACKLIST= auto/Pg/.packlist
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="punting"></a>21.7.�Marking packages as having problems</h2></div></div></div>
-<p>In some cases one does not have the time to solve a problem
- immediately. In this case, one can plainly mark a package as broken. For
- this, one just sets the variable <code class="varname">BROKEN</code> to the
- reason why the package is broken (similar to the
- <code class="varname">PKG_FAIL_REASON</code> variable). A user trying to build
- the package will immediately be shown this message, and the build
- will not be even tried.</p>
-<p><code class="varname">BROKEN</code> packages are removed from pkgsrc in irregular
- intervals.</p>
-</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="debug"></a>Chapter�22.�Debugging</h2></div></div></div>
-<p>To check out all the gotchas when building a package, here are
- the steps that I do in order to get a package working. Please note
- this is basically the same as what was explained in the previous
- sections, only with some debugging aids.</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Be sure to set <code class="varname">PKG_DEVELOPER=yes</code> in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p></li>
-<li class="listitem">
-<p>Install <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/url2pkg/README.html"; target="_top"><code class="filename">pkgtools/url2pkg</code></a>,
- create a directory for a new package, change into it, then run
- <span class="command"><strong>url2pkg</strong></span>:</p>
-<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>
-<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>
-<code class="prompt">%</code> <strong class="userinput"><code>url2pkg https://www.example.com/path/to/distfile.tar.gz</code></strong></pre>
-</li>
-<li class="listitem"><p>Edit the <code class="filename">Makefile</code> as requested.</p></li>
-<li class="listitem"><p>Fill in the <code class="filename">DESCR</code> file</p></li>
-<li class="listitem"><p>Run <span class="command"><strong>make configure</strong></span></p></li>
-<li class="listitem"><p>Add any dependencies glimpsed from documentation and the
- configure step to the package's
- <code class="filename">Makefile</code>.</p></li>
-<li class="listitem">
-<p>Make the package compile, doing multiple rounds of</p>
-<pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>make</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>pkgvi ${WRKSRC}/some/file/that/does/not/compile</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>mkpatches</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>patchdiff</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>mv ${WRKDIR}/.newpatches/* patches</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>make mps</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>make clean</code></strong></pre>
-<p>Doing this step as non-root user will ensure that no files
- are modified that shouldn't be, especially during the build
- phase. <span class="command"><strong>mkpatches</strong></span>,
- <span class="command"><strong>patchdiff</strong></span> and <span class="command"><strong>pkgvi</strong></span> are
- from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code class="filename">pkgtools/pkgdiff</code></a>
- package.</p>
-</li>
-<li class="listitem"><p>Look at the <code class="filename">Makefile</code>, fix if
- necessary; see <a class="xref" href="#components.Makefile" title="13.1.�Makefile">Section�13.1, “<code class="filename">Makefile</code>”</a>.</p></li>
-<li class="listitem">
-<p>Generate a <code class="filename">PLIST</code>:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST >PLIST</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make deinstall</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make deinstall</code></strong></pre>
-<p>You usually need to be <code class="username">root</code> to do
- this. Look if there are any files left:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST</code></strong></pre>
-<p>If this reveals any files that are missing in
- <code class="filename">PLIST</code>, add them.</p>
-</li>
-<li class="listitem">
-<p>Now that the <code class="filename">PLIST</code> is OK, install the
- package again and make a binary package:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make reinstall</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>make package</code></strong></pre>
-</li>
-<li class="listitem">
-<p>Delete the installed package:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg_delete <em class="replaceable"><code>examplepkg</code></em></code></strong></pre>
-</li>
+<a name="punting"></a>21.7.�Marking packages as having problems</h2></div></div></div>
+<p>In some cases one does not have the time to solve a problem
+ immediately. In this case, one can plainly mark a package as broken. For
+ this, one just sets the variable <code class="varname">BROKEN</code> to the
+ reason why the package is broken (similar to the
+ <code class="varname">PKG_FAIL_REASON</code> variable). A user trying to build
+ the package will immediately be shown this message, and the build
+ will not be even tried.</p>
+<p><code class="varname">BROKEN</code> packages are removed from pkgsrc in irregular
+ intervals.</p>
+</div>
+</div>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="gnome"></a>Chapter�22.�GNOME packaging and porting</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl class="toc">
+<dt><span class="sect1"><a href="#meta-packages">22.1. Meta packages</a></span></dt>
+<dt><span class="sect1"><a href="#new-package">22.2. Packaging a GNOME application</a></span></dt>
+<dt><span class="sect1"><a href="#full-update">22.3. Updating GNOME to a newer version</a></span></dt>
+<dt><span class="sect1"><a href="#patching">22.4. Patching guidelines</a></span></dt>
+</dl>
+</div>
+<p>Quoting <a class="ulink" href="https://www.gnome.org/"; target="_top">GNOME's web
+site</a>:</p>
+<div class="blockquote"><blockquote class="blockquote"><p>The GNOME project provides two things: The GNOME desktop
+ environment, an intuitive and attractive desktop for users, and the
+ GNOME development platform, an extensive framework for building
+ applications that integrate into the rest of the desktop.</p></blockquote></div>
+<p>pkgsrc provides a seamless way to automatically build and install
+a complete GNOME environment <span class="emphasis"><em>under many different
+platforms</em></span>. We can say with confidence that pkgsrc is one of
+the most advanced build and packaging systems for GNOME due to its
+included technologies buildlink3, the wrappers and tools framework and
+automatic configuration file management. Lots of efforts are put into
+achieving a completely clean deinstallation of installed software
+components.</p>
+<p>Given that pkgsrc is <a class="ulink" href="https://www.NetBSD.org/"; target="_top">NetBSD</a>'s official packaging system,
+the above also means that great efforts are put into making GNOME work
+under this operating system. Recently, <a class="ulink" href="https://www.dragonflybsd.org/"; target="_top">DragonFly BSD</a> also adopted
+pkgsrc as its preferred packaging system, contributing lots of
+portability fixes to make GNOME build and install under it.</p>
+<p>This chapter is aimed at pkgsrc developers and other people
+interested in helping our GNOME porting and packaging efforts. It
+provides instructions on how to manage the existing packages and some
+important information regarding their internals.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">We need your help!</h3>
+<p>Should you have some spare cycles to devote to NetBSD, pkgsrc
+ and GNOME and are willing to learn new exciting stuff, please jump
+ straight to the <a class="ulink" href="https://www.NetBSD.org/contrib/projects.html#gnome"; target="_top">pending
+ work</a> list! There is still a long way to go to get a
+ fully-functional GNOME desktop under NetBSD and we need your help to
+ achieve it!</p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="meta-packages"></a>22.1.�Meta packages</h2></div></div></div>
+<p>pkgsrc includes three GNOME-related meta packages:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-base/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-base</code></a>: Provides
+ the core GNOME desktop environment. It only includes the necessary
+ bits to get it to boot correctly, although it may lack important
+ functionality for daily operation. The idea behind this package is
+ to let end users build their own configurations on top of this one,
+ first installing this meta package to achieve a functional setup and
+ then adding individual applications.</p></li>
+<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome/README.html"; target="_top"><code class="filename">meta-pkgs/gnome</code></a>: Provides a
+ complete installation of the GNOME platform and desktop as defined
+ by the GNOME project; this is based on the components distributed in
+ the <code class="filename">platform/x.y/x.y.z/sources</code> and
+ <code class="filename">desktop/x.y/x.y.z/sources</code> directories of the
+ official FTP server. Developer-only tools found in those
+ directories are not installed unless required by some other
+ component to work properly. Similarly, packages from the bindings
+ set (<code class="filename">bindings/x.y/x.y.z/sources</code>) are not pulled
+ in unless required as a dependency for an end-user component. This
+ package "extends" <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-base/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-base</code></a>.</p></li>
+<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-devel/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-devel</code></a>:
+ Installs all the tools required to build a GNOME component when
+ fetched from the CVS repository. These are required to let the
+ <span class="command"><strong>autogen.sh</strong></span> scripts work appropriately.</p></li>
+</ul></div>
+<p>In all these packages, the <code class="varname">DEPENDS</code> lines are
+sorted in a way that eases updates: a package may depend on other
+packages listed before it but not on any listed after it. It is very
+important to keep this order to ease updates so... <span class="emphasis"><em>do not
+change it to alphabetical sorting!</em></span></p>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="new-package"></a>22.2.�Packaging a GNOME application</h2></div></div></div>
+<p>Almost all GNOME applications are written in C and use a common
+set of tools as their build system. Things get different with the new
+bindings to other languages (such as Python), but the following will
+give you a general idea on the minimum required tools:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem">
+<p>Almost all GNOME applications use the GNU Autotools as their
+ build system. As a general rule you will need to tell this to your
+ package:</p>
+<pre class="programlisting">
+GNU_CONFIGURE=yes
+USE_LIBTOOL=yes
+USE_TOOLS+=gmake
+</pre>
+</li>
+<li class="listitem">
+<p>If the package uses pkg-config to detect dependencies, add this
+ tool to the list of required utilities:</p>
+<pre class="programlisting">
+USE_TOOLS+=pkg-config
+</pre>
+<p>Also use <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/verifypc/README.html"; target="_top"><code class="filename">pkgtools/verifypc</code></a> at
+ the end of the build process to ensure that you did not miss to
+ specify any dependency in your package and that the version
+ requirements are all correct.</p>
+</li>
+<li class="listitem"><p>If the package uses intltool, be sure to add
+ <code class="literal">intltool</code> to the <code class="varname">USE_TOOLS</code>
+ to handle dependencies and to force the package to use the latest
+ available version.</p></li>
+<li class="listitem">
+<p>If the package uses gtk-doc (a documentation generation
+ utility), do <span class="emphasis"><em>not</em></span> add a dependency on it. The
+ tool is rather big and the distfile should come with pregenerated
+ documentation anyway; if it does not, it is a bug that you ought to
+ report. For such packages you should disable gtk-doc (unless it is
+ the default):</p>
+<pre class="programlisting">
+CONFIGURE_ARGS+=--disable-gtk-doc
+</pre>
+<p>The default location of installed HTML files
+ (<code class="filename">share/gtk-doc/<package-name></code>) is correct
+ and should not be changed unless the package insists on installing
+ them somewhere else. Otherwise programs as
+ <span class="command"><strong>devhelp</strong></span> will not be able to open them. You can
+ do that with an entry similar to:</p>
+<pre class="programlisting">
+CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...
+</pre>
+</li>
+</ul></div>
+<p>GNOME uses multiple <span class="emphasis"><em>shared</em></span> directories and
+files under the installation prefix to maintain databases. In this
+context, shared means that those exact same directories and files are
+used among several different packages, leading to conflicts in the
+<code class="filename">PLIST</code>. pkgsrc currently includes functionality to
+handle the most common cases, so you have to forget about using
+<code class="literal">@unexec ${RMDIR}</code> lines in your file lists and
+omitting shared files from them. If you find yourself doing those,
+<span class="emphasis"><em>your package is most likely incorrect</em></span>.</p>
+<p>The following table lists the common situations that result in
+using shared directories or files. For each of them, the appropriate
+solution is given. After applying the solution be sure to
+<span class="emphasis"><em>regenerate the package's file list</em></span> with
+<span class="command"><strong>make print-PLIST</strong></span> and ensure it is correct.</p>
+<div class="table">
+<a name="plist-handling"></a><p class="title"><b>Table�22.1.�PLIST handling for GNOME packages</b></p>
+<div class="table-contents"><table class="table" summary="PLIST handling for GNOME packages" border="1">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>If the package...</th>
+<th>Then...</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>Installs OMF files under <code class="filename">share/omf</code>.</td>
+<td>See <a class="xref" href="#scrollkeeper-data-files" title="21.6.10.�Packages installing scrollkeeper/rarian data files">Section�21.6.10, “Packages installing scrollkeeper/rarian data
files”</a>.</td>
+</tr>
+<tr>
+<td>Installs icons under the
+ <code class="filename">share/icons/hicolor</code> hierarchy or updates
+ <code class="filename">share/icons/hicolor/icon-theme.cache</code>.</td>
+<td>See <a class="xref" href="#hicolor-theme" title="21.6.19.�Packages installing hicolor theme icons">Section�21.6.19, “Packages installing hicolor theme icons”</a>.</td>
+</tr>
+<tr>
+<td>Installs files under
+ <code class="filename">share/mime/packages</code>.</td>
+<td>See <a class="xref" href="#mime-database" title="21.6.14.�Packages installing extensions to the MIME database">Section�21.6.14, “Packages installing extensions to the MIME
database”</a>.</td>
+</tr>
+<tr>
+<td>Installs <code class="filename">.desktop</code> files under
+ <code class="filename">share/applications</code> and these include MIME
+ information.</td>
+<td>See <a class="xref" href="#desktop-files" title="21.6.20.�Packages installing desktop files">Section�21.6.20, “Packages installing desktop files”</a>.</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="full-update"></a>22.3.�Updating GNOME to a newer version</h2></div></div></div>
+<p>When seeing GNOME as a whole, there are two kinds of
+updates:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term">Major update</span></dt>
+<dd>
+<p>Given that there is still a very long way for GNOME 3 (if it
+ ever appears), we consider a major update one that goes from a
+ <code class="literal">2.X</code> version to a <code class="literal">2.Y</code> one,
+ where <code class="literal">Y</code> is even and greater than
+ <code class="literal">X</code>. These are hard to achieve because they
+ introduce lots of changes in the components' code and almost all
+ GNOME distfiles are updated to newer versions. Some of them can
+ even break API and ABI compatibility with the previous major
+ version series. As a result, the update needs to be done all at
+ once to minimize breakage.</p>
+<p>A major update typically consists of around 80 package
+ updates and the addition of some new ones.</p>
+</dd>
+<dt><span class="term">Minor update</span></dt>
+<dd>
+<p>We consider a minor update one that goes from a
+ <code class="literal">2.A.X</code> version to a <code class="literal">2.A.Y</code>
+ one where <code class="literal">Y</code> is greater than
+ <code class="literal">X</code>. These are easy to achieve because they do
+ not update all GNOME components, can be done in an incremental way
+ and do not break API nor ABI compatibility.</p>
+<p>A minor update typically consists of around 50 package
+ updates, although the numbers here may vary a lot.</p>
+</dd>
+</dl></div>
+<p>In order to update the GNOME components in pkgsrc to a new stable
+release (either major or minor), the following steps should be
+followed:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
-<p>Repeat the above <span class="command"><strong>make print-PLIST</strong></span>
- command, which shouldn't find anything now:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make print-PLIST</code></strong></pre>
+<p>Get a list of all the tarballs that form the new release by
+ using the following commands. These will leave the full list of the
+ components' distfiles into the <code class="filename">list.txt</code>
+ file:</p>
+<pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>echo ls "*.tar.bz2" | \
+ ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
+ awk '{ print $9 }' >list.txt</code></strong>
+<code class="prompt">%</code> <strong class="userinput"><code>echo ls "*.tar.bz2" | \
+ ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
+ awk '{ print $9 }' >>list.txt</code></strong></pre>
</li>
+<li class="listitem"><p>Open each meta package's <code class="filename">Makefile</code> and
+ bump their version to the release you are updating them to. The
+ three meta packages should be always consistent with versioning.
+ Obviously remove any <code class="varname">PKGREVISION</code>s that might be
+ in them.</p></li>
<li class="listitem">
-<p>Reinstall the binary package:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg_add .../<em class="replaceable"><code>examplepkg</code></em>.tgz</code></strong></pre>
+<p>For each meta package, update all its
+ <code class="varname">DEPENDS</code> lines to match the latest versions as
+ shown by the above commands. Do <span class="emphasis"><em>not</em></span> list any
+ newer version (even if found in the FTP) because the meta packages
+ are supposed to list the exact versions that form a specific GNOME
+ release. Exceptions are permitted here if a newer version solves a
+ serious issue in the overall desktop experience; these typically
+ come in the form of a revision bump in pkgsrc, not in newer versions
+ from the developers.</p>
+<p>Packages not listed in the <code class="filename">list.txt</code> file
+ should be updated to the latest version available (if found in
+ pkgsrc). This is the case, for example, of the dependencies on the
+ GNU Autotools in the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-devel/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-devel</code></a> meta
package.</p>
</li>
-<li class="listitem"><p>Play with it. Make sure everything works.</p></li>
<li class="listitem">
-<p>Run <span class="command"><strong>pkglint</strong></span> from <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkglint/README.html"; target="_top"><code
class="filename">pkgtools/pkglint</code></a>, and fix the problems it
- reports:</p>
-<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkglint</code></strong></pre>
+<p>Generate a patch from the modified meta packages and extract the
+ list of "new" lines. This will provide you an outline on what
+ packages need to be updated in pkgsrc and in what order:</p>
+<pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs diff -u gnome-devel gnome-base gnome | grep '^+D' >todo.txt</code></strong></pre>
</li>
-<li class="listitem"><p>Submit (or commit, if you have cvs access); see <a class="xref" href="#submit" title="Chapter�23.�Submitting and Committing">Chapter�23, <i>Submitting and
Committing</i></a>.</p></li>
-</ul></div>
+<li class="listitem"><p>For major desktop updates it is recommended to zap all your
+ installed packages and start over from scratch at this point.</p></li>
+<li class="listitem"><p>Now comes the longest step by far: iterate over the contents
+ of <code class="filename">todo.txt</code> and update the packages listed in
+ it in order. For major desktop updates none of these should be
+ committed until the entire set is completed because there are chances
+ of breaking not-yet-updated packages.</p></li>
+<li class="listitem"><p>Once the packages are up to date and working, commit them to
+ the tree one by one with appropriate log messages. At the end,
+ commit the three meta package updates and all the corresponding
+ changes to the <code class="filename">doc/CHANGES-<YEAR></code> and
+ <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/doc/TODO?rev=HEAD&content-type=text/x-cvsweb-markup"; target="_top"><code class="filename">pkgsrc/doc/TODO</code></a> files.</p></li>
+</ol></div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="patching"></a>22.4.�Patching guidelines</h2></div></div></div>
+<p>GNOME is a very big component in pkgsrc which approaches 100
+packages. Please, it is very important that you always, always,
+<span class="strong"><strong>always</strong></span> feed back any portability
+fixes you do to a GNOME package to the mainstream developers (see <a class="xref" href="#components.patches.feedback" title="12.3.5.�Feedback to the author">Section�12.3.5, “Feedback to the
author”</a>). This is the only way to get
+their attention on portability issues and to ensure that future versions
+can be built out-of-the box on NetBSD. The less custom patches in
+pkgsrc, the easier further updates are. Those developers in charge of
+issuing major GNOME updates will be grateful if you do that.</p>
+<p>The most common places to report bugs are the <a class="ulink" href="https://bugzilla.gnome.org/"; target="_top">GNOME's Bugzilla</a> and the <a class="ulink"
href="https://bugzilla.freedesktop.org/"; target="_top">freedesktop.org's
+Bugzilla</a>. Not all components use these to track bugs, but most
+of them do. Do not be short on your reports: always provide detailed
+explanations of the current failure, how it can be improved to achieve
+maximum portability and, if at all possible, provide a patch against CVS
+head. The more verbose you are, the higher chances of your patch being
+accepted.</p>
+<p>Also, please avoid using preprocessor magic to fix portability
+issues. While the FreeBSD GNOME people are doing a great job in porting
+GNOME to their operating system, the official GNOME sources are now
+plagued by conditionals that check for <code class="varname">__FreeBSD__</code>
+and similar macros. This hurts portability. Please see our patching
+guidelines (<a class="xref" href="#components.patches.guidelines" title="12.3.4.�Patching guidelines">Section�12.3.4, “Patching guidelines”</a>) for more
+details.</p>
+</div>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
@@ -9390,7 +9628,7 @@ builds)</i></a>.</p>
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="submitting-your-package"></a>23.2.�Submitting source packages (for non-NetBSD-developers)</h2></div></div></div>
<p>First, check that your package is complete, compiles and
- runs well; see <a class="xref" href="#debug" title="Chapter�22.�Debugging">Chapter�22, <i>Debugging</i></a> and the rest of this
+ runs well; see <a class="xref" href="#creating" title="Chapter�14.�Creating a new pkgsrc package from scratch">Chapter�14, <i>Creating a new pkgsrc package from scratch</i></a> and the rest
of this
document. Next, generate an uuencoded gzipped <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?tar+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">tar</span>(1)</span></a>
archive that contains all files that make up the package.
Finally, send this package to the pkgsrc bug tracking system,
@@ -9689,500 +9927,200 @@ What shall I do?</a>
<td align="left" valign="top"><p><code class="varname">MAKEFLAGS</code> are the flags passed
to the pkgsrc-internal invocations of <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a>, while
<code class="varname">MAKE_FLAGS</code> are the flags that are passed to
- the <code class="varname">MAKE_PROGRAM</code> when building the
- package. [FIXME: What is .MAKEFLAGS for?]</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.make"></a><a name="devfaq.make.q"></a><p><b>24.2.</b></p>
-</td>
-<td align="left" valign="top"><p>What is the difference between
- <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and
- <code class="varname">MAKE_PROGRAM</code>?</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><p><code class="varname">MAKE</code> is the path to the
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> program that is
used in the pkgsrc
- infrastructure. <code class="varname">GMAKE</code> is the path to GNU
- Make, but you need to say <code class="varname">USE_TOOLS+=gmake</code> to
- use that. <code class="varname">MAKE_PROGRAM</code> is the path to the
- Make program that is used for building the
- package.</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.cc"></a><a name="devfaq.cc.q"></a><p><b>24.3.</b></p>
-</td>
-<td align="left" valign="top"><p>What is the difference between
- <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and
- <code class="varname">PKGSRC_COMPILER</code>?</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><p><code class="varname">CC</code> is the path to the real C
- compiler, which can be configured by the pkgsrc user.
- <code class="varname">PKG_CC</code> is the path to the compiler wrapper.
- <code class="varname">PKGSRC_COMPILER</code> is <span class="emphasis"><em>not</em></span> a
- path to a compiler, but the type of compiler that should be
- used. See <code class="filename">mk/compiler.mk</code> for more
- information about the latter variable.</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.bl3flags"></a><a name="devfaq.bl3flags.q"></a><p><b>24.4.</b></p>
-</td>
-<td align="left" valign="top"><p>What is the difference between
- <code class="varname">BUILDLINK_LDFLAGS</code>,
- <code class="varname">BUILDLINK_LDADD</code> and
- <code class="varname">BUILDLINK_LIBS</code>?</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><p>[FIXME]</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.bl3prefix"></a><a name="devfaq.bl3prefix.q"></a><p><b>24.5.</b></p>
-</td>
-<td align="left" valign="top"><p>Why does <span class="command"><strong>make show-var
- VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span>
- say it's empty?</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><p>For optimization reasons, some variables are only
- available in the <span class="quote">“<span class="quote">wrapper</span>”</span> phase and later. To
- <span class="quote">“<span class="quote">simulate</span>”</span> the wrapper phase, append
- <span class="command"><strong>PKG_PHASE=wrapper</strong></span> to the above
- command.</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.master_sites"></a><a name="devfaq.master_sites.q"></a><p><b>24.6.</b></p>
-</td>
-<td align="left" valign="top"><p>What does
- <code class="code">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I
- don't understand the <code class="code">:=</code> inside
- it.</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><p>The <code class="code">:=</code> is not really an
- assignment operator, although it looks like it.
- Instead, it is a degenerate form of
- <code class="code">${LIST:<em class="replaceable"><code>old_string</code></em>=<em class="replaceable"><code>new_string</code></em>}</code>,
- which is documented in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> man page and which is
- commonly used in the form <code class="code">${SRCS:.c=.o}</code>. In the
- case of <code class="varname">MASTER_SITE_*</code>,
- <em class="replaceable"><code>old_string</code></em> is the empty string and
- <em class="replaceable"><code>new_string</code></em> is
- <code class="code">package/</code>. That's where the
- <code class="code">:</code> and the <code class="code">=</code> fall
- together.</p></td>
-</tr>
-<tr class="question">
-<td align="left" valign="top">
-<a name="devfaq.mailinglists"></a><a name="devfaq.mailinglists.q"></a><p><b>24.7.</b></p>
-</td>
-<td align="left" valign="top"><p>Which mailing lists are there for package
- developers?</p></td>
-</tr>
-<tr class="answer">
-<td align="left" valign="top"></td>
-<td align="left" valign="top"><div class="variablelist"><dl class="variablelist">
-<dt><span class="term"><a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#tech-pkg"; target="_top">tech-pkg</a></span></dt>
-<dd><p>This is a list for technical discussions related
- to pkgsrc development, e.g. soliciting feedback for changes to
- pkgsrc infrastructure, proposed new features, questions related
- to porting pkgsrc to a new platform, advice for maintaining a
- package, patches that affect many packages, help requests moved
- from pkgsrc-users when an infrastructure bug is found,
- etc.</p></dd>
-<dt><span class="term"><a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#pkgsrc-bugs"; target="_top">pkgsrc-bugs</a></span></dt>
-<dd><p>All bug reports in category "pkg" sent with
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> appear here.
Please do not report your bugs here
- directly; use one of the other mailing
- lists.</p></dd>
-</dl></div></td>
+ the <code class="varname">MAKE_PROGRAM</code> when building the
+ package. [FIXME: What is .MAKEFLAGS for?]</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.documentation"></a><a name="devfaq.documentation.q"></a><p><b>24.8.</b></p>
+<a name="devfaq.make"></a><a name="devfaq.make.q"></a><p><b>24.2.</b></p>
</td>
-<td align="left" valign="top"><p>Where is the pkgsrc
- documentation?</p></td>
+<td align="left" valign="top"><p>What is the difference between
+ <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and
+ <code class="varname">MAKE_PROGRAM</code>?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
+<td align="left" valign="top"><p><code class="varname">MAKE</code> is the path to the
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> program that is
used in the pkgsrc
+ infrastructure. <code class="varname">GMAKE</code> is the path to GNU
+ Make, but you need to say <code class="varname">USE_TOOLS+=gmake</code> to
+ use that. <code class="varname">MAKE_PROGRAM</code> is the path to the
+ Make program that is used for building the
+ package.</p></td>
+</tr>
+<tr class="question">
<td align="left" valign="top">
-<p>There are many places where you can find
- documentation about pkgsrc:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>The pkgsrc guide (this document) is a collection
- of chapters that explain large parts of pkgsrc, but some
- chapters tend to be outdated. Which ones they are is hard to
- say.</p></li>
-<li class="listitem"><p>On the mailing list archives (see <a class="ulink" href="https://mail-index.NetBSD.org/"; target="_top">https://mail-index.NetBSD.org/</a>), you can find discussions
- about certain features, announcements of new parts of the pkgsrc
- infrastructure and sometimes even announcements that a certain
- feature has been marked as obsolete. The benefit here is that
- each message has a date appended to it.</p></li>
-<li class="listitem"><p>Many of the files in the
- <code class="filename">mk/</code> directory start with a comment that
- describes the purpose of the file and how it can be used by the
- pkgsrc user and package authors. An easy way to find this
- documentation is to run <span class="command"><strong>bmake
- help</strong></span>.</p></li>
-<li class="listitem"><p>The CVS log messages are a rich source of
- information, but they tend to be highly abbreviated, especially
- for actions that occur often. Some contain a detailed
- description of what has changed, but they are geared towards the
- other pkgsrc developers, not towards an average pkgsrc user.
- They also only document <span class="emphasis"><em>changes</em></span>, so if you
- don't know what has been before, these messages may not be worth
- too much to you.</p></li>
-<li class="listitem"><p>Some parts of pkgsrc are only <span class="quote">“<span class="quote">implicitly
- documented</span>”</span>, that is the documentation exists only in the
- mind of the developer who wrote the code. To get this
- information, use the <span class="command"><strong>cvs annotate</strong></span> command
- to see who has written it and ask on the
- <code class="literal">tech-pkg</code> mailing list, so that others can
- find your questions later (see above). To be sure that the
- developer in charge reads the mail, you may CC him or
- her.</p></li>
-</ul></div>
+<a name="devfaq.cc"></a><a name="devfaq.cc.q"></a><p><b>24.3.</b></p>
</td>
+<td align="left" valign="top"><p>What is the difference between
+ <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and
+ <code class="varname">PKGSRC_COMPILER</code>?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p><code class="varname">CC</code> is the path to the real C
+ compiler, which can be configured by the pkgsrc user.
+ <code class="varname">PKG_CC</code> is the path to the compiler wrapper.
+ <code class="varname">PKGSRC_COMPILER</code> is <span class="emphasis"><em>not</em></span> a
+ path to a compiler, but the type of compiler that should be
+ used. See <code class="filename">mk/compiler.mk</code> for more
+ information about the latter variable.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.too-much-time"></a><a name="devfaq.too-much-time.q"></a><p><b>24.9.</b></p>
+<a name="devfaq.bl3flags"></a><a name="devfaq.bl3flags.q"></a><p><b>24.4.</b></p>
</td>
-<td align="left" valign="top"><p>I have a little time to kill.
-What shall I do?</p></td>
+<td align="left" valign="top"><p>What is the difference between
+ <code class="varname">BUILDLINK_LDFLAGS</code>,
+ <code class="varname">BUILDLINK_LDADD</code> and
+ <code class="varname">BUILDLINK_LIBS</code>?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>[FIXME]</p></td>
+</tr>
+<tr class="question">
<td align="left" valign="top">
-<p>This is not really an FAQ yet, but here's the answer
-anyway.</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Run <span class="command"><strong>pkg_chk -N</strong></span> (from the
- <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_chk/README.html"; target="_top"><code class="filename">pkgtools/pkg_chk</code></a> package). It
- will tell you about newer versions of installed packages that are
- available, but not yet updated in pkgsrc.</p></li>
-<li class="listitem"><p>Browse <code class="filename">pkgsrc/doc/TODO</code>
- — it contains a list of suggested new packages and a list of
- cleanups and enhancements for pkgsrc that would be nice to
- have.</p></li>
-<li class="listitem"><p>Review packages for which review was requested on
- the <a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#tech-pkg"; target="_top">tech-pkg</a>
- mailing list.</p></li>
-</ul></div>
+<a name="devfaq.bl3prefix"></a><a name="devfaq.bl3prefix.q"></a><p><b>24.5.</b></p>
</td>
+<td align="left" valign="top"><p>Why does <span class="command"><strong>make show-var
+ VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span>
+ say it's empty?</p></td>
</tr>
-</tbody>
-</table>
-</div>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="gnome"></a>Chapter�25.�GNOME packaging and porting</h2></div></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl class="toc">
-<dt><span class="sect1"><a href="#meta-packages">25.1. Meta packages</a></span></dt>
-<dt><span class="sect1"><a href="#new-package">25.2. Packaging a GNOME application</a></span></dt>
-<dt><span class="sect1"><a href="#full-update">25.3. Updating GNOME to a newer version</a></span></dt>
-<dt><span class="sect1"><a href="#patching">25.4. Patching guidelines</a></span></dt>
-</dl>
-</div>
-<p>Quoting <a class="ulink" href="https://www.gnome.org/"; target="_top">GNOME's web
-site</a>:</p>
-<div class="blockquote"><blockquote class="blockquote"><p>The GNOME project provides two things: The GNOME desktop
- environment, an intuitive and attractive desktop for users, and the
- GNOME development platform, an extensive framework for building
- applications that integrate into the rest of the desktop.</p></blockquote></div>
-<p>pkgsrc provides a seamless way to automatically build and install
-a complete GNOME environment <span class="emphasis"><em>under many different
-platforms</em></span>. We can say with confidence that pkgsrc is one of
-the most advanced build and packaging systems for GNOME due to its
-included technologies buildlink3, the wrappers and tools framework and
-automatic configuration file management. Lots of efforts are put into
-achieving a completely clean deinstallation of installed software
-components.</p>
-<p>Given that pkgsrc is <a class="ulink" href="https://www.NetBSD.org/"; target="_top">NetBSD</a>'s official packaging system,
-the above also means that great efforts are put into making GNOME work
-under this operating system. Recently, <a class="ulink" href="https://www.dragonflybsd.org/"; target="_top">DragonFly BSD</a> also adopted
-pkgsrc as its preferred packaging system, contributing lots of
-portability fixes to make GNOME build and install under it.</p>
-<p>This chapter is aimed at pkgsrc developers and other people
-interested in helping our GNOME porting and packaging efforts. It
-provides instructions on how to manage the existing packages and some
-important information regarding their internals.</p>
-<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
-<h3 class="title">We need your help!</h3>
-<p>Should you have some spare cycles to devote to NetBSD, pkgsrc
- and GNOME and are willing to learn new exciting stuff, please jump
- straight to the <a class="ulink" href="https://www.NetBSD.org/contrib/projects.html#gnome"; target="_top">pending
- work</a> list! There is still a long way to go to get a
- fully-functional GNOME desktop under NetBSD and we need your help to
- achieve it!</p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="meta-packages"></a>25.1.�Meta packages</h2></div></div></div>
-<p>pkgsrc includes three GNOME-related meta packages:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-base/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-base</code></a>: Provides
- the core GNOME desktop environment. It only includes the necessary
- bits to get it to boot correctly, although it may lack important
- functionality for daily operation. The idea behind this package is
- to let end users build their own configurations on top of this one,
- first installing this meta package to achieve a functional setup and
- then adding individual applications.</p></li>
-<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome/README.html"; target="_top"><code class="filename">meta-pkgs/gnome</code></a>: Provides a
- complete installation of the GNOME platform and desktop as defined
- by the GNOME project; this is based on the components distributed in
- the <code class="filename">platform/x.y/x.y.z/sources</code> and
- <code class="filename">desktop/x.y/x.y.z/sources</code> directories of the
- official FTP server. Developer-only tools found in those
- directories are not installed unless required by some other
- component to work properly. Similarly, packages from the bindings
- set (<code class="filename">bindings/x.y/x.y.z/sources</code>) are not pulled
- in unless required as a dependency for an end-user component. This
- package "extends" <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-base/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-base</code></a>.</p></li>
-<li class="listitem"><p><a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-devel/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-devel</code></a>:
- Installs all the tools required to build a GNOME component when
- fetched from the CVS repository. These are required to let the
- <span class="command"><strong>autogen.sh</strong></span> scripts work appropriately.</p></li>
-</ul></div>
-<p>In all these packages, the <code class="varname">DEPENDS</code> lines are
-sorted in a way that eases updates: a package may depend on other
-packages listed before it but not on any listed after it. It is very
-important to keep this order to ease updates so... <span class="emphasis"><em>do not
-change it to alphabetical sorting!</em></span></p>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="new-package"></a>25.2.�Packaging a GNOME application</h2></div></div></div>
-<p>Almost all GNOME applications are written in C and use a common
-set of tools as their build system. Things get different with the new
-bindings to other languages (such as Python), but the following will
-give you a general idea on the minimum required tools:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
-<p>Almost all GNOME applications use the GNU Autotools as their
- build system. As a general rule you will need to tell this to your
- package:</p>
-<pre class="programlisting">
-GNU_CONFIGURE=yes
-USE_LIBTOOL=yes
-USE_TOOLS+=gmake
-</pre>
-</li>
-<li class="listitem">
-<p>If the package uses pkg-config to detect dependencies, add this
- tool to the list of required utilities:</p>
-<pre class="programlisting">
-USE_TOOLS+=pkg-config
-</pre>
-<p>Also use <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/verifypc/README.html"; target="_top"><code class="filename">pkgtools/verifypc</code></a> at
- the end of the build process to ensure that you did not miss to
- specify any dependency in your package and that the version
- requirements are all correct.</p>
-</li>
-<li class="listitem"><p>If the package uses intltool, be sure to add
- <code class="literal">intltool</code> to the <code class="varname">USE_TOOLS</code>
- to handle dependencies and to force the package to use the latest
- available version.</p></li>
-<li class="listitem">
-<p>If the package uses gtk-doc (a documentation generation
- utility), do <span class="emphasis"><em>not</em></span> add a dependency on it. The
- tool is rather big and the distfile should come with pregenerated
- documentation anyway; if it does not, it is a bug that you ought to
- report. For such packages you should disable gtk-doc (unless it is
- the default):</p>
-<pre class="programlisting">
-CONFIGURE_ARGS+=--disable-gtk-doc
-</pre>
-<p>The default location of installed HTML files
- (<code class="filename">share/gtk-doc/<package-name></code>) is correct
- and should not be changed unless the package insists on installing
- them somewhere else. Otherwise programs as
- <span class="command"><strong>devhelp</strong></span> will not be able to open them. You can
- do that with an entry similar to:</p>
-<pre class="programlisting">
-CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...
-</pre>
-</li>
-</ul></div>
-<p>GNOME uses multiple <span class="emphasis"><em>shared</em></span> directories and
-files under the installation prefix to maintain databases. In this
-context, shared means that those exact same directories and files are
-used among several different packages, leading to conflicts in the
-<code class="filename">PLIST</code>. pkgsrc currently includes functionality to
-handle the most common cases, so you have to forget about using
-<code class="literal">@unexec ${RMDIR}</code> lines in your file lists and
-omitting shared files from them. If you find yourself doing those,
-<span class="emphasis"><em>your package is most likely incorrect</em></span>.</p>
-<p>The following table lists the common situations that result in
-using shared directories or files. For each of them, the appropriate
-solution is given. After applying the solution be sure to
-<span class="emphasis"><em>regenerate the package's file list</em></span> with
-<span class="command"><strong>make print-PLIST</strong></span> and ensure it is correct.</p>
-<div class="table">
-<a name="plist-handling"></a><p class="title"><b>Table�25.1.�PLIST handling for GNOME packages</b></p>
-<div class="table-contents"><table class="table" summary="PLIST handling for GNOME packages" border="1">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>If the package...</th>
-<th>Then...</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>Installs OMF files under <code class="filename">share/omf</code>.</td>
-<td>See <a class="xref" href="#scrollkeeper-data-files" title="21.6.10.�Packages installing scrollkeeper/rarian data files">Section�21.6.10, “Packages installing scrollkeeper/rarian data
files”</a>.</td>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>For optimization reasons, some variables are only
+ available in the <span class="quote">“<span class="quote">wrapper</span>”</span> phase and later. To
+ <span class="quote">“<span class="quote">simulate</span>”</span> the wrapper phase, append
+ <span class="command"><strong>PKG_PHASE=wrapper</strong></span> to the above
+ command.</p></td>
</tr>
-<tr>
-<td>Installs icons under the
- <code class="filename">share/icons/hicolor</code> hierarchy or updates
- <code class="filename">share/icons/hicolor/icon-theme.cache</code>.</td>
-<td>See <a class="xref" href="#hicolor-theme" title="21.6.19.�Packages installing hicolor theme icons">Section�21.6.19, “Packages installing hicolor theme icons”</a>.</td>
+<tr class="question">
+<td align="left" valign="top">
+<a name="devfaq.master_sites"></a><a name="devfaq.master_sites.q"></a><p><b>24.6.</b></p>
+</td>
+<td align="left" valign="top"><p>What does
+ <code class="code">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I
+ don't understand the <code class="code">:=</code> inside
+ it.</p></td>
</tr>
-<tr>
-<td>Installs files under
- <code class="filename">share/mime/packages</code>.</td>
-<td>See <a class="xref" href="#mime-database" title="21.6.14.�Packages installing extensions to the MIME database">Section�21.6.14, “Packages installing extensions to the MIME
database”</a>.</td>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>The <code class="code">:=</code> is not really an
+ assignment operator, although it looks like it.
+ Instead, it is a degenerate form of
+ <code class="code">${LIST:<em class="replaceable"><code>old_string</code></em>=<em class="replaceable"><code>new_string</code></em>}</code>,
+ which is documented in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a> man page and which is
+ commonly used in the form <code class="code">${SRCS:.c=.o}</code>. In the
+ case of <code class="varname">MASTER_SITE_*</code>,
+ <em class="replaceable"><code>old_string</code></em> is the empty string and
+ <em class="replaceable"><code>new_string</code></em> is
+ <code class="code">package/</code>. That's where the
+ <code class="code">:</code> and the <code class="code">=</code> fall
+ together.</p></td>
</tr>
-<tr>
-<td>Installs <code class="filename">.desktop</code> files under
- <code class="filename">share/applications</code> and these include MIME
- information.</td>
-<td>See <a class="xref" href="#desktop-files" title="21.6.20.�Packages installing desktop files">Section�21.6.20, “Packages installing desktop files”</a>.</td>
+<tr class="question">
+<td align="left" valign="top">
+<a name="devfaq.mailinglists"></a><a name="devfaq.mailinglists.q"></a><p><b>24.7.</b></p>
+</td>
+<td align="left" valign="top"><p>Which mailing lists are there for package
+ developers?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#tech-pkg"; target="_top">tech-pkg</a></span></dt>
+<dd><p>This is a list for technical discussions related
+ to pkgsrc development, e.g. soliciting feedback for changes to
+ pkgsrc infrastructure, proposed new features, questions related
+ to porting pkgsrc to a new platform, advice for maintaining a
+ package, patches that affect many packages, help requests moved
+ from pkgsrc-users when an infrastructure bug is found,
+ etc.</p></dd>
+<dt><span class="term"><a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#pkgsrc-bugs"; target="_top">pkgsrc-bugs</a></span></dt>
+<dd><p>All bug reports in category "pkg" sent with
+ <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> appear here.
Please do not report your bugs here
+ directly; use one of the other mailing
+ lists.</p></dd>
+</dl></div></td>
+</tr>
+<tr class="question">
+<td align="left" valign="top">
+<a name="devfaq.documentation"></a><a name="devfaq.documentation.q"></a><p><b>24.8.</b></p>
+</td>
+<td align="left" valign="top"><p>Where is the pkgsrc
+ documentation?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top">
+<p>There are many places where you can find
+ documentation about pkgsrc:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>The pkgsrc guide (this document) is a collection
+ of chapters that explain large parts of pkgsrc, but some
+ chapters tend to be outdated. Which ones they are is hard to
+ say.</p></li>
+<li class="listitem"><p>On the mailing list archives (see <a class="ulink" href="https://mail-index.NetBSD.org/"; target="_top">https://mail-index.NetBSD.org/</a>), you can find discussions
+ about certain features, announcements of new parts of the pkgsrc
+ infrastructure and sometimes even announcements that a certain
+ feature has been marked as obsolete. The benefit here is that
+ each message has a date appended to it.</p></li>
+<li class="listitem"><p>Many of the files in the
+ <code class="filename">mk/</code> directory start with a comment that
+ describes the purpose of the file and how it can be used by the
+ pkgsrc user and package authors. An easy way to find this
+ documentation is to run <span class="command"><strong>bmake
+ help</strong></span>.</p></li>
+<li class="listitem"><p>The CVS log messages are a rich source of
+ information, but they tend to be highly abbreviated, especially
+ for actions that occur often. Some contain a detailed
+ description of what has changed, but they are geared towards the
+ other pkgsrc developers, not towards an average pkgsrc user.
+ They also only document <span class="emphasis"><em>changes</em></span>, so if you
+ don't know what has been before, these messages may not be worth
+ too much to you.</p></li>
+<li class="listitem"><p>Some parts of pkgsrc are only <span class="quote">“<span class="quote">implicitly
+ documented</span>”</span>, that is the documentation exists only in the
+ mind of the developer who wrote the code. To get this
+ information, use the <span class="command"><strong>cvs annotate</strong></span> command
+ to see who has written it and ask on the
+ <code class="literal">tech-pkg</code> mailing list, so that others can
+ find your questions later (see above). To be sure that the
+ developer in charge reads the mail, you may CC him or
+ her.</p></li>
+</ul></div>
+</td>
+</tr>
+<tr class="question">
+<td align="left" valign="top">
+<a name="devfaq.too-much-time"></a><a name="devfaq.too-much-time.q"></a><p><b>24.9.</b></p>
+</td>
+<td align="left" valign="top"><p>I have a little time to kill.
+What shall I do?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top">
+<p>This is not really an FAQ yet, but here's the answer
+anyway.</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Run <span class="command"><strong>pkg_chk -N</strong></span> (from the
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_chk/README.html"; target="_top"><code class="filename">pkgtools/pkg_chk</code></a> package). It
+ will tell you about newer versions of installed packages that are
+ available, but not yet updated in pkgsrc.</p></li>
+<li class="listitem"><p>Browse <code class="filename">pkgsrc/doc/TODO</code>
+ — it contains a list of suggested new packages and a list of
+ cleanups and enhancements for pkgsrc that would be nice to
+ have.</p></li>
+<li class="listitem"><p>Review packages for which review was requested on
+ the <a class="ulink" href="https://www.NetBSD.org/mailinglists/index.html#tech-pkg"; target="_top">tech-pkg</a>
+ mailing list.</p></li>
+</ul></div>
+</td>
</tr>
</tbody>
-</table></div>
-</div>
-<br class="table-break">
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="full-update"></a>25.3.�Updating GNOME to a newer version</h2></div></div></div>
-<p>When seeing GNOME as a whole, there are two kinds of
-updates:</p>
-<div class="variablelist"><dl class="variablelist">
-<dt><span class="term">Major update</span></dt>
-<dd>
-<p>Given that there is still a very long way for GNOME 3 (if it
- ever appears), we consider a major update one that goes from a
- <code class="literal">2.X</code> version to a <code class="literal">2.Y</code> one,
- where <code class="literal">Y</code> is even and greater than
- <code class="literal">X</code>. These are hard to achieve because they
- introduce lots of changes in the components' code and almost all
- GNOME distfiles are updated to newer versions. Some of them can
- even break API and ABI compatibility with the previous major
- version series. As a result, the update needs to be done all at
- once to minimize breakage.</p>
-<p>A major update typically consists of around 80 package
- updates and the addition of some new ones.</p>
-</dd>
-<dt><span class="term">Minor update</span></dt>
-<dd>
-<p>We consider a minor update one that goes from a
- <code class="literal">2.A.X</code> version to a <code class="literal">2.A.Y</code>
- one where <code class="literal">Y</code> is greater than
- <code class="literal">X</code>. These are easy to achieve because they do
- not update all GNOME components, can be done in an incremental way
- and do not break API nor ABI compatibility.</p>
-<p>A minor update typically consists of around 50 package
- updates, although the numbers here may vary a lot.</p>
-</dd>
-</dl></div>
-<p>In order to update the GNOME components in pkgsrc to a new stable
-release (either major or minor), the following steps should be
-followed:</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem">
-<p>Get a list of all the tarballs that form the new release by
- using the following commands. These will leave the full list of the
- components' distfiles into the <code class="filename">list.txt</code>
- file:</p>
-<pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>echo ls "*.tar.bz2" | \
- ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
- awk '{ print $9 }' >list.txt</code></strong>
-<code class="prompt">%</code> <strong class="userinput"><code>echo ls "*.tar.bz2" | \
- ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
- awk '{ print $9 }' >>list.txt</code></strong></pre>
-</li>
-<li class="listitem"><p>Open each meta package's <code class="filename">Makefile</code> and
- bump their version to the release you are updating them to. The
- three meta packages should be always consistent with versioning.
- Obviously remove any <code class="varname">PKGREVISION</code>s that might be
- in them.</p></li>
-<li class="listitem">
-<p>For each meta package, update all its
- <code class="varname">DEPENDS</code> lines to match the latest versions as
- shown by the above commands. Do <span class="emphasis"><em>not</em></span> list any
- newer version (even if found in the FTP) because the meta packages
- are supposed to list the exact versions that form a specific GNOME
- release. Exceptions are permitted here if a newer version solves a
- serious issue in the overall desktop experience; these typically
- come in the form of a revision bump in pkgsrc, not in newer versions
- from the developers.</p>
-<p>Packages not listed in the <code class="filename">list.txt</code> file
- should be updated to the latest version available (if found in
- pkgsrc). This is the case, for example, of the dependencies on the
- GNU Autotools in the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome-devel/README.html"; target="_top"><code class="filename">meta-pkgs/gnome-devel</code></a> meta
package.</p>
-</li>
-<li class="listitem">
-<p>Generate a patch from the modified meta packages and extract the
- list of "new" lines. This will provide you an outline on what
- packages need to be updated in pkgsrc and in what order:</p>
-<pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs diff -u gnome-devel gnome-base gnome | grep '^+D' >todo.txt</code></strong></pre>
-</li>
-<li class="listitem"><p>For major desktop updates it is recommended to zap all your
- installed packages and start over from scratch at this point.</p></li>
-<li class="listitem"><p>Now comes the longest step by far: iterate over the contents
- of <code class="filename">todo.txt</code> and update the packages listed in
- it in order. For major desktop updates none of these should be
- committed until the entire set is completed because there are chances
- of breaking not-yet-updated packages.</p></li>
-<li class="listitem"><p>Once the packages are up to date and working, commit them to
- the tree one by one with appropriate log messages. At the end,
- commit the three meta package updates and all the corresponding
- changes to the <code class="filename">doc/CHANGES-<YEAR></code> and
- <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/doc/TODO?rev=HEAD&content-type=text/x-cvsweb-markup"; target="_top"><code class="filename">pkgsrc/doc/TODO</code></a> files.</p></li>
-</ol></div>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="patching"></a>25.4.�Patching guidelines</h2></div></div></div>
-<p>GNOME is a very big component in pkgsrc which approaches 100
-packages. Please, it is very important that you always, always,
-<span class="strong"><strong>always</strong></span> feed back any portability
-fixes you do to a GNOME package to the mainstream developers (see <a class="xref" href="#components.patches.feedback" title="13.3.5.�Feedback to the author">Section�13.3.5, “Feedback to the
author”</a>). This is the only way to get
-their attention on portability issues and to ensure that future versions
-can be built out-of-the box on NetBSD. The less custom patches in
-pkgsrc, the easier further updates are. Those developers in charge of
-issuing major GNOME updates will be grateful if you do that.</p>
-<p>The most common places to report bugs are the <a class="ulink" href="https://bugzilla.gnome.org/"; target="_top">GNOME's Bugzilla</a> and the <a class="ulink"
href="https://bugzilla.freedesktop.org/"; target="_top">freedesktop.org's
-Bugzilla</a>. Not all components use these to track bugs, but most
-of them do. Do not be short on your reports: always provide detailed
-explanations of the current failure, how it can be improved to achieve
-maximum portability and, if at all possible, provide a patch against CVS
-head. The more verbose you are, the higher chances of your patch being
-accepted.</p>
-<p>Also, please avoid using preprocessor magic to fix portability
-issues. While the FreeBSD GNOME people are doing a great job in porting
-GNOME to their operating system, the official GNOME sources are now
-plagued by conditionals that check for <code class="varname">__FreeBSD__</code>
-and similar macros. This hurts portability. Please see our patching
-guidelines (<a class="xref" href="#components.patches.guidelines" title="13.3.4.�Patching guidelines">Section�13.3.4, “Patching guidelines”</a>) for more
-details.</p>
+</table>
</div>
</div>
</div>
@@ -10198,64 +10136,64 @@ details.</p>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="chapter"><a href="#infr.design">26. Design of the pkgsrc infrastructure</a></span></dt>
+<dt><span class="chapter"><a href="#infr.design">25. Design of the pkgsrc infrastructure</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#infr.vardef">26.1. The meaning of variable definitions</a></span></dt>
-<dt><span class="sect1"><a href="#infr.vardef.problems">26.2. Avoiding problems before they arise</a></span></dt>
-<dt><span class="sect1"><a href="#infr.var">26.3. Variable evaluation</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef">25.1. The meaning of variable definitions</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef.problems">25.2. Avoiding problems before they arise</a></span></dt>
+<dt><span class="sect1"><a href="#infr.var">25.3. Variable evaluation</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.var.load">26.3.1. At load time</a></span></dt>
-<dt><span class="sect2"><a href="#infr.var.run">26.3.2. At runtime</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.load">25.3.1. At load time</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.run">25.3.2. At runtime</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.varspec">26.4. How can variables be specified?</a></span></dt>
-<dt><span class="sect1"><a href="#infr.design.intf">26.5. Designing interfaces for Makefile fragments</a></span></dt>
+<dt><span class="sect1"><a href="#infr.varspec">25.4. How can variables be specified?</a></span></dt>
+<dt><span class="sect1"><a href="#infr.design.intf">25.5. Designing interfaces for Makefile fragments</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.design.intf.proc">26.5.1. Procedures with parameters</a></span></dt>
-<dt><span class="sect2"><a href="#infr.design.intf.action">26.5.2. Actions taken on behalf of parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.proc">25.5.1. Procedures with parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.action">25.5.2. Actions taken on behalf of parameters</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.order">26.6. The order in which files are loaded</a></span></dt>
+<dt><span class="sect1"><a href="#infr.order">25.6. The order in which files are loaded</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.order.prefs">26.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
-<dt><span class="sect2"><a href="#infr.order.pkg">26.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.prefs">25.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.pkg">25.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#regression">27. Regression tests</a></span></dt>
+<dt><span class="chapter"><a href="#regression">26. Regression tests</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#regression.run">27.1. Running the regression tests</a></span></dt>
-<dt><span class="sect1"><a href="#regression.new">27.2. Adding a new regression test</a></span></dt>
+<dt><span class="sect1"><a href="#regression.run">26.1. Running the regression tests</a></span></dt>
+<dt><span class="sect1"><a href="#regression.new">26.2. Adding a new regression test</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#regression.fun.override">27.2.1. Overridable functions</a></span></dt>
-<dt><span class="sect2"><a href="#regression.fun.helper">27.2.2. Helper functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.override">26.2.1. Overridable functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.helper">26.2.2. Helper functions</a></span></dt>
</dl></dd>
</dl></dd>
-<dt><span class="chapter"><a href="#porting">28. Porting pkgsrc</a></span></dt>
-<dd><dl><dt><span class="sect1"><a href="#porting.opsys">28.1. Porting pkgsrc to a new operating system</a></span></dt></dl></dd>
+<dt><span class="chapter"><a href="#porting">27. Porting pkgsrc</a></span></dt>
+<dd><dl><dt><span class="sect1"><a href="#porting.opsys">27.1. Porting pkgsrc to a new operating system</a></span></dt></dl></dd>
</dl>
</div>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="infr.design"></a>Chapter�26.�Design of the pkgsrc infrastructure</h2></div></div></div>
+<a name="infr.design"></a>Chapter�25.�Design of the pkgsrc infrastructure</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="#infr.vardef">26.1. The meaning of variable definitions</a></span></dt>
-<dt><span class="sect1"><a href="#infr.vardef.problems">26.2. Avoiding problems before they arise</a></span></dt>
-<dt><span class="sect1"><a href="#infr.var">26.3. Variable evaluation</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef">25.1. The meaning of variable definitions</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef.problems">25.2. Avoiding problems before they arise</a></span></dt>
+<dt><span class="sect1"><a href="#infr.var">25.3. Variable evaluation</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.var.load">26.3.1. At load time</a></span></dt>
-<dt><span class="sect2"><a href="#infr.var.run">26.3.2. At runtime</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.load">25.3.1. At load time</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.run">25.3.2. At runtime</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.varspec">26.4. How can variables be specified?</a></span></dt>
-<dt><span class="sect1"><a href="#infr.design.intf">26.5. Designing interfaces for Makefile fragments</a></span></dt>
+<dt><span class="sect1"><a href="#infr.varspec">25.4. How can variables be specified?</a></span></dt>
+<dt><span class="sect1"><a href="#infr.design.intf">25.5. Designing interfaces for Makefile fragments</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.design.intf.proc">26.5.1. Procedures with parameters</a></span></dt>
-<dt><span class="sect2"><a href="#infr.design.intf.action">26.5.2. Actions taken on behalf of parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.proc">25.5.1. Procedures with parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.action">25.5.2. Actions taken on behalf of parameters</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="#infr.order">26.6. The order in which files are loaded</a></span></dt>
+<dt><span class="sect1"><a href="#infr.order">25.6. The order in which files are loaded</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#infr.order.prefs">26.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
-<dt><span class="sect2"><a href="#infr.order.pkg">26.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.prefs">25.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.pkg">25.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
</dl></dd>
</dl>
</div>
@@ -10265,7 +10203,7 @@ details.</p>
like.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.vardef"></a>26.1.�The meaning of variable definitions</h2></div></div></div>
+<a name="infr.vardef"></a>25.1.�The meaning of variable definitions</h2></div></div></div>
<p>Whenever a variable is defined in the pkgsrc
infrastructure, the location and the way of definition provide
much information about the intended use of that variable.
@@ -10296,7 +10234,7 @@ details.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.vardef.problems"></a>26.2.�Avoiding problems before they arise</h2></div></div></div>
+<a name="infr.vardef.problems"></a>25.2.�Avoiding problems before they arise</h2></div></div></div>
<p>All variables that contain lists of things should default
to being empty. Two examples that do not follow this rule are
<code class="varname">USE_LANGUAGES</code> and
@@ -10320,10 +10258,10 @@ DISTFILES= ${DISTNAME}${EXTRACT_SUF
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.var"></a>26.3.�Variable evaluation</h2></div></div></div>
+<a name="infr.var"></a>25.3.�Variable evaluation</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.var.load"></a>26.3.1.�At load time</h3></div></div></div>
+<a name="infr.var.load"></a>25.3.1.�At load time</h3></div></div></div>
<p>Variable evaluation takes place either at load time or at
runtime, depending on the context in which they occur. The
contexts where variables are evaluated at load time are:</p>
@@ -10365,7 +10303,7 @@ CFLAGS+= -Wall
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.var.run"></a>26.3.2.�At runtime</h3></div></div></div>
+<a name="infr.var.run"></a>25.3.2.�At runtime</h3></div></div></div>
<p>After all the files have been loaded, the values of the
variables cannot be changed anymore. Variables that are used in
the shell commands are expanded at this point.</p>
@@ -10373,7 +10311,7 @@ CFLAGS+= -Wall
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.varspec"></a>26.4.�How can variables be specified?</h2></div></div></div>
+<a name="infr.varspec"></a>25.4.�How can variables be specified?</h2></div></div></div>
<p>There are many ways in which the definition and use of a
variable can be restricted in order to detect bugs and violations
of the (mostly unwritten) policies. A package can be checked with
@@ -10382,14 +10320,14 @@ CFLAGS+= -Wall
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.design.intf"></a>26.5.�Designing interfaces for Makefile fragments</h2></div></div></div>
+<a name="infr.design.intf"></a>25.5.�Designing interfaces for Makefile fragments</h2></div></div></div>
<p>Most of the <code class="filename">.mk</code> files fall into one
of the following classes. Cases where a file falls into more
than one class should be avoided as it often leads to subtle
bugs.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.design.intf.proc"></a>26.5.1.�Procedures with parameters</h3></div></div></div>
+<a name="infr.design.intf.proc"></a>25.5.1.�Procedures with parameters</h3></div></div></div>
<p>In a traditional imperative programming language some of
the <code class="filename">.mk</code> files could be described as
procedures. They take some input parameters and—after
@@ -10423,7 +10361,7 @@ CFLAGS+= -Wall
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.design.intf.action"></a>26.5.2.�Actions taken on behalf of parameters</h3></div></div></div>
+<a name="infr.design.intf.action"></a>25.5.2.�Actions taken on behalf of parameters</h3></div></div></div>
<p>Action files take some input parameters and may define
runtime variables. They shall not define loadtime variables.
There are action files that are included implicitly by the
@@ -10435,7 +10373,7 @@ CFLAGS+= -Wall
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="infr.order"></a>26.6.�The order in which files are loaded</h2></div></div></div>
+<a name="infr.order"></a>25.6.�The order in which files are loaded</h2></div></div></div>
<p>Package <code class="filename">Makefile</code>s usually consist of
a set of variable definitions, and include the file
<code class="filename">../../mk/bsd.pkg.mk</code> in the very last line.
@@ -10450,7 +10388,7 @@ CFLAGS+= -Wall
are loaded and gives reasons for that order.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.order.prefs"></a>26.6.1.�The order in <code class="filename">bsd.prefs.mk</code>
+<a name="infr.order.prefs"></a>25.6.1.�The order in <code class="filename">bsd.prefs.mk</code>
</h3></div></div></div>
<p>The very first action in <code class="filename">bsd.prefs.mk</code>
is to define some essential variables like
@@ -10475,7 +10413,7 @@ CFLAGS+= -Wall
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="infr.order.pkg"></a>26.6.2.�The order in <code class="filename">bsd.pkg.mk</code>
+<a name="infr.order.pkg"></a>25.6.2.�The order in <code class="filename">bsd.pkg.mk</code>
</h3></div></div></div>
<p>First, <code class="filename">bsd.prefs.mk</code> is loaded.</p>
<p>Then, the various <code class="filename">*-vars.mk</code> files are
@@ -10508,15 +10446,15 @@ CFLAGS+= -Wall
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="regression"></a>Chapter�27.�Regression tests</h2></div></div></div>
+<a name="regression"></a>Chapter�26.�Regression tests</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="#regression.run">27.1. Running the regression tests</a></span></dt>
-<dt><span class="sect1"><a href="#regression.new">27.2. Adding a new regression test</a></span></dt>
+<dt><span class="sect1"><a href="#regression.run">26.1. Running the regression tests</a></span></dt>
+<dt><span class="sect1"><a href="#regression.new">26.2. Adding a new regression test</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#regression.fun.override">27.2.1. Overridable functions</a></span></dt>
-<dt><span class="sect2"><a href="#regression.fun.helper">27.2.2. Helper functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.override">26.2.1. Overridable functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.helper">26.2.2. Helper functions</a></span></dt>
</dl></dd>
</dl>
</div>
@@ -10530,7 +10468,7 @@ CFLAGS+= -Wall
how you can add new tests.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="regression.run"></a>27.1.�Running the regression tests</h2></div></div></div>
+<a name="regression.run"></a>26.1.�Running the regression tests</h2></div></div></div>
<p>You first need to install the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_regress/README.html"; target="_top"><code class="filename">pkgtools/pkg_regress</code></a>
package, which
provides the <span class="command"><strong>pkg_regress</strong></span> command. Then you
can simply run that command, which will run all tests in the
@@ -10538,7 +10476,7 @@ CFLAGS+= -Wall
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="regression.new"></a>27.2.�Adding a new regression test</h2></div></div></div>
+<a name="regression.new"></a>26.2.�Adding a new regression test</h2></div></div></div>
<p>Every directory in the <code class="filename">regress/</code>
directory that contains a file called <code class="filename">spec</code>
is considered a regression test. This file is a shell program
@@ -10547,7 +10485,7 @@ CFLAGS+= -Wall
needs.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="regression.fun.override"></a>27.2.1.�Overridable functions</h3></div></div></div>
+<a name="regression.fun.override"></a>26.2.1.�Overridable functions</h3></div></div></div>
<p>These functions do not take any parameters. Although they
are called in <span class="quote">“<span class="quote">set -e</span>”</span> mode, they don't stop at the
first failing command. See <a class="ulink" href="https://stackoverflow.com/q/4072984"; target="_top">this Stack Overflow
@@ -10595,7 +10533,7 @@ check_result() {
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="regression.fun.helper"></a>27.2.2.�Helper functions</h3></div></div></div>
+<a name="regression.fun.helper"></a>26.2.2.�Helper functions</h3></div></div></div>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="varname">regress_fail <em class="replaceable"><code>message...</code></em></code></span></dt>
<dd><p>This function makes the test fail with the given error message.</p></dd>
@@ -10626,10 +10564,10 @@ output_require "^[[:alpha:]+[[:space:]][
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
-<a name="porting"></a>Chapter�28.�Porting pkgsrc</h2></div></div></div>
+<a name="porting"></a>Chapter�27.�Porting pkgsrc</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl class="toc"><dt><span class="sect1"><a href="#porting.opsys">28.1. Porting pkgsrc to a new operating system</a></span></dt></dl>
+<dl class="toc"><dt><span class="sect1"><a href="#porting.opsys">27.1. Porting pkgsrc to a new operating system</a></span></dt></dl>
</div>
<p>The pkgsrc system has already been ported to many
operating systems, hardware architectures and compilers. This
@@ -10637,7 +10575,7 @@ output_require "^[[:alpha:]+[[:space:]][
portable.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="porting.opsys"></a>28.1.�Porting pkgsrc to a new operating system</h2></div></div></div>
+<a name="porting.opsys"></a>27.1.�Porting pkgsrc to a new operating system</h2></div></div></div>
<p>To port pkgsrc to a new operating system (called
<code class="literal">MyOS</code> in this example), you need to touch the
following files:</p>
@@ -10768,7 +10706,7 @@ WARN: PLIST:5: "share/bison.hairy" shoul
<code class="prompt">#</code> <strong class="userinput"><code>cd bison</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mkdir patches</code></strong></pre>
<p>Create <code class="filename">Makefile</code>, <code class="filename">DESCR</code> and
- <code class="filename">PLIST</code> (see <a class="xref" href="#components" title="Chapter�13.�Package components - files, directories and contents">Chapter�13, <i>Package components - files,
directories and contents</i></a>)
+ <code class="filename">PLIST</code> (see <a class="xref" href="#components" title="Chapter�12.�Package components - files, directories and contents">Chapter�12, <i>Package components - files,
directories and contents</i></a>)
then continue with fetching the distfile:</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make fetch</code></strong>
>> bison-1.25.tar.gz doesn't seem to exist on this system.
Index: pkgsrc/doc/pkgsrc.txt
diff -u pkgsrc/doc/pkgsrc.txt:1.296 pkgsrc/doc/pkgsrc.txt:1.297
--- pkgsrc/doc/pkgsrc.txt:1.296 Thu Jun 18 20:31:14 2020
+++ pkgsrc/doc/pkgsrc.txt Sat Jun 20 05:32:11 2020
@@ -14,7 +14,7 @@ The pkgsrc Developers
Copyright 1994-2020 The NetBSD Foundation, Inc
-$NetBSD: pkgsrc.xml,v 1.36 2020/01/03 15:55:24 leot Exp $
+$NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $
Abstract
@@ -154,144 +154,144 @@ I. The pkgsrc user's guide
II. The pkgsrc developer's guide
11. Getting help
- 12. Creating a new pkgsrc package from scratch
+ 12. Package components - files, directories and contents
- 12.1. Common types of packages
+ 12.1. Makefile
+ 12.2. distinfo
+ 12.3. patches/*
- 12.1.1. Perl modules
- 12.1.2. Python modules and programs
- 12.1.3. R packages
- 12.1.4. TeXlive packages
+ 12.3.1. Structure of a single patch file
+ 12.3.2. Creating patch files
+ 12.3.3. Sources where the patch files come from
+ 12.3.4. Patching guidelines
+ 12.3.5. Feedback to the author
- 12.2. Examples
+ 12.4. Other mandatory files
+ 12.5. Optional files
- 12.2.1. How the www/nvu package came into pkgsrc
+ 12.5.1. Files affecting the binary package
+ 12.5.2. Files affecting the build process
+ 12.5.3. Files affecting nothing at all
- 13. Package components - files, directories and contents
+ 12.6. work*
+ 12.7. files/*
- 13.1. Makefile
- 13.2. distinfo
- 13.3. patches/*
+ 13. The build process
- 13.3.1. Structure of a single patch file
- 13.3.2. Creating patch files
- 13.3.3. Sources where the patch files come from
- 13.3.4. Patching guidelines
- 13.3.5. Feedback to the author
+ 13.1. Introduction
+ 13.2. Program location
+ 13.3. Directories used during the build process
+ 13.4. Running a phase
+ 13.5. The fetch phase
- 13.4. Other mandatory files
- 13.5. Optional files
+ 13.5.1. What to fetch and where to get it from
+ 13.5.2. How are the files fetched?
- 13.5.1. Files affecting the binary package
- 13.5.2. Files affecting the build process
- 13.5.3. Files affecting nothing at all
+ 13.6. The checksum phase
+ 13.7. The extract phase
+ 13.8. The patch phase
+ 13.9. The tools phase
+ 13.10. The wrapper phase
+ 13.11. The configure phase
+ 13.12. The build phase
+ 13.13. The test phase
+ 13.14. The install phase
+ 13.15. The package phase
+ 13.16. Cleaning up
+ 13.17. Other helpful targets
- 13.6. work*
- 13.7. files/*
+ 14. Creating a new pkgsrc package from scratch
- 14. Programming in Makefiles
+ 14.1. Common types of packages
- 14.1. Caveats
- 14.2. Makefile variables
+ 14.1.1. Perl modules
+ 14.1.2. Python modules and programs
+ 14.1.3. R packages
+ 14.1.4. TeXlive packages
- 14.2.1. Naming conventions
+ 14.2. Examples
- 14.3. Code snippets
+ 14.2.1. How the www/nvu package came into pkgsrc
- 14.3.1. Adding things to a list
- 14.3.2. Echoing a string exactly as-is
- 14.3.3. Passing CFLAGS to GNU configure scripts
- 14.3.4. Handling possibly empty variables
+ 15. Programming in Makefiles
- 15. PLIST issues
+ 15.1. Caveats
+ 15.2. Makefile variables
- 15.1. RCS ID
- 15.2. Semi-automatic PLIST generation
- 15.3. Tweaking output of make print-PLIST
- 15.4. Variable substitution in PLIST
- 15.5. Man page compression
- 15.6. Changing PLIST source with PLIST_SRC
- 15.7. Platform-specific and differing PLISTs
- 15.8. Build-specific PLISTs
- 15.9. Sharing directories between packages
+ 15.2.1. Naming conventions
- 16. Buildlink methodology
+ 15.3. Code snippets
- 16.1. Converting packages to use buildlink3
- 16.2. Writing buildlink3.mk files
+ 15.3.1. Adding things to a list
+ 15.3.2. Echoing a string exactly as-is
+ 15.3.3. Passing CFLAGS to GNU configure scripts
+ 15.3.4. Handling possibly empty variables
- 16.2.1. Anatomy of a buildlink3.mk file
- 16.2.2. Updating BUILDLINK_API_DEPENDS.pkg and
- BUILDLINK_ABI_DEPENDS.pkg in buildlink3.mk files
+ 16. Options handling
- 16.3. Writing builtin.mk files
+ 16.1. Global default options
+ 16.2. Converting packages to use bsd.options.mk
+ 16.3. Option Names
+ 16.4. Determining the options of dependencies
- 16.3.1. Anatomy of a builtin.mk file
- 16.3.2. Global preferences for native or pkgsrc software
+ 17. Tools needed for building or running
- 17. The pkginstall framework
+ 17.1. Tools for pkgsrc builds
+ 17.2. Tools needed by packages
+ 17.3. Tools provided by platforms
- 17.1. Files and directories outside the installation prefix
+ 18. Buildlink methodology
- 17.1.1. Directory manipulation
- 17.1.2. File manipulation
+ 18.1. Converting packages to use buildlink3
+ 18.2. Writing buildlink3.mk files
- 17.2. Configuration files
+ 18.2.1. Anatomy of a buildlink3.mk file
+ 18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and
+ BUILDLINK_ABI_DEPENDS.pkg in buildlink3.mk files
- 17.2.1. How PKG_SYSCONFDIR is set
- 17.2.2. Telling the software where configuration files are
- 17.2.3. Patching installations
- 17.2.4. Disabling handling of configuration files
+ 18.3. Writing builtin.mk files
- 17.3. System startup scripts
+ 18.3.1. Anatomy of a builtin.mk file
+ 18.3.2. Global preferences for native or pkgsrc software
- 17.3.1. Disabling handling of system startup scripts
+ 19. PLIST issues
- 17.4. System users and groups
- 17.5. System shells
+ 19.1. RCS ID
+ 19.2. Semi-automatic PLIST generation
+ 19.3. Tweaking output of make print-PLIST
+ 19.4. Variable substitution in PLIST
+ 19.5. Man page compression
+ 19.6. Changing PLIST source with PLIST_SRC
+ 19.7. Platform-specific and differing PLISTs
+ 19.8. Build-specific PLISTs
+ 19.9. Sharing directories between packages
- 17.5.1. Disabling shell registration
+ 20. The pkginstall framework
- 17.6. Fonts
+ 20.1. Files and directories outside the installation prefix
- 17.6.1. Disabling automatic update of the fonts databases
+ 20.1.1. Directory manipulation
+ 20.1.2. File manipulation
- 18. Options handling
+ 20.2. Configuration files
- 18.1. Global default options
- 18.2. Converting packages to use bsd.options.mk
- 18.3. Option Names
- 18.4. Determining the options of dependencies
+ 20.2.1. How PKG_SYSCONFDIR is set
+ 20.2.2. Telling the software where configuration files are
+ 20.2.3. Patching installations
+ 20.2.4. Disabling handling of configuration files
- 19. The build process
+ 20.3. System startup scripts
- 19.1. Introduction
- 19.2. Program location
- 19.3. Directories used during the build process
- 19.4. Running a phase
- 19.5. The fetch phase
+ 20.3.1. Disabling handling of system startup scripts
- 19.5.1. What to fetch and where to get it from
- 19.5.2. How are the files fetched?
+ 20.4. System users and groups
+ 20.5. System shells
- 19.6. The checksum phase
- 19.7. The extract phase
- 19.8. The patch phase
- 19.9. The tools phase
- 19.10. The wrapper phase
- 19.11. The configure phase
- 19.12. The build phase
- 19.13. The test phase
- 19.14. The install phase
- 19.15. The package phase
- 19.16. Cleaning up
- 19.17. Other helpful targets
+ 20.5.1. Disabling shell registration
- 20. Tools needed for building or running
+ 20.6. Fonts
- 20.1. Tools for pkgsrc builds
- 20.2. Tools needed by packages
- 20.3. Tools provided by platforms
+ 20.6.1. Disabling automatic update of the fonts databases
21. Making your package work
@@ -365,7 +365,13 @@ II. The pkgsrc developer's guide
21.7. Marking packages as having problems
- 22. Debugging
+ 22. GNOME packaging and porting
+
+ 22.1. Meta packages
+ 22.2. Packaging a GNOME application
+ 22.3. Updating GNOME to a newer version
+ 22.4. Patching guidelines
+
23. Submitting and Committing
23.1. Submitting binary packages
@@ -378,46 +384,40 @@ II. The pkgsrc developer's guide
23.8. Moving a package in pkgsrc
24. Frequently Asked Questions
- 25. GNOME packaging and porting
-
- 25.1. Meta packages
- 25.2. Packaging a GNOME application
- 25.3. Updating GNOME to a newer version
- 25.4. Patching guidelines
III. The pkgsrc infrastructure internals
- 26. Design of the pkgsrc infrastructure
+ 25. Design of the pkgsrc infrastructure
- 26.1. The meaning of variable definitions
- 26.2. Avoiding problems before they arise
- 26.3. Variable evaluation
+ 25.1. The meaning of variable definitions
+ 25.2. Avoiding problems before they arise
+ 25.3. Variable evaluation
- 26.3.1. At load time
- 26.3.2. At runtime
+ 25.3.1. At load time
+ 25.3.2. At runtime
- 26.4. How can variables be specified?
- 26.5. Designing interfaces for Makefile fragments
+ 25.4. How can variables be specified?
+ 25.5. Designing interfaces for Makefile fragments
- 26.5.1. Procedures with parameters
- 26.5.2. Actions taken on behalf of parameters
+ 25.5.1. Procedures with parameters
+ 25.5.2. Actions taken on behalf of parameters
- 26.6. The order in which files are loaded
+ 25.6. The order in which files are loaded
- 26.6.1. The order in bsd.prefs.mk
- 26.6.2. The order in bsd.pkg.mk
+ 25.6.1. The order in bsd.prefs.mk
+ 25.6.2. The order in bsd.pkg.mk
- 27. Regression tests
+ 26. Regression tests
- 27.1. Running the regression tests
- 27.2. Adding a new regression test
+ 26.1. Running the regression tests
+ 26.2. Adding a new regression test
- 27.2.1. Overridable functions
- 27.2.2. Helper functions
+ 26.2.1. Overridable functions
+ 26.2.2. Helper functions
- 28. Porting pkgsrc
+ 27. Porting pkgsrc
- 28.1. Porting pkgsrc to a new operating system
+ 27.1. Porting pkgsrc to a new operating system
A. A simple example package: bison
@@ -452,8 +452,8 @@ E. Editing guidelines for the pkgsrc gui
List of Tables
1.1. Platforms supported by pkgsrc
-13.1. Patching examples
-25.1. PLIST handling for GNOME packages
+12.1. Patching examples
+22.1. PLIST handling for GNOME packages
Chapter 1. What is pkgsrc?
@@ -1477,7 +1477,7 @@ mk.conf, together with some comments tha
tree. It is possible to have many pkgsrc tree instances.)
* LOCALPATCHES: Directory for local patches that aren't part of pkgsrc. See
- Section 13.3, "patches/*" for more information.
+ Section 12.3, "patches/*" for more information.
* PKGMAKECONF: Location of the mk.conf file used by a package's BSD-style
Makefile. If this is not set, MAKECONF is set to /dev/null to avoid picking
@@ -1720,7 +1720,7 @@ a binary package.
7.2. Settings for creation of binary packages
-See Section 19.17, "Other helpful targets".
+See Section 13.17, "Other helpful targets".
Chapter 8. Creating binary packages for everything in pkgsrc (bulk builds)
@@ -2652,144 +2652,144 @@ more like a reference manual for pkgsrc.
Table of Contents
11. Getting help
-12. Creating a new pkgsrc package from scratch
+12. Package components - files, directories and contents
- 12.1. Common types of packages
+ 12.1. Makefile
+ 12.2. distinfo
+ 12.3. patches/*
- 12.1.1. Perl modules
- 12.1.2. Python modules and programs
- 12.1.3. R packages
- 12.1.4. TeXlive packages
+ 12.3.1. Structure of a single patch file
+ 12.3.2. Creating patch files
+ 12.3.3. Sources where the patch files come from
+ 12.3.4. Patching guidelines
+ 12.3.5. Feedback to the author
- 12.2. Examples
+ 12.4. Other mandatory files
+ 12.5. Optional files
- 12.2.1. How the www/nvu package came into pkgsrc
+ 12.5.1. Files affecting the binary package
+ 12.5.2. Files affecting the build process
+ 12.5.3. Files affecting nothing at all
-13. Package components - files, directories and contents
+ 12.6. work*
+ 12.7. files/*
- 13.1. Makefile
- 13.2. distinfo
- 13.3. patches/*
+13. The build process
- 13.3.1. Structure of a single patch file
- 13.3.2. Creating patch files
- 13.3.3. Sources where the patch files come from
- 13.3.4. Patching guidelines
- 13.3.5. Feedback to the author
+ 13.1. Introduction
+ 13.2. Program location
+ 13.3. Directories used during the build process
+ 13.4. Running a phase
+ 13.5. The fetch phase
- 13.4. Other mandatory files
- 13.5. Optional files
+ 13.5.1. What to fetch and where to get it from
+ 13.5.2. How are the files fetched?
- 13.5.1. Files affecting the binary package
- 13.5.2. Files affecting the build process
- 13.5.3. Files affecting nothing at all
+ 13.6. The checksum phase
+ 13.7. The extract phase
+ 13.8. The patch phase
+ 13.9. The tools phase
+ 13.10. The wrapper phase
+ 13.11. The configure phase
+ 13.12. The build phase
+ 13.13. The test phase
+ 13.14. The install phase
+ 13.15. The package phase
+ 13.16. Cleaning up
+ 13.17. Other helpful targets
- 13.6. work*
- 13.7. files/*
+14. Creating a new pkgsrc package from scratch
-14. Programming in Makefiles
+ 14.1. Common types of packages
- 14.1. Caveats
- 14.2. Makefile variables
+ 14.1.1. Perl modules
+ 14.1.2. Python modules and programs
+ 14.1.3. R packages
+ 14.1.4. TeXlive packages
- 14.2.1. Naming conventions
+ 14.2. Examples
- 14.3. Code snippets
+ 14.2.1. How the www/nvu package came into pkgsrc
- 14.3.1. Adding things to a list
- 14.3.2. Echoing a string exactly as-is
- 14.3.3. Passing CFLAGS to GNU configure scripts
- 14.3.4. Handling possibly empty variables
+15. Programming in Makefiles
-15. PLIST issues
+ 15.1. Caveats
+ 15.2. Makefile variables
- 15.1. RCS ID
- 15.2. Semi-automatic PLIST generation
- 15.3. Tweaking output of make print-PLIST
- 15.4. Variable substitution in PLIST
- 15.5. Man page compression
- 15.6. Changing PLIST source with PLIST_SRC
- 15.7. Platform-specific and differing PLISTs
- 15.8. Build-specific PLISTs
- 15.9. Sharing directories between packages
+ 15.2.1. Naming conventions
-16. Buildlink methodology
+ 15.3. Code snippets
- 16.1. Converting packages to use buildlink3
- 16.2. Writing buildlink3.mk files
+ 15.3.1. Adding things to a list
+ 15.3.2. Echoing a string exactly as-is
+ 15.3.3. Passing CFLAGS to GNU configure scripts
+ 15.3.4. Handling possibly empty variables
- 16.2.1. Anatomy of a buildlink3.mk file
- 16.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.
- pkg in buildlink3.mk files
+16. Options handling
- 16.3. Writing builtin.mk files
+ 16.1. Global default options
+ 16.2. Converting packages to use bsd.options.mk
+ 16.3. Option Names
+ 16.4. Determining the options of dependencies
- 16.3.1. Anatomy of a builtin.mk file
- 16.3.2. Global preferences for native or pkgsrc software
+17. Tools needed for building or running
-17. The pkginstall framework
+ 17.1. Tools for pkgsrc builds
+ 17.2. Tools needed by packages
+ 17.3. Tools provided by platforms
- 17.1. Files and directories outside the installation prefix
+18. Buildlink methodology
- 17.1.1. Directory manipulation
- 17.1.2. File manipulation
+ 18.1. Converting packages to use buildlink3
+ 18.2. Writing buildlink3.mk files
- 17.2. Configuration files
+ 18.2.1. Anatomy of a buildlink3.mk file
+ 18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.
+ pkg in buildlink3.mk files
- 17.2.1. How PKG_SYSCONFDIR is set
- 17.2.2. Telling the software where configuration files are
- 17.2.3. Patching installations
- 17.2.4. Disabling handling of configuration files
+ 18.3. Writing builtin.mk files
- 17.3. System startup scripts
+ 18.3.1. Anatomy of a builtin.mk file
+ 18.3.2. Global preferences for native or pkgsrc software
- 17.3.1. Disabling handling of system startup scripts
+19. PLIST issues
- 17.4. System users and groups
- 17.5. System shells
+ 19.1. RCS ID
+ 19.2. Semi-automatic PLIST generation
+ 19.3. Tweaking output of make print-PLIST
+ 19.4. Variable substitution in PLIST
+ 19.5. Man page compression
+ 19.6. Changing PLIST source with PLIST_SRC
+ 19.7. Platform-specific and differing PLISTs
+ 19.8. Build-specific PLISTs
+ 19.9. Sharing directories between packages
- 17.5.1. Disabling shell registration
+20. The pkginstall framework
- 17.6. Fonts
+ 20.1. Files and directories outside the installation prefix
- 17.6.1. Disabling automatic update of the fonts databases
+ 20.1.1. Directory manipulation
+ 20.1.2. File manipulation
-18. Options handling
+ 20.2. Configuration files
- 18.1. Global default options
- 18.2. Converting packages to use bsd.options.mk
- 18.3. Option Names
- 18.4. Determining the options of dependencies
+ 20.2.1. How PKG_SYSCONFDIR is set
+ 20.2.2. Telling the software where configuration files are
+ 20.2.3. Patching installations
+ 20.2.4. Disabling handling of configuration files
-19. The build process
+ 20.3. System startup scripts
- 19.1. Introduction
- 19.2. Program location
- 19.3. Directories used during the build process
- 19.4. Running a phase
- 19.5. The fetch phase
+ 20.3.1. Disabling handling of system startup scripts
- 19.5.1. What to fetch and where to get it from
- 19.5.2. How are the files fetched?
+ 20.4. System users and groups
+ 20.5. System shells
- 19.6. The checksum phase
- 19.7. The extract phase
- 19.8. The patch phase
- 19.9. The tools phase
- 19.10. The wrapper phase
- 19.11. The configure phase
- 19.12. The build phase
- 19.13. The test phase
- 19.14. The install phase
- 19.15. The package phase
- 19.16. Cleaning up
- 19.17. Other helpful targets
+ 20.5.1. Disabling shell registration
-20. Tools needed for building or running
+ 20.6. Fonts
- 20.1. Tools for pkgsrc builds
- 20.2. Tools needed by packages
- 20.3. Tools provided by platforms
+ 20.6.1. Disabling automatic update of the fonts databases
21. Making your package work
@@ -2862,7 +2862,13 @@ Table of Contents
21.7. Marking packages as having problems
-22. Debugging
+22. GNOME packaging and porting
+
+ 22.1. Meta packages
+ 22.2. Packaging a GNOME application
+ 22.3. Updating GNOME to a newer version
+ 22.4. Patching guidelines
+
23. Submitting and Committing
23.1. Submitting binary packages
@@ -2875,12 +2881,6 @@ Table of Contents
23.8. Moving a package in pkgsrc
24. Frequently Asked Questions
-25. GNOME packaging and porting
-
- 25.1. Meta packages
- 25.2. Packaging a GNOME application
- 25.3. Updating GNOME to a newer version
- 25.4. Patching guidelines
Chapter 11. Getting help
@@ -2907,607 +2907,219 @@ pkgsrc guide. If you don't find anything
a specialized chat program such as XChat. Pick any user name and join the
channel #pkgsrc.
-Chapter 12. Creating a new pkgsrc package from scratch
+Chapter 12. Package components - files, directories and contents
Table of Contents
-12.1. Common types of packages
-
- 12.1.1. Perl modules
- 12.1.2. Python modules and programs
- 12.1.3. R packages
- 12.1.4. TeXlive packages
-
-12.2. Examples
+12.1. Makefile
+12.2. distinfo
+12.3. patches/*
+
+ 12.3.1. Structure of a single patch file
+ 12.3.2. Creating patch files
+ 12.3.3. Sources where the patch files come from
+ 12.3.4. Patching guidelines
+ 12.3.5. Feedback to the author
+
+12.4. Other mandatory files
+12.5. Optional files
+
+ 12.5.1. Files affecting the binary package
+ 12.5.2. Files affecting the build process
+ 12.5.3. Files affecting nothing at all
- 12.2.1. How the www/nvu package came into pkgsrc
+12.6. work*
+12.7. files/*
-When you find a package that is not yet in pkgsrc, you most likely have a URL
-from where you can download the source code. Starting with this URL, creating a
-package involves only a few steps.
+Whenever you're preparing a package, there are a number of files involved which
+are described in the following sections.
- 1. First, install the packages pkgtools/url2pkg and pkgtools/pkglint.
+12.1. Makefile
- 2. Then, choose one of the top-level directories as the category in which you
- want to place your package. You can also create a directory of your own
- (maybe called local). In that category directory, create another directory
- for your package and change into it.
+Building, installation and creation of a binary package are all controlled by
+the package's Makefile. The Makefile describes various things about a package,
+for example from where to get it, how to configure, build, and install it.
- 3. Run the program url2pkg, which will ask you for a URL. Enter the URL of the
- distribution file (in most cases a .tar.gz file) and watch how the basic
- ingredients of your package are created automatically. The distribution
- file is extracted automatically to fill in some details in the Makefile
- that would otherwise have to be done manually.
+A package Makefile contains several sections that describe the package.
- 4. Examine the extracted files to determine the dependencies of your package.
- Ideally, this is mentioned in some README file, but things may differ. For
- each of these dependencies, look where it exists in pkgsrc, and if there is
- a file called buildlink3.mk in that directory, add a line to your package
- Makefile which includes that file just before the last line. If the
- buildlink3.mk file does not exist, it must be created first. The
- buildlink3.mk file makes sure that the package's include files and
- libraries are provided.
+In the first section there are the following variables, which should appear
+exactly in the order given here. The order and grouping of the variables is
+mostly historical and has no further meaning.
- If you just need binaries from a package, add a DEPENDS line to the
- Makefile, which specifies the version of the dependency and where it can be
- found in pkgsrc. This line should be placed in the third paragraph. If the
- dependency is only needed for building the package, but not when using it,
- use TOOL_DEPENDS or BUILD_DEPENDS instead of DEPENDS. The difference
- between TOOL_DEPENDS and BUILD_DEPENDS occurs when cross-compiling:
- TOOL_DEPENDS are native packages, i.e. packages for the architecture where
- the package is built; BUILD_DEPENDS are target packages, i.e. packages for
- the architecture for which the package is built. There is also
- TEST_DEPENDS, which is used to specify a dependency used only for testing
- the resulting package built, using the upstream project's included test
- suite. Your package may then look like this:
+ * DISTNAME is the basename of the distribution file to be downloaded from the
+ package's website.
- [...]
+ * PKGNAME is the name of the package, as used by pkgsrc. You need to provide
+ it if DISTNAME (which is the default) is not a good name for the package in
+ pkgsrc or DISTNAME is not provided (no distribution file is required).
+ Usually it is the pkgsrc directory name together with the version number.
+ It must match the regular expression ^[A-Za-z0-9][A-Za-z0-9-_.+]*$, that
+ is, it starts with a letter or digit, and contains only letters, digits,
+ dashes, underscores, dots and plus signs.
- TOOL_DEPENDS+= libxslt-[0-9]*:../../textproc/libxslt
- DEPENDS+= screen-[0-9]*:../../misc/screen
- DEPENDS+= screen>=4.0:../../misc/screen
+ * CATEGORIES is a list of categories which the package fits in. You can
+ choose any of the top-level directories of pkgsrc for it.
- [...]
+ Currently the following values are available for CATEGORIES. If more than
+ one is used, they need to be separated by spaces:
- .include "../../category/package/buildlink3.mk"
- .include "../../devel/glib2/buildlink3.mk"
- .include "../../mk/bsd.pkg.mk"
+ archivers cross geography meta-pkgs security
+ audio databases graphics misc shells
+ benchmarks devel ham multimedia sysutils
+ biology editors inputmethod net textproc
+ cad emulators lang news time
+ chat finance mail parallel wm
+ comms fonts math pkgtools www
+ converters games mbone print x11
- 5. Run pkglint to see what things still need to be done to make your package a
- "good" one. If you don't know what pkglint's warnings want to tell you, try
- pkglint --explain or pkglint -e, which outputs additional explanations.
+ * MASTER_SITES, DYNAMIC_MASTER_SITES, DIST_SUBDIR, EXTRACT_SUFX and DISTFILES
+ are discussed in detail in Section 13.5, "The fetch phase".
- 6. In many cases the package is not yet ready to build. You can find
- instructions for the most common cases in the next section, Section 12.1,
- "Common types of packages". After you have followed the instructions over
- there, you can hopefully continue here.
+The second section contains information about separately downloaded patches, if
+any.
- 7. Run bmake clean to clean the working directory from the extracted files.
- Besides these files, a lot of cache files and other system information has
- been saved in the working directory, which may become wrong after you
- edited the Makefile.
+ * PATCHFILES: Name(s) of additional files that contain distribution patches.
+ There is no default. pkgsrc will look for them at PATCH_SITES. They will
+ automatically be uncompressed before patching if the names end with .gz or
+ .Z.
- 8. Now, run bmake to build the package. For the various things that can go
- wrong in this phase, consult Chapter 21, Making your package work.
+ * PATCH_SITES: Primary location(s) for distribution patch files (see
+ PATCHFILES above) if not found locally.
- 9. When the package builds fine, the next step is to install the package. Run
- bmake install and hope that everything works.
+ * PATCH_DIST_STRIP: an argument to patch(1) that sets the pathname strip
+ count to help find the correct files to patch. It defaults to -p0.
-10. Up to now, the file PLIST, which contains a list of the files that are
- installed by the package, is nearly empty. Run bmake print-PLIST >PLIST to
- generate a probably correct list. Check the file using your preferred text
- editor to see if the list of files looks plausible.
+The third section contains the following variables.
-11. Run pkglint again to see if the generated PLIST contains garbage or not.
+ * MAINTAINER is the email address of the person who feels responsible for
+ this package, and who is most likely to look at problems or questions
+ regarding this package which have been reported with send-pr(1). Other
+ developers may contact the MAINTAINER before making changes to the package,
+ but are not required to do so. When packaging a new program, set MAINTAINER
+ to yourself. If you really can't maintain the package for future updates,
+ set it to <pkgsrc-users%NetBSD.org@localhost>.
-12. When you ran bmake install, the package has been registered in the database
- of installed files, but with an empty list of files. To fix this, run bmake
- deinstall and bmake install again. Now the package is registered with the
- list of files from PLIST.
+ * OWNER should be used instead of MAINTAINER when you do not want other
+ developers to update or change the package without contacting you first. A
+ package Makefile should contain one of MAINTAINER or OWNER, but not both.
-13. Run bmake package to create a binary package from the set of installed
- files.
+ * HOMEPAGE is a URL where users can find more information about the package.
-12.1. Common types of packages
+ * COMMENT is a one-line description of the package (should not include the
+ package name).
-12.1.1. Perl modules
+ * LICENSE indicates the license(s) applicable for the package. See
+ Section 21.1.3, "Handling licenses" for further details.
-Simple Perl modules are handled automatically by url2pkg, including
-dependencies.
+Other variables that affect the build:
-12.1.2. Python modules and programs
+ * WRKSRC: The directory where the interesting distribution files of the
+ package are found. The default is ${WRKDIR}/${DISTNAME}, which works for
+ most packages.
-Python modules and programs packages are easily created using a set of
-predefined variables.
+ If a package doesn't create a subdirectory for itself (most GNU software
+ does, for instance), but extracts itself in the current directory, you
+ should set WRKSRC=${WRKDIR}.
-If some Python versions are not supported by the software, set the
-PYTHON_VERSIONS_INCOMPATIBLE variable to the Python versions that are not
-supported, e.g.
+ If a package doesn't create a subdirectory with the name of DISTNAME but
+ some different name, set WRKSRC to point to the proper name in ${WRKDIR},
+ for example WRKSRC=${WRKDIR}/${DISTNAME}/unix. See lang/tcl and x11/tk for
+ other examples.
-PYTHON_VERSIONS_INCOMPATIBLE= 27
+ The name of the working directory created by pkgsrc is taken from the
+ WRKDIR_BASENAME variable. By default, its value is work. If you want to use
+ the same pkgsrc tree for building different kinds of binary packages, you
+ can change the variable according to your needs. Two other variables handle
+ common cases of setting WRKDIR_BASENAME individually. If OBJHOSTNAME is
+ defined in mk.conf, the first component of the host's name is attached to
+ the directory name. If OBJMACHINE is defined, the platform name is
+ attached, which might look like work.i386 or work.sparc.
-If the packaged software is a Python module, include one of ../../lang/python/
-egg.mk, ../../lang/python/distutils.mk, or ../../lang/python/extension.mk.
+Please pay attention to the following gotchas:
-Most Python packages use either "distutils" or easy-setup/setuptools ("eggs").
-If the packaged software is using setuptools, you only need to include "../../
-lang/python/egg.mk". Otherwise, if the software uses "distutils", include "..
-/../lang/python/distutils.mk", so pkgsrc will use this framework. "distutils"
-uses a script called setup.py; if the "distutils" driver is not called
-setup.py, set the PYSETUP variable to the name of the script.
+ * Add MANCOMPRESSED if man pages are installed in compressed form by the
+ package. For packages using BSD-style makefiles which honor MANZ, there is
+ MANCOMPRESSED_IF_MANZ.
-Either way, the package directory should be called "py-software" and PKGNAME
-should be set to "${PYPKGPREFIX}-${DISTNAME}", e.g.
+ * Replace /usr/local with "${PREFIX}" in all files (see patches, below).
-DISTNAME= foopymodule-1.2.10
-PKGNAME= ${PYPKGPREFIX}-${DISTNAME}
+ * If the package installs any info files, see Section 21.6.7, "Packages
+ installing info files".
-If it is an application, include "../../lang/python/application.mk". In order
-to correctly set the path to the Python interpreter, use the REPLACE_PYTHON
-variable and set it to the list of files (paths relative to WRKSRC) that must
-be corrected. For example:
+12.2. distinfo
-REPLACE_PYTHON= *.py
+The distinfo file contains the message digest, or checksum, of each distfile
+needed for the package. This ensures that the distfiles retrieved from the
+Internet have not been corrupted during transfer or altered by a malign force
+to introduce a security hole. To provide maximum security, all distfiles are
+protected using three different message digest algorithms (SHA1, RMD160,
+SHA512), as well as the file size.
-Some Python modules have separate distributions for Python-2.x and Python-3.x
-support. In pkgsrc this is handled by the versioned_dependencies.mk file. Set
-PYTHON_VERSIONED_DEPENDENCIES to the list of packages that should be depended
-upon and include "../../lang/python/versioned_dependencies.mk", then the pkgsrc
-infrastructure will depend on the appropriate package version. For example:
+The distinfo file also contains the checksums for all the patches found in the
+patches directory (see Section 12.3, "patches/*"). These checksums ensure that
+patches are only applied intentionally and that they don't accidentally change,
+e.g. when merging different changes together. They also make sure that new
+patches are actually added to CVS and old ones are removed. Too see whether the
+patches and the distinfo file match, run pkglint after changing the patches.
-PYTHON_VERSIONED_DEPENDENCIES=dialog
+To regenerate the distinfo file, use the make distinfo command.
-Look inside versioned_dependencies.mk for a list of supported packages.
+Some packages have different sets of distfiles depending on the platform, for
+example lang/openjdk8. These are kept in the same distinfo file and care should
+be taken when upgrading such a package to ensure distfile information is not
+lost.
-12.1.3. R packages
+12.3. patches/*
-Simple R packages from CRAN are handled automatically by R2pkg, which is
-available in pkgtools/R2pkg. Individual packages (and optionally their
-dependencies) may be created and updated. R packages generally follow the same
-form, and most of the relevant information needed is contained in a DESCRIPTION
-file as part of each R package on CRAN. Consequently, R2pkg downloads that
-information and creates or updates a package in the canonical form. The
-resulting package should be reviewed for correctness.
+Some packages don't work out-of-the box on the various platforms that are
+supported by pkgsrc. These packages need to be patched to make them work. The
+patch files can be found in the patches/ directory.
-12.1.4. TeXlive packages
+In the patch phase, these patches are applied to the files in WRKSRC directory
+after extracting them, in alphabetic order.
-TeXlive packages from CTAN are handled automatically by texlive2pkg, which is
-available in pkgtools/texlive2pkg.
+12.3.1. Structure of a single patch file
-If the TeXlive package name is not known, it may be useful to search CTAN. A "
-Contained in" field on the package page typically identifies the basename of
-the package file in the TeXlive archive.
+The patch-* files should be in diff -bu format, and apply without a fuzz to
+avoid problems. (To force patches to apply with fuzz you can set
+PATCH_FUZZ_FACTOR=-F2). Furthermore, each patch should contain only changes for
+a single file, and no file should be patched by more than one patch file. This
+helps to keep future modifications simple.
-If the TeXlive package name is known, download the files from the TeXlive
-archive. For package foo, you will need to download foo.tar.xz. Most TeXlive
-packages also have associated documentation packages, so download
-foo.doc.tar.xz at the same time. These files should be placed in the
-appropriate category directory, which is often but not always print. Then run
-the following command in the category directory.
+Each patch file is structured as follows: In the first line, there is the RCS
+Id of the patch itself. The second line should be empty for aesthetic reasons.
+After that, there should be a comment for each change that the patch does.
+There are a number of standard cases:
-texlive2pkg foo.tar.xz foo.doc.tar.xz
+ * Patches for commonly known vulnerabilities should mention the vulnerability
+ ID (CAN, CVE).
-This will create two packages, tex-foo and tex-foo-doc. Be sure to check that
-both packages are correct.
+ * Patches that change source code should mention the platform and other
+ environment (for example, the compiler) that the patch is needed for.
-Finally, CTAN currently does not include version information in package
-filenames and changes their contents periodically when updates occur.
-Consequently, pkgsrc avoids downloading distfiles directly from CTAN and
-instead relies on the pkgsrc archives. For each new or updated TeXlive package,
-e.g., the main one and the corresponding documentation, upload the distfiles
-with the following command in each package directory.
+The patch should be commented so that any developer who knows the code of the
+application can make some use of the patch. Special care should be taken for
+the upstream developers, since we generally want that they accept our patches,
+so we have less work in the future.
-make upload-distfiles
+12.3.2. Creating patch files
-12.2. Examples
+One important thing to mention is to pay attention that no RCS IDs get stored
+in the patch files, as these will cause problems when later checked into the
+NetBSD CVS tree. Use the pkgdiff command from the pkgtools/pkgdiff package to
+avoid these problems.
-12.2.1. How the www/nvu package came into pkgsrc
+For even more automation, we recommend using mkpatches from the same package to
+make a whole set of patches. You just have to backup files before you edit them
+to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using
+pkgvi again from the same package. If you upgrade a package this way, you can
+easily compare the new set of patches with the previously existing one with
+patchdiff. The files in patches are replaced by new files, so carefully check
+if you want to take all the changes.
-12.2.1.1. The initial package
-
-Looking at the file pkgsrc/doc/TODO, I saw that the "nvu" package has not yet
-been imported into pkgsrc. As the description says it has to do with the web,
-the obvious choice for the category is "www".
-
-$ mkdir www/nvu
-$ cd www/nvu
-
-The web site says that the sources are available as a tar file, so I fed that
-URL to the url2pkg program:
-
-$ url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
-
-My editor popped up, and I added a PKGNAME line below the DISTNAME line, as the
-package name should not have the word "sources" in it. I also filled in the
-MAINTAINER, HOMEPAGE and COMMENT fields. Then the package Makefile looked like
-that:
-
-# $NetBSD $
-#
-
-DISTNAME= nvu-1.0-sources
-PKGNAME= nvu-1.0
-CATEGORIES= www
-MASTER_SITES= http://cvs.nvu.com/download/
-EXTRACT_SUFX= .tar.bz2
-
-MAINTAINER= rillig%NetBSD.org@localhost
-HOMEPAGE= http://cvs.nvu.com/
-COMMENT= Web Authoring System
-
-# url2pkg-marker (please do not remove this line.)
-.include "../../mk/bsd.pkg.mk"
-
-On the first line of output above, an artificial space has been added between
-NetBSD and $, this is a workaround to prevent CVS expanding to the filename of
-the guide.
-
-Then, I quit the editor and watched pkgsrc downloading a large source archive:
-
-url2pkg> Running "make makesum" ...
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Fetching nvu-1.0-sources.tar.bz2
-Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
-100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA
-29687976 bytes retrieved in 03:12 (150.77 KB/s)
-url2pkg> Running "make extract" ...
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
-=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
-work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
-===> Installing dependencies for nvu-1.0
-===> Overriding tools for nvu-1.0
-===> Extracting for nvu-1.0
-url2pkg> Adjusting the Makefile.
-
-Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
-
-Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
-
-12.2.1.2. Fixing all kinds of problems to make the package work
-
-Now that the package has been extracted, let's see what's inside it. The
-package has a README.txt, but that only says something about mozilla, so it's
-probably useless for seeing what dependencies this package has. But since there
-is a GNU configure script in the package, let's hope that it will complain
-about everything it needs.
-
-$ bmake
-=> Required installed package digest>=20010302: digest-20060826 found
-=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
-=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
-===> Patching for nvu-1.0
-===> Creating toolchain wrappers for nvu-1.0
-===> Configuring for nvu-1.0
-[...]
-configure: error: Perl 5.004 or higher is required.
-[...]
-WARNING: Please add USE_TOOLS+=perl to the package Makefile.
-[...]
-
-That worked quite well. So I opened the package Makefile in my editor, and
-since it already has a USE_TOOLS line, I just appended "perl" to it. Since the
-dependencies of the package have changed now, and since a perl wrapper is
-automatically installed in the "tools" phase, I need to build the package from
-scratch.
-
-$ bmake clean
-===> Cleaning for nvu-1.0
-$ bmake
-[...]
-*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
-GNU Make. You will not be able to build Mozilla without GNU Make.
-[...]
-
-So I added "gmake" to the USE_TOOLS line and tried again (from scratch).
-
-[...]
-checking for GTK - version >= 1.2.0... no
-*** Could not run GTK test program, checking why...
-[...]
-
-Now to the other dependencies. The first question is: Where is the GTK package
-hidden in pkgsrc?
-
-$ echo ../../*/gtk*
-[many packages ...]
-$ echo ../../*/gtk
-../../x11/gtk
-$ echo ../../*/gtk2
-../../x11/gtk2
-$ echo ../../*/gtk2/bui*
-../../x11/gtk2/buildlink3.mk
-
-The first try was definitely too broad. The second one had exactly one result,
-which is very good. But there is one pitfall with GNOME packages. Before GNOME
-2 had been released, there were already many GNOME 1 packages in pkgsrc. To be
-able to continue to use these packages, the GNOME 2 packages were imported as
-separate packages, and their names usually have a "2" appended. So I checked
-whether this was the case here, and indeed it was.
-
-Since the GTK2 package has a buildlink3.mk file, adding the dependency is very
-easy. I just inserted an .include line before the last line of the package
-Makefile, so that it now looks like this:
-
-[...]
-.include "../../x11/gtk2/buildlink3.mk"
-.include "../../mk/bsd.pkg.mk
-
-After another bmake clean && bmake, the answer was:
-
-[...]
-checking for gtk-config... /home/roland/pkg/bin/gtk-config
-checking for GTK - version >= 1.2.0... no
-*** Could not run GTK test program, checking why...
-*** The test program failed to compile or link. See the file config.log for the
-*** exact error that occured. This usually means GTK was incorrectly installed
-*** or that you have moved GTK since it was installed. In the latter case, you
-*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
-configure: error: Test for GTK failed.
-[...]
-
-In this particular case, the assumption that "every package prefers GNOME 2"
-had been wrong. The first of the lines above told me that this package really
-wanted to have the GNOME 1 version of GTK. If the package had looked for GTK2,
-it would have looked for pkg-config instead of gtk-config. So I changed the x11
-/gtk2 to x11/gtk in the package Makefile, and tried again.
-
-[...]
-cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" [...]
-In file included from xpidl.c:42:
-xpidl.h:53:24: libIDL/IDL.h: No such file or directory
-In file included from xpidl.c:42:
-xpidl.h:132: error: parse error before "IDL_ns"
-[...]
-
-The package still does not find all of its dependencies. Now the question is:
-Which package provides the libIDL/IDL.h header file?
-
-$ echo ../../*/*idl*
-../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
-$ echo ../../*/*IDL*
-../../net/libIDL
-
-Let's take the one from the second try. So I included the ../../net/libIDL/
-buildlink3.mk file and tried again. But the error didn't change. After digging
-through some of the code, I concluded that the build process of the package was
-broken and couldn't have ever worked, but since the Mozilla source tree is
-quite large, I didn't want to fix it. So I added the following to the package
-Makefile and tried again:
-
-CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
-BUILDLINK_TRANSFORM+= l:IDL:IDL-2
-
-The latter line is needed because the package expects the library libIDL.so,
-but only libIDL-2.so is available. So I told the compiler wrapper to rewrite
-that on the fly.
-
-The next problem was related to a recent change of the FreeType interface. I
-looked up in www/seamonkey which patch files were relevant for this issue and
-copied them to the patches directory. Then I retried, fixed the patches so that
-they applied cleanly and retried again. This time, everything worked.
-
-12.2.1.3. Installing the package
-
-$ bmake CHECK_FILES=no install
-[...]
-$ bmake print-PLIST >PLIST
-$ bmake deinstall
-$ bmake install
-
-Chapter 13. Package components - files, directories and contents
-
-Table of Contents
-
-13.1. Makefile
-13.2. distinfo
-13.3. patches/*
-
- 13.3.1. Structure of a single patch file
- 13.3.2. Creating patch files
- 13.3.3. Sources where the patch files come from
- 13.3.4. Patching guidelines
- 13.3.5. Feedback to the author
-
-13.4. Other mandatory files
-13.5. Optional files
-
- 13.5.1. Files affecting the binary package
- 13.5.2. Files affecting the build process
- 13.5.3. Files affecting nothing at all
-
-13.6. work*
-13.7. files/*
-
-Whenever you're preparing a package, there are a number of files involved which
-are described in the following sections.
-
-13.1. Makefile
-
-Building, installation and creation of a binary package are all controlled by
-the package's Makefile. The Makefile describes various things about a package,
-for example from where to get it, how to configure, build, and install it.
-
-A package Makefile contains several sections that describe the package.
-
-In the first section there are the following variables, which should appear
-exactly in the order given here. The order and grouping of the variables is
-mostly historical and has no further meaning.
-
- * DISTNAME is the basename of the distribution file to be downloaded from the
- package's website.
-
- * PKGNAME is the name of the package, as used by pkgsrc. You need to provide
- it if DISTNAME (which is the default) is not a good name for the package in
- pkgsrc or DISTNAME is not provided (no distribution file is required).
- Usually it is the pkgsrc directory name together with the version number.
- It must match the regular expression ^[A-Za-z0-9][A-Za-z0-9-_.+]*$, that
- is, it starts with a letter or digit, and contains only letters, digits,
- dashes, underscores, dots and plus signs.
-
- * CATEGORIES is a list of categories which the package fits in. You can
- choose any of the top-level directories of pkgsrc for it.
-
- Currently the following values are available for CATEGORIES. If more than
- one is used, they need to be separated by spaces:
-
- archivers cross geography meta-pkgs security
- audio databases graphics misc shells
- benchmarks devel ham multimedia sysutils
- biology editors inputmethod net textproc
- cad emulators lang news time
- chat finance mail parallel wm
- comms fonts math pkgtools www
- converters games mbone print x11
-
- * MASTER_SITES, DYNAMIC_MASTER_SITES, DIST_SUBDIR, EXTRACT_SUFX and DISTFILES
- are discussed in detail in Section 19.5, "The fetch phase".
-
-The second section contains information about separately downloaded patches, if
-any.
-
- * PATCHFILES: Name(s) of additional files that contain distribution patches.
- There is no default. pkgsrc will look for them at PATCH_SITES. They will
- automatically be uncompressed before patching if the names end with .gz or
- .Z.
-
- * PATCH_SITES: Primary location(s) for distribution patch files (see
- PATCHFILES above) if not found locally.
-
- * PATCH_DIST_STRIP: an argument to patch(1) that sets the pathname strip
- count to help find the correct files to patch. It defaults to -p0.
-
-The third section contains the following variables.
-
- * MAINTAINER is the email address of the person who feels responsible for
- this package, and who is most likely to look at problems or questions
- regarding this package which have been reported with send-pr(1). Other
- developers may contact the MAINTAINER before making changes to the package,
- but are not required to do so. When packaging a new program, set MAINTAINER
- to yourself. If you really can't maintain the package for future updates,
- set it to <pkgsrc-users%NetBSD.org@localhost>.
-
- * OWNER should be used instead of MAINTAINER when you do not want other
- developers to update or change the package without contacting you first. A
- package Makefile should contain one of MAINTAINER or OWNER, but not both.
-
- * HOMEPAGE is a URL where users can find more information about the package.
-
- * COMMENT is a one-line description of the package (should not include the
- package name).
-
- * LICENSE indicates the license(s) applicable for the package. See
- Section 21.1.3, "Handling licenses" for further details.
-
-Other variables that affect the build:
-
- * WRKSRC: The directory where the interesting distribution files of the
- package are found. The default is ${WRKDIR}/${DISTNAME}, which works for
- most packages.
-
- If a package doesn't create a subdirectory for itself (most GNU software
- does, for instance), but extracts itself in the current directory, you
- should set WRKSRC=${WRKDIR}.
-
- If a package doesn't create a subdirectory with the name of DISTNAME but
- some different name, set WRKSRC to point to the proper name in ${WRKDIR},
- for example WRKSRC=${WRKDIR}/${DISTNAME}/unix. See lang/tcl and x11/tk for
- other examples.
-
- The name of the working directory created by pkgsrc is taken from the
- WRKDIR_BASENAME variable. By default, its value is work. If you want to use
- the same pkgsrc tree for building different kinds of binary packages, you
- can change the variable according to your needs. Two other variables handle
- common cases of setting WRKDIR_BASENAME individually. If OBJHOSTNAME is
- defined in mk.conf, the first component of the host's name is attached to
- the directory name. If OBJMACHINE is defined, the platform name is
- attached, which might look like work.i386 or work.sparc.
-
-Please pay attention to the following gotchas:
-
- * Add MANCOMPRESSED if man pages are installed in compressed form by the
- package. For packages using BSD-style makefiles which honor MANZ, there is
- MANCOMPRESSED_IF_MANZ.
-
- * Replace /usr/local with "${PREFIX}" in all files (see patches, below).
-
- * If the package installs any info files, see Section 21.6.7, "Packages
- installing info files".
-
-13.2. distinfo
-
-The distinfo file contains the message digest, or checksum, of each distfile
-needed for the package. This ensures that the distfiles retrieved from the
-Internet have not been corrupted during transfer or altered by a malign force
-to introduce a security hole. To provide maximum security, all distfiles are
-protected using three different message digest algorithms (SHA1, RMD160,
-SHA512), as well as the file size.
-
-The distinfo file also contains the checksums for all the patches found in the
-patches directory (see Section 13.3, "patches/*"). These checksums ensure that
-patches are only applied intentionally and that they don't accidentally change,
-e.g. when merging different changes together. They also make sure that new
-patches are actually added to CVS and old ones are removed. Too see whether the
-patches and the distinfo file match, run pkglint after changing the patches.
-
-To regenerate the distinfo file, use the make distinfo command.
-
-Some packages have different sets of distfiles depending on the platform, for
-example lang/openjdk8. These are kept in the same distinfo file and care should
-be taken when upgrading such a package to ensure distfile information is not
-lost.
-
-13.3. patches/*
-
-Some packages don't work out-of-the box on the various platforms that are
-supported by pkgsrc. These packages need to be patched to make them work. The
-patch files can be found in the patches/ directory.
-
-In the patch phase, these patches are applied to the files in WRKSRC directory
-after extracting them, in alphabetic order.
-
-13.3.1. Structure of a single patch file
-
-The patch-* files should be in diff -bu format, and apply without a fuzz to
-avoid problems. (To force patches to apply with fuzz you can set
-PATCH_FUZZ_FACTOR=-F2). Furthermore, each patch should contain only changes for
-a single file, and no file should be patched by more than one patch file. This
-helps to keep future modifications simple.
-
-Each patch file is structured as follows: In the first line, there is the RCS
-Id of the patch itself. The second line should be empty for aesthetic reasons.
-After that, there should be a comment for each change that the patch does.
-There are a number of standard cases:
-
- * Patches for commonly known vulnerabilities should mention the vulnerability
- ID (CAN, CVE).
-
- * Patches that change source code should mention the platform and other
- environment (for example, the compiler) that the patch is needed for.
-
-The patch should be commented so that any developer who knows the code of the
-application can make some use of the patch. Special care should be taken for
-the upstream developers, since we generally want that they accept our patches,
-so we have less work in the future.
-
-13.3.2. Creating patch files
-
-One important thing to mention is to pay attention that no RCS IDs get stored
-in the patch files, as these will cause problems when later checked into the
-NetBSD CVS tree. Use the pkgdiff command from the pkgtools/pkgdiff package to
-avoid these problems.
-
-For even more automation, we recommend using mkpatches from the same package to
-make a whole set of patches. You just have to backup files before you edit them
-to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using
-pkgvi again from the same package. If you upgrade a package this way, you can
-easily compare the new set of patches with the previously existing one with
-patchdiff. The files in patches are replaced by new files, so carefully check
-if you want to take all the changes.
-
-When you have finished a package, remember to generate the checksums for the
-patch files by using the make makepatchsum command, see Section 13.2,
-"distinfo".
+When you have finished a package, remember to generate the checksums for the
+patch files by using the make makepatchsum command, see Section 12.2,
+"distinfo".
When adding a patch that corrects a problem in the distfile (rather than e.g.
enforcing pkgsrc's view of where man pages should go), send the patch as a bug
@@ -3520,7 +3132,7 @@ convention patch-[a-z][a-z], but new pat
the filename. mkpatches included in pkgtools/pkgdiff takes care of the name
automatically.
-13.3.3. Sources where the patch files come from
+12.3.3. Sources where the patch files come from
If you want to share patches between multiple packages in pkgsrc, e.g. because
they use the same distfiles, set PATCHDIR to the path where the patch files can
@@ -3540,7 +3152,7 @@ for pkgsrc/graphics/png, keep it in $LOC
files in the named directory are expected to be patch files, and they are
applied after pkgsrc patches are applied.
-13.3.4. Patching guidelines
+12.3.4. Patching guidelines
When fixing a portability issue in the code do not use preprocessor magic to
check for the current operating system nor platform. Doing so hurts portability
@@ -3564,7 +3176,7 @@ doesn't work unless it is right!
Some typical examples:
-Table 13.1. Patching examples
+Table 12.1. Patching examples
+-------------------------------------------------------------------------------------------+
| Where | Incorrect | Correct |
@@ -3591,7 +3203,7 @@ Table 13.1. Patching examples
+-------------------------------------------------------------------------------------------+
-13.3.5. Feedback to the author
+12.3.5. Feedback to the author
Always, always, always feed back any portability fixes or improvements you do
to a package to the mainstream developers. This is the only way to get their
@@ -3611,7 +3223,7 @@ patch comment.
Support the idea of free software!
-13.4. Other mandatory files
+12.4. Other mandatory files
DESCR
@@ -3625,12 +3237,12 @@ PLIST
This file governs the files that are installed on your system: all the
binaries, manual pages, etc. There are other directives which may be
entered in this file, to control the creation and deletion of directories,
- and the location of inserted files. See Chapter 15, PLIST issues for more
+ and the location of inserted files. See Chapter 19, PLIST issues for more
information.
-13.5. Optional files
+12.5. Optional files
-13.5.1. Files affecting the binary package
+12.5.1. Files affecting the binary package
INSTALL
@@ -3638,7 +3250,7 @@ INSTALL
extraction and before files are moved in place, the second time after the
files to install are moved in place. This can be used to do any custom
procedures not possible with @exec commands in PLIST. See pkg_add(1) and
- pkg_create(1) for more information. See also Section 17.1, "Files and
+ pkg_create(1) for more information. See also Section 20.1, "Files and
directories outside the installation prefix". Please note that you can
modify variables in it easily by using FILES_SUBST in the package's
Makefile:
@@ -3685,7 +3297,7 @@ ALTERNATIVES
Each line of the file contains two filenames, first the wrapper and then
the alternative provided by the package. Both paths are relative to PREFIX.
-13.5.2. Files affecting the build process
+12.5.2. Files affecting the build process
Makefile.common
@@ -3698,7 +3310,7 @@ Makefile.common
buildlink3.mk
This file contains the dependency information for the buildlink3 framework
- (see Chapter 16, Buildlink methodology).
+ (see Chapter 18, Buildlink methodology).
hacks.mk
@@ -3709,1154 +3321,1464 @@ hacks.mk
options.mk
This file contains the code for the package-specific options (see
- Chapter 18, Options handling) that can be selected by the user. If a
+ Chapter 16, Options handling) that can be selected by the user. If a
package has only one or two options, it is equally acceptable to put the
code directly into the Makefile.
-13.5.3. Files affecting nothing at all
+12.5.3. Files affecting nothing at all
+
+README*
+
+ These files do not take place in the creation of a package and thus are
+ purely informative to the package developer.
+
+TODO
+
+ This file contains things that need to be done to make the package even
+ better.
+
+12.6. work*
+
+When you type make, the distribution files are unpacked into the directory
+denoted by WRKDIR. It can be removed by running make clean. Besides the
+sources, this directory is also used to keep various timestamp files. The
+directory gets removed completely on clean. The default is ${.CURDIR}/work or $
+{.CURDIR}/work.${MACHINE_ARCH} if OBJMACHINE is set.
+
+12.7. files/*
+
+If you have any files that you wish to be placed in the package prior to
+configuration or building, you can place these files here and use a ${CP}
+command in the "post-extract" target to achieve this.
+
+If you want to share files in this way with other packages, set the FILESDIR
+variable to point to the other package's files directory, e.g.:
+
+FILESDIR= ../../editors/xemacs/files
+
+Chapter 13. The build process
+
+Table of Contents
+
+13.1. Introduction
+13.2. Program location
+13.3. Directories used during the build process
+13.4. Running a phase
+13.5. The fetch phase
+
+ 13.5.1. What to fetch and where to get it from
+ 13.5.2. How are the files fetched?
+
+13.6. The checksum phase
+13.7. The extract phase
+13.8. The patch phase
+13.9. The tools phase
+13.10. The wrapper phase
+13.11. The configure phase
+13.12. The build phase
+13.13. The test phase
+13.14. The install phase
+13.15. The package phase
+13.16. Cleaning up
+13.17. Other helpful targets
+
+13.1. Introduction
+
+This chapter gives a detailed description on how a package is built. Building a
+package is separated into different phases (for example fetch, build, install),
+all of which are described in the following sections. Each phase is split into
+so-called stages, which take the name of the containing phase, prefixed by one
+of pre-, do- or post-. (Examples are pre-configure, post-build.) Most of the
+actual work is done in the do-* stages.
+
+Never override the regular targets (like fetch), if you have to, override the
+do-* ones instead.
+
+The basic steps for building a program are always the same. First the program's
+source (distfile) must be brought to the local system and then extracted. After
+any pkgsrc-specific patches to compile properly are applied, the software can
+be configured, then built (usually by compiling), and finally the generated
+binaries, etc. can be put into place on the system.
+
+To get more details about what is happening at each step, you can set the
+PKG_VERBOSE variable, or the PATCH_DEBUG variable if you are just interested in
+more details about the patch step.
+
+13.2. Program location
+
+Before outlining the process performed by the NetBSD package system in the next
+section, here's a brief discussion on where programs are installed, and which
+variables influence this.
+
+The automatic variable PREFIX indicates where all files of the final program
+shall be installed. It is usually set to LOCALBASE (/usr/pkg), or CROSSBASE for
+pkgs in the cross category. The value of PREFIX needs to be put into the
+various places in the program's source where paths to these files are encoded.
+See Section 12.3, "patches/*" and Section 21.3.1, "Shared libraries - libtool"
+for more details.
+
+When choosing which of these variables to use, follow the following rules:
+
+ * PREFIX always points to the location where the current pkg will be
+ installed. When referring to a pkg's own installation path, use "${PREFIX}"
+ .
+
+ * LOCALBASE is where all non-X11 pkgs are installed. If you need to construct
+ a -I or -L argument to the compiler to find includes and libraries
+ installed by another non-X11 pkg, use "${LOCALBASE}". The name LOCALBASE
+ stems from FreeBSD, which installed all packages in /usr/local. As pkgsrc
+ leaves /usr/local for the system administrator, this variable is a
+ misnomer.
+
+ * X11BASE is where the actual X11 distribution (from xsrc, etc.) is
+ installed. When looking for standard X11 includes (not those installed by a
+ package), use "${X11BASE}".
+
+ * X11-based packages using imake must set USE_IMAKE to be installed correctly
+ under LOCALBASE.
+
+ * Within ${PREFIX}, packages should install files according to hier(7), with
+ the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/
+ man.
+
+13.3. Directories used during the build process
+
+When building a package, various directories are used to store source files,
+temporary files, pkgsrc-internal files, and so on. These directories are
+explained here.
+
+Some of the directory variables contain relative pathnames. There are two
+common base directories for these relative directories: PKGSRCDIR/PKGPATH is
+used for directories that are pkgsrc-specific. WRKSRC is used for directories
+inside the package itself.
+
+PKGSRCDIR
+
+ This is an absolute pathname that points to the pkgsrc root directory.
+ Generally, you don't need it.
+
+PKGDIR
+
+ This is an absolute pathname that points to the current package.
+
+PKGPATH
+
+ This is a pathname relative to PKGSRCDIR that points to the current
+ package.
+
+WRKDIR
+
+ This is an absolute pathname pointing to the directory where all work takes
+ place. The distfiles are extracted to this directory. It also contains
+ temporary directories and log files used by the various pkgsrc frameworks,
+ like buildlink or the wrappers.
+
+WRKSRC
+
+ This is an absolute pathname pointing to the directory where the distfiles
+ are extracted. It is usually a direct subdirectory of WRKDIR, and often
+ it's the only directory entry that isn't hidden. This variable may be
+ changed by a package Makefile.
+
+The CREATE_WRKDIR_SYMLINK definition takes either the value yes or no and
+defaults to no. It indicates whether a symbolic link to the WRKDIR is to be
+created in the pkgsrc entry's directory. If users would like to have their
+pkgsrc trees behave in a read-only manner, then the value of
+CREATE_WRKDIR_SYMLINK should be set to no.
+
+13.4. Running a phase
+
+You can run a particular phase by typing make phase, where phase is the name of
+the phase. This will automatically run all phases that are required for this
+phase. The default phase is build, that is, when you run make without
+parameters in a package directory, the package will be built, but not
+installed.
+
+13.5. The fetch phase
+
+The first step in building a package is to fetch the distribution files
+(distfiles) from the sites that are providing them. This is the task of the
+fetch phase.
+
+13.5.1. What to fetch and where to get it from
+
+In simple cases, MASTER_SITES defines all URLs from where the distfile, whose
+name is derived from the DISTNAME variable, is fetched. The more complicated
+cases are described below.
+
+The variable DISTFILES specifies the list of distfiles that have to be fetched.
+Its value defaults to ${DEFAULT_DISTFILES} and its value is ${DISTNAME}$
+{EXTRACT_SUFX}, so that most packages don't need to define it at all.
+EXTRACT_SUFX is .tar.gz by default, but can be changed freely. Note that if
+your package requires additional distfiles to the default one, you cannot just
+append the additional filenames using the += operator, but you have write for
+example:
+
+DISTFILES= ${DEFAULT_DISTFILES} additional-files.tar.gz
+
+Each distfile is fetched from a list of sites, usually MASTER_SITES. If the
+package has multiple DISTFILES or multiple PATCHFILES from different sites, you
+can set SITES.distfile to the list of URLs where the file distfile (including
+the suffix) can be found.
+
+DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
+DISTFILES+= foo-file.tar.gz
+SITES.foo-file.tar.gz= \
+https://www.somewhere.com/somehow/ \
+https://www.somewhereelse.com/mirror/somehow/
+
+When actually fetching the distfiles, each item from MASTER_SITES or SITES.*
+gets the name of each distfile appended to it, without an intermediate slash.
+Therefore, all site values have to end with a slash or other separator
+character. This allows for example to set MASTER_SITES to a URL of a CGI script
+that gets the name of the distfile as a parameter. In this case, the definition
+would look like:
+
+MASTER_SITES= https://www.example.com/download.cgi?file=
+
+The exception to this rule are URLs starting with a dash. In that case the URL
+is taken as is, fetched and the result stored under the name of the distfile.
+You can use this style for the case when the download URL style does not match
+the above common case. For example, if permanent download URL is a redirector
+to the real download URL, or the download file name is offered by an HTTP
+Content-Disposition header. In the following example, foo-1.0.0.tar.gz will be
+created instead of the default v1.0.0.tar.gz.
+
+DISTNAME= foo-1.0.0
+MASTER_SITES= -https://www.example.com/archive/v1.0.0.tar.gz
+
+There are some predefined values for MASTER_SITES, which can be used in
+packages. The names of the variables should speak for themselves.
+
+MASTER_SITE_APACHE MASTER_SITE_BACKUP
+MASTER_SITE_CRATESIO MASTER_SITE_CYGWIN
+MASTER_SITE_DEBIAN MASTER_SITE_FREEBSD
+MASTER_SITE_FREEBSD_LOCAL MASTER_SITE_GENTOO
+MASTER_SITE_GITHUB MASTER_SITE_GNOME
+MASTER_SITE_GNU MASTER_SITE_GNUSTEP
+MASTER_SITE_HASKELL_HACKAGE MASTER_SITE_IFARCHIVE
+MASTER_SITE_KDE MASTER_SITE_MOZILLA
+MASTER_SITE_MOZILLA_ALL MASTER_SITE_MYSQL
+MASTER_SITE_NETLIB MASTER_SITE_OPENBSD
+MASTER_SITE_OPENOFFICE MASTER_SITE_OSDN
+MASTER_SITE_PERL_CPAN MASTER_SITE_PGSQL
+MASTER_SITE_PYPI MASTER_SITE_RUBYGEMS
+MASTER_SITE_R_CRAN MASTER_SITE_SOURCEFORGE
+MASTER_SITE_SUNSITE MASTER_SITE_SUSE
+MASTER_SITE_TEX_CTAN MASTER_SITE_XCONTRIB
+MASTER_SITE_XEMACS MASTER_SITE_XORG
+
+Some explanations for the less self-explaining ones: MASTER_SITE_BACKUP
+contains backup sites for packages that are maintained in ftp://ftp.NetBSD.org/
+pub/pkgsrc/distfiles/${DIST_SUBDIR}. MASTER_SITE_LOCAL contains local package
+source distributions that are maintained in ftp://ftp.NetBSD.org/pub/pkgsrc/
+distfiles/LOCAL_PORTS/.
+
+If you choose one of these predefined sites, you may want to specify a
+subdirectory of that site. Since these macros may expand to more than one
+actual site, you must use the following construct to specify a subdirectory:
+
+MASTER_SITES= ${MASTER_SITE_GNU:=subdirectory/name/}
+MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/}
+
+Note the trailing slash after the subdirectory name.
+
+13.5.2. How are the files fetched?
+
+The fetch phase makes sure that all the distfiles exist in a local directory
+(DISTDIR, which can be set by the pkgsrc user). If the files do not exist, they
+are fetched using commands of the form
+
+${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
+
+where ${site} varies through several possibilities in turn: first,
+MASTER_SITE_OVERRIDE is tried, then the sites specified in either SITES.file if
+defined, else MASTER_SITES or PATCH_SITES, as applies, then finally the value
+of MASTER_SITE_BACKUP. The order of all except the first and the last can be
+optionally sorted by the user, via setting either MASTER_SORT_RANDOM, and
+MASTER_SORT_AWK or MASTER_SORT_REGEX.
+
+The specific command and arguments used depend on the FETCH_USING parameter.
+The example above is for FETCH_USING=custom.
+
+The distfiles mirror run by the NetBSD Foundation uses the mirror-distfiles
+target to mirror the distfiles, if they are freely distributable. Packages
+setting NO_SRC_ON_FTP (usually to "${RESTRICTED}") will not have their
+distfiles mirrored.
+
+13.6. The checksum phase
+
+After the distfile(s) are fetched, their checksum is generated and compared
+with the checksums stored in the distinfo file. If the checksums don't match,
+the build is aborted. This is to ensure the same distfile is used for building,
+and that the distfile wasn't changed, e.g. by some malign force, deliberately
+changed distfiles on the master distribution site or network lossage.
-README*
+13.7. The extract phase
- These files do not take place in the creation of a package and thus are
- purely informative to the package developer.
+When the distfiles are present on the local system, they need to be extracted,
+as they usually come in the form of some compressed archive format.
-TODO
+By default, all DISTFILES are extracted. If you only need some of them, you can
+set the EXTRACT_ONLY variable to the list of those files.
- This file contains things that need to be done to make the package even
- better.
+Extracting the files is usually done by a little program, mk/extract/extract,
+which already knows how to extract various archive formats, so most likely you
+will not need to change anything here. But if you need, the following variables
+may help you:
-13.6. work*
+EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}
-When you type make, the distribution files are unpacked into the directory
-denoted by WRKDIR. It can be removed by running make clean. Besides the
-sources, this directory is also used to keep various timestamp files. The
-directory gets removed completely on clean. The default is ${.CURDIR}/work or $
-{.CURDIR}/work.${MACHINE_ARCH} if OBJMACHINE is set.
+ Use these variables to override the default options for an extract command,
+ which are defined in mk/extract/extract.
-13.7. files/*
+EXTRACT_USING
-If you have any files that you wish to be placed in the package prior to
-configuration or building, you can place these files here and use a ${CP}
-command in the "post-extract" target to achieve this.
+ This variable can be set to bsdtar, gtar, nbtar (which is the default
+ value), pax, or an absolute pathname pointing to the command with which tar
+ archives should be extracted. It is preferred to choose bsdtar over gtar if
+ NetBSD's pax-as-tar is not good enough.
-If you want to share files in this way with other packages, set the FILESDIR
-variable to point to the other package's files directory, e.g.:
+If the extract program doesn't serve your needs, you can also override the
+EXTRACT_CMD variable, which holds the command used for extracting the files.
+This command is executed in the ${WRKSRC} directory. During execution of this
+command, the shell variable extract_file holds the absolute pathname of the
+file that is going to be extracted.
-FILESDIR= ../../editors/xemacs/files
+And if that still does not suffice, you can override the do-extract target in
+the package Makefile.
-Chapter 14. Programming in Makefiles
+13.8. The patch phase
-Table of Contents
+After extraction, all the patches named by the PATCHFILES, those present in the
+patches subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
+/usr/local/patches/graphics/png) are applied. Patchfiles ending in .Z or .gz
+are uncompressed before they are applied, files ending in .orig or .rej are
+ignored. Any special options to patch(1) can be handed in PATCH_DIST_ARGS. See
+Section 12.3, "patches/*" for more details.
-14.1. Caveats
-14.2. Makefile variables
+By default patch(1) is given special arguments to make it fail if the expected
+text from the patch context is not found in the patched file. If that happens,
+fix the patch file by comparing it with the actual text in the file to be
+patched.
- 14.2.1. Naming conventions
+13.9. The tools phase
-14.3. Code snippets
+This is covered in Chapter 17, Tools needed for building or running.
- 14.3.1. Adding things to a list
- 14.3.2. Echoing a string exactly as-is
- 14.3.3. Passing CFLAGS to GNU configure scripts
- 14.3.4. Handling possibly empty variables
+13.10. The wrapper phase
-Pkgsrc consists of many Makefile fragments, each of which forms a well-defined
-part of the pkgsrc system. Using the make(1) system as a programming language
-for a big system like pkgsrc requires some discipline to keep the code correct
-and understandable.
+This phase creates wrapper programs for the compilers and linkers. The
+following variables can be used to tweak the wrappers.
-The basic ingredients for Makefile programming are variables and shell
-commands. Among these shell commands may even be more complex ones like awk(1)
-programs. To make sure that every shell command runs as intended it is
-necessary to quote all variables correctly when they are used.
+ECHO_WRAPPER_MSG
-This chapter describes some patterns that appear quite often in Makefiles,
-including the pitfalls that come along with them.
+ The command used to print progress messages. Does nothing by default. Set
+ to ${ECHO} to see the progress messages.
-14.1. Caveats
+WRAPPER_DEBUG
- * When you are creating a file as a target of a rule, always write the data
- to a temporary file first and finally rename that file. Otherwise there
- might occur an error in the middle of generating the file, and when the
- user runs make(1) for the second time, the file exists and will not be
- regenerated properly. Example:
+ This variable can be set to yes (default) or no, depending on whether you
+ want additional information in the wrapper log file.
- wrong:
- @echo "line 1" > ${.TARGET}
- @echo "line 2" >> ${.TARGET}
- @false
+WRAPPER_UPDATE_CACHE
- correct:
- @echo "line 1" > ${.TARGET}.tmp
- @echo "line 2" >> ${.TARGET}.tmp
- @false
- @mv ${.TARGET}.tmp ${.TARGET}
+ This variable can be set to yes or no, depending on whether the wrapper
+ should use its cache, which will improve the speed. The default value is
+ yes, but is forced to no if the platform does not support it.
- When you run make wrong twice, the file wrong will exist, although there
- was an error message in the first run. On the other hand, running make
- correct gives an error message twice, as expected.
+WRAPPER_REORDER_CMDS
- You might remember that make(1) sometimes removes ${.TARGET} in case of
- error, but this only happens when it is interrupted, for example by
- pressing Ctrl+C. This does not happen when one of the commands fails (like
- false(1) above).
+ A list of reordering commands. A reordering command has the form reorder:l:
+ lib1:lib2. It ensures that that -llib1 occurs before -llib2.
-14.2. Makefile variables
+13.11. The configure phase
-Makefile variables contain strings that can be processed using the five
-operators =, +=, ?=, := and !=, which are described in the make(1) man page.
+Most pieces of software need information on the header files, system calls, and
+library routines which are available on the platform they run on. The process
+of determining this information is known as configuration, and is usually
+automated. In most cases, a script is supplied with the distfiles, and its
+invocation results in generation of header files, Makefiles, etc.
-When a variable's value is parsed from a Makefile, the hash character # and the
-backslash character \ are handled specially. If a backslash is the last
-character in a line, that backslash is removed from the line and the line
-continues with the next line of the file.
+If the package contains a configure script, this can be invoked by setting
+HAS_CONFIGURE to "yes". If the configure script is a GNU autoconf script, you
+should set GNU_CONFIGURE to "yes" instead. What happens in the configure phase
+is roughly:
-The # character starts a comment that reaches until the end of the line. To get
-an actual # character, such as in a URL, write \# instead.
+.for d in ${CONFIGURE_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
+.endfor
-The evaluation of variables either happens immediately or lazy. It happens
-immediately when the variable occurs on the right-hand side of the := or the !=
-operator, in a .if condition or a .for loop. In the other cases, it is
-evaluated lazily.
+CONFIGURE_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In
+each of these directories, the configure script is run with the environment
+CONFIGURE_ENV and arguments CONFIGURE_ARGS. The variables CONFIGURE_ENV,
+CONFIGURE_SCRIPT (default: "./configure") and CONFIGURE_ARGS may all be changed
+by the package.
-Some of the modifiers split the string into words and then operate on the
-words, others operate on the string as a whole. When a string is split into
-words, double quotes and single quotes are interpreted as delimiters, just like
-in sh(1).
+If the program uses the Perl way of configuration (mainly Perl modules, but not
+only), i.e. a file called Makefile.PL, it should include ../../lang/perl5/
+module.mk. To set any parameter for Makefile.PL use the MAKE_PARAMS variable
+(e.g., MAKE_PARAMS+=foo=bar
-14.2.1. Naming conventions
+If the program uses an Imakefile for configuration, the appropriate steps can
+be invoked by setting USE_IMAKE to "yes". If you only need xmkmf, add it to
+USE_TOOLS. You can add variables to xmkmf's environment by adding them to the
+SCRIPTS_ENV variable.
- * All variable names starting with an underscore are reserved for use by the
- pkgsrc infrastructure. They shall not be used by packages.
+If the program uses cmake for configuration, the appropriate steps can be
+invoked by setting USE_CMAKE to "yes". You can add variables to cmake's
+environment by adding them to the CONFIGURE_ENV variable and arguments to cmake
+by adding them to the CMAKE_ARGS variable. The top directory argument is given
+by the CMAKE_ARG_PATH variable, that defaults to "." (relative to
+CONFIGURE_DIRS)
- * In .for loops you should use lowercase variable names for the iteration
- variables.
+If there is no configure step at all, set NO_CONFIGURE to "yes".
- * All list variables should have a plural name, such as PKG_OPTIONS or
- DISTFILES.
+13.12. The build phase
-14.3. Code snippets
+For building a package, a rough equivalent of the following code is executed.
-14.3.1. Adding things to a list
+.for d in ${BUILD_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${MAKE_ENV} \
+ ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
+ -f ${MAKE_FILE} \
+ ${BUILD_TARGET}
+.endfor
-When adding a string that possibly contains whitespace or quotes to a list
-(example 1), it must be quoted using the :Q modifier.
+BUILD_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In each of
+these directories, MAKE_PROGRAM is run with the environment MAKE_ENV and
+arguments BUILD_MAKE_FLAGS. The variables MAKE_ENV, BUILD_MAKE_FLAGS, MAKE_FILE
+and BUILD_TARGET may all be changed by the package.
-When adding another list to a list (example 2), it must not be quoted, since
-its elements are already quoted.
+The default value of MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake", "
+make" otherwise. The default value of MAKE_FILE is "Makefile", and BUILD_TARGET
+defaults to "all".
-STRING= foo * bar `date`
-LIST= # empty
-ANOTHER_LIST= a=b c=d
+If there is no build step at all, set NO_BUILD to "yes".
-LIST+= ${STRING:Q} # 1
-LIST+= ${ANOTHER_LIST} # 2
+13.13. The test phase
-14.3.2. Echoing a string exactly as-is
+[TODO]
-Echoing a string containing special characters needs special work.
+13.14. The install phase
-STRING= foo bar < > * `date` $$HOME ' "
-EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
+Once the build stage has completed, the final step is to install the software
+in public directories, so users can access the programs and files.
-all:
- echo ${STRING} # 1
- echo ${STRING:Q} # 2
- printf '%s\n' ${STRING:Q}'' # 3
- env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
+In the install phase, a rough equivalent of the following code is executed.
+Additionally, before and after this code, much magic is performed to do
+consistency checks, registering the package, and so on.
-Example 1 leads to a syntax error in the shell, as the characters are just
-copied.
+.for d in ${INSTALL_DIRS}
+ cd ${WRKSRC} \
+ && cd ${d} \
+ && env ${MAKE_ENV} \
+ ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
+ -f ${MAKE_FILE} \
+ ${INSTALL_TARGET}
+.endfor
-Example 2 quotes the string so that the shell interprets it correctly. But the
-echo command may additionally interpret strings with a leading dash or those
-containing backslashes.
+The variable's meanings are analogous to the ones in the build phase.
+INSTALL_DIRS defaults to BUILD_DIRS. INSTALL_TARGET is "install" by default,
+plus "install.man" if USE_IMAKE is defined and NO_INSTALL_MANPAGES is not
+defined.
-Example 3 can handle arbitrary strings, since printf(1) only interprets the
-format string, but not the next argument. The trailing single quotes handle the
-case when the string is empty. In that case, the :Q modifier would result in an
-empty string too, which would then be skipped by the shell. For printf(1) this
-doesn't make a difference, but other programs may care.
+In the install phase, the following variables are useful. They are all
+variations of the install(1) command that have the owner, group and permissions
+preset. INSTALL is the plain install command. The specialized variants,
+together with their intended use, are:
-In example 4, the EXAMPLE_ENV does not need to be quoted because the quoting
-has already been done when adding elements to the list.
+INSTALL_PROGRAM_DIR
-14.3.3. Passing CFLAGS to GNU configure scripts
+ directories that contain binaries
-When passing CFLAGS or similar variables to a GNU-style configure script
-(especially those that call other configure scripts), it must not have leading
-or trailing whitespace, since otherwise the configure script gets confused. To
-trim leading and trailing whitespace, use the :M modifier, as in the following
-example:
+INSTALL_SCRIPT_DIR
-CPPFLAGS= # empty
-CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
-CPPFLAGS+= ${MY_CPPFLAGS}
+ directories that contain scripts
-CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
+INSTALL_LIB_DIR
-all:
- echo x${CPPFLAGS:Q}x # leading and trailing whitespace
- echo x${CONFIGURE_ARGS:Q}x # properly trimmed
+ directories that contain shared and static libraries
-In this example, CPPFLAGS has both leading and trailing whitespace because the
-+= operator always adds a space.
+INSTALL_DATA_DIR
-14.3.4. Handling possibly empty variables
+ directories that contain data files
-When a possibly empty variable is used in a shell program, it may lead to a
-syntax error.
+INSTALL_MAN_DIR
-EGFILES= # empty
+ directories that contain man pages
-install-examples: # produces a syntax error in the shell
- for egfile in ${EGFILES}; do \
- echo "Installing $$egfile"; \
- done
+INSTALL_GAME_DIR
-The shell only sees the text for egfile in ; do, since ${EGFILES} is replaced
-with an empty string by make(1). To fix this syntax error, use one of the
-snippets below.
+ directories that contain data files for games
-EMPTY= # empty
+INSTALL_PROGRAM
-install-examples:
- for egfile in ${EGFILES} ""; do \
- [ -n "$$egfile" ] || continue; \
- echo "Installing $$egfile"; \
- done
+ binaries that can be stripped from debugging symbols
-In this case, an empty string is appended to the iteration list (to prevent the
-syntax error) and filtered out later.
+INSTALL_SCRIPT
-EGFILES= # empty
+ binaries that cannot be stripped
-install-examples:
-.for egfile in ${EGFILES}
- echo "Installing ${egfile}"
-.endfor
+INSTALL_GAME
-If one of the filenames contains special characters, it should be enclosed in
-single or double quotes.
+ game binaries
-To have a shell command test whether a make variable is empty, use the
-following code: ${TEST} -z ${POSSIBLY_EMPTY:Q}"".
+INSTALL_LIB
-Chapter 15. PLIST issues
+ shared and static libraries
-Table of Contents
+INSTALL_DATA
-15.1. RCS ID
-15.2. Semi-automatic PLIST generation
-15.3. Tweaking output of make print-PLIST
-15.4. Variable substitution in PLIST
-15.5. Man page compression
-15.6. Changing PLIST source with PLIST_SRC
-15.7. Platform-specific and differing PLISTs
-15.8. Build-specific PLISTs
-15.9. Sharing directories between packages
+ data files
-The PLIST file contains a package's "packing list", i.e. a list of files that
-belong to the package (relative to the ${PREFIX} directory it's been installed
-in) plus some additional statements - see the pkg_create(1) man page for a full
-list. This chapter addresses some issues that need attention when dealing with
-the PLIST file (or files, see below!).
+INSTALL_GAME_DATA
-15.1. RCS ID
+ data files for games
-Be sure to add a RCS ID line as the first thing in any PLIST file you write:
+INSTALL_MAN
-@comment $NetBSD $
+ man pages
-An artificial space has been added between NetBSD and $, this is a workaround
-here to prevent CVS expanding to the filename of the guide. When adding the RCS
-ID the space should be omitted.
+Some other variables are:
-15.2. Semi-automatic PLIST generation
+INSTALL_UNSTRIPPED
-You can use the make print-PLIST command to output a PLIST that matches any new
-files since the package was extracted. See Section 19.17, "Other helpful
-targets" for more information on this target.
+ If set to yes, do not run strip(1) when installing binaries. Any debugging
+ sections and symbols present in binaries will be preserved.
-15.3. Tweaking output of make print-PLIST
+INSTALLATION_DIRS
-The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that are
-used to filter the output of print-PLIST. You can append any chunk of AWK
-scripting you like to it, but be careful with quoting.
+ A list of directories relative to PREFIX that are created by pkgsrc at the
+ beginning of the install phase. The package is supposed to create all
+ needed directories itself before installing files to it and list all other
+ directories here.
-For example, to get all files inside the libdata/foo directory removed from the
-resulting PLIST:
+In the rare cases that a package shouldn't install anything, set NO_INSTALL to
+"yes". This is mostly relevant for packages in the regress category.
-PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
+13.15. The package phase
-The PRINT_PLIST_AWK transformations are evaluated after the file list and
-directory list are sorted. EARLY_PRINT_PLIST_AWK is like PRINT_PLIST_AWK except
-it operates before the file list and directory list are sorted.
+Once the install stage has completed, a binary package of the installed files
+can be built. These binary packages can be used for quick installation without
+previous compilation, e.g. by the make bin-install or by using pkg_add.
-15.4. Variable substitution in PLIST
+By default, the binary packages are created in ${PACKAGES}/All and symlinks are
+created in ${PACKAGES}/category, one for each category in the CATEGORIES
+variable. PACKAGES defaults to pkgsrc/packages.
-A number of variables are substituted automatically in PLISTs when a package is
-installed on a system. This includes the following variables:
+13.16. Cleaning up
-${MACHINE_ARCH}, ${MACHINE_GNU_ARCH}
+Once you're finished with a package, you can clean the work directory by
+running make clean. If you want to clean the work directories of all
+dependencies too, use make clean-depends.
- Some packages like emacs and perl embed information about which
- architecture they were built on into the pathnames where they install their
- files. To handle this case, PLIST will be preprocessed before actually
- used, and the symbol "${MACHINE_ARCH}" will be replaced by what uname -p
- gives. The same is done if the string ${MACHINE_GNU_ARCH} is embedded in
- PLIST somewhere - use this on packages that have GNU autoconf-created
- configure scripts.
+13.17. Other helpful targets
- Legacy note
+pre/post-*
- There used to be a symbol "$ARCH" that was replaced by the output of uname
- -m, but that's no longer supported and has been removed.
+ For any of the main targets described in the previous section (configure,
+ build, install, etc.), two auxiliary targets exist with "pre-" and "post-"
+ used as a prefix for the main target's name. These targets are invoked
+ before and after the main target is called, allowing extra configuration or
+ installation steps be performed from a package's Makefile, for example,
+ which a program's configure script or install target omitted.
+
+ About 5% of the pkgsrc packages define their custom post-extract target,
+ another 5% define pre-configure, and 10% define post-install. The other pre
+ /post-* targets are defined even less often.
-${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION}
+do-*
- Some packages want to embed the OS name and version into some paths. To do
- this, use these variables in the PLIST:
+ Should one of the main targets do the wrong thing, and should there be no
+ variable to fix this, you can redefine it with the do-* target. (Note that
+ redefining the target itself instead of the do-* target is a bad idea, as
+ the pre-* and post-* targets won't be called anymore, etc.)
- + ${OPSYS} - output of "uname -s"
+ About 15% of the pkgsrc packages override the default do-install, the other
+ do-* targets are overridden even less often.
- + ${LOWER_OPSYS} - lowercase common name (eg. "solaris")
+reinstall
- + ${OS_VERSION} - "uname -r"
+ If you did a make install and you noticed some file was not installed
+ properly, you can repeat the installation with this target, which will
+ ignore the "already installed" flag.
-For a list of values which are replaced by default, the output of make help
-topic=PLIST_SUBST as well as searching the pkgsrc/mk directory with grep for
-PLIST_SUBST should help.
+ This is the default value of DEPENDS_TARGET except in the case of make
+ update and make package, where the defaults are "package" and "update",
+ respectively.
-If you want to change other variables not listed above, you can add variables
-and their expansions to this variable in the following way, similar to
-MESSAGE_SUBST (see Section 13.5, "Optional files"):
+deinstall
-PLIST_SUBST+= SOMEVAR="somevalue"
+ This target does a pkg_delete(1) in the current directory, effectively
+ de-installing the package. The following variables can be used to tune the
+ behaviour:
-This replaces all occurrences of "${SOMEVAR}" in the PLIST with "somevalue".
+ PKG_VERBOSE
-The PLIST_VARS variable can be used to simplify the common case of
-conditionally including some PLIST entries. It can be done by adding
-PLIST_VARS+=foo and setting the corresponding PLIST.foo variable to yes if the
-entry should be included. This will substitute "${PLIST.foo}" in the PLIST with
-either """" or ""@comment "". For example, in Makefile:
+ Add a "-v" to the pkg_delete(1) command.
-PLIST_VARS+= foo
-.if condition
-PLIST.foo= yes
-.else
+ DEINSTALLDEPENDS
-And then in PLIST:
+ Remove all packages that require (depend on) the given package. This
+ can be used to remove any packages that may have been pulled in by a
+ given package, e.g. if make deinstall DEINSTALLDEPENDS=1 is done in
+ pkgsrc/x11/kde, this is likely to remove whole KDE. Works by adding "-R
+ " to the pkg_delete(1) command line.
-@comment $NetBSD $
-bin/bar
-man/man1/bar.1
-${PLIST.foo}bin/foo
-${PLIST.foo}man/man1/foo.1
-${PLIST.foo}share/bar/foo.data
+bin-install
-An artificial space has been added between NetBSD and $, this is a workaround
-here to prevent CVS expanding to the filename of the guide. When adding the RCS
-ID the space should be ommited.
+ Install a binary package from local disk and via FTP from a list of sites
+ (see the BINPKG_SITES variable), and do a make package if no binary package
+ is available anywhere. The arguments given to pkg_add can be set via
+ BIN_INSTALL_FLAGS e.g., to do verbose operation, etc.
-15.5. Man page compression
+install-clean
-Man pages should be installed in compressed form if MANZ is set (in
-bsd.own.mk), and uncompressed otherwise. To handle this in the PLIST file, the
-suffix ".gz" is appended/removed automatically for man pages according to MANZ
-and MANCOMPRESSED being set or not, see above for details. This modification of
-the PLIST file is done on a copy of it, not PLIST itself.
+ This target removes the state files for the "install" and later phases so
+ that the "install" target may be re-invoked. This can be used after editing
+ the PLIST to install the package without rebuilding it.
-15.6. Changing PLIST source with PLIST_SRC
+build-clean
-To use one or more files as source for the PLIST used in generating the binary
-package, set the variable PLIST_SRC to the names of that file(s). The files are
-later concatenated using cat(1), and the order of things is important. The
-default for PLIST_SRC is ${PKGDIR}/PLIST.
+ This target removes the state files for the "build" and later phases so
+ that the "build" target may be re-invoked.
-15.7. Platform-specific and differing PLISTs
+update
-Some packages decide to install a different set of files based on the operating
-system being used. These differences can be automatically handled by using the
-following files:
+ This target causes the current package to be updated to the latest version.
+ The package and all depending packages first get de-installed, then current
+ versions of the corresponding packages get compiled and installed. This is
+ similar to manually noting which packages are currently installed, then
+ performing a series of make deinstall and make install (or whatever
+ UPDATE_TARGET is set to) for these packages.
- * PLIST.common
+ You can use the "update" target to resume package updating in case a
+ previous make update was interrupted for some reason. However, in this
+ case, make sure you don't call make clean or otherwise remove the list of
+ dependent packages in WRKDIR. Otherwise, you lose the ability to
+ automatically update the current package along with the dependent packages
+ you have installed.
- * PLIST.${OPSYS}
+ Resuming an interrupted make update will only work as long as the package
+ tree remains unchanged. If the source code for one of the packages to be
+ updated has been changed, resuming make update will most certainly fail!
- * PLIST.${MACHINE_ARCH}
+ The following variables can be used either on the command line or in
+ mk.conf to alter the behaviour of make update:
- * PLIST.${OPSYS}-${MACHINE_ARCH}
+ UPDATE_TARGET
- * PLIST.common_end
+ Install target to recursively use for the updated package and the
+ dependent packages. Defaults to DEPENDS_TARGET if set, "install"
+ otherwise for make update. Other good targets are "package" or "
+ bin-install". Do not set this to "update" or you will get stuck in an
+ endless loop!
-15.8. Build-specific PLISTs
+ NOCLEAN
-Some packages decide to generate hard-to-guess file names during installation
-that are hard to wire down.
+ Don't clean up after updating. Useful if you want to leave the work
+ sources of the updated packages around for inspection or other
+ purposes. Be sure you eventually clean up the source tree (see the "
+ clean-update" target below) or you may run into troubles with old
+ source code still lying around on your next make or make update.
-In such cases, you can set the GENERATE_PLIST variable to shell code terminated
-(with a semicolon) that will output PLIST entries which will be appended to the
-PLIST
+ REINSTALL
-You can find one example in editors/xemacs:
+ Deinstall each package before installing (making DEPENDS_TARGET). This
+ may be necessary if the "clean-update" target (see below) was called
+ after interrupting a running make update.
-GENERATE_PLIST+= ${ECHO} bin/${DISTNAME}-`${WRKSRC}/src/xemacs -sd`.dmp ;
+ DEPENDS_TARGET
-which will append something like bin/xemacs-21.4.23-54e8ea71.dmp to the PLIST.
+ Allows you to disable recursion and hardcode the target for packages.
+ The default is "update" for the update target, facilitating a recursive
+ update of prerequisite packages. Only set DEPENDS_TARGET if you want to
+ disable recursive updates. Use UPDATE_TARGET instead to just set a
+ specific target for each package to be installed during make update
+ (see above).
-15.9. Sharing directories between packages
+clean-update
-A "shared directory" is a directory where multiple (and unrelated) packages
-install files. These directories were problematic because you had to add
-special tricks in the PLIST to conditionally remove them, or have some
-centralized package handle them.
+ Clean the source tree for all packages that would get updated if make
+ update was called from the current directory. This target should not be
+ used if the current package (or any of its depending packages) have already
+ been de-installed (e.g., after calling make update) or you may lose some
+ packages you intended to update. As a rule of thumb: only use this target
+ before the first time you run make update and only if you have a dirty
+ package tree (e.g., if you used NOCLEAN).
-In pkgsrc, it is now easy: Each package should create directories and install
-files as needed; pkg_delete will remove any directories left empty after
-uninstalling a package.
+ If you are unsure about whether your tree is clean, you can either perform
+ a make clean at the top of the tree, or use the following sequence of
+ commands from the directory of the package you want to update (before
+ running make update for the first time, otherwise you lose all the packages
+ you wanted to update!):
-If a package needs an empty directory to work, create the directory during
-installation as usual, and also add an entry to the PLIST:
+ # make clean-update
+ # make clean CLEANDEPENDS=YES
+ # make update
-@pkgdir path/to/empty/directory
-or take a look at MAKE_DIRS and OWN_DIRS.
+ The following variables can be used either on the command line or in
+ mk.conf to alter the behaviour of make clean-update:
+
+ CLEAR_DIRLIST
+
+ After make clean, do not reconstruct the list of directories to update
+ for this package. Only use this if make update successfully installed
+ all packages you wanted to update. Normally, this is done automatically
+ on make update, but may have been suppressed by the NOCLEAN variable
+ (see above).
-Chapter 16. Buildlink methodology
+replace
-Table of Contents
+ Update the installation of the current package. This differs from update in
+ that it does not replace dependent packages. You will need to install
+ pkgtools/pkg_tarup for this target to work.
-16.1. Converting packages to use buildlink3
-16.2. Writing buildlink3.mk files
+ Be careful when using this target! There are no guarantees that dependent
+ packages will still work, in particular they will most certainly break if
+ you make replace a library package whose shared library major version
+ changed between your installed version and the new one. For this reason,
+ this target is not officially supported and only recommended for advanced
+ users.
- 16.2.1. Anatomy of a buildlink3.mk file
- 16.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
- buildlink3.mk files
+info
-16.3. Writing builtin.mk files
+ This target invokes pkg_info(1) for the current package. You can use this
+ to check which version of a package is installed.
- 16.3.1. Anatomy of a builtin.mk file
- 16.3.2. Global preferences for native or pkgsrc software
+index
-Buildlink is a framework in pkgsrc that controls what headers and libraries are
-seen by a package's configure and build processes. This is implemented in a two
-step process:
+ This is a top-level command, i.e. it should be used in the pkgsrc
+ directory. It creates a database of all packages in the local pkgsrc tree,
+ including dependencies, comment, maintainer, and some other useful
+ information. Individual entries are created by running make describe in the
+ packages' directories. This index file is saved as pkgsrc/INDEX. It can be
+ displayed in verbose format by running make print-index. You can search in
+ it with make search key=something. You can extract a list of all packages
+ that depend on a particular one by running make show-deps PKG=somepackage.
- 1. Symlink headers and libraries for dependencies into BUILDLINK_DIR, which by
- default is a subdirectory of WRKDIR.
+ Running this command takes a very long time, some hours even on fast
+ machines!
- 2. Create wrapper scripts that are used in place of the normal compiler tools
- that translate -I${LOCALBASE}/include and -L${LOCALBASE}/lib into
- references to BUILDLINK_DIR. The wrapper scripts also make native compiler
- on some operating systems look like GCC, so that packages that expect GCC
- won't require modifications to build with those native compilers.
+readme
-This normalizes the environment in which a package is built so that the package
-may be built consistently despite what other software may be installed. Please
-note that the normal system header and library paths, e.g. /usr/include, /usr/
-lib, etc., are always searched -- buildlink3 is designed to insulate the
-package build from non-system-supplied software.
+ This target generates a README.html file, which can be viewed using a
+ browser such as www/firefox or www/links. The generated files contain
+ references to any packages which are in the PACKAGES directory on the local
+ host. The generated files can be made to refer to URLs based on
+ FTP_PKG_URL_HOST and FTP_PKG_URL_DIR. For example, if I wanted to generate
+ README.html files which pointed to binary packages on the local machine, in
+ the directory /usr/packages, set FTP_PKG_URL_HOST=file://localhost and
+ FTP_PKG_URL_DIR=/usr/packages. The ${PACKAGES} directory and its
+ subdirectories will be searched for all the binary packages.
-16.1. Converting packages to use buildlink3
+ The target can be run at the toplevel or in category directories, in which
+ case it descends recursively.
-The process of converting packages to use the buildlink3 framework ("bl3ifying"
-) is fairly straightforward. The things to keep in mind are:
+readme-all
- 1. Ensure that the build always calls the wrapper scripts instead of the
- actual toolchain. Some packages are tricky, and the only way to know for
- sure is the check ${WRKDIR}/.work.log to see if the wrappers are being
- invoked.
+ This is a top-level command, run it in pkgsrc. Use this target to create a
+ file README-all.html which contains a list of all packages currently
+ available in the NetBSD Packages Collection, together with the category
+ they belong to and a short description. This file is compiled from the
+ pkgsrc/*/README.html files, so be sure to run this after a make readme.
- 2. Don't override PREFIX from within the package Makefile, e.g. Java VMs,
- standalone shells, etc., because the code to symlink files into $
- {BUILDLINK_DIR} looks for files relative to "pkg_info -qp pkgname".
+cdrom-readme
- 3. Remember that only the buildlink3.mk files that you list in a package's
- Makefile are added as dependencies for that package.
+ This is very much the same as the "readme" target (see above), but is to be
+ used when generating a pkgsrc tree to be written to a CD-ROM. This target
+ also produces README.html files, and can be made to refer to URLs based on
+ CDROM_PKG_URL_HOST and CDROM_PKG_URL_DIR.
-If a dependency on a particular package is required for its libraries and
-headers, then we replace:
+show-distfiles
-DEPENDS+= foo>=1.1.0:../../category/foo
+ This target shows which distfiles and patchfiles are needed to build the
+ package (ALLFILES, which contains all DISTFILES and PATCHFILES, but not
+ patches/*).
-with
+show-downlevel
-.include "../../category/foo/buildlink3.mk"
+ This target shows nothing if the package is not installed. If a version of
+ this package is installed, but is not the version provided in this version
+ of pkgsrc, then a warning message is displayed. This target can be used to
+ show which of your installed packages are downlevel, and so the old
+ versions can be deleted, and the current ones added.
-The buildlink3.mk files usually define the required dependencies. If you need a
-newer version of the dependency when using buildlink3.mk files, then you can
-define it in your Makefile; for example:
+show-pkgsrc-dir
-BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0
-.include "../../category/foo/buildlink3.mk"
+ This target shows the directory in the pkgsrc hierarchy from which the
+ package can be built and installed. This may not be the same directory as
+ the one from which the package was installed. This target is intended to be
+ used by people who may wish to upgrade many packages on a single host, and
+ can be invoked from the top-level pkgsrc Makefile by using the "
+ show-host-specific-pkgs" target.
-There are several buildlink3.mk files in pkgsrc/mk that handle special package
-issues:
+show-installed-depends
- * bdb.buildlink3.mk chooses either the native or a pkgsrc Berkeley DB
- implementation based on the values of BDB_ACCEPTED and BDB_DEFAULT.
+ This target shows which installed packages match the current package's
+ DEPENDS. Useful if out of date dependencies are causing build problems.
- * curses.buildlink3.mk: If the system comes with neither Curses nor NCurses,
- this will take care to install the devel/ncurses package.
+print-build-depends-list
- * krb5.buildlink3.mk uses the value of KRB5_ACCEPTED to choose between adding
- a dependency on Heimdal or MIT-krb5 for packages that require a Kerberos 5
- implementation.
+ This target shows the list of packages that the current package depends on
+ for building.
- * motif.buildlink3.mk checks for a system-provided Motif installation or adds
- a dependency on x11/lesstif or x11/motif. The user can set MOTIF_TYPE to "
- dt", "lesstif" or "motif" to choose which Motif version will be used.
+print-run-depends-list
- * readline.buildlink3.mk checks for a system-provided GNU readline or
- editline (libedit) installation, or adds a dependency on devel/readline,
- devel/editline. The user can set READLINE_DEFAULT to choose readline
- implementation. If your package really needs GNU readline library, its
- Makefile should include devel/readline/buildlink3.mk instead of
- readline.buildlink3.mk.
+ This target shows the list of packages that the current package depends on
+ for running.
- * oss.buildlink3.mk defines several variables that may be used by packages
- that use the Open Sound System (OSS) API.
+check-shlibs
- * pgsql.buildlink3.mk will accept any of the Postgres versions in the
- variable PGSQL_VERSIONS_ACCEPTED and default to the version
- PGSQL_VERSION_DEFAULT. See the file for more information.
+ After a package is installed, check all its binaries and (on ELF platforms)
+ shared libraries to see if they find the shared libs they need. Run by
+ default if PKG_DEVELOPER is set in mk.conf.
- * pthread.buildlink3.mk uses the value of PTHREAD_OPTS and checks for native
- pthreads or adds a dependency on devel/pth as needed.
+print-PLIST
- * xaw.buildlink3.mk uses the value of XAW_TYPE to choose a particular Athena
- widgets library.
+ After a "make install" from a new or upgraded pkg, this prints out an
+ attempt to generate a new PLIST from a find -newer work/.extract_done. An
+ attempt is made to care for shared libs etc., but it is strongly
+ recommended to review the result before putting it into PLIST. On upgrades,
+ it's useful to diff the output of this command against an already existing
+ PLIST file.
-The comments in those buildlink3.mk files provide a more complete description
-of how to use them properly.
+ If the package installs files via tar(1) or other methods that don't update
+ file access times, be sure to add these files manually to your PLIST, as
+ the "find -newer" command used by this target won't catch them!
-16.2. Writing buildlink3.mk files
+ See Section 19.3, "Tweaking output of make print-PLIST" for more
+ information on this target.
-A package's buildlink3.mk file is included by Makefiles to indicate the need to
-compile and link against header files and libraries provided by the package. A
-buildlink3.mk file should always provide enough information to add the correct
-type of dependency relationship and include any other buildlink3.mk files that
-it needs to find headers and libraries that it needs in turn.
+Chapter 14. Creating a new pkgsrc package from scratch
-To generate an initial buildlink3.mk file for further editing, Rene Hexel's
-pkgtools/createbuildlink package is highly recommended. For most packages, the
-following command will generate a good starting point for buildlink3.mk files:
+Table of Contents
-% cd pkgsrc/category/pkgdir
-% createbuildlink >buildlink3.mk
+14.1. Common types of packages
+ 14.1.1. Perl modules
+ 14.1.2. Python modules and programs
+ 14.1.3. R packages
+ 14.1.4. TeXlive packages
-16.2.1. Anatomy of a buildlink3.mk file
+14.2. Examples
-The following real-life example buildlink3.mk is taken from pkgsrc/graphics/
-tiff:
+ 14.2.1. How the www/nvu package came into pkgsrc
-# $NetBSD: buildlink3.mk,v 1.16 2009/03/20 19:24:45 joerg Exp $
+When you find a package that is not yet in pkgsrc, you most likely have a URL
+from where you can download the source code. Starting with this URL, creating a
+package involves only a few steps.
-BUILDLINK_TREE+= tiff
+ 1. In your mk.conf, set PKG_DEVELOPER=yes to enable the basic quality checks.
-.if !defined(TIFF_BUILDLINK3_MK)
-TIFF_BUILDLINK3_MK:=
+ 2. Install the package meta-pkgs/pkg_developer, which among others will
+ install the utilities url2pkg, pkglint, pkgvi and mkpatches:
-BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1
-BUILDLINK_ABI_DEPENDS.tiff+= tiff>=3.7.2nb1
-BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
+ $ cd /usr/pkgsrc
+ $ (cd meta-pkgs/pkg_developer && bmake update)
-.include "../../devel/zlib/buildlink3.mk"
-.include "../../graphics/jpeg/buildlink3.mk"
-.endif # TIFF_BUILDLINK3_MK
+ 3. Choose one of the top-level directories as the category in which you want
+ to place your package. You can also create a directory of your own (maybe
+ called local). In that category directory, create another directory for
+ your package and change into it:
-BUILDLINK_TREE+= -tiff
+ $ mkdir category/package
+ $ cd category/package
-The header and footer manipulate BUILDLINK_TREE, which is common across all
-buildlink3.mk files and is used to track the dependency tree.
+ 4. Run the program url2pkg, which will ask you for a URL. Enter the URL of the
+ distribution file (in most cases a .tar.gz file) and watch how the basic
+ ingredients of your package are created automatically. The distribution
+ file is extracted automatically to fill in some details in the Makefile
+ that would otherwise have to be done manually:
-The main section is protected from multiple inclusion and controls how the
-dependency on pkg is added. Several important variables are set in the section:
+ $ url2pkg https://www.example.org/packages/package-1.0.tar.gz
- * BUILDLINK_API_DEPENDS.pkg is the dependency version recorded in the
- installed package; this should always be set using += to ensure that we're
- appending to any pre-existing list of values. This variable should be set
- to the last version of the package that had an backwards-incompatible API
- change.
+ 5. Examine the extracted files to determine the dependencies of your package.
+ Ideally, this is mentioned in some README file, but things may differ. For
+ each of these dependencies, look where it exists in pkgsrc, and if there is
+ a file called buildlink3.mk in that directory, add a line to your package
+ Makefile which includes that file just before the last line. If the
+ buildlink3.mk file does not exist, it must be created first. The
+ buildlink3.mk file makes sure that the package's include files and
+ libraries are provided.
- * BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory.
+ If you just need binaries from a package, add a DEPENDS line to the
+ Makefile, which specifies the version of the dependency and where it can be
+ found in pkgsrc. This line should be placed in the third paragraph. If the
+ dependency is only needed for building the package, but not when using it,
+ use TOOL_DEPENDS or BUILD_DEPENDS instead of DEPENDS. The difference
+ between TOOL_DEPENDS and BUILD_DEPENDS occurs when cross-compiling:
+ TOOL_DEPENDS are native packages, i.e. packages for the architecture where
+ the package is built; BUILD_DEPENDS are target packages, i.e. packages for
+ the architecture for which the package is built. There is also
+ TEST_DEPENDS, which is used to specify a dependency used only for testing
+ the resulting package built, using the upstream project's included test
+ suite. Your package may then look like this:
- * BUILDLINK_DEPMETHOD.pkg (not shown above) controls whether we use
- BUILD_DEPENDS or DEPENDS to add the dependency on pkg. The build dependency
- is selected by setting BUILDLINK_DEPMETHOD.pkg to "build". By default, the
- full dependency is used.
+ [...]
- * BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS.pkg (not shown above) are lists
- of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and
- library search paths. These default to "include" and "lib" respectively.
+ TOOL_DEPENDS+= libxslt-[0-9]*:../../textproc/libxslt
+ DEPENDS+= screen-[0-9]*:../../misc/screen
+ DEPENDS+= screen>=4.0:../../misc/screen
- * BUILDLINK_CPPFLAGS.pkg (not shown above) is the list of preprocessor flags
- to add to CPPFLAGS, which are passed on to the configure and build phases.
- The "-I" option should be avoided and instead be handled using
- BUILDLINK_INCDIRS.pkg as above.
+ [...]
-The following variables are all optionally defined within this second section
-(protected against multiple inclusion) and control which package files are
-symlinked into ${BUILDLINK_DIR} and how their names are transformed during the
-symlinking:
+ .include "../../category/package/buildlink3.mk"
+ .include "../../devel/glib2/buildlink3.mk"
+ .include "../../mk/bsd.pkg.mk"
- * BUILDLINK_FILES.pkg (not shown above) is a shell glob pattern relative to $
- {BUILDLINK_PREFIX.pkg} to be symlinked into ${BUILDLINK_DIR}, e.g. include/
- *.h.
+ 6. Run pkglint to see what things still need to be done to make your package a
+ "good" one. If you don't know what pkglint's warnings want to tell you, try
+ pkglint --explain or pkglint -e, which outputs additional explanations.
- * BUILDLINK_FILES_CMD.pkg (not shown above) is a shell pipeline that outputs
- to stdout a list of files relative to ${BUILDLINK_PREFIX.pkg}. The
- resulting files are to be symlinked into ${BUILDLINK_DIR}. By default, this
- takes the +CONTENTS of a pkg and filters it through $
- {BUILDLINK_CONTENTS_FILTER.pkg}.
+ 7. In many cases the package is not yet ready to build. You can find
+ instructions for the most common cases in the next section, Section 14.1,
+ "Common types of packages". After you have followed the instructions over
+ there, you can hopefully continue here.
- * BUILDLINK_CONTENTS_FILTER.pkg (not shown above) is a filter command that
- filters +CONTENTS input into a list of files relative to $
- {BUILDLINK_PREFIX.pkg} on stdout. By default, BUILDLINK_CONTENTS_FILTER.pkg
- outputs the contents of the include and lib directories in the package
- +CONTENTS.
+ 8. Run bmake clean to clean the working directory from the extracted files.
+ Besides these files, a lot of cache files and other system information has
+ been saved in the working directory, which may become wrong after you
+ edited the Makefile.
- * BUILDLINK_FNAME_TRANSFORM.pkg (not shown above) is a list of sed arguments
- used to transform the name of the source filename into a destination
- filename, e.g. -e "s|/curses.h|/ncurses.h|g".
+ 9. Now, run bmake to build the package. For the various things that can go
+ wrong in this phase, consult Chapter 21, Making your package work.
-This section can additionally include any buildlink3.mk needed for pkg's
-library dependencies. Including these buildlink3.mk files means that the
-headers and libraries for these dependencies are also symlinked into $
-{BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included. Dependencies
-are only added for directly include buildlink3.mk files.
+ If the extracted files from the package need to be fixed, run multiple
+ rounds of these commands:
-When providing a buildlink3.mk and including other buildlink3.mk files in it,
-please only add necessary ones, i.e., those whose libraries or header files are
-automatically exposed when the package is use.
+ $ make
+ $ pkgvi ${WRKSRC}/some/file/that/does/not/compile
+ $ mkpatches
+ $ make mps
+ $ make clean
-In particular, if only an executable (bin/foo) is linked against a library,
-that library does not need to be propagated in the buildlink3.mk file.
+10. When the package builds fine, the next step is to install the package. Run
+ bmake install and hope that everything works.
-The following steps should help you decide if a buildlink3.mk file needs to be
-included:
+11. Up to now, the file PLIST, which contains a list of the files that are
+ installed by the package, is nearly empty. Run bmake print-PLIST >PLIST to
+ generate a probably correct list. Check the file using your preferred text
+ editor to see if the list of files looks plausible.
- * Look at the installed header files: What headers do they include? The
- packages providing these files must be buildlinked.
+12. Run pkglint again to see if the generated PLIST contains garbage or not.
- * Run ldd on all installed libraries and look against what other libraries
- they link. Some of the packages providing these probably need to be
- buildlinked; however, it's not automatic, since e.g. GTK on some systems
- pulls in the X libraries, so they will show up in the ldd output, while on
- others (like OS X) it won't. ldd output can thus only be used as a hint.
+13. When you ran bmake install, the package had been registered in the database
+ of installed files, but with an empty list of files. To fix this, run bmake
+ deinstall and bmake install again. Now the package is registered with the
+ list of files from PLIST.
-16.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
-buildlink3.mk files
+14. Run bmake package to create a binary package from the set of installed
+ files.
-Both variables set lower bounds for a version of this package. The two
-variables differ in that one describes source compatibility (API) and the other
-binary compatibility (ABI). The difference is that a change in the API breaks
-compilation of programs while changes in the ABI stop compiled programs from
-running.
-
-The BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk should be changed
-very rarely. (One possible scenario: If all packages using this package need a
-higher version than defined in the buildlink3.mk, BUILDLINK_API_DEPENDS.pkg
-could be updated to that higher version.)
-
-On the other hand, changes to BUILDLINK_ABI_DEPENDS.pkg are more common. The
-variable will need to be updated every time the major version of one of its
-shared libraries is changed, or any other change where a binary built against
-the previous version of the package will not run against the new version any
-longer.
-
-In such a case, the package's BUILDLINK_ABI_DEPENDS.pkg must be increased to
-require the new package version. Then the PKGREVISION of all packages that
-depend on this package need to be increased, and if they have buildlink3.mk
-files, their BUILDLINK_ABI_DEPENDS.pkg must be increased to the new version as
-well. This is required so that a package will pull in the versions of the
-packages that use the new ABI and that the packages' PKGREVISIONs uniquely
-identify the packages built against the new ABI. The pkgtools/revbump package
-can help with these updates.
+15. Run bmake clean update to run everything from above again in a single step,
+ making sure that the PLIST is correct and the whole package is created as
+ intended.
-See Section 21.1.5, "Handling dependencies" for more information about
-dependencies on other packages, including the BUILDLINK_API_DEPENDS
-definitions.
+16. Run pkglint to see if there's anything left to do.
-Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or
-BUILDLINK_ABI_DEPENDS.pkg in a buildlink3.mk file as we don't want to cause
-unneeded package deletions and rebuilds. In many cases, new versions of
-packages work just fine with older dependencies.
+17. Commit the package to pkgsrc-wip or main pkgsrc; see Chapter 23, Submitting
+ and Committing.
-Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to
-BUILDLINK_API_DEPENDS.pkg.
+14.1. Common types of packages
-16.3. Writing builtin.mk files
+14.1.1. Perl modules
-Some packages in pkgsrc install headers and libraries that coincide with
-headers and libraries present in the base system. Aside from a buildlink3.mk
-file, these packages should also include a builtin.mk file that includes the
-necessary checks to decide whether using the built-in software or the pkgsrc
-software is appropriate.
+Simple Perl modules are handled automatically by url2pkg, including
+dependencies.
-The only requirements of a builtin.mk file for pkg are:
+14.1.2. Python modules and programs
- 1. It should set USE_BUILTIN.pkg to either "yes" or "no" after it is included.
+Python modules and programs packages are easily created using a set of
+predefined variables.
- 2. It should not override any USE_BUILTIN.pkg which is already set before the
- builtin.mk file is included.
+If some Python versions are not supported by the software, set the
+PYTHON_VERSIONS_INCOMPATIBLE variable to the Python versions that are not
+supported, e.g.
- 3. It should be written to allow multiple inclusion. This is very important
- and takes careful attention to Makefile coding.
+PYTHON_VERSIONS_INCOMPATIBLE= 27
-16.3.1. Anatomy of a builtin.mk file
+If the packaged software is a Python module, include one of ../../lang/python/
+egg.mk, ../../lang/python/distutils.mk, or ../../lang/python/extension.mk.
-The following is the recommended template for builtin.mk files:
+Most Python packages use either "distutils" or easy-setup/setuptools ("eggs").
+If the packaged software is using setuptools, you only need to include "../../
+lang/python/egg.mk". Otherwise, if the software uses "distutils", include "..
+/../lang/python/distutils.mk", so pkgsrc will use this framework. "distutils"
+uses a script called setup.py; if the "distutils" driver is not called
+setup.py, set the PYSETUP variable to the name of the script.
-.if !defined(IS_BUILTIN.foo)
-#
-# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
-# genuinely exists in the system or not.
-#
-IS_BUILTIN.foo?= no
+Either way, the package directory should be called "py-software" and PKGNAME
+should be set to "${PYPKGPREFIX}-${DISTNAME}", e.g.
-# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
-# version can be determined.
-#
-. if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
-BUILTIN_PKG.foo?= foo-1.0
-. endif
-.endif # IS_BUILTIN.foo
+DISTNAME= foopymodule-1.2.10
+PKGNAME= ${PYPKGPREFIX}-${DISTNAME}
-.if !defined(USE_BUILTIN.foo)
-USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
-. if defined(BUILTIN_PKG.foo)
-. for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
-. if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
-USE_BUILTIN.foo!= \
- ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo} \
- && ${ECHO} "yes" || ${ECHO} "no"
-. endif
-. endfor
-. endif
-.endif # USE_BUILTIN.foo
+If it is an application, include "../../lang/python/application.mk". In order
+to correctly set the path to the Python interpreter, use the REPLACE_PYTHON
+variable and set it to the list of files (paths relative to WRKSRC) that must
+be corrected. For example:
-CHECK_BUILTIN.foo?= no
-.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
-#
-# Here we place code that depends on whether USE_BUILTIN.foo is set to
-# "yes" or "no".
-#
-.endif # CHECK_BUILTIN.foo
+REPLACE_PYTHON= *.py
-The first section sets IS_BUILTIN.pkg depending on if pkg really exists in the
-base system. This should not be a base system software with similar
-functionality to pkg; it should only be "yes" if the actual package is included
-as part of the base system. This variable is only used internally within the
-builtin.mk file.
+Some Python modules have separate distributions for Python-2.x and Python-3.x
+support. In pkgsrc this is handled by the versioned_dependencies.mk file. Set
+PYTHON_VERSIONED_DEPENDENCIES to the list of packages that should be depended
+upon and include "../../lang/python/versioned_dependencies.mk", then the pkgsrc
+infrastructure will depend on the appropriate package version. For example:
-The second section sets BUILTIN_PKG.pkg to the version of pkg in the base
-system if it exists (if IS_BUILTIN.pkg is "yes"). This variable is only used
-internally within the builtin.mk file.
+PYTHON_VERSIONED_DEPENDENCIES=dialog
-The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files.
-The code in this section must make the determination whether the built-in
-software is adequate to satisfy the dependencies listed in
-BUILDLINK_API_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg
-against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg
-must be set to the correct value by the end of the builtin.mk file. Note that
-USE_BUILTIN.pkg may be "yes" even if IS_BUILTIN.pkg is "no" because we may make
-the determination that the built-in version of the software is similar enough
-to be used as a replacement.
+Look inside versioned_dependencies.mk for a list of supported packages.
-The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses
-the value of USE_BUILTIN.pkg set in the previous section. This typically
-includes, e.g., adding additional dependency restrictions and listing
-additional files to symlink into ${BUILDLINK_DIR} (via BUILDLINK_FILES.pkg).
+14.1.3. R packages
-16.3.2. Global preferences for native or pkgsrc software
+Simple R packages from CRAN are handled automatically by R2pkg, which is
+available in pkgtools/R2pkg. Individual packages (and optionally their
+dependencies) may be created and updated. R packages generally follow the same
+form, and most of the relevant information needed is contained in a DESCRIPTION
+file as part of each R package on CRAN. Consequently, R2pkg downloads that
+information and creates or updates a package in the canonical form. The
+resulting package should be reviewed for correctness.
-When building packages, it's possible to choose whether to set a global
-preference for using either the built-in (native) version or the pkgsrc version
-of software to satisfy a dependency. This is controlled by setting
-PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either "yes", "
-no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc
-versions of software, while PREFER_NATIVE tells pkgsrc to use the built-in
-versions. Preferences are determined by the most specific instance of the
-package in either PREFER_PKGSRC or PREFER_NATIVE. If a package is specified in
-neither or in both variables, then PREFER_PKGSRC has precedence over
-PREFER_NATIVE. For example, to require using pkgsrc versions of software for
-all but the most basic bits on a NetBSD system, you can set:
+14.1.4. TeXlive packages
-PREFER_PKGSRC= yes
-PREFER_NATIVE= getopt skey tcp_wrappers
+TeXlive packages from CTAN are handled automatically by texlive2pkg, which is
+available in pkgtools/texlive2pkg.
-A package must have a builtin.mk file to be listed in PREFER_NATIVE, otherwise
-it is simply ignored in that list.
+If the TeXlive package name is not known, it may be useful to search CTAN. A "
+Contained in" field on the package page typically identifies the basename of
+the package file in the TeXlive archive.
-Setting PREFER_NATIVE should be performed straight after bootstrap and
-PREFER_PKGSRC during bootstrap. Switching between settings globally at a later
-date can introduce complications with dependency resolution. This is caused by
-packages built with the opposite preference being installed alongside each
-other.
+If the TeXlive package name is known, download the files from the TeXlive
+archive. For package foo, you will need to download foo.tar.xz. Most TeXlive
+packages also have associated documentation packages, so download
+foo.doc.tar.xz at the same time. These files should be placed in the
+appropriate category directory, which is often but not always print. Then run
+the following command in the category directory.
-# ./bootstrap --prefer-pkgsrc yes
+texlive2pkg foo.tar.xz foo.doc.tar.xz
+
+This will create two packages, tex-foo and tex-foo-doc. Be sure to check that
+both packages are correct.
-Chapter 17. The pkginstall framework
+Finally, CTAN currently does not include version information in package
+filenames and changes their contents periodically when updates occur.
+Consequently, pkgsrc avoids downloading distfiles directly from CTAN and
+instead relies on the pkgsrc archives. For each new or updated TeXlive package,
+e.g., the main one and the corresponding documentation, upload the distfiles
+with the following command in each package directory.
-Table of Contents
+make upload-distfiles
+
+14.2. Examples
-17.1. Files and directories outside the installation prefix
+14.2.1. How the www/nvu package came into pkgsrc
- 17.1.1. Directory manipulation
- 17.1.2. File manipulation
+14.2.1.1. The initial package
-17.2. Configuration files
+Looking at the file pkgsrc/doc/TODO, I saw that the "nvu" package has not yet
+been imported into pkgsrc. As the description says it has to do with the web,
+the obvious choice for the category is "www".
- 17.2.1. How PKG_SYSCONFDIR is set
- 17.2.2. Telling the software where configuration files are
- 17.2.3. Patching installations
- 17.2.4. Disabling handling of configuration files
+$ mkdir www/nvu
+$ cd www/nvu
-17.3. System startup scripts
+The web site says that the sources are available as a tar file, so I fed that
+URL to the url2pkg program:
- 17.3.1. Disabling handling of system startup scripts
+$ url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
-17.4. System users and groups
-17.5. System shells
+My editor popped up, and I added a PKGNAME line below the DISTNAME line, as the
+package name should not have the word "sources" in it. I also filled in the
+MAINTAINER, HOMEPAGE and COMMENT fields. Then the package Makefile looked like
+that:
- 17.5.1. Disabling shell registration
+# $NetBSD $
+#
-17.6. Fonts
+DISTNAME= nvu-1.0-sources
+PKGNAME= nvu-1.0
+CATEGORIES= www
+MASTER_SITES= http://cvs.nvu.com/download/
+EXTRACT_SUFX= .tar.bz2
- 17.6.1. Disabling automatic update of the fonts databases
+MAINTAINER= rillig%NetBSD.org@localhost
+HOMEPAGE= http://cvs.nvu.com/
+COMMENT= Web Authoring System
-This chapter describes the framework known as pkginstall, whose key features
-are:
+# url2pkg-marker (please do not remove this line.)
+.include "../../mk/bsd.pkg.mk"
- * Generic installation and manipulation of directories and files outside the
- pkgsrc-handled tree, LOCALBASE.
+On the first line of output above, an artificial space has been added between
+NetBSD and $, this is a workaround to prevent CVS expanding to the filename of
+the guide.
- * Automatic handling of configuration files during installation, provided
- that packages are correctly designed.
+Then, I quit the editor and watched pkgsrc downloading a large source archive:
- * Generation and installation of system startup scripts.
+url2pkg> Running "make makesum" ...
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Fetching nvu-1.0-sources.tar.bz2
+Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
+100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA
+29687976 bytes retrieved in 03:12 (150.77 KB/s)
+url2pkg> Running "make extract" ...
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
+===> Installing dependencies for nvu-1.0
+===> Overriding tools for nvu-1.0
+===> Extracting for nvu-1.0
+url2pkg> Adjusting the Makefile.
- * Registration of system users and groups.
+Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
- * Registration of system shells.
+Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
- * Automatic updating of fonts databases.
+14.2.1.2. Fixing all kinds of problems to make the package work
-The following sections inspect each of the above points in detail.
+Now that the package has been extracted, let's see what's inside it. The
+package has a README.txt, but that only says something about mozilla, so it's
+probably useless for seeing what dependencies this package has. But since there
+is a GNU configure script in the package, let's hope that it will complain
+about everything it needs.
-You may be thinking that many of the things described here could be easily done
-with simple code in the package's post-installation target (post-install). This
-is incorrect, as the code in them is only executed when building from source.
-Machines using binary packages could not benefit from it at all (as the code
-itself could be unavailable). Therefore, the only way to achieve any of the
-items described above is by means of the installation scripts, which are
-automatically generated by pkginstall.
+$ bmake
+=> Required installed package digest>=20010302: digest-20060826 found
+=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+===> Patching for nvu-1.0
+===> Creating toolchain wrappers for nvu-1.0
+===> Configuring for nvu-1.0
+[...]
+configure: error: Perl 5.004 or higher is required.
+[...]
+WARNING: Please add USE_TOOLS+=perl to the package Makefile.
+[...]
-17.1. Files and directories outside the installation prefix
+That worked quite well. So I opened the package Makefile in my editor, and
+since it already has a USE_TOOLS line, I just appended "perl" to it. Since the
+dependencies of the package have changed now, and since a perl wrapper is
+automatically installed in the "tools" phase, I need to build the package from
+scratch.
-As you already know, the PLIST file holds a list of files and directories that
-belong to a package. The names used in it are relative to the installation
-prefix (${PREFIX}), which means that it cannot register files outside this
-directory (absolute path names are not allowed). Despite this restriction, some
-packages need to install files outside this location; e.g., under ${VARBASE} or
-${PKG_SYSCONFDIR}. The only way to achieve this is to create such files during
-installation time by using installation scripts.
+$ bmake clean
+===> Cleaning for nvu-1.0
+$ bmake
+[...]
+*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
+GNU Make. You will not be able to build Mozilla without GNU Make.
+[...]
-The generic installation scripts are shell scripts that can contain arbitrary
-code. The list of scripts to execute is taken from the INSTALL_FILE variable,
-which defaults to INSTALL. A similar variable exists for package removal
-(DEINSTALL_FILE, whose default is DEINSTALL). These scripts can run arbitrary
-commands, so they have the potential to create and manage files anywhere in the
-file system.
+So I added "gmake" to the USE_TOOLS line and tried again (from scratch).
-Using these general installation files is not recommended, but may be needed in
-some special cases. One reason for avoiding them is that the user has to trust
-the packager that there is no unwanted or simply erroneous code included in the
-installation script. Also, previously there were many similar scripts for the
-same functionality, and fixing a common error involved finding and changing all
-of them.
+[...]
+checking for GTK - version >= 1.2.0... no
+*** Could not run GTK test program, checking why...
+[...]
-The pkginstall framework offers another, standardized way. It provides generic
-scripts to abstract the manipulation of such files and directories based on
-variables set in the package's Makefile. The rest of this section describes
-these variables.
+Now to the other dependencies. The first question is: Where is the GTK package
+hidden in pkgsrc?
-17.1.1. Directory manipulation
+$ echo ../../*/gtk*
+[many packages ...]
+$ echo ../../*/gtk
+../../x11/gtk
+$ echo ../../*/gtk2
+../../x11/gtk2
+$ echo ../../*/gtk2/bui*
+../../x11/gtk2/buildlink3.mk
-The following variables can be set to request the creation of directories
-anywhere in the file system:
+The first try was definitely too broad. The second one had exactly one result,
+which is very good. But there is one pitfall with GNOME packages. Before GNOME
+2 had been released, there were already many GNOME 1 packages in pkgsrc. To be
+able to continue to use these packages, the GNOME 2 packages were imported as
+separate packages, and their names usually have a "2" appended. So I checked
+whether this was the case here, and indeed it was.
- * MAKE_DIRS and OWN_DIRS contain a list of directories that should be created
- and should attempt to be destroyed by the installation scripts. The
- difference between the two is that the latter prompts the administrator to
- remove any directories that may be left after deinstallation (because they
- were not empty), while the former does not. Example:
+Since the GTK2 package has a buildlink3.mk file, adding the dependency is very
+easy. I just inserted an .include line before the last line of the package
+Makefile, so that it now looks like this:
- MAKE_DIRS+= ${VARBASE}/foo/private
+[...]
+.include "../../x11/gtk2/buildlink3.mk"
+.include "../../mk/bsd.pkg.mk
- * MAKE_DIRS_PERMS and OWN_DIRS_PERMS contain a list of tuples describing
- which directories should be created and should attempt to be destroyed by
- the installation scripts. Each tuple holds the following values, separated
- by spaces: the directory name, its owner, its group and its numerical mode.
- For example:
+After another bmake clean && bmake, the answer was:
- MAKE_DIRS_PERMS+= ${VARBASE}/foo/private \
- ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
+[...]
+checking for gtk-config... /home/roland/pkg/bin/gtk-config
+checking for GTK - version >= 1.2.0... no
+*** Could not run GTK test program, checking why...
+*** The test program failed to compile or link. See the file config.log for the
+*** exact error that occured. This usually means GTK was incorrectly installed
+*** or that you have moved GTK since it was installed. In the latter case, you
+*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
+configure: error: Test for GTK failed.
+[...]
- The difference between the two is exactly the same as their non-PERMS
- counterparts.
+In this particular case, the assumption that "every package prefers GNOME 2"
+had been wrong. The first of the lines above told me that this package really
+wanted to have the GNOME 1 version of GTK. If the package had looked for GTK2,
+it would have looked for pkg-config instead of gtk-config. So I changed the x11
+/gtk2 to x11/gtk in the package Makefile, and tried again.
-17.1.2. File manipulation
+[...]
+cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" [...]
+In file included from xpidl.c:42:
+xpidl.h:53:24: libIDL/IDL.h: No such file or directory
+In file included from xpidl.c:42:
+xpidl.h:132: error: parse error before "IDL_ns"
+[...]
-Creating non-empty files outside the installation prefix is tricky because the
-PLIST forces all files to be inside it. To overcome this problem, the only
-solution is to extract the file in the known place (i.e., inside the
-installation prefix) and copy it to the appropriate location during
-installation (done by the installation scripts generated by pkginstall). We
-will call the former the master file in the following paragraphs, which
-describe the variables that can be used to automatically and consistently
-handle files outside the installation prefix:
+The package still does not find all of its dependencies. Now the question is:
+Which package provides the libIDL/IDL.h header file?
- * CONF_FILES and REQD_FILES are pairs of master and target files. During
- installation time, the master file is copied to the target one if and only
- if the latter does not exist. Upon deinstallation, the target file is
- removed provided that it was not modified by the installation.
+$ echo ../../*/*idl*
+../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
+$ echo ../../*/*IDL*
+../../net/libIDL
- The difference between the two is that the latter prompts the administrator
- to remove any files that may be left after deinstallation (because they
- were not empty), while the former does not.
+Let's take the one from the second try. So I included the ../../net/libIDL/
+buildlink3.mk file and tried again. But the error didn't change. After digging
+through some of the code, I concluded that the build process of the package was
+broken and couldn't have ever worked, but since the Mozilla source tree is
+quite large, I didn't want to fix it. So I added the following to the package
+Makefile and tried again:
- * CONF_FILES_PERMS and REQD_FILES_PERMS contain tuples describing master
- files as well as their target locations. For each of them, it also
- specifies their owner, their group and their numeric permissions, in this
- order. For example:
+CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
+BUILDLINK_TRANSFORM+= l:IDL:IDL-2
- REQD_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile \
- ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
+The latter line is needed because the package expects the library libIDL.so,
+but only libIDL-2.so is available. So I told the compiler wrapper to rewrite
+that on the fly.
- The difference between the two is exactly the same as their non-PERMS
- counterparts.
+The next problem was related to a recent change of the FreeType interface. I
+looked up in www/seamonkey which patch files were relevant for this issue and
+copied them to the patches directory. Then I retried, fixed the patches so that
+they applied cleanly and retried again. This time, everything worked.
-17.2. Configuration files
+14.2.1.3. Installing the package
-Configuration files are special in the sense that they are installed in their
-own specific directory, PKG_SYSCONFDIR, and need special treatment during
-installation (most of which is automated by pkginstall). The main concept you
-must bear in mind is that files marked as configuration files are automatically
-copied to the right place (somewhere inside PKG_SYSCONFDIR) during installation
-if and only if they didn't exist before. Similarly, they will not be removed if
-they have local modifications. This ensures that administrators never lose any
-custom changes they may have made.
+$ bmake CHECK_FILES=no install
+[...]
+$ bmake print-PLIST >PLIST
+$ bmake deinstall
+$ bmake install
-17.2.1. How PKG_SYSCONFDIR is set
+Chapter 15. Programming in Makefiles
-As said before, the PKG_SYSCONFDIR variable specifies where configuration files
-shall be installed. Its contents are set based upon the following variables:
+Table of Contents
- * PKG_SYSCONFBASE: The configuration's root directory. Defaults to ${PREFIX}/
- etc although it may be overridden by the user to point to his preferred
- location (e.g., /etc, /etc/pkg, etc.). Packages must not use it directly.
+15.1. Caveats
+15.2. Makefile variables
- * PKG_SYSCONFSUBDIR: A subdirectory of PKG_SYSCONFBASE under which the
- configuration files for the package being built shall be installed. The
- definition of this variable only makes sense in the package's Makefile
- (i.e., it is not user-customizable).
+ 15.2.1. Naming conventions
- As an example, consider the Apache package, www/apache24, which places its
- configuration files under the httpd/ subdirectory of PKG_SYSCONFBASE. This
- should be set in the package Makefile.
+15.3. Code snippets
- * PKG_SYSCONFVAR: Specifies the name of the variable that holds this
- package's configuration directory (if different from PKG_SYSCONFBASE). It
- defaults to PKGBASE's value, and is always prefixed with PKG_SYSCONFDIR.
+ 15.3.1. Adding things to a list
+ 15.3.2. Echoing a string exactly as-is
+ 15.3.3. Passing CFLAGS to GNU configure scripts
+ 15.3.4. Handling possibly empty variables
- * PKG_SYSCONFDIR.${PKG_SYSCONFVAR}: Holds the directory where the
- configuration files for the package identified by PKG_SYSCONFVAR's shall be
- placed.
+Pkgsrc consists of many Makefile fragments, each of which forms a well-defined
+part of the pkgsrc system. Using the make(1) system as a programming language
+for a big system like pkgsrc requires some discipline to keep the code correct
+and understandable.
-Based on the above variables, pkginstall determines the value of
-PKG_SYSCONFDIR, which is the only variable that can be used within a package to
-refer to its configuration directory. The algorithm used to set its value is
-basically the following:
+The basic ingredients for Makefile programming are variables and shell
+commands. Among these shell commands may even be more complex ones like awk(1)
+programs. To make sure that every shell command runs as intended it is
+necessary to quote all variables correctly when they are used.
- 1. If PKG_SYSCONFDIR.${PKG_SYSCONFVAR} is set, its value is used.
+This chapter describes some patterns that appear quite often in Makefiles,
+including the pitfalls that come along with them.
- 2. If the previous variable is not defined but PKG_SYSCONFSUBDIR is set in the
- package's Makefile, the resulting value is ${PKG_SYSCONFBASE}/$
- {PKG_SYSCONFSUBDIR}.
+15.1. Caveats
- 3. Otherwise, it is set to ${PKG_SYSCONFBASE}.
+ * When you are creating a file as a target of a rule, always write the data
+ to a temporary file first and finally rename that file. Otherwise there
+ might occur an error in the middle of generating the file, and when the
+ user runs make(1) for the second time, the file exists and will not be
+ regenerated properly. Example:
-It is worth mentioning that ${PKG_SYSCONFDIR} is automatically added to
-OWN_DIRS. See Section 17.1.1, "Directory manipulation" what this means. This
-does not apply to subdirectories of ${PKG_SYSCONFDIR}, they still have to be
-created with OWN_DIRS or MAKE_DIRS.
+ wrong:
+ @echo "line 1" > ${.TARGET}
+ @echo "line 2" >> ${.TARGET}
+ @false
-17.2.2. Telling the software where configuration files are
+ correct:
+ @echo "line 1" > ${.TARGET}.tmp
+ @echo "line 2" >> ${.TARGET}.tmp
+ @false
+ @mv ${.TARGET}.tmp ${.TARGET}
-Given that pkgsrc (and users!) expect configuration files to be in a known
-place, you need to teach each package where it shall install its files. In some
-cases you will have to patch the package Makefiles to achieve it. If you are
-lucky, though, it may be as easy as passing an extra flag to the configuration
-script; this is the case of GNU Autoconf- generated files:
+ When you run make wrong twice, the file wrong will exist, although there
+ was an error message in the first run. On the other hand, running make
+ correct gives an error message twice, as expected.
-CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
+ You might remember that make(1) sometimes removes ${.TARGET} in case of
+ error, but this only happens when it is interrupted, for example by
+ pressing Ctrl+C. This does not happen when one of the commands fails (like
+ false(1) above).
-Note that this specifies where the package has to look for its configuration
-files, not where they will be originally installed (although the difference is
-never explicit, unfortunately).
+15.2. Makefile variables
-17.2.3. Patching installations
+Makefile variables contain strings that can be processed using the five
+operators =, +=, ?=, := and !=, which are described in the make(1) man page.
-As said before, pkginstall automatically handles configuration files. This
-means that the packages themselves must not touch the contents of $
-{PKG_SYSCONFDIR} directly. Bad news is that many software installation scripts
-will, out of the box, mess with the contents of that directory. So what is the
-correct procedure to fix this issue?
+When a variable's value is parsed from a Makefile, the hash character # and the
+backslash character \ are handled specially. If a backslash is the last
+character in a line, that backslash is removed from the line and the line
+continues with the next line of the file.
-You must teach the package (usually by manually patching it) to install any
-configuration files under the examples hierarchy, share/examples/${PKGBASE}/.
-This way, the PLIST registers them and the administrator always has the
-original copies available.
+The # character starts a comment that reaches until the end of the line. To get
+an actual # character, such as in a URL, write \# instead.
-Once the required configuration files are in place (i.e., under the examples
-hierarchy), the pkginstall framework can use them as master copies during the
-package installation to update what is in ${PKG_SYSCONFDIR}. To achieve this,
-the variables CONF_FILES and CONF_FILES_PERMS are used. Check out
-Section 17.1.2, "File manipulation" for information about their syntax and
-their purpose. Here is an example, taken from the mail/mutt package:
+The evaluation of variables either happens immediately or lazy. It happens
+immediately when the variable occurs on the right-hand side of the := or the !=
+operator, in a .if condition or a .for loop. In the other cases, it is
+evaluated lazily.
-EGDIR= ${PREFIX}/share/doc/mutt/samples
-CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
+Some of the modifiers split the string into words and then operate on the
+words, others operate on the string as a whole. When a string is split into
+words, double quotes and single quotes are interpreted as delimiters, just like
+in sh(1).
-Note that the EGDIR variable is specific to that package and has no meaning
-outside it.
+15.2.1. Naming conventions
-17.2.4. Disabling handling of configuration files
+ * All variable names starting with an underscore are reserved for use by the
+ pkgsrc infrastructure. They shall not be used by packages.
-The automatic copying of config files can be toggled by setting the environment
-variable PKG_CONFIG prior to package installation.
+ * In .for loops you should use lowercase variable names for the iteration
+ variables.
-17.3. System startup scripts
+ * All list variables should have a plural name, such as PKG_OPTIONS or
+ DISTFILES.
-System startup scripts are special files because they must be installed in a
-place known by the underlying OS, usually outside the installation prefix.
-Therefore, the same rules described in Section 17.1, "Files and directories
-outside the installation prefix" apply, and the same solutions can be used.
-However, pkginstall provides a special mechanism to handle these files.
+15.3. Code snippets
-In order to provide system startup scripts, the package has to:
+15.3.1. Adding things to a list
- 1. Store the script inside ${FILESDIR}, with the .sh suffix appended.
- Considering the print/cups package as an example, it has a cupsd.sh in its
- files directory.
+When adding a string that possibly contains whitespace or quotes to a list
+(example 1), it must be quoted using the :Q modifier.
- 2. Tell pkginstall to handle it, appending the name of the script, without its
- extension, to the RCD_SCRIPTS variable. Continuing the previous example:
+When adding another list to a list (example 2), it must not be quoted, since
+its elements are already quoted.
- RCD_SCRIPTS+= cupsd
+STRING= foo * bar `date`
+LIST= # empty
+ANOTHER_LIST= a=b c=d
-Once this is done, pkginstall will do the following steps for each script in an
-automated fashion:
+LIST+= ${STRING:Q} # 1
+LIST+= ${ANOTHER_LIST} # 2
- 1. Process the file found in the files directory applying all the
- substitutions described in the FILES_SUBST variable.
+15.3.2. Echoing a string exactly as-is
- 2. Copy the script from the files directory to the examples hierarchy, $
- {PREFIX}/share/examples/rc.d/. Note that this master file must be
- explicitly registered in the PLIST.
+Echoing a string containing special characters needs special work.
- 3. Add code to the installation scripts to copy the startup script from the
- examples hierarchy into the system-wide startup scripts directory.
+STRING= foo bar < > * `date` $$HOME ' "
+EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
-17.3.1. Disabling handling of system startup scripts
+all:
+ echo ${STRING} # 1
+ echo ${STRING:Q} # 2
+ printf '%s\n' ${STRING:Q}'' # 3
+ env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
-The automatic copying of config files can be toggled by setting the environment
-variable PKG_RCD_SCRIPTS prior to package installation. Note that the scripts
-will be always copied inside the examples hierarchy, ${PREFIX}/share/examples/
-rc.d/, no matter what the value of this variable is.
+Example 1 leads to a syntax error in the shell, as the characters are just
+copied.
-17.4. System users and groups
+Example 2 quotes the string so that the shell interprets it correctly. But the
+echo command may additionally interpret strings with a leading dash or those
+containing backslashes.
-If a package needs to create special users and/or groups during installation,
-it can do so by using the pkginstall framework.
+Example 3 can handle arbitrary strings, since printf(1) only interprets the
+format string, but not the next argument. The trailing single quotes handle the
+case when the string is empty. In that case, the :Q modifier would result in an
+empty string too, which would then be skipped by the shell. For printf(1) this
+doesn't make a difference, but other programs may care.
-Users can be created by adding entries to the PKG_USERS variable. Each entry
-has the following syntax:
+In example 4, the EXAMPLE_ENV does not need to be quoted because the quoting
+has already been done when adding elements to the list.
-user:group
+15.3.3. Passing CFLAGS to GNU configure scripts
-Further specification of user details may be done by setting per-user
-variables. PKG_UID.user is the numeric UID for the user. PKG_GECOS.user is the
-user's description or comment. PKG_HOME.user is the user's home directory, and
-defaults to /nonexistent if not specified. PKG_SHELL.user is the user's shell,
-and defaults to /sbin/nologin if not specified.
+When passing CFLAGS or similar variables to a GNU-style configure script
+(especially those that call other configure scripts), it must not have leading
+or trailing whitespace, since otherwise the configure script gets confused. To
+trim leading and trailing whitespace, use the :M modifier, as in the following
+example:
-Similarly, groups can be created by adding entries to the PKG_GROUPS variable,
-whose syntax is:
+CPPFLAGS= # empty
+CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
+CPPFLAGS+= ${MY_CPPFLAGS}
-group
+CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
-The numeric GID of the group may be set by defining PKG_GID.group.
+all:
+ echo x${CPPFLAGS:Q}x # leading and trailing whitespace
+ echo x${CONFIGURE_ARGS:Q}x # properly trimmed
-If a package needs to create the users and groups at an earlier stage, then it
-can set USERGROUP_PHASE to either configure,build, or pre-install to indicate
-the phase before which the users and groups are created. In this case, the
-numeric UIDs and GIDs of the created users and groups are automatically
-hardcoded into the final installation scripts.
+In this example, CPPFLAGS has both leading and trailing whitespace because the
++= operator always adds a space.
-17.5. System shells
+15.3.4. Handling possibly empty variables
-Packages that install system shells should register them in the shell database,
-/etc/shells, to make things easier to the administrator. This must be done from
-the installation scripts to keep binary packages working on any system.
-pkginstall provides an easy way to accomplish this task.
+When a possibly empty variable is used in a shell program, it may lead to a
+syntax error.
-When a package provides a shell interpreter, it has to set the PKG_SHELL
-variable to its absolute file name. This will add some hooks to the
-installation scripts to handle it. Consider the following example, taken from
-shells/zsh:
+EGFILES= # empty
-PKG_SHELL= ${PREFIX}/bin/zsh
+install-examples: # produces a syntax error in the shell
+ for egfile in ${EGFILES}; do \
+ echo "Installing $$egfile"; \
+ done
-17.5.1. Disabling shell registration
+The shell only sees the text for egfile in ; do, since ${EGFILES} is replaced
+with an empty string by make(1). To fix this syntax error, use one of the
+snippets below.
-The automatic registration of shell interpreters can be disabled by the
-administrator by setting the PKG_REGISTER_SHELLS environment variable to NO.
+EMPTY= # empty
-17.6. Fonts
+install-examples:
+ for egfile in ${EGFILES} ""; do \
+ [ -n "$$egfile" ] || continue; \
+ echo "Installing $$egfile"; \
+ done
-Packages that install X11 fonts should update the database files that index the
-fonts within each fonts directory. This can easily be accomplished within the
-pkginstall framework.
+In this case, an empty string is appended to the iteration list (to prevent the
+syntax error) and filtered out later.
-When a package installs X11 fonts, it must list the directories in which fonts
-are installed in the FONTS_DIRS.type variables, where type can be one of "ttf",
-"type1" or "x11". This will add hooks to the installation scripts to run the
-appropriate commands to update the fonts database files within each of those
-directories. For convenience, if the directory path is relative, it is taken to
-be relative to the package's installation prefix. Consider the following
-example, taken from fonts/dbz-ttf:
+EGFILES= # empty
-FONTS_DIRS.ttf= ${PREFIX}/share/fonts/X11/TTF
+install-examples:
+.for egfile in ${EGFILES}
+ echo "Installing ${egfile}"
+.endfor
-17.6.1. Disabling automatic update of the fonts databases
+If one of the filenames contains special characters, it should be enclosed in
+single or double quotes.
-The automatic update of fonts databases can be disabled by the administrator by
-setting the PKG_UPDATE_FONTS_DB environment variable to NO.
+To have a shell command test whether a make variable is empty, use the
+following code: ${TEST} -z ${POSSIBLY_EMPTY:Q}"".
-Chapter 18. Options handling
+Chapter 16. Options handling
Table of Contents
-18.1. Global default options
-18.2. Converting packages to use bsd.options.mk
-18.3. Option Names
-18.4. Determining the options of dependencies
+16.1. Global default options
+16.2. Converting packages to use bsd.options.mk
+16.3. Option Names
+16.4. Determining the options of dependencies
Many packages have the ability to be built to support different sets of
features. bsd.options.mk is a framework in pkgsrc that provides generic
@@ -4893,13 +4815,13 @@ A further consideration is licensing. No
non-free dependencies (especially plugins) should almost always be split if
feasible.
-18.1. Global default options
+16.1. Global default options
Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of
the options that should be built into every package if that option is
supported. This variable should be set in mk.conf.
-18.2. Converting packages to use bsd.options.mk
+16.2. Converting packages to use bsd.options.mk
The following example shows how bsd.options.mk should be used by the
hypothetical ``wibble'' package, either in the package Makefile, or in a file,
@@ -5017,7 +4939,7 @@ PKG_OPTIONS:
.if !empty(PKG_OPTIONS:Moption)
-18.3. Option Names
+16.3. Option Names
Options that enable similar features in different packages (like optional
support for a library) should use a common name in all packages that support it
@@ -5038,7 +4960,7 @@ description. The description should be a
uppercase letter and ending with a period) that describes what enabling the
option does. E. g. "Enable ispell support." The file is sorted by option names.
-18.4. Determining the options of dependencies
+16.4. Determining the options of dependencies
When writing buildlink3.mk files, it is often necessary to list different
dependencies based on the options with which the package was built. For
@@ -5057,865 +4979,965 @@ PKG_BUILD_OPTIONS.libpurple to the build
which can then be queried like PKG_OPTIONS in the options.mk file. See the file
pkg-build-options.mk for more details.
-Chapter 19. The build process
+Chapter 17. Tools needed for building or running
Table of Contents
-19.1. Introduction
-19.2. Program location
-19.3. Directories used during the build process
-19.4. Running a phase
-19.5. The fetch phase
-
- 19.5.1. What to fetch and where to get it from
- 19.5.2. How are the files fetched?
-
-19.6. The checksum phase
-19.7. The extract phase
-19.8. The patch phase
-19.9. The tools phase
-19.10. The wrapper phase
-19.11. The configure phase
-19.12. The build phase
-19.13. The test phase
-19.14. The install phase
-19.15. The package phase
-19.16. Cleaning up
-19.17. Other helpful targets
+17.1. Tools for pkgsrc builds
+17.2. Tools needed by packages
+17.3. Tools provided by platforms
-19.1. Introduction
+The USE_TOOLS definition is used both internally by pkgsrc and also for
+individual packages to define what commands are needed for building a package
+(like TOOL_DEPENDS) or for later run-time of an installed packaged (such as
+DEPENDS). If the native system provides an adequate tool, then in many cases, a
+pkgsrc package will not be used.
-This chapter gives a detailed description on how a package is built. Building a
-package is separated into different phases (for example fetch, build, install),
-all of which are described in the following sections. Each phase is split into
-so-called stages, which take the name of the containing phase, prefixed by one
-of pre-, do- or post-. (Examples are pre-configure, post-build.) Most of the
-actual work is done in the do-* stages.
+When building a package, the replacement tools are made available in a
+directory (as symlinks or wrapper scripts) that is early in the executable
+search path. Just like the buildlink system, this helps with consistent builds.
-Never override the regular targets (like fetch), if you have to, override the
-do-* ones instead.
+A tool may be needed to help build a specific package. For example, perl, GNU
+make (gmake) or yacc may be needed.
-The basic steps for building a program are always the same. First the program's
-source (distfile) must be brought to the local system and then extracted. After
-any pkgsrc-specific patches to compile properly are applied, the software can
-be configured, then built (usually by compiling), and finally the generated
-binaries, etc. can be put into place on the system.
+Also a tool may be needed, for example, because the native system's supplied
+tool may be inefficient for building a package with pkgsrc. For example, a
+package may need GNU awk, bison (instead of yacc) or a better sed.
+
+The tools used by a package can be listed by running make show-tools.
+
+17.1. Tools for pkgsrc builds
+
+The default set of tools used by pkgsrc is defined in bsd.pkg.mk. This includes
+standard Unix tools, such as: cat, awk, chmod, test, and so on. These can be
+seen by running: make show-var VARNAME=USE_TOOLS.
+
+If a package needs a specific program to build then the USE_TOOLS variable can
+be used to define the tools needed.
+
+17.2. Tools needed by packages
+
+In the following examples, the :run means that it is needed at run-time (and
+becomes a DEPENDS). The default is a build dependency which can be set with
+:build. (So in this example, it is the same as gmake:build and
+pkg-config:build.)
+
+USE_TOOLS+= gmake perl:run pkg-config
+
+When using the tools framework, a TOOLS_PATH.foo variable is defined which
+contains the full path to the appropriate tool. For example, TOOLS_PATH.bash
+could be "/bin/bash" on Linux systems.
+
+If you always need a pkgsrc version of the tool at run-time, then just use
+DEPENDS instead.
+
+17.3. Tools provided by platforms
+
+When improving or porting pkgsrc to a new platform, have a look at (or create)
+the corresponding platform specific make file fragment under pkgsrc/mk/tools/
+tools.${OPSYS}.mk which defines the name of the common tools. For example:
+
+.if exists(/usr/bin/bzcat)
+TOOLS_PLATFORM.bzcat?= /usr/bin/bzcat
+.elif exists(/usr/bin/bzip2)
+TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd
+.endif
+
+TOOLS_PLATFORM.true?= true # shell builtin
+
+Chapter 18. Buildlink methodology
+
+Table of Contents
+
+18.1. Converting packages to use buildlink3
+18.2. Writing buildlink3.mk files
+
+ 18.2.1. Anatomy of a buildlink3.mk file
+ 18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
+ buildlink3.mk files
+
+18.3. Writing builtin.mk files
+
+ 18.3.1. Anatomy of a builtin.mk file
+ 18.3.2. Global preferences for native or pkgsrc software
+
+Buildlink is a framework in pkgsrc that controls what headers and libraries are
+seen by a package's configure and build processes. This is implemented in a two
+step process:
+
+ 1. Symlink headers and libraries for dependencies into BUILDLINK_DIR, which by
+ default is a subdirectory of WRKDIR.
+
+ 2. Create wrapper scripts that are used in place of the normal compiler tools
+ that translate -I${LOCALBASE}/include and -L${LOCALBASE}/lib into
+ references to BUILDLINK_DIR. The wrapper scripts also make native compiler
+ on some operating systems look like GCC, so that packages that expect GCC
+ won't require modifications to build with those native compilers.
+
+This normalizes the environment in which a package is built so that the package
+may be built consistently despite what other software may be installed. Please
+note that the normal system header and library paths, e.g. /usr/include, /usr/
+lib, etc., are always searched -- buildlink3 is designed to insulate the
+package build from non-system-supplied software.
+
+18.1. Converting packages to use buildlink3
+
+The process of converting packages to use the buildlink3 framework ("bl3ifying"
+) is fairly straightforward. The things to keep in mind are:
-To get more details about what is happening at each step, you can set the
-PKG_VERBOSE variable, or the PATCH_DEBUG variable if you are just interested in
-more details about the patch step.
+ 1. Ensure that the build always calls the wrapper scripts instead of the
+ actual toolchain. Some packages are tricky, and the only way to know for
+ sure is the check ${WRKDIR}/.work.log to see if the wrappers are being
+ invoked.
-19.2. Program location
+ 2. Don't override PREFIX from within the package Makefile, e.g. Java VMs,
+ standalone shells, etc., because the code to symlink files into $
+ {BUILDLINK_DIR} looks for files relative to "pkg_info -qp pkgname".
-Before outlining the process performed by the NetBSD package system in the next
-section, here's a brief discussion on where programs are installed, and which
-variables influence this.
+ 3. Remember that only the buildlink3.mk files that you list in a package's
+ Makefile are added as dependencies for that package.
-The automatic variable PREFIX indicates where all files of the final program
-shall be installed. It is usually set to LOCALBASE (/usr/pkg), or CROSSBASE for
-pkgs in the cross category. The value of PREFIX needs to be put into the
-various places in the program's source where paths to these files are encoded.
-See Section 13.3, "patches/*" and Section 21.3.1, "Shared libraries - libtool"
-for more details.
+If a dependency on a particular package is required for its libraries and
+headers, then we replace:
-When choosing which of these variables to use, follow the following rules:
+DEPENDS+= foo>=1.1.0:../../category/foo
- * PREFIX always points to the location where the current pkg will be
- installed. When referring to a pkg's own installation path, use "${PREFIX}"
- .
+with
- * LOCALBASE is where all non-X11 pkgs are installed. If you need to construct
- a -I or -L argument to the compiler to find includes and libraries
- installed by another non-X11 pkg, use "${LOCALBASE}". The name LOCALBASE
- stems from FreeBSD, which installed all packages in /usr/local. As pkgsrc
- leaves /usr/local for the system administrator, this variable is a
- misnomer.
+.include "../../category/foo/buildlink3.mk"
- * X11BASE is where the actual X11 distribution (from xsrc, etc.) is
- installed. When looking for standard X11 includes (not those installed by a
- package), use "${X11BASE}".
+The buildlink3.mk files usually define the required dependencies. If you need a
+newer version of the dependency when using buildlink3.mk files, then you can
+define it in your Makefile; for example:
- * X11-based packages using imake must set USE_IMAKE to be installed correctly
- under LOCALBASE.
+BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0
+.include "../../category/foo/buildlink3.mk"
- * Within ${PREFIX}, packages should install files according to hier(7), with
- the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/
- man.
+There are several buildlink3.mk files in pkgsrc/mk that handle special package
+issues:
-19.3. Directories used during the build process
+ * bdb.buildlink3.mk chooses either the native or a pkgsrc Berkeley DB
+ implementation based on the values of BDB_ACCEPTED and BDB_DEFAULT.
-When building a package, various directories are used to store source files,
-temporary files, pkgsrc-internal files, and so on. These directories are
-explained here.
+ * curses.buildlink3.mk: If the system comes with neither Curses nor NCurses,
+ this will take care to install the devel/ncurses package.
-Some of the directory variables contain relative pathnames. There are two
-common base directories for these relative directories: PKGSRCDIR/PKGPATH is
-used for directories that are pkgsrc-specific. WRKSRC is used for directories
-inside the package itself.
+ * krb5.buildlink3.mk uses the value of KRB5_ACCEPTED to choose between adding
+ a dependency on Heimdal or MIT-krb5 for packages that require a Kerberos 5
+ implementation.
-PKGSRCDIR
+ * motif.buildlink3.mk checks for a system-provided Motif installation or adds
+ a dependency on x11/lesstif or x11/motif. The user can set MOTIF_TYPE to "
+ dt", "lesstif" or "motif" to choose which Motif version will be used.
- This is an absolute pathname that points to the pkgsrc root directory.
- Generally, you don't need it.
+ * readline.buildlink3.mk checks for a system-provided GNU readline or
+ editline (libedit) installation, or adds a dependency on devel/readline,
+ devel/editline. The user can set READLINE_DEFAULT to choose readline
+ implementation. If your package really needs GNU readline library, its
+ Makefile should include devel/readline/buildlink3.mk instead of
+ readline.buildlink3.mk.
-PKGDIR
+ * oss.buildlink3.mk defines several variables that may be used by packages
+ that use the Open Sound System (OSS) API.
- This is an absolute pathname that points to the current package.
+ * pgsql.buildlink3.mk will accept any of the Postgres versions in the
+ variable PGSQL_VERSIONS_ACCEPTED and default to the version
+ PGSQL_VERSION_DEFAULT. See the file for more information.
-PKGPATH
+ * pthread.buildlink3.mk uses the value of PTHREAD_OPTS and checks for native
+ pthreads or adds a dependency on devel/pth as needed.
- This is a pathname relative to PKGSRCDIR that points to the current
- package.
+ * xaw.buildlink3.mk uses the value of XAW_TYPE to choose a particular Athena
+ widgets library.
-WRKDIR
+The comments in those buildlink3.mk files provide a more complete description
+of how to use them properly.
- This is an absolute pathname pointing to the directory where all work takes
- place. The distfiles are extracted to this directory. It also contains
- temporary directories and log files used by the various pkgsrc frameworks,
- like buildlink or the wrappers.
+18.2. Writing buildlink3.mk files
-WRKSRC
+A package's buildlink3.mk file is included by Makefiles to indicate the need to
+compile and link against header files and libraries provided by the package. A
+buildlink3.mk file should always provide enough information to add the correct
+type of dependency relationship and include any other buildlink3.mk files that
+it needs to find headers and libraries that it needs in turn.
- This is an absolute pathname pointing to the directory where the distfiles
- are extracted. It is usually a direct subdirectory of WRKDIR, and often
- it's the only directory entry that isn't hidden. This variable may be
- changed by a package Makefile.
+To generate an initial buildlink3.mk file for further editing, Rene Hexel's
+pkgtools/createbuildlink package is highly recommended. For most packages, the
+following command will generate a good starting point for buildlink3.mk files:
-The CREATE_WRKDIR_SYMLINK definition takes either the value yes or no and
-defaults to no. It indicates whether a symbolic link to the WRKDIR is to be
-created in the pkgsrc entry's directory. If users would like to have their
-pkgsrc trees behave in a read-only manner, then the value of
-CREATE_WRKDIR_SYMLINK should be set to no.
+% cd pkgsrc/category/pkgdir
+% createbuildlink >buildlink3.mk
-19.4. Running a phase
-You can run a particular phase by typing make phase, where phase is the name of
-the phase. This will automatically run all phases that are required for this
-phase. The default phase is build, that is, when you run make without
-parameters in a package directory, the package will be built, but not
-installed.
+18.2.1. Anatomy of a buildlink3.mk file
-19.5. The fetch phase
+The following real-life example buildlink3.mk is taken from pkgsrc/graphics/
+tiff:
-The first step in building a package is to fetch the distribution files
-(distfiles) from the sites that are providing them. This is the task of the
-fetch phase.
+# $NetBSD: buildlink3.mk,v 1.16 2009/03/20 19:24:45 joerg Exp $
-19.5.1. What to fetch and where to get it from
+BUILDLINK_TREE+= tiff
-In simple cases, MASTER_SITES defines all URLs from where the distfile, whose
-name is derived from the DISTNAME variable, is fetched. The more complicated
-cases are described below.
+.if !defined(TIFF_BUILDLINK3_MK)
+TIFF_BUILDLINK3_MK:=
-The variable DISTFILES specifies the list of distfiles that have to be fetched.
-Its value defaults to ${DEFAULT_DISTFILES} and its value is ${DISTNAME}$
-{EXTRACT_SUFX}, so that most packages don't need to define it at all.
-EXTRACT_SUFX is .tar.gz by default, but can be changed freely. Note that if
-your package requires additional distfiles to the default one, you cannot just
-append the additional filenames using the += operator, but you have write for
-example:
+BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1
+BUILDLINK_ABI_DEPENDS.tiff+= tiff>=3.7.2nb1
+BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
-DISTFILES= ${DEFAULT_DISTFILES} additional-files.tar.gz
+.include "../../devel/zlib/buildlink3.mk"
+.include "../../graphics/jpeg/buildlink3.mk"
+.endif # TIFF_BUILDLINK3_MK
-Each distfile is fetched from a list of sites, usually MASTER_SITES. If the
-package has multiple DISTFILES or multiple PATCHFILES from different sites, you
-can set SITES.distfile to the list of URLs where the file distfile (including
-the suffix) can be found.
+BUILDLINK_TREE+= -tiff
-DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
-DISTFILES+= foo-file.tar.gz
-SITES.foo-file.tar.gz= \
-https://www.somewhere.com/somehow/ \
-https://www.somewhereelse.com/mirror/somehow/
+The header and footer manipulate BUILDLINK_TREE, which is common across all
+buildlink3.mk files and is used to track the dependency tree.
-When actually fetching the distfiles, each item from MASTER_SITES or SITES.*
-gets the name of each distfile appended to it, without an intermediate slash.
-Therefore, all site values have to end with a slash or other separator
-character. This allows for example to set MASTER_SITES to a URL of a CGI script
-that gets the name of the distfile as a parameter. In this case, the definition
-would look like:
+The main section is protected from multiple inclusion and controls how the
+dependency on pkg is added. Several important variables are set in the section:
-MASTER_SITES= https://www.example.com/download.cgi?file=
+ * BUILDLINK_API_DEPENDS.pkg is the actual dependency recorded in the
+ installed package; this should always be set using += to ensure that we're
+ appending to any pre-existing list of values. This variable should be set
+ to the first version of the package that had an backwards-incompatible API
+ change.
-The exception to this rule are URLs starting with a dash. In that case the URL
-is taken as is, fetched and the result stored under the name of the distfile.
-You can use this style for the case when the download URL style does not match
-the above common case. For example, if permanent download URL is a redirector
-to the real download URL, or the download file name is offered by an HTTP
-Content-Disposition header. In the following example, foo-1.0.0.tar.gz will be
-created instead of the default v1.0.0.tar.gz.
+ * BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory.
-DISTNAME= foo-1.0.0
-MASTER_SITES= -https://www.example.com/archive/v1.0.0.tar.gz
+ * BUILDLINK_DEPMETHOD.pkg (not shown above) controls whether we use
+ BUILD_DEPENDS or DEPENDS to add the dependency on pkg. The build dependency
+ is selected by setting BUILDLINK_DEPMETHOD.pkg to "build". By default, the
+ full dependency is used.
-There are some predefined values for MASTER_SITES, which can be used in
-packages. The names of the variables should speak for themselves.
+ * BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS.pkg (not shown above) are lists
+ of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and
+ library search paths. These default to "include" and "lib" respectively.
-MASTER_SITE_APACHE MASTER_SITE_BACKUP
-MASTER_SITE_CRATESIO MASTER_SITE_CYGWIN
-MASTER_SITE_DEBIAN MASTER_SITE_FREEBSD
-MASTER_SITE_FREEBSD_LOCAL MASTER_SITE_GENTOO
-MASTER_SITE_GITHUB MASTER_SITE_GNOME
-MASTER_SITE_GNU MASTER_SITE_GNUSTEP
-MASTER_SITE_HASKELL_HACKAGE MASTER_SITE_IFARCHIVE
-MASTER_SITE_KDE MASTER_SITE_MOZILLA
-MASTER_SITE_MOZILLA_ALL MASTER_SITE_MYSQL
-MASTER_SITE_NETLIB MASTER_SITE_OPENBSD
-MASTER_SITE_OPENOFFICE MASTER_SITE_OSDN
-MASTER_SITE_PERL_CPAN MASTER_SITE_PGSQL
-MASTER_SITE_PYPI MASTER_SITE_RUBYGEMS
-MASTER_SITE_R_CRAN MASTER_SITE_SOURCEFORGE
-MASTER_SITE_SUNSITE MASTER_SITE_SUSE
-MASTER_SITE_TEX_CTAN MASTER_SITE_XCONTRIB
-MASTER_SITE_XEMACS MASTER_SITE_XORG
+ * BUILDLINK_CPPFLAGS.pkg (not shown above) is the list of preprocessor flags
+ to add to CPPFLAGS, which are passed on to the configure and build phases.
+ The "-I" option should be avoided and instead be handled using
+ BUILDLINK_INCDIRS.pkg as above.
-Some explanations for the less self-explaining ones: MASTER_SITE_BACKUP
-contains backup sites for packages that are maintained in ftp://ftp.NetBSD.org/
-pub/pkgsrc/distfiles/${DIST_SUBDIR}. MASTER_SITE_LOCAL contains local package
-source distributions that are maintained in ftp://ftp.NetBSD.org/pub/pkgsrc/
-distfiles/LOCAL_PORTS/.
+The following variables are all optionally defined within this second section
+(protected against multiple inclusion) and control which package files are
+symlinked into ${BUILDLINK_DIR} and how their names are transformed during the
+symlinking:
-If you choose one of these predefined sites, you may want to specify a
-subdirectory of that site. Since these macros may expand to more than one
-actual site, you must use the following construct to specify a subdirectory:
+ * BUILDLINK_FILES.pkg (not shown above) is a shell glob pattern relative to $
+ {BUILDLINK_PREFIX.pkg} to be symlinked into ${BUILDLINK_DIR}, e.g. include/
+ *.h.
-MASTER_SITES= ${MASTER_SITE_GNU:=subdirectory/name/}
-MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/}
+ * BUILDLINK_FILES_CMD.pkg (not shown above) is a shell pipeline that outputs
+ to stdout a list of files relative to ${BUILDLINK_PREFIX.pkg}. The
+ resulting files are to be symlinked into ${BUILDLINK_DIR}. By default, this
+ takes the +CONTENTS of a pkg and filters it through $
+ {BUILDLINK_CONTENTS_FILTER.pkg}.
-Note the trailing slash after the subdirectory name.
+ * BUILDLINK_CONTENTS_FILTER.pkg (not shown above) is a filter command that
+ filters +CONTENTS input into a list of files relative to $
+ {BUILDLINK_PREFIX.pkg} on stdout. By default, BUILDLINK_CONTENTS_FILTER.pkg
+ outputs the contents of the include and lib directories in the package
+ +CONTENTS.
-19.5.2. How are the files fetched?
+ * BUILDLINK_FNAME_TRANSFORM.pkg (not shown above) is a list of sed arguments
+ used to transform the name of the source filename into a destination
+ filename, e.g. -e "s|/curses.h|/ncurses.h|g".
-The fetch phase makes sure that all the distfiles exist in a local directory
-(DISTDIR, which can be set by the pkgsrc user). If the files do not exist, they
-are fetched using commands of the form
+This section can additionally include any buildlink3.mk needed for pkg's
+library dependencies. Including these buildlink3.mk files means that the
+headers and libraries for these dependencies are also symlinked into $
+{BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included. Dependencies
+are only added for directly include buildlink3.mk files.
+
+When providing a buildlink3.mk and including other buildlink3.mk files in it,
+please only add necessary ones, i.e., those whose libraries or header files are
+automatically exposed when the package is use.
-${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
+In particular, if only an executable (bin/foo) is linked against a library,
+that library does not need to be propagated in the buildlink3.mk file.
-where ${site} varies through several possibilities in turn: first,
-MASTER_SITE_OVERRIDE is tried, then the sites specified in either SITES.file if
-defined, else MASTER_SITES or PATCH_SITES, as applies, then finally the value
-of MASTER_SITE_BACKUP. The order of all except the first and the last can be
-optionally sorted by the user, via setting either MASTER_SORT_RANDOM, and
-MASTER_SORT_AWK or MASTER_SORT_REGEX.
+The following steps should help you decide if a buildlink3.mk file needs to be
+included:
-The specific command and arguments used depend on the FETCH_USING parameter.
-The example above is for FETCH_USING=custom.
+ * Look at the installed header files: What headers do they include? The
+ packages providing these files must be buildlinked.
-The distfiles mirror run by the NetBSD Foundation uses the mirror-distfiles
-target to mirror the distfiles, if they are freely distributable. Packages
-setting NO_SRC_ON_FTP (usually to "${RESTRICTED}") will not have their
-distfiles mirrored.
+ * Run ldd on all installed libraries and look against what other libraries
+ they link. Some of the packages providing these probably need to be
+ buildlinked; however, it's not automatic, since e.g. GTK on some systems
+ pulls in the X libraries, so they will show up in the ldd output, while on
+ others (like OS X) it won't. ldd output can thus only be used as a hint.
-19.6. The checksum phase
+18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
+buildlink3.mk files
-After the distfile(s) are fetched, their checksum is generated and compared
-with the checksums stored in the distinfo file. If the checksums don't match,
-the build is aborted. This is to ensure the same distfile is used for building,
-and that the distfile wasn't changed, e.g. by some malign force, deliberately
-changed distfiles on the master distribution site or network lossage.
+These two variables differ in that one describes source compatibility (API) and
+the other binary compatibility (ABI). The difference is that a change in the
+API breaks compilation of programs while changes in the ABI stop compiled
+programs from running.
+
+Changes to the BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk file
+happen very rarely. One possible reason is that all packages depending on this
+already need a newer version. In case it is bumped see the description below.
+
+The most common example of an ABI change is that the major version of a shared
+library is increased. In this case, BUILDLINK_ABI_DEPENDS.pkg should be
+adjusted to require at least the new package version. Then the packages that
+depend on this package need their PKGREVISIONs increased and, if they have
+buildlink3.mk files, their BUILDLINK_ABI_DEPENDS.pkg adjusted, too. This is
+needed so pkgsrc will require the correct package dependency and not settle for
+an older one when building the source.
-19.7. The extract phase
+See Section 21.1.5, "Handling dependencies" for more information about
+dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and
+ABI_DEPENDS definitions.
-When the distfiles are present on the local system, they need to be extracted,
-as they usually come in the form of some compressed archive format.
+Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or
+BUILDLINK_ABI_DEPENDS.pkg as we don't want to cause unneeded package deletions
+and rebuilds. In many cases, new versions of packages work just fine with older
+dependencies.
-By default, all DISTFILES are extracted. If you only need some of them, you can
-set the EXTRACT_ONLY variable to the list of those files.
+Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to
+BUILDLINK_API_DEPENDS.pkg.
-Extracting the files is usually done by a little program, mk/extract/extract,
-which already knows how to extract various archive formats, so most likely you
-will not need to change anything here. But if you need, the following variables
-may help you:
+18.3. Writing builtin.mk files
-EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}
+Some packages in pkgsrc install headers and libraries that coincide with
+headers and libraries present in the base system. Aside from a buildlink3.mk
+file, these packages should also include a builtin.mk file that includes the
+necessary checks to decide whether using the built-in software or the pkgsrc
+software is appropriate.
- Use these variables to override the default options for an extract command,
- which are defined in mk/extract/extract.
+The only requirements of a builtin.mk file for pkg are:
-EXTRACT_USING
+ 1. It should set USE_BUILTIN.pkg to either "yes" or "no" after it is included.
- This variable can be set to bsdtar, gtar, nbtar (which is the default
- value), pax, or an absolute pathname pointing to the command with which tar
- archives should be extracted. It is preferred to choose bsdtar over gtar if
- NetBSD's pax-as-tar is not good enough.
+ 2. It should not override any USE_BUILTIN.pkg which is already set before the
+ builtin.mk file is included.
-If the extract program doesn't serve your needs, you can also override the
-EXTRACT_CMD variable, which holds the command used for extracting the files.
-This command is executed in the ${WRKSRC} directory. During execution of this
-command, the shell variable extract_file holds the absolute pathname of the
-file that is going to be extracted.
+ 3. It should be written to allow multiple inclusion. This is very important
+ and takes careful attention to Makefile coding.
-And if that still does not suffice, you can override the do-extract target in
-the package Makefile.
+18.3.1. Anatomy of a builtin.mk file
-19.8. The patch phase
+The following is the recommended template for builtin.mk files:
-After extraction, all the patches named by the PATCHFILES, those present in the
-patches subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
-/usr/local/patches/graphics/png) are applied. Patchfiles ending in .Z or .gz
-are uncompressed before they are applied, files ending in .orig or .rej are
-ignored. Any special options to patch(1) can be handed in PATCH_DIST_ARGS. See
-Section 13.3, "patches/*" for more details.
+.if !defined(IS_BUILTIN.foo)
+#
+# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
+# genuinely exists in the system or not.
+#
+IS_BUILTIN.foo?= no
-By default patch(1) is given special arguments to make it fail if the expected
-text from the patch context is not found in the patched file. If that happens,
-fix the patch file by comparing it with the actual text in the file to be
-patched.
+# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
+# version can be determined.
+#
+. if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
+BUILTIN_PKG.foo?= foo-1.0
+. endif
+.endif # IS_BUILTIN.foo
-19.9. The tools phase
+.if !defined(USE_BUILTIN.foo)
+USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
+. if defined(BUILTIN_PKG.foo)
+. for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
+. if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
+USE_BUILTIN.foo!= \
+ ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo} \
+ && ${ECHO} "yes" || ${ECHO} "no"
+. endif
+. endfor
+. endif
+.endif # USE_BUILTIN.foo
-This is covered in Chapter 20, Tools needed for building or running.
+CHECK_BUILTIN.foo?= no
+.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
+#
+# Here we place code that depends on whether USE_BUILTIN.foo is set to
+# "yes" or "no".
+#
+.endif # CHECK_BUILTIN.foo
-19.10. The wrapper phase
+The first section sets IS_BUILTIN.pkg depending on if pkg really exists in the
+base system. This should not be a base system software with similar
+functionality to pkg; it should only be "yes" if the actual package is included
+as part of the base system. This variable is only used internally within the
+builtin.mk file.
-This phase creates wrapper programs for the compilers and linkers. The
-following variables can be used to tweak the wrappers.
+The second section sets BUILTIN_PKG.pkg to the version of pkg in the base
+system if it exists (if IS_BUILTIN.pkg is "yes"). This variable is only used
+internally within the builtin.mk file.
-ECHO_WRAPPER_MSG
+The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files.
+The code in this section must make the determination whether the built-in
+software is adequate to satisfy the dependencies listed in
+BUILDLINK_API_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg
+against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg
+must be set to the correct value by the end of the builtin.mk file. Note that
+USE_BUILTIN.pkg may be "yes" even if IS_BUILTIN.pkg is "no" because we may make
+the determination that the built-in version of the software is similar enough
+to be used as a replacement.
- The command used to print progress messages. Does nothing by default. Set
- to ${ECHO} to see the progress messages.
+The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses
+the value of USE_BUILTIN.pkg set in the previous section. This typically
+includes, e.g., adding additional dependency restrictions and listing
+additional files to symlink into ${BUILDLINK_DIR} (via BUILDLINK_FILES.pkg).
-WRAPPER_DEBUG
+18.3.2. Global preferences for native or pkgsrc software
- This variable can be set to yes (default) or no, depending on whether you
- want additional information in the wrapper log file.
+When building packages, it's possible to choose whether to set a global
+preference for using either the built-in (native) version or the pkgsrc version
+of software to satisfy a dependency. This is controlled by setting
+PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either "yes", "
+no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc
+versions of software, while PREFER_NATIVE tells pkgsrc to use the built-in
+versions. Preferences are determined by the most specific instance of the
+package in either PREFER_PKGSRC or PREFER_NATIVE. If a package is specified in
+neither or in both variables, then PREFER_PKGSRC has precedence over
+PREFER_NATIVE. For example, to require using pkgsrc versions of software for
+all but the most basic bits on a NetBSD system, you can set:
-WRAPPER_UPDATE_CACHE
+PREFER_PKGSRC= yes
+PREFER_NATIVE= getopt skey tcp_wrappers
- This variable can be set to yes or no, depending on whether the wrapper
- should use its cache, which will improve the speed. The default value is
- yes, but is forced to no if the platform does not support it.
+A package must have a builtin.mk file to be listed in PREFER_NATIVE, otherwise
+it is simply ignored in that list.
-WRAPPER_REORDER_CMDS
+Setting PREFER_NATIVE should be performed straight after bootstrap and
+PREFER_PKGSRC during bootstrap. Switching between settings globally at a later
+date can introduce complications with dependency resolution. This is caused by
+packages built with the opposite preference being installed alongside each
+other.
- A list of reordering commands. A reordering command has the form reorder:l:
- lib1:lib2. It ensures that that -llib1 occurs before -llib2.
+# ./bootstrap --prefer-pkgsrc yes
-19.11. The configure phase
+Chapter 19. PLIST issues
-Most pieces of software need information on the header files, system calls, and
-library routines which are available on the platform they run on. The process
-of determining this information is known as configuration, and is usually
-automated. In most cases, a script is supplied with the distfiles, and its
-invocation results in generation of header files, Makefiles, etc.
+Table of Contents
-If the package contains a configure script, this can be invoked by setting
-HAS_CONFIGURE to "yes". If the configure script is a GNU autoconf script, you
-should set GNU_CONFIGURE to "yes" instead. What happens in the configure phase
-is roughly:
+19.1. RCS ID
+19.2. Semi-automatic PLIST generation
+19.3. Tweaking output of make print-PLIST
+19.4. Variable substitution in PLIST
+19.5. Man page compression
+19.6. Changing PLIST source with PLIST_SRC
+19.7. Platform-specific and differing PLISTs
+19.8. Build-specific PLISTs
+19.9. Sharing directories between packages
-.for d in ${CONFIGURE_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${CONFIGURE_ENV} ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
-.endfor
+The PLIST file contains a package's "packing list", i.e. a list of files that
+belong to the package (relative to the ${PREFIX} directory it's been installed
+in) plus some additional statements - see the pkg_create(1) man page for a full
+list. This chapter addresses some issues that need attention when dealing with
+the PLIST file (or files, see below!).
-CONFIGURE_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In
-each of these directories, the configure script is run with the environment
-CONFIGURE_ENV and arguments CONFIGURE_ARGS. The variables CONFIGURE_ENV,
-CONFIGURE_SCRIPT (default: "./configure") and CONFIGURE_ARGS may all be changed
-by the package.
+19.1. RCS ID
-If the program uses the Perl way of configuration (mainly Perl modules, but not
-only), i.e. a file called Makefile.PL, it should include ../../lang/perl5/
-module.mk. To set any parameter for Makefile.PL use the MAKE_PARAMS variable
-(e.g., MAKE_PARAMS+=foo=bar
+Be sure to add a RCS ID line as the first thing in any PLIST file you write:
-If the program uses an Imakefile for configuration, the appropriate steps can
-be invoked by setting USE_IMAKE to "yes". If you only need xmkmf, add it to
-USE_TOOLS. You can add variables to xmkmf's environment by adding them to the
-SCRIPTS_ENV variable.
+@comment $NetBSD $
-If the program uses cmake for configuration, the appropriate steps can be
-invoked by setting USE_CMAKE to "yes". You can add variables to cmake's
-environment by adding them to the CONFIGURE_ENV variable and arguments to cmake
-by adding them to the CMAKE_ARGS variable. The top directory argument is given
-by the CMAKE_ARG_PATH variable, that defaults to "." (relative to
-CONFIGURE_DIRS)
+An artificial space has been added between NetBSD and $, this is a workaround
+here to prevent CVS expanding to the filename of the guide. When adding the RCS
+ID the space should be omitted.
-If there is no configure step at all, set NO_CONFIGURE to "yes".
+19.2. Semi-automatic PLIST generation
-19.12. The build phase
+You can use the make print-PLIST command to output a PLIST that matches any new
+files since the package was extracted. See Section 13.17, "Other helpful
+targets" for more information on this target.
-For building a package, a rough equivalent of the following code is executed.
+19.3. Tweaking output of make print-PLIST
-.for d in ${BUILD_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${MAKE_ENV} \
- ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
- -f ${MAKE_FILE} \
- ${BUILD_TARGET}
-.endfor
+The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that are
+used to filter the output of print-PLIST. You can append any chunk of AWK
+scripting you like to it, but be careful with quoting.
-BUILD_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In each of
-these directories, MAKE_PROGRAM is run with the environment MAKE_ENV and
-arguments BUILD_MAKE_FLAGS. The variables MAKE_ENV, BUILD_MAKE_FLAGS, MAKE_FILE
-and BUILD_TARGET may all be changed by the package.
+For example, to get all files inside the libdata/foo directory removed from the
+resulting PLIST:
-The default value of MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake", "
-make" otherwise. The default value of MAKE_FILE is "Makefile", and BUILD_TARGET
-defaults to "all".
+PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
-If there is no build step at all, set NO_BUILD to "yes".
+19.4. Variable substitution in PLIST
+
+A number of variables are substituted automatically in PLISTs when a package is
+installed on a system. This includes the following variables:
-19.13. The test phase
+${MACHINE_ARCH}, ${MACHINE_GNU_ARCH}
-[TODO]
+ Some packages like emacs and perl embed information about which
+ architecture they were built on into the pathnames where they install their
+ files. To handle this case, PLIST will be preprocessed before actually
+ used, and the symbol "${MACHINE_ARCH}" will be replaced by what uname -p
+ gives. The same is done if the string ${MACHINE_GNU_ARCH} is embedded in
+ PLIST somewhere - use this on packages that have GNU autoconf-created
+ configure scripts.
-19.14. The install phase
+ Legacy note
-Once the build stage has completed, the final step is to install the software
-in public directories, so users can access the programs and files.
+ There used to be a symbol "$ARCH" that was replaced by the output of uname
+ -m, but that's no longer supported and has been removed.
-In the install phase, a rough equivalent of the following code is executed.
-Additionally, before and after this code, much magic is performed to do
-consistency checks, registering the package, and so on.
+${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION}
-.for d in ${INSTALL_DIRS}
- cd ${WRKSRC} \
- && cd ${d} \
- && env ${MAKE_ENV} \
- ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
- -f ${MAKE_FILE} \
- ${INSTALL_TARGET}
-.endfor
+ Some packages want to embed the OS name and version into some paths. To do
+ this, use these variables in the PLIST:
-The variable's meanings are analogous to the ones in the build phase.
-INSTALL_DIRS defaults to BUILD_DIRS. INSTALL_TARGET is "install" by default,
-plus "install.man" if USE_IMAKE is defined and NO_INSTALL_MANPAGES is not
-defined.
+ + ${OPSYS} - output of "uname -s"
-In the install phase, the following variables are useful. They are all
-variations of the install(1) command that have the owner, group and permissions
-preset. INSTALL is the plain install command. The specialized variants,
-together with their intended use, are:
+ + ${LOWER_OPSYS} - lowercase common name (eg. "solaris")
-INSTALL_PROGRAM_DIR
+ + ${OS_VERSION} - "uname -r"
- directories that contain binaries
+For a list of values which are replaced by default, the output of make help
+topic=PLIST_SUBST as well as searching the pkgsrc/mk directory with grep for
+PLIST_SUBST should help.
-INSTALL_SCRIPT_DIR
+If you want to change other variables not listed above, you can add variables
+and their expansions to this variable in the following way, similar to
+MESSAGE_SUBST (see Section 12.5, "Optional files"):
- directories that contain scripts
+PLIST_SUBST+= SOMEVAR="somevalue"
-INSTALL_LIB_DIR
+This replaces all occurrences of "${SOMEVAR}" in the PLIST with "somevalue".
- directories that contain shared and static libraries
+The PLIST_VARS variable can be used to simplify the common case of
+conditionally including some PLIST entries. It can be done by adding
+PLIST_VARS+=foo and setting the corresponding PLIST.foo variable to yes if the
+entry should be included. This will substitute "${PLIST.foo}" in the PLIST with
+either """" or ""@comment "". For example, in Makefile:
-INSTALL_DATA_DIR
+PLIST_VARS+= foo
+.if condition
+PLIST.foo= yes
+.else
- directories that contain data files
+And then in PLIST:
-INSTALL_MAN_DIR
+@comment $NetBSD $
+bin/bar
+man/man1/bar.1
+${PLIST.foo}bin/foo
+${PLIST.foo}man/man1/foo.1
+${PLIST.foo}share/bar/foo.data
- directories that contain man pages
+An artificial space has been added between NetBSD and $, this is a workaround
+here to prevent CVS expanding to the filename of the guide. When adding the RCS
+ID the space should be ommited.
-INSTALL_GAME_DIR
+19.5. Man page compression
- directories that contain data files for games
+Man pages should be installed in compressed form if MANZ is set (in
+bsd.own.mk), and uncompressed otherwise. To handle this in the PLIST file, the
+suffix ".gz" is appended/removed automatically for man pages according to MANZ
+and MANCOMPRESSED being set or not, see above for details. This modification of
+the PLIST file is done on a copy of it, not PLIST itself.
-INSTALL_PROGRAM
+19.6. Changing PLIST source with PLIST_SRC
- binaries that can be stripped from debugging symbols
+To use one or more files as source for the PLIST used in generating the binary
+package, set the variable PLIST_SRC to the names of that file(s). The files are
+later concatenated using cat(1), and the order of things is important. The
+default for PLIST_SRC is ${PKGDIR}/PLIST.
-INSTALL_SCRIPT
+19.7. Platform-specific and differing PLISTs
- binaries that cannot be stripped
+Some packages decide to install a different set of files based on the operating
+system being used. These differences can be automatically handled by using the
+following files:
-INSTALL_GAME
+ * PLIST.common
- game binaries
+ * PLIST.${OPSYS}
-INSTALL_LIB
+ * PLIST.${MACHINE_ARCH}
- shared and static libraries
+ * PLIST.${OPSYS}-${MACHINE_ARCH}
-INSTALL_DATA
+ * PLIST.common_end
- data files
+19.8. Build-specific PLISTs
-INSTALL_GAME_DATA
+Some packages decide to generate hard-to-guess file names during installation
+that are hard to wire down.
- data files for games
+In such cases, you can set the GENERATE_PLIST variable to shell code terminated
+(with a semicolon) that will output PLIST entries which will be appended to the
+PLIST
-INSTALL_MAN
+You can find one example in editors/xemacs:
- man pages
+GENERATE_PLIST+= ${ECHO} bin/${DISTNAME}-`${WRKSRC}/src/xemacs -sd`.dmp ;
-Some other variables are:
+which will append something like bin/xemacs-21.4.23-54e8ea71.dmp to the PLIST.
-INSTALL_UNSTRIPPED
+19.9. Sharing directories between packages
- If set to yes, do not run strip(1) when installing binaries. Any debugging
- sections and symbols present in binaries will be preserved.
+A "shared directory" is a directory where multiple (and unrelated) packages
+install files. These directories were problematic because you had to add
+special tricks in the PLIST to conditionally remove them, or have some
+centralized package handle them.
-INSTALLATION_DIRS
+In pkgsrc, it is now easy: Each package should create directories and install
+files as needed; pkg_delete will remove any directories left empty after
+uninstalling a package.
- A list of directories relative to PREFIX that are created by pkgsrc at the
- beginning of the install phase. The package is supposed to create all
- needed directories itself before installing files to it and list all other
- directories here.
+If a package needs an empty directory to work, create the directory during
+installation as usual, and also add an entry to the PLIST:
-In the rare cases that a package shouldn't install anything, set NO_INSTALL to
-"yes". This is mostly relevant for packages in the regress category.
+@pkgdir path/to/empty/directory
-19.15. The package phase
+or take a look at MAKE_DIRS and OWN_DIRS.
-Once the install stage has completed, a binary package of the installed files
-can be built. These binary packages can be used for quick installation without
-previous compilation, e.g. by the make bin-install or by using pkg_add.
+Chapter 20. The pkginstall framework
-By default, the binary packages are created in ${PACKAGES}/All and symlinks are
-created in ${PACKAGES}/category, one for each category in the CATEGORIES
-variable. PACKAGES defaults to pkgsrc/packages.
+Table of Contents
-19.16. Cleaning up
+20.1. Files and directories outside the installation prefix
-Once you're finished with a package, you can clean the work directory by
-running make clean. If you want to clean the work directories of all
-dependencies too, use make clean-depends.
+ 20.1.1. Directory manipulation
+ 20.1.2. File manipulation
-19.17. Other helpful targets
+20.2. Configuration files
-pre/post-*
+ 20.2.1. How PKG_SYSCONFDIR is set
+ 20.2.2. Telling the software where configuration files are
+ 20.2.3. Patching installations
+ 20.2.4. Disabling handling of configuration files
- For any of the main targets described in the previous section, two
- auxiliary targets exist with "pre-" and "post-" used as a prefix for the
- main target's name. These targets are invoked before and after the main
- target is called, allowing extra configuration or installation steps be
- performed from a package's Makefile, for example, which a program's
- configure script or install target omitted.
+20.3. System startup scripts
-do-*
+ 20.3.1. Disabling handling of system startup scripts
- Should one of the main targets do the wrong thing, and should there be no
- variable to fix this, you can redefine it with the do-* target. (Note that
- redefining the target itself instead of the do-* target is a bad idea, as
- the pre-* and post-* targets won't be called anymore, etc.) You will not
- usually need to do this.
+20.4. System users and groups
+20.5. System shells
-reinstall
+ 20.5.1. Disabling shell registration
- If you did a make install and you noticed some file was not installed
- properly, you can repeat the installation with this target, which will
- ignore the "already installed" flag.
+20.6. Fonts
- This is the default value of DEPENDS_TARGET except in the case of make
- update and make package, where the defaults are "package" and "update",
- respectively.
+ 20.6.1. Disabling automatic update of the fonts databases
-deinstall
+This chapter describes the framework known as pkginstall, whose key features
+are:
- This target does a pkg_delete(1) in the current directory, effectively
- de-installing the package. The following variables can be used to tune the
- behaviour:
+ * Generic installation and manipulation of directories and files outside the
+ pkgsrc-handled tree, LOCALBASE.
- PKG_VERBOSE
+ * Automatic handling of configuration files during installation, provided
+ that packages are correctly designed.
- Add a "-v" to the pkg_delete(1) command.
+ * Generation and installation of system startup scripts.
- DEINSTALLDEPENDS
+ * Registration of system users and groups.
- Remove all packages that require (depend on) the given package. This
- can be used to remove any packages that may have been pulled in by a
- given package, e.g. if make deinstall DEINSTALLDEPENDS=1 is done in
- pkgsrc/x11/kde, this is likely to remove whole KDE. Works by adding "-R
- " to the pkg_delete(1) command line.
+ * Registration of system shells.
-bin-install
+ * Automatic updating of fonts databases.
- Install a binary package from local disk and via FTP from a list of sites
- (see the BINPKG_SITES variable), and do a make package if no binary package
- is available anywhere. The arguments given to pkg_add can be set via
- BIN_INSTALL_FLAGS e.g., to do verbose operation, etc.
+The following sections inspect each of the above points in detail.
-install-clean
+You may be thinking that many of the things described here could be easily done
+with simple code in the package's post-installation target (post-install). This
+is incorrect, as the code in them is only executed when building from source.
+Machines using binary packages could not benefit from it at all (as the code
+itself could be unavailable). Therefore, the only way to achieve any of the
+items described above is by means of the installation scripts, which are
+automatically generated by pkginstall.
- This target removes the state files for the "install" and later phases so
- that the "install" target may be re-invoked. This can be used after editing
- the PLIST to install the package without rebuilding it.
+20.1. Files and directories outside the installation prefix
-build-clean
+As you already know, the PLIST file holds a list of files and directories that
+belong to a package. The names used in it are relative to the installation
+prefix (${PREFIX}), which means that it cannot register files outside this
+directory (absolute path names are not allowed). Despite this restriction, some
+packages need to install files outside this location; e.g., under ${VARBASE} or
+${PKG_SYSCONFDIR}. The only way to achieve this is to create such files during
+installation time by using installation scripts.
- This target removes the state files for the "build" and later phases so
- that the "build" target may be re-invoked.
+The generic installation scripts are shell scripts that can contain arbitrary
+code. The list of scripts to execute is taken from the INSTALL_FILE variable,
+which defaults to INSTALL. A similar variable exists for package removal
+(DEINSTALL_FILE, whose default is DEINSTALL). These scripts can run arbitrary
+commands, so they have the potential to create and manage files anywhere in the
+file system.
-update
+Using these general installation files is not recommended, but may be needed in
+some special cases. One reason for avoiding them is that the user has to trust
+the packager that there is no unwanted or simply erroneous code included in the
+installation script. Also, previously there were many similar scripts for the
+same functionality, and fixing a common error involved finding and changing all
+of them.
- This target causes the current package to be updated to the latest version.
- The package and all depending packages first get de-installed, then current
- versions of the corresponding packages get compiled and installed. This is
- similar to manually noting which packages are currently installed, then
- performing a series of make deinstall and make install (or whatever
- UPDATE_TARGET is set to) for these packages.
+The pkginstall framework offers another, standardized way. It provides generic
+scripts to abstract the manipulation of such files and directories based on
+variables set in the package's Makefile. The rest of this section describes
+these variables.
- You can use the "update" target to resume package updating in case a
- previous make update was interrupted for some reason. However, in this
- case, make sure you don't call make clean or otherwise remove the list of
- dependent packages in WRKDIR. Otherwise, you lose the ability to
- automatically update the current package along with the dependent packages
- you have installed.
+20.1.1. Directory manipulation
- Resuming an interrupted make update will only work as long as the package
- tree remains unchanged. If the source code for one of the packages to be
- updated has been changed, resuming make update will most certainly fail!
+The following variables can be set to request the creation of directories
+anywhere in the file system:
- The following variables can be used either on the command line or in
- mk.conf to alter the behaviour of make update:
+ * MAKE_DIRS and OWN_DIRS contain a list of directories that should be created
+ and should attempt to be destroyed by the installation scripts. The
+ difference between the two is that the latter prompts the administrator to
+ remove any directories that may be left after deinstallation (because they
+ were not empty), while the former does not. Example:
- UPDATE_TARGET
+ MAKE_DIRS+= ${VARBASE}/foo/private
- Install target to recursively use for the updated package and the
- dependent packages. Defaults to DEPENDS_TARGET if set, "install"
- otherwise for make update. Other good targets are "package" or "
- bin-install". Do not set this to "update" or you will get stuck in an
- endless loop!
+ * MAKE_DIRS_PERMS and OWN_DIRS_PERMS contain a list of tuples describing
+ which directories should be created and should attempt to be destroyed by
+ the installation scripts. Each tuple holds the following values, separated
+ by spaces: the directory name, its owner, its group and its numerical mode.
+ For example:
- NOCLEAN
+ MAKE_DIRS_PERMS+= ${VARBASE}/foo/private \
+ ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
- Don't clean up after updating. Useful if you want to leave the work
- sources of the updated packages around for inspection or other
- purposes. Be sure you eventually clean up the source tree (see the "
- clean-update" target below) or you may run into troubles with old
- source code still lying around on your next make or make update.
+ The difference between the two is exactly the same as their non-PERMS
+ counterparts.
- REINSTALL
+20.1.2. File manipulation
- Deinstall each package before installing (making DEPENDS_TARGET). This
- may be necessary if the "clean-update" target (see below) was called
- after interrupting a running make update.
+Creating non-empty files outside the installation prefix is tricky because the
+PLIST forces all files to be inside it. To overcome this problem, the only
+solution is to extract the file in the known place (i.e., inside the
+installation prefix) and copy it to the appropriate location during
+installation (done by the installation scripts generated by pkginstall). We
+will call the former the master file in the following paragraphs, which
+describe the variables that can be used to automatically and consistently
+handle files outside the installation prefix:
- DEPENDS_TARGET
+ * CONF_FILES and REQD_FILES are pairs of master and target files. During
+ installation time, the master file is copied to the target one if and only
+ if the latter does not exist. Upon deinstallation, the target file is
+ removed provided that it was not modified by the installation.
- Allows you to disable recursion and hardcode the target for packages.
- The default is "update" for the update target, facilitating a recursive
- update of prerequisite packages. Only set DEPENDS_TARGET if you want to
- disable recursive updates. Use UPDATE_TARGET instead to just set a
- specific target for each package to be installed during make update
- (see above).
+ The difference between the two is that the latter prompts the administrator
+ to remove any files that may be left after deinstallation (because they
+ were not empty), while the former does not.
-clean-update
+ * CONF_FILES_PERMS and REQD_FILES_PERMS contain tuples describing master
+ files as well as their target locations. For each of them, it also
+ specifies their owner, their group and their numeric permissions, in this
+ order. For example:
- Clean the source tree for all packages that would get updated if make
- update was called from the current directory. This target should not be
- used if the current package (or any of its depending packages) have already
- been de-installed (e.g., after calling make update) or you may lose some
- packages you intended to update. As a rule of thumb: only use this target
- before the first time you run make update and only if you have a dirty
- package tree (e.g., if you used NOCLEAN).
+ REQD_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile \
+ ${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
- If you are unsure about whether your tree is clean, you can either perform
- a make clean at the top of the tree, or use the following sequence of
- commands from the directory of the package you want to update (before
- running make update for the first time, otherwise you lose all the packages
- you wanted to update!):
+ The difference between the two is exactly the same as their non-PERMS
+ counterparts.
- # make clean-update
- # make clean CLEANDEPENDS=YES
- # make update
+20.2. Configuration files
+Configuration files are special in the sense that they are installed in their
+own specific directory, PKG_SYSCONFDIR, and need special treatment during
+installation (most of which is automated by pkginstall). The main concept you
+must bear in mind is that files marked as configuration files are automatically
+copied to the right place (somewhere inside PKG_SYSCONFDIR) during installation
+if and only if they didn't exist before. Similarly, they will not be removed if
+they have local modifications. This ensures that administrators never lose any
+custom changes they may have made.
- The following variables can be used either on the command line or in
- mk.conf to alter the behaviour of make clean-update:
+20.2.1. How PKG_SYSCONFDIR is set
- CLEAR_DIRLIST
+As said before, the PKG_SYSCONFDIR variable specifies where configuration files
+shall be installed. Its contents are set based upon the following variables:
- After make clean, do not reconstruct the list of directories to update
- for this package. Only use this if make update successfully installed
- all packages you wanted to update. Normally, this is done automatically
- on make update, but may have been suppressed by the NOCLEAN variable
- (see above).
+ * PKG_SYSCONFBASE: The configuration's root directory. Defaults to ${PREFIX}/
+ etc although it may be overridden by the user to point to his preferred
+ location (e.g., /etc, /etc/pkg, etc.). Packages must not use it directly.
-replace
+ * PKG_SYSCONFSUBDIR: A subdirectory of PKG_SYSCONFBASE under which the
+ configuration files for the package being built shall be installed. The
+ definition of this variable only makes sense in the package's Makefile
+ (i.e., it is not user-customizable).
- Update the installation of the current package. This differs from update in
- that it does not replace dependent packages. You will need to install
- pkgtools/pkg_tarup for this target to work.
+ As an example, consider the Apache package, www/apache24, which places its
+ configuration files under the httpd/ subdirectory of PKG_SYSCONFBASE. This
+ should be set in the package Makefile.
- Be careful when using this target! There are no guarantees that dependent
- packages will still work, in particular they will most certainly break if
- you make replace a library package whose shared library major version
- changed between your installed version and the new one. For this reason,
- this target is not officially supported and only recommended for advanced
- users.
+ * PKG_SYSCONFVAR: Specifies the name of the variable that holds this
+ package's configuration directory (if different from PKG_SYSCONFBASE). It
+ defaults to PKGBASE's value, and is always prefixed with PKG_SYSCONFDIR.
-info
+ * PKG_SYSCONFDIR.${PKG_SYSCONFVAR}: Holds the directory where the
+ configuration files for the package identified by PKG_SYSCONFVAR's shall be
+ placed.
- This target invokes pkg_info(1) for the current package. You can use this
- to check which version of a package is installed.
+Based on the above variables, pkginstall determines the value of
+PKG_SYSCONFDIR, which is the only variable that can be used within a package to
+refer to its configuration directory. The algorithm used to set its value is
+basically the following:
-index
+ 1. If PKG_SYSCONFDIR.${PKG_SYSCONFVAR} is set, its value is used.
- This is a top-level command, i.e. it should be used in the pkgsrc
- directory. It creates a database of all packages in the local pkgsrc tree,
- including dependencies, comment, maintainer, and some other useful
- information. Individual entries are created by running make describe in the
- packages' directories. This index file is saved as pkgsrc/INDEX. It can be
- displayed in verbose format by running make print-index. You can search in
- it with make search key=something. You can extract a list of all packages
- that depend on a particular one by running make show-deps PKG=somepackage.
+ 2. If the previous variable is not defined but PKG_SYSCONFSUBDIR is set in the
+ package's Makefile, the resulting value is ${PKG_SYSCONFBASE}/$
+ {PKG_SYSCONFSUBDIR}.
- Running this command takes a very long time, some hours even on fast
- machines!
+ 3. Otherwise, it is set to ${PKG_SYSCONFBASE}.
-readme
+It is worth mentioning that ${PKG_SYSCONFDIR} is automatically added to
+OWN_DIRS. See Section 20.1.1, "Directory manipulation" what this means. This
+does not apply to subdirectories of ${PKG_SYSCONFDIR}, they still have to be
+created with OWN_DIRS or MAKE_DIRS.
- This target generates a README.html file, which can be viewed using a
- browser such as www/firefox or www/links. The generated files contain
- references to any packages which are in the PACKAGES directory on the local
- host. The generated files can be made to refer to URLs based on
- FTP_PKG_URL_HOST and FTP_PKG_URL_DIR. For example, if I wanted to generate
- README.html files which pointed to binary packages on the local machine, in
- the directory /usr/packages, set FTP_PKG_URL_HOST=file://localhost and
- FTP_PKG_URL_DIR=/usr/packages. The ${PACKAGES} directory and its
- subdirectories will be searched for all the binary packages.
+20.2.2. Telling the software where configuration files are
- The target can be run at the toplevel or in category directories, in which
- case it descends recursively.
+Given that pkgsrc (and users!) expect configuration files to be in a known
+place, you need to teach each package where it shall install its files. In some
+cases you will have to patch the package Makefiles to achieve it. If you are
+lucky, though, it may be as easy as passing an extra flag to the configuration
+script; this is the case of GNU Autoconf- generated files:
-readme-all
+CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
- This is a top-level command, run it in pkgsrc. Use this target to create a
- file README-all.html which contains a list of all packages currently
- available in the NetBSD Packages Collection, together with the category
- they belong to and a short description. This file is compiled from the
- pkgsrc/*/README.html files, so be sure to run this after a make readme.
+Note that this specifies where the package has to look for its configuration
+files, not where they will be originally installed (although the difference is
+never explicit, unfortunately).
-cdrom-readme
+20.2.3. Patching installations
- This is very much the same as the "readme" target (see above), but is to be
- used when generating a pkgsrc tree to be written to a CD-ROM. This target
- also produces README.html files, and can be made to refer to URLs based on
- CDROM_PKG_URL_HOST and CDROM_PKG_URL_DIR.
+As said before, pkginstall automatically handles configuration files. This
+means that the packages themselves must not touch the contents of $
+{PKG_SYSCONFDIR} directly. Bad news is that many software installation scripts
+will, out of the box, mess with the contents of that directory. So what is the
+correct procedure to fix this issue?
-show-distfiles
+You must teach the package (usually by manually patching it) to install any
+configuration files under the examples hierarchy, share/examples/${PKGBASE}/.
+This way, the PLIST registers them and the administrator always has the
+original copies available.
- This target shows which distfiles and patchfiles are needed to build the
- package (ALLFILES, which contains all DISTFILES and PATCHFILES, but not
- patches/*).
+Once the required configuration files are in place (i.e., under the examples
+hierarchy), the pkginstall framework can use them as master copies during the
+package installation to update what is in ${PKG_SYSCONFDIR}. To achieve this,
+the variables CONF_FILES and CONF_FILES_PERMS are used. Check out
+Section 20.1.2, "File manipulation" for information about their syntax and
+their purpose. Here is an example, taken from the mail/mutt package:
-show-downlevel
+EGDIR= ${PREFIX}/share/doc/mutt/samples
+CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
- This target shows nothing if the package is not installed. If a version of
- this package is installed, but is not the version provided in this version
- of pkgsrc, then a warning message is displayed. This target can be used to
- show which of your installed packages are downlevel, and so the old
- versions can be deleted, and the current ones added.
+Note that the EGDIR variable is specific to that package and has no meaning
+outside it.
-show-pkgsrc-dir
+20.2.4. Disabling handling of configuration files
- This target shows the directory in the pkgsrc hierarchy from which the
- package can be built and installed. This may not be the same directory as
- the one from which the package was installed. This target is intended to be
- used by people who may wish to upgrade many packages on a single host, and
- can be invoked from the top-level pkgsrc Makefile by using the "
- show-host-specific-pkgs" target.
+The automatic copying of config files can be toggled by setting the environment
+variable PKG_CONFIG prior to package installation.
-show-installed-depends
+20.3. System startup scripts
- This target shows which installed packages match the current package's
- DEPENDS. Useful if out of date dependencies are causing build problems.
+System startup scripts are special files because they must be installed in a
+place known by the underlying OS, usually outside the installation prefix.
+Therefore, the same rules described in Section 20.1, "Files and directories
+outside the installation prefix" apply, and the same solutions can be used.
+However, pkginstall provides a special mechanism to handle these files.
-print-build-depends-list
+In order to provide system startup scripts, the package has to:
- This target shows the list of packages that the current package depends on
- for building.
+ 1. Store the script inside ${FILESDIR}, with the .sh suffix appended.
+ Considering the print/cups package as an example, it has a cupsd.sh in its
+ files directory.
-print-run-depends-list
+ 2. Tell pkginstall to handle it, appending the name of the script, without its
+ extension, to the RCD_SCRIPTS variable. Continuing the previous example:
- This target shows the list of packages that the current package depends on
- for running.
+ RCD_SCRIPTS+= cupsd
-check-shlibs
+Once this is done, pkginstall will do the following steps for each script in an
+automated fashion:
- After a package is installed, check all its binaries and (on ELF platforms)
- shared libraries to see if they find the shared libs they need. Run by
- default if PKG_DEVELOPER is set in mk.conf.
+ 1. Process the file found in the files directory applying all the
+ substitutions described in the FILES_SUBST variable.
-print-PLIST
+ 2. Copy the script from the files directory to the examples hierarchy, $
+ {PREFIX}/share/examples/rc.d/. Note that this master file must be
+ explicitly registered in the PLIST.
- After a "make install" from a new or upgraded pkg, this prints out an
- attempt to generate a new PLIST from a find -newer work/.extract_done. An
- attempt is made to care for shared libs etc., but it is strongly
- recommended to review the result before putting it into PLIST. On upgrades,
- it's useful to diff the output of this command against an already existing
- PLIST file.
+ 3. Add code to the installation scripts to copy the startup script from the
+ examples hierarchy into the system-wide startup scripts directory.
- If the package installs files via tar(1) or other methods that don't update
- file access times, be sure to add these files manually to your PLIST, as
- the "find -newer" command used by this target won't catch them!
+20.3.1. Disabling handling of system startup scripts
- See Section 15.3, "Tweaking output of make print-PLIST" for more
- information on this target.
+The automatic copying of config files can be toggled by setting the environment
+variable PKG_RCD_SCRIPTS prior to package installation. Note that the scripts
+will be always copied inside the examples hierarchy, ${PREFIX}/share/examples/
+rc.d/, no matter what the value of this variable is.
-Chapter 20. Tools needed for building or running
+20.4. System users and groups
-Table of Contents
+If a package needs to create special users and/or groups during installation,
+it can do so by using the pkginstall framework.
-20.1. Tools for pkgsrc builds
-20.2. Tools needed by packages
-20.3. Tools provided by platforms
+Users can be created by adding entries to the PKG_USERS variable. Each entry
+has the following syntax:
-The USE_TOOLS definition is used both internally by pkgsrc and also for
-individual packages to define what commands are needed for building a package
-(like TOOL_DEPENDS) or for later run-time of an installed packaged (such as
-DEPENDS). If the native system provides an adequate tool, then in many cases, a
-pkgsrc package will not be used.
+user:group
+
+Further specification of user details may be done by setting per-user
+variables. PKG_UID.user is the numeric UID for the user. PKG_GECOS.user is the
+user's description or comment. PKG_HOME.user is the user's home directory, and
+defaults to /nonexistent if not specified. PKG_SHELL.user is the user's shell,
+and defaults to /sbin/nologin if not specified.
-When building a package, the replacement tools are made available in a
-directory (as symlinks or wrapper scripts) that is early in the executable
-search path. Just like the buildlink system, this helps with consistent builds.
+Similarly, groups can be created by adding entries to the PKG_GROUPS variable,
+whose syntax is:
-A tool may be needed to help build a specific package. For example, perl, GNU
-make (gmake) or yacc may be needed.
+group
-Also a tool may be needed, for example, because the native system's supplied
-tool may be inefficient for building a package with pkgsrc. For example, a
-package may need GNU awk, bison (instead of yacc) or a better sed.
+The numeric GID of the group may be set by defining PKG_GID.group.
-The tools used by a package can be listed by running make show-tools.
+If a package needs to create the users and groups at an earlier stage, then it
+can set USERGROUP_PHASE to either configure,build, or pre-install to indicate
+the phase before which the users and groups are created. In this case, the
+numeric UIDs and GIDs of the created users and groups are automatically
+hardcoded into the final installation scripts.
-20.1. Tools for pkgsrc builds
+20.5. System shells
-The default set of tools used by pkgsrc is defined in bsd.pkg.mk. This includes
-standard Unix tools, such as: cat, awk, chmod, test, and so on. These can be
-seen by running: make show-var VARNAME=USE_TOOLS.
+Packages that install system shells should register them in the shell database,
+/etc/shells, to make things easier to the administrator. This must be done from
+the installation scripts to keep binary packages working on any system.
+pkginstall provides an easy way to accomplish this task.
-If a package needs a specific program to build then the USE_TOOLS variable can
-be used to define the tools needed.
+When a package provides a shell interpreter, it has to set the PKG_SHELL
+variable to its absolute file name. This will add some hooks to the
+installation scripts to handle it. Consider the following example, taken from
+shells/zsh:
-20.2. Tools needed by packages
+PKG_SHELL= ${PREFIX}/bin/zsh
-In the following examples, the :run means that it is needed at run-time (and
-becomes a DEPENDS). The default is a build dependency which can be set with
-:build. (So in this example, it is the same as gmake:build and
-pkg-config:build.)
+20.5.1. Disabling shell registration
-USE_TOOLS+= gmake perl:run pkg-config
+The automatic registration of shell interpreters can be disabled by the
+administrator by setting the PKG_REGISTER_SHELLS environment variable to NO.
-When using the tools framework, a TOOLS_PATH.foo variable is defined which
-contains the full path to the appropriate tool. For example, TOOLS_PATH.bash
-could be "/bin/bash" on Linux systems.
+20.6. Fonts
-If you always need a pkgsrc version of the tool at run-time, then just use
-DEPENDS instead.
+Packages that install X11 fonts should update the database files that index the
+fonts within each fonts directory. This can easily be accomplished within the
+pkginstall framework.
-20.3. Tools provided by platforms
+When a package installs X11 fonts, it must list the directories in which fonts
+are installed in the FONTS_DIRS.type variables, where type can be one of "ttf",
+"type1" or "x11". This will add hooks to the installation scripts to run the
+appropriate commands to update the fonts database files within each of those
+directories. For convenience, if the directory path is relative, it is taken to
+be relative to the package's installation prefix. Consider the following
+example, taken from fonts/dbz-ttf:
-When improving or porting pkgsrc to a new platform, have a look at (or create)
-the corresponding platform specific make file fragment under pkgsrc/mk/tools/
-tools.${OPSYS}.mk which defines the name of the common tools. For example:
+FONTS_DIRS.ttf= ${PREFIX}/share/fonts/X11/TTF
-.if exists(/usr/bin/bzcat)
-TOOLS_PLATFORM.bzcat?= /usr/bin/bzcat
-.elif exists(/usr/bin/bzip2)
-TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd
-.endif
+20.6.1. Disabling automatic update of the fonts databases
-TOOLS_PLATFORM.true?= true # shell builtin
+The automatic update of fonts databases can be disabled by the administrator by
+setting the PKG_UPDATE_FONTS_DB environment variable to NO.
Chapter 21. Making your package work
@@ -6184,13 +6206,13 @@ various ways of expressing this dependen
BUILD_DEPENDS, TOOL_DEPENDS, and TEST_DEPENDS definitions, the USE_TOOLS
definition, as well as dependencies via buildlink3.mk, which is the preferred
way to handle dependencies, and which uses the variables named above. See
-Chapter 16, Buildlink methodology for more information.
+Chapter 18, Buildlink methodology for more information.
The basic difference is that the DEPENDS definition registers that
pre-requisite in the binary package so it will be pulled in when the binary
package is later installed, whilst the BUILD_DEPENDS, TOOL_DEPENDS, and
TEST_DEPENDS definitions do not, marking a dependency that is only needed for
-building or testing the resulting package. See also Chapter 12, Creating a new
+building or testing the resulting package. See also Chapter 14, Creating a new
pkgsrc package from scratch for more information.
This means that if you only need a package present whilst you are building or
@@ -6880,7 +6902,7 @@ NO in the package Makefile.
Compilers for the C, C++, and Fortran languages comes with the NetBSD base
system. By default, pkgsrc assumes that a package is written in C and will hide
-all other compilers (via the wrapper framework, see Chapter 16, Buildlink
+all other compilers (via the wrapper framework, see Chapter 18, Buildlink
methodology).
To declare which language's compiler a package needs, set the USE_LANGUAGES
@@ -7385,7 +7407,7 @@ Packages that use GNU_CONFIGURE but do n
CONFIGURE_HAS_MANDIR to "no". Or if the ./configure script uses a non-standard
use of --mandir, you can set GNU_CONFIGURE_MANDIR as needed.
-See Section 15.5, "Man page compression" for information on installation of
+See Section 19.5, "Man page compression" for information on installation of
compressed manual pages.
21.6.9. Packages installing GConf data files
@@ -7614,87 +7636,255 @@ be shown this message, and the build wil
BROKEN packages are removed from pkgsrc in irregular intervals.
-Chapter 22. Debugging
+Chapter 22. GNOME packaging and porting
+
+Table of Contents
+
+22.1. Meta packages
+22.2. Packaging a GNOME application
+22.3. Updating GNOME to a newer version
+22.4. Patching guidelines
+
+Quoting GNOME's web site:
+
+ The GNOME project provides two things: The GNOME desktop environment, an
+ intuitive and attractive desktop for users, and the GNOME development
+ platform, an extensive framework for building applications that integrate
+ into the rest of the desktop.
+
+pkgsrc provides a seamless way to automatically build and install a complete
+GNOME environment under many different platforms. We can say with confidence
+that pkgsrc is one of the most advanced build and packaging systems for GNOME
+due to its included technologies buildlink3, the wrappers and tools framework
+and automatic configuration file management. Lots of efforts are put into
+achieving a completely clean deinstallation of installed software components.
+
+Given that pkgsrc is NetBSD's official packaging system, the above also means
+that great efforts are put into making GNOME work under this operating system.
+Recently, DragonFly BSD also adopted pkgsrc as its preferred packaging system,
+contributing lots of portability fixes to make GNOME build and install under
+it.
+
+This chapter is aimed at pkgsrc developers and other people interested in
+helping our GNOME porting and packaging efforts. It provides instructions on
+how to manage the existing packages and some important information regarding
+their internals.
+
+We need your help!
+
+Should you have some spare cycles to devote to NetBSD, pkgsrc and GNOME and are
+willing to learn new exciting stuff, please jump straight to the pending work
+list! There is still a long way to go to get a fully-functional GNOME desktop
+under NetBSD and we need your help to achieve it!
+
+22.1. Meta packages
+
+pkgsrc includes three GNOME-related meta packages:
+
+ * meta-pkgs/gnome-base: Provides the core GNOME desktop environment. It only
+ includes the necessary bits to get it to boot correctly, although it may
+ lack important functionality for daily operation. The idea behind this
+ package is to let end users build their own configurations on top of this
+ one, first installing this meta package to achieve a functional setup and
+ then adding individual applications.
+
+ * meta-pkgs/gnome: Provides a complete installation of the GNOME platform and
+ desktop as defined by the GNOME project; this is based on the components
+ distributed in the platform/x.y/x.y.z/sources and desktop/x.y/x.y.z/sources
+ directories of the official FTP server. Developer-only tools found in those
+ directories are not installed unless required by some other component to
+ work properly. Similarly, packages from the bindings set (bindings/x.y/
+ x.y.z/sources) are not pulled in unless required as a dependency for an
+ end-user component. This package "extends" meta-pkgs/gnome-base.
+
+ * meta-pkgs/gnome-devel: Installs all the tools required to build a GNOME
+ component when fetched from the CVS repository. These are required to let
+ the autogen.sh scripts work appropriately.
+
+In all these packages, the DEPENDS lines are sorted in a way that eases
+updates: a package may depend on other packages listed before it but not on any
+listed after it. It is very important to keep this order to ease updates so...
+do not change it to alphabetical sorting!
+
+22.2. Packaging a GNOME application
+
+Almost all GNOME applications are written in C and use a common set of tools as
+their build system. Things get different with the new bindings to other
+languages (such as Python), but the following will give you a general idea on
+the minimum required tools:
+
+ * Almost all GNOME applications use the GNU Autotools as their build system.
+ As a general rule you will need to tell this to your package:
+
+ GNU_CONFIGURE=yes
+ USE_LIBTOOL=yes
+ USE_TOOLS+=gmake
+
+ * If the package uses pkg-config to detect dependencies, add this tool to the
+ list of required utilities:
+
+ USE_TOOLS+=pkg-config
+
+ Also use pkgtools/verifypc at the end of the build process to ensure that
+ you did not miss to specify any dependency in your package and that the
+ version requirements are all correct.
+
+ * If the package uses intltool, be sure to add intltool to the USE_TOOLS to
+ handle dependencies and to force the package to use the latest available
+ version.
+
+ * If the package uses gtk-doc (a documentation generation utility), do not
+ add a dependency on it. The tool is rather big and the distfile should come
+ with pregenerated documentation anyway; if it does not, it is a bug that
+ you ought to report. For such packages you should disable gtk-doc (unless
+ it is the default):
+
+ CONFIGURE_ARGS+=--disable-gtk-doc
+
+ The default location of installed HTML files (share/gtk-doc/<package-name>)
+ is correct and should not be changed unless the package insists on
+ installing them somewhere else. Otherwise programs as devhelp will not be
+ able to open them. You can do that with an entry similar to:
-To check out all the gotchas when building a package, here are the steps that I
-do in order to get a package working. Please note this is basically the same as
-what was explained in the previous sections, only with some debugging aids.
+ CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...
- * Be sure to set PKG_DEVELOPER=yes in mk.conf.
+GNOME uses multiple shared directories and files under the installation prefix
+to maintain databases. In this context, shared means that those exact same
+directories and files are used among several different packages, leading to
+conflicts in the PLIST. pkgsrc currently includes functionality to handle the
+most common cases, so you have to forget about using @unexec ${RMDIR} lines in
+your file lists and omitting shared files from them. If you find yourself doing
+those, your package is most likely incorrect.
- * Install pkgtools/url2pkg, create a directory for a new package, change into
- it, then run url2pkg:
+The following table lists the common situations that result in using shared
+directories or files. For each of them, the appropriate solution is given.
+After applying the solution be sure to regenerate the package's file list with
+make print-PLIST and ensure it is correct.
- % mkdir /usr/pkgsrc/category/examplepkg
- % cd /usr/pkgsrc/category/examplepkg
- % url2pkg https://www.example.com/path/to/distfile.tar.gz
+Table 22.1. PLIST handling for GNOME packages
- * Edit the Makefile as requested.
++-----------------------------------------------------------------------------+
+| If the package... | Then... |
+|-------------------------------------------+---------------------------------|
+| |See Section 21.6.10, "Packages |
+|Installs OMF files under share/omf. |installing scrollkeeper/rarian |
+| |data files". |
+|-------------------------------------------+---------------------------------|
+|Installs icons under the share/icons/ |See Section 21.6.19, "Packages |
+|hicolor hierarchy or updates share/icons/ |installing hicolor theme icons". |
+|hicolor/icon-theme.cache. | |
+|-------------------------------------------+---------------------------------|
+| |See Section 21.6.14, "Packages |
+|Installs files under share/mime/packages. |installing extensions to the MIME|
+| |database". |
+|-------------------------------------------+---------------------------------|
+|Installs .desktop files under share/ |See Section 21.6.20, "Packages |
+|applications and these include MIME |installing desktop files". |
+|information. | |
++-----------------------------------------------------------------------------+
- * Fill in the DESCR file
- * Run make configure
+22.3. Updating GNOME to a newer version
- * Add any dependencies glimpsed from documentation and the configure step to
- the package's Makefile.
+When seeing GNOME as a whole, there are two kinds of updates:
- * Make the package compile, doing multiple rounds of
+Major update
- % make
- % pkgvi ${WRKSRC}/some/file/that/does/not/compile
- % mkpatches
- % patchdiff
- % mv ${WRKDIR}/.newpatches/* patches
- % make mps
- % make clean
+ Given that there is still a very long way for GNOME 3 (if it ever appears),
+ we consider a major update one that goes from a 2.X version to a 2.Y one,
+ where Y is even and greater than X. These are hard to achieve because they
+ introduce lots of changes in the components' code and almost all GNOME
+ distfiles are updated to newer versions. Some of them can even break API
+ and ABI compatibility with the previous major version series. As a result,
+ the update needs to be done all at once to minimize breakage.
- Doing this step as non-root user will ensure that no files are modified
- that shouldn't be, especially during the build phase. mkpatches, patchdiff
- and pkgvi are from the pkgtools/pkgdiff package.
+ A major update typically consists of around 80 package updates and the
+ addition of some new ones.
- * Look at the Makefile, fix if necessary; see Section 13.1, "Makefile".
+Minor update
- * Generate a PLIST:
+ We consider a minor update one that goes from a 2.A.X version to a 2.A.Y
+ one where Y is greater than X. These are easy to achieve because they do
+ not update all GNOME components, can be done in an incremental way and do
+ not break API nor ABI compatibility.
- # make install
- # make print-PLIST >PLIST
- # make deinstall
- # make install
- # make deinstall
+ A minor update typically consists of around 50 package updates, although
+ the numbers here may vary a lot.
- You usually need to be root to do this. Look if there are any files left:
+In order to update the GNOME components in pkgsrc to a new stable release
+(either major or minor), the following steps should be followed:
- # make print-PLIST
+ 1. Get a list of all the tarballs that form the new release by using the
+ following commands. These will leave the full list of the components'
+ distfiles into the list.txt file:
- If this reveals any files that are missing in PLIST, add them.
+ % echo ls "*.tar.bz2" | \
+ ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
+ awk '{ print $9 }' >list.txt
+ % echo ls "*.tar.bz2" | \
+ ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
+ awk '{ print $9 }' >>list.txt
- * Now that the PLIST is OK, install the package again and make a binary
- package:
+ 2. Open each meta package's Makefile and bump their version to the release you
+ are updating them to. The three meta packages should be always consistent
+ with versioning. Obviously remove any PKGREVISIONs that might be in them.
- # make reinstall
- # make package
+ 3. For each meta package, update all its DEPENDS lines to match the latest
+ versions as shown by the above commands. Do not list any newer version
+ (even if found in the FTP) because the meta packages are supposed to list
+ the exact versions that form a specific GNOME release. Exceptions are
+ permitted here if a newer version solves a serious issue in the overall
+ desktop experience; these typically come in the form of a revision bump in
+ pkgsrc, not in newer versions from the developers.
- * Delete the installed package:
+ Packages not listed in the list.txt file should be updated to the latest
+ version available (if found in pkgsrc). This is the case, for example, of
+ the dependencies on the GNU Autotools in the meta-pkgs/gnome-devel meta
+ package.
- # pkg_delete examplepkg
+ 4. Generate a patch from the modified meta packages and extract the list of
+ "new" lines. This will provide you an outline on what packages need to be
+ updated in pkgsrc and in what order:
- * Repeat the above make print-PLIST command, which shouldn't find anything
- now:
+ % cvs diff -u gnome-devel gnome-base gnome | grep '^+D' >todo.txt
- # make print-PLIST
+ 5. For major desktop updates it is recommended to zap all your installed
+ packages and start over from scratch at this point.
- * Reinstall the binary package:
+ 6. Now comes the longest step by far: iterate over the contents of todo.txt
+ and update the packages listed in it in order. For major desktop updates
+ none of these should be committed until the entire set is completed because
+ there are chances of breaking not-yet-updated packages.
- # pkg_add .../examplepkg.tgz
+ 7. Once the packages are up to date and working, commit them to the tree one
+ by one with appropriate log messages. At the end, commit the three meta
+ package updates and all the corresponding changes to the doc/CHANGES-<YEAR>
+ and pkgsrc/doc/TODO files.
- * Play with it. Make sure everything works.
+22.4. Patching guidelines
- * Run pkglint from pkgtools/pkglint, and fix the problems it reports:
+GNOME is a very big component in pkgsrc which approaches 100 packages. Please,
+it is very important that you always, always, always feed back any portability
+fixes you do to a GNOME package to the mainstream developers (see
+Section 12.3.5, "Feedback to the author"). This is the only way to get their
+attention on portability issues and to ensure that future versions can be built
+out-of-the box on NetBSD. The less custom patches in pkgsrc, the easier further
+updates are. Those developers in charge of issuing major GNOME updates will be
+grateful if you do that.
- # pkglint
+The most common places to report bugs are the GNOME's Bugzilla and the
+freedesktop.org's Bugzilla. Not all components use these to track bugs, but
+most of them do. Do not be short on your reports: always provide detailed
+explanations of the current failure, how it can be improved to achieve maximum
+portability and, if at all possible, provide a patch against CVS head. The more
+verbose you are, the higher chances of your patch being accepted.
- * Submit (or commit, if you have cvs access); see Chapter 23, Submitting and
- Committing.
+Also, please avoid using preprocessor magic to fix portability issues. While
+the FreeBSD GNOME people are doing a great job in porting GNOME to their
+operating system, the official GNOME sources are now plagued by conditionals
+that check for __FreeBSD__ and similar macros. This hurts portability. Please
+see our patching guidelines (Section 12.3.4, "Patching guidelines") for more
+details.
Chapter 23. Submitting and Committing
@@ -7721,13 +7911,14 @@ Creating binary packages for everything
23.2. Submitting source packages (for non-NetBSD-developers)
First, check that your package is complete, compiles and runs well; see
-Chapter 22, Debugging and the rest of this document. Next, generate an
-uuencoded gzipped tar(1) archive that contains all files that make up the
-package. Finally, send this package to the pkgsrc bug tracking system, either
-with the send-pr(1) command, or if you don't have that, go to the web page
-https://www.NetBSD.org/support/send-pr.html, which contains some instructions
-and a link to a form where you can submit packages. The sysutils/gtk-send-pr
-package is also available as a substitute for either of the above two tools.
+Chapter 14, Creating a new pkgsrc package from scratch and the rest of this
+document. Next, generate an uuencoded gzipped tar(1) archive that contains all
+files that make up the package. Finally, send this package to the pkgsrc bug
+tracking system, either with the send-pr(1) command, or if you don't have that,
+go to the web page https://www.NetBSD.org/support/send-pr.html, which contains
+some instructions and a link to a form where you can submit packages. The
+sysutils/gtk-send-pr package is also available as a substitute for either of
+the above two tools.
In the form of the problem report, the category should be "pkg", the synopsis
should include the package name and version number, and the description field
@@ -8052,256 +8243,6 @@ pkgsrc-users mailing list.
* Review packages for which review was requested on the tech-pkg
mailing list.
-Chapter 25. GNOME packaging and porting
-
-Table of Contents
-
-25.1. Meta packages
-25.2. Packaging a GNOME application
-25.3. Updating GNOME to a newer version
-25.4. Patching guidelines
-
-Quoting GNOME's web site:
-
- The GNOME project provides two things: The GNOME desktop environment, an
- intuitive and attractive desktop for users, and the GNOME development
- platform, an extensive framework for building applications that integrate
- into the rest of the desktop.
-
-pkgsrc provides a seamless way to automatically build and install a complete
-GNOME environment under many different platforms. We can say with confidence
-that pkgsrc is one of the most advanced build and packaging systems for GNOME
-due to its included technologies buildlink3, the wrappers and tools framework
-and automatic configuration file management. Lots of efforts are put into
-achieving a completely clean deinstallation of installed software components.
-
-Given that pkgsrc is NetBSD's official packaging system, the above also means
-that great efforts are put into making GNOME work under this operating system.
-Recently, DragonFly BSD also adopted pkgsrc as its preferred packaging system,
-contributing lots of portability fixes to make GNOME build and install under
-it.
-
-This chapter is aimed at pkgsrc developers and other people interested in
-helping our GNOME porting and packaging efforts. It provides instructions on
-how to manage the existing packages and some important information regarding
-their internals.
-
-We need your help!
-
-Should you have some spare cycles to devote to NetBSD, pkgsrc and GNOME and are
-willing to learn new exciting stuff, please jump straight to the pending work
-list! There is still a long way to go to get a fully-functional GNOME desktop
-under NetBSD and we need your help to achieve it!
-
-25.1. Meta packages
-
-pkgsrc includes three GNOME-related meta packages:
-
- * meta-pkgs/gnome-base: Provides the core GNOME desktop environment. It only
- includes the necessary bits to get it to boot correctly, although it may
- lack important functionality for daily operation. The idea behind this
- package is to let end users build their own configurations on top of this
- one, first installing this meta package to achieve a functional setup and
- then adding individual applications.
-
- * meta-pkgs/gnome: Provides a complete installation of the GNOME platform and
- desktop as defined by the GNOME project; this is based on the components
- distributed in the platform/x.y/x.y.z/sources and desktop/x.y/x.y.z/sources
- directories of the official FTP server. Developer-only tools found in those
- directories are not installed unless required by some other component to
- work properly. Similarly, packages from the bindings set (bindings/x.y/
- x.y.z/sources) are not pulled in unless required as a dependency for an
- end-user component. This package "extends" meta-pkgs/gnome-base.
-
- * meta-pkgs/gnome-devel: Installs all the tools required to build a GNOME
- component when fetched from the CVS repository. These are required to let
- the autogen.sh scripts work appropriately.
-
-In all these packages, the DEPENDS lines are sorted in a way that eases
-updates: a package may depend on other packages listed before it but not on any
-listed after it. It is very important to keep this order to ease updates so...
-do not change it to alphabetical sorting!
-
-25.2. Packaging a GNOME application
-
-Almost all GNOME applications are written in C and use a common set of tools as
-their build system. Things get different with the new bindings to other
-languages (such as Python), but the following will give you a general idea on
-the minimum required tools:
-
- * Almost all GNOME applications use the GNU Autotools as their build system.
- As a general rule you will need to tell this to your package:
-
- GNU_CONFIGURE=yes
- USE_LIBTOOL=yes
- USE_TOOLS+=gmake
-
- * If the package uses pkg-config to detect dependencies, add this tool to the
- list of required utilities:
-
- USE_TOOLS+=pkg-config
-
- Also use pkgtools/verifypc at the end of the build process to ensure that
- you did not miss to specify any dependency in your package and that the
- version requirements are all correct.
-
- * If the package uses intltool, be sure to add intltool to the USE_TOOLS to
- handle dependencies and to force the package to use the latest available
- version.
-
- * If the package uses gtk-doc (a documentation generation utility), do not
- add a dependency on it. The tool is rather big and the distfile should come
- with pregenerated documentation anyway; if it does not, it is a bug that
- you ought to report. For such packages you should disable gtk-doc (unless
- it is the default):
-
- CONFIGURE_ARGS+=--disable-gtk-doc
-
- The default location of installed HTML files (share/gtk-doc/<package-name>)
- is correct and should not be changed unless the package insists on
- installing them somewhere else. Otherwise programs as devhelp will not be
- able to open them. You can do that with an entry similar to:
-
- CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...
-
-GNOME uses multiple shared directories and files under the installation prefix
-to maintain databases. In this context, shared means that those exact same
-directories and files are used among several different packages, leading to
-conflicts in the PLIST. pkgsrc currently includes functionality to handle the
-most common cases, so you have to forget about using @unexec ${RMDIR} lines in
-your file lists and omitting shared files from them. If you find yourself doing
-those, your package is most likely incorrect.
-
-The following table lists the common situations that result in using shared
-directories or files. For each of them, the appropriate solution is given.
-After applying the solution be sure to regenerate the package's file list with
-make print-PLIST and ensure it is correct.
-
-Table 25.1. PLIST handling for GNOME packages
-
-+-----------------------------------------------------------------------------+
-| If the package... | Then... |
-|-------------------------------------------+---------------------------------|
-| |See Section 21.6.10, "Packages |
-|Installs OMF files under share/omf. |installing scrollkeeper/rarian |
-| |data files". |
-|-------------------------------------------+---------------------------------|
-|Installs icons under the share/icons/ |See Section 21.6.19, "Packages |
-|hicolor hierarchy or updates share/icons/ |installing hicolor theme icons". |
-|hicolor/icon-theme.cache. | |
-|-------------------------------------------+---------------------------------|
-| |See Section 21.6.14, "Packages |
-|Installs files under share/mime/packages. |installing extensions to the MIME|
-| |database". |
-|-------------------------------------------+---------------------------------|
-|Installs .desktop files under share/ |See Section 21.6.20, "Packages |
-|applications and these include MIME |installing desktop files". |
-|information. | |
-+-----------------------------------------------------------------------------+
-
-
-25.3. Updating GNOME to a newer version
-
-When seeing GNOME as a whole, there are two kinds of updates:
-
-Major update
-
- Given that there is still a very long way for GNOME 3 (if it ever appears),
- we consider a major update one that goes from a 2.X version to a 2.Y one,
- where Y is even and greater than X. These are hard to achieve because they
- introduce lots of changes in the components' code and almost all GNOME
- distfiles are updated to newer versions. Some of them can even break API
- and ABI compatibility with the previous major version series. As a result,
- the update needs to be done all at once to minimize breakage.
-
- A major update typically consists of around 80 package updates and the
- addition of some new ones.
-
-Minor update
-
- We consider a minor update one that goes from a 2.A.X version to a 2.A.Y
- one where Y is greater than X. These are easy to achieve because they do
- not update all GNOME components, can be done in an incremental way and do
- not break API nor ABI compatibility.
-
- A minor update typically consists of around 50 package updates, although
- the numbers here may vary a lot.
-
-In order to update the GNOME components in pkgsrc to a new stable release
-(either major or minor), the following steps should be followed:
-
- 1. Get a list of all the tarballs that form the new release by using the
- following commands. These will leave the full list of the components'
- distfiles into the list.txt file:
-
- % echo ls "*.tar.bz2" | \
- ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
- awk '{ print $9 }' >list.txt
- % echo ls "*.tar.bz2" | \
- ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
- awk '{ print $9 }' >>list.txt
-
- 2. Open each meta package's Makefile and bump their version to the release you
- are updating them to. The three meta packages should be always consistent
- with versioning. Obviously remove any PKGREVISIONs that might be in them.
-
- 3. For each meta package, update all its DEPENDS lines to match the latest
- versions as shown by the above commands. Do not list any newer version
- (even if found in the FTP) because the meta packages are supposed to list
- the exact versions that form a specific GNOME release. Exceptions are
- permitted here if a newer version solves a serious issue in the overall
- desktop experience; these typically come in the form of a revision bump in
- pkgsrc, not in newer versions from the developers.
-
- Packages not listed in the list.txt file should be updated to the latest
- version available (if found in pkgsrc). This is the case, for example, of
- the dependencies on the GNU Autotools in the meta-pkgs/gnome-devel meta
- package.
-
- 4. Generate a patch from the modified meta packages and extract the list of
- "new" lines. This will provide you an outline on what packages need to be
- updated in pkgsrc and in what order:
-
- % cvs diff -u gnome-devel gnome-base gnome | grep '^+D' >todo.txt
-
- 5. For major desktop updates it is recommended to zap all your installed
- packages and start over from scratch at this point.
-
- 6. Now comes the longest step by far: iterate over the contents of todo.txt
- and update the packages listed in it in order. For major desktop updates
- none of these should be committed until the entire set is completed because
- there are chances of breaking not-yet-updated packages.
-
- 7. Once the packages are up to date and working, commit them to the tree one
- by one with appropriate log messages. At the end, commit the three meta
- package updates and all the corresponding changes to the doc/CHANGES-<YEAR>
- and pkgsrc/doc/TODO files.
-
-25.4. Patching guidelines
-
-GNOME is a very big component in pkgsrc which approaches 100 packages. Please,
-it is very important that you always, always, always feed back any portability
-fixes you do to a GNOME package to the mainstream developers (see
-Section 13.3.5, "Feedback to the author"). This is the only way to get their
-attention on portability issues and to ensure that future versions can be built
-out-of-the box on NetBSD. The less custom patches in pkgsrc, the easier further
-updates are. Those developers in charge of issuing major GNOME updates will be
-grateful if you do that.
-
-The most common places to report bugs are the GNOME's Bugzilla and the
-freedesktop.org's Bugzilla. Not all components use these to track bugs, but
-most of them do. Do not be short on your reports: always provide detailed
-explanations of the current failure, how it can be improved to achieve maximum
-portability and, if at all possible, provide a patch against CVS head. The more
-verbose you are, the higher chances of your patch being accepted.
-
-Also, please avoid using preprocessor magic to fix portability issues. While
-the FreeBSD GNOME people are doing a great job in porting GNOME to their
-operating system, the official GNOME sources are now plagued by conditionals
-that check for __FreeBSD__ and similar macros. This hurts portability. Please
-see our patching guidelines (Section 13.3.4, "Patching guidelines") for more
-details.
-
Part III. The pkgsrc infrastructure internals
This part of the guide deals with everything from the infrastructure that is
@@ -8310,65 +8251,65 @@ maintainer should not need anything from
Table of Contents
-26. Design of the pkgsrc infrastructure
+25. Design of the pkgsrc infrastructure
- 26.1. The meaning of variable definitions
- 26.2. Avoiding problems before they arise
- 26.3. Variable evaluation
+ 25.1. The meaning of variable definitions
+ 25.2. Avoiding problems before they arise
+ 25.3. Variable evaluation
- 26.3.1. At load time
- 26.3.2. At runtime
+ 25.3.1. At load time
+ 25.3.2. At runtime
- 26.4. How can variables be specified?
- 26.5. Designing interfaces for Makefile fragments
+ 25.4. How can variables be specified?
+ 25.5. Designing interfaces for Makefile fragments
- 26.5.1. Procedures with parameters
- 26.5.2. Actions taken on behalf of parameters
+ 25.5.1. Procedures with parameters
+ 25.5.2. Actions taken on behalf of parameters
- 26.6. The order in which files are loaded
+ 25.6. The order in which files are loaded
- 26.6.1. The order in bsd.prefs.mk
- 26.6.2. The order in bsd.pkg.mk
+ 25.6.1. The order in bsd.prefs.mk
+ 25.6.2. The order in bsd.pkg.mk
-27. Regression tests
+26. Regression tests
- 27.1. Running the regression tests
- 27.2. Adding a new regression test
+ 26.1. Running the regression tests
+ 26.2. Adding a new regression test
- 27.2.1. Overridable functions
- 27.2.2. Helper functions
+ 26.2.1. Overridable functions
+ 26.2.2. Helper functions
-28. Porting pkgsrc
+27. Porting pkgsrc
- 28.1. Porting pkgsrc to a new operating system
+ 27.1. Porting pkgsrc to a new operating system
-Chapter 26. Design of the pkgsrc infrastructure
+Chapter 25. Design of the pkgsrc infrastructure
Table of Contents
-26.1. The meaning of variable definitions
-26.2. Avoiding problems before they arise
-26.3. Variable evaluation
+25.1. The meaning of variable definitions
+25.2. Avoiding problems before they arise
+25.3. Variable evaluation
- 26.3.1. At load time
- 26.3.2. At runtime
+ 25.3.1. At load time
+ 25.3.2. At runtime
-26.4. How can variables be specified?
-26.5. Designing interfaces for Makefile fragments
+25.4. How can variables be specified?
+25.5. Designing interfaces for Makefile fragments
- 26.5.1. Procedures with parameters
- 26.5.2. Actions taken on behalf of parameters
+ 25.5.1. Procedures with parameters
+ 25.5.2. Actions taken on behalf of parameters
-26.6. The order in which files are loaded
+25.6. The order in which files are loaded
- 26.6.1. The order in bsd.prefs.mk
- 26.6.2. The order in bsd.pkg.mk
+ 25.6.1. The order in bsd.prefs.mk
+ 25.6.2. The order in bsd.pkg.mk
The pkgsrc infrastructure consists of many small Makefile fragments. Each such
fragment needs a properly specified interface. This chapter explains how such
an interface looks like.
-26.1. The meaning of variable definitions
+25.1. The meaning of variable definitions
Whenever a variable is defined in the pkgsrc infrastructure, the location and
the way of definition provide much information about the intended use of that
@@ -8395,7 +8336,7 @@ Note
These conventions are currently not applied consistently to the complete pkgsrc
infrastructure.
-26.2. Avoiding problems before they arise
+25.2. Avoiding problems before they arise
All variables that contain lists of things should default to being empty. Two
examples that do not follow this rule are USE_LANGUAGES and DISTFILES. These
@@ -8412,9 +8353,9 @@ package Makefiles. Similarly for USE_LAN
value ("c") is so short that it doesn't stand out. Nevertheless it is mentioned
in many files.
-26.3. Variable evaluation
+25.3. Variable evaluation
-26.3.1. At load time
+25.3.1. At load time
Variable evaluation takes place either at load time or at runtime, depending on
the context in which they occur. The contexts where variables are evaluated at
@@ -8449,26 +8390,26 @@ paragraph, the -Wall is appended to the
appear in CONFIGURE_ARGS. In actual code, the three paragraphs from above
typically occur in completely unrelated files.
-26.3.2. At runtime
+25.3.2. At runtime
After all the files have been loaded, the values of the variables cannot be
changed anymore. Variables that are used in the shell commands are expanded at
this point.
-26.4. How can variables be specified?
+25.4. How can variables be specified?
There are many ways in which the definition and use of a variable can be
restricted in order to detect bugs and violations of the (mostly unwritten)
policies. A package can be checked with pkglint -Wall to see whether it meets
these rules.
-26.5. Designing interfaces for Makefile fragments
+25.5. Designing interfaces for Makefile fragments
Most of the .mk files fall into one of the following classes. Cases where a
file falls into more than one class should be avoided as it often leads to
subtle bugs.
-26.5.1. Procedures with parameters
+25.5.1. Procedures with parameters
In a traditional imperative programming language some of the .mk files could be
described as procedures. They take some input parameters and?after
@@ -8496,7 +8437,7 @@ Examples for procedures are mk/bsd.optio
To express that the parameters are evaluated at load time, they should be
assigned using the := operator, which should be used only for this purpose.
-26.5.2. Actions taken on behalf of parameters
+25.5.2. Actions taken on behalf of parameters
Action files take some input parameters and may define runtime variables. They
shall not define loadtime variables. There are action files that are included
@@ -8505,7 +8446,7 @@ explicitly.
An example for action files is mk/subst.mk.
-26.6. The order in which files are loaded
+25.6. The order in which files are loaded
Package Makefiles usually consist of a set of variable definitions, and include
the file ../../mk/bsd.pkg.mk in the very last line. Before that, they may also
@@ -8517,7 +8458,7 @@ the files are loaded matters.
This section describes at which point the various files are loaded and gives
reasons for that order.
-26.6.1. The order in bsd.prefs.mk
+25.6.1. The order in bsd.prefs.mk
The very first action in bsd.prefs.mk is to define some essential variables
like OPSYS, OS_VERSION and MACHINE_ARCH.
@@ -8537,7 +8478,7 @@ As the last steps, some essential variab
system flavor are loaded, as well as the variables that have been cached in
earlier phases of a package build.
-26.6.2. The order in bsd.pkg.mk
+25.6.2. The order in bsd.pkg.mk
First, bsd.prefs.mk is loaded.
@@ -8564,15 +8505,15 @@ execution, though the actual order shoul
At last, some more files are included that don't set any interesting variables
but rather just define make targets to be executed.
-Chapter 27. Regression tests
+Chapter 26. Regression tests
Table of Contents
-27.1. Running the regression tests
-27.2. Adding a new regression test
+26.1. Running the regression tests
+26.2. Adding a new regression test
- 27.2.1. Overridable functions
- 27.2.2. Helper functions
+ 26.2.1. Overridable functions
+ 26.2.2. Helper functions
The pkgsrc infrastructure consists of a large codebase, and there are many
corners where every little bit of a file is well thought out, making pkgsrc
@@ -8581,20 +8522,20 @@ changes from breaking anything, a suite
with every important part of the pkgsrc infrastructure. This chapter describes
how regression tests work in pkgsrc and how you can add new tests.
-27.1. Running the regression tests
+26.1. Running the regression tests
You first need to install the pkgtools/pkg_regress package, which provides the
pkg_regress command. Then you can simply run that command, which will run all
tests in the regress/ directory.
-27.2. Adding a new regression test
+26.2. Adding a new regression test
Every directory in the regress/ directory that contains a file called spec is
considered a regression test. This file is a shell program that is included by
the pkg_regress command. The following functions can be overridden to suit your
needs.
-27.2.1. Overridable functions
+26.2.1. Overridable functions
These functions do not take any parameters. Although they are called in "set -e
" mode, they don't stop at the first failing command. See this Stack Overflow
@@ -8637,7 +8578,7 @@ do_cleanup
This function cleans everything up after the test has been run. By default
it does nothing.
-27.2.2. Helper functions
+26.2.2. Helper functions
regress_fail message...
@@ -8663,17 +8604,17 @@ output_prohibit regex...
() does not match the extended regular expression. If any of the regular
expressions matches, the test will fail.
-Chapter 28. Porting pkgsrc
+Chapter 27. Porting pkgsrc
Table of Contents
-28.1. Porting pkgsrc to a new operating system
+27.1. Porting pkgsrc to a new operating system
The pkgsrc system has already been ported to many operating systems, hardware
architectures and compilers. This chapter explains the necessary steps to make
pkgsrc even more portable.
-28.1. Porting pkgsrc to a new operating system
+27.1. Porting pkgsrc to a new operating system
To port pkgsrc to a new operating system (called MyOS in this example), you
need to touch the following files:
@@ -8783,7 +8724,7 @@ Create the directory where the package l
# cd bison
# mkdir patches
-Create Makefile, DESCR and PLIST (see Chapter 13, Package components - files,
+Create Makefile, DESCR and PLIST (see Chapter 12, Package components - files,
directories and contents) then continue with fetching the distfile:
# make fetch
Home |
Main Index |
Thread Index |
Old Index