diff options
| -rw-r--r-- | doc/pkgsrc.html | 110 | ||||
| -rw-r--r-- | doc/pkgsrc.txt | 95 |
2 files changed, 108 insertions, 97 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index ef1ee87169e..a5358b8cb2e 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -108,7 +108,7 @@ alink="#0000FF"> </dl> </dd> - <dt><span class="part"><a href="#users-guide">1. The pkgsrc + <dt><span class="part"><a href="#users-guide">I. The pkgsrc user's guide</a></span></dt> <dd> @@ -384,7 +384,7 @@ alink="#0000FF"> </dl> </dd> - <dt><span class="part"><a href="#developers-guide">2. The + <dt><span class="part"><a href="#developers-guide">II. The pkgsrc developer's guide</a></span></dt> <dd> @@ -909,63 +909,63 @@ alink="#0000FF"> </dl> </dd> - <dt><span class="appendix"><a href="#examples">1. A simple + <dt><span class="appendix"><a href="#examples">A. A simple example package: bison</a></span></dt> <dd> <dl> - <dt><span class="sect1"><a href="#example-files">1.1. + <dt><span class="sect1"><a href="#example-files">A.1. files</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#example-Makefile">1.1.1. Makefile</a></span></dt> + "#example-Makefile">A.1.1. Makefile</a></span></dt> <dt><span class="sect2"><a href= - "#example-descr">1.1.2. DESCR</a></span></dt> + "#example-descr">A.1.2. DESCR</a></span></dt> <dt><span class="sect2"><a href= - "#example-plist">1.1.3. PLIST</a></span></dt> + "#example-plist">A.1.3. PLIST</a></span></dt> <dt><span class="sect2"><a href= - "#checking-package-with-pkglint">1.1.4. Checking a + "#checking-package-with-pkglint">A.1.4. Checking a package with <span><strong class= "command">pkglint</strong></span></a></span></dt> </dl> </dd> - <dt><span class="sect1"><a href="#steps-for-b-i-p">1.2. + <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2. Steps for building, installing, packaging</a></span></dt> </dl> </dd> - <dt><span class="appendix"><a href="#logs">2. Build + <dt><span class="appendix"><a href="#logs">B. Build logs</a></span></dt> <dd> <dl> - <dt><span class="sect1"><a href="#logs.building">2.1. + <dt><span class="sect1"><a href="#logs.building">B.1. Building figlet</a></span></dt> - <dt><span class="sect1"><a href="#logs.package">2.2. + <dt><span class="sect1"><a href="#logs.package">B.2. Packaging figlet</a></span></dt> </dl> </dd> - <dt><span class="appendix"><a href="#ftp-layout">3. Layout + <dt><span class="appendix"><a href="#ftp-layout">C. Layout of the FTP server's package archive</a></span></dt> - <dt><span class="appendix"><a href="#editing">4. Editing + <dt><span class="appendix"><a href="#editing">D. Editing guidelines for the pkgsrc guide</a></span></dt> <dd> <dl> - <dt><span class="sect1"><a href="#targets">4.1. + <dt><span class="sect1"><a href="#targets">D.1. Targets</a></span></dt> - <dt><span class="sect1"><a href="#procedure">4.2. + <dt><span class="sect1"><a href="#procedure">D.2. Procedure</a></span></dt> </dl> </dd> @@ -1150,16 +1150,16 @@ alink="#0000FF"> <p>This document is divided into two parts. The first, <a href="#users-guide" title= - "Part 1. The pkgsrc user's guide">The pkgsrc + "Part I. The pkgsrc user's guide">The pkgsrc user's guide</a>, describes how one can use one of the packages in the Package Collection, either by installing a precompiled binary package, or by building one's own copy using the NetBSD package system. The second part, <a href= "#developers-guide" title= - "Part 2. The pkgsrc developer's guide">The pkgsrc - developer's guide</a>, explains how to prepare a package so - it can be easily built by other NetBSD users without - knowing about the package's building details.</p> + "Part II. The pkgsrc developer's guide">The + pkgsrc developer's guide</a>, explains how to prepare a + package so it can be easily built by other NetBSD users + without knowing about the package's building details.</p> <p>This document is available in various formats:</p> @@ -1310,8 +1310,7 @@ alink="#0000FF"> <div> <div> <h1 class="title"><a name="users-guide" id= - "users-guide"></a>Part 1. The pkgsrc user's - guide</h1> + "users-guide"></a>The pkgsrc user's guide</h1> </div> </div> </div> @@ -2869,7 +2868,7 @@ CFLAGS= -xtarget=ultra -xarch=v9 <p>This assumes that the package is already in pkgsrc. If it is not, see <a href="#developers-guide" title= - "Part 2. The pkgsrc developer's guide">Part 2, + "Part II. The pkgsrc developer's guide">Part II, “The pkgsrc developer's guide”</a> for instructions how to create your own packages.</p> @@ -2976,7 +2975,7 @@ CFLAGS= -xtarget=ultra -xarch=v9 <p>Taking the figlet utility as an example, we can install it on our system by building as shown in <a href="#logs" title= - "Appendix 2. Build logs">Appendix 2, <i>Build + "Appendix B. Build logs">Appendix B, <i>Build logs</i></a>.</p> <p>The program is installed under the default root of @@ -3676,7 +3675,7 @@ CFLAGS= -xtarget=ultra -xarch=v9 "http://www.w3.org/TR/xhtml1/transitional" class= "filename">/usr/pkgsrc/packages</code>, in the form of a gzipped tar file. See <a href="#logs.package" title= - "2.2. Packaging figlet">Section 2.2, + "B.2. Packaging figlet">Section B.2, “Packaging figlet”</a> for a continuation of the above <a xmlns= "http://www.w3.org/TR/xhtml1/transitional" href= @@ -5519,8 +5518,8 @@ SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c <div> <div> <h1 class="title"><a name="developers-guide" id= - "developers-guide"></a>Part 2. The pkgsrc - developer's guide</h1> + "developers-guide"></a>The pkgsrc developer's + guide</h1> </div> </div> </div> @@ -6512,6 +6511,13 @@ SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \ “<code xmlns="http://www.w3.org/TR/xhtml1/transitional" 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 enables removing the patch in + future version.</p> + <p>Patch files that are distributed by the author or other maintainers can be listed in <code class= "varname">$PATCHFILES</code>.</p> @@ -13689,7 +13695,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h2 class="title"><a name="examples" id= - "examples"></a>Appendix 1. A simple example + "examples"></a>Appendix A. A simple example package: bison</h2> </div> </div> @@ -13699,28 +13705,28 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <p><b>Table of Contents</b></p> <dl> - <dt><span class="sect1"><a href="#example-files">1.1. + <dt><span class="sect1"><a href="#example-files">A.1. files</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#example-Makefile">1.1.1. Makefile</a></span></dt> + "#example-Makefile">A.1.1. Makefile</a></span></dt> <dt><span class="sect2"><a href= - "#example-descr">1.1.2. DESCR</a></span></dt> + "#example-descr">A.1.2. DESCR</a></span></dt> <dt><span class="sect2"><a href= - "#example-plist">1.1.3. PLIST</a></span></dt> + "#example-plist">A.1.3. PLIST</a></span></dt> <dt><span class="sect2"><a href= - "#checking-package-with-pkglint">1.1.4. Checking a + "#checking-package-with-pkglint">A.1.4. Checking a package with <span><strong class= "command">pkglint</strong></span></a></span></dt> </dl> </dd> - <dt><span class="sect1"><a href="#steps-for-b-i-p">1.2. + <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2. Steps for building, installing, packaging</a></span></dt> </dl> </div> @@ -13739,7 +13745,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "example-files" id= - "example-files"></a>1.1. files</h2> + "example-files"></a>A.1. files</h2> </div> </div> </div> @@ -13749,7 +13755,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="example-Makefile" id= - "example-Makefile"></a>1.1.1. Makefile</h3> + "example-Makefile"></a>A.1.1. Makefile</h3> </div> </div> </div> @@ -13777,7 +13783,7 @@ INFO_FILES= bison.info <div> <div> <h3 class="title"><a name="example-descr" id= - "example-descr"></a>1.1.2. DESCR</h3> + "example-descr"></a>A.1.2. DESCR</h3> </div> </div> </div> @@ -13794,7 +13800,7 @@ of the NetBSD source tree is beyond me. <div> <div> <h3 class="title"><a name="example-plist" id= - "example-plist"></a>1.1.3. PLIST</h3> + "example-plist"></a>A.1.3. PLIST</h3> </div> </div> </div> @@ -13813,7 +13819,7 @@ share/bison.hairy <div> <h3 class="title"><a name= "checking-package-with-pkglint" id= - "checking-package-with-pkglint"></a>1.1.4. Checking + "checking-package-with-pkglint"></a>A.1.4. Checking a package with <span><strong class= "command">pkglint</strong></span></h3> </div> @@ -13849,7 +13855,7 @@ looks fine. <div> <h2 class="title" style="clear: both"><a name= "steps-for-b-i-p" id= - "steps-for-b-i-p"></a>1.2. Steps for building, + "steps-for-b-i-p"></a>A.2. Steps for building, installing, packaging</h2> </div> </div> @@ -14007,7 +14013,7 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz' <div> <div> <h2 class="title"><a name="logs" id= - "logs"></a>Appendix 2. Build logs</h2> + "logs"></a>Appendix B. Build logs</h2> </div> </div> </div> @@ -14016,10 +14022,10 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz' <p><b>Table of Contents</b></p> <dl> - <dt><span class="sect1"><a href="#logs.building">2.1. + <dt><span class="sect1"><a href="#logs.building">B.1. Building figlet</a></span></dt> - <dt><span class="sect1"><a href="#logs.package">2.2. + <dt><span class="sect1"><a href="#logs.package">B.2. Packaging figlet</a></span></dt> </dl> </div> @@ -14030,7 +14036,7 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz' <div> <h2 class="title" style="clear: both"><a name= "logs.building" id= - "logs.building"></a>2.1. Building figlet</h2> + "logs.building"></a>B.1. Building figlet</h2> </div> </div> </div> @@ -14134,7 +14140,7 @@ cp figlet.6 /usr/pkg/man/man6 <div> <h2 class="title" style="clear: both"><a name= "logs.package" id= - "logs.package"></a>2.2. Packaging figlet</h2> + "logs.package"></a>B.2. Packaging figlet</h2> </div> </div> </div> @@ -14157,7 +14163,7 @@ Registering depends:. <div> <div> <h2 class="title"><a name="ftp-layout" id= - "ftp-layout"></a>Appendix 3. Layout of the + "ftp-layout"></a>Appendix C. Layout of the FTP server's package archive</h2> </div> </div> @@ -14262,7 +14268,7 @@ Registering depends:. <div> <div> <h2 class="title"><a name="editing" id= - "editing"></a>Appendix 4. Editing guidelines + "editing"></a>Appendix D. Editing guidelines for the pkgsrc guide</h2> </div> </div> @@ -14272,10 +14278,10 @@ Registering depends:. <p><b>Table of Contents</b></p> <dl> - <dt><span class="sect1"><a href="#targets">4.1. + <dt><span class="sect1"><a href="#targets">D.1. Targets</a></span></dt> - <dt><span class="sect1"><a href="#procedure">4.2. + <dt><span class="sect1"><a href="#procedure">D.2. Procedure</a></span></dt> </dl> </div> @@ -14288,7 +14294,7 @@ Registering depends:. <div> <div> <h2 class="title" style="clear: both"><a name= - "targets" id="targets"></a>4.1. Targets</h2> + "targets" id="targets"></a>D.1. Targets</h2> </div> </div> </div> @@ -14346,7 +14352,7 @@ Registering depends:. <div> <h2 class="title" style="clear: both"><a name= "procedure" id= - "procedure"></a>4.2. Procedure</h2> + "procedure"></a>D.2. Procedure</h2> </div> </div> </div> diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index 952265fe509..18d979b9921 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -33,7 +33,7 @@ Table of Contents 1.3. Terminology 1.4. Typography -1. The pkgsrc user's guide +I. The pkgsrc user's guide 2. Where to get pkgsrc @@ -114,7 +114,7 @@ Table of Contents 7.14. How do I change the location of configuration files? 7.15. Automated security checks -2. The pkgsrc developer's guide +II. The pkgsrc developer's guide 8. Package components - files, directories and contents @@ -260,27 +260,27 @@ Table of Contents 17.4. Updating a package to a newer version 17.5. Moving a package in pkgsrc -1. A simple example package: bison +A. A simple example package: bison - 1.1. files + A.1. files - 1.1.1. Makefile - 1.1.2. DESCR - 1.1.3. PLIST - 1.1.4. Checking a package with pkglint + A.1.1. Makefile + A.1.2. DESCR + A.1.3. PLIST + A.1.4. Checking a package with pkglint - 1.2. Steps for building, installing, packaging + A.2. Steps for building, installing, packaging -2. Build logs +B. Build logs - 2.1. Building figlet - 2.2. Packaging figlet + B.1. Building figlet + B.2. Packaging figlet -3. Layout of the FTP server's package archive -4. Editing guidelines for the pkgsrc guide +C. Layout of the FTP server's package archive +D. Editing guidelines for the pkgsrc guide - 4.1. Targets - 4.2. Procedure + D.1. Targets + D.2. Procedure Chapter 1. Introduction @@ -417,7 +417,7 @@ command should/can be issued as root, or if "normal" user privileges are sufficient. We use a # for root's shell prompt, and a % for users' shell prompt, assuming they use the C-shell or tcsh. -Part 1. The pkgsrc user's guide +The pkgsrc user's guide Table of Contents @@ -1038,7 +1038,7 @@ your system by indiscriminate adding of such files. 4.2. Building packages from source -This assumes that the package is already in pkgsrc. If it is not, see Part 2, +This assumes that the package is already in pkgsrc. If it is not, see Part II, "The pkgsrc developer's guide" for instructions how to create your own packages. @@ -1085,7 +1085,7 @@ has a just-in-time-su feature, which allows you to only become root for the actual installation step Taking the figlet utility as an example, we can install it on our system by -building as shown in Appendix 2, Build logs. +building as shown in Appendix B, Build logs. The program is installed under the default root of the packages tree - /usr/ pkg. Should this not conform to your tastes, set the LOCALBASE variable in your @@ -1345,7 +1345,7 @@ and run make package: This will build and install your package (if not already done), and then build a binary package from what was installed. You can then use the pkg_* tools to manipulate it. Binary packages are created by default in /usr/pkgsrc/packages, -in the form of a gzipped tar file. See Section 2.2, "Packaging figlet" for a +in the form of a gzipped tar file. See Section B.2, "Packaging figlet" for a continuation of the above misc/figlet example. See Chapter 17, Submitting and Committing for information on how to submit such @@ -2024,7 +2024,7 @@ Use of the security/audit-packages package is strongly recommended! After "audit-packages" is installed, please read the package's message, which you can get by running pkg_info -D audit-package. -Part 2. The pkgsrc developer's guide +The pkgsrc developer's guide Table of Contents @@ -2380,6 +2380,11 @@ When you have finished a package, remember to generate the checksums for the patch files by using the make makepatchsum command, see Section 8.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 +report to the maintainer. This benefits non-pkgsrc users of the package, and +usually enables removing the patch in future version. + Patch files that are distributed by the author or other maintainers can be listed in $PATCHFILES. @@ -5268,27 +5273,27 @@ possibly untested features. (and any packages from step 5, of course). -Appendix 1. A simple example package: bison +Appendix A. A simple example package: bison Table of Contents -1.1. files +A.1. files - 1.1.1. Makefile - 1.1.2. DESCR - 1.1.3. PLIST - 1.1.4. Checking a package with pkglint + A.1.1. Makefile + A.1.2. DESCR + A.1.3. PLIST + A.1.4. Checking a package with pkglint -1.2. Steps for building, installing, packaging +A.2. Steps for building, installing, packaging We checked to find a piece of software that wasn't in the packages collection, and picked GNU bison. Quite why someone would want to have bison when Berkeley yacc is already present in the tree is beyond us, but it's useful for the purposes of this exercise. -1.1. files +A.1. files -1.1.1. Makefile +A.1.1. Makefile # $NetBSD$ # @@ -5306,13 +5311,13 @@ INFO_FILES= bison.info .include "../../mk/bsd.pkg.mk" -1.1.2. DESCR +A.1.2. DESCR GNU version of yacc. Can make re-entrant parsers, and numerous other improvements. Why you would want this when Berkeley yacc(1) is part of the NetBSD source tree is beyond me. -1.1.3. PLIST +A.1.3. PLIST @comment $NetBSD$ bin/bison @@ -5320,7 +5325,7 @@ man/man1/bison.1.gz share/bison.simple share/bison.hairy -1.1.4. Checking a package with pkglint +A.1.4. Checking a package with pkglint The NetBSD package system comes with pkgtools/pkglint which helps to check the contents of these files. After installation it is quite easy to use, just @@ -5332,7 +5337,7 @@ looks fine. Depending on the supplied command line arguments (see pkglint(1)) more verbose checks will be performed. Use e.g. pkglint -v for a very verbose check. -1.2. Steps for building, installing, packaging +A.2. Steps for building, installing, packaging Create the directory where the package lives, plus any auxiliary directories: @@ -5447,14 +5452,14 @@ Now that you don't need the source and object files any more, clean up: # make clean ===> Cleaning for bison-1.25 -Appendix 2. Build logs +Appendix B. Build logs Table of Contents -2.1. Building figlet -2.2. Packaging figlet +B.1. Building figlet +B.2. Packaging figlet -2.1. Building figlet +B.1. Building figlet # make ===> Checking for vulnerabilities in figlet-2.2.1nb2 @@ -5545,7 +5550,7 @@ cp figlet.6 /usr/pkg/man/man6 ===> Registering installation for figlet-2.2.1nb2 # -2.2. Packaging figlet +B.2. Packaging figlet # make package ===> Checking for vulnerabilities in figlet-2.2.1nb2 @@ -5556,7 +5561,7 @@ Using SrcDir value of /usr/pkg Registering depends:. # -Appendix 3. Layout of the FTP server's package archive +Appendix C. Layout of the FTP server's package archive Layout for precompiled binary packages on ftp.NetBSD.org: @@ -5634,16 +5639,16 @@ To create: 3. If necessary, create a symlink ln -s `uname -m` `uname -p` (amiga -> m68k, ...) -Appendix 4. Editing guidelines for the pkgsrc guide +Appendix D. Editing guidelines for the pkgsrc guide Table of Contents -4.1. Targets -4.2. Procedure +D.1. Targets +D.2. Procedure This section contains information on editing the pkgsrc guide itself. -4.1. Targets +D.1. Targets The pkgsrc guide's source code is stored in pkgsrc/doc/guide/files, and several files are created from it: @@ -5663,7 +5668,7 @@ files are created from it: * http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps: PostScript version of the pkgsrc guide. -4.2. Procedure +D.2. Procedure The procedure to edit the pkgsrc guide is: |