diff options
| author | rillig <rillig> | 2007-09-18 08:35:13 +0000 |
|---|---|---|
| committer | rillig <rillig> | 2007-09-18 08:35:13 +0000 |
| commit | 815bb1a57d3c3a394e405a21506a11ec3d7d4650 (patch) | |
| tree | e3ad44851c8fa1ec1cc7ef206747d19a666d270e /doc/pkgsrc.txt | |
| parent | 0de4e5e8d46bb76ec9e47d6655c22fddf56577e0 (diff) | |
| download | pkgsrc-815bb1a57d3c3a394e405a21506a11ec3d7d4650.tar.gz | |
regen
Diffstat (limited to 'doc/pkgsrc.txt')
| -rw-r--r-- | doc/pkgsrc.txt | 2017 |
1 files changed, 1051 insertions, 966 deletions
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index 7fcd26e112c..1a99b73e092 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -14,7 +14,7 @@ The pkgsrc Developers Copyright 1994-2007 The NetBSD Foundation, Inc -$NetBSD: pkgsrc.xml,v 1.25 2007/08/15 06:32:38 rillig Exp $ +$NetBSD: pkgsrc.xml,v 1.26 2007/09/18 08:17:21 rillig Exp $ Abstract @@ -108,309 +108,318 @@ I. The pkgsrc user's guide 6.1. Building a single binary package 6.2. Settings for creation of binary packages - 6.3. Doing a bulk build of all packages - - 6.3.1. Configuration - 6.3.2. Other environmental considerations - 6.3.3. Operation - 6.3.4. What it does - 6.3.5. Disk space requirements - 6.3.6. Setting up a sandbox for chrooted builds - 6.3.7. Building a partial set of packages - 6.3.8. Uploading results of a bulk build - - 6.4. Creating a multiple CD-ROM packages collection - - 6.4.1. Example of cdpack - - 7. Directory layout of the installed files - - 7.1. File system layout in ${LOCALBASE} - 7.2. File system layout in ${VARBASE} - - 8. Frequently Asked Questions - - 8.1. Are there any mailing lists for pkg-related discussion? - 8.2. Where's the pkgviews documentation? - 8.3. Utilities for package management (pkgtools) - 8.4. How to use pkgsrc as non-root - 8.5. How to resume transfers when fetching distfiles? - 8.6. How can I install/use modular X.org from pkgsrc? - 8.7. How to fetch files from behind a firewall - 8.8. How do I tell make fetch to do passive FTP? - 8.9. How to fetch all distfiles at once - 8.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" + + 7. Creating binary packages for everything in pkgsrc (bulk builds) + + 7.1. Think first, build later + 7.2. Requirements of a bulk build + 7.3. Running an old-style bulk build + + 7.3.1. Configuration + 7.3.2. Other environmental considerations + 7.3.3. Operation + 7.3.4. What it does + 7.3.5. Disk space requirements + 7.3.6. Setting up a sandbox for chrooted builds + 7.3.7. Building a partial set of packages + 7.3.8. Uploading results of a bulk build + + 7.4. Running a pbulk-style bulk build + + 7.4.1. Configuration + + 7.5. Creating a multiple CD-ROM packages collection + + 7.5.1. Example of cdpack + + 8. Directory layout of the installed files + + 8.1. File system layout in ${LOCALBASE} + 8.2. File system layout in ${VARBASE} + + 9. Frequently Asked Questions + + 9.1. Are there any mailing lists for pkg-related discussion? + 9.2. Where's the pkgviews documentation? + 9.3. Utilities for package management (pkgtools) + 9.4. How to use pkgsrc as non-root + 9.5. How to resume transfers when fetching distfiles? + 9.6. How can I install/use modular X.org from pkgsrc? + 9.7. How to fetch files from behind a firewall + 9.8. How do I tell make fetch to do passive FTP? + 9.9. How to fetch all distfiles at once + 9.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? - 8.11. What does "Could not find bsd.own.mk" mean? - 8.12. Using 'sudo' with pkgsrc - 8.13. How do I change the location of configuration files? - 8.14. Automated security checks - 8.15. Why do some packages ignore my CFLAGS? - 8.16. A package does not build. What shall I do? - 8.17. What does "Makefile appears to contain unresolved cvs/rcs/??? + 9.11. What does "Could not find bsd.own.mk" mean? + 9.12. Using 'sudo' with pkgsrc + 9.13. How do I change the location of configuration files? + 9.14. Automated security checks + 9.15. Why do some packages ignore my CFLAGS? + 9.16. A package does not build. What shall I do? + 9.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge conflicts" mean? II. The pkgsrc developer's guide - 9. Creating a new pkgsrc package from scratch + 10. Creating a new pkgsrc package from scratch - 9.1. Common types of packages + 10.1. Common types of packages - 9.1.1. Perl modules - 9.1.2. KDE applications + 10.1.1. Perl modules + 10.1.2. KDE applications - 9.2. Examples + 10.2. Examples - 9.2.1. How the www/nvu package came into pkgsrc + 10.2.1. How the www/nvu package came into pkgsrc - 10. Package components - files, directories and contents + 11. Package components - files, directories and contents - 10.1. Makefile - 10.2. distinfo - 10.3. patches/* + 11.1. Makefile + 11.2. distinfo + 11.3. patches/* - 10.3.1. Structure of a single patch file - 10.3.2. Creating patch files - 10.3.3. Sources where the patch files come from - 10.3.4. Patching guidelines - 10.3.5. Feedback to the author + 11.3.1. Structure of a single patch file + 11.3.2. Creating patch files + 11.3.3. Sources where the patch files come from + 11.3.4. Patching guidelines + 11.3.5. Feedback to the author - 10.4. Other mandatory files - 10.5. Optional files + 11.4. Other mandatory files + 11.5. Optional files - 10.5.1. Files affecting the binary package - 10.5.2. Files affecting the build process - 10.5.3. Files affecting nothing at all + 11.5.1. Files affecting the binary package + 11.5.2. Files affecting the build process + 11.5.3. Files affecting nothing at all - 10.6. work* - 10.7. files/* + 11.6. work* + 11.7. files/* - 11. Programming in Makefiles + 12. Programming in Makefiles - 11.1. Caveats - 11.2. Makefile variables + 12.1. Caveats + 12.2. Makefile variables - 11.2.1. Naming conventions + 12.2.1. Naming conventions - 11.3. Code snippets + 12.3. Code snippets - 11.3.1. Adding things to a list - 11.3.2. Converting an internal list into an external list - 11.3.3. Passing variables to a shell command - 11.3.4. Quoting guideline - 11.3.5. Workaround for a bug in BSD Make + 12.3.1. Adding things to a list + 12.3.2. Converting an internal list into an external list + 12.3.3. Passing variables to a shell command + 12.3.4. Quoting guideline + 12.3.5. Workaround for a bug in BSD Make - 12. PLIST issues + 13. PLIST issues - 12.1. RCS ID - 12.2. Semi-automatic PLIST generation - 12.3. Tweaking output of make print-PLIST - 12.4. Variable substitution in PLIST - 12.5. Man page compression - 12.6. Changing PLIST source with PLIST_SRC - 12.7. Platform-specific and differing PLISTs - 12.8. Sharing directories between packages + 13.1. RCS ID + 13.2. Semi-automatic PLIST generation + 13.3. Tweaking output of make print-PLIST + 13.4. Variable substitution in PLIST + 13.5. Man page compression + 13.6. Changing PLIST source with PLIST_SRC + 13.7. Platform-specific and differing PLISTs + 13.8. Sharing directories between packages - 13. Buildlink methodology + 14. Buildlink methodology - 13.1. Converting packages to use buildlink3 - 13.2. Writing buildlink3.mk files + 14.1. Converting packages to use buildlink3 + 14.2. Writing buildlink3.mk files - 13.2.1. Anatomy of a buildlink3.mk file - 13.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files + 14.2.1. Anatomy of a buildlink3.mk file + 14.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files - 13.3. Writing builtin.mk files + 14.3. Writing builtin.mk files - 13.3.1. Anatomy of a builtin.mk file - 13.3.2. Global preferences for native or pkgsrc software + 14.3.1. Anatomy of a builtin.mk file + 14.3.2. Global preferences for native or pkgsrc software - 14. The pkginstall framework + 15. The pkginstall framework - 14.1. Files and directories outside the installation prefix + 15.1. Files and directories outside the installation prefix - 14.1.1. Directory manipulation - 14.1.2. File manipulation + 15.1.1. Directory manipulation + 15.1.2. File manipulation - 14.2. Configuration files + 15.2. Configuration files - 14.2.1. How PKG_SYSCONFDIR is set - 14.2.2. Telling the software where configuration files are - 14.2.3. Patching installations - 14.2.4. Disabling handling of configuration files + 15.2.1. How PKG_SYSCONFDIR is set + 15.2.2. Telling the software where configuration files are + 15.2.3. Patching installations + 15.2.4. Disabling handling of configuration files - 14.3. System startup scripts + 15.3. System startup scripts - 14.3.1. Disabling handling of system startup scripts + 15.3.1. Disabling handling of system startup scripts - 14.4. System users and groups - 14.5. System shells + 15.4. System users and groups + 15.5. System shells - 14.5.1. Disabling shell registration + 15.5.1. Disabling shell registration - 14.6. Fonts + 15.6. Fonts - 14.6.1. Disabling automatic update of the fonts databases + 15.6.1. Disabling automatic update of the fonts databases - 15. Options handling + 16. Options handling - 15.1. Global default options - 15.2. Converting packages to use bsd.options.mk - 15.3. Option Names + 16.1. Global default options + 16.2. Converting packages to use bsd.options.mk + 16.3. Option Names - 16. The build process + 17. The build process - 16.1. Introduction - 16.2. Program location - 16.3. Directories used during the build process - 16.4. Running a phase - 16.5. The fetch phase + 17.1. Introduction + 17.2. Program location + 17.3. Directories used during the build process + 17.4. Running a phase + 17.5. The fetch phase - 16.5.1. What to fetch and where to get it from - 16.5.2. How are the files fetched? + 17.5.1. What to fetch and where to get it from + 17.5.2. How are the files fetched? - 16.6. The checksum phase - 16.7. The extract phase - 16.8. The patch phase - 16.9. The tools phase - 16.10. The wrapper phase - 16.11. The configure phase - 16.12. The build phase - 16.13. The test phase - 16.14. The install phase - 16.15. The package phase - 16.16. Cleaning up - 16.17. Other helpful targets + 17.6. The checksum phase + 17.7. The extract phase + 17.8. The patch phase + 17.9. The tools phase + 17.10. The wrapper phase + 17.11. The configure phase + 17.12. The build phase + 17.13. The test phase + 17.14. The install phase + 17.15. The package phase + 17.16. Cleaning up + 17.17. Other helpful targets - 17. Tools needed for building or running + 18. Tools needed for building or running - 17.1. Tools for pkgsrc builds - 17.2. Tools needed by packages - 17.3. Tools provided by platforms - 17.4. Questions regarding the tools + 18.1. Tools for pkgsrc builds + 18.2. Tools needed by packages + 18.3. Tools provided by platforms + 18.4. Questions regarding the tools - 18. Making your package work + 19. Making your package work - 18.1. General operation + 19.1. General operation - 18.1.1. Portability of packages - 18.1.2. How to pull in user-settable variables from mk.conf - 18.1.3. User interaction - 18.1.4. Handling licenses - 18.1.5. Restricted packages - 18.1.6. Handling dependencies - 18.1.7. Handling conflicts with other packages - 18.1.8. Packages that cannot or should not be built - 18.1.9. Packages which should not be deleted, once installed - 18.1.10. Handling packages with security problems - 18.1.11. How to handle incrementing versions when fixing an + 19.1.1. Portability of packages + 19.1.2. How to pull in user-settable variables from mk.conf + 19.1.3. User interaction + 19.1.4. Handling licenses + 19.1.5. Restricted packages + 19.1.6. Handling dependencies + 19.1.7. Handling conflicts with other packages + 19.1.8. Packages that cannot or should not be built + 19.1.9. Packages which should not be deleted, once installed + 19.1.10. Handling packages with security problems + 19.1.11. How to handle incrementing versions when fixing an existing package - 18.1.12. Substituting variable text in the package files (the SUBST + 19.1.12. Substituting variable text in the package files (the SUBST framework) - 18.2. Fixing problems in the fetch phase + 19.2. Fixing problems in the fetch phase - 18.2.1. Packages whose distfiles aren't available for plain + 19.2.1. Packages whose distfiles aren't available for plain downloading - 18.2.2. How to handle modified distfiles with the 'old' name - - 18.3. Fixing problems in the configure phase - - 18.3.1. Shared libraries - libtool - 18.3.2. Using libtool on GNU packages that already support libtool - 18.3.3. GNU Autoconf/Automake - - 18.4. Programming languages - - 18.4.1. C, C++, and Fortran - 18.4.2. Java - 18.4.3. Packages containing perl scripts - 18.4.4. Other programming languages - - 18.5. Fixing problems in the build phase - - 18.5.1. Compiling C and C++ code conditionally - 18.5.2. How to handle compiler bugs - 18.5.3. Undefined reference to "..." - 18.5.4. Running out of memory - - 18.6. Fixing problems in the install phase - - 18.6.1. Creating needed directories - 18.6.2. Where to install documentation - 18.6.3. Installing highscore files - 18.6.4. Adding DESTDIR support to packages - 18.6.5. Packages with hardcoded paths to other interpreters - 18.6.6. Packages installing perl modules - 18.6.7. Packages installing info files - 18.6.8. Packages installing man pages - 18.6.9. Packages installing GConf2 data files - 18.6.10. Packages installing scrollkeeper data files - 18.6.11. Packages installing X11 fonts - 18.6.12. Packages installing GTK2 modules - 18.6.13. Packages installing SGML or XML data - 18.6.14. Packages installing extensions to the MIME database - 18.6.15. Packages using intltool - 18.6.16. Packages installing startup scripts - 18.6.17. Packages installing TeX modules - 18.6.18. Packages supporting running binaries in emulation - 18.6.19. Packages installing hicolor theme icons - 18.6.20. Packages installing desktop files - - 18.7. Marking packages as having problems - - 19. Debugging - 20. Submitting and Committing - - 20.1. Submitting binary packages - 20.2. Submitting source packages (for non-NetBSD-developers) - 20.3. General notes when adding, updating, or removing packages - 20.4. Committing: Importing a package into CVS - 20.5. Updating a package to a newer version - 20.6. Moving a package in pkgsrc - - 21. Frequently Asked Questions - 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 + 19.2.2. How to handle modified distfiles with the 'old' name + + 19.3. Fixing problems in the configure phase + + 19.3.1. Shared libraries - libtool + 19.3.2. Using libtool on GNU packages that already support libtool + 19.3.3. GNU Autoconf/Automake + + 19.4. Programming languages + + 19.4.1. C, C++, and Fortran + 19.4.2. Java + 19.4.3. Packages containing perl scripts + 19.4.4. Other programming languages + + 19.5. Fixing problems in the build phase + + 19.5.1. Compiling C and C++ code conditionally + 19.5.2. How to handle compiler bugs + 19.5.3. Undefined reference to "..." + 19.5.4. Running out of memory + + 19.6. Fixing problems in the install phase + + 19.6.1. Creating needed directories + 19.6.2. Where to install documentation + 19.6.3. Installing highscore files + 19.6.4. Adding DESTDIR support to packages + 19.6.5. Packages with hardcoded paths to other interpreters + 19.6.6. Packages installing perl modules + 19.6.7. Packages installing info files + 19.6.8. Packages installing man pages + 19.6.9. Packages installing GConf2 data files + 19.6.10. Packages installing scrollkeeper data files + 19.6.11. Packages installing X11 fonts + 19.6.12. Packages installing GTK2 modules + 19.6.13. Packages installing SGML or XML data + 19.6.14. Packages installing extensions to the MIME database + 19.6.15. Packages using intltool + 19.6.16. Packages installing startup scripts + 19.6.17. Packages installing TeX modules + 19.6.18. Packages supporting running binaries in emulation + 19.6.19. Packages installing hicolor theme icons + 19.6.20. Packages installing desktop files + + 19.7. Marking packages as having problems + + 20. Debugging + 21. Submitting and Committing + + 21.1. Submitting binary packages + 21.2. Submitting source packages (for non-NetBSD-developers) + 21.3. General notes when adding, updating, or removing packages + 21.4. Committing: Importing a package into CVS + 21.5. Updating a package to a newer version + 21.6. Moving a package in pkgsrc + + 22. Frequently Asked Questions + 23. GNOME packaging and porting + + 23.1. Meta packages + 23.2. Packaging a GNOME application + 23.3. Updating GNOME to a newer version + 23.4. Patching guidelines III. The pkgsrc infrastructure internals - 23. Design of the pkgsrc infrastructure + 24. Design of the pkgsrc infrastructure - 23.1. The meaning of variable definitions - 23.2. Avoiding problems before they arise - 23.3. Variable evaluation + 24.1. The meaning of variable definitions + 24.2. Avoiding problems before they arise + 24.3. Variable evaluation - 23.3.1. At load time - 23.3.2. At runtime + 24.3.1. At load time + 24.3.2. At runtime - 23.4. How can variables be specified? - 23.5. Designing interfaces for Makefile fragments + 24.4. How can variables be specified? + 24.5. Designing interfaces for Makefile fragments - 23.5.1. Procedures with parameters - 23.5.2. Actions taken on behalf of parameters + 24.5.1. Procedures with parameters + 24.5.2. Actions taken on behalf of parameters - 23.6. The order in which files are loaded + 24.6. The order in which files are loaded - 23.6.1. The order in bsd.prefs.mk - 23.6.2. The order in bsd.pkg.mk + 24.6.1. The order in bsd.prefs.mk + 24.6.2. The order in bsd.pkg.mk - 24. Regression tests + 25. Regression tests - 24.1. The regression tests framework - 24.2. Running the regression tests - 24.3. Adding a new regression test + 25.1. The regression tests framework + 25.2. Running the regression tests + 25.3. Adding a new regression test - 24.3.1. Overridable functions - 24.3.2. Helper functions + 25.3.1. Overridable functions + 25.3.2. Helper functions - 25. Porting pkgsrc + 26. Porting pkgsrc - 25.1. Porting pkgsrc to a new operating system - 25.2. Adding support for a new compiler + 26.1. Porting pkgsrc to a new operating system + 26.2. Adding support for a new compiler A. A simple example package: bison @@ -446,8 +455,8 @@ List of Tables 1.1. Platforms supported by pkgsrc 3.1. Binary kits and available packages -10.1. Patching examples -22.1. PLIST handling for GNOME packages +11.1. Patching examples +23.1. PLIST handling for GNOME packages Chapter 1. What is pkgsrc? @@ -739,45 +748,54 @@ Table of Contents 6.1. Building a single binary package 6.2. Settings for creation of binary packages - 6.3. Doing a bulk build of all packages - - 6.3.1. Configuration - 6.3.2. Other environmental considerations - 6.3.3. Operation - 6.3.4. What it does - 6.3.5. Disk space requirements - 6.3.6. Setting up a sandbox for chrooted builds - 6.3.7. Building a partial set of packages - 6.3.8. Uploading results of a bulk build - - 6.4. Creating a multiple CD-ROM packages collection - - 6.4.1. Example of cdpack - -7. Directory layout of the installed files - - 7.1. File system layout in ${LOCALBASE} - 7.2. File system layout in ${VARBASE} - -8. Frequently Asked Questions - - 8.1. Are there any mailing lists for pkg-related discussion? - 8.2. Where's the pkgviews documentation? - 8.3. Utilities for package management (pkgtools) - 8.4. How to use pkgsrc as non-root - 8.5. How to resume transfers when fetching distfiles? - 8.6. How can I install/use modular X.org from pkgsrc? - 8.7. How to fetch files from behind a firewall - 8.8. How do I tell make fetch to do passive FTP? - 8.9. How to fetch all distfiles at once - 8.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? - 8.11. What does "Could not find bsd.own.mk" mean? - 8.12. Using 'sudo' with pkgsrc - 8.13. How do I change the location of configuration files? - 8.14. Automated security checks - 8.15. Why do some packages ignore my CFLAGS? - 8.16. A package does not build. What shall I do? - 8.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge + +7. Creating binary packages for everything in pkgsrc (bulk builds) + + 7.1. Think first, build later + 7.2. Requirements of a bulk build + 7.3. Running an old-style bulk build + + 7.3.1. Configuration + 7.3.2. Other environmental considerations + 7.3.3. Operation + 7.3.4. What it does + 7.3.5. Disk space requirements + 7.3.6. Setting up a sandbox for chrooted builds + 7.3.7. Building a partial set of packages + 7.3.8. Uploading results of a bulk build + + 7.4. Running a pbulk-style bulk build + + 7.4.1. Configuration + + 7.5. Creating a multiple CD-ROM packages collection + + 7.5.1. Example of cdpack + +8. Directory layout of the installed files + + 8.1. File system layout in ${LOCALBASE} + 8.2. File system layout in ${VARBASE} + +9. Frequently Asked Questions + + 9.1. Are there any mailing lists for pkg-related discussion? + 9.2. Where's the pkgviews documentation? + 9.3. Utilities for package management (pkgtools) + 9.4. How to use pkgsrc as non-root + 9.5. How to resume transfers when fetching distfiles? + 9.6. How can I install/use modular X.org from pkgsrc? + 9.7. How to fetch files from behind a firewall + 9.8. How do I tell make fetch to do passive FTP? + 9.9. How to fetch all distfiles at once + 9.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? + 9.11. What does "Could not find bsd.own.mk" mean? + 9.12. Using 'sudo' with pkgsrc + 9.13. How do I change the location of configuration files? + 9.14. Automated security checks + 9.15. Why do some packages ignore my CFLAGS? + 9.16. A package does not build. What shall I do? + 9.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge conflicts" mean? Chapter 2. Where to get pkgsrc and how to keep it up-to-date @@ -1959,7 +1977,7 @@ XXX tree. It is possible to have many pkgsrc tree instances.) * LOCALPATCHES: Directory for local patches that aren't part of pkgsrc. See - Section 10.3, "patches/*" for more information. + Section 11.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 @@ -2134,20 +2152,6 @@ Table of Contents 6.1. Building a single binary package 6.2. Settings for creation of binary packages -6.3. Doing a bulk build of all packages - - 6.3.1. Configuration - 6.3.2. Other environmental considerations - 6.3.3. Operation - 6.3.4. What it does - 6.3.5. Disk space requirements - 6.3.6. Setting up a sandbox for chrooted builds - 6.3.7. Building a partial set of packages - 6.3.8. Uploading results of a bulk build - -6.4. Creating a multiple CD-ROM packages collection - - 6.4.1. Example of cdpack 6.1. Building a single binary package @@ -2170,28 +2174,103 @@ manipulate it. Binary packages are created by default in /usr/pkgsrc/packages, 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 20, Submitting and Committing for information on how to submit such +See Chapter 21, Submitting and Committing for information on how to submit such a binary package. 6.2. Settings for creation of binary packages -See Section 16.17, "Other helpful targets". +See Section 17.17, "Other helpful targets". + +Chapter 7. Creating binary packages for everything in pkgsrc (bulk builds) + +Table of Contents + +7.1. Think first, build later +7.2. Requirements of a bulk build +7.3. Running an old-style bulk build + + 7.3.1. Configuration + 7.3.2. Other environmental considerations + 7.3.3. Operation + 7.3.4. What it does + 7.3.5. Disk space requirements + 7.3.6. Setting up a sandbox for chrooted builds + 7.3.7. Building a partial set of packages + 7.3.8. Uploading results of a bulk build + +7.4. Running a pbulk-style bulk build + + 7.4.1. Configuration -6.3. Doing a bulk build of all packages +7.5. Creating a multiple CD-ROM packages collection -If you want to get a full set of precompiled binary packages, this section -describes how to get them. Beware that the bulk build will remove all currently -installed packages from your system! + 7.5.1. Example of cdpack -Having an FTP server configured either on the machine doing the bulk builds or -on a nearby NFS server can help to make the packages available to other -machines that can then save time by installing only the binary packages. See -ftpd(8) for more information. If you use a remote NFS server's storage, be sure -to not actually compile on NFS storage, as this slows things down a lot. +When you have multiple machines that should run the same packages, it is wasted +time if they all build their packages themselves from source. There are two +ways of getting a set of binary packages: The old bulk build system, or the new +(as of 2007) parallel bulk build (pbulk) system. This chapter describes how to +set them up so that the packages are most likely to be usable later. -6.3.1. Configuration +7.1. Think first, build later -6.3.1.1. build.conf +Since a bulk build takes several days or even weeks to finish, you should think +about the setup before you start everything. Pay attention to at least the +following points: + + * If you want to upload the binary packages to ftp.NetBSD.org, make sure the + setup complies to the requirements for binary packages: + + o To end up on ftp.NetBSD.org, the packages must be built by a NetBSD + developer on a trusted machine (that is, where you and only you have + root access). + + o Packages on ftp.NetBSD.org should only be created from the stable + branches (like 2007Q1), so that users browsing the available + collections can see at a glance how old the packages are. + + o The packages must be built as root, since some packages require set-uid + binaries at runtime, and creating those packages as unprivileged user + doesn't work well at the moment. + + * Make sure that the bulk build cannot break anything in your system. Most + bulk builds run as root, so they should be run at least in a chroot + environment or something even more restrictive, depending on what the + operating system provides. There have been numerous cases where certain + packages tried to install files outside the LOCALBASE or wanted to edit + some files in /etc. Furthermore, the bulk builds install and deinstall + packages in /usr/pkg (or whatever LOCALBASE is) during their operation, so + be sure that you don't need any package during the build. + +7.2. Requirements of a bulk build + +A complete bulk build requires lots of disk space. Some of the disk space can +be read-only, some other must be writable. Some can be on remote filesystems +(such as NFS) and some should be local. Some can be temporary filesystems, +others must survive a sudden reboot. + + * 10 GB for the distfiles (read-write, remote, temporary) + + * 10 GB for the binary packages (read-write, remote, permanent) + + * 400 MB for the pkgsrc tree (read-only, remote, permanent) + + * 5 GB for LOCALBASE (read-write, local, temporary for pbulk, permanent for + old-bulk) + + * 5 GB for the log files (read-write, remote, permanent) + + * 5 GB for temporary files (read-write, local, temporary) + +7.3. Running an old-style bulk build + +Warning + +The rest of this section is rather old. Don't rely on it too much. + +7.3.1. Configuration + +7.3.1.1. build.conf The build.conf file is the main configuration file for bulk builds. You can configure how your copy of pkgsrc is kept up to date, how the distfiles are @@ -2200,7 +2279,7 @@ find an annotated example file in pkgsrc/mk/bulk/build.conf-example. To use it, copy build.conf-example to build.conf and edit it, following the comments in that file. -6.3.1.2. mk.conf +7.3.1.2. mk.conf You may want to set variables in mk.conf. Look at pkgsrc/mk/defaults/mk.conf for details of the default settings. You will want to ensure that @@ -2251,7 +2330,7 @@ Some other options are scattered in the pkgsrc infrastructure: bulk builds is not completely idle. Otherwise some test programs will seem to hang, while they are just waiting for new random data to be available. -6.3.1.3. pre-build.local +7.3.1.3. pre-build.local It is possible to configure the bulk build to perform certain site-specific tasks at the end of the pre-build stage. If the file pre-build.local exists in @@ -2264,7 +2343,7 @@ echo "I do not have enough disk space to build this pig." \ to prevent the system from trying to build a particular package which requires nearly 3 GB of disk space. -6.3.2. Other environmental considerations +7.3.2. Other environmental considerations As /usr/pkg will be completely deleted at the start of bulk builds, make sure your login shell is placed somewhere else. Either drop it into /usr/local/bin @@ -2284,7 +2363,7 @@ Not doing so will result in you being not able to log in via ssh after the bulk build is finished or if the machine gets rebooted or crashes. You have been warned! :) -6.3.3. Operation +7.3.3. Operation Make sure you don't need any of the packages still installed. @@ -2309,7 +2388,7 @@ panic, ...), you can continue it by running: At the end of the bulk build, you will get a summary via mail, and find build logs in the directory specified by FTP in the build.conf file. -6.3.4. What it does +7.3.4. What it does The bulk builds consist of three steps: @@ -2336,7 +2415,7 @@ logs of broken builds can be found in the package's directory. These files are used by the bulk-targets to mark broken builds to not waste time trying to rebuild them, and they can be used to debug these broken package builds later. -6.3.5. Disk space requirements +7.3.5. Disk space requirements Currently, roughly the following requirements are valid for NetBSD 2.0/i386: @@ -2352,7 +2431,7 @@ demand to disk space. Afterwards, if the package is needed again, it will be installed via pkg_add(1) instead of building again, so there are no cycles wasted by recompiling. -6.3.6. Setting up a sandbox for chrooted builds +7.3.6. Setting up a sandbox for chrooted builds If you don't want all the packages nuked from a machine (rendering it useless for anything but pkg compiling), there is the possibility of doing the package @@ -2416,7 +2495,7 @@ src/etc, be sure the following items are present and properly configured: 10. Make /usr/sandbox/usr/pkgsrc/packages and .../distfiles point somewhere appropriate. NFS- and/or nullfs-mounts may come in handy! -11. Edit mk.conf, see Section 6.3.1.2, "mk.conf". +11. Edit mk.conf, see Section 7.3.1.2, "mk.conf". 12. Adjust mk/bulk/build.conf to suit your needs. @@ -2432,7 +2511,7 @@ build, mail will be sent with the results of the build. Created binary pkgs will be in /usr/sandbox/usr/pkgsrc/packages (wherever that points/mounts to/ from). -6.3.7. Building a partial set of packages +7.3.7. Building a partial set of packages In addition to building a complete set of all packages in pkgsrc, the pkgsrc/mk /bulk/build script may be used to build a subset of the packages contained in @@ -2454,7 +2533,7 @@ One use of this is to do a bulk build with SPECIFIC_PKGS in a chroot sandbox periodically to have a complete set of the binary packages needed for your site available without the overhead of building extra packages that are not needed. -6.3.8. Uploading results of a bulk build +7.3.8. Uploading results of a bulk build This section describes how pkgsrc developers can upload binary pkgs built by bulk builds to ftp.NetBSD.org. @@ -2535,7 +2614,13 @@ nbftp% rmdir upload nbftp% chmod 755 . -6.4. Creating a multiple CD-ROM packages collection +7.4. Running a pbulk-style bulk build + +7.4.1. Configuration + +TODO; see the wiki for more information. + +7.5. Creating a multiple CD-ROM packages collection After your pkgsrc bulk-build has completed, you may wish to create a CD-ROM set of the resulting binary packages to assist in installing packages on other @@ -2543,7 +2628,7 @@ machines. The pkgtools/cdpack package provides a simple tool for creating the ISO 9660 images. cdpack arranges the packages on the CD-ROMs in a way that keeps all the dependencies for a given package on the same CD as that package. -6.4.1. Example of cdpack +7.5.1. Example of cdpack Complete documentation for cdpack is found in the cdpack(1) man page. The following short example assumes that the binary packages are left in /usr/ @@ -2575,12 +2660,12 @@ Now create the images: Each image will contain README, COPYING, and bin/myscript in their root directories. -Chapter 7. Directory layout of the installed files +Chapter 8. Directory layout of the installed files Table of Contents -7.1. File system layout in ${LOCALBASE} -7.2. File system layout in ${VARBASE} +8.1. File system layout in ${LOCALBASE} +8.2. File system layout in ${VARBASE} The files that are installed by pkgsrc are organized in a way that is similar to what you find in the /usr directory of the base system. But some details are @@ -2619,7 +2704,7 @@ below. * PKG_SYSCONFDIR corresponds to /etc in the base system. It contains configuration files of the packages, as well as pkgsrc's mk.conf itself. -7.1. File system layout in ${LOCALBASE} +8.1. File system layout in ${LOCALBASE} The following directories exist in a typical pkgsrc installation in $ {LOCALBASE}. @@ -2696,7 +2781,7 @@ var (the usual location of ${VARBASE}) Contains files that may be modified after installation. -7.2. File system layout in ${VARBASE} +8.2. File system layout in ${VARBASE} db/pkg (the usual location of ${PKG_DBDIR}) @@ -2714,34 +2799,34 @@ run Contains informational files about daemons that are currently running. -Chapter 8. Frequently Asked Questions +Chapter 9. Frequently Asked Questions Table of Contents -8.1. Are there any mailing lists for pkg-related discussion? -8.2. Where's the pkgviews documentation? -8.3. Utilities for package management (pkgtools) -8.4. How to use pkgsrc as non-root -8.5. How to resume transfers when fetching distfiles? -8.6. How can I install/use modular X.org from pkgsrc? -8.7. How to fetch files from behind a firewall -8.8. How do I tell make fetch to do passive FTP? -8.9. How to fetch all distfiles at once -8.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? -8.11. What does "Could not find bsd.own.mk" mean? -8.12. Using 'sudo' with pkgsrc -8.13. How do I change the location of configuration files? -8.14. Automated security checks -8.15. Why do some packages ignore my CFLAGS? -8.16. A package does not build. What shall I do? -8.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge +9.1. Are there any mailing lists for pkg-related discussion? +9.2. Where's the pkgviews documentation? +9.3. Utilities for package management (pkgtools) +9.4. How to use pkgsrc as non-root +9.5. How to resume transfers when fetching distfiles? +9.6. How can I install/use modular X.org from pkgsrc? +9.7. How to fetch files from behind a firewall +9.8. How do I tell make fetch to do passive FTP? +9.9. How to fetch all distfiles at once +9.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? +9.11. What does "Could not find bsd.own.mk" mean? +9.12. Using 'sudo' with pkgsrc +9.13. How do I change the location of configuration files? +9.14. Automated security checks +9.15. Why do some packages ignore my CFLAGS? +9.16. A package does not build. What shall I do? +9.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge conflicts" mean? This section contains hints, tips & tricks on special things in pkgsrc that we didn't find a better place for in the previous chapters, and it contains items for both pkgsrc users and developers. -8.1. Are there any mailing lists for pkg-related discussion? +9.1. Are there any mailing lists for pkg-related discussion? The following mailing lists may be of interest to pkgsrc users: @@ -2768,12 +2853,12 @@ To subscribe, do: Archives for all these mailing lists are available from http:// mail-index.NetBSD.org/. -8.2. Where's the pkgviews documentation? +9.2. Where's the pkgviews documentation? Pkgviews is tightly integrated with buildlink. You can find a pkgviews User's guide in pkgsrc/mk/buildlink3/PKGVIEWS_UG. -8.3. Utilities for package management (pkgtools) +9.3. Utilities for package management (pkgtools) The directory pkgsrc/pkgtools contains a number of useful utilities for both users and developers of pkgsrc. This section attempts only to make the reader @@ -2840,7 +2925,7 @@ Utilities for people maintaining pkgsrc (or: more obscure pkg utilities) * pkgtools/libkver: Spoof kernel version for chrooted cross builds. -8.4. How to use pkgsrc as non-root +9.4. How to use pkgsrc as non-root If you want to use pkgsrc as non-root user, you can set some variables to make pkgsrc work under these conditions. At the very least, you need to set @@ -2858,7 +2943,7 @@ choose and use multiple default directories under ~/pkg as the installation targets. These directories can be overridden by the "--prefix" flag provided by the script, as well as some others that allow finer tuning of the tree layout. -8.5. How to resume transfers when fetching distfiles? +9.5. How to resume transfers when fetching distfiles? By default, resuming transfers in pkgsrc is disabled, but you can enable this feature by adding the option PKG_RESUME_TRANSFERS=YES into mk.conf. If, during @@ -2876,7 +2961,7 @@ FETCH_BEFORE_ARGS= --passive-ftp FETCH_RESUME_ARGS= -c FETCH_OUTPUT_ARGS= -O -8.6. How can I install/use modular X.org from pkgsrc? +9.6. How can I install/use modular X.org from pkgsrc? If you want to use modular X.org from pkgsrc instead of your system's own X11 (/usr/X11R6, /usr/openwin, ...) you will have to add the following line into @@ -2888,7 +2973,7 @@ Note The DragonFly operating system defaults to using modular X.org from pkgsrc. -8.7. How to fetch files from behind a firewall +9.7. How to fetch files from behind a firewall If you are sitting behind a firewall which does not allow direct connections to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts. This @@ -2899,7 +2984,7 @@ the proxy port number. So the proxy environment variables are: ftp_proxy=ftp://orpheus.amdahl.com:80/ http_proxy=http://orpheus.amdahl.com:80/ -8.8. How do I tell make fetch to do passive FTP? +9.8. How do I tell make fetch to do passive FTP? This depends on which utility is used to retrieve distfiles. From bsd.pkg.mk, FETCH_CMD is assigned the first available command from the following list: @@ -2916,7 +3001,7 @@ following to your mk.conf file: PASSIVE_FETCH=1. Having that option present will prevent /usr/bin/ftp from falling back to active transfers. -8.9. How to fetch all distfiles at once +9.9. How to fetch all distfiles at once You would like to download all the distfiles in a single batch from work or university, where you can't run a make fetch. There is an archive of distfiles @@ -2951,7 +3036,7 @@ everything by running: % make fetch NO_SKIP=yes -8.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? +9.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? When compiling the pkgtools/pkg_install package, you get the error from make that it doesn't know how to make /usr/share/tmac/tmac.andoc? This indicates @@ -2961,7 +3046,7 @@ distribution on your machine. It is recommended to do that to format man pages. In the case of the pkgtools/pkg_install package, you can get away with setting NOMAN=YES either in the environment or in mk.conf. -8.11. What does "Could not find bsd.own.mk" mean? +9.11. What does "Could not find bsd.own.mk" mean? You didn't install the compiler set, comp.tgz, when you installed your NetBSD machine. Please get and install it, by extracting it in /: @@ -2972,7 +3057,7 @@ machine. Please get and install it, by extracting it in /: comp.tgz is part of every NetBSD release. Get the one that corresponds to your release (determine via uname -r). -8.12. Using 'sudo' with pkgsrc +9.12. Using 'sudo' with pkgsrc When installing packages as non-root user and using the just-in-time su(1) feature of pkgsrc, it can become annoying to type in the root password for each @@ -2985,7 +3070,7 @@ mk.conf, somewhere after the definition of the LOCALBASE variable: SU_CMD= ${LOCALBASE}/bin/sudo /bin/sh -c .endif -8.13. How do I change the location of configuration files? +9.13. How do I change the location of configuration files? As the system administrator, you can choose where configuration files are installed. The default settings make all these files go into ${PREFIX}/etc or @@ -3005,7 +3090,7 @@ of PKGBASE. Note that after changing these settings, you must rebuild and reinstall any affected packages. -8.14. Automated security checks +9.14. Automated security checks Please be aware that there can often be bugs in third-party software, and some of these bugs can leave a machine vulnerable to exploitation by attackers. In @@ -3035,7 +3120,7 @@ If this package is installed, pkgsrc builds will use it to perform a security check before building any package. See Section 5.2, "Variables affecting the build process" for ways to control this check. -8.15. Why do some packages ignore my CFLAGS? +9.15. Why do some packages ignore my CFLAGS? When you add your own preferences to the CFLAGS variable in your mk.conf, these flags are passed in environment variables to the ./configure scripts and to @@ -3049,7 +3134,7 @@ Usually you can remove these lines. But be aware that some "smart" programmers write so bad code that it only works for the specific combination of CFLAGS they have chosen. -8.16. A package does not build. What shall I do? +9.16. A package does not build. What shall I do? 1. Make sure that your copy of pkgsrc is consistent. A case that occurs often is that people only update pkgsrc in parts, because of performance reasons. @@ -3065,7 +3150,7 @@ they have chosen. 4. If the problem still exists, write a mail to the pkgsrc-users mailing list. -8.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge +9.17. What does "Makefile appears to contain unresolved cvs/rcs/??? merge conflicts" mean? You have modified a file from pkgsrc, and someone else has modified that same @@ -3086,241 +3171,241 @@ more like a reference manual for pkgsrc. Table of Contents -9. Creating a new pkgsrc package from scratch +10. Creating a new pkgsrc package from scratch - 9.1. Common types of packages + 10.1. Common types of packages - 9.1.1. Perl modules - 9.1.2. KDE applications + 10.1.1. Perl modules + 10.1.2. KDE applications - 9.2. Examples + 10.2. Examples - 9.2.1. How the www/nvu package came into pkgsrc + 10.2.1. How the www/nvu package came into pkgsrc -10. Package components - files, directories and contents +11. Package components - files, directories and contents - 10.1. Makefile - 10.2. distinfo - 10.3. patches/* + 11.1. Makefile + 11.2. distinfo + 11.3. patches/* - 10.3.1. Structure of a single patch file - 10.3.2. Creating patch files - 10.3.3. Sources where the patch files come from - 10.3.4. Patching guidelines - 10.3.5. Feedback to the author + 11.3.1. Structure of a single patch file + 11.3.2. Creating patch files + 11.3.3. Sources where the patch files come from + 11.3.4. Patching guidelines + 11.3.5. Feedback to the author - 10.4. Other mandatory files - 10.5. Optional files + 11.4. Other mandatory files + 11.5. Optional files - 10.5.1. Files affecting the binary package - 10.5.2. Files affecting the build process - 10.5.3. Files affecting nothing at all + 11.5.1. Files affecting the binary package + 11.5.2. Files affecting the build process + 11.5.3. Files affecting nothing at all - 10.6. work* - 10.7. files/* + 11.6. work* + 11.7. files/* -11. Programming in Makefiles +12. Programming in Makefiles - 11.1. Caveats - 11.2. Makefile variables + 12.1. Caveats + 12.2. Makefile variables - 11.2.1. Naming conventions + 12.2.1. Naming conventions - 11.3. Code snippets + 12.3. Code snippets - 11.3.1. Adding things to a list - 11.3.2. Converting an internal list into an external list - 11.3.3. Passing variables to a shell command - 11.3.4. Quoting guideline - 11.3.5. Workaround for a bug in BSD Make + 12.3.1. Adding things to a list + 12.3.2. Converting an internal list into an external list + 12.3.3. Passing variables to a shell command + 12.3.4. Quoting guideline + 12.3.5. Workaround for a bug in BSD Make -12. PLIST issues +13. PLIST issues - 12.1. RCS ID - 12.2. Semi-automatic PLIST generation - 12.3. Tweaking output of make print-PLIST - 12.4. Variable substitution in PLIST - 12.5. Man page compression - 12.6. Changing PLIST source with PLIST_SRC - 12.7. Platform-specific and differing PLISTs - 12.8. Sharing directories between packages + 13.1. RCS ID + 13.2. Semi-automatic PLIST generation + 13.3. Tweaking output of make print-PLIST + 13.4. Variable substitution in PLIST + 13.5. Man page compression + 13.6. Changing PLIST source with PLIST_SRC + 13.7. Platform-specific and differing PLISTs + 13.8. Sharing directories between packages -13. Buildlink methodology +14. Buildlink methodology - 13.1. Converting packages to use buildlink3 - 13.2. Writing buildlink3.mk files + 14.1. Converting packages to use buildlink3 + 14.2. Writing buildlink3.mk files - 13.2.1. Anatomy of a buildlink3.mk file - 13.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files + 14.2.1. Anatomy of a buildlink3.mk file + 14.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files - 13.3. Writing builtin.mk files + 14.3. Writing builtin.mk files - 13.3.1. Anatomy of a builtin.mk file - 13.3.2. Global preferences for native or pkgsrc software + 14.3.1. Anatomy of a builtin.mk file + 14.3.2. Global preferences for native or pkgsrc software -14. The pkginstall framework +15. The pkginstall framework - 14.1. Files and directories outside the installation prefix + 15.1. Files and directories outside the installation prefix - 14.1.1. Directory manipulation - 14.1.2. File manipulation + 15.1.1. Directory manipulation + 15.1.2. File manipulation - 14.2. Configuration files + 15.2. Configuration files - 14.2.1. How PKG_SYSCONFDIR is set - 14.2.2. Telling the software where configuration files are - 14.2.3. Patching installations - 14.2.4. Disabling handling of configuration files + 15.2.1. How PKG_SYSCONFDIR is set + 15.2.2. Telling the software where configuration files are + 15.2.3. Patching installations + 15.2.4. Disabling handling of configuration files - 14.3. System startup scripts + 15.3. System startup scripts - 14.3.1. Disabling handling of system startup scripts + 15.3.1. Disabling handling of system startup scripts - 14.4. System users and groups - 14.5. System shells + 15.4. System users and groups + 15.5. System shells - 14.5.1. Disabling shell registration + 15.5.1. Disabling shell registration - 14.6. Fonts + 15.6. Fonts - 14.6.1. Disabling automatic update of the fonts databases + 15.6.1. Disabling automatic update of the fonts databases -15. Options handling +16. Options handling - 15.1. Global default options - 15.2. Converting packages to use bsd.options.mk - 15.3. Option Names + 16.1. Global default options + 16.2. Converting packages to use bsd.options.mk + 16.3. Option Names -16. The build process +17. The build process - 16.1. Introduction - 16.2. Program location - 16.3. Directories used during the build process - 16.4. Running a phase - 16.5. The fetch phase + 17.1. Introduction + 17.2. Program location + 17.3. Directories used during the build process + 17.4. Running a phase + 17.5. The fetch phase - 16.5.1. What to fetch and where to get it from - 16.5.2. How are the files fetched? + 17.5.1. What to fetch and where to get it from + 17.5.2. How are the files fetched? - 16.6. The checksum phase - 16.7. The extract phase - 16.8. The patch phase - 16.9. The tools phase - 16.10. The wrapper phase - 16.11. The configure phase - 16.12. The build phase - 16.13. The test phase - 16.14. The install phase - 16.15. The package phase - 16.16. Cleaning up - 16.17. Other helpful targets + 17.6. The checksum phase + 17.7. The extract phase + 17.8. The patch phase + 17.9. The tools phase + 17.10. The wrapper phase + 17.11. The configure phase + 17.12. The build phase + 17.13. The test phase + 17.14. The install phase + 17.15. The package phase + 17.16. Cleaning up + 17.17. Other helpful targets -17. Tools needed for building or running +18. Tools needed for building or running - 17.1. Tools for pkgsrc builds - 17.2. Tools needed by packages - 17.3. Tools provided by platforms - 17.4. Questions regarding the tools + 18.1. Tools for pkgsrc builds + 18.2. Tools needed by packages + 18.3. Tools provided by platforms + 18.4. Questions regarding the tools -18. Making your package work +19. Making your package work - 18.1. General operation + 19.1. General operation - 18.1.1. Portability of packages - 18.1.2. How to pull in user-settable variables from mk.conf - 18.1.3. User interaction - 18.1.4. Handling licenses - 18.1.5. Restricted packages - 18.1.6. Handling dependencies - 18.1.7. Handling conflicts with other packages - 18.1.8. Packages that cannot or should not be built - 18.1.9. Packages which should not be deleted, once installed - 18.1.10. Handling packages with security problems - 18.1.11. How to handle incrementing versions when fixing an existing + 19.1.1. Portability of packages + 19.1.2. How to pull in user-settable variables from mk.conf + 19.1.3. User interaction + 19.1.4. Handling licenses + 19.1.5. Restricted packages + 19.1.6. Handling dependencies + 19.1.7. Handling conflicts with other packages + 19.1.8. Packages that cannot or should not be built + 19.1.9. Packages which should not be deleted, once installed + 19.1.10. Handling packages with security problems + 19.1.11. How to handle incrementing versions when fixing an existing package - 18.1.12. Substituting variable text in the package files (the SUBST + 19.1.12. Substituting variable text in the package files (the SUBST framework) - 18.2. Fixing problems in the fetch phase + 19.2. Fixing problems in the fetch phase - 18.2.1. Packages whose distfiles aren't available for plain downloading - 18.2.2. How to handle modified distfiles with the 'old' name + 19.2.1. Packages whose distfiles aren't available for plain downloading + 19.2.2. How to handle modified distfiles with the 'old' name - 18.3. Fixing problems in the configure phase + 19.3. Fixing problems in the configure phase - 18.3.1. Shared libraries - libtool - 18.3.2. Using libtool on GNU packages that already support libtool - 18.3.3. GNU Autoconf/Automake + 19.3.1. Shared libraries - libtool + 19.3.2. Using libtool on GNU packages that already support libtool + 19.3.3. GNU Autoconf/Automake - 18.4. Programming languages + 19.4. Programming languages - 18.4.1. C, C++, and Fortran - 18.4.2. Java - 18.4.3. Packages containing perl scripts - 18.4.4. Other programming languages + 19.4.1. C, C++, and Fortran + 19.4.2. Java + 19.4.3. Packages containing perl scripts + 19.4.4. Other programming languages - 18.5. Fixing problems in the build phase + 19.5. Fixing problems in the build phase - 18.5.1. Compiling C and C++ code conditionally - 18.5.2. How to handle compiler bugs - 18.5.3. Undefined reference to "..." - 18.5.4. Running out of memory + 19.5.1. Compiling C and C++ code conditionally + 19.5.2. How to handle compiler bugs + 19.5.3. Undefined reference to "..." + 19.5.4. Running out of memory - 18.6. Fixing problems in the install phase + 19.6. Fixing problems in the install phase - 18.6.1. Creating needed directories - 18.6.2. Where to install documentation - 18.6.3. Installing highscore files - 18.6.4. Adding DESTDIR support to packages - 18.6.5. Packages with hardcoded paths to other interpreters - 18.6.6. Packages installing perl modules - 18.6.7. Packages installing info files - 18.6.8. Packages installing man pages - 18.6.9. Packages installing GConf2 data files - 18.6.10. Packages installing scrollkeeper data files - 18.6.11. Packages installing X11 fonts - 18.6.12. Packages installing GTK2 modules - 18.6.13. Packages installing SGML or XML data - 18.6.14. Packages installing extensions to the MIME database - 18.6.15. Packages using intltool - 18.6.16. Packages installing startup scripts - 18.6.17. Packages installing TeX modules - 18.6.18. Packages supporting running binaries in emulation - 18.6.19. Packages installing hicolor theme icons - 18.6.20. Packages installing desktop files + 19.6.1. Creating needed directories + 19.6.2. Where to install documentation + 19.6.3. Installing highscore files + 19.6.4. Adding DESTDIR support to packages + 19.6.5. Packages with hardcoded paths to other interpreters + 19.6.6. Packages installing perl modules + 19.6.7. Packages installing info files + 19.6.8. Packages installing man pages + 19.6.9. Packages installing GConf2 data files + 19.6.10. Packages installing scrollkeeper data files + 19.6.11. Packages installing X11 fonts + 19.6.12. Packages installing GTK2 modules + 19.6.13. Packages installing SGML or XML data + 19.6.14. Packages installing extensions to the MIME database + 19.6.15. Packages using intltool + 19.6.16. Packages installing startup scripts + 19.6.17. Packages installing TeX modules + 19.6.18. Packages supporting running binaries in emulation + 19.6.19. Packages installing hicolor theme icons + 19.6.20. Packages installing desktop files - 18.7. Marking packages as having problems + 19.7. Marking packages as having problems -19. Debugging -20. Submitting and Committing +20. Debugging +21. Submitting and Committing - 20.1. Submitting binary packages - 20.2. Submitting source packages (for non-NetBSD-developers) - 20.3. General notes when adding, updating, or removing packages - 20.4. Committing: Importing a package into CVS - 20.5. Updating a package to a newer version - 20.6. Moving a package in pkgsrc + 21.1. Submitting binary packages + 21.2. Submitting source packages (for non-NetBSD-developers) + 21.3. General notes when adding, updating, or removing packages + 21.4. Committing: Importing a package into CVS + 21.5. Updating a package to a newer version + 21.6. Moving a package in pkgsrc -21. Frequently Asked Questions -22. GNOME packaging and porting +22. Frequently Asked Questions +23. 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.1. Meta packages + 23.2. Packaging a GNOME application + 23.3. Updating GNOME to a newer version + 23.4. Patching guidelines -Chapter 9. Creating a new pkgsrc package from scratch +Chapter 10. Creating a new pkgsrc package from scratch Table of Contents -9.1. Common types of packages +10.1. Common types of packages - 9.1.1. Perl modules - 9.1.2. KDE applications + 10.1.1. Perl modules + 10.1.2. KDE applications -9.2. Examples +10.2. Examples - 9.2.1. How the www/nvu package came into pkgsrc + 10.2.1. How the www/nvu package came into pkgsrc 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 @@ -3367,7 +3452,7 @@ package involves only a few steps. pkglint --explain or pkglint -e, which outputs additional explanations. 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 9.1, + instructions for the most common cases in the next section, Section 10.1, "Common types of packages". After you have followed the instructions over there, you can hopefully continue here. @@ -3377,7 +3462,7 @@ package involves only a few steps. edited the Makefile. 8. Now, run bmake to build the package. For the various things that can go - wrong in this phase, consult Chapter 18, Making your package work. + wrong in this phase, consult Chapter 19, Making your package work. 9. When the package builds fine, the next step is to install the package. Run bmake install and hope that everything works. @@ -3397,23 +3482,23 @@ package involves only a few steps. 13. Run bmake package to create a binary package from the set of installed files. -9.1. Common types of packages +10.1. Common types of packages -9.1.1. Perl modules +10.1.1. Perl modules Simple Perl modules are handled automatically by url2pkg, including dependencies. -9.1.2. KDE applications +10.1.2. KDE applications KDE applications should always include meta-pkgs/kde3/kde3.mk, which contains numerous settings that are typical of KDE packages. -9.2. Examples +10.2. Examples -9.2.1. How the www/nvu package came into pkgsrc +10.2.1. How the www/nvu package came into pkgsrc -9.2.1.1. The initial package +10.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, @@ -3470,7 +3555,7 @@ Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done! Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-) -9.2.1.2. Fixing all kinds of problems to make the package work +10.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 @@ -3593,7 +3678,7 @@ 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. -9.2.1.3. Installing the package +10.2.1.3. Installing the package $ bmake CHECK_FILES=no install [...] @@ -3601,34 +3686,34 @@ $ bmake print-PLIST >PLIST $ bmake deinstall $ bmake install -Chapter 10. Package components - files, directories and contents +Chapter 11. Package components - files, directories and contents Table of Contents -10.1. Makefile -10.2. distinfo -10.3. patches/* +11.1. Makefile +11.2. distinfo +11.3. patches/* - 10.3.1. Structure of a single patch file - 10.3.2. Creating patch files - 10.3.3. Sources where the patch files come from - 10.3.4. Patching guidelines - 10.3.5. Feedback to the author + 11.3.1. Structure of a single patch file + 11.3.2. Creating patch files + 11.3.3. Sources where the patch files come from + 11.3.4. Patching guidelines + 11.3.5. Feedback to the author -10.4. Other mandatory files -10.5. Optional files +11.4. Other mandatory files +11.5. Optional files - 10.5.1. Files affecting the binary package - 10.5.2. Files affecting the build process - 10.5.3. Files affecting nothing at all + 11.5.1. Files affecting the binary package + 11.5.2. Files affecting the build process + 11.5.3. Files affecting nothing at all -10.6. work* -10.7. files/* +11.6. work* +11.7. files/* Whenever you're preparing a package, there are a number of files involved which are described in the following sections. -10.1. Makefile +11.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, @@ -3672,7 +3757,7 @@ mostly historical and has no further meaning. converters games mbone print x11 * MASTER_SITES, DYNAMIC_MASTER_SITES, DIST_SUBDIR, EXTRACT_SUFX and DISTFILES - are discussed in detail in Section 16.5, "The fetch phase". + are discussed in detail in Section 17.5, "The fetch phase". The second section contains information about separately downloaded patches, if any. @@ -3732,10 +3817,10 @@ Please pay attention to the following gotchas: * Replace /usr/local with "${PREFIX}" in all files (see patches, below). - * If the package installs any info files, see Section 18.6.7, "Packages + * If the package installs any info files, see Section 19.6.7, "Packages installing info files". -10.2. distinfo +11.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 @@ -3745,7 +3830,7 @@ algorithms, all distfiles are protected using both SHA1 and RMD160 message digests, as well as the file size. The distinfo file also contains the checksums for all the patches found in the -patches directory (see Section 10.3, "patches/*"). +patches directory (see Section 11.3, "patches/*"). To regenerate the distinfo file, use the make makedistinfo or make mdi command. @@ -3754,7 +3839,7 @@ example www/navigator). 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. -10.3. patches/* +11.3. patches/* Many packages still don't work out-of-the box on the various platforms that are supported by pkgsrc. Therefore, a number of custom patch files are needed to @@ -3764,7 +3849,7 @@ In the patch phase, these patches are applied to the files in WRKSRC directory after extracting them, in alphabetic order, so patch-aa is applied before patch-ab, etc. -10.3.1. Structure of a single patch file +11.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 @@ -3791,7 +3876,7 @@ 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. -10.3.2. Creating patch files +11.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 @@ -3807,7 +3892,7 @@ patchdiff. Copy the patches you want to use or update from the work/.newpatches directory to patches/. When you have finished a package, remember to generate the checksums for the -patch files by using the make makepatchsum command, see Section 10.2, +patch files by using the make makepatchsum command, see Section 11.2, "distinfo". When adding a patch that corrects a problem in the distfile (rather than e.g. @@ -3817,7 +3902,7 @@ usually makes it possible to remove the patch in future version. The file names of the patch files are usually of the form patch-[a-z][a-z]. -10.3.3. Sources where the patch files come from +11.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 @@ -3837,7 +3922,7 @@ for pkgsrc/graphics/png, keep it in $LOCALPATCHES/graphics/png/mypatch. All files in the named directory are expected to be patch files, and they are applied after pkgsrc patches are applied. -10.3.4. Patching guidelines +11.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 @@ -3861,7 +3946,7 @@ doesn't work unless it is right! Some typical examples: -Table 10.1. Patching examples +Table 11.1. Patching examples +-------------------------------------------------------------------------------------------+ | Where | Incorrect | Correct | @@ -3893,7 +3978,7 @@ For more information, please read the Making packager-friendly software article to package; all the suggestions in it were collected from our experience in pkgsrc work, so they are possibly helpful when creating patches too. -10.3.5. Feedback to the author +11.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 @@ -3910,7 +3995,7 @@ much hassle. Support the idea of free software! -10.4. Other mandatory files +11.4. Other mandatory files DESCR @@ -3924,12 +4009,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 12, PLIST issues for more + and the location of inserted files. See Chapter 13, PLIST issues for more information. -10.5. Optional files +11.5. Optional files -10.5.1. Files affecting the binary package +11.5.1. Files affecting the binary package INSTALL @@ -3937,7 +4022,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 14.1, "Files and + pkg_create(1) for more information. See also Section 15.1, "Files and directories outside the installation prefix". DEINSTALL @@ -3969,7 +4054,7 @@ ALTERNATIVES FIXME: There is no documentation on the alternatives framework. -10.5.2. Files affecting the build process +11.5.2. Files affecting the build process Makefile.common @@ -3982,7 +4067,7 @@ Makefile.common buildlink3.mk This file contains the dependency information for the buildlink3 framework - (see Chapter 13, Buildlink methodology). + (see Chapter 14, Buildlink methodology). hacks.mk @@ -3993,11 +4078,11 @@ hacks.mk options.mk This file contains the code for the package-specific options (see - Chapter 15, 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. -10.5.3. Files affecting nothing at all +11.5.3. Files affecting nothing at all README* @@ -4009,7 +4094,7 @@ TODO This file contains things that need to be done to make the package even better. -10.6. work* +11.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 @@ -4017,7 +4102,7 @@ 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. -10.7. files/* +11.7. files/* If you have any files that you wish to be placed in the package prior to configuration or building, you could place these files here and use a ${CP} @@ -4030,22 +4115,22 @@ variable to point to the other package's files directory, e.g.: FILESDIR=${.CURDIR}/../xemacs/files -Chapter 11. Programming in Makefiles +Chapter 12. Programming in Makefiles Table of Contents -11.1. Caveats -11.2. Makefile variables +12.1. Caveats +12.2. Makefile variables - 11.2.1. Naming conventions + 12.2.1. Naming conventions -11.3. Code snippets +12.3. Code snippets - 11.3.1. Adding things to a list - 11.3.2. Converting an internal list into an external list - 11.3.3. Passing variables to a shell command - 11.3.4. Quoting guideline - 11.3.5. Workaround for a bug in BSD Make + 12.3.1. Adding things to a list + 12.3.2. Converting an internal list into an external list + 12.3.3. Passing variables to a shell command + 12.3.4. Quoting guideline + 12.3.5. Workaround for a bug in BSD Make 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 @@ -4061,7 +4146,7 @@ used. This chapter describes some patterns, that appear quite often in Makefiles, including the pitfalls that come along with them. -11.1. Caveats +12.1. Caveats * 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 @@ -4089,7 +4174,7 @@ including the pitfalls that come along with them. pressing ^C. This does not happen when one of the commands fails (like false(1) above). -11.2. Makefile variables +12.2. Makefile variables Makefile variables contain strings that can be processed using the five operators ``='', ``+='', ``?='', ``:='', and ``!='', which are described in the @@ -4140,7 +4225,7 @@ Strings and two types of lists. elements can contain any characters, including whitespace. That's why they cannot be used in .for loops. Examples are DISTFILES and MASTER_SITES. -11.2.1. Naming conventions +12.2.1. Naming conventions * All variable names starting with an underscore are reserved for use by the pkgsrc infrastructure. They shall not be used by package Makefiles. @@ -4151,13 +4236,13 @@ Strings and two types of lists. * All list variables should have a ``plural'' name, e.g. PKG_OPTIONS or DISTFILES. -11.3. Code snippets +12.3. Code snippets This section presents you with some code snippets you should use in your own code. If you don't find anything appropriate here, you should test your code and add it here. -11.3.1. Adding things to a list +12.3.1. Adding things to a list STRING= foo * bar `date` INT_LIST= # empty @@ -4175,7 +4260,7 @@ all other cases, you must not add a quoting level. You must not merge internal and external lists, unless you are sure that all entries are correctly interpreted in both lists. -11.3.2. Converting an internal list into an external list +12.3.2. Converting an internal list into an external list EXT_LIST= # empty .for i in ${INT_LIST} @@ -4186,7 +4271,7 @@ This code converts the internal list INT_LIST into the external list EXT_LIST. As the elements of an internal list are unquoted they must be quoted here. The reason for appending "" is explained below. -11.3.3. Passing variables to a shell command +12.3.3. Passing variables to a shell command Sometimes you may want to print an arbitrary string. There are many ways to get it wrong and only few that can handle every nastiness. @@ -4228,7 +4313,7 @@ done when adding elements to the list. As internal lists shall not be passed to the shell, there is no example for it. -11.3.4. Quoting guideline +12.3.4. Quoting guideline There are many possible sources of wrongly quoted variables. This section lists some of the commonly known ones. @@ -4293,7 +4378,7 @@ some of the commonly known ones. line the arguments of the echo(1) command from the first line. To avoid this, write ${i:Q}"". -11.3.5. Workaround for a bug in BSD Make +12.3.5. Workaround for a bug in BSD Make The pkgsrc bmake program does not handle the following assignment correctly. In case _othervar_ contains a ``-'' character, one of the closing braces is @@ -4304,18 +4389,18 @@ VAR:= ${VAR:N${_othervar_:C/-//}} For a more complex code snippet and a workaround, see the package regress/ make-quoting, testcase bug1. -Chapter 12. PLIST issues +Chapter 13. PLIST issues Table of Contents -12.1. RCS ID -12.2. Semi-automatic PLIST generation -12.3. Tweaking output of make print-PLIST -12.4. Variable substitution in PLIST -12.5. Man page compression -12.6. Changing PLIST source with PLIST_SRC -12.7. Platform-specific and differing PLISTs -12.8. Sharing directories between packages +13.1. RCS ID +13.2. Semi-automatic PLIST generation +13.3. Tweaking output of make print-PLIST +13.4. Variable substitution in PLIST +13.5. Man page compression +13.6. Changing PLIST source with PLIST_SRC +13.7. Platform-specific and differing PLISTs +13.8. Sharing directories between packages 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 @@ -4323,22 +4408,22 @@ 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!). -12.1. RCS ID +13.1. RCS ID Be sure to add a RCS ID line as the first thing in any PLIST file you write: @comment $NetBSD$ -12.2. Semi-automatic PLIST generation +13.2. Semi-automatic PLIST generation You can use the make print-PLIST command to output a PLIST that matches any new -files since the package was extracted. See Section 16.17, "Other helpful +files since the package was extracted. See Section 17.17, "Other helpful targets" for more information on this target. -12.3. Tweaking output of make print-PLIST +13.3. Tweaking output of make print-PLIST -If you have used any of the *-dirs packages, as explained in Section 12.8, +If you have used any of the *-dirs packages, as explained in Section 13.8, "Sharing directories between packages", you may have noticed that make print-PLIST outputs a set of @comments instead of real @dirrm lines. You can also do this for specific directories and files, so that the results of that @@ -4361,7 +4446,7 @@ converted to @comments: PRINT_PLIST_AWK+= /^@dirrm share\/specific/ { print "@comment " $$0; next; } -12.4. Variable substitution in PLIST +13.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: @@ -4397,14 +4482,14 @@ bsd.pkg.mk (and search for PLIST_SUBST). 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 10.5, "Optional files"): +MESSAGE_SUBST (see Section 11.5, "Optional files"): PLIST_SUBST+= SOMEVAR="somevalue" This replaces all occurrences of "${SOMEVAR}" in the PLIST with "somevalue". -12.5. Man page compression +13.5. Man page compression 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 @@ -4412,14 +4497,14 @@ 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. -12.6. Changing PLIST source with PLIST_SRC +13.6. Changing PLIST source with PLIST_SRC 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. -12.7. Platform-specific and differing PLISTs +13.7. Platform-specific and differing PLISTs 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 @@ -4435,7 +4520,7 @@ following files: * PLIST.common_end -12.8. Sharing directories between packages +13.8. Sharing directories between packages A "shared directory" is a directory where multiple (and unrelated) packages install files. These directories are problematic because you have to add @@ -4485,20 +4570,20 @@ Note that even if your package is using $X11BASE, it must not depend on the *-x11-dirs packages. Just specify the name without that part and pkgsrc (in particular, mk/dirs.mk) will take care of it. -Chapter 13. Buildlink methodology +Chapter 14. Buildlink methodology Table of Contents -13.1. Converting packages to use buildlink3 -13.2. Writing buildlink3.mk files +14.1. Converting packages to use buildlink3 +14.2. Writing buildlink3.mk files - 13.2.1. Anatomy of a buildlink3.mk file - 13.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files + 14.2.1. Anatomy of a buildlink3.mk file + 14.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files -13.3. Writing builtin.mk files +14.3. Writing builtin.mk files - 13.3.1. Anatomy of a builtin.mk file - 13.3.2. Global preferences for native or pkgsrc software + 14.3.1. Anatomy of a builtin.mk file + 14.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 @@ -4519,7 +4604,7 @@ 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. -13.1. Converting packages to use buildlink3 +14.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: @@ -4585,7 +4670,7 @@ issues: The comments in those buildlink3.mk files provide a more complete description of how to use them properly. -13.2. Writing buildlink3.mk files +14.2. Writing buildlink3.mk files 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 @@ -4601,7 +4686,7 @@ following command will generate a good starting point for buildlink3.mk files: % createbuildlink >buildlink3.mk -13.2.1. Anatomy of a buildlink3.mk file +14.2.1. Anatomy of a buildlink3.mk file The following real-life example buildlink3.mk is taken from pkgsrc/graphics/ tiff: @@ -4695,7 +4780,7 @@ 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. -13.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files +14.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files The situation that requires increasing the dependency listed in BUILDLINK_API_DEPENDS.pkg after a package update is when the API or interface @@ -4714,7 +4799,7 @@ change. This is needed so that binary packages made using it will require the correct package dependency and not settle for an older one which will not contain the necessary shared libraries. -See Section 18.1.6, "Handling dependencies" for more information about +See Section 19.1.6, "Handling dependencies" for more information about dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and ABI_DEPENDS definitions. @@ -4726,7 +4811,7 @@ dependencies. Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to BUILDLINK_API_DEPENDS.pkg. -13.3. Writing builtin.mk files +14.3. Writing builtin.mk files Some packages in pkgsrc install headers and libraries that coincide with headers and libraries present in the base system. Aside from a buildlink3.mk @@ -4744,7 +4829,7 @@ The only requirements of a builtin.mk file for pkg are: 3. It should be written to allow multiple inclusion. This is very important and takes careful attention to Makefile coding. -13.3.1. Anatomy of a builtin.mk file +14.3.1. Anatomy of a builtin.mk file The following is the recommended template for builtin.mk files: @@ -4809,7 +4894,7 @@ 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). -13.3.2. Global preferences for native or pkgsrc software +14.3.2. Global preferences for native or pkgsrc software 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 @@ -4829,34 +4914,34 @@ PREFER_NATIVE= getopt skey tcp_wrappers A package must have a builtin.mk file to be listed in PREFER_NATIVE, otherwise it is simply ignored in that list. -Chapter 14. The pkginstall framework +Chapter 15. The pkginstall framework Table of Contents -14.1. Files and directories outside the installation prefix +15.1. Files and directories outside the installation prefix - 14.1.1. Directory manipulation - 14.1.2. File manipulation + 15.1.1. Directory manipulation + 15.1.2. File manipulation -14.2. Configuration files +15.2. Configuration files - 14.2.1. How PKG_SYSCONFDIR is set - 14.2.2. Telling the software where configuration files are - 14.2.3. Patching installations - 14.2.4. Disabling handling of configuration files + 15.2.1. How PKG_SYSCONFDIR is set + 15.2.2. Telling the software where configuration files are + 15.2.3. Patching installations + 15.2.4. Disabling handling of configuration files -14.3. System startup scripts +15.3. System startup scripts - 14.3.1. Disabling handling of system startup scripts + 15.3.1. Disabling handling of system startup scripts -14.4. System users and groups -14.5. System shells +15.4. System users and groups +15.5. System shells - 14.5.1. Disabling shell registration + 15.5.1. Disabling shell registration -14.6. Fonts +15.6. Fonts - 14.6.1. Disabling automatic update of the fonts databases + 15.6.1. Disabling automatic update of the fonts databases This chapter describes the framework known as pkginstall, whose key features are: @@ -4885,7 +4970,7 @@ 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. -14.1. Files and directories outside the installation prefix +15.1. Files and directories outside the installation prefix 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 @@ -4914,7 +4999,7 @@ 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. -14.1.1. Directory manipulation +15.1.1. Directory manipulation The following variables can be set to request the creation of directories anywhere in the file system: @@ -4936,7 +5021,7 @@ anywhere in the file system: The difference between the two is exactly the same as their non-PERMS counterparts. -14.1.2. File manipulation +15.1.2. File manipulation 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 @@ -4966,7 +5051,7 @@ handle files outside the installation prefix: The difference between the two is exactly the same as their non-PERMS counterparts. -14.2. Configuration files +15.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 @@ -4977,7 +5062,7 @@ 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. -14.2.1. How PKG_SYSCONFDIR is set +15.2.1. How PKG_SYSCONFDIR is set As said before, the PKG_SYSCONFDIR variable specifies where configuration files shall be installed. Its contents are set based upon the following variables: @@ -5017,9 +5102,9 @@ basically the following: 3. Otherwise, it is set to ${PKG_SYSCONFBASE}. It is worth mentioning that ${PKG_SYSCONFDIR} is automatically added to -OWN_DIRS. See Section 14.1.1, "Directory manipulation" what this means. +OWN_DIRS. See Section 15.1.1, "Directory manipulation" what this means. -14.2.2. Telling the software where configuration files are +15.2.2. Telling the software where configuration files are 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 @@ -5033,7 +5118,7 @@ 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). -14.2.3. Patching installations +15.2.3. Patching installations As said before, pkginstall automatically handles configuration files. This means that the packages themselves must not touch the contents of $ @@ -5050,7 +5135,7 @@ 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 14.1.2, "File manipulation" for information about their syntax and +Section 15.1.2, "File manipulation" for information about their syntax and their purpose. Here is an example, taken from the mail/mutt package: EGDIR= ${PREFIX}/share/doc/mutt/samples @@ -5059,16 +5144,16 @@ CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc Note that the EGDIR variable is specific to that package and has no meaning outside it. -14.2.4. Disabling handling of configuration files +15.2.4. Disabling handling of configuration files The automatic copying of config files can be toggled by setting the environment variable PKG_CONFIG prior to package installation. -14.3. System startup scripts +15.3. System startup scripts 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 14.1, "Files and directories +Therefore, the same rules described in Section 15.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. @@ -5096,14 +5181,14 @@ automated fashion: 3. Add code to the installation scripts to copy the startup script from the examples hierarchy into the system-wide startup scripts directory. -14.3.1. Disabling handling of system startup scripts +15.3.1. Disabling handling of system startup scripts 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. -14.4. System users and groups +15.4. System users and groups If a package needs to create special users and/or groups during installation, it can do so by using the pkginstall framework. @@ -5132,7 +5217,7 @@ 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. -14.5. System shells +15.5. System shells 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 @@ -5146,12 +5231,12 @@ shells/zsh: PKG_SHELL= ${PREFIX}/bin/zsh -14.5.1. Disabling shell registration +15.5.1. Disabling shell registration The automatic registration of shell interpreters can be disabled by the administrator by setting the PKG_REGISTER_SHELLS environment variable to NO. -14.6. Fonts +15.6. Fonts 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 @@ -5167,18 +5252,18 @@ example, taken from fonts/dbz-ttf: FONTS_DIRS.ttf= ${PREFIX}/lib/X11/fonts/TTF -14.6.1. Disabling automatic update of the fonts databases +15.6.1. Disabling automatic update of the fonts databases The automatic update of fonts databases can be disabled by the administrator by setting the PKG_UPDATE_FONTS_DB environment variable to NO. -Chapter 15. Options handling +Chapter 16. Options handling Table of Contents -15.1. Global default options -15.2. Converting packages to use bsd.options.mk -15.3. Option Names +16.1. Global default options +16.2. Converting packages to use bsd.options.mk +16.3. Option Names 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 @@ -5187,13 +5272,13 @@ 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. -15.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. -15.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, @@ -5311,7 +5396,7 @@ PKG_OPTIONS: .if !empty(PKG_OPTIONS:Moption) -15.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 @@ -5332,33 +5417,33 @@ 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. "Enable ispell support." The file is sorted by option names. -Chapter 16. The build process +Chapter 17. The build process Table of Contents -16.1. Introduction -16.2. Program location -16.3. Directories used during the build process -16.4. Running a phase -16.5. The fetch phase - - 16.5.1. What to fetch and where to get it from - 16.5.2. How are the files fetched? - -16.6. The checksum phase -16.7. The extract phase -16.8. The patch phase -16.9. The tools phase -16.10. The wrapper phase -16.11. The configure phase -16.12. The build phase -16.13. The test phase -16.14. The install phase -16.15. The package phase -16.16. Cleaning up -16.17. Other helpful targets - -16.1. Introduction +17.1. Introduction +17.2. Program location +17.3. Directories used during the build process +17.4. Running a phase +17.5. The fetch phase + + 17.5.1. What to fetch and where to get it from + 17.5.2. How are the files fetched? + +17.6. The checksum phase +17.7. The extract phase +17.8. The patch phase +17.9. The tools phase +17.10. The wrapper phase +17.11. The configure phase +17.12. The build phase +17.13. The test phase +17.14. The install phase +17.15. The package phase +17.16. Cleaning up +17.17. Other helpful targets + +17.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), @@ -5380,7 +5465,7 @@ 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. -16.2. Program location +17.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 @@ -5390,7 +5475,7 @@ 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 10.3, "patches/*" and Section 18.3.1, "Shared libraries - libtool" +See Section 11.3, "patches/*" and Section 19.3.1, "Shared libraries - libtool" for more details. When choosing which of these variables to use, follow the following rules: @@ -5458,7 +5543,7 @@ When choosing which of these variables to use, follow the following rules: the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/ man. -16.3. Directories used during the build process +17.3. Directories used during the build process When building a package, a number of directories is used to store source files, temporary files, pkgsrc-internal files, and so on. These directories are @@ -5497,7 +5582,7 @@ WRKSRC it's the only directory entry that isn't hidden. This variable may be changed by a package Makefile. -16.4. Running a phase +17.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 @@ -5505,13 +5590,13 @@ 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. -16.5. The fetch phase +17.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. -16.5.1. What to fetch and where to get it from +17.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 @@ -5590,7 +5675,7 @@ MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/} Note the trailing slash after the subdirectory name. -16.5.2. How are the files fetched? +17.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 @@ -5610,7 +5695,7 @@ 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. -16.6. The checksum phase +17.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, @@ -5618,7 +5703,7 @@ 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. -16.7. The extract phase +17.7. The extract phase 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. @@ -5651,25 +5736,25 @@ file that is going to be extracted. And if that still does not suffice, you can override the do-extract target in the package Makefile. -16.8. The patch phase +17.8. The patch phase 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 10.3, "patches/*" for more details. +Section 11.3, "patches/*" for more details. By default patch(1) is given special args to make it fail if the patches apply with some lines of fuzz. Please fix (regen) the patches so that they apply cleanly. The rationale behind this is that patches that don't apply cleanly may end up being applied in the wrong place, and cause severe harm there. -16.9. The tools phase +17.9. The tools phase -This is covered in Chapter 17, Tools needed for building or running. +This is covered in Chapter 18, Tools needed for building or running. -16.10. The wrapper phase +17.10. The wrapper phase This phase creates wrapper programs for the compilers and linkers. The following variables can be used to tweak the wrappers. @@ -5699,7 +5784,7 @@ WRAPPER_TRANSFORM_CMDS A list of transformation commands. [TODO: investigate further] -16.11. The configure phase +17.11. The configure phase 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 @@ -5732,7 +5817,7 @@ variable. If there is no configure step at all, set NO_CONFIGURE to "yes". -16.12. The build phase +17.12. The build phase For building a package, a rough equivalent of the following code is executed. @@ -5756,11 +5841,11 @@ BUILD_TARGET defaults to "all". If there is no build step at all, set NO_BUILD to "yes". -16.13. The test phase +17.13. The test phase [TODO] -16.14. The install phase +17.14. The install phase 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. @@ -5848,7 +5933,7 @@ INSTALLATION_DIRS 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. -16.15. The package phase +17.15. The package phase 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 @@ -5862,13 +5947,13 @@ If there should be no binary package, set NO_PACKAGE to "yes". This should only be used in rare cases, like when a package definitely is only usable on the machine where it is built and even then, a binary package can be useful. -16.16. Cleaning up +17.16. Cleaning up 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. -16.17. Other helpful targets +17.17. Other helpful targets pre/post-* @@ -6117,14 +6202,14 @@ print-PLIST 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! - See Section 12.3, "Tweaking output of make print-PLIST" for more + See Section 13.3, "Tweaking output of make print-PLIST" for more information on this target. bulk-package Used to do bulk builds. If an appropriate binary package already exists, no action is taken. If not, this target will compile, install and package it - (and its depends, if PKG_DEPENDS is set properly. See Section 6.3.1, + (and its depends, if PKG_DEPENDS is set properly. See Section 7.3.1, "Configuration"). After creating the binary package, the sources, the just-installed package and its required packages are removed, preserving free disk space. @@ -6149,14 +6234,14 @@ bulk-install Beware that this target may deinstall all packages installed on a system! -Chapter 17. Tools needed for building or running +Chapter 18. Tools needed for building or running Table of Contents -17.1. Tools for pkgsrc builds -17.2. Tools needed by packages -17.3. Tools provided by platforms -17.4. Questions regarding the tools +18.1. Tools for pkgsrc builds +18.2. Tools needed by packages +18.3. Tools provided by platforms +18.4. Questions regarding the tools 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 @@ -6177,7 +6262,7 @@ 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 +18.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 @@ -6186,7 +6271,7 @@ 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 +18.2. Tools needed by packages In the following examples, the :pkgsrc means to use the pkgsrc version and not the native version for a build dependency. And the :run means that it is used @@ -6204,7 +6289,7 @@ 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 +18.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/ @@ -6218,107 +6303,107 @@ TOOLS_PLATFORM.bzcat?= /usr/bin/bzip2 -cd TOOLS_PLATFORM.true?= true # shell builtin -17.4. Questions regarding the tools +18.4. Questions regarding the tools -17.4.1. How do I add a new tool? -17.4.2. How do I get a list of all available tools? -17.4.3. How can I get a list of all the tools that a package is using while +18.4.1. How do I add a new tool? +18.4.2. How do I get a list of all available tools? +18.4.3. How can I get a list of all the tools that a package is using while being built? I want to know whether it uses sed or not. -17.4.1. How do I add a new tool? +18.4.1. How do I add a new tool? TODO -17.4.2. How do I get a list of all available tools? +18.4.2. How do I get a list of all available tools? TODO -17.4.3. How can I get a list of all the tools that a package is using while +18.4.3. How can I get a list of all the tools that a package is using while being built? I want to know whether it uses sed or not. Currently, you can't. (TODO: But I want to be able to do it.) -Chapter 18. Making your package work +Chapter 19. Making your package work Table of Contents -18.1. General operation - - 18.1.1. Portability of packages - 18.1.2. How to pull in user-settable variables from mk.conf - 18.1.3. User interaction - 18.1.4. Handling licenses - 18.1.5. Restricted packages - 18.1.6. Handling dependencies - 18.1.7. Handling conflicts with other packages - 18.1.8. Packages that cannot or should not be built - 18.1.9. Packages which should not be deleted, once installed - 18.1.10. Handling packages with security problems - 18.1.11. How to handle incrementing versions when fixing an existing +19.1. General operation + + 19.1.1. Portability of packages + 19.1.2. How to pull in user-settable variables from mk.conf + 19.1.3. User interaction + 19.1.4. Handling licenses + 19.1.5. Restricted packages + 19.1.6. Handling dependencies + 19.1.7. Handling conflicts with other packages + 19.1.8. Packages that cannot or should not be built + 19.1.9. Packages which should not be deleted, once installed + 19.1.10. Handling packages with security problems + 19.1.11. How to handle incrementing versions when fixing an existing package - 18.1.12. Substituting variable text in the package files (the SUBST + 19.1.12. Substituting variable text in the package files (the SUBST framework) -18.2. Fixing problems in the fetch phase +19.2. Fixing problems in the fetch phase - 18.2.1. Packages whose distfiles aren't available for plain downloading - 18.2.2. How to handle modified distfiles with the 'old' name + 19.2.1. Packages whose distfiles aren't available for plain downloading + 19.2.2. How to handle modified distfiles with the 'old' name -18.3. Fixing problems in the configure phase +19.3. Fixing problems in the configure phase - 18.3.1. Shared libraries - libtool - 18.3.2. Using libtool on GNU packages that already support libtool - 18.3.3. GNU Autoconf/Automake + 19.3.1. Shared libraries - libtool + 19.3.2. Using libtool on GNU packages that already support libtool + 19.3.3. GNU Autoconf/Automake -18.4. Programming languages +19.4. Programming languages - 18.4.1. C, C++, and Fortran - 18.4.2. Java - 18.4.3. Packages containing perl scripts - 18.4.4. Other programming languages + 19.4.1. C, C++, and Fortran + 19.4.2. Java + 19.4.3. Packages containing perl scripts + 19.4.4. Other programming languages -18.5. Fixing problems in the build phase +19.5. Fixing problems in the build phase - 18.5.1. Compiling C and C++ code conditionally - 18.5.2. How to handle compiler bugs - 18.5.3. Undefined reference to "..." - 18.5.4. Running out of memory + 19.5.1. Compiling C and C++ code conditionally + 19.5.2. How to handle compiler bugs + 19.5.3. Undefined reference to "..." + 19.5.4. Running out of memory -18.6. Fixing problems in the install phase +19.6. Fixing problems in the install phase - 18.6.1. Creating needed directories - 18.6.2. Where to install documentation - 18.6.3. Installing highscore files - 18.6.4. Adding DESTDIR support to packages - 18.6.5. Packages with hardcoded paths to other interpreters - 18.6.6. Packages installing perl modules - 18.6.7. Packages installing info files - 18.6.8. Packages installing man pages - 18.6.9. Packages installing GConf2 data files - 18.6.10. Packages installing scrollkeeper data files - 18.6.11. Packages installing X11 fonts - 18.6.12. Packages installing GTK2 modules - 18.6.13. Packages installing SGML or XML data - 18.6.14. Packages installing extensions to the MIME database - 18.6.15. Packages using intltool - 18.6.16. Packages installing startup scripts - 18.6.17. Packages installing TeX modules - 18.6.18. Packages supporting running binaries in emulation - 18.6.19. Packages installing hicolor theme icons - 18.6.20. Packages installing desktop files + 19.6.1. Creating needed directories + 19.6.2. Where to install documentation + 19.6.3. Installing highscore files + 19.6.4. Adding DESTDIR support to packages + 19.6.5. Packages with hardcoded paths to other interpreters + 19.6.6. Packages installing perl modules + 19.6.7. Packages installing info files + 19.6.8. Packages installing man pages + 19.6.9. Packages installing GConf2 data files + 19.6.10. Packages installing scrollkeeper data files + 19.6.11. Packages installing X11 fonts + 19.6.12. Packages installing GTK2 modules + 19.6.13. Packages installing SGML or XML data + 19.6.14. Packages installing extensions to the MIME database + 19.6.15. Packages using intltool + 19.6.16. Packages installing startup scripts + 19.6.17. Packages installing TeX modules + 19.6.18. Packages supporting running binaries in emulation + 19.6.19. Packages installing hicolor theme icons + 19.6.20. Packages installing desktop files -18.7. Marking packages as having problems +19.7. Marking packages as having problems -18.1. General operation +19.1. General operation -18.1.1. Portability of packages +19.1.1. Portability of packages One appealing feature of pkgsrc is that it runs on many different platforms. As a result, it is important to ensure, where possible, that packages in pkgsrc are portable. This chapter mentions some particular details you should pay attention to while working on pkgsrc. -18.1.2. How to pull in user-settable variables from mk.conf +19.1.2. How to pull in user-settable variables from mk.conf The pkgsrc user can configure pkgsrc by overriding several variables in the file pointed to by MAKECONF, which is mk.conf by default. When you want to use @@ -6338,7 +6423,7 @@ Note Currently there is no exhaustive list of all variables that tells you whether they can be used at load time or only at run time, but it is in preparation. -18.1.3. User interaction +19.1.3. User interaction Occasionally, packages require interaction from the user, and this can be in a number of ways: @@ -6368,7 +6453,7 @@ INTERACTIVE_STAGE= configure install The user can then decide to skip this package by setting the BATCH variable. -18.1.4. Handling licenses +19.1.4. Handling licenses Authors of software can choose the licence under which software can be copied. This is due to copyright law, and reasons for license choices are outside the @@ -6446,7 +6531,7 @@ Another problem with such usage is that it does not enable a user to tell pkgsrc to proceed for a single package without also telling pkgsrc to proceed for all packages with that tag. -18.1.5. Restricted packages +19.1.5. Restricted packages Some licenses restrict how software may be re-distributed. Because a license tag is required unless the package is Free or Open Source, all packages with @@ -6502,13 +6587,13 @@ Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic make variables to denote restrictions is deprecated, because they unconditionally prevent users from generating binary packages! -18.1.6. Handling dependencies +19.1.6. Handling dependencies Your package may depend on some other package being present - and there are various ways of expressing this dependency. pkgsrc supports the BUILD_DEPENDS and 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 13, Buildlink methodology for more +uses the variables named above. See Chapter 14, Buildlink methodology for more information. The basic difference between the two variables is as follows: The DEPENDS @@ -6597,7 +6682,7 @@ version numbers recognized by pkg_info(1). systems that may have different versions of binary packages installed. For security fixes, please update the package vulnerabilities file. See - Section 18.1.10, "Handling packages with security problems" for more + Section 19.1.10, "Handling packages with security problems" for more information. 4. If your package needs some executable to be able to run correctly and if @@ -6616,7 +6701,7 @@ distribution files to DISTFILES, so they will be extracted automatically. See the print/ghostscript package for an example. (It relies on the jpeg sources being present in source form during the build.) -18.1.7. Handling conflicts with other packages +19.1.7. Handling conflicts with other packages Your package may conflict with other packages a user might already have installed on his system, e.g. if your package installs the same set of files as @@ -6640,7 +6725,7 @@ Packages will automatically conflict with other packages with the name prefix and a different version string. "Xaw3d-1.5" e.g. will automatically conflict with the older version "Xaw3d-1.3". -18.1.8. Packages that cannot or should not be built +19.1.8. Packages that cannot or should not be built There are several reasons why a package might be instructed to not build under certain circumstances. If the package builds and runs on most platforms, the @@ -6661,7 +6746,7 @@ functionality already provided by the system), set PKG_SKIP_REASON to a descriptive message. If the package should fail because some preconditions are not met, set PKG_FAIL_REASON to a descriptive message. -18.1.9. Packages which should not be deleted, once installed +19.1.9. Packages which should not be deleted, once installed To ensure that a package may not be deleted, once it has been installed, the PKG_PRESERVE definition should be set in the package Makefile. This will be @@ -6669,7 +6754,7 @@ carried into any binary package that is made from this pkgsrc entry. A "preserved" package will not be deleted using pkg_delete(1) unless the "-f" option is used. -18.1.10. Handling packages with security problems +19.1.10. Handling packages with security problems When a vulnerability is found, this should be noted in localsrc/security/ advisories/pkg-vulnerabilities, and after committing that file, use make upload @@ -6685,7 +6770,7 @@ submit a pullup request! Binary packages already on ftp.NetBSD.org will be handled semi-automatically by a weekly cron job. -18.1.11. How to handle incrementing versions when fixing an existing package +19.1.11. How to handle incrementing versions when fixing an existing package When making fixes to an existing package it can be useful to change the version number in PKGNAME. To avoid conflicting with future versions by the original @@ -6734,7 +6819,7 @@ Examples of changes that do merit an increase to PKGREVISION include: PKGREVISION must also be incremented when dependencies have ABI changes. -18.1.12. Substituting variable text in the package files (the SUBST framework) +19.1.12. Substituting variable text in the package files (the SUBST framework) When you want to replace the same text in multiple files or when the replacement text varies, patches alone cannot help. This is where the SUBST @@ -6785,9 +6870,9 @@ blocks look uniform. There are some more variables, but they are so seldomly used that they are only documented in the mk/subst.mk file. -18.2. Fixing problems in the fetch phase +19.2. Fixing problems in the fetch phase -18.2.1. Packages whose distfiles aren't available for plain downloading +19.2.1. Packages whose distfiles aren't available for plain downloading If you need to download from a dynamic URL you can set DYNAMIC_MASTER_SITES and a make fetch will call files/getsite.sh with the name of each file to download @@ -6804,7 +6889,7 @@ FETCH_MESSAGE+= " "${DISTFILES:Q} FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." -18.2.2. How to handle modified distfiles with the 'old' name +19.2.2. How to handle modified distfiles with the 'old' name Sometimes authors of a software package make some modifications after the software was released, and they put up a new distfile without changing the @@ -6816,7 +6901,7 @@ in. Please mention that the distfiles were compared and what was found in your commit message. Then, the correct way to work around this is to set DIST_SUBDIR to a unique directory name, usually based on PKGNAME_NOREV. All DISTFILES and PATCHFILES for this package will be put in that subdirectory of the local -distfiles directory. (See Section 18.1.11, "How to handle incrementing versions +distfiles directory. (See Section 19.1.11, "How to handle incrementing versions when fixing an existing package" for more details.) In case this happens more often, PKGNAME can be used (thus including the nbX suffix) or a date stamp can be appended, like ${PKGNAME_NOREV}-YYYYMMDD. Do not forget regenerating the @@ -6826,9 +6911,9 @@ Furthermore, a mail to the package's authors seems appropriate telling them that changing distfiles after releases without changing the file names is not good practice. -18.3. Fixing problems in the configure phase +19.3. Fixing problems in the configure phase -18.3.1. Shared libraries - libtool +19.3.1. Shared libraries - libtool pkgsrc supports many different machines, with different object formats like a.out and ELF, and varying abilities to do shared library and dynamic loading @@ -6931,7 +7016,7 @@ Here's how to use libtool in a package in seven simple steps: 7. In your PLIST, include only the .la file (this is a change from previous behaviour). -18.3.2. Using libtool on GNU packages that already support libtool +19.3.2. Using libtool on GNU packages that already support libtool Add USE_LIBTOOL=yes to the package Makefile. This will override the package's own libtool in most cases. For older libtool using packages, libtool is made by @@ -6965,7 +7050,7 @@ in some circumstances. Some of the more common errors are: The function lt_dlinit() should be called and the macro LTDL_SET_PRELOADED_SYMBOLS included in executables. -18.3.3. GNU Autoconf/Automake +19.3.3. GNU Autoconf/Automake If a package needs GNU autoconf or automake to be executed to regenerate the configure script and Makefile.in makefile templates, then they should be @@ -7004,13 +7089,13 @@ automake sequence. This is prevented by touching various files in the configure stage. If this causes problems with your package you can set AUTOMAKE_OVERRIDE= NO in the package Makefile. -18.4. Programming languages +19.4. Programming languages -18.4.1. C, C++, and Fortran +19.4.1. C, C++, and Fortran 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 13, Buildlink +all other compilers (via the wrapper framework, see Chapter 14, Buildlink methodology). To declare which language's compiler a package needs, set the USE_LANGUAGES @@ -7018,7 +7103,7 @@ variable. Allowed values currently are "c", "c++", and "fortran" (and any combination). The default is "c". Packages using GNU configure scripts, even if written in C++, usually need a C compiler for the configure phase. -18.4.2. Java +19.4.2. Java If a program is written in Java, use the Java framework in pkgsrc. The package must include ../../mk/java-vm.mk. This Makefile fragment provides the following @@ -7033,7 +7118,7 @@ variables: implementation, "1.4" insists on versions 1.4 or above, and "1.5" only accepts versions 1.5 or above. This variable is not set by default. -18.4.3. Packages containing perl scripts +19.4.3. Packages containing perl scripts If your package contains interpreted perl scripts, add "perl" to the USE_TOOLS variable and set REPLACE_PERL to ensure that the proper interpreter path is @@ -7044,16 +7129,16 @@ full path to the perl executable. If a particular version of perl is needed, set the PERL5_REQD variable to the version number. The default is "5.0". -See Section 18.6.6, "Packages installing perl modules" for information about +See Section 19.6.6, "Packages installing perl modules" for information about handling perl modules. -18.4.4. Other programming languages +19.4.4. Other programming languages Currently, there is no special handling for other languages in pkgsrc. If a compiler package provides a buildlink3.mk file, include that, otherwise just add a (build) dependency on the appropriate compiler package. -18.5. Fixing problems in the build phase +19.5. Fixing problems in the build phase The most common failures when building a package are that some platforms do not provide certain header files, functions or libraries, or they provide the @@ -7061,7 +7146,7 @@ functions in a library that the original package author didn't know. To work around this, you can rewrite the source code in most cases so that it does not use the missing functions or provides a replacement function. -18.5.1. Compiling C and C++ code conditionally +19.5.1. Compiling C and C++ code conditionally If a package already comes with a GNU configure script, the preferred way to fix the build failure is to change the configure script, not the code. In the @@ -7078,7 +7163,7 @@ the compiler that is used. For example, if you want to conditionally compile code on Solaris, don't use __sun__, as the SunPro compiler does not define it. Use __sun instead. -18.5.1.1. C preprocessor macros to identify the operating system +19.5.1.1. C preprocessor macros to identify the operating system To distinguish between 4.4 BSD-derived systems and the rest of the world, you should use the following code. @@ -7102,20 +7187,20 @@ NetBSD __NetBSD__ OpenBSD __OpenBSD__ Solaris sun, __sun -18.5.1.2. C preprocessor macros to identify the hardware architecture +19.5.1.2. C preprocessor macros to identify the hardware architecture i386 i386, __i386, __i386__ MIPS __mips SPARC sparc, __sparc -18.5.1.3. C preprocessor macros to identify the compiler +19.5.1.3. C preprocessor macros to identify the compiler GCC __GNUC__ (major version), __GNUC_MINOR__ MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41) SunPro __SUNPRO_C (0x570 for Sun C 5.7) SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8) -18.5.2. How to handle compiler bugs +19.5.2. How to handle compiler bugs Some source files trigger bugs in the compiler, based on combinations of compiler version and architecture and almost always relation to optimisation @@ -7126,7 +7211,7 @@ Typically, a workaround involves testing the MACHINE_ARCH and compiler version, disabling optimisation for that combination of file, MACHINE_ARCH and compiler, and documenting it in pkgsrc/doc/HACKS. See that file for a number of examples. -18.5.3. Undefined reference to "..." +19.5.3. Undefined reference to "..." This error message often means that a package did not link to a shared library it needs. The following functions are known to cause this error message over @@ -7153,7 +7238,7 @@ and over. To fix these linker errors, it is often sufficient to say LIBS.OperatingSystem+ = -lfoo to the package Makefile and then say bmake clean; bmake. -18.5.3.1. Special issue: The SunPro compiler +19.5.3.1. Special issue: The SunPro compiler When you are using the SunPro compiler, there is another possibility. That compiler cannot handle the following code: @@ -7175,7 +7260,7 @@ It generates the code for inline_func even if that function is never used. This code then refers to extern_func, which can usually not be resolved. To solve this problem you can try to tell the package to disable inlining of functions. -18.5.4. Running out of memory +19.5.4. Running out of memory Sometimes packages fail to build because the compiler runs into an operating system specific soft limit. With the UNLIMIT_RESOURCES variable pkgsrc can be @@ -7184,9 +7269,9 @@ told to unlimit the resources. Currently, the allowed values are "datasize" and builtin ulimit command to raise the maximum data segment size or maximum stack size of a process, respectively, to their hard limits. -18.6. Fixing problems in the install phase +19.6. Fixing problems in the install phase -18.6.1. Creating needed directories +19.6.1. Creating needed directories The BSD-compatible install supplied with some operating systems cannot create more than one directory at a time. As such, you should call ${INSTALL_*_DIR} @@ -7199,7 +7284,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 You can also just append "dir1 dir2" to the INSTALLATION_DIRS variable, which will automatically do the right thing. -18.6.2. Where to install documentation +19.6.2. Where to install documentation In general, documentation should be installed into ${PREFIX}/share/doc/$ {PKGBASE} or ${PREFIX}/share/doc/${PKGNAME} (the latter includes the version @@ -7220,7 +7305,7 @@ then, no additional subdirectory level is allowed in this case. This is usually achieved by using "--with-html-dir=${PREFIX}/share/doc". ${PREFIX}/share/ gtk-doc is preferred though.) -18.6.3. Installing highscore files +19.6.3. Installing highscore files Certain packages, most of them in the games category, install a score file that allows all users on the system to record their highscores. In order for this to @@ -7235,7 +7320,7 @@ SETGIDGAME=YES will set all the other variables accordingly. A package should therefor never hard code file ownership or access permissions but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly. -18.6.4. Adding DESTDIR support to packages +19.6.4. Adding DESTDIR support to packages * All installation operations have to be prefixed with ${DESTDIR}. @@ -7248,7 +7333,7 @@ but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly. * In general, packages should support UNPRIVILEGED to be able to use DESTDIR. -18.6.5. Packages with hardcoded paths to other interpreters +19.6.5. Packages with hardcoded paths to other interpreters Your package may also contain scripts with hardcoded paths to other interpreters besides (or as well as) perl. To correct the full pathname to the @@ -7266,7 +7351,7 @@ Note Before March 2006, these variables were called _REPLACE.* and _REPLACE_FILES.*. -18.6.6. Packages installing perl modules +19.6.6. Packages installing perl modules Makefiles of packages providing perl5 modules should include the Makefile fragment ../../lang/perl5/module.mk. It provides a do-configure target for the @@ -7287,7 +7372,7 @@ three locations in which perl5 modules may be installed, and may be used by perl5 packages that don't have a packlist. These three variables are also substituted for in the PLIST. -18.6.7. Packages installing info files +19.6.7. Packages installing info files Some packages install info files or use the "makeinfo" or "install-info" commands. INFO_FILES should be defined in the package Makefile so that INSTALL @@ -7322,7 +7407,7 @@ message. The script overriding makeinfo logs a message and according to the value of TEXINFO_REQD either runs the appropriate makeinfo command or exit on error. -18.6.8. Packages installing man pages +19.6.8. Packages installing man pages All packages that install manual pages should install them into the same directory, so that there is one common place to look for them. In pkgsrc, this @@ -7347,10 +7432,10 @@ Packages that use GNU_CONFIGURE but do not use --mandir, can set 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 12.5, "Man page compression" for information on installation of +See Section 13.5, "Man page compression" for information on installation of compressed manual pages. -18.6.9. Packages installing GConf2 data files +19.6.9. Packages installing GConf2 data files If a package installs .schemas or .entries files, used by GConf2, you need to take some extra steps to make sure they get registered in the database: @@ -7366,7 +7451,7 @@ take some extra steps to make sure they get registered in the database: manually patch the package. 3. Check the PLIST and remove any entries under the etc/gconf directory, as - they will be handled automatically. See Section 8.13, "How do I change the + they will be handled automatically. See Section 9.13, "How do I change the location of configuration files?" for more information. 4. Define the GCONF2_SCHEMAS variable in your Makefile with a list of all @@ -7377,7 +7462,7 @@ take some extra steps to make sure they get registered in the database: .entries files installed by the package, if any. Names must not contain any directories in them. -18.6.10. Packages installing scrollkeeper data files +19.6.10. Packages installing scrollkeeper data files If a package installs .omf files, used by scrollkeeper, you need to take some extra steps to make sure they get registered in the database: @@ -7393,7 +7478,7 @@ extra steps to make sure they get registered in the database: 3. Remove the share/omf directory from the PLIST. It will be handled by scrollkeeper. -18.6.11. Packages installing X11 fonts +19.6.11. Packages installing X11 fonts If a package installs font files, you will need to rebuild the fonts database in the directory where they get installed at installation and deinstallation @@ -7407,7 +7492,7 @@ Note that you should not create new directories for fonts; instead use the standard ones to avoid that the user needs to manually configure his X server to find them. -18.6.12. Packages installing GTK2 modules +19.6.12. Packages installing GTK2 modules If a package installs GTK2 immodules or loaders, you need to take some extra steps to get them registered in the GTK2 database properly: @@ -7430,7 +7515,7 @@ steps to get them registered in the GTK2 database properly: 5. Check the PLIST and remove any entries under the libdata/gtk-2.0 directory, as they will be handled automatically. -18.6.13. Packages installing SGML or XML data +19.6.13. Packages installing SGML or XML data If a package installs SGML or XML data files that need to be registered in system-wide catalogs (like DTDs, sub-catalogs, etc.), you need to take some @@ -7456,7 +7541,7 @@ extra steps: (specifically, arguments recognized by the 'add' action). Note that you will normally not use this variable. -18.6.14. Packages installing extensions to the MIME database +19.6.14. Packages installing extensions to the MIME database If a package provides extensions to the MIME database by installing .xml files inside ${PREFIX}/share/mime/packages, you need to take some extra steps to @@ -7477,7 +7562,7 @@ ensure that the database is kept consistent with respect to these new files: 3. Remove any share/mime/* directories from the PLIST. They will be handled by the shared-mime-info package. -18.6.15. Packages using intltool +19.6.15. Packages using intltool If a package uses intltool during its build, add intltool to the USE_TOOLS, which forces it to use the intltool package provided by pkgsrc, instead of the @@ -7487,7 +7572,7 @@ This tracks intltool's build-time dependencies and uses the latest available version; this way, the package benefits of any bug fixes that may have appeared since it was released. -18.6.16. Packages installing startup scripts +19.6.16. Packages installing startup scripts If a package contains a rc.d script, it won't be copied into the startup directory by default, but you can enable it, by adding the option @@ -7495,7 +7580,7 @@ PKG_RCD_SCRIPTS=YES in mk.conf. This option will copy the scripts into /etc/ rc.d when a package is installed, and it will automatically remove the scripts when the package is deinstalled. -18.6.17. Packages installing TeX modules +19.6.17. Packages installing TeX modules If a package installs TeX packages into the texmf tree, the ls-R database of the tree needs to be updated. @@ -7521,7 +7606,7 @@ into PKG_LOCALTEXMFPREFIX, not PKG_TEXMFPREFIX. 3. Make sure that none of ls-R databases are included in PLIST, as they will be removed only by the teTeX-bin package. -18.6.18. Packages supporting running binaries in emulation +19.6.18. Packages supporting running binaries in emulation There are some packages that provide libraries and executables for running binaries from a one operating system on a different one (if the latter supports @@ -7535,7 +7620,7 @@ linker. Since the standard dynamic linker is run, this fails for emulation packages, because the libraries used by the emulation are not in the standard directories. -18.6.19. Packages installing hicolor theme icons +19.6.19. Packages installing hicolor theme icons If a package installs images under the share/icons/hicolor and/or updates the share/icons/hicolor/icon-theme.cache database, you need to take some extra @@ -7552,7 +7637,7 @@ that the cache database is rebuilt: The best way to verify that the PLIST is correct with respect to the last two points is to regenerate it using make print-PLIST. -18.6.20. Packages installing desktop files +19.6.20. Packages installing desktop files If a package installs .desktop files under share/applications and these include MIME information, you need to take extra steps to ensure that they are @@ -7566,7 +7651,7 @@ registered into the MIME database: The best way to verify that the PLIST is correct with respect to the last point is to regenerate it using make print-PLIST. -18.7. Marking packages as having problems +19.7. Marking packages as having problems In some cases one does not have the time to solve a problem immediately. There are currently two ways to declare that one knows that a package has problems. @@ -7586,7 +7671,7 @@ are currently two ways to declare that one knows that a package has problems. Both types of packages are removed from pkgsrc in irregular intervals. -Chapter 19. Debugging +Chapter 20. Debugging 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 @@ -7624,7 +7709,7 @@ what was explained in the previous sections, only with some debugging aids. that shouldn't be, especially during the build phase. mkpatches, patchdiff and pkgvi are from the pkgtools/pkgdiff package. - * Look at the Makefile, fix if necessary; see Section 10.1, "Makefile". + * Look at the Makefile, fix if necessary; see Section 11.1, "Makefile". * Generate a PLIST: @@ -7665,33 +7750,33 @@ what was explained in the previous sections, only with some debugging aids. # pkglint - * Submit (or commit, if you have cvs access); see Chapter 20, Submitting and + * Submit (or commit, if you have cvs access); see Chapter 21, Submitting and Committing. -Chapter 20. Submitting and Committing +Chapter 21. Submitting and Committing Table of Contents -20.1. Submitting binary packages -20.2. Submitting source packages (for non-NetBSD-developers) -20.3. General notes when adding, updating, or removing packages -20.4. Committing: Importing a package into CVS -20.5. Updating a package to a newer version -20.6. Moving a package in pkgsrc +21.1. Submitting binary packages +21.2. Submitting source packages (for non-NetBSD-developers) +21.3. General notes when adding, updating, or removing packages +21.4. Committing: Importing a package into CVS +21.5. Updating a package to a newer version +21.6. Moving a package in pkgsrc -20.1. Submitting binary packages +21.1. Submitting binary packages Our policy is that we accept binaries only from pkgsrc developers to guarantee that the packages don't contain any trojan horses etc. This is not to annoy anyone but rather to protect our users! You're still free to put up your home-made binary packages and tell the world where to get them. NetBSD developers doing bulk builds and wanting to upload them please see -Section 6.3.8, "Uploading results of a bulk build". +Section 7.3.8, "Uploading results of a bulk build". -20.2. Submitting source packages (for non-NetBSD-developers) +21.2. Submitting source packages (for non-NetBSD-developers) First, check that your package is complete, compiles and runs well; see -Chapter 19, Debugging and the rest of this document. Next, generate an +Chapter 20, 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 @@ -7711,7 +7796,7 @@ Alternatively, you can also import new packages into pkgsrc-wip ("pkgsrc work-in-progress"); see the homepage at http://pkgsrc-wip.sourceforge.net/ for details. -20.3. General notes when adding, updating, or removing packages +21.3. General notes when adding, updating, or removing packages Please note all package additions, updates, moves, and removals in pkgsrc/doc/ CHANGES-YYYY. It's very important to keep this file up to date and conforming @@ -7735,7 +7820,7 @@ or package moves or removals, set the CTYPE variable on the command line to your local login name is not the same as your NetBSD login name. Don't forget to commit the changes to pkgsrc/doc/CHANGES-YYYY! -20.4. Committing: Importing a package into CVS +21.4. Committing: Importing a package into CVS This section is only of interest for pkgsrc developers with write access to the pkgsrc repository. Please remember that cvs imports files relative to the @@ -7757,7 +7842,7 @@ so people reading the mailing lists know what the package is/does. For new packages, "cvs import" is preferred to "cvs add" because the former gets everything with a single command, and provides a consistent tag. -20.5. Updating a package to a newer version +21.5. Updating a package to a newer version Please always put a concise, appropriate and relevant summary of the changes between old and new versions into the commit log when updating a package. There @@ -7782,7 +7867,7 @@ which pkgsrc is used. Please use your judgement about what should go into pkgsrc, and bear in mind that stability is to be preferred above new and possibly untested features. -20.6. Moving a package in pkgsrc +21.6. Moving a package in pkgsrc 1. Make a copy of the directory somewhere else. @@ -7818,57 +7903,57 @@ possibly untested features. (and any packages from step 5, of course). -Chapter 21. Frequently Asked Questions +Chapter 22. Frequently Asked Questions This section contains the answers to questions that may arise when you are writing a package. If you don't find your question answered here, first have a look in the other chapters, and if you still don't have the answer, ask on the pkgsrc-users mailing list. -21.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? -21.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? -21.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? -21.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and +22.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? +22.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? +22.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? +22.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and BUILDLINK_LIBS? -21.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? -21.6. What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I don't understand +22.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? +22.6. What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I don't understand the := inside it. -21.7. Which mailing lists are there for package developers? -21.8. Where is the pkgsrc documentation? -21.9. I have a little time to kill. What shall I do? +22.7. Which mailing lists are there for package developers? +22.8. Where is the pkgsrc documentation? +22.9. I have a little time to kill. What shall I do? -21.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? +22.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? MAKEFLAGS are the flags passed to the pkgsrc-internal invocations of make (1), while MAKE_FLAGS are the flags that are passed to the MAKE_PROGRAM when building the package. [FIXME: What is .MAKEFLAGS for?] -21.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? +22.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? MAKE is the path to the make(1) program that is used in the pkgsrc infrastructure. GMAKE is the path to GNU Make, but you need to say USE_TOOLS+=gmake to use that. MAKE_PROGRAM is the path to the Make program that is used for building the package. -21.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? +22.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? CC is the path to the real C compiler, which can be configured by the pkgsrc user. PKG_CC is the path to the compiler wrapper. PKGSRC_COMPILER is not a path to a compiler, but the type of compiler that should be used. See mk/compiler.mk for more information about the latter variable. -21.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and +22.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and BUILDLINK_LIBS? [FIXME] -21.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? +22.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? For optimization reasons, some variables are only available in the "wrapper" phase and later. To "simulate" the wrapper phase, append PKG_PHASE=wrapper to the above command. -21.6. What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I don't understand +22.6. What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I don't understand the := inside it. The := is not really an assignment operator, like you might expect at @@ -7878,7 +7963,7 @@ pkgsrc-users mailing list. old_string is the empty string and new_string is package/. That's where the : and the = fall together. -21.7. Which mailing lists are there for package developers? +22.7. Which mailing lists are there for package developers? tech-pkg @@ -7895,7 +7980,7 @@ pkgsrc-users mailing list. Please do not report your bugs here directly; use one of the other mailing lists. -21.8. Where is the pkgsrc documentation? +22.8. Where is the pkgsrc documentation? There are many places where you can find documentation about pkgsrc: @@ -7929,7 +8014,7 @@ pkgsrc-users mailing list. 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. -21.9. I have a little time to kill. What shall I do? +22.9. I have a little time to kill. What shall I do? This is not really an FAQ yet, but here's the answer anyway. @@ -7944,14 +8029,14 @@ pkgsrc-users mailing list. * Review packages for which review was requested on the pkgsrc-wip review mailing list. -Chapter 22. GNOME packaging and porting +Chapter 23. 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 +23.1. Meta packages +23.2. Packaging a GNOME application +23.3. Updating GNOME to a newer version +23.4. Patching guidelines Quoting GNOME's web site: @@ -7985,7 +8070,7 @@ 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 +23.1. Meta packages pkgsrc includes three GNOME-related meta packages: @@ -8014,7 +8099,7 @@ 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 +23.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 @@ -8069,30 +8154,30 @@ 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 22.1. PLIST handling for GNOME packages +Table 23.1. PLIST handling for GNOME packages +-----------------------------------------------------------------------------+ | If the package... | Then... | |-------------------------------------------+---------------------------------| -| |See Section 18.6.10, "Packages | +| |See Section 19.6.10, "Packages | |Installs OMF files under share/omf. |installing scrollkeeper data | | |files". | |-------------------------------------------+---------------------------------| -|Installs icons under the share/icons/ |See Section 18.6.19, "Packages | +|Installs icons under the share/icons/ |See Section 19.6.19, "Packages | |hicolor hierarchy or updates share/icons/ |installing hicolor theme icons". | |hicolor/icon-theme.cache. | | |-------------------------------------------+---------------------------------| -| |See Section 18.6.14, "Packages | +| |See Section 19.6.14, "Packages | |Installs files under share/mime/packages. |installing extensions to the MIME| | |database". | |-------------------------------------------+---------------------------------| -|Installs .desktop files under share/ |See Section 18.6.20, "Packages | +|Installs .desktop files under share/ |See Section 19.6.20, "Packages | |applications and these include MIME |installing desktop files". | |information. | | +-----------------------------------------------------------------------------+ -22.3. Updating GNOME to a newer version +23.3. Updating GNOME to a newer version When seeing GNOME as a whole, there are two kinds of updates: @@ -8169,12 +8254,12 @@ In order to update the GNOME components in pkgsrc to a new stable release package updates and all the corresponding changes to the doc/CHANGES-<YEAR> and pkgsrc/doc/TODO files. -22.4. Patching guidelines +23.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 10.3.5, "Feedback to the author"). This is the only way to get their +Section 11.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 @@ -8191,7 +8276,7 @@ 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 10.3.4, "Patching guidelines") for more +see our patching guidelines (Section 11.3.4, "Patching guidelines") for more details. Part III. The pkgsrc infrastructure internals @@ -8202,67 +8287,67 @@ maintainer should not need anything from this part. Table of Contents -23. Design of the pkgsrc infrastructure +24. Design of the pkgsrc infrastructure - 23.1. The meaning of variable definitions - 23.2. Avoiding problems before they arise - 23.3. Variable evaluation + 24.1. The meaning of variable definitions + 24.2. Avoiding problems before they arise + 24.3. Variable evaluation - 23.3.1. At load time - 23.3.2. At runtime + 24.3.1. At load time + 24.3.2. At runtime - 23.4. How can variables be specified? - 23.5. Designing interfaces for Makefile fragments + 24.4. How can variables be specified? + 24.5. Designing interfaces for Makefile fragments - 23.5.1. Procedures with parameters - 23.5.2. Actions taken on behalf of parameters + 24.5.1. Procedures with parameters + 24.5.2. Actions taken on behalf of parameters - 23.6. The order in which files are loaded + 24.6. The order in which files are loaded - 23.6.1. The order in bsd.prefs.mk - 23.6.2. The order in bsd.pkg.mk + 24.6.1. The order in bsd.prefs.mk + 24.6.2. The order in bsd.pkg.mk -24. Regression tests +25. Regression tests - 24.1. The regression tests framework - 24.2. Running the regression tests - 24.3. Adding a new regression test + 25.1. The regression tests framework + 25.2. Running the regression tests + 25.3. Adding a new regression test - 24.3.1. Overridable functions - 24.3.2. Helper functions + 25.3.1. Overridable functions + 25.3.2. Helper functions -25. Porting pkgsrc +26. Porting pkgsrc - 25.1. Porting pkgsrc to a new operating system - 25.2. Adding support for a new compiler + 26.1. Porting pkgsrc to a new operating system + 26.2. Adding support for a new compiler -Chapter 23. Design of the pkgsrc infrastructure +Chapter 24. Design of the pkgsrc infrastructure Table of Contents -23.1. The meaning of variable definitions -23.2. Avoiding problems before they arise -23.3. Variable evaluation +24.1. The meaning of variable definitions +24.2. Avoiding problems before they arise +24.3. Variable evaluation - 23.3.1. At load time - 23.3.2. At runtime + 24.3.1. At load time + 24.3.2. At runtime -23.4. How can variables be specified? -23.5. Designing interfaces for Makefile fragments +24.4. How can variables be specified? +24.5. Designing interfaces for Makefile fragments - 23.5.1. Procedures with parameters - 23.5.2. Actions taken on behalf of parameters + 24.5.1. Procedures with parameters + 24.5.2. Actions taken on behalf of parameters -23.6. The order in which files are loaded +24.6. The order in which files are loaded - 23.6.1. The order in bsd.prefs.mk - 23.6.2. The order in bsd.pkg.mk + 24.6.1. The order in bsd.prefs.mk + 24.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. -23.1. The meaning of variable definitions +24.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 @@ -8289,7 +8374,7 @@ Note These conventions are currently not applied consistently to the complete pkgsrc infrastructure. -23.2. Avoiding problems before they arise +24.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 @@ -8306,9 +8391,9 @@ package Makefiles. Similarly for USE_LANGUAGES, but in this case the default value ("c") is so short that it doesn't stand out. Nevertheless it is mentioned in many files. -23.3. Variable evaluation +24.3. Variable evaluation -23.3.1. At load time +24.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 @@ -8344,25 +8429,25 @@ paragraph, the -Wall is appended to the CFLAGS, but this addition will not appear in CONFIGURE_ARGS. In actual code, the three paragraphs from above typically occur in completely unrelated files. -23.3.2. At runtime +24.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. -23.4. How can variables be specified? +24.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. See the pkglint developer's documentation for further details. -23.5. Designing interfaces for Makefile fragments +24.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. -23.5.1. Procedures with parameters +24.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 inclusion? @@ -8389,7 +8474,7 @@ Examples for procedures are mk/bsd.options.mk and mk/buildlink3/bsd.builtin.mk. 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. -23.5.2. Actions taken on behalf of parameters +24.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 @@ -8398,7 +8483,7 @@ explicitly. An example for action files is mk/subst.mk. -23.6. The order in which files are loaded +24.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 @@ -8410,7 +8495,7 @@ the files are loaded matters. This section describes at which point the various files are loaded and gives reasons for that order. -23.6.1. The order in bsd.prefs.mk +24.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. @@ -8430,7 +8515,7 @@ As the last steps, some essential variables from the wrapper and the package system flavor are loaded, as well as the variables that have been cached in earlier phases of a package build. -23.6.2. The order in bsd.pkg.mk +24.6.2. The order in bsd.pkg.mk First, bsd.prefs.mk is loaded. @@ -8457,16 +8542,16 @@ execution, though the actual order should not matter. At last, some more files are included that don't set any interesting variables but rather just define make targets to be executed. -Chapter 24. Regression tests +Chapter 25. Regression tests Table of Contents -24.1. The regression tests framework -24.2. Running the regression tests -24.3. Adding a new regression test +25.1. The regression tests framework +25.2. Running the regression tests +25.3. Adding a new regression test - 24.3.1. Overridable functions - 24.3.2. Helper functions + 25.3.1. Overridable functions + 25.3.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 @@ -8475,22 +8560,22 @@ changes from breaking anything, a suite of regression tests should go along with every important part of the pkgsrc infrastructure. This chapter describes how regression tests work in pkgsrc and how you can add new tests. -24.1. The regression tests framework +25.1. The regression tests framework -24.2. Running the regression tests +25.2. 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 category. -24.3. Adding a new regression test +25.3. Adding a new regression test Every directory in the regress category 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. -24.3.1. Overridable functions +25.3.1. Overridable functions These functions do not take any parameters. They are all called in "set -e" mode, so you should be careful to check the exitcodes of any commands you run @@ -8518,7 +8603,7 @@ do_cleanup() This function cleans everything up after the test has been run. By default it does nothing. -24.3.2. Helper functions +25.3.2. Helper functions exit_status(expected) @@ -8537,18 +8622,18 @@ output_prohibit(regex...) () does not match the extended regular expression. If any of the regular expressions matches, the test will fail. -Chapter 25. Porting pkgsrc +Chapter 26. Porting pkgsrc Table of Contents -25.1. Porting pkgsrc to a new operating system -25.2. Adding support for a new compiler +26.1. Porting pkgsrc to a new operating system +26.2. Adding support for a new compiler 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. -25.1. Porting pkgsrc to a new operating system +26.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: @@ -8595,7 +8680,7 @@ mk/tools/tools.MyOS.mk Now, you should be able to build some basic packages, like lang/perl5, shells/ bash. -25.2. Adding support for a new compiler +26.2. Adding support for a new compiler TODO @@ -8672,7 +8757,7 @@ Create the directory where the package lives, plus any auxiliary directories: # cd bison # mkdir patches -Create Makefile, DESCR and PLIST (see Chapter 10, Package components - files, +Create Makefile, DESCR and PLIST (see Chapter 11, Package components - files, directories and contents) then continue with fetching the distfile: # make fetch |