The pkgsrc guide

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. Speeding up bulk build scans

8.4. Requirements of a full bulk build

8.5. Bulk build variants

8.5.1. Detect unknown configure options

8.5.2. Detect classes of bugs by forcing compiler warnings

8.5.3. Force compiler options only in the build phase

8.5.4. Use custom directories

8.5.5. Turn warnings into errors

8.5.6. Reject packages for which pkglint reports errors

8.5.7. Reject packages that contain forbidden strings

8.5.8. Reject packages whose self-test fails

8.5.9. Reject packages that use undefined shell variables

8.5.10. Turn off verbose logging

8.6. Creating a multiple CD-ROM packages collection

8.6.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 X.org 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 bsd.own.mk” 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 bsd.options.mk

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 buildlink3.mk files

18.2.1. Anatomy of a buildlink3.mk file

18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in buildlink3.mk files

18.3. Writing builtin.mk files

18.3.1. Anatomy of a builtin.mk 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 github.com

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.3.5. Determining the endianness

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. pkgsrc Policies

24.1. Packages for which updating is restricted

24.1.1. Limited Updates - ABI

24.1.2. Limited Updates - Bootstrap

25. Frequently Asked Questions

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 bsd.prefs.mk

26.6.2. The order in bsd.pkg.mk

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. 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