The pkgsrc guide

Documentation on the NetBSD packages system

Alistair Crooks

Hubert Feyrer

The pkgsrc Developers

$NetBSD: index.html,v 1.256 2024/05/10 12:32:05 wiz 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. Updating packages
5.1.4. Deinstalling packages
5.1.5. Getting information about installed packages
5.1.6. Checking for security vulnerabilities in installed packages
5.1.7. Finding if newer versions of your installed packages are in pkgsrc
5.1.8. 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. Preferences for native or pkgsrc software
6.4. Variables affecting the installation process
6.5. Selecting and configuring the compiler
6.5.1. Selecting the compiler
6.5.2. Additional flags to the compiler (CFLAGS)
6.5.3. Additional flags to the linker (LDFLAGS)
6.6. Developer/advanced settings
6.7. 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' or `priv` 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. Package components - files, directories and contents
12.1. Makefile
12.2. distinfo
12.3. patches/*
12.3.1. Structure of a single patch file
12.3.2. Creating patch files
12.3.3. Sources where the patch files come from
12.3.4. Patching guidelines
12.3.5. Feedback to the author
12.4. Other mandatory files
12.5. Optional files
12.5.1. Files affecting the binary package
12.5.2. Files affecting the build process
12.5.3. Files affecting nothing at all
12.6. work*
12.7. files/*
13. The build process
13.1. Introduction
13.2. Program location
13.3. Directories used during the build process
13.4. Running a phase
13.5. The fetch phase
13.5.1. What to fetch and where to get it from
13.5.2. How are the files fetched?
13.6. The checksum phase
13.7. The extract phase
13.8. The patch phase
13.9. The tools phase
13.10. The wrapper phase
13.11. The configure phase
13.12. The build phase
13.13. The test phase
13.14. The install phase
13.15. The package phase
13.16. Cleaning up
13.17. Other helpful targets
14. Creating a new pkgsrc package from scratch
14.1. Common types of packages
14.1.1. Python modules and programs
14.1.2. R packages
14.1.3. TeXlive packages
14.2. Examples
14.2.1. How the www/nvu package came into pkgsrc
15. Programming in Makefiles
15.1. Caveats
15.2. Makefile variables
15.2.1. Naming conventions
15.3. Code snippets
15.3.1. Adding things to a list
15.3.2. Echoing a string exactly as-is
15.3.3. Passing CFLAGS to GNU configure scripts
15.3.4. Handling possibly empty variables
15.3.5. Testing yes/no variables in conditions
16. Options handling
16.1. Global default options
16.2. Converting packages to use
16.3. Option Names
16.4. Determining the options of dependencies
17. Tools needed for building or running
17.1. Tools for pkgsrc builds
17.2. Tools needed by packages
17.3. Tools provided by platforms
18. Buildlink methodology
18.1. Converting packages to use buildlink3
18.2. Writing files
18.2.1. Anatomy of a file
18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in files
18.3. Writing files
18.3.1. Anatomy of a file
19. PLIST issues
19.1. RCS ID
19.2. Semi-automatic PLIST generation
19.3. Tweaking output of make print-PLIST
19.4. Variable substitution in PLIST
19.5. Man page compression
19.6. Changing PLIST source with PLIST_SRC
19.7. Platform-specific and differing PLISTs
19.8. Build-specific PLISTs
19.9. Sharing directories between packages
20. The pkginstall framework
20.1. Files and directories outside the installation prefix
20.1.1. Directory manipulation
20.1.2. File manipulation
20.2. Configuration files
20.2.1. How PKG_SYSCONFDIR is set
20.2.2. Telling the software where configuration files are
20.2.3. Patching installation
20.2.4. Declaring configuration files
20.2.5. Disabling handling of configuration files
20.3. System startup scripts
20.3.1. Disabling handling of system startup scripts
20.4. System users and groups
20.5. System shells
20.5.1. Disabling shell registration
20.6. Fonts
20.6.1. Disabling automatic update of the fonts databases
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.3.4. Meson / ninja
21.4. Programming languages
21.4.1. C, C++, and Fortran
21.4.2. Java
21.4.3. Go
21.4.4. Rust
21.4.5. Packages containing Perl scripts
21.4.6. Packages containing shell scripts
21.4.7. 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 pkg-config files
21.6.8. Packages installing info files
21.6.9. Packages installing man pages
21.6.10. Packages installing X11 fonts
21.6.11. Packages installing SGML or XML data
21.6.12. Packages installing extensions to the MIME database
21.6.13. Packages using intltool
21.6.14. Packages installing startup scripts
21.6.15. Packages installing TeX modules
21.6.16. Packages supporting running binaries in emulation
21.6.17. Packages installing hicolor icons
21.6.18. Packages installing desktop files
21.7. Marking packages as having problems
22. GNOME packaging and porting
22.1. Meta packages
22.2. Packaging a GNOME application
22.3. Updating GNOME to a newer version
22.4. Patching guidelines
23. Submitting and Committing
23.1. Submitting binary packages
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
III. The pkgsrc infrastructure internals
25. Design of the pkgsrc infrastructure
25.1. The meaning of variable definitions
25.2. Avoiding problems before they arise
25.3. Variable evaluation
25.3.1. At load time
25.3.2. At runtime
25.4. How can variables be specified?
25.5. Designing interfaces for Makefile fragments
25.5.1. Procedures with parameters
25.5.2. Actions taken on behalf of parameters
25.6. The order in which files are loaded
25.6.1. The order in
25.6.2. The order in
26. Regression tests
26.1. Running the regression tests
26.2. Adding a new regression test
26.2.1. Overridable functions
26.2.2. Helper functions
27. Porting pkgsrc
27.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. Security hardening
B.1. Mechanisms
B.1.1. Enabled by default
B.1.2. Not enabled by default
B.2. Caveats
B.2.1. Problems with PKGSRC_MKPIE
B.2.2. Problems with PKGSRC_USE_FORTIFY
B.2.3. Problems with PKGSRC_USE_RELRO
B.2.4. Problems with PKGSRC_USE_SSP
B.3. Auditing the system
B.3.1. Checking for PIE
B.3.2. Checking for partial RELRO
B.3.3. Checking for full RELRO
B.3.4. Checking for SSP
C. Build logs
C.1. Building figlet
C.2. Packaging figlet
D. Directory layout of the pkgsrc FTP server
D.1. distfiles: The distributed source files
D.2. misc: Miscellaneous things
D.3. packages: Binary packages
D.4. reports: Bulk build reports
D.5. current, stable, pkgsrc-20xxQy: source packages
E. Help topics
F. Editing guidelines for the pkgsrc guide
F.1. Make targets
F.2. Procedure

List of Tables

1.1. Platforms supported by pkgsrc
12.1. Patching examples
22.1. PLIST handling for GNOME packages