The pkgsrc guide

Documentation on the NetBSD packages system

Alistair Crooks

Hubert Feyrer

The pkgsrc Developers

$NetBSD: index.html,v 1.183 2020/06/10 16:09:01 leot Exp $


pkgsrc is a centralized package management system for Unix-like operating systems. This guide provides information for users and developers of pkgsrc. It covers installation of binary and source packages, creation of binary and source packages and a high-level overview about the infrastructure.

Table of Contents

1. What is pkgsrc?
1.1. Introduction
1.1.1. Why pkgsrc?
1.1.2. Supported platforms
1.2. Overview
1.3. Terminology
1.3.1. Roles involved in pkgsrc
1.4. Typography
I. The pkgsrc user's guide
2. Getting help
3. Where to get pkgsrc and how to keep it up-to-date
3.1. Getting pkgsrc for the first time
3.1.1. As tar archive
3.1.2. Via anonymous CVS
3.2. Keeping pkgsrc up-to-date
3.2.1. Via tar files
3.2.2. Via CVS
4. Using pkgsrc on systems other than NetBSD
4.1. Binary distribution
4.2. Bootstrapping pkgsrc
5. Using pkgsrc
5.1. Using binary packages
5.1.1. Finding binary packages
5.1.2. Installing binary packages
5.1.3. Deinstalling packages
5.1.4. Getting information about installed packages
5.1.5. Checking for security vulnerabilities in installed packages
5.1.6. Finding if newer versions of your installed packages are in pkgsrc
5.1.7. Other administrative functions
5.2. Building packages from source
5.2.1. Requirements
5.2.2. Fetching distfiles
5.2.3. How to build and install
6. Configuring pkgsrc
6.1. General configuration
6.2. Variables affecting the build process
6.3. Variables affecting the installation process
6.4. Selecting and configuring the compiler
6.4.1. Selecting the compiler
6.4.2. Additional flags to the compiler (CFLAGS)
6.4.3. Additional flags to the linker (LDFLAGS)
6.5. Developer/advanced settings
6.6. Selecting Build Options
7. Creating binary packages
7.1. Building a single binary package
7.2. Settings for creation of binary packages
8. Creating binary packages for everything in pkgsrc (bulk builds)
8.1. Preparations
8.2. Running a bulk build
8.2.1. Configuration
8.3. Requirements of a full bulk build
8.4. Bulk build variants
8.4.1. Detect unknown configure options
8.4.2. Detect classes of bugs by forcing compiler warnings
8.4.3. Force compiler options only in the build phase
8.4.4. Use custom directories
8.4.5. Turn warnings into errors
8.4.6. Reject packages for which pkglint reports errors
8.4.7. Reject packages that contain forbidden strings
8.4.8. Reject packages whose self-test fails
8.4.9. Reject packages that use undefined shell variables
8.4.10. Turn off verbose logging
8.5. Creating a multiple CD-ROM packages collection
8.5.1. Example of cdpack
9. Directory layout of the installed files
9.1. File system layout in ${LOCALBASE}
9.2. File system layout in ${VARBASE}
10. Frequently Asked Questions
10.1. Are there any mailing lists for pkg-related discussion?
10.2. Utilities for package management (pkgtools)
10.3. How to use pkgsrc as non-root
10.4. How to resume transfers when fetching distfiles?
10.5. How can I install/use modular from pkgsrc?
10.6. How to fetch files from behind a firewall
10.7. How to fetch files from HTTPS sites
10.8. How do I tell make fetch to do passive FTP?
10.9. How to fetch all distfiles at once
10.10. What does Don't know how to make /usr/share/tmac/tmac.andoc mean?
10.11. What does Could not find mean?
10.12. Using 'sudo' with pkgsrc
10.13. How do I change the location of configuration files?
10.14. Automated security checks
10.15. Why do some packages ignore my CFLAGS?
10.16. A package does not build. What shall I do?
10.17. What does Makefile appears to contain unresolved cvs/rcs/??? merge conflicts mean?
II. The pkgsrc developer's guide
11. Getting help
12. Creating a new pkgsrc package from scratch
12.1. Common types of packages
12.1.1. Perl modules
12.1.2. Python modules and programs
12.1.3. R packages
12.1.4. TeXlive packages
12.2. Examples
12.2.1. How the www/nvu package came into pkgsrc
13. Package components - files, directories and contents
13.1. Makefile
13.2. distinfo
13.3. patches/*
13.3.1. Structure of a single patch file
13.3.2. Creating patch files
13.3.3. Sources where the patch files come from
13.3.4. Patching guidelines
13.3.5. Feedback to the author
13.4. Other mandatory files
13.5. Optional files
13.5.1. Files affecting the binary package
13.5.2. Files affecting the build process
13.5.3. Files affecting nothing at all
13.6. work*
13.7. files/*
14. Programming in Makefiles
14.1. Caveats
14.2. Makefile variables
14.2.1. Naming conventions
14.3. Code snippets
14.3.1. Adding things to a list
14.3.2. Echoing a string exactly as-is
14.3.3. Passing CFLAGS to GNU configure scripts
14.3.4. Handling possibly empty variables
15. PLIST issues
15.1. RCS ID
15.2. Semi-automatic PLIST generation
15.3. Tweaking output of make print-PLIST
15.4. Variable substitution in PLIST
15.5. Man page compression
15.6. Changing PLIST source with PLIST_SRC
15.7. Platform-specific and differing PLISTs
15.8. Build-specific PLISTs
15.9. Sharing directories between packages
16. Buildlink methodology
16.1. Converting packages to use buildlink3
16.2. Writing files
16.2.1. Anatomy of a file
16.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in files
16.3. Writing files
16.3.1. Anatomy of a file
16.3.2. Global preferences for native or pkgsrc software
17. The pkginstall framework
17.1. Files and directories outside the installation prefix
17.1.1. Directory manipulation
17.1.2. File manipulation
17.2. Configuration files
17.2.1. How PKG_SYSCONFDIR is set
17.2.2. Telling the software where configuration files are
17.2.3. Patching installations
17.2.4. Disabling handling of configuration files
17.3. System startup scripts
17.3.1. Disabling handling of system startup scripts
17.4. System users and groups
17.5. System shells
17.5.1. Disabling shell registration
17.6. Fonts
17.6.1. Disabling automatic update of the fonts databases
18. Options handling
18.1. Global default options
18.2. Converting packages to use
18.3. Option Names
18.4. Determining the options of dependencies
19. The build process
19.1. Introduction
19.2. Program location
19.3. Directories used during the build process
19.4. Running a phase
19.5. The fetch phase
19.5.1. What to fetch and where to get it from
19.5.2. How are the files fetched?
19.6. The checksum phase
19.7. The extract phase
19.8. The patch phase
19.9. The tools phase
19.10. The wrapper phase
19.11. The configure phase
19.12. The build phase
19.13. The test phase
19.14. The install phase
19.15. The package phase
19.16. Cleaning up
19.17. Other helpful targets
20. Tools needed for building or running
20.1. Tools for pkgsrc builds
20.2. Tools needed by packages
20.3. Tools provided by platforms
21. Making your package work
21.1. General operation
21.1.1. How to pull in user-settable variables from mk.conf
21.1.2. User interaction
21.1.3. Handling licenses
21.1.4. Restricted packages
21.1.5. Handling dependencies
21.1.6. Handling conflicts with other packages
21.1.7. Packages that cannot or should not be built
21.1.8. Packages which should not be deleted, once installed
21.1.9. Handling packages with security problems
21.1.10. How to handle incrementing versions when fixing an existing package
21.1.11. Substituting variable text in the package files (the SUBST framework)
21.2. The fetch phase
21.2.1. Packages whose distfiles aren't available for plain downloading
21.2.2. How to handle modified distfiles with the 'old' name
21.2.3. Packages hosted on
21.3. The configure phase
21.3.1. Shared libraries - libtool
21.3.2. Using libtool on GNU packages that already support libtool
21.3.3. GNU Autoconf/Automake
21.4. Programming languages
21.4.1. C, C++, and Fortran
21.4.2. Java
21.4.3. Packages containing perl scripts
21.4.4. Packages containing shell scripts
21.4.5. Other programming languages
21.5. The build phase
21.5.1. Compiling C and C++ code conditionally
21.5.2. How to handle compiler bugs
21.5.3. No such file or directory
21.5.4. Undefined reference to ...
21.5.5. Running out of memory
21.6. The install phase
21.6.1. Creating needed directories
21.6.2. Where to install documentation
21.6.3. Installing highscore files
21.6.4. Adding DESTDIR support to packages
21.6.5. Packages with hardcoded paths to other interpreters
21.6.6. Packages installing perl modules
21.6.7. Packages installing info files
21.6.8. Packages installing man pages
21.6.9. Packages installing GConf data files
21.6.10. Packages installing scrollkeeper/rarian data files
21.6.11. Packages installing X11 fonts
21.6.12. Packages installing GTK2 modules
21.6.13. Packages installing SGML or XML data
21.6.14. Packages installing extensions to the MIME database
21.6.15. Packages using intltool
21.6.16. Packages installing startup scripts
21.6.17. Packages installing TeX modules
21.6.18. Packages supporting running binaries in emulation
21.6.19. Packages installing hicolor theme icons
21.6.20. Packages installing desktop files
21.7. Marking packages as having problems
22. Debugging
23. Submitting and Committing
23.1. Submitting binary packages
23.2. Submitting source packages (for non-NetBSD-developers)
23.3. General notes when adding, updating, or removing packages
23.4. Commit Messages
23.5. Committing: Adding a package to CVS
23.6. Updating a package to a newer version
23.7. Renaming a package in pkgsrc
23.8. Moving a package in pkgsrc
24. Frequently Asked Questions
25. GNOME packaging and porting
25.1. Meta packages
25.2. Packaging a GNOME application
25.3. Updating GNOME to a newer version
25.4. Patching guidelines
III. The pkgsrc infrastructure internals
26. Design of the pkgsrc infrastructure
26.1. The meaning of variable definitions
26.2. Avoiding problems before they arise
26.3. Variable evaluation
26.3.1. At load time
26.3.2. At runtime
26.4. How can variables be specified?
26.5. Designing interfaces for Makefile fragments
26.5.1. Procedures with parameters
26.5.2. Actions taken on behalf of parameters
26.6. The order in which files are loaded
26.6.1. The order in
26.6.2. The order in
27. Regression tests
27.1. Running the regression tests
27.2. Adding a new regression test
27.2.1. Overridable functions
27.2.2. Helper functions
28. Porting pkgsrc
28.1. Porting pkgsrc to a new operating system
A. A simple example package: bison
A.1. files
A.1.1. Makefile
A.1.2. DESCR
A.1.3. PLIST
A.1.4. Checking a package with pkglint
A.2. Steps for building, installing, packaging
B. Build logs
B.1. Building figlet
B.2. Packaging figlet
C. Directory layout of the pkgsrc FTP server
C.1. distfiles: The distributed source files
C.2. misc: Miscellaneous things
C.3. packages: Binary packages
C.4. reports: Bulk build reports
C.5. current, stable, pkgsrc-20xxQy: source packages
D. Help topics
E. Editing guidelines for the pkgsrc guide
E.1. Make targets
E.2. Procedure

List of Tables

1.1. Platforms supported by pkgsrc
13.1. Patching examples
25.1. PLIST handling for GNOME packages