The pkgsrc guide

Documentation on the NetBSD packages system

Alistair Crooks

Hubert Feyrer

The pkgsrc Developers

$NetBSD: index.html,v 1.91 2015/03/07 21:32:40 tnn Exp $

Abstract

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. Where to get pkgsrc and how to keep it up-to-date
2.1. Getting pkgsrc for the first time
2.1.1. As tar archive
2.1.2. Via anonymous CVS
2.2. Keeping pkgsrc up-to-date
2.2.1. Via tar files
2.2.2. Via CVS
3. Using pkgsrc on systems other than NetBSD
3.1. Binary distribution
3.2. Bootstrapping pkgsrc
3.3. Platform-specific notes
3.3.1. Cygwin
3.3.2. Darwin (Mac OS X)
3.3.3. FreeBSD
3.3.4. GNU/kFreeBSD
3.3.5. Interix
3.3.6. IRIX
3.3.7. Linux
3.3.8. MirBSD
3.3.9. OpenBSD
3.3.10. Solaris
4. Using pkgsrc
4.1. Using binary packages
4.1.1. Finding binary packages
4.1.2. Installing binary packages
4.1.3. Deinstalling packages
4.1.4. Getting information about installed packages
4.1.5. Checking for security vulnerabilities in installed packages
4.1.6. Finding if newer versions of your installed packages are in pkgsrc
4.1.7. Other administrative functions
4.1.8. A word of warning
4.2. Building packages from source
4.2.1. Requirements
4.2.2. Fetching distfiles
4.2.3. How to build and install
5. Configuring pkgsrc
5.1. General configuration
5.2. Variables affecting the build process
5.3. Variables affecting the installation process
5.4. Selecting and configuring the compiler
5.4.1. Selecting the compiler
5.4.2. Additional flags to the compiler (CFLAGS)
5.4.3. Additional flags to the linker (LDFLAGS)
5.5. Developer/advanced settings
5.6. Selecting Build Options
6. Creating binary packages
6.1. Building a single binary package
6.2. Settings for creation of binary packages
7. Creating binary packages for everything in pkgsrc (bulk builds)
7.1. Preparations
7.2. Running a pbulk-style bulk build
7.2.1. Configuration
7.3. Requirements of a full bulk build
7.4. Creating a multiple CD-ROM packages collection
7.4.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. Utilities for package management (pkgtools)
9.3. How to use pkgsrc as non-root
9.4. How to resume transfers when fetching distfiles?
9.5. How can I install/use modular X.org from pkgsrc?
9.6. How to fetch files from behind a firewall
9.7. How to fetch files from HTTPS sites
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?
II. The pkgsrc developer's guide
10. Creating a new pkgsrc package from scratch
10.1. Common types of packages
10.1.1. Perl modules
10.1.2. KDE3 applications
10.1.3. Python modules and programs
10.2. Examples
10.2.1. How the www/nvu package came into pkgsrc
11. Package components - files, directories and contents
11.1. Makefile
11.2. distinfo
11.3. patches/*
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
11.4. Other mandatory files
11.5. Optional files
11.5.1. Files affecting the binary package
11.5.2. Files affecting the build process
11.5.3. Files affecting nothing at all
11.6. work*
11.7. files/*
12. Programming in Makefiles
12.1. Caveats
12.2. Makefile variables
12.2.1. Naming conventions
12.3. Code snippets
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
13. PLIST issues
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. Build-specific PLISTs
13.9. Sharing directories between packages
14. Buildlink methodology
14.1. Converting packages to use buildlink3
14.2. Writing buildlink3.mk files
14.2.1. Anatomy of a buildlink3.mk file
14.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in buildlink3.mk files
14.3. Writing builtin.mk files
14.3.1. Anatomy of a builtin.mk file
14.3.2. Global preferences for native or pkgsrc software
15. The pkginstall framework
15.1. Files and directories outside the installation prefix
15.1.1. Directory manipulation
15.1.2. File manipulation
15.2. 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
15.3. System startup scripts
15.3.1. Disabling handling of system startup scripts
15.4. System users and groups
15.5. System shells
15.5.1. Disabling shell registration
15.6. Fonts
15.6.1. Disabling automatic update of the fonts databases
16. Options handling
16.1. Global default options
16.2. Converting packages to use bsd.options.mk
16.3. Option Names
16.4. Determining the options of dependencies
17. The build process
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
18. Tools needed for building or running
18.1. Tools for pkgsrc builds
18.2. Tools needed by packages
18.3. Tools provided by platforms
18.4. Questions regarding the tools
19. Making your package work
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
19.1.12. Substituting variable text in the package files (the SUBST framework)
19.2. Fixing problems in the fetch phase
19.2.1. Packages whose distfiles aren't available for plain downloading
19.2.2. How to handle modified distfiles with the 'old' name
19.2.3. Packages hosted on github.com
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. Packages containing shell scripts
19.4.5. 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 GConf data files
19.6.10. Packages installing scrollkeeper/rarian 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: Adding a package to CVS
21.5. Updating a package to a newer version
21.6. Renaming a package in pkgsrc
21.7. 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
24. Design of the pkgsrc infrastructure
24.1. The meaning of variable definitions
24.2. Avoiding problems before they arise
24.3. Variable evaluation
24.3.1. At load time
24.3.2. At runtime
24.4. How can variables be specified?
24.5. Designing interfaces for Makefile fragments
24.5.1. Procedures with parameters
24.5.2. Actions taken on behalf of parameters
24.6. The order in which files are loaded
24.6.1. The order in bsd.prefs.mk
24.6.2. The order in bsd.pkg.mk
25. Regression tests
25.1. The regression tests framework
25.2. Running the regression tests
25.3. Adding a new regression test
25.3.1. Overridable functions
25.3.2. Helper functions
26. Porting pkgsrc
26.1. Porting pkgsrc to a new operating system
26.2. Adding support for a new compiler
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, pkgsrc-20xxQy: source packages
D. Editing guidelines for the pkgsrc guide
D.1. Make targets
D.2. Procedure

List of Tables

1.1. Platforms supported by pkgsrc
11.1. Patching examples
23.1. PLIST handling for GNOME packages