[BACK]Return to pkgsrc.txt CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / pkgsrc / doc

Annotation of pkgsrc/doc/pkgsrc.txt, Revision 1.9

1.1       grant       1: The pkgsrc guide
                      2:
1.2       hubertf     3: Documentation on the NetBSD packages system
1.1       grant       4:
                      5: Alistair Crooks
                      6:
                      7: <agc@NetBSD.org>
                      8:
                      9: Hubert Feyrer
                     10:
                     11: <hubertf@NetBSD.org>
                     12:
1.3       hubertf    13: The pkgsrc Developers
1.2       hubertf    14:
1.1       grant      15: Copyright (C) 1994-2004 The NetBSD Foundation, Inc
                     16:
1.9     ! dillo      17: $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant      18:
                     19: Abstract
                     20:
                     21: Information about using the NetBSD package system (pkgsrc) from both a user
                     22: view for installing packages as well as from a pkgsrc developers' view for
                     23: creating new packages.
                     24:
                     25: -------------------------------------------------------------------------------
                     26:
                     27: Table of Contents
                     28:
                     29: 1. Introduction
1.7       wiz        30:
1.1       grant      31:     1.1. Introduction
                     32:     1.2. Overview
                     33:     1.3. Terminology
                     34:     1.4. Typography
1.7       wiz        35:
1.2       hubertf    36: I. The pkgsrc user's guide
1.7       wiz        37:
1.1       grant      38:     2. Where to get pkgsrc
1.7       wiz        39:
1.1       grant      40:         2.1. As tar file
                     41:         2.2. Via SUP
                     42:         2.3. Via CVS
1.7       wiz        43:
1.1       grant      44:     3. Using pkgsrc on systems other than NetBSD
1.7       wiz        45:
1.1       grant      46:         3.1. Bootstrapping pkgsrc
                     47:         3.2. Platform specific notes
1.7       wiz        48:
1.1       grant      49:             3.2.1. Darwin (Mac OS X)
                     50:             3.2.2. FreeBSD
                     51:             3.2.3. Interix
                     52:             3.2.4. IRIX
                     53:             3.2.5. OpenBSD
                     54:             3.2.6. Solaris
1.7       wiz        55:
1.1       grant      56:     4. Using pkgsrc
1.7       wiz        57:
1.1       grant      58:         4.1. Working with binary packages
1.7       wiz        59:
1.1       grant      60:             4.1.1. Where to get binary packages
                     61:             4.1.2. How to use binary packages
                     62:             4.1.3. A word of warning
1.7       wiz        63:
1.1       grant      64:         4.2. Building packages from source
1.7       wiz        65:
1.1       grant      66:             4.2.1. Requirements
                     67:             4.2.2. Fetching distfiles
                     68:             4.2.3. How to build and install
                     69:             4.2.4. Selecting the compiler
1.7       wiz        70:
1.1       grant      71:     5. Creating binary packages
1.7       wiz        72:
1.1       grant      73:         5.1. Building a single binary package
                     74:         5.2. Settings for creation of binary packages
                     75:         5.3. Doing a bulk build of all packages
1.7       wiz        76:
1.1       grant      77:             5.3.1. Configuration
                     78:             5.3.2. Other environmental considerations
                     79:             5.3.3. Operation
                     80:             5.3.4. What it does
                     81:             5.3.5. Disk space requirements
                     82:             5.3.6. Setting up a sandbox for chroot'ed builds
                     83:             5.3.7. Building a partial set of packages
1.7       wiz        84:
1.1       grant      85:         5.4. Creating a multiple CD-ROM packages collection
1.7       wiz        86:
1.1       grant      87:             5.4.1. Example of cdpack
1.7       wiz        88:
1.1       grant      89:     6. Frequently Asked Questions
1.7       wiz        90:
1.1       grant      91:         6.1. Is there a mailing list for pkg-related discussion?
                     92:         6.2. Where's the pkgviews documentation?
                     93:         6.3. Utilities for package management (pkgtools)
                     94:         6.4. How to use pkgsrc as non-root
                     95:         6.5. How can I install/use XFree86 from pkgsrc?
                     96:         6.6. How can I install/use X.org from pkgsrc?
                     97:         6.7. How to fetch files from behind a firewall
                     98:         6.8. How do I tell make fetch to do passive FTP?
                     99:         6.9. How to fetch all distfiles at once
1.7       wiz       100:         6.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc"
                    101:             mean?
                    102:         6.11. What does "Could not find bsd.own.mk" mean?
1.1       grant     103:         6.12. Using 'sudo' with pkgsrc
                    104:         6.13. Configuration files handling and placement
                    105:         6.14. Automated security checks
1.7       wiz       106:
1.2       hubertf   107: II. The pkgsrc developer's guide
1.7       wiz       108:
1.1       grant     109:     7. Package components - files, directories and contents
1.7       wiz       110:
1.1       grant     111:         7.1. Makefile
                    112:         7.2. distinfo
                    113:         7.3. patches/*
                    114:         7.4. Other mandatory files
                    115:         7.5. Optional files
                    116:         7.6. work*
                    117:         7.7. files/*
1.7       wiz       118:
1.1       grant     119:     8. PLIST issues
1.7       wiz       120:
1.1       grant     121:         8.1. RCS ID
                    122:         8.2. Semi-automatic PLIST generation
                    123:         8.3. Tweaking output of make print-PLIST
                    124:         8.4. Variable substitution in PLIST
                    125:         8.5. Manpage-compression
                    126:         8.6. Changing PLIST source with PLIST_SRC
                    127:         8.7. Platform specific and differing PLISTs
                    128:         8.8. Sharing directories between packages
1.7       wiz       129:
1.1       grant     130:     9. Buildlink methodology
1.7       wiz       131:
1.1       grant     132:         9.1. Converting packages to use buildlink3
                    133:         9.2. Writing buildlink3.mk files
1.7       wiz       134:
1.1       grant     135:             9.2.1. Anatomy of a buildlink3.mk file
                    136:             9.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
1.7       wiz       137:
1.1       grant     138:         9.3. Writing builtin.mk files
1.7       wiz       139:
1.1       grant     140:             9.3.1. Anatomy of a builtin.mk file
                    141:             9.3.2. Global preferences for native or pkgsrc software
1.7       wiz       142:
1.1       grant     143:     10. Options handling
1.7       wiz       144:
1.1       grant     145:         10.1. Global default options
                    146:         10.2. Converting packages to use bsd.options.mk
1.7       wiz       147:
1.1       grant     148:     11. The build process
1.7       wiz       149:
1.1       grant     150:         11.1. Program location
                    151:         11.2. Main targets
                    152:         11.3. Other helpful targets
1.7       wiz       153:
1.1       grant     154:     12. Notes on fixes for packages
1.7       wiz       155:
1.1       grant     156:         12.1. General operation
1.7       wiz       157:
1.1       grant     158:             12.1.1. How to pull in variables from /etc/mk.conf
                    159:             12.1.2. Restricted packages
                    160:             12.1.3. Handling dependencies
                    161:             12.1.4. Handling conflicts with other packages
                    162:             12.1.5. Packages that cannot or should not be built
                    163:             12.1.6. Packages which should not be deleted, once installed
                    164:             12.1.7. Handling packages with security problems
                    165:             12.1.8. How to handle compiler bugs
                    166:             12.1.9. How to handle incrementing versions when fixing an existing
                    167:                 package
                    168:             12.1.10. Portability of packages
1.7       wiz       169:
1.1       grant     170:         12.2. Possible downloading issues
1.7       wiz       171:
1.1       grant     172:             12.2.1. Packages whose distfiles aren't available for plain
                    173:                 downloading
                    174:             12.2.2. How to handle modified distfiles with the 'old' name
1.7       wiz       175:
1.1       grant     176:         12.3. Configuration gotchas
1.7       wiz       177:
1.1       grant     178:             12.3.1. Shared libraries - libtool
                    179:             12.3.2. Using libtool on GNU packages that already support libtool
                    180:             12.3.3. GNU Autoconf/Automake
1.7       wiz       181:
1.1       grant     182:         12.4. Building considerations
1.7       wiz       183:
1.1       grant     184:             12.4.1. CPP defines
1.7       wiz       185:
1.1       grant     186:         12.5. Package specific actions
1.7       wiz       187:
1.1       grant     188:             12.5.1. Package configuration files
1.2       hubertf   189:             12.5.2. User interaction
1.1       grant     190:             12.5.3. Handling licenses
                    191:             12.5.4. Creating an account from a package
                    192:             12.5.5. Installing score files
                    193:             12.5.6. Packages providing login shells
                    194:             12.5.7. Packages containing perl scripts
                    195:             12.5.8. Packages with hardcoded paths to other interpreters
                    196:             12.5.9. Packages installing perl modules
                    197:             12.5.10. Packages installing info files
                    198:             12.5.11. Packages installing GConf2 data files
                    199:             12.5.12. Packages installing scrollkeeper data files
                    200:             12.5.13. Packages installing X11 fonts
                    201:             12.5.14. Packages installing GTK2 modules
                    202:             12.5.15. Packages installing SGML or XML data
                    203:             12.5.16. Packages installing extensions to the MIME database
                    204:             12.5.17. Packages using intltool
1.7       wiz       205:
1.1       grant     206:         12.6. Feedback to the author
1.7       wiz       207:
1.1       grant     208:     13. Debugging
                    209:     14. Submitting and Committing
1.7       wiz       210:
1.1       grant     211:         14.1. Submitting your packages
                    212:         14.2. Committing: Importing a package into CVS
1.2       hubertf   213:         14.3. Updating a package to a newer version
                    214:         14.4. Moving a package in pkgsrc
1.7       wiz       215:
1.1       grant     216: A. A simple example package: bison
1.7       wiz       217:
1.1       grant     218:     A.1. files
1.7       wiz       219:
1.1       grant     220:         A.1.1. Makefile
                    221:         A.1.2. DESCR
                    222:         A.1.3. PLIST
                    223:         A.1.4. Checking a package with pkglint
1.7       wiz       224:
1.1       grant     225:     A.2. Steps for building, installing, packaging
1.7       wiz       226:
1.1       grant     227: B. Build logs
1.7       wiz       228:
1.1       grant     229:     B.1. Building figlet
                    230:     B.2. Packaging figlet
1.7       wiz       231:
1.1       grant     232: C. Layout of the FTP server's package archive
1.2       hubertf   233: D. Editing guidelines for the pkgsrc guide
1.7       wiz       234:
1.2       hubertf   235:     D.1. Targets
                    236:     D.2. Procedure
1.7       wiz       237:
1.1       grant     238: Chapter 1. Introduction
                    239:
                    240: Table of Contents
                    241:
                    242: 1.1. Introduction
                    243: 1.2. Overview
                    244: 1.3. Terminology
                    245: 1.4. Typography
                    246:
                    247: 1.1. Introduction
                    248:
                    249: There is a lot of software freely available for Unix based systems, which
                    250: usually runs on NetBSD and other Unix-flavoured systems, too, sometimes with
                    251: some modifications. The NetBSD Packages Collection (pkgsrc) incorporates any
                    252: such changes necessary to make that software run, and makes the installation
                    253: (and de-installation) of the software package easy by means of a single
                    254: command.
                    255:
                    256: Once the software has been built, it is manipulated with the pkg_* tools so
                    257: that installation and de-installation, printing of an inventory of all
                    258: installed packages and retrieval of one-line comments or more verbose
                    259: descriptions are all simple.
                    260:
                    261: pkgsrc currently contains several thousand packages, including:
                    262:
                    263:   * www/apache - The Apache web server
1.7       wiz       264:
1.1       grant     265:   * www/mozilla - The Mozilla web browser
1.7       wiz       266:
1.1       grant     267:   * meta-pkgs/gnome - The GNOME Desktop Environment
1.7       wiz       268:
1.1       grant     269:   * meta-pkgs/kde3 - The K Desktop Environment
1.7       wiz       270:
1.1       grant     271: ...just to name a few.
                    272:
                    273: pkgsrc has built-in support for handling varying dependencies, such as pthreads
                    274: and X11, and extended features such as IPv6 support on a range of platforms.
                    275:
                    276: pkgsrc was derived from FreeBSD's ports system, and initially developed for
                    277: NetBSD only. Since then, pkgsrc has grown a lot, and now supports the following
                    278: platforms:
                    279:
                    280:   * Darwin (Mac OS X)
1.7       wiz       281:
1.3       hubertf   282:   * DragonFlyBSD
1.7       wiz       283:
1.1       grant     284:   * FreeBSD
1.7       wiz       285:
1.3       hubertf   286:   * Microsoft Windows, via Interix
1.7       wiz       287:
1.1       grant     288:   * IRIX
1.7       wiz       289:
1.1       grant     290:   * Linux
1.7       wiz       291:
1.1       grant     292:   * NetBSD (of course)
1.7       wiz       293:
1.1       grant     294:   * OpenBSD
1.7       wiz       295:
1.1       grant     296:   * Solaris
1.7       wiz       297:
1.1       grant     298: 1.2. Overview
                    299:
1.2       hubertf   300: This document is divided into two parts. The first, The pkgsrc user's guide,
1.1       grant     301: describes how one can use one of the packages in the Package Collection, either
                    302: by installing a precompiled binary package, or by building one's own copy using
1.2       hubertf   303: the NetBSD package system. The second part, The pkgsrc developer's guide,
                    304: explains how to prepare a package so it can be easily built by other NetBSD
                    305: users without knowing about the package's building details.
1.1       grant     306:
                    307: This document is available in various formats:
                    308:
                    309:   * HTML
1.7       wiz       310:
1.1       grant     311:   * PDF
1.7       wiz       312:
1.1       grant     313:   * PS
1.7       wiz       314:
1.1       grant     315:   * TXT
1.7       wiz       316:
1.1       grant     317: 1.3. Terminology
                    318:
                    319: There has been a lot of talk about "ports", "packages", etc. so far. Here is a
                    320: description of all the terminology used within this document.
                    321:
                    322: Package
1.7       wiz       323:
1.1       grant     324:     A set of files and building instructions that describe what's necessary to
                    325:     build a certain piece of software using pkgsrc. Packages are traditionally
                    326:     stored under /usr/pkgsrc.
1.7       wiz       327:
1.1       grant     328: The NetBSD package system
1.7       wiz       329:
1.1       grant     330:     This is the former name of "pkgsrc". It is part of the NetBSD operating
                    331:     system and can be bootstrap to run on non-NetBSD operating systems as well.
                    332:     It handles building (compiling), installing, and removing of packages.
1.7       wiz       333:
1.1       grant     334: Distfile
1.7       wiz       335:
1.1       grant     336:     This term describes the file or files that are provided by the author of
                    337:     the piece of software to distribute his work. All the changes necessary to
                    338:     build on NetBSD are reflected in the corresponding package. Usually the
                    339:     distfile is in the form of a compressed tar-archive, but other types are
                    340:     possible, too. Distfiles are usually stored below /usr/pkgsrc/distfiles.
1.7       wiz       341:
1.1       grant     342: Port
1.7       wiz       343:
1.1       grant     344:     This is the term used by FreeBSD and OpenBSD people for what we call a
                    345:     package. In NetBSD terminology, "port" refers to a different architecture.
1.7       wiz       346:
1.1       grant     347: Precompiled/binary package
1.7       wiz       348:
1.1       grant     349:     A set of binaries built with pkgsrc from a distfile and stuffed together in
                    350:     a single .tgz file so it can be installed on machines of the same machine
                    351:     architecture without the need to recompile. Packages are usually generated
                    352:     in /usr/pkgsrc/packages; there is also an archive on ftp.NetBSD.org.
1.7       wiz       353:
1.1       grant     354:     Sometimes, this is referred to by the term "package" too, especially in the
                    355:     context of precompiled packages.
1.7       wiz       356:
1.1       grant     357: Program
1.7       wiz       358:
1.1       grant     359:     The piece of software to be installed which will be constructed from all
                    360:     the files in the Distfile by the actions defined in the corresponding
                    361:     package.
1.7       wiz       362:
1.1       grant     363: 1.4. Typography
                    364:
                    365: When giving examples for commands, shell prompts are used to show if the
                    366: command should/can be issued as root, or if "normal" user privileges are
                    367: sufficient. We use a # for root's shell prompt, and a $ for users' shell
                    368: prompt, assuming they use the C-shell or tcsh.
                    369:
1.2       hubertf   370: The pkgsrc user's guide
1.1       grant     371:
                    372: Table of Contents
                    373:
                    374: 2. Where to get pkgsrc
1.7       wiz       375:
1.1       grant     376:     2.1. As tar file
                    377:     2.2. Via SUP
                    378:     2.3. Via CVS
1.7       wiz       379:
1.1       grant     380: 3. Using pkgsrc on systems other than NetBSD
1.7       wiz       381:
1.1       grant     382:     3.1. Bootstrapping pkgsrc
                    383:     3.2. Platform specific notes
1.7       wiz       384:
1.1       grant     385:         3.2.1. Darwin (Mac OS X)
                    386:         3.2.2. FreeBSD
                    387:         3.2.3. Interix
                    388:         3.2.4. IRIX
                    389:         3.2.5. OpenBSD
                    390:         3.2.6. Solaris
1.7       wiz       391:
1.1       grant     392: 4. Using pkgsrc
1.7       wiz       393:
1.1       grant     394:     4.1. Working with binary packages
1.7       wiz       395:
1.1       grant     396:         4.1.1. Where to get binary packages
                    397:         4.1.2. How to use binary packages
                    398:         4.1.3. A word of warning
1.7       wiz       399:
1.1       grant     400:     4.2. Building packages from source
1.7       wiz       401:
1.1       grant     402:         4.2.1. Requirements
                    403:         4.2.2. Fetching distfiles
                    404:         4.2.3. How to build and install
                    405:         4.2.4. Selecting the compiler
1.7       wiz       406:
1.1       grant     407: 5. Creating binary packages
1.7       wiz       408:
1.1       grant     409:     5.1. Building a single binary package
                    410:     5.2. Settings for creation of binary packages
                    411:     5.3. Doing a bulk build of all packages
1.7       wiz       412:
1.1       grant     413:         5.3.1. Configuration
                    414:         5.3.2. Other environmental considerations
                    415:         5.3.3. Operation
                    416:         5.3.4. What it does
                    417:         5.3.5. Disk space requirements
                    418:         5.3.6. Setting up a sandbox for chroot'ed builds
                    419:         5.3.7. Building a partial set of packages
1.7       wiz       420:
1.1       grant     421:     5.4. Creating a multiple CD-ROM packages collection
1.7       wiz       422:
1.1       grant     423:         5.4.1. Example of cdpack
1.7       wiz       424:
1.1       grant     425: 6. Frequently Asked Questions
1.7       wiz       426:
1.1       grant     427:     6.1. Is there a mailing list for pkg-related discussion?
                    428:     6.2. Where's the pkgviews documentation?
                    429:     6.3. Utilities for package management (pkgtools)
                    430:     6.4. How to use pkgsrc as non-root
                    431:     6.5. How can I install/use XFree86 from pkgsrc?
                    432:     6.6. How can I install/use X.org from pkgsrc?
                    433:     6.7. How to fetch files from behind a firewall
                    434:     6.8. How do I tell make fetch to do passive FTP?
                    435:     6.9. How to fetch all distfiles at once
1.7       wiz       436:     6.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
                    437:     6.11. What does "Could not find bsd.own.mk" mean?
1.1       grant     438:     6.12. Using 'sudo' with pkgsrc
                    439:     6.13. Configuration files handling and placement
                    440:     6.14. Automated security checks
1.7       wiz       441:
1.1       grant     442: Chapter 2. Where to get pkgsrc
                    443:
                    444: Table of Contents
                    445:
                    446: 2.1. As tar file
                    447: 2.2. Via SUP
                    448: 2.3. Via CVS
                    449:
                    450: There are three ways to get pkgsrc. Either as a tar file, via SUP, or via CVS.
                    451: All three ways are described here.
                    452:
                    453: 2.1. As tar file
                    454:
                    455: To get pkgsrc going, you need to get the pkgsrc.tar.gz file from ftp.NetBSD.org
                    456: and unpack it into /usr/pkgsrc.
                    457:
                    458: 2.2. Via SUP
                    459:
                    460: As an alternative to the tar file, you can get pkgsrc via the Software Update
                    461: Protocol, SUP. To do so, make sure your supfile has a line
                    462:
                    463: release=pkgsrc
                    464:
                    465: in it, see the examples in /usr/share/examples/supfiles, and that the /usr/
                    466: pkgsrc directory exists. Then, simply run sup -v /path/to/your/supfile.
                    467:
                    468: 2.3. Via CVS
                    469:
                    470: To get pkgsrc via CVS, make sure you have "cvs" installed. If not present on
                    471: your system, it can be found as precompiled binary on ftp.NetBSD.org. To do an
                    472: initial (full) checkout of pkgsrc, do the following steps:
                    473:
                    474: % setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
                    475: % setenv CVS_RSH ssh
                    476: % cd /usr
                    477: % cvs checkout -P pkgsrc
                    478:
                    479: This will create the pkgsrc directory in your /usr, and all the package source
                    480: will be stored under /usr/pkgsrc. To update pkgsrc after the initial checkout,
                    481: make sure you have CVS_RSH set as above, then do:
                    482:
                    483: % cd /usr/pkgsrc
                    484: % cvs -q update -dP
                    485:
                    486: Please also note that it is possible to have multiple copies of the pkgsrc
                    487: hierarchy in use at any one time - all work is done relatively within the
                    488: pkgsrc tree.
                    489:
                    490: Chapter 3. Using pkgsrc on systems other than NetBSD
                    491:
                    492: Table of Contents
                    493:
                    494: 3.1. Bootstrapping pkgsrc
                    495: 3.2. Platform specific notes
1.7       wiz       496:
1.1       grant     497:     3.2.1. Darwin (Mac OS X)
                    498:     3.2.2. FreeBSD
                    499:     3.2.3. Interix
                    500:     3.2.4. IRIX
                    501:     3.2.5. OpenBSD
                    502:     3.2.6. Solaris
1.7       wiz       503:
1.1       grant     504: 3.1. Bootstrapping pkgsrc
                    505:
                    506: For Operating Systems other than NetBSD, we provide a bootstrap kit to build
                    507: the required tools to use pkgsrc on your platform. Besides support for native
                    508: NetBSD, pkgsrc and the bootstrap kit have support for the following operating
                    509: systems:
                    510:
                    511:   * Darwin (Mac OS X)
1.7       wiz       512:
1.1       grant     513:   * FreeBSD
1.7       wiz       514:
1.1       grant     515:   * Interix (Windows 2000, XP, 2003)
1.7       wiz       516:
1.1       grant     517:   * IRIX
1.7       wiz       518:
1.1       grant     519:   * Linux
1.7       wiz       520:
1.1       grant     521:   * OpenBSD
1.7       wiz       522:
1.1       grant     523:   * Solaris
1.7       wiz       524:
1.1       grant     525: Support for other platforms is under development.
                    526:
                    527: Installing the bootstrap kit should be as simple as:
                    528:
                    529: # env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc
                    530: # cd pkgsrc/bootstrap
                    531: # ./bootstrap
                    532:
                    533: See Chapter 2, Where to get pkgsrc for other ways to get pkgsrc before
                    534: bootstrapping. The given bootstrap command will use the defaults of /usr/pkg
                    535: for the prefix where programs will be installed in, and /var/db/pkg for the
                    536: package database directory where pkgsrc will do it's internal bookkeeping.
                    537: However, these can also be set using command-line parameters.
                    538:
                    539: Binary packages for the pkgsrc tools and an initial set of packages is
1.7       wiz       540: available for supported platforms. An up-to-date list of these can be found on
1.1       grant     541: www.pkgsrc.org.
                    542:
                    543: 3.2. Platform specific notes
                    544:
                    545: Here are some platform-specific notes you should be aware of.
                    546:
                    547: 3.2.1. Darwin (Mac OS X)
                    548:
                    549: Darwin 5.x and 6.x are supported. There are two methods of using pkgsrc on Mac
                    550: OS X, by using a disk image, or a UFS partition.
                    551:
                    552: Before you start, you will need to download and install the Mac OS X Developer
                    553: Tools from Apple's Developer Connection. See http://developer.apple.com/macosx/
1.7       wiz       554: for details. Also, make sure you install X11 for Mac OS X and the X11 SDK from
1.1       grant     555: http://www.apple.com/macosx/x11/download/ if you intend to build packages that
                    556: use the X11 Window System.
                    557:
                    558: If you already have a UFS partition, or have a spare partition that you can
                    559: format as UFS, it is recommended to use that instead of the disk image. It'll
                    560: be somewhat faster and will mount automatically at boot time, where you must
                    561: manually mount a disk image.
                    562:
                    563: Note
                    564:
                    565: You cannot use a HFS+ file system for pkgsrc, because pkgsrc currently requires
                    566: the filesystem to be case-sensitive, and HFS+ is not.
                    567:
                    568: 3.2.1.1. Using a disk image
                    569:
                    570: Create the disk image:
                    571:
                    572: # cd pkgsrc/bootstrap
                    573: # ./ufsdiskimage create ~/Documents/NetBSD 512 # megabytes - season to taste
                    574: # ./ufsdiskimage mount ~/Documents/NetBSD
                    575: # sudo chown `id -u`:`id -g` /Volumes/NetBSD
                    576:
                    577: That's it!
                    578:
                    579: 3.2.1.2. Using a UFS partition
                    580:
                    581: By default, /usr will be on your root file system, normally HFS+. It is
                    582: possible to use the default prefix of /usr/pkg by symlinking /usr/pkg to a
                    583: directory on a UFS file system. Obviously, another symlink is required if you
                    584: want to place the package database directory outside the prefix. e.g.
                    585:
                    586: # ./bootstrap --pkgdbdir=/usr/pkg/pkgdb --pkgsrcdir=/Volumes/ufs/pkgsrc
                    587:
                    588: If you created your partitions at the time of installing Mac OS X and formatted
                    589: the target partition as UFS, it should automatically mount on /Volumes/<volume
                    590: name> when the machine boots. If you are (re)formatting a partition as UFS, you
                    591: need to ensure that the partition map correctly reflects "Apple_UFS" and not
                    592: "Apple_HFS".
                    593:
                    594: The problem is that none of the disk tools will let you touch a disk that is
                    595: booted from. You can unmount the partition, but even if you newfs it, the
                    596: partition type will be incorrect and the automounter won't mount it. It can be
                    597: mounted manually, but it won't appear in Finder.
                    598:
                    599: You'll need to boot off of the OS X Installation (User) CD. When the
                    600: Installation program starts, go up to the menu and select Disk Utility. Now,
                    601: you will be able to select the partition you want to be UFS, and Format it
                    602: Apple UFS. Quit the Disk Utility, quit the installer which will reboot your
                    603: machine. The new UFS file system will appear in Finder.
                    604:
                    605: Be aware that the permissions on the new file system will be writable by root
                    606: only.
                    607:
                    608: This note is as of 10.2 (Jaguar) and applies to earlier versions. Hopefully
                    609: Apple will fix Disk Utility in 10.3 (Panther).
                    610:
                    611: 3.2.2. FreeBSD
                    612:
                    613: FreeBSD 4.7 and 5.0 have been tested and are supported, other versions may
                    614: work.
                    615:
                    616: Care should be taken so that the tools that this kit installs do not conflict
                    617: with the FreeBSD userland tools. There are several steps:
                    618:
                    619:  1. FreeBSD stores its ports pkg database in /var/db/pkg. It is therefore
                    620:     recommended that you choose a different location (e.g. /usr/pkgdb) by using
                    621:     the --pkgdbdir option to the bootstrap script.
1.7       wiz       622:
1.1       grant     623:  2. If you do not intend to use the FreeBSD ports tools, it's probably a good
                    624:     idea to move them out of the way to avoid confusion, e.g.
1.7       wiz       625:
1.1       grant     626:     # cd /usr/sbin
                    627:     # mv pkg_add pkg_add.orig
                    628:     # mv pkg_create pkg_create.orig
                    629:     # mv pkg_delete pkg_delete.orig
                    630:     # mv pkg_info pkg_info.orig
1.7       wiz       631:
1.1       grant     632:  3. An example /etc/mk.conf file will be placed in /etc/mk.conf.example file
                    633:     when you use the bootstrap script.
1.7       wiz       634:
1.1       grant     635: 3.2.3. Interix
                    636:
                    637: Interix is a POSIX compatible subsystem for the Windows NT kernel, providing a
                    638: Unix-like environment with a tighter kernel integration than available with
                    639: Cygwin. It is part of the Windows Services for Unix package, available for free
1.7       wiz       640: for any licensed copy of Windows 2000, XP, or 2003. SFU can be downloaded from
1.1       grant     641: http://www.microsoft.com/windows/sfu/.
                    642:
                    643: Services for Unix 3.5, current as of this writing, has been tested. 3.0 or 3.1
                    644: may work, but are not officially supported. (The main difference in 3.0/3.1 is
                    645: lack of pthreads.)
                    646:
1.2       hubertf   647: 3.2.3.1. When installing Interix/SFU
1.1       grant     648:
                    649: At an absolute minimum, the following packages must be installed from the
                    650: Windows Services for Unix 3.5 distribution in order to use pkgsrc:
                    651:
                    652:   * Utilities -> Base Utilities
1.7       wiz       653:
1.1       grant     654:   * Interix GNU Components -> (all)
1.7       wiz       655:
1.1       grant     656:   * Remote Connectivity
1.7       wiz       657:
1.1       grant     658:   * Interix SDK
1.7       wiz       659:
1.1       grant     660: When using pkgsrc on Interix, DO NOT install the Utilities subcomponent "UNIX
                    661: Perl". That is Perl 5.6 without shared module support, installed to /usr/local,
                    662: and will only cause confusion. Instead, install Perl 5.8 from pkgsrc (or from a
                    663: binary package).
                    664:
                    665: The Remote Connectivity subcomponent "Windows Remote Shell Service" does not
                    666: need to be installed, but Remote Connectivity itself should be installed in
                    667: order to have a working inetd.
                    668:
                    669: Finally, during installation you may be asked whether to enable setuid behavior
                    670: for Interix programs, and whether to make pathnames default to case-sensitive.
                    671: Setuid should be enabled, and case-sensitivity MUST be enabled. (Without
                    672: case-sensitivity, a large number of packages including perl will not build.)
                    673:
                    674: 3.2.3.2. What to do if Interix/SFU is already installed
                    675:
                    676: If SFU is already installed and you wish to alter these settings to work with
                    677: pkgsrc, note the following things.
                    678:
                    679:   * To uninstall UNIX Perl, use Add/Remove Programs, select Microsoft Windows
                    680:     Services for UNIX, then click Change. In the installer, choose Add or
                    681:     Remove, then uncheck Utilities->UNIX Perl.
1.7       wiz       682:
1.1       grant     683:   * To enable case-sensitivity for the filesystem, run REGEDIT.EXE, and change
                    684:     the following registry key:
1.7       wiz       685:
1.1       grant     686:     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel
1.7       wiz       687:
1.1       grant     688:     Set the DWORD value "obcaseinsensitive" to 0; then reboot.
1.7       wiz       689:
1.1       grant     690:   * To enable setuid binaries (optional), run REGEDIT.EXE, and change the
                    691:     following registry key:
1.7       wiz       692:
1.1       grant     693:     HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Services for UNIX
1.7       wiz       694:
1.1       grant     695:     Set the DWORD value "EnableSetuidBinaries" to 1; then reboot.
1.7       wiz       696:
1.1       grant     697: 3.2.3.3. Important notes for using pkgsrc
                    698:
                    699: The package imanager (either the pkgsrc "su" user, or the user running
                    700: "pkg_add") must be a member of the local Administrators group. Such a user must
                    701: also be used to run the bootstrap. This is slightly relaxed from the normal
                    702: pkgsrc requirement of "root".
                    703:
                    704: The package manager should use a umask of 002. "make install" will
                    705: automatically complain if this is not the case. This ensures that directories
                    706: written in /var/db/pkg are Administrators-group writeable.
                    707:
                    708: The popular Interix binary packages from http://www.interopsystems.com/ use an
                    709: older version of pkgsrc's pkg_* tools. Ideally, these should NOT be used in
                    710: conjunction with pkgsrc. If you choose to use them at the same time as the
                    711: pkgsrc packages, ensure that you use the proper pkg_* tools for each type of
                    712: binary package.
                    713:
                    714: 3.2.4. IRIX
                    715:
                    716: You will need a working C compiler, either gcc or SGI's MIPS and MIPSpro
                    717: compiler (cc/c89). Please set the CC environment variable according to your
                    718: preference. If you do not have a license for the MIPSpro compiler suite, you
                    719: can download a gcc tardist file from http://freeware.sgi.com/.
                    720:
                    721: Please note that you will need IRIX 6.5.17 or higher, as this is the earliest
                    722: version of IRIX providing support for if_indextoname(3), if_nametoindex(3),
                    723: etc.
                    724:
                    725: At this point in time, pkgsrc only supports one ABI. That is, you can not
                    726: switch between the old 32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If
                    727: you start out using "abi=n32", that's what all your packages will be built
                    728: with.
                    729:
                    730: Therefore, please make sure that you have no conflicting CFLAGS in your
                    731: environment or the /etc/mk.conf. Particularly, make sure that you do not try to
                    732: link n32 object files with lib64 or vice versa. Check your /etc/
                    733: compiler.defaults!
                    734:
                    735: If you have the actual pkgsrc tree mounted via NFS from a different host,
                    736: please make sure to set WRKOBJDIR to a local directory, as it appears that IRIX
                    737: linker occasionally runs into issues when trying to link over a network mounted
                    738: filesystem.
                    739:
                    740: The bootstrapping process should set all the right options for programs such as
                    741: imake(1), but you may want to set some options depending on your local setup.
                    742: Please see pkgsrc/mk/bsd.pkg.defaults.mk and, of course, your compilers man
                    743: pages for details.
                    744:
                    745: 3.2.5. OpenBSD
                    746:
                    747: OpenBSD 3.0 and 3.2 are tested and supported.
                    748:
                    749: Care should be taken so that the tools that this kit installs do not conflict
                    750: with the OpenBSD userland tools. There are several steps:
                    751:
                    752:  1. OpenBSD stores its ports pkg database in /var/db/pkg. It is therefore
                    753:     recommended that you choose a different location (e.g. /usr/pkgdb) by using
                    754:     the --pkgdbdir option to the bootstrap script.
1.7       wiz       755:
1.1       grant     756:  2. If you do not intend to use the OpenBSD ports tools, it's probably a good
                    757:     idea to move them out of the way to avoid confusion, e.g.
1.7       wiz       758:
1.1       grant     759:     # cd /usr/sbin
                    760:     # mv pkg_add pkg_add.orig
                    761:     # mv pkg_create pkg_create.orig
                    762:     # mv pkg_delete pkg_delete.orig
                    763:     # mv pkg_info pkg_info.orig
1.7       wiz       764:
1.1       grant     765:  3. An example /etc/mk.conf file will be placed in /etc/mk.conf.example file
                    766:     when you use the bootstrap script. OpenBSD's make program uses /etc/mk.conf
                    767:     as well. You can work around this by enclosing all the pkgsrc specific
                    768:     parts of the file with:
1.7       wiz       769:
1.1       grant     770:     .ifdef BSD_PKG_MK
                    771:     # pkgsrc stuff, e.g. insert bsd.pkg.defaults.mk or similar here
                    772:     .else
                    773:     # OpenBSD stuff
                    774:     .endif
1.7       wiz       775:
1.1       grant     776:
                    777: 3.2.6. Solaris
                    778:
                    779: Solaris 2.6 through 9 are supported on both x86 and sparc. You will need a
                    780: working C compiler. Both gcc 2.95.3 and Sun WorkShop 5 have been tested.
                    781:
                    782: The following packages are required on Solaris 8 for the bootstrap process and
                    783: to build packages.
                    784:
                    785:   * SUNWsprot
1.7       wiz       786:
1.1       grant     787:   * SUNWarc
1.7       wiz       788:
1.1       grant     789:   * SUNWbtool
1.7       wiz       790:
1.1       grant     791:   * SUNWtoo
1.7       wiz       792:
1.1       grant     793:   * SUNWlibm
1.7       wiz       794:
1.1       grant     795: Please note the use of GNU binutils on Solaris is not supported.
                    796:
                    797: 3.2.6.1. If you are using gcc
                    798:
                    799: It makes life much simpler if you only use the same gcc consistently for
                    800: building all packages.
                    801:
                    802: It is recommended that an external gcc be used only for bootstrapping, then
                    803: either build gcc from lang/gcc or install a binary gcc package, then remove gcc
                    804: used during bootstrapping.
                    805:
                    806: Binary packages of gcc can be found through http://www.sun.com/bigadmin/common/
                    807: freewareSearch.html.
                    808:
                    809: 3.2.6.2. If you are using Sun WorkShop
                    810:
                    811: You will need at least the following packages installed (from WorkShop 5.0)
                    812:
                    813:   * SPROcc - Sun WorkShop Compiler C 5.0
1.7       wiz       814:
1.1       grant     815:   * SPROcpl - Sun WorkShop Compiler C++ 5.0
1.7       wiz       816:
1.1       grant     817:   * SPROild - Sun WorkShop Incremental Linker
1.7       wiz       818:
1.1       grant     819:   * SPROlang - Sun WorkShop Compilers common components
1.7       wiz       820:
1.1       grant     821: You should set CC, CXX and optionally, CPP in /etc/mk.conf, eg.
                    822:
                    823: CC=        cc
                    824: CXX=    CC
                    825: CPP=    /usr/ccs/lib/cpp
                    826:
                    827: You may also want to build 64-bit binaries, eg.
                    828:
                    829: CFLAGS= -xtarget=ultra -xarch=v9
                    830:
                    831: Whichever compiler you use, please ensure the compiler tools and your $prefix
                    832: are in your PATH. This includes /usr/ccs/{bin,lib} and eg. /usr/pkg/{bin,sbin}.
                    833:
                    834: Chapter 4. Using pkgsrc
                    835:
                    836: Table of Contents
                    837:
                    838: 4.1. Working with binary packages
1.7       wiz       839:
1.1       grant     840:     4.1.1. Where to get binary packages
                    841:     4.1.2. How to use binary packages
                    842:     4.1.3. A word of warning
1.7       wiz       843:
1.1       grant     844: 4.2. Building packages from source
1.7       wiz       845:
1.1       grant     846:     4.2.1. Requirements
                    847:     4.2.2. Fetching distfiles
                    848:     4.2.3. How to build and install
                    849:     4.2.4. Selecting the compiler
1.7       wiz       850:
1.1       grant     851: 4.1. Working with binary packages
                    852:
                    853: This section describes how to find, retrieve and install a precompiled binary
                    854: package that someone else already prepared for your type of machine.
                    855:
                    856: 4.1.1. Where to get binary packages
                    857:
                    858: Precompiled packages are stored on ftp.NetBSD.org and its mirrors in the
                    859: directory /pub/NetBSD/packages for anonymous FTP access. Please pick the right
                    860: subdirectory there as indicated by uname -p. In that directory, there is a
                    861: subdirectory for each category plus a subdirectory All which includes the
                    862: actual binaries in .tgz files. The category subdirectories use symbolic links
                    863: to those files (this is the same directory layout as in /usr/pkgsrc/packages).
                    864:
                    865: This same directory layout applies for CDROM distributions, only that the
                    866: directory may be rooted somewhere else, probably somewhere below /cdrom. Please
                    867: consult your CDROMs documentation for the exact location.
                    868:
                    869: 4.1.2. How to use binary packages
                    870:
                    871: If you have the files on a CDROM or downloaded them to your hard disk, youcan
                    872: install them with the following command (be sure tosu to root first):
                    873:
                    874: # pkg_add /path/to/package.tgz
                    875:
                    876: If you have FTP access and you don't want to download the packages via FTP
                    877: prior to installation, you can do this automatically by giving pkg_add an FTP
                    878: URL:
                    879:
                    880: # pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSvers>/<arch>/All/package.tgz
                    881:
                    882: If there is any doubt, the uname utility can be used to determine the <OSvers>,
                    883: and <arch> by running uname -rp.
                    884:
                    885: Also note that any prerequisite packages needed to run the package in question
                    886: will be installed, too, assuming they are present where you install from.
                    887:
                    888: After you've installed packages, be sure to have /usr/pkg/bin in your PATH so
                    889: you can actually start the just installed program.
                    890:
                    891: 4.1.3. A word of warning
                    892:
                    893: Please pay very careful attention to the warnings expressed in the pkg_add(1)
                    894: manual page about the inherent dangers of installing binary packages which you
                    895: did not create yourself, and the security holes that can be introduced onto
                    896: your system by indiscriminate adding of such files.
                    897:
                    898: 4.2. Building packages from source
                    899:
                    900: This assumes that the package is already in pkgsrc. If it is not, see Part II,
1.2       hubertf   901: "The pkgsrc developer's guide".
1.1       grant     902:
                    903: 4.2.1. Requirements
                    904:
                    905: To build packages from source on a NetBSD system the "comp" and the "text"
                    906: distribution sets must be installed. If you want to build X11 related packages
                    907: the "xbase" and "xcomp" distribution sets are required, too.
                    908:
                    909: 4.2.2. Fetching distfiles
                    910:
                    911: The distfile (i.e. the unmodified source) must exist on your system for the
1.7       wiz       912: packages system to be able to build it. If it does not exist, pkgsrc will use
1.1       grant     913: ftp(1) to fetch it automatically.
                    914:
                    915: You can overwrite some of the major distribution sites to fit to sites that are
                    916: close to your own. Have a look at pkgsrc/mk/bsd.pkg.defaults.mk to find some
                    917: examples - in particular, look for the MASTER_SORT, MASTER_SORT_REGEX and
                    918: INET_COUNTRY definitions. This may save some of your bandwidth and time.
                    919:
                    920: You can change these settings either in your shell's environment, or, if you
                    921: want to keep the settings, by editing the /etc/mk.conf file, and adding the
                    922: definitions there.
                    923:
                    924: If you don't have a permanent Internet connection and you want to know which
                    925: files to download, make fetch-list will tell you what you'll need. Put these
                    926: distfiles into /usr/pkgsrc/distfiles.
                    927:
                    928: 4.2.3. How to build and install
                    929:
                    930: Assuming that the distfile has been fetched (see previous section), become root
                    931: and change into the relevant directory and running make. For example, type
                    932:
                    933: % cd misc/figlet
                    934: % make
                    935:
                    936: at the shell prompt to build the various components of the package, and
                    937:
                    938: # make install
                    939:
                    940: to install the various components into the correct places on your system.
                    941: Installing the package on your system requires you to be root. However, pkgsrc
                    942: has a just-in-time-su feature, which allows you to only become root for the
                    943: actual installation step
                    944:
                    945: Taking the figlet utility as an example, we can install it on our system by
                    946: building as shown in Appendix B, Build logs.
                    947:
                    948: The program is installed under the default root of the packages tree - /usr/
                    949: pkg. Should this not conform to your tastes, set the LOCALBASE variable in your
                    950: environment, and it will use that value as the root of your packages tree. So,
                    951: to use /usr/local, set LOCALBASE=/usr/local in your environment. Please note
                    952: that you should use a directory which is dedicated to packages and not shared
                    953: with other programs (ie, do not try and use LOCALBASE=/usr). Also, you should
                    954: not try to add any of your own files or directories (such as src/, obj/, or
                    955: pkgsrc/) below the LOCALBASE tree. This is to prevent possible conflicts
                    956: between programs and other files installed by the package system and whatever
                    957: else may have been installed there.
                    958:
                    959: Some packages look in /etc/mk.conf to alter some configuration options at build
                    960: time. Have a look at pkgsrc/mk/bsd.pkg.defaults.mk to get an overview of what
                    961: will be set there by default. Environment variables such as LOCALBASE can be
                    962: set in /etc/mk.conf to save having to remember to set them each time you want
                    963: to use pkgsrc.
                    964:
                    965: Occasionally, people want to "look under the covers" to see what is going on
                    966: when a package is building or being installed. This may be for debugging
                    967: purposes, or out of simple curiosity. A number of utility values have been
                    968: added to help with this.
                    969:
                    970:  1. If you invoke the make(1) command with PKG_DEBUG_LEVEL=2, then a huge
                    971:     amount of information will be displayed. For example,
1.7       wiz       972:
1.1       grant     973:     make patch PKG_DEBUG_LEVEL=2
1.7       wiz       974:
1.1       grant     975:     will show all the commands that are invoked, up to and including the
                    976:     "patch" stage.
1.7       wiz       977:
1.1       grant     978:  2. If you want to know the value of a certain make(1) definition, then the
                    979:     VARNAME definition should be used, in conjunction with the show-var target.
                    980:     e.g. to show the expansion of the make(1) variable DISTFILES:
1.7       wiz       981:
1.1       grant     982:     % make show-var VARNAME=LOCALBASE
                    983:     /usr/pkg
                    984:     %
1.7       wiz       985:
                    986:
1.1       grant     987:
                    988: If you want to install a binary package that you've either created yourself
                    989: (see next section), that you put into pkgsrc/packages manually or that is
1.8       wiz       990: located on a remote FTP server, you can use the "bin-install" target. This
1.1       grant     991: target will install a binary package - if available - via pkg_add(1), else do a
                    992: make package. The list of remote FTP sites searched is kept in the variable
                    993: BINPKG_SITE, which defaults to ftp.NetBSD.org. Any flags that should be added
                    994: to pkg_add(1) can be put into BIN_INSTALL_FLAGS. See pkgsrc/mk/
                    995: bsd.pkg.defaults.mk for more details.
                    996:
                    997: A final word of warning: If you setup a system that has a non-standard setting
                    998: for LOCALBASE, be sure to set that before any packages are installed, as you
                    999: can not use several directories for the same purpose. Doing so will result in
                   1000: pkgsrc not being able to properly detect your installed packages, and fail
                   1001: miserably. Note also that precompiled binary packages are usually built with
                   1002: the default LOCALBASE of /usr/pkg, and that you should not install any if you
                   1003: use a non-standard LOCALBASE.
                   1004:
                   1005: 4.2.4. Selecting the compiler
                   1006:
                   1007: By default, pkgsrc will use GCC to build packages. This may be overridden by
                   1008: setting the following variables in /etc/mk.conf:
                   1009:
                   1010: PKGSRC_COMPILER:
1.7       wiz      1011:
1.1       grant    1012:     This is a list of values specifying the chain of compilers to invoke when
                   1013:     building packages. Valid values are:
1.7       wiz      1014:
1.1       grant    1015:       * distcc: distributed C/C++ (chainable)
1.7       wiz      1016:
1.1       grant    1017:       * ccache: compiler cache (chainable)
1.7       wiz      1018:
1.1       grant    1019:       * gcc: GNU C/C++ Compiler
1.7       wiz      1020:
1.1       grant    1021:       * mipspro: Silicon Graphics, Inc. MIPSpro (n32/n64)
1.7       wiz      1022:
1.1       grant    1023:       * mipspro: Silicon Graphics, Inc. MIPSpro (o32)
1.7       wiz      1024:
1.1       grant    1025:       * sunpro: Microsystems, Inc. WorkShip/Forte/Sun ONE Studio
1.7       wiz      1026:
1.1       grant    1027:     The default is "gcc". You can use ccache and/or distcc with an appropriate
                   1028:     PKGSRC_COMPILER setting, e.g. "ccache gcc". This variable should always be
                   1029:     terminated with a value for a real compiler.
1.7       wiz      1030:
1.1       grant    1031: GCC_REQD:
1.7       wiz      1032:
1.1       grant    1033:     This specifies the minimum version of GCC to use when building packages. If
                   1034:     the system GCC doesn't satisfy this requirement, then pkgsrc will build and
                   1035:     install one of the GCC packages to use instead.
1.7       wiz      1036:
1.1       grant    1037: Chapter 5. Creating binary packages
                   1038:
                   1039: Table of Contents
                   1040:
                   1041: 5.1. Building a single binary package
                   1042: 5.2. Settings for creation of binary packages
                   1043: 5.3. Doing a bulk build of all packages
1.7       wiz      1044:
1.1       grant    1045:     5.3.1. Configuration
                   1046:     5.3.2. Other environmental considerations
                   1047:     5.3.3. Operation
                   1048:     5.3.4. What it does
                   1049:     5.3.5. Disk space requirements
                   1050:     5.3.6. Setting up a sandbox for chroot'ed builds
                   1051:     5.3.7. Building a partial set of packages
1.7       wiz      1052:
1.1       grant    1053: 5.4. Creating a multiple CD-ROM packages collection
1.7       wiz      1054:
1.1       grant    1055:     5.4.1. Example of cdpack
1.7       wiz      1056:
1.1       grant    1057: 5.1. Building a single binary package
                   1058:
                   1059: Once you have built and installed a package, you can create a binary package
                   1060: which can be installed on another system with pkg_add(1) This saves having to
                   1061: build the same package on a group of hosts and wasting CPU time. It also
                   1062: provides a simple means for others to install your package, should you
                   1063: distribute it.
                   1064:
                   1065: To create a binary package, change into the appropriate directory in pkgsrc,
                   1066: and run make package:
                   1067:
                   1068: # cd misc/figlet
                   1069: # make package
                   1070:
                   1071: This will build and install your package (if not already done), and then build
                   1072: a binary package from what was installed. You can then use the pkg_* tools to
                   1073: manipulate it. Binary packages are created by default in /usr/pkgsrc/packages,
                   1074: in the form of a gzipped tar file. See Section B.2, "Packaging figlet" for a
                   1075: continuation of the above misc/figlet example.
                   1076:
                   1077: See Chapter 14, Submitting and Committing for information on how to submit such
                   1078: a binary package.
                   1079:
                   1080: 5.2. Settings for creation of binary packages
                   1081:
                   1082: See Section 11.3, "Other helpful targets".
                   1083:
                   1084: 5.3. Doing a bulk build of all packages
                   1085:
                   1086: If you want to get a full set of precompiled binary packages, this section
                   1087: describes how to get them. Beware that the bulk build will remove all currently
                   1088: installed packages from your system! Having a FTP server configured either on
                   1089: the machine doing the bulk builds or on a nearby NFS server can help to make
                   1090: the packages available to everyone. See ftpd(8) for more information. If you
                   1091: use a remote NFS server's storage, be sure to not actually compile on NFS
                   1092: storage, as this slows things down a lot.
                   1093:
                   1094: 5.3.1. Configuration
                   1095:
                   1096: 5.3.1.1. /etc/mk.conf
                   1097:
                   1098: You may want to set things in /etc/mk.conf. Look at pkgsrc/mk/
                   1099: bsd.pkg.defaults.mk for details of the default settings. You will want to
                   1100: ensure that ACCEPTABLE_LICENSES meet your local policy. As used in this
                   1101: example, _ACCEPTABLE=yes accepts all licenses.
                   1102:
                   1103: PACKAGES?=      ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
                   1104: WRKOBJDIR?=     /usr/tmp/pkgsrc   # build here instead of in pkgsrc
                   1105: BSDSRCDIR=      /usr/src
                   1106: BSDXSRCDIR=     /usr/xsrc         # for x11/xservers
                   1107: OBJHOSTNAME?=   yes               # use work.`hostname`
                   1108: FAILOVER_FETCH= yes               # insist on the correct checksum
                   1109: PKG_DEVELOPER?= yes
                   1110: _ACCEPTABLE=    yes
                   1111:
                   1112: 5.3.1.2. build.conf
                   1113:
                   1114: In pkgsrc/mk/bulk, copy build.conf-example to build.conf and edit it, following
                   1115: the comments in that file. This is the config file that determines where log
                   1116: files are generated after the build, where to mail the build report to, where
                   1117: your pkgsrc tree is located and which user to su(8) to to do a cvs update.
                   1118:
                   1119: 5.3.1.3. pre-build.local
                   1120:
                   1121: It is possible to configure the bulk build to perform certain site specific
                   1122: tasks at the end of the pre-build stage. If the file pre-build.local exists in
                   1123: /usr/pkgsrc/mk/bulk it will be executed (as a sh(1) script) at the end of the
                   1124: usual pre-build stage. An example use of pre-build.local is to have the line:
                   1125:
                   1126: # echo "I do not have enough disk space to build this pig." \
                   1127:     > pkgsrc/games/crafty-book-enormous/$BROKENF
                   1128:
                   1129: to prevent the system from trying to build a particular package which requires
                   1130: nearly 3 GB of disk space.
                   1131:
                   1132: 5.3.2. Other environmental considerations
                   1133:
                   1134: As /usr/pkg will be completely deleted at the start of bulk builds, make sure
                   1135: your login shell is placed somewhere else. Either drop it into /usr/local/bin
1.7       wiz      1136: (and adjust your login shell in the passwd file), or (re-)install it via
1.1       grant    1137: pkg_add(1) from /etc/rc.local, so you can login after a reboot (remember that
                   1138: your current process won't die if the package is removed, you just can't start
                   1139: any new instances of the shell any more). Also, if you use NetBSD earlier than
                   1140: 1.5, or you still want to use the pkgsrc version of ssh for some reason, be
                   1141: sure to install ssh before starting it from rc.local:
                   1142:
                   1143: ( cd /usr/pkgsrc/security/ssh ; make bulk-install )
                   1144: if [ -f /usr/pkg/etc/rc.d/sshd ]; then
                   1145:     /usr/pkg/etc/rc.d/sshd
                   1146: fi
                   1147:
                   1148: Not doing so will result in you being not able to log in via ssh after the bulk
                   1149: build is finished or if the machine gets rebooted or crashes. You have been
                   1150: warned! :)
                   1151:
                   1152: 5.3.3. Operation
                   1153:
                   1154: Make sure you don't need any of the packages still installed.
                   1155:
                   1156: Warning
                   1157:
                   1158: During the bulk build, all packages will be removed!
                   1159:
                   1160: Be sure to remove all other things that might interfere with builds, like some
                   1161: libs installed in /usr/local, etc. then become root and type:
                   1162:
                   1163: # cd /usr/pkgsrc
                   1164: # sh mk/bulk/build
                   1165:
                   1166: If for some reason your last build didn't complete (power failure, system
                   1167: panic, ...), you can continue it by running:
                   1168:
                   1169: # sh mk/bulk/build restart
                   1170:
                   1171: At the end of the bulk build, you will get a summary via mail, and find build
                   1172: logs in the directory specified by FTP in the build.conf file.
                   1173:
                   1174: 5.3.4. What it does
                   1175:
                   1176: The bulk builds consist of three steps:
                   1177:
                   1178: 1. pre-build
1.7       wiz      1179:
1.1       grant    1180:     The script updates your pkgsrc tree via (anon)cvs, then cleans out any
                   1181:     broken distfiles, and removes all packages installed.
1.7       wiz      1182:
1.1       grant    1183: 2. the bulk build
1.7       wiz      1184:
1.1       grant    1185:     This is basically "make bulk-package" with an optimised order in which
                   1186:     packages will be built. Packages that don't require other packages will be
                   1187:     built first, and packages with many dependencies will be built later.
1.7       wiz      1188:
1.1       grant    1189: 3. post-build
1.7       wiz      1190:
1.1       grant    1191:     Generates a report that's placed in the directory specified in the
                   1192:     build.conf file named broken.html, a short version of that report will also
                   1193:     be mailed to the build's admin.
1.7       wiz      1194:
1.1       grant    1195: During the build, a list of broken packages will be compiled in /usr/pkgsrc
                   1196: /.broken (or .../.broken.${MACHINE} if OBJMACHINE is set), individual build
                   1197: logs of broken builds can be found in the package's directory. These files are
                   1198: used by the bulk-targets to mark broken builds to not waste time trying to
                   1199: rebuild them, and they can be used to debug these broken package builds later.
                   1200:
                   1201: 5.3.5. Disk space requirements
                   1202:
                   1203: Currently, roughly the following requirements are valid for NetBSD 2.0/i386:
                   1204:
                   1205:   * 10 GB - distfiles (NFS ok)
1.7       wiz      1206:
1.1       grant    1207:   * 8 GB - full set of all binaries (NFS ok)
1.7       wiz      1208:
1.1       grant    1209:   * 5 GB - temp space for compiling (local disk recommended)
1.7       wiz      1210:
1.1       grant    1211: Note that all pkgs will be de-installed as soon as they are turned into a
                   1212: binary package, and that sources are removed, so there is no excessively huge
                   1213: demand to disk space. Afterwards, if the package is needed again, it will be
                   1214: installed via pkg_add(1) instead of building again, so there are no cycles
                   1215: wasted by recompiling.
                   1216:
                   1217: 5.3.6. Setting up a sandbox for chroot'ed builds
                   1218:
                   1219: If you don't want all the pkgs nuked from a machine (rendering it useless for
                   1220: anything but pkg compiling), there is the possibility of doing the pkg bulk
                   1221: build inside a chroot environment.
                   1222:
                   1223: The first step to do so is setting up a chroot sandbox, e.g. /usr/sandbox.
                   1224: After extracting all the sets from a NetBSD installation or doing a make
                   1225: distribution DESTDIR=/usr/sandbox in /usr/src/etc, be sure the following items
                   1226: are present and properly configured:
                   1227:
                   1228:  1. Kernel
1.7       wiz      1229:
1.1       grant    1230:     # cp /netbsd /usr/sandbox
1.7       wiz      1231:
1.1       grant    1232:  2. /dev/*
1.7       wiz      1233:
1.1       grant    1234:     # cd /usr/sandbox/dev ; sh MAKEDEV all
1.7       wiz      1235:
1.1       grant    1236:  3. /etc/resolv.conf (for security/smtpd and mail):
1.7       wiz      1237:
1.1       grant    1238:     # cp /etc/resolv.conf /usr/sandbox/etc
1.7       wiz      1239:
1.1       grant    1240:  4. Working(!) mail config (hostname, sendmail.cf):
1.7       wiz      1241:
1.1       grant    1242:     # cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail
1.7       wiz      1243:
1.1       grant    1244:  5. /etc/localtime (for security/smtpd):
1.7       wiz      1245:
1.1       grant    1246:     # ln -sf /usr/share/zoneinfo/UTC /usr/sandbox/etc/localtime
1.7       wiz      1247:
1.1       grant    1248:  6. /usr/src (system sources, for sysutils/aperture, net/ppp-mppe):
1.7       wiz      1249:
1.1       grant    1250:     # ln -s ../disk1/cvs .
                   1251:     # ln -s cvs/src-1.6 src
1.7       wiz      1252:
1.1       grant    1253:  7. Create /var/db/pkg (not part of default install):
1.7       wiz      1254:
1.1       grant    1255:     # mkdir /usr/sandbox/var/db/pkg
1.7       wiz      1256:
1.1       grant    1257:  8. Create /usr/pkg (not part of default install):
1.7       wiz      1258:
1.1       grant    1259:     # mkdir /usr/sandbox/usr/pkg
1.7       wiz      1260:
1.1       grant    1261:  9. Checkout pkgsrc via cvs into /usr/sandbox/usr/pkgsrc:
1.7       wiz      1262:
1.1       grant    1263:     # cd /usr/sandbox/usr
                   1264:     # cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -d -P pkgsrc
1.7       wiz      1265:
1.1       grant    1266:     Do not mount/link this to the copy of your pkgsrc tree you do development
                   1267:     in, as this will likely cause problems!
1.7       wiz      1268:
1.1       grant    1269: 10. Make /usr/sandbox/usr/pkgsrc/packages and .../distfiles point somewhere
                   1270:     appropriate. NFS- and/or nullfs-mounts may come in handy!
1.7       wiz      1271:
1.1       grant    1272: 11. Edit /etc/mk.conf, see Section 5.3.1.1, "/etc/mk.conf".
1.7       wiz      1273:
1.1       grant    1274: 12. Adjust mk/bulk/build.conf to suit your needs.
1.7       wiz      1275:
1.1       grant    1276: 13. If you have set CVS_USER in build.conf, make sure that account exists and
                   1277:     can do a cvs ${CVS_FLAGS} update properly!
1.7       wiz      1278:
1.1       grant    1279: When the chroot sandbox is setup, you can start the build with the following
                   1280: steps:
                   1281:
                   1282: # cd /usr/sandbox/usr/pkgsrc
                   1283: # sh mk/bulk/do-sandbox-build
                   1284:
                   1285: This will just jump inside the sandbox and start building. At the end of the
                   1286: build, mail will be sent with the results of the build. Created binary pkgs
                   1287: will be in /usr/sandbox/usr/pkgsrc/packages (wherever that points/mounts to/
                   1288: from).
                   1289:
                   1290: 5.3.7. Building a partial set of packages
                   1291:
                   1292: In addition to building a complete set of all packages in pkgsrc, the pkgsrc/mk
                   1293: /bulk/build script may be used to build a subset of the packages contained in
                   1294: pkgsrc. By setting defining SPECIFIC_PKGS in /etc/mk.conf, the variables
                   1295:
                   1296:   * SITE_SPECIFIC_PKGS
1.7       wiz      1297:
1.1       grant    1298:   * HOST_SPECIFIC_PKGS
1.7       wiz      1299:
1.1       grant    1300:   * GROUP_SPECIFIC_PKGS
1.7       wiz      1301:
1.1       grant    1302:   * USER_SPECIFIC_PKGS
1.7       wiz      1303:
1.1       grant    1304: will define the set of packages which should be built. The bulk build code will
                   1305: also include any packages which are needed as dependencies for the explicitly
                   1306: listed packages.
                   1307:
                   1308: One use of this is to do a bulk build with SPECIFIC_PKGS in a chroot sandbox
                   1309: periodically to have a complete set of the binary packages needed for your site
                   1310: available without the overhead of building extra packages that are not needed.
                   1311:
                   1312: 5.4. Creating a multiple CD-ROM packages collection
                   1313:
                   1314: After your pkgsrc bulk-build has completed, you may wish to create a CD-ROM set
                   1315: of the resulting binary packages to assist in installing packages on other
                   1316: machines. The pkgtools/cdpack package provides a simple tool for creating the
                   1317: ISO 9660 images. cdpack arranges the packages on the CD-ROMs in a way that
                   1318: keeps all the dependencies for given package on the same CD as that package.
                   1319:
                   1320: 5.4.1. Example of cdpack
                   1321:
                   1322: Complete documentation for cdpack is found in the cdpack(1) manpage. The
                   1323: following short example assumes that the binary packages are left in /usr/
                   1324: pkgsrc/packages/All and that sufficient disk space exists in /u2 to hold the
                   1325: ISO 9660 images.
                   1326:
                   1327: # mkdir /u2/images
                   1328: # pkg_add /usr/pkgsrc/packages/All/cdpack
                   1329: # cdpack /usr/pkgsrc/packages/All /u2/images
                   1330:
                   1331: If you wish to include a common set of files (COPYRIGHT, README, etc.) on each
                   1332: CD in the collection, then you need to create a directory which contains these
                   1333: files. e.g.
                   1334:
                   1335: # mkdir /tmp/common
                   1336: # echo "This is a README" > /tmp/common/README
                   1337: # echo "Another file" > /tmp/common/COPYING
                   1338: # mkdir /tmp/common/bin
                   1339: # echo "#!/bin/sh" > /tmp/common/bin/myscript
                   1340: # echo "echo Hello world" >> /tmp/common/bin/myscript
                   1341: # chmod 755 /tmp/common/bin/myscript
                   1342:
                   1343: Now create the images:
                   1344:
                   1345: # cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images
                   1346:
                   1347: Each image will contain README, COPYING, and bin/myscript in their root
                   1348: directories.
                   1349:
                   1350: Chapter 6. Frequently Asked Questions
                   1351:
                   1352: Table of Contents
                   1353:
                   1354: 6.1. Is there a mailing list for pkg-related discussion?
                   1355: 6.2. Where's the pkgviews documentation?
                   1356: 6.3. Utilities for package management (pkgtools)
                   1357: 6.4. How to use pkgsrc as non-root
                   1358: 6.5. How can I install/use XFree86 from pkgsrc?
                   1359: 6.6. How can I install/use X.org from pkgsrc?
                   1360: 6.7. How to fetch files from behind a firewall
                   1361: 6.8. How do I tell make fetch to do passive FTP?
                   1362: 6.9. How to fetch all distfiles at once
1.7       wiz      1363: 6.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
                   1364: 6.11. What does "Could not find bsd.own.mk" mean?
1.1       grant    1365: 6.12. Using 'sudo' with pkgsrc
                   1366: 6.13. Configuration files handling and placement
                   1367: 6.14. Automated security checks
                   1368:
                   1369: This section contains hints, tips & tricks on special things in pkgsrc that we
                   1370: didn't find a better place for in the previous chapters, and it contains items
                   1371: for both pkgsrc users and developers.
                   1372:
                   1373: 6.1. Is there a mailing list for pkg-related discussion?
                   1374:
                   1375: Yes, <tech-pkg@NetBSD.org> is the list for discussing package related issues.
                   1376: To subscribe do:
                   1377:
                   1378: % echo subscribe tech-pkg | mail majordomo@NetBSD.org
                   1379:
                   1380: An archive of the list is available at http://mail-index.NetBSD.org/tech-pkg/.
                   1381:
                   1382: 6.2. Where's the pkgviews documentation?
                   1383:
                   1384: Pkgviews is tightly integrated with buildlink. You can find a pkgviews User's
                   1385: guide in pkgsrc/mk/buildlink3/PKGVIEWS_UG.
                   1386:
                   1387: 6.3. Utilities for package management (pkgtools)
                   1388:
                   1389: The pkgsrc/pkgtools directory pkgtools contains a number of useful utilities
                   1390: for both users and developers of pkgsrc. This section attempts only to make the
                   1391: reader aware of the utilities and when they might be useful, and not to
                   1392: duplicate the documentation that comes with each package.
                   1393:
                   1394: Utilities used by pkgsrc (automatically installed when needed):
                   1395:
                   1396:   * pkgtools/x11-links: symlinks for use by buildlink
1.7       wiz      1397:
1.1       grant    1398: OS tool augmentation (automatically installed when needed):
                   1399:
                   1400:   * pkgtools/digest: calculates SHA1 checksums (and other kinds)
1.7       wiz      1401:
1.1       grant    1402:   * pkgtools/libnbcompat: compat library for pkg tools
1.7       wiz      1403:
1.1       grant    1404:   * pkgtools/mtree: installed on non-BSD systems due to lack of native mtree
1.7       wiz      1405:
1.1       grant    1406:   * pkgtools/pkg_install: up-to-date replacement for /usr/sbin/pkg_install, or
                   1407:     for use on operating systems where pkg_install is not present
1.7       wiz      1408:
1.1       grant    1409: Utilities used by pkgsrc (not automatically installed):
                   1410:
                   1411:   * pkgtools/pkg_tarup: create a binary package from an already-installed
                   1412:     package. used by 'make replace' to save the old package
1.7       wiz      1413:
1.5       hubertf  1414:   * pkgtools/dfdisk: adds extra functionality to pkgsrc, allowing it to fetch
                   1415:     distfiles from multiple locations. It currently supports the following
                   1416:     methods: multiple CD-ROMs and network FTP/HTTP connections.
1.7       wiz      1417:
1.1       grant    1418:   * pkgtools/xpkgwedge: put X11 packages someplace else (enabled by default)
1.7       wiz      1419:
1.5       hubertf  1420:   * devel/cpuflags: will determine the best compiler flags to optimise code for
                   1421:     your current CPU and compiler.
1.7       wiz      1422:
1.1       grant    1423: Utilities for keeping track of installed packages, being up to date, etc:
                   1424:
                   1425:   * pkgtools/pkg_chk: installs pkg_chk, which reports on packages whose
                   1426:     installed versions do not match the latest pkgsrc entries
1.7       wiz      1427:
1.1       grant    1428:   * pkgtools/pkgdep: makes dependency graphs of packages, to aid in choosing a
                   1429:     strategy for updating
1.7       wiz      1430:
1.1       grant    1431:   * pkgtools/pkgdepgraph: make graph from above (uses graphviz)
1.7       wiz      1432:
1.1       grant    1433:   * pkgtools/pkglint: This provides two distinct abilities: check a pkgsrc
                   1434:     entry for correctness (pkglint) check for and remove out-of-date distfiles
                   1435:     and binary packages (lintpkgsrc)
1.7       wiz      1436:
1.1       grant    1437:   * pkgtools/pkgsurvey: report what packages you have installed
1.7       wiz      1438:
1.1       grant    1439: Utilities for people maintaining or creating individual packages:
                   1440:
                   1441:   * pkgtools/pkgdiff: automate making and maintaining patches for a package
                   1442:     (includes pkgdiff, pkgvi, mkpatches, ...)
1.7       wiz      1443:
1.1       grant    1444:   * pkgtools/rpm2pkg, pkgtools/url2pkg: aids in converting to pkgsrc
1.7       wiz      1445:
1.1       grant    1446:   * pkgtools/gensolpkg: convert pkgsrc to a Solaris package
1.7       wiz      1447:
1.1       grant    1448: Utilities for people maintaining pkgsrc (or more obscure pkg utilities)
                   1449:
                   1450:   * pkgtools/pkgconflict: find packages that conflict but aren't marked as such
1.7       wiz      1451:
1.1       grant    1452:   * pkgtools/pkg_comp: build packages in a chrooted area
1.7       wiz      1453:
1.1       grant    1454:   * pkgtools/libkver: spoof kernel version for chrooted cross builds
1.7       wiz      1455:
1.1       grant    1456: 6.4. How to use pkgsrc as non-root
                   1457:
                   1458: If you want to use pkgsrc as non-root user, you can set some variables to make
                   1459: pkgsrc work under these conditions. Please see this message for more details.
                   1460:
                   1461: 6.5. How can I install/use XFree86 from pkgsrc?
                   1462:
                   1463: If you want to use XFree86 from pkgsrc instead of your system's own X11 (/usr/
                   1464: X11R6, /usr/openwin, ...), you will have to add the following lines into
                   1465: mk.conf:
                   1466:
                   1467:       X11_TYPE=XFree86
1.7       wiz      1468:
1.1       grant    1469:
                   1470: 6.6. How can I install/use X.org from pkgsrc?
                   1471:
                   1472: If you want to use X.org from pkgsrc instead of your system's own X11 (/usr/
                   1473: X11R6, /usr/openwin, ...) you will have to add the following lines into
                   1474: mk.conf:
                   1475:
                   1476:       X11_TYPE=xorg
1.7       wiz      1477:
1.1       grant    1478:
                   1479: 6.7. How to fetch files from behind a firewall
                   1480:
                   1481: If you are sitting behind a firewall which does not allow direct connections to
                   1482: Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts. This
                   1483: is done using an environment variable in the form of a URL e.g. in Amdahl, the
                   1484: machine "orpheus.amdahl.com" is one of the firewalls, and it uses port 80 as
                   1485: the proxy port number. So the proxy environment variables are:
                   1486:
                   1487:   ftp_proxy=ftp://orpheus.amdahl.com:80/
                   1488: http_proxy=http://orpheus.amdahl.com:80/
                   1489:
                   1490: 6.8. How do I tell make fetch to do passive FTP?
                   1491:
                   1492: This depends on which utility is used to retrieve distfiles. From bsd.pkg.mk,
                   1493: FETCH_CMD is assigned the first available command from the following list:
                   1494:
                   1495: ${LOCALBASE}/bin/ftp
                   1496: /usr/bin/ftp
                   1497:
                   1498: On a default NetBSD installation, this will be /usr/bin/ftp, which
                   1499: automatically tries passive connections first, and falls back to active
                   1500: connections if the server refuses to do passive. For the other tools, add the
                   1501: following to your /etc/mk.conf file: PASSIVE_FETCH=1.
                   1502:
                   1503: Having that option present will prevent /usr/bin/ftp from falling back to
                   1504: active transfers.
                   1505:
                   1506: 6.9. How to fetch all distfiles at once
                   1507:
                   1508: You would like to download all the distfiles in a single batch from work or
                   1509: university, where you can't run a make fetch. There is an archive of distfiles
                   1510: on ftp.NetBSD.org, but downloading the entire directory may not be appropriate.
                   1511:
                   1512: The answer here is to do a make fetch-list in /usr/pkgsrc or one of it's
                   1513: subdirectories, carry the resulting list to your machine at work/school and use
                   1514: it there If you don't have a NetBSD-compatible ftp(1) (like lukemftp) at work,
                   1515: don't forget to set FETCH_CMD to something that fetches a URL:
                   1516:
                   1517: At home:
                   1518:
                   1519: % cd /usr/pkgsrc
                   1520: % make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh
                   1521: % scp /tmp/fetch.sh work:/tmp
                   1522:
                   1523: At work:
                   1524:
                   1525: % sh /tmp/fetch.sh
                   1526:
                   1527: then tar up /tmp/distfiles and take it home.
                   1528:
                   1529: If you have a machine running NetBSD, and you want to get all distfiles (even
                   1530: ones that aren't for your machine architecture), you can do so by using the
                   1531: above-mentioned make fetch-list approach, or fetch the distfiles directly by
                   1532: running:
                   1533:
                   1534: % make mirror-distfiles
                   1535:
                   1536: If you even decide to ignore NO_{SRC,BIN}_ON_{FTP,CDROM}, then you can get
                   1537: everything by running:
                   1538:
                   1539: % make fetch NO_SKIP=yes
                   1540:
                   1541: 6.10. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
                   1542:
                   1543: When compiling the pkgtools/pkg_install package, you get the error from make
                   1544: that it doesn't know how to make /usr/share/tmac/tmac.andoc? This indicates
                   1545: that you don't have installed the "text" set on your machine (nroff, ...). It
                   1546: is recommended to do that to format manpages.
                   1547:
                   1548: In the case of the pkgtools/pkg_install package, you can get away with setting
                   1549: NOMAN=YES either in the environment or in /etc/mk.conf.
                   1550:
                   1551: 6.11. What does "Could not find bsd.own.mk" mean?
                   1552:
                   1553: You didn't install the compiler set, comp.tgz, when you installed your NetBSD
                   1554: machine. Please get it and install it, by extracting it in /:
                   1555:
                   1556: # cd /
                   1557: # tar --unlink -zxvpf .../comp.tgz
                   1558:
                   1559: comp.tgz is part of every NetBSD release. Get the one that corresponds to your
                   1560: release (determine via uname -r).
                   1561:
                   1562: 6.12. Using 'sudo' with pkgsrc
                   1563:
                   1564: When installing packages as non-root user and using the just-in-time su(1)
                   1565: feature of pkgsrc, it can become annoying to type in the root password for each
                   1566: required package installed. To avoid this, the sudo package can be used, which
                   1567: does password caching over a limited time. To use it, install sudo (either as
                   1568: binary package or from security/sudo) and then put the following into your /etc
                   1569: /mk.conf:
                   1570:
                   1571:         .if exists(/usr/pkg/bin/sudo)
                   1572:         SU_CMD=/usr/pkg/bin/sudo /bin/sh -c
                   1573:         .endif
1.7       wiz      1574:
1.1       grant    1575:
                   1576: 6.13. Configuration files handling and placement
                   1577:
                   1578: The global variable PKG_SYSCONFBASE (and some others) can be set by the system
                   1579: administrator in /etc/mk.conf to define the place where configuration files get
                   1580: installed. Therefore, packages must be adapted to support this feature. Keep in
                   1581: mind that you should only install files that are strictly necessary in the
                   1582: configuration directory, files that can go to $PREFIX/share should go there.
                   1583:
                   1584: We will take a look at available variables first (bsd.pkg.mk contains more
                   1585: information). PKG_SYSCONFDIR is where the configuration files for a package may
                   1586: be found (that is, the full path, e.g. /etc or /usr/pkg/etc). This value may be
                   1587: customized in various ways:
                   1588:
                   1589:  1. PKG_SYSCONFBASE is the main config directory under which all package
                   1590:     configuration files are to be found. Users will typically want to set it to
                   1591:     /etc, or accept the default location of $PREFIX/etc.
1.7       wiz      1592:
1.1       grant    1593:  2. PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which the
                   1594:     configuration files for a particular package may be found. Defaults to $
                   1595:     {SYSCONFBASE}.
1.7       wiz      1596:
1.1       grant    1597:  3. PKG_SYSCONFVAR is the special suffix used to distinguish any overriding
                   1598:     values for a particular package (see next item). It defaults to ${PKGBASE},
                   1599:     but for a collection of related packages that should all have the same
                   1600:     PKG_SYSCONFDIR value, it can be set in each of the package Makefiles to a
                   1601:     common value.
1.7       wiz      1602:
1.1       grant    1603:  4. PKG_SYSCONFDIR.${PKG_SYSCONFVAR} overrides the value of ${PKG_SYSCONFDIR}
                   1604:     for packages with the same value for PKG_SYSCONFVAR.
1.7       wiz      1605:
1.1       grant    1606:     As an example, all the various KDE packages may want to set PKG_SYSCONFVAR
                   1607:     to "kde" so admins can set PKG_SYSCONFDIR.kde in /etc/mk.conf to define
                   1608:     where to install KDE config files.
1.7       wiz      1609:
1.1       grant    1610: Programs' configuration directory should be defined during the configure stage.
                   1611: Packages that use GNU autoconf can usually do this by using the "--sysconfdir"
                   1612: parameter, but this brings some problems as we will see now. When you change
                   1613: this pathname in packages, you should not allow them to install files in that
                   1614: directory directly. Instead they need to install those files under share/
                   1615: examples/${PKGNAME} so PLIST can register them.
                   1616:
                   1617: Once you have the required configuration files in place (under the share/
                   1618: examples directory) the variable CONF_FILES should be set to copy them into
                   1619: PKG_SYSCONFDIR. The contents of this variable is formed by pairs of filenames;
                   1620: the first element of the pair specifies the file inside the examples directory
                   1621: (registered by PLIST) and the second element specifies the target file. This is
                   1622: done this way to allow binary packages to place files in the right directory
                   1623: using INSTALL/DEINSTALL scripts which are created automatically. The package
                   1624: Makefile must also set USE_PKGINSTALL=YES to use these automatically generated
                   1625: scripts. The automatic copying of config files can be toggled by setting the
                   1626: environment variable PKG_CONFIG prior to package installation.
                   1627:
                   1628: Here is an example, taken from mail/mutt/Makefile:
                   1629:
                   1630:   EGDIR=            ${PREFIX}/share/doc/mutt/samples
                   1631: CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
                   1632:
                   1633: As you can see, this package installs configuration files inside EGDIR, which
                   1634: are registered by PLIST. After that, the variable CONF_FILES lists the
                   1635: installed file first and then the target file. Users will also get an automatic
                   1636: message when files are installed using this method.
                   1637:
                   1638: 6.14. Automated security checks
                   1639:
                   1640: Please be aware that there can often be bugs in third-party software, and some
                   1641: of these bugs can leave a machine vulnerable to exploitation by attackers. In
                   1642: an effort to lessen the exposure, the NetBSD packages team maintains a database
                   1643: of known-exploits to packages which have at one time been included in pkgsrc.
                   1644: The database can be downloaded automatically, and a security audit of all
                   1645: packages installed on a system can take place. To do this, install the security
                   1646: /audit-packages package. It has two components:
                   1647:
                   1648:  1. "download-vulnerability-list", an easy way to download a list of the
                   1649:     security vulnerabilities information. This list is kept up to date by the
                   1650:     NetBSD security officer and the NetBSD packages team, and is distributed
                   1651:     from the NetBSD ftp server:
1.7       wiz      1652:
1.1       grant    1653:     ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities
1.7       wiz      1654:
1.1       grant    1655:  2. "audit-packages", an easy way to audit the current machine, checking each
                   1656:     vulnerability which is known. If a vulnerable package is installed, it will
                   1657:     be shown by output to stdout, including a description of the type of
                   1658:     vulnerability, and a URL containing more information.
1.7       wiz      1659:
1.1       grant    1660: Use of the audit-packages package is strongly recommended!
                   1661:
                   1662: The following message is displayed as part of the audit-packages installation
                   1663: procedure:
                   1664:
                   1665: ===========================================================================
1.9     ! dillo    1666: $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant    1667:
                   1668: You may wish to have the vulnerabilities file downloaded daily so that
                   1669: it remains current.  This may be done by adding an appropriate entry
                   1670: to the root users crontab(5) entry.  For example the entry
                   1671:
                   1672: # download vulnerabilities file
                   1673: 0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1
                   1674:
                   1675: will update the vulnerability list every day at 3AM. You may wish to do
                   1676: this more often than once a day.
                   1677:
                   1678: In addition, you may wish to run the package audit from the daily
                   1679: security script.  This may be accomplished by adding the following
                   1680: lines to /etc/security.local
                   1681:
                   1682: if [ -x ${PREFIX}/sbin/audit-packages ]; then
                   1683:           ${PREFIX}/sbin/audit-packages
                   1684: fi
                   1685:
                   1686: ===========================================================================
1.7       wiz      1687:
1.1       grant    1688:
1.2       hubertf  1689: The pkgsrc developer's guide
1.1       grant    1690:
                   1691: Table of Contents
                   1692:
                   1693: 7. Package components - files, directories and contents
1.7       wiz      1694:
1.1       grant    1695:     7.1. Makefile
                   1696:     7.2. distinfo
                   1697:     7.3. patches/*
                   1698:     7.4. Other mandatory files
                   1699:     7.5. Optional files
                   1700:     7.6. work*
                   1701:     7.7. files/*
1.7       wiz      1702:
1.1       grant    1703: 8. PLIST issues
1.7       wiz      1704:
1.1       grant    1705:     8.1. RCS ID
                   1706:     8.2. Semi-automatic PLIST generation
                   1707:     8.3. Tweaking output of make print-PLIST
                   1708:     8.4. Variable substitution in PLIST
                   1709:     8.5. Manpage-compression
                   1710:     8.6. Changing PLIST source with PLIST_SRC
                   1711:     8.7. Platform specific and differing PLISTs
                   1712:     8.8. Sharing directories between packages
1.7       wiz      1713:
1.1       grant    1714: 9. Buildlink methodology
1.7       wiz      1715:
1.1       grant    1716:     9.1. Converting packages to use buildlink3
                   1717:     9.2. Writing buildlink3.mk files
1.7       wiz      1718:
1.1       grant    1719:         9.2.1. Anatomy of a buildlink3.mk file
                   1720:         9.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
1.7       wiz      1721:
1.1       grant    1722:     9.3. Writing builtin.mk files
1.7       wiz      1723:
1.1       grant    1724:         9.3.1. Anatomy of a builtin.mk file
                   1725:         9.3.2. Global preferences for native or pkgsrc software
1.7       wiz      1726:
1.1       grant    1727: 10. Options handling
1.7       wiz      1728:
1.1       grant    1729:     10.1. Global default options
                   1730:     10.2. Converting packages to use bsd.options.mk
1.7       wiz      1731:
1.1       grant    1732: 11. The build process
1.7       wiz      1733:
1.1       grant    1734:     11.1. Program location
                   1735:     11.2. Main targets
                   1736:     11.3. Other helpful targets
1.7       wiz      1737:
1.1       grant    1738: 12. Notes on fixes for packages
1.7       wiz      1739:
1.1       grant    1740:     12.1. General operation
1.7       wiz      1741:
1.1       grant    1742:         12.1.1. How to pull in variables from /etc/mk.conf
                   1743:         12.1.2. Restricted packages
                   1744:         12.1.3. Handling dependencies
                   1745:         12.1.4. Handling conflicts with other packages
                   1746:         12.1.5. Packages that cannot or should not be built
                   1747:         12.1.6. Packages which should not be deleted, once installed
                   1748:         12.1.7. Handling packages with security problems
                   1749:         12.1.8. How to handle compiler bugs
                   1750:         12.1.9. How to handle incrementing versions when fixing an existing
                   1751:             package
                   1752:         12.1.10. Portability of packages
1.7       wiz      1753:
1.1       grant    1754:     12.2. Possible downloading issues
1.7       wiz      1755:
1.1       grant    1756:         12.2.1. Packages whose distfiles aren't available for plain downloading
                   1757:         12.2.2. How to handle modified distfiles with the 'old' name
1.7       wiz      1758:
1.1       grant    1759:     12.3. Configuration gotchas
1.7       wiz      1760:
1.1       grant    1761:         12.3.1. Shared libraries - libtool
                   1762:         12.3.2. Using libtool on GNU packages that already support libtool
                   1763:         12.3.3. GNU Autoconf/Automake
1.7       wiz      1764:
1.1       grant    1765:     12.4. Building considerations
1.7       wiz      1766:
1.1       grant    1767:         12.4.1. CPP defines
1.7       wiz      1768:
1.1       grant    1769:     12.5. Package specific actions
1.7       wiz      1770:
1.1       grant    1771:         12.5.1. Package configuration files
1.2       hubertf  1772:         12.5.2. User interaction
1.1       grant    1773:         12.5.3. Handling licenses
                   1774:         12.5.4. Creating an account from a package
                   1775:         12.5.5. Installing score files
                   1776:         12.5.6. Packages providing login shells
                   1777:         12.5.7. Packages containing perl scripts
                   1778:         12.5.8. Packages with hardcoded paths to other interpreters
                   1779:         12.5.9. Packages installing perl modules
                   1780:         12.5.10. Packages installing info files
                   1781:         12.5.11. Packages installing GConf2 data files
                   1782:         12.5.12. Packages installing scrollkeeper data files
                   1783:         12.5.13. Packages installing X11 fonts
                   1784:         12.5.14. Packages installing GTK2 modules
                   1785:         12.5.15. Packages installing SGML or XML data
                   1786:         12.5.16. Packages installing extensions to the MIME database
                   1787:         12.5.17. Packages using intltool
1.7       wiz      1788:
1.1       grant    1789:     12.6. Feedback to the author
1.7       wiz      1790:
1.1       grant    1791: 13. Debugging
                   1792: 14. Submitting and Committing
1.7       wiz      1793:
1.1       grant    1794:     14.1. Submitting your packages
                   1795:     14.2. Committing: Importing a package into CVS
1.2       hubertf  1796:     14.3. Updating a package to a newer version
                   1797:     14.4. Moving a package in pkgsrc
1.7       wiz      1798:
1.1       grant    1799: Chapter 7. Package components - files, directories and contents
                   1800:
                   1801: Table of Contents
                   1802:
                   1803: 7.1. Makefile
                   1804: 7.2. distinfo
                   1805: 7.3. patches/*
                   1806: 7.4. Other mandatory files
                   1807: 7.5. Optional files
                   1808: 7.6. work*
                   1809: 7.7. files/*
                   1810:
                   1811: Whenever you're preparing a package, there are a number of files involved which
                   1812: are described in the following sections.
                   1813:
                   1814: 7.1. Makefile
                   1815:
                   1816: Building, installation and creation of a binary package are all controlled by
                   1817: the package's Makefile.
                   1818:
                   1819: There is a Makefile for each package. This file includes the standard
                   1820: bsd.pkg.mk file (referenced as ../../mk/bsd.pkg.mk), which sets all the
                   1821: definitions and actions necessary for the package to compile and install
                   1822: itself. The mandatory variables are the DISTNAME which specifies the base name
                   1823: of the distribution file to be downloaded from the site on the Internet,
                   1824: MASTER_SITES which specifies that site, CATEGORIES which denotes the categories
                   1825: into which the package falls, PKGNAME which is the name of the package, the
                   1826: MAINTAINER's name, and the COMMENT variable, which should contain a one-line
                   1827: description of the package (the package name should not appear, it will be
                   1828: added automatically). The maintainer variable is there so that anyone who
                   1829: quibbles with the (always completely correct) decisions taken by the guy who
                   1830: maintains the package can complain vigorously, or send chocolate as a sign of
                   1831: appreciation.
                   1832:
                   1833: The MASTER_SITES may be set to one of the predefined sites:
                   1834:
                   1835:         ${MASTER_SITE_APACHE}
                   1836:         ${MASTER_SITE_DEBIAN}
                   1837:         ${MASTER_SITE_GNOME}
                   1838:         ${MASTER_SITE_GNU}
                   1839:         ${MASTER_SITE_GNUSTEP}
1.9     ! dillo    1840:         ${MASTER_SITE_IFARCHIVE}
1.1       grant    1841:         ${MASTER_SITE_MOZILLA}
                   1842:         ${MASTER_SITE_PERL_CPAN}
                   1843:         ${MASTER_SITE_SOURCEFORGE}
                   1844:         ${MASTER_SITE_SUNSITE}
                   1845:         ${MASTER_SITE_R_CRAN}
                   1846:         ${MASTER_SITE_SUSE}
                   1847:         ${MASTER_SITE_TEX_CTAN}
                   1848:         ${MASTER_SITE_XCONTRIB}
1.7       wiz      1849:         ${MASTER_SITE_XEMACS}
1.1       grant    1850:
                   1851: If one of these predefined sites is chosen, you may require the ability to
                   1852: specify a subdirectory of that site. Since these macros may expand to more than
                   1853: one actual site, you must use the following construct to specify a
                   1854: subdirectory:
                   1855:
                   1856:         ${MASTER_SITE_GNU:=subdirectory/name/}
1.7       wiz      1857:         ${MASTER_SITE_SOURCEFORGE:=project_name/}
1.1       grant    1858:
                   1859: Note the trailing slash after the subdirectory name.
                   1860:
                   1861: Note
                   1862:
                   1863: MASTER_SITE_SUBDIR has been deprecated and should no longer be used.
                   1864:
                   1865: If the package has multiple DISTFILES or multiple PATCHFILES from different
                   1866: sites, set SITES_foo to a list of URI's where file "foo" may be found. "foo"
                   1867: includes the suffix, e.g.
                   1868:
                   1869: DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
                   1870: DISTFILES+=     foo-file.tar.gz
                   1871: SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
                   1872:         http://www.somewhereelse.com/mirror/somehow/
                   1873:
                   1874: Note that the normal default setting of DISTFILES must be made explicit if you
                   1875: want to add to it (rather than replace it), as you usually would.
                   1876:
                   1877: Currently the following values are available for CATEGORIES. If more than one
                   1878: is used, they need to be separated by spaces:
                   1879:
                   1880: archivers     cross         geography     meta-pkgs     security
                   1881: audio         databases     graphics      misc          shells
                   1882: benchmarks    devel         ham           multimedia    sysutils
                   1883: biology       editors       inputmethod   net           textproc
                   1884: cad           emulators     lang          news          time
                   1885: chat          finance       mail          parallel      wm
                   1886: comms         fonts         math          pkgtools      www
                   1887: converters    games         mbone         print         x11
                   1888:
                   1889: Please pay attention to the following gotchas:
                   1890:
                   1891:   * Add MANCOMPRESSED if manpages are installed in compressed form by the
                   1892:     package; see comment in bsd.pkg.mk.
1.7       wiz      1893:
1.1       grant    1894:   * Replace /usr/local with "${PREFIX}" in all files (see patches, below).
1.7       wiz      1895:
1.1       grant    1896:   * If the package installs any info files, see Section 12.5.10, "Packages
                   1897:     installing info files".
1.7       wiz      1898:
1.1       grant    1899:   * Set MAINTAINER to be yourself. If you really can't maintain the package for
                   1900:     future updates, set it to <tech-pkg@NetBSD.org>.
1.7       wiz      1901:
1.1       grant    1902:   * If a home page for the software in question exists, add the variable
                   1903:     HOMEPAGE right after MAINTAINER. The value of this variable should be the
                   1904:     URL for the home page.
1.7       wiz      1905:
1.1       grant    1906:   * Be sure to set the COMMENT variable to a short description of the package,
                   1907:     not containing the pkg's name.
1.7       wiz      1908:
1.1       grant    1909: 7.2. distinfo
                   1910:
                   1911: Most important, the mandatory message digest, or checksum, of all the distfiles
                   1912: needed for the package to compile, confirming they match the original file
                   1913: distributed by the author. This ensures that the distfile retrieved from the
                   1914: Internet has not been corrupted during transfer or altered by a malign force to
                   1915: introduce a security hole. It is generated using the make makesum command. The
                   1916: digest algorithm used was, at one stage, md5, but that was felt lacking
                   1917: compared to sha1, and so sha1 is now the default algorithm. The distfile size
                   1918: is also generated and stored in new distinfo files. The pkgtools/digest utility
                   1919: calculates all of the digests in the distinfo file, and it provides various
1.7       wiz      1920: different algorithms. At the current time, the algorithms provided are: md5,
1.1       grant    1921: rmd160, sha1, sha256, sha384 and sha512.
                   1922:
                   1923: Some packages have different sets of distfiles on a per architecture basis, for
                   1924: example www/navigator). These are kept in the same distinfo file and care
                   1925: should be taken when upgrading such a package to ensure distfile information is
                   1926: not lost.
                   1927:
                   1928: The message digest/checksum for all the official patches found in the patches/
                   1929: directory (see Section 7.3, "patches/*") for the package is also stored in the
                   1930: distinfo file. This is a message digest/checksum of all lines in the patch file
                   1931: except the NetBSD RCS Id. This file is generated by invoking make makepatchsum
                   1932: (or make mps if you're in a hurry).
                   1933:
                   1934: 7.3. patches/*
                   1935:
                   1936: This directory contains files that are used by the patch(1) command to modify
                   1937: the sources as distributed in the distribution file into a form that will
                   1938: compile and run perfectly on NetBSD. The files are applied successively in
                   1939: alphabetic order (as returned by a shell "patches/patch-*" glob expansion), so
                   1940: patch-aa is applied before patch-ab, etc.
                   1941:
                   1942: The patch-* files should be in diff -bu format, and apply without a fuzz to
                   1943: avoid problems. (To force patches to apply with fuzz you can set
                   1944: PATCH_FUZZ_FACTOR=-F2). Furthermore, do not put changes for more than one file
                   1945: into a single patch-file, as this will make future modifications more
                   1946: difficult.
                   1947:
                   1948: Similar, a file should be patched at most once, not several times by several
                   1949: different patches. If a file needs several patches, they should be combined
                   1950: into one file.
                   1951:
                   1952: One important thing to mention is to pay attention that no RCS IDs get stored
                   1953: in the patch files, as these will cause problems when later checked into the
                   1954: NetBSD CVS tree. Use the pkgdiff from the pkgtools/pkgdiff package to avoid
                   1955: these problems.
                   1956:
                   1957: For even more automation, we recommend using mkpatches from the same package to
                   1958: make a whole set of patches. You just have to backup files before you edit them
1.7       wiz      1959: to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using
1.1       grant    1960: pkgvi again from the same package. If you upgrade a package this way, you can
1.7       wiz      1961: easily compare the new set of patches with the previously existing one with
1.1       grant    1962: patchdiff.
                   1963:
                   1964: When you have finished a package, remember to generate the checksums for the
                   1965: patch files by using the make makepatchsum command, see Section 7.2, "distinfo"
                   1966: .
                   1967:
                   1968: Patch files that are distributed by the author or other maintainers can be
                   1969: listed in $PATCHFILES.
                   1970:
                   1971: If it is desired to store any patches that should not be committed into pkgsrc,
                   1972: they can be kept outside the pkgsrc tree in the $LOCALPATCHES directory. The
                   1973: directory tree there is expected to have the same "category/package" structure
                   1974: as pkgsrc, and patches are expected to be stored inside these dirs (also known
                   1975: as $LOCALPATCHES/$PKGPATH). For example if you want to keep a private patch for
                   1976: pkgsrc/graphics/png, keep it in $LOCALPATCHES/graphics/png/mypatch. All files
                   1977: in the named directory are expected to be patch files, and they are applied
                   1978: after pkgsrc patches are applied.
                   1979:
                   1980: 7.4. Other mandatory files
                   1981:
                   1982: DESCR
1.7       wiz      1983:
1.1       grant    1984:     A multi-line description of the piece of software. This should include any
                   1985:     credits where they are due. Please bear in mind that others do not share
                   1986:     your sense of humour (or spelling idiosyncrasies), and that others will
                   1987:     read everything that you write here.
1.7       wiz      1988:
1.1       grant    1989: PLIST
1.7       wiz      1990:
1.1       grant    1991:     This file governs the files that are installed on your system: all the
                   1992:     binaries, manual pages, etc. There are other directives which may be
                   1993:     entered in this file, to control the creation and deletion of directories,
                   1994:     and the location of inserted files. See Chapter 8, PLIST issues for more
                   1995:     information.
1.7       wiz      1996:
1.1       grant    1997: 7.5. Optional files
                   1998:
                   1999: INSTALL
1.7       wiz      2000:
1.1       grant    2001:     This shell script is invoked twice by pkg_add(1). First time after package
                   2002:     extraction and before files are moved in place, the second time after the
                   2003:     files to install are moved in place. This can be used to do any custom
1.7       wiz      2004:     procedures not possible with @exec commands in PLIST. See pkg_add(1) and
1.1       grant    2005:     pkg_create(1) for more information.
1.7       wiz      2006:
1.1       grant    2007: DEINSTALL
1.7       wiz      2008:
1.1       grant    2009:     This script is executed before and after any files are removed. It is this
                   2010:     script's responsibility to clean up any additional messy details around the
                   2011:     package's installation, since all pkg_delete knows is how to delete the
1.7       wiz      2012:     files created in the original distribution. See pkg_delete(1) and
1.1       grant    2013:     pkg_create(1) for more information.
1.7       wiz      2014:
1.1       grant    2015: MESSAGE
1.7       wiz      2016:
1.1       grant    2017:     Display this file after installation of the package. Useful for things like
                   2018:     legal notices on almost-free software and hints for updating config files
                   2019:     after installing modules for apache, PHP etc. Please note that you can
                   2020:     modify variables in it easily by using MESSAGE_SUBST in the package's
                   2021:     Makefile:
1.7       wiz      2022:
1.1       grant    2023:     MESSAGE_SUBST+=  SOMEVAR="somevalue"
1.7       wiz      2024:
1.1       grant    2025:     replaces "${SOMEVAR}" with "somevalue" in MESSAGE.
1.7       wiz      2026:
1.1       grant    2027: 7.6. work*
                   2028:
                   2029: When you type make the distribution files are unpacked into this directory. It
                   2030: can be removed by running make clean. Besides the sources, this directory is
                   2031: also used to keep various timestamp files.
                   2032:
                   2033: If a package doesn't create a subdirectory for itself (like GNU software does,
                   2034: for instance), but extracts itself in the current directory, you should set
                   2035: WRKSRC accordingly, e.g. editors/sam again, but the quick answer is:
                   2036:
                   2037: WRKSRC=                ${WRKDIR}
                   2038:
                   2039: Please note that the old NO_WRKSUBDIR has been deprecated and should not be
                   2040: used. Also, if your package doesn't create a subdir with the name of DISTNAME
                   2041: but some different name, set WRKSRC to point to the proper name in ${WRKDIR}.
                   2042: See lang/tcl and x11/tk for examples, and here is another one:
                   2043:
                   2044: WRKSRC=         ${WRKDIR}/${DISTNAME}/unix
                   2045:
                   2046: The name of the working directory created by pkgsrc is work by default. If the
                   2047: same pkgsrc tree should be used on several different platforms, the variable
                   2048: OBJMACHINE can be set in /etc/mk.conf to attach the platform to the directory
                   2049: name, e.g. work.i386 or work.sparc.
                   2050:
                   2051: 7.7. files/*
                   2052:
                   2053: If you have any files that you wish to be placed in the package prior to
                   2054: configuration or building, you could place these files here and use a "${CP}"
                   2055: command in the "pre-configure" target to achieve this. Alternatively, you could
                   2056: simply diff the file against /dev/null and use the patch mechanism to manage
                   2057: the creation of this file.
                   2058:
                   2059: Chapter 8. PLIST issues
                   2060:
                   2061: Table of Contents
                   2062:
                   2063: 8.1. RCS ID
                   2064: 8.2. Semi-automatic PLIST generation
                   2065: 8.3. Tweaking output of make print-PLIST
                   2066: 8.4. Variable substitution in PLIST
                   2067: 8.5. Manpage-compression
                   2068: 8.6. Changing PLIST source with PLIST_SRC
                   2069: 8.7. Platform specific and differing PLISTs
                   2070: 8.8. Sharing directories between packages
                   2071:
                   2072: The PLIST file contains a package's "packing list", i.e. a list of files that
                   2073: belong to the package (relative to the ${PREFIX} directory it's been installed
                   2074: in) plus some additional statements - see the pkg_create(1) manpage for a full
                   2075: list. This chapter addresses some issues that need attention when dealing with
                   2076: the PLIST file (or files, see below!).
                   2077:
                   2078: 8.1. RCS ID
                   2079:
                   2080: Be sure to add a RCS ID line as the first thing in any PLIST file you write:
                   2081:
1.9     ! dillo    2082: @comment $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant    2083:
                   2084: 8.2. Semi-automatic PLIST generation
                   2085:
                   2086: You can use the make print-PLIST command to output a PLIST that matches any new
                   2087: files since the package was extracted. See Section 11.3, "Other helpful
                   2088: targets" for more information on this target.
                   2089:
                   2090: 8.3. Tweaking output of make print-PLIST
                   2091:
                   2092: If you have used any of the *-dirs packages, as explained in Section 8.8,
                   2093: "Sharing directories between packages", you may have noticed that make
                   2094: print-PLIST outputs a set of @comments instead of real @dirrm lines. You can
                   2095: also do this for specific directories and files, so that the results of that
                   2096: command are very close to reality. This helps a lot during the update of
                   2097: packages.
                   2098:
                   2099: The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that are
                   2100: used to filter the output of print-PLIST. You can append any chunk of AWK
                   2101: scripting you like to it, but be careful with quoting.
                   2102:
                   2103: For example, to get all files inside the libdata/foo directory removed from the
                   2104: resulting PLIST:
                   2105:
                   2106:       PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
1.7       wiz      2107:
1.1       grant    2108:
                   2109: And to get all the @dirrm lines referring to a specific (shared) directory
                   2110: converted to @comments:
                   2111:
                   2112:       PRINT_PLIST_AWK+= /^@dirrm share\/specific/ { print "@comment " $$0; next; }
1.7       wiz      2113:
1.1       grant    2114:
                   2115: 8.4. Variable substitution in PLIST
                   2116:
                   2117: A number of variables are substituted automatically in PLISTs when a package is
                   2118: installed on a system. This includes the following variables:
                   2119:
                   2120: ${MACHINE_ARCH}, ${MACHINE_GNU_ARCH}
1.7       wiz      2121:
1.1       grant    2122:     Some packages like emacs and perl embed information about which
                   2123:     architecture they were built on into the pathnames where they install their
                   2124:     file. To handle this case, PLIST will be preprocessed before actually used,
                   2125:     and the symbol "${MACHINE_ARCH}" will be replaced by what uname -p gives.
                   2126:     The same is done if the string ${MACHINE_GNU_ARCH} is embedded in PLIST
                   2127:     somewhere - use this on packages that have GNU autoconf created configure
                   2128:     scripts.
1.7       wiz      2129:
1.1       grant    2130:     Legacy note
1.7       wiz      2131:
1.1       grant    2132:     There used to be a symbol "$ARCH" that was replaced by the output of uname
                   2133:     -m, but that's no longer supported and has been removed.
1.7       wiz      2134:
1.1       grant    2135: ${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION}
1.7       wiz      2136:
1.1       grant    2137:     Some packages want to embed the OS name and version into some paths. To do
                   2138:     this, use these variables in the PLIST:
1.7       wiz      2139:
1.1       grant    2140:       * ${OPSYS} - output of "uname -s"
1.7       wiz      2141:
1.1       grant    2142:       * ${LOWER_OPSYS} - lowercase common name (eg. "solaris")
1.7       wiz      2143:
1.1       grant    2144:       * ${OS_VERSION} - "uname -r"
1.7       wiz      2145:
1.1       grant    2146: ${PKGLOCALEDIR}
1.7       wiz      2147:
1.1       grant    2148:     Packages that install locale files should list them in the PLIST as "$
                   2149:     {PKGLOCALEDIR}/locale/de/LC_MESSAGES/..." instead of "share/locale/de/
                   2150:     LC_MESSAGES/...". This properly handles the fact that different operating
                   2151:     systems expect locale files to be either in share or lib by default.
1.7       wiz      2152:
1.1       grant    2153: For a complete list of values which are replaced by default, please look in
                   2154: bsd.pkg.mk (and search for PLIST_SUBST).
                   2155:
                   2156: If you want to change other variables not listed above, you can add variables
                   2157: and their expansions to this variable in the following way, similar to
                   2158: MESSAGE_SUBST (see Section 7.5, "Optional files"):
                   2159:
                   2160: PLIST_SUBST+=    SOMEVAR="somevalue"
                   2161:
                   2162: This replaces all occurrences of "${SOMEVAR}" in the PLIST with "somevalue".
                   2163:
                   2164: 8.5. Manpage-compression
                   2165:
                   2166: Manpages should be installed in compressed form if MANZ is set (in bsd.own.mk),
                   2167: and uncompressed otherwise. To handle this in the PLIST file, the suffix ".gz"
                   2168: is appended/removed automatically for manpages according to MANZ and
                   2169: MANCOMPRESSED being set or not, see above for details. This modification of the
                   2170: PLIST file is done on a copy of it, not PLIST itself.
                   2171:
                   2172: 8.6. Changing PLIST source with PLIST_SRC
                   2173:
                   2174: To use one or more files as source for the PLIST used in generating the binary
                   2175: package, set the variable PLIST_SRC to the names of that file(s). The files are
                   2176: later concatenated using cat(1), and order of things is important.
                   2177:
                   2178: 8.7. Platform specific and differing PLISTs
                   2179:
                   2180: Some packages decide to install a different set of files based on the operating
                   2181: system being used. These differences can be automatically handled by using the
                   2182: following files:
                   2183:
                   2184:   * PLIST.common
1.7       wiz      2185:
1.1       grant    2186:   * PLIST.${OPSYS}
1.7       wiz      2187:
1.1       grant    2188:   * PLIST.common_end
1.7       wiz      2189:
1.1       grant    2190: If PLIST.${OPSYS} exists, these files are used instead of PLIST. This allows
                   2191: packages which behave in this way to be handled gracefully. Manually overriding
                   2192: PLIST_SRC for other more exotic uses is also possible.
                   2193:
                   2194: 8.8. Sharing directories between packages
                   2195:
                   2196: A "shared directory" is a directory where multiple (and unrelated) packages
                   2197: install files. These directories are problematic because you have to add
                   2198: special tricks in the PLIST to conditionally remove them, or have some
                   2199: centralized package handle them.
                   2200:
                   2201: Within pkgsrc, you'll find both approaches. If a directory is shared by a few
                   2202: unrelated packages, it's often not worth to add an extra package to remove it.
                   2203: Therefore, one simply does:
                   2204:
                   2205:       @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE}
1.7       wiz      2206:
1.1       grant    2207:
                   2208: in the PLISTs of all affected packages, instead of the regular "@dirrm" line.
                   2209:
                   2210: However, if the directory is shared across many packages, two different
                   2211: solutions are available:
                   2212:
                   2213:  1. If the packages have a common dependency, the directory can be removed in
                   2214:     that. For example, see textproc/scrollkeeper, which removes the shared
                   2215:     directory share/omf.
1.7       wiz      2216:
1.1       grant    2217:  2. If the packages using the directory are not related at all (they have no
                   2218:     common dependencies), a *-dirs package is used.
1.7       wiz      2219:
1.1       grant    2220: From now on, we'll discuss the second solution. To get an idea of the *-dirs
                   2221: packages available, issue:
                   2222:
                   2223:       % cd .../pkgsrc
                   2224:       % ls -d */*-dirs
1.7       wiz      2225:
1.1       grant    2226:
                   2227: Their use from other packages is very simple. The USE_DIRS variable takes a
                   2228: list of package names (without the "-dirs" part) together with the required
                   2229: version number (always pick the latest one when writting new packages).
                   2230:
                   2231: For example, if a package installs files under share/applications, it should
                   2232: have the following line in it:
                   2233:
                   2234:       USE_DIRS+= xdg-1.1
1.7       wiz      2235:
1.1       grant    2236:
                   2237: After regenerating the PLIST using make print-PLIST, you should get the right
                   2238: (commented out) lines.
                   2239:
                   2240: Note that, even if your package is using $X11BASE, it must not depend on the
                   2241: *-x11-dirs packages. Just specify the name without that part and pkgsrc (in
                   2242: particular, mk/dirs.mk) will take care of it.
                   2243:
                   2244: Chapter 9. Buildlink methodology
                   2245:
                   2246: Table of Contents
                   2247:
                   2248: 9.1. Converting packages to use buildlink3
                   2249: 9.2. Writing buildlink3.mk files
1.7       wiz      2250:
1.1       grant    2251:     9.2.1. Anatomy of a buildlink3.mk file
                   2252:     9.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
1.7       wiz      2253:
1.1       grant    2254: 9.3. Writing builtin.mk files
1.7       wiz      2255:
1.1       grant    2256:     9.3.1. Anatomy of a builtin.mk file
                   2257:     9.3.2. Global preferences for native or pkgsrc software
1.7       wiz      2258:
1.1       grant    2259: Buildlink is a framework in pkgsrc that controls what headers and libraries are
                   2260: seen by a package's configure and build processes. This is implemented in a two
                   2261: step process:
                   2262:
                   2263:  1. Symlink headers and libraries for dependencies into BUILDLINK_DIR, which by
                   2264:     default is a subdirectory of WRKDIR.
1.7       wiz      2265:
1.1       grant    2266:  2. Create wrapper scripts that are used in place of the normal compiler tools
                   2267:     that translate -I${LOCALBASE}/include and -L${LOCALBASE}/lib into
                   2268:     references to BUILDLINK_DIR. The wrapper scripts also make native compiler
                   2269:     on some operating systems look like GCC, so that packages that expect GCC
                   2270:     won't require modifications to build with those native compilers.
1.7       wiz      2271:
1.1       grant    2272: This normalizes the environment in which a package is built so that the package
                   2273: may be built consistently despite what other software may be installed. Please
                   2274: note that the normal system header and library paths, e.g. /usr/include, /usr/
                   2275: lib, etc., are always searched -- buildlink3 is designed to insulate the
                   2276: package build from non-system-supplied software.
                   2277:
                   2278: 9.1. Converting packages to use buildlink3
                   2279:
                   2280: The process of converting packages to use the buildlink3 framework
                   2281: ("bl3ifying") is fairly straightforward. The things to keep in mind are:
                   2282:
                   2283:  1. Set USE_BUILDLINK3 to "yes".
1.7       wiz      2284:
1.1       grant    2285:  2. Ensure that the build always calls the wrapper scripts instead of the
                   2286:     actual toolchain. Some packages are tricky, and the only way to know for
                   2287:     sure is the check ${WRKDIR}/.work.log to see if the wrappers are being
                   2288:     invoked.
1.7       wiz      2289:
1.1       grant    2290:  3. Don't override PREFIX from within the package Makefile, e.g. Java VMs,
                   2291:     standalone shells, etc., because the code to symlink files into $
                   2292:     {BUILDLINK_DIR} looks for files relative to "pkg_info -qp pkgname".
1.7       wiz      2293:
1.1       grant    2294:  4. Remember that only the buildlink3.mk files that you list in a package's
                   2295:     Makefile are added as dependencies for that package.
1.7       wiz      2296:
1.1       grant    2297: If a dependency on a particular package is required for its libraries and
                   2298: headers, then we replace:
                   2299:
                   2300: DEPENDS+=       foo>=1.1.0:../../category/foo
                   2301:
                   2302: with
                   2303:
                   2304: .include "../../category/foo/buildlink3.mk"
                   2305:
                   2306: There are several buildlink3.mk files in pkgsrc/mk that handle special package
                   2307: issues:
                   2308:
                   2309:   * bdb.buildlink3.mk chooses either the native or a pkgsrc Berkeley DB
                   2310:     implementation based on the values of BDB_ACCEPTED and BDB_DEFAULT.
1.7       wiz      2311:
1.1       grant    2312:   * curses.buildlink3.mk If the system comes with neither Curses nor NCurses,
                   2313:     this will take care to install the devel/ncurses package.
1.7       wiz      2314:
1.1       grant    2315:   * krb5.buildlink3.mk uses the value of KRB5_ACCEPTED to choose between adding
                   2316:     a dependency on Heimdal or MIT-krb5 for packages that require a Kerberos 5
                   2317:     implementation.
1.7       wiz      2318:
1.1       grant    2319:   * motif.buildlink3.mk checks for a system-provided Motif installation or adds
                   2320:     a dependency on x11/lesstif or x11/openmotif;
1.7       wiz      2321:
1.1       grant    2322:   * ossaudio.buildlink3.mk defines several variables that may be used by
                   2323:     packages that use the Open Sound System (OSS) API;
1.7       wiz      2324:
1.1       grant    2325:   * pgsql.buildlink3.mk will accept either Postgres 7.3 or 7.4, whichever is
                   2326:     found installed. See the file for more information.
1.7       wiz      2327:
1.1       grant    2328:   * pthread.buildlink3.mk uses the value of PTHREAD_OPTS and checks for native
                   2329:     pthreads or adds a dependency on devel/pth as needed;
1.7       wiz      2330:
1.1       grant    2331:   * xaw.buildlink3.mk uses the value of XAW_TYPE to choose a particular Athena
                   2332:     widgets library.
1.7       wiz      2333:
1.1       grant    2334: The comments in those buildlink3.mk files provide a more complete description
                   2335: of how to use them properly.
                   2336:
                   2337: 9.2. Writing buildlink3.mk files
                   2338:
                   2339: A package's buildlink3.mk file is included by Makefiles to indicate the need to
                   2340: compile and link against header files and libraries provided by the package. A
                   2341: buildlink3.mk file should always provide enough information to add the correct
                   2342: type of dependency relationship and include any other buildlink3.mk files that
                   2343: it needs to find headers and libraries that it needs in turn.
                   2344:
1.7       wiz      2345: To generate an initial buildlink3.mk file for further editing, Rene Hexel's
1.1       grant    2346: pkgtools/createbuildlink package is highly recommended. For most packages, the
                   2347: following command will generate a good starting point for buildlink3.mk files:
                   2348:
                   2349: % cd pkgsrc/category/pkgdir
                   2350: % createbuildlink -3 >buildlink3.mk
                   2351:
                   2352: 9.2.1. Anatomy of a buildlink3.mk file
                   2353:
                   2354: The following real-life example buildlink3.mk is taken from pkgsrc/graphics/
                   2355: tiff:
                   2356:
1.9     ! dillo    2357: # $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant    2358:
                   2359: BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH}+
                   2360: TIFF_BUILDLINK3_MK:=    ${TIFF_BUILDLINK3_MK}+
                   2361:
                   2362: .if !empty(BUILDLINK_DEPTH:M+)
                   2363: BUILDLINK_DEPENDS+=     tiff
                   2364: .endif
                   2365:
                   2366: BUILDLINK_PACKAGES:=    ${BUILDLINK_PACKAGES:Ntiff}
                   2367: BUILDLINK_PACKAGES+=    tiff
                   2368:
                   2369: .if !empty(TIFF_BUILDLINK3_MK:M+)
                   2370: BUILDLINK_DEPENDS.tiff+=        tiff>=3.6.1
                   2371: BUILDLINK_PKGSRCDIR.tiff?=      ../../graphics/tiff
                   2372: .endif  # TIFF_BUILDLINK3_MK
                   2373:
                   2374: .include "../../devel/zlib/buildlink3.mk"
                   2375: .include "../../graphics/jpeg/buildlink3.mk"
                   2376:
1.7       wiz      2377: BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH:S/+$//}
1.1       grant    2378:
                   2379: The header and footer manipulate BUILDLINK_DEPTH, which is common across all
                   2380: buildlink3.mk files and is used to track at what depth we are including
                   2381: buildlink3.mk files.
                   2382:
                   2383: The first section controls if the dependency on pkg is added. BUILDLINK_DEPENDS
                   2384: is the global list of packages for which dependencies are added by buildlink3.
                   2385:
                   2386: The second section advises pkgsrc that the buildlink3.mk file for pkg has been
                   2387: included at some point. BUILDLINK_PACKAGES is the global list of packages for
                   2388: which buildlink3.mk files have been included. It must always be appended to
                   2389: within a buildlink3.mk file.
                   2390:
                   2391: The third section is protected from multiple inclusion and controls how the
                   2392: dependency on pkg is added. Several important variables are set in the section:
                   2393:
1.7       wiz      2394:   * BUILDLINK_DEPENDS.pkg is the actual dependency recorded in the installed
1.1       grant    2395:     package; this should always be set using += to ensure that we're appending
                   2396:     to any pre-existing list of values. This variable should be set to the
                   2397:     first version of the package that had the last change in the major number
                   2398:     of a shared library or that had a major API change.
1.7       wiz      2399:
1.1       grant    2400:   * BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory;
1.7       wiz      2401:
1.1       grant    2402:   * BUILDLINK_DEPMETHOD.pkg (not shown above) controls whether we use
                   2403:     BUILD_DEPENDS or DEPENDS to add the dependency on pkg. The build dependency
                   2404:     is selected by setting BUILDLINK_DEPMETHOD.pkg to "build". By default, the
                   2405:     full dependency is used.
1.7       wiz      2406:
                   2407:   * BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS. pkg (not shown above) are
1.1       grant    2408:     lists of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and
                   2409:     library search paths. These default to "include" and "lib" respectively.
1.7       wiz      2410:
1.1       grant    2411:   * BUILDLINK_CPPFLAGS.pkg (not shown above) is the list of preprocessor flags
                   2412:     to add to CPPFLAGS, which are passed on to the configure and build phases.
                   2413:     The "-I" option should be avoided and instead be handled using
                   2414:     BUILDLINK_INCDIRS.pkg as above.
1.7       wiz      2415:
1.1       grant    2416: The following variables are all optionally defined within this second section
                   2417: (protected against multiple inclusion) and control which package files are
                   2418: symlinked into ${BUILDLINK_DIR} and how their names are transformed during the
                   2419: symlinking:
                   2420:
                   2421:   * BUILDLINK_FILES.pkg (not shown above) is a shell glob pattern relative to $
                   2422:     {BUILDLINK_PREFIX.pkg} to be symlinked into ${BUILDLINK_DIR}, e.g. include/
                   2423:     *.h.
1.7       wiz      2424:
1.1       grant    2425:   * BUILDLINK_FILES_CMD.pkg (not shown above) is a shell pipeline that outputs
                   2426:     to stdout a list of files relative to ${BUILDLINK_PREFIX.pkg}. The
                   2427:     resulting files are to be symlinked into ${BUILDLINK_DIR}. By default, this
                   2428:     takes the +CONTENTS of a pkg and filters it through $
                   2429:     {BUILDLINK_CONTENTS_FILTER.pkg}.
1.7       wiz      2430:
1.1       grant    2431:   * BUILDLINK_CONTENTS_FILTER.pkg (not shown above) is a filter command that
                   2432:     filters +CONTENTS input into a list of files relative to $
                   2433:     {BUILDLINK_PREFIX.pkg} on stdout. By default for overwrite packages,
                   2434:     BUILDLINK_CONTENTS_FILTER.pkg outputs the contents of the include and lib
                   2435:     directories in the package +CONTENTS, and for pkgviews packages, it outputs
                   2436:     any libtool archives in lib directories.
1.7       wiz      2437:
1.1       grant    2438:   * BUILDLINK_TRANSFORM.pkg (not shown above) is a list of sed arguments used
                   2439:     to transform the name of the source filename into a destination filename,
                   2440:     e.g. -e "s|/curses.h|/ncurses.h|g".
1.7       wiz      2441:
1.1       grant    2442: The last section includes any buildlink3.mk needed for pkg's library
                   2443: dependencies. Including these buildlink3.mk files means that the headers and
                   2444: libraries for these dependencies are also symlinked into ${BUILDLINK_DIR}
                   2445: whenever the pkg buildlink3.mk file is included.
                   2446:
                   2447: 9.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
                   2448:
                   2449: There are two situations that require increasing the dependency listed in
                   2450: BUILDLINK_DEPENDS.pkg after a package update:
                   2451:
                   2452:  1. if the sonames (major number of the library version) of any installed
                   2453:     shared libraries change;
1.7       wiz      2454:
1.1       grant    2455:  2. if the API or interface to the header files change.
1.7       wiz      2456:
1.1       grant    2457: In these cases, BUILDLINK_DEPENDS.pkg should be adjusted to require at least
                   2458: the new package version. In some cases, the packages that depend on this new
                   2459: version may need their PKGREVISIONs increased and, if they have buildlink3.mk
1.7       wiz      2460: files, their BUILDLINK_DEPENDS. pkg adjusted, too. This is needed so that
                   2461: binary packages made using it will require the correct package dependency and
                   2462: not settle for an older one which will not contain the necessary shared
                   2463: libraries.
1.1       grant    2464:
                   2465: Please take careful consideration before adjusting BUILDLINK_DEPENDS.pkg as we
                   2466: don't want to cause unneeded package deletions and rebuilds. In many cases, new
                   2467: versions of packages work just fine with older dependencies. See Section
                   2468: 12.1.3, "Handling dependencies" and Chapter 9, Buildlink methodology for more
                   2469: information about dependencies on other packages, including the
                   2470: BUILDLINK_RECOMMENDED and RECOMMENDED definitions.
                   2471:
                   2472: 9.3. Writing builtin.mk files
                   2473:
                   2474: Some packages in pkgsrc install headers and libraries that coincide with
                   2475: headers and libraries present in the base system. Aside from a buildlink3.mk
                   2476: file, these packages should also include a builtin.mk file that includes the
                   2477: necessary checks to decide whether using the built-in software or the pkgsrc
                   2478: software is appropriate.
                   2479:
                   2480: The only requirements of a builtin.mk file for pkg are:
                   2481:
                   2482:  1. It should set USE_BUILTIN.pkg to either "yes" or "no" after it is included.
1.7       wiz      2483:
1.1       grant    2484:  2. It should not override any USE_BUILTIN.pkg which is already set before the
                   2485:     builtin.mk file is included.
1.7       wiz      2486:
1.1       grant    2487:  3. It should be written to allow multiple inclusion. This is very important
                   2488:     and takes careful attention to Makefile coding.
1.7       wiz      2489:
1.1       grant    2490: 9.3.1. Anatomy of a builtin.mk file
                   2491:
                   2492: The following is the recommended template for builtin.mk files:
                   2493:
                   2494: .if !defined(IS_BUILTIN.foo)
                   2495: #
                   2496: # IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
                   2497: # genuinely exists in the system or not.
                   2498: #
                   2499: IS_BUILTIN.foo?=        no
                   2500:
                   2501: # BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
                   2502: # version can be determined.
                   2503: #
                   2504: .  if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
                   2505: BUILTIN_PKG.foo?=       foo-1.0
                   2506: .  endif
                   2507: .endif  # IS_BUILTIN.foo
                   2508:
                   2509: .if !defined(USE_BUILTIN.foo)
                   2510: USE_BUILTIN.foo?=       ${IS_BUILTIN.foo}
                   2511: .  if defined(BUILTIN_PKG.foo)
                   2512: .    for _depend_ in ${BUILDLINK_DEPENDS.foo}
                   2513: .      if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
                   2514: USE_BUILTIN.foo!=                                                       \
                   2515:       if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then     \
                   2516:               ${ECHO} "yes";                                            \
                   2517:       else                                                              \
                   2518:               ${ECHO} "no";                                             \
                   2519:       fi
                   2520: .      endif
                   2521: .    endfor
                   2522: .  endif
                   2523: .endif  # USE_BUILTIN.foo
                   2524:
                   2525: CHECK_BUILTIN.foo?=     no
                   2526: .if !empty(CHECK_BUILTIN.foo:M[nN][oO])
                   2527: #
                   2528: # Here we place code that depends on whether USE_BUILTIN.foo is set to
                   2529: # "yes" or "no".
                   2530: #
                   2531: .endif  # CHECK_BUILTIN.foo
1.7       wiz      2532:
1.1       grant    2533:
                   2534: The first section sets IS_BUILTIN.pkg depending on if pkg really exists in the
                   2535: base system. This should not be a base system software with similar
                   2536: functionality to pkg; it should only be "yes" if the actual package is included
                   2537: as part of the base system. This variable is only used internally within the
                   2538: builtin.mk file.
                   2539:
                   2540: The second section sets BUILTIN_PKG.pkg to the version of pkg in the base
                   2541: system if it exists (if IS_BUILTIN.pkg is "yes"). This variable is only used
                   2542: internally within the builtin.mk file.
                   2543:
                   2544: The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files.
                   2545: The code in this section must make the determination whether the built-in
1.7       wiz      2546: software is adequate to satisfy the dependencies listed in BUILDLINK_DEPENDS.
                   2547: pkg. This is typically done by comparing BUILTIN_PKG.pkg against each of the
                   2548: dependencies in BUILDLINK_DEPENDS.pkg. USE_BUILTIN.pkg must be set to the
                   2549: correct value by the end of the builtin.mk file. Note that USE_BUILTIN.pkg may
                   2550: be "yes" even if IS_BUILTIN.pkg is "no" because we may make the determination
                   2551: that the built-in version of the software is similar enough to be used as a
                   2552: replacement.
1.1       grant    2553:
                   2554: The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses
                   2555: the value of USE_BUILTIN.pkg set in the previous section. This typically
                   2556: includes, e.g., adding additional dependency restrictions and listing
                   2557: additional files to symlink into ${BUILDLINK_DIR} (via BUILDLINK_FILES.pkg).
                   2558:
                   2559: 9.3.2. Global preferences for native or pkgsrc software
                   2560:
                   2561: When building packages, it's possible to choose whether to set a global
                   2562: preference for using either the built-in (native) version or the pkgsrc version
                   2563: of software to satisfy a dependency. This is controlled by setting
                   2564: PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either "yes",
                   2565: "no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc
                   2566: versions of software, while PREFER_NATIVE tells pkgsrc to use the built-in
                   2567: versions. Preferences are determined by the most specific instance of the
                   2568: package in either PREFER_PKGSRC or PREFER_NATIVE. If a package is specified in
                   2569: neither or in both variables, then PREFER_PKGSRC has precedence over
                   2570: PREFER_NATIVE. For example, to require using pkgsrc versions of software for
                   2571: all but the most basic bits on a NetBSD system, you can set:
                   2572:
                   2573:         PREFER_PKGSRC=  yes
                   2574:         PREFER_NATIVE=  getopt skey tcp_wrappers
1.7       wiz      2575:
1.1       grant    2576:
                   2577: A package must have a builtin.mk file to be listed in PREFER_NATIVE, otherwise
                   2578: it is simply ignored in that list.
                   2579:
                   2580: Chapter 10. Options handling
                   2581:
                   2582: Table of Contents
                   2583:
                   2584: 10.1. Global default options
                   2585: 10.2. Converting packages to use bsd.options.mk
                   2586:
                   2587: Many packages have the ability to be built to support different sets of
                   2588: features. bsd.options.mk is a framework in pkgsrc that provides generic
                   2589: handling of those options that determine different ways in which the packages
                   2590: can be built. It's possible for the user to specify exactly which sets of
                   2591: options will be built into a package or to allow a set of global default
                   2592: options apply.
                   2593:
                   2594: 10.1. Global default options
                   2595:
                   2596: Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of
                   2597: the options that should be built into every package if that option is
                   2598: supported. This variable should be set in /etc/mk.conf.
                   2599:
                   2600: 10.2. Converting packages to use bsd.options.mk
                   2601:
                   2602: The following example shows how bsd.options.mk should be use in a package
                   2603: Makefile, or in a file, e.g. options.mk, that is included by the main package
                   2604: Makefile.
                   2605:
                   2606: # Global and legacy options
                   2607: .if defined(WIBBLE_USE_OPENLDAP) && !empty(WIBBLE_USE_OPENLDAP:M[yY][eE][sS])
                   2608: PKG_DEFAULT_OPTIONS+=   ldap
                   2609: .endif
                   2610: .if defined(USE_SASL2) && !empty(USE_SASL2:M[yY][eE][sS])
                   2611: PKG_DEFAULT_OPTIONS+=   sasl
                   2612: .endif
                   2613:
                   2614: PKG_OPTIONS_VAR=        PKG_OPTIONS.wibble
                   2615: PKG_SUPPORTED_OPTIONS=  ldap sasl
                   2616: #
                   2617: # Default options for "wibble" package.
                   2618: #
                   2619: .if !defined(PKG_OPTIONS.wibble)
                   2620: PKG_DEFAULT_OPTIONS+=   sasl
                   2621: endif
                   2622: .include "../../mk/bsd.options.mk"
                   2623:
                   2624: # Package-specific option-handling
                   2625:
                   2626: ###
                   2627: ### LDAP support
                   2628: ###
                   2629: .if !empty(PKG_OPTIONS:Mldap)
                   2630: .  include "../../databases/openldap/buildlink3.mk"
                   2631: CONFIGURE_ARGS+=      --enable-ldap=${BUILDLINK_PREFIX.openldap}
                   2632: .endif
                   2633:
                   2634: ###
                   2635: ### SASL authentication
                   2636: ###
                   2637: .if !empty(PKG_OPTIONS:Msasl)
                   2638: .  include "../../security/cyrus-sasl2/buildlink3.mk"
                   2639: CONFIGURE_ARGS+=        --enable-sasl=${BUILDLINK_PREFIX.sasl}
                   2640: .endif
1.7       wiz      2641:
1.1       grant    2642:
                   2643: The first section only exists if you are converting a package that had its own
                   2644: ad-hoc options handling to use bsd.options.mk. It converts global or legacy
                   2645: options variables into an equivalent PKG_OPTIONS.pkg value. These sections will
                   2646: be removed over time as the old options are in turn deprecated and removed.
                   2647:
                   2648: The second section contains the information about which build options are
                   2649: supported by the package, and any default options settings if needed.
                   2650:
                   2651:  1. PKG_OPTIONS_VAR is a list of the name of the make(1) variables that contain
                   2652:     the options the user wishes to select. The recommended value is
                   2653:     "PKG_OPTIONS.pkg" but any package-specific value may be used. This variable
                   2654:     should be set in a package Makefile.
1.7       wiz      2655:
1.1       grant    2656:  2. PKG_SUPPORTED_OPTIONS is a list of build options supported by the package.
                   2657:     This variable should be set in a package Makefile.
1.7       wiz      2658:
1.1       grant    2659:  3. ${PKG_OPTIONS_VAR} (the variables named in PKG_OPTIONS_VAR) are variables
                   2660:     that list the selected build options and override any default options given
                   2661:     in PKG_DEFAULT_OPTIONS. If any of the options begin with a "-", then that
                   2662:     option is always removed from the selected build options, e.g.
1.7       wiz      2663:
1.1       grant    2664:             PKG_DEFAULT_OPTIONS=    kerberos ldap sasl
                   2665:             PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
                   2666:             WIBBLE_OPTIONS=         ${PKG_DEFAULT_OPTIONS} -sasl
                   2667:             # implies PKG_OPTIONS == "kerberos ldap"
1.7       wiz      2668:
                   2669:
1.1       grant    2670:     or
1.7       wiz      2671:
1.1       grant    2672:             PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
                   2673:             WIBBLE_OPTIONS=         kerberos -ldap ldap
                   2674:             # implies PKG_OPTIONS == "kerberos"
1.7       wiz      2675:
                   2676:
1.1       grant    2677:     This variable should be set in /etc/mk.conf.
1.7       wiz      2678:
1.1       grant    2679: After the inclusion of bsd.options.mk, the following variables are set:
                   2680:
                   2681:   * PKG_OPTIONS contains the list of the selected build options, properly
                   2682:     filtered to remove unsupported and duplicate options.
1.7       wiz      2683:
1.1       grant    2684: The remaining sections contain the logic that is specific to each option. There
                   2685: should be a check for every option listed in PKG_SUPPORTED_OPTIONS, and there
                   2686: should be clear documentation on what turning on the option will do in the
                   2687: comments preceding each section. The correct way to check for an option is to
                   2688: check whether it is listed in PKG_OPTIONS.
                   2689:
                   2690: Chapter 11. The build process
                   2691:
                   2692: Table of Contents
                   2693:
                   2694: 11.1. Program location
                   2695: 11.2. Main targets
                   2696: 11.3. Other helpful targets
                   2697:
                   2698: The basic steps for building a program are always the same. First the program's
                   2699: source (distfile) must be brought to the local system and then extracted. After
                   2700: any patches to compile properly on NetBSD are applied, the software can be
                   2701: configured, then built (usually by compiling), and finally the generated
                   2702: binaries, etc. can be put into place on the system. These are exactly the steps
                   2703: performed by the NetBSD package system, which is implemented as a series of
                   2704: targets in a central Makefile, pkgsrc/mk/bsd.pkg.mk.
                   2705:
                   2706: 11.1. Program location
                   2707:
                   2708: Before outlining the process performed by the NetBSD package system in the next
                   2709: section, here's a brief discussion on where programs are installed, and which
                   2710: variables influence this.
                   2711:
                   2712: The automatic variable PREFIX indicates where all files of the final program
                   2713: shall be installed. It is usually set to LOCALBASE (/usr/pkg), or CROSSBASE for
                   2714: pkgs in the "cross" category. The value of PREFIX needs to be put into the
                   2715: various places in the program's source where paths to these files are encoded.
                   2716: See Section 7.3, "patches/*" and Section 12.3.1, "Shared libraries - libtool"
                   2717: for more details.
                   2718:
                   2719: When choosing which of these variables to use, follow the following rules:
                   2720:
                   2721:   * PREFIX always points to the location where the current pkg will be
                   2722:     installed. When referring to a pkg's own installation path, use "${PREFIX}
                   2723:     ".
1.7       wiz      2724:
1.1       grant    2725:   * LOCALBASE is where all non-X11 pkgs are installed. If you need to construct
                   2726:     a -I or -L argument to the compiler to find includes and libraries
                   2727:     installed by another non-X11 pkg, use "${LOCALBASE}".
1.7       wiz      2728:
1.1       grant    2729:   * X11BASE is where the actual X11 distribution (from xsrc, etc.) is
                   2730:     installed. When looking for standard X11 includes (not those installed by a
                   2731:     pkg), use "${X11BASE}".
1.7       wiz      2732:
1.1       grant    2733:   * X11 based are special in that they may be installed in either X11BASE or
                   2734:     LOCALBASE.
1.7       wiz      2735:
1.1       grant    2736:     Usually, X11 packages should be installed under LOCALBASE whenever
                   2737:     possible. Note that you will need to set USE_X11 in them to request the
                   2738:     presence of X11 and to get the right compilation flags.
1.7       wiz      2739:
1.1       grant    2740:     Even though, there are some packages that cannot be installed under
                   2741:     LOCALBASE: those that come with app-defaults files. These packages are
                   2742:     special and they must be placed under X11BASE. To accomplish this, set
                   2743:     either USE_X11BASE or USE_IMAKE in your package.
1.7       wiz      2744:
1.1       grant    2745:     Some notes: USE_X11 and USE_X11BASE are mutually exclusive. If you need to
                   2746:     find includes or libraries installed by a pkg that has USE_IMAKE or
                   2747:     USE_X11BASE in its pkg Makefile, you need to use both ${X11BASE} and $
1.7       wiz      2748:     {LOCALBASE}. To force installation of all X11 packages in LOCALBASE, the
1.1       grant    2749:     pkgtools/xpkgwedge is enabled by default.
1.7       wiz      2750:
1.1       grant    2751:   * X11PREFIX should be used to refer to the installed location of an X11
                   2752:     package. X11PREFIX will be set to X11BASE if xpkgwedge is not installed,
                   2753:     and to LOCALBASE if xpkgwedge is installed.
1.7       wiz      2754:
1.1       grant    2755:   * If xpkgwedge is installed, it is possible to have some packages installed
                   2756:     in X11BASE and some in LOCALBASE. To determine the prefix of an installed
                   2757:     package, the EVAL_PREFIX definition can be used. It takes pairs in the
                   2758:     format "DIRNAME=<package>", and the make(1) variable DIRNAME will be set to
                   2759:     the prefix of the installed package <package>, or "${X11PREFIX}" if the
                   2760:     package is not installed.
1.7       wiz      2761:
1.1       grant    2762:     This is best illustrated by example.
1.7       wiz      2763:
1.1       grant    2764:     The following lines are taken from pkgsrc/wm/scwm/Makefile:
1.7       wiz      2765:
                   2766:     EVAL_PREFIX+=           GTKDIR=gtk+
1.1       grant    2767:     CONFIGURE_ARGS+=        --with-guile-prefix=${LOCALBASE}        \
                   2768:                             --with-gtk-prefix="${GTKDIR}"           \
                   2769:                             --enable-multibyte
1.7       wiz      2770:
1.1       grant    2771:     Specific defaults can be defined for the packages evaluated using
                   2772:     EVAL_PREFIX, by using a definition of the form:
1.7       wiz      2773:
1.1       grant    2774:     GTKDIR_DEFAULT= ${LOCALBASE}
1.7       wiz      2775:
1.1       grant    2776:     where GTKDIR corresponds to the first definition in the EVAL_PREFIX pair.
1.7       wiz      2777:
1.1       grant    2778:   * Within ${PREFIX}, packages should install files according to hier(7), with
                   2779:     the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/
                   2780:     man.
1.7       wiz      2781:
1.1       grant    2782: 11.2. Main targets
                   2783:
                   2784: The main targets used during the build process defined in bsd.pkg.mk are:
                   2785:
                   2786: fetch
1.7       wiz      2787:
1.1       grant    2788:     This will check if the file(s) given in the variables DISTFILES and
                   2789:     PATCHFILES (as defined in the package's Makefile) are present on the local
                   2790:     system in /usr/pkgsrc/distfiles. If they are not present, an attempt will
                   2791:     be made to fetch them using commands of the form:
1.7       wiz      2792:
1.1       grant    2793:     ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
1.7       wiz      2794:
1.1       grant    2795:     where ${site} varies through several possibilities in turn: first,
                   2796:     MASTER_SITE_OVERRIDE is tried, then the sites specified in either
                   2797:     SITES_file if defined, else MASTER_SITES or PATCH_SITES, as applies, then
                   2798:     finally the value of MASTER_SITE_BACKUP. The order of all except the first
                   2799:     can be optionally sorted by the user, via setting either MASTER_SORT_AWK or
                   2800:     MASTER_SORT_REGEX.
1.7       wiz      2801:
1.1       grant    2802: checksum
1.7       wiz      2803:
1.1       grant    2804:     After the distfile(s) are fetched, their checksum is generated and compared
                   2805:     with the checksums stored in the distinfo file. If the checksums don't
                   2806:     match, the build is aborted. This is to ensure the same distfile is used
                   2807:     for building, and that the distfile wasn't changed, e.g. by some malign
                   2808:     force, deliberately changed distfiles on the master distribution site or
                   2809:     network lossage.
1.7       wiz      2810:
1.1       grant    2811: extract
1.7       wiz      2812:
1.1       grant    2813:     When the distfiles are present on the local system, they need to be
                   2814:     extracted, as they are usually in the form of some compressed archive
                   2815:     format, most commonly .tar.gz.
1.7       wiz      2816:
1.1       grant    2817:     If only some of the distfiles need to be uncompressed, the files to be
                   2818:     uncompressed should be put into EXTRACT_ONLY.
1.7       wiz      2819:
1.1       grant    2820:     If the distfiles are not in .tar.gz format, they can be extracted by
                   2821:     setting either EXTRACT_SUFX, or EXTRACT_CMD, EXTRACT_BEFORE_ARGS and
                   2822:     EXTRACT_AFTER_ARGS. In the former case, pkgsrc knows how to extract a
                   2823:     number of suffixes (.tar.gz, .tgz, .tar.gz2, .tbz, .tar.Z, .tar, .shar.gz,
                   2824:     .shar.bz2, .shar.Z, .shar, .Z, .bz2 and .gz; see the definition of the
                   2825:     various DECOMPRESS_CMD variables bsd.pkg.mk for a complete list). Here's an
                   2826:     example on how to use the other variables for a program that comes with a
                   2827:     compressed shell archive whose name ends in .msg.gz:
1.7       wiz      2828:
1.1       grant    2829:          EXTRACT_SUFX=   .msg.gz
                   2830:          EXTRACT_CMD=            zcat
                   2831:          EXTRACT_BEFORE_ARGS=
                   2832:          EXTRACT_AFTER_ARGS=     |sh
1.7       wiz      2833:
1.1       grant    2834: patch
1.7       wiz      2835:
1.1       grant    2836:     After extraction, all the patches named by the PATCHFILES, those present in
                   2837:     the patches subdirectory of the package as well as in $LOCALPATCHES/
                   2838:     $PKGPATH (e.g. /usr/local/patches/graphics/png) are applied. Patchfiles
                   2839:     ending in .Z or .gz are uncompressed before they are applied, files ending
                   2840:     in .orig or .rej are ignored. Any special options to patch(1) can be handed
                   2841:     in PATCH_DIST_ARGS. See Section 7.3, "patches/*" for more details.
1.7       wiz      2842:
1.1       grant    2843:     By default patch(1) is given special args to make it fail if the patches
                   2844:     apply with some lines of fuzz. Please fix (regen) the patches so that they
                   2845:     apply cleanly. The rationale behind this is that patches that don't apply
                   2846:     cleanly may end up being applied in the wrong place, and cause severe harm
                   2847:     there.
1.7       wiz      2848:
1.1       grant    2849: configure
1.7       wiz      2850:
1.1       grant    2851:     Most pieces of software need information on the header files, system calls,
                   2852:     and library routines which are available in NetBSD. This is the process
                   2853:     known as configuration, and is usually automated. In most cases, a script
                   2854:     is supplied with the source, and its invocation results in generation of
                   2855:     header files, Makefiles, etc.
1.7       wiz      2856:
1.1       grant    2857:     If the program's distfile contains its own configure script, this can be
                   2858:     invoked by setting HAS_CONFIGURE. If the configure script is a GNU autoconf
                   2859:     script, GNU_CONFIGURE should be specified instead. In either case, any
                   2860:     arguments to the configure script can be specified in the CONFIGURE_ARGS
                   2861:     variable, and the configure script's name can be set in CONFIGURE_SCRIPT if
1.7       wiz      2862:     it differs from the default "configure". Here's an example from the
1.1       grant    2863:     sysutils/top package:
1.7       wiz      2864:
1.1       grant    2865:     HAS_CONFIGURE=          yes
                   2866:     CONFIGURE_SCRIPT=       Configure
                   2867:     CONFIGURE_ARGS+=        netbsd13
1.7       wiz      2868:
1.1       grant    2869:     If the program uses an Imakefile for configuration, the appropriate steps
                   2870:     can be invoked by setting USE_IMAKE to "YES". (If you only want the package
                   2871:     installed in $X11PREFIX but xmkmf not being run, set USE_X11BASE instead!)
1.7       wiz      2872:
1.1       grant    2873: build
1.7       wiz      2874:
1.1       grant    2875:     Once configuration has taken place, the software will be built by invoking
                   2876:     $MAKE_PROGRAM on $MAKEFILE with $ALL_TARGET as the target to build. The
1.7       wiz      2877:     default MAKE_PROGRAM is "gmake" if USE_GNU_TOOLS contains "make", "make"
                   2878:     otherwise. MAKEFILE is set to "Makefile" by default, and ALL_TARGET
                   2879:     defaults to "all". Any of these variables can be set in the package's
                   2880:     Makefile to change the default build process.
                   2881:
1.1       grant    2882: install
1.7       wiz      2883:
1.1       grant    2884:     Once the build stage has completed, the final step is to install the
                   2885:     software in public directories, so users can access the programs and files.
                   2886:     As in the build-target, $MAKE_PROGRAM is invoked on $MAKEFILE here, but
                   2887:     with the $INSTALL_TARGET instead, the latter defaulting to "install" (plus
                   2888:     "install.man", if USE_IMAKE is set).
1.7       wiz      2889:
1.1       grant    2890: If no target is specified, the default is "build". If a subsequent stage is
                   2891: requested, all prior stages are made: e.g. make build will also perform the
                   2892: equivalent of:
                   2893:
                   2894: make fetch
                   2895: make checksum
                   2896: make extract
                   2897: make patch
                   2898: make configure
                   2899: make build
                   2900:
                   2901: 11.3. Other helpful targets
                   2902:
                   2903: pre/post-*
1.7       wiz      2904:
1.1       grant    2905:     For any of the main targets described in the previous section, two
                   2906:     auxiliary targets exist with "pre-" and "post-" used as a prefix for the
                   2907:     main target's name. These targets are invoked before and after the main
                   2908:     target is called, allowing extra configuration or installation steps be
                   2909:     performed from a package's Makefile, for example, which a program's
                   2910:     configure script or install target omitted.
1.7       wiz      2911:
1.1       grant    2912: do-*
1.7       wiz      2913:
1.1       grant    2914:     Should one of the main targets do the wrong thing, and should there be no
                   2915:     variable to fix this, you can redefine it with the do-* target. (Note that
                   2916:     redefining the target itself instead of the do-* target is a bad idea, as
                   2917:     the pre-* and post-* targets won't be called anymore, etc.) You will not
                   2918:     usually need to do this.
1.7       wiz      2919:
1.1       grant    2920: reinstall
1.7       wiz      2921:
1.1       grant    2922:     If you did a make install and you noticed some file was not installed
                   2923:     properly, you can repeat the installation with this target, which will
                   2924:     ignore the "already installed" flag.
1.7       wiz      2925:
1.1       grant    2926: deinstall
1.7       wiz      2927:
1.1       grant    2928:     This target does a pkg_delete(1) in the current directory, effectively
                   2929:     de-installing the package. The following variables can be used to tune the
                   2930:     behaviour:
1.7       wiz      2931:
1.1       grant    2932:     PKG_VERBOSE
1.7       wiz      2933:
1.1       grant    2934:         Add a "-v" to the pkg_delete(1) command.
1.7       wiz      2935:
1.1       grant    2936:     DEINSTALLDEPENDS
1.7       wiz      2937:
1.1       grant    2938:         Remove all packages that require (depend on) the given package. This
                   2939:         can be used to remove any packages that may have been pulled in by a
                   2940:         given package, e.g. if make deinstall DEINSTALLDEPENDS=1 is done in
                   2941:         pkgsrc/x11/kde, this is likely to remove whole KDE. Works by adding
                   2942:         "-R" to the pkg_delete(1) command line.
1.7       wiz      2943:
1.1       grant    2944: update
1.7       wiz      2945:
1.1       grant    2946:     This target causes the current package to be updated to the latest version.
                   2947:     The package and all depending packages first get de-installed, then current
                   2948:     versions of the corresponding packages get compiled and installed. This is
                   2949:     similar to manually noting which packages are currently installed, then
                   2950:     performing a series of make deinstall and make install (or whatever
                   2951:     UPDATE_TARGET is set to) for these packages.
1.7       wiz      2952:
1.1       grant    2953:     You can use the "update" target to resume package updating in case a
                   2954:     previous make update was interrupted for some reason. However, in this
                   2955:     case, make sure you don't call make clean or otherwise remove the list of
                   2956:     dependent packages in WRKDIR. Otherwise you lose the ability to
                   2957:     automatically update the current package along with the dependent packages
                   2958:     you have installed.
1.7       wiz      2959:
1.1       grant    2960:     Resuming an interrupted make update will only work as long as the package
                   2961:     tree remains unchanged. If the source code for one of the packages to be
                   2962:     updated has been changed, resuming make update will most certainly fail!
1.7       wiz      2963:
1.1       grant    2964:     The following variables can be used either on the command line or in /etc/
                   2965:     mk.conf to alter the behaviour of make update:
1.7       wiz      2966:
1.1       grant    2967:     UPDATE_TARGET
1.7       wiz      2968:
1.1       grant    2969:         Install target to recursively use for the updated package and the
                   2970:         dependent packages. Defaults to DEPENDS_TARGET if set, "install"
                   2971:         otherwise for make update. e.g. make update UPDATE_TARGET=package
1.7       wiz      2972:
1.1       grant    2973:     NOCLEAN
1.7       wiz      2974:
1.1       grant    2975:         Don't clean up after updating. Useful if you want to leave the work
                   2976:         sources of the updated packages around for inspection or other
                   2977:         purposes. Be sure you eventually clean up the source tree (see the
                   2978:         "clean-update" target below) or you may run into troubles with old
                   2979:         source code still lying around on your next make or make update.
1.7       wiz      2980:
1.1       grant    2981:     REINSTALL
1.7       wiz      2982:
1.1       grant    2983:         Deinstall each package before installing (making DEPENDS_TARGET). This
                   2984:         may be necessary if the "clean-update" target (see below) was called
                   2985:         after interrupting a running make update.
1.7       wiz      2986:
1.1       grant    2987:     DEPENDS_TARGET
1.7       wiz      2988:
1.1       grant    2989:         Allows you to disable recursion and hardcode the target for packages.
                   2990:         The default is "update" for the update target, facilitating a recursive
                   2991:         update of prerequisite packages. Only set DEPENDS_TARGET if you want to
                   2992:         disable recursive updates. Use UPDATE_TARGET instead to just set a
                   2993:         specific target for each package to be installed during make update
                   2994:         (see above).
1.7       wiz      2995:
1.1       grant    2996: clean-update
1.7       wiz      2997:
1.1       grant    2998:     Clean the source tree for all packages that would get updated if make
                   2999:     update was called from the current directory. This target should not be
                   3000:     used if the current package (or any of its depending packages) have already
                   3001:     been de-installed (e.g., after calling make update) or you may lose some
1.7       wiz      3002:     packages you intended to update. As a rule of thumb: only use this target
1.1       grant    3003:     before the first time you run make update and only if you have a dirty
                   3004:     package tree (e.g., if you used NOCLEAN).
1.7       wiz      3005:
                   3006:     If you unsure about whether your tree is clean you can either perform a
1.1       grant    3007:     make clean at the top of the tree, or use the following sequence of
                   3008:     commands from the directory of the package you want to update (before
                   3009:     running make update for the first time, otherwise you lose all the packages
                   3010:     you wanted to update!):
1.7       wiz      3011:
1.1       grant    3012:     # make clean-update
                   3013:     # make clean CLEANDEPENDS=YES
                   3014:     # make update
1.7       wiz      3015:
1.1       grant    3016:     The following variables can be used either on the command line or in /etc/
                   3017:     mk.conf to alter the behaviour of make clean-update:
1.7       wiz      3018:
1.1       grant    3019:     CLEAR_DIRLIST
1.7       wiz      3020:
1.1       grant    3021:         After make clean, do not reconstruct the list of directories to update
                   3022:         for this package. Only use this if make update successfully installed
                   3023:         all packages you wanted to update. Normally, this is done automatically
                   3024:         on make update, but may have been suppressed by the NOCLEAN variable
                   3025:         (see above).
1.7       wiz      3026:
1.1       grant    3027: info
1.7       wiz      3028:
1.1       grant    3029:     This target invokes pkg_info(1) for the current package. You can use this
                   3030:     to check which version of a package is installed.
1.7       wiz      3031:
1.1       grant    3032: readme
1.7       wiz      3033:
1.1       grant    3034:     This target generates a README.html file, which can be viewed using a
                   3035:     browser such as www/mozilla or www/links. The generated files contain
                   3036:     references to any packages which are in the PACKAGES directory on the local
                   3037:     host. The generated files can be made to refer to URLs based on
                   3038:     FTP_PKG_URL_HOST and FTP_PKG_URL_DIR. For example, if I wanted to generate
                   3039:     README.html files which pointed to binary packages on the local machine, in
                   3040:     the directory /usr/packages, set FTP_PKG_URL_HOST=file://localhost and
                   3041:     FTP_PKG_URL_DIR=/usr/packages. The ${PACKAGES} directory and its
                   3042:     subdirectories will be searched for all the binary packages.
1.7       wiz      3043:
1.1       grant    3044: readme-all
1.7       wiz      3045:
1.1       grant    3046:     Use this target to create a file README-all.html which contains a list of
                   3047:     all packages currently available in the NetBSD Packages Collection,
                   3048:     together with the category they belong to and a short description. This
                   3049:     file is compiled from the pkgsrc/*/README.html files, so be sure to run
                   3050:     this after a make readme.
1.7       wiz      3051:
1.1       grant    3052: cdrom-readme
1.7       wiz      3053:
1.1       grant    3054:     This is very much the same as the "readme" target (see above), but is to be
                   3055:     used when generating a pkgsrc tree to be written to a CD-ROM. This target
                   3056:     also produces README.html files, and can be made to refer to URLs based on
                   3057:     CDROM_PKG_URL_HOST and CDROM_PKG_URL_DIR.
1.7       wiz      3058:
1.1       grant    3059: show-distfiles
1.7       wiz      3060:
1.1       grant    3061:     This target shows which distfiles and patchfiles are needed to build the
                   3062:     package. (DISTFILES and PATCHFILES, but not patches/*)
1.7       wiz      3063:
1.1       grant    3064: show-downlevel
1.7       wiz      3065:
1.1       grant    3066:     This target shows nothing if the package is not installed. If a version of
                   3067:     this package is installed, but is not the version provided in this version
                   3068:     of pkgsrc, then a warning message is displayed. This target can be used to
                   3069:     show which of your installed packages are downlevel, and so the old
                   3070:     versions can be deleted, and the current ones added.
1.7       wiz      3071:
1.1       grant    3072: show-pkgsrc-dir
1.7       wiz      3073:
1.1       grant    3074:     This target shows the directory in the pkgsrc hierarchy from which the
                   3075:     package can be built and installed. This may not be the same directory as
                   3076:     the one from which the package was installed. This target is intended to be
                   3077:     used by people who may wish to upgrade many packages on a single host, and
                   3078:     can be invoked from the top-level pkgsrc Makefile by using the
                   3079:     "show-host-specific-pkgs" target.
1.7       wiz      3080:
1.1       grant    3081: show-installed-depends
1.7       wiz      3082:
1.1       grant    3083:     This target shows which installed packages match the current package's
                   3084:     DEPENDS. Useful if out of date dependencies are causing build problems.
1.7       wiz      3085:
1.1       grant    3086: check-shlibs
1.7       wiz      3087:
1.1       grant    3088:     After a package is installed, check all its binaries and (on ELF platforms)
                   3089:     shared libraries to see if they find the shared libs they need. Run by
                   3090:     default if PKG_DEVELOPER is set in /etc/mk.conf.
1.7       wiz      3091:
1.1       grant    3092: print-PLIST
1.7       wiz      3093:
1.1       grant    3094:     After a "make install" from a new or upgraded pkg, this prints out an
                   3095:     attempt to generate a new PLIST from a find -newer work/.extract_done. An
                   3096:     attempt is made to care for shared libs etc., but it is strongly
                   3097:     recommended to review the result before putting it into PLIST. On upgrades,
                   3098:     it's useful to diff the output of this command against an already existing
                   3099:     PLIST file.
1.7       wiz      3100:
1.1       grant    3101:     If the package installs files via tar(1) or other methods that don't update
                   3102:     file access times, be sure to add these files manually to your PLIST, as
                   3103:     the "find -newer" command used by this target won't catch them!
1.7       wiz      3104:
1.1       grant    3105:     See Section 8.3, "Tweaking output of make print-PLIST" for more information
                   3106:     on this target.
1.7       wiz      3107:
1.1       grant    3108: bulk-package
1.7       wiz      3109:
1.1       grant    3110:     Used to do bulk builds. If an appropriate binary package already exists, no
                   3111:     action is taken. If not, this target will compile, install and package it
                   3112:     (and it's depends, if PKG_DEPENDS is set properly. See Section 5.3.1,
                   3113:     "Configuration". After creating the binary package, the sources, the
                   3114:     just-installed package and it's required packages are removed, preserving
                   3115:     free disk space.
1.7       wiz      3116:
1.1       grant    3117:     Beware that this target may deinstall all packages installed on a system!
1.7       wiz      3118:
1.1       grant    3119: bulk-install
1.7       wiz      3120:
1.1       grant    3121:     Used during bulk-installs to install required packages. If an upto-date
1.7       wiz      3122:     binary package is available, it will be installed via pkg_add(1). If not,
1.1       grant    3123:     make bulk-package will be executed, but the installed binary not be
                   3124:     removed.
1.7       wiz      3125:
1.1       grant    3126:     A binary package is considered "upto-date" to be installed via pkg_add(1)
                   3127:     if:
1.7       wiz      3128:
1.1       grant    3129:       * None of the package's files (Makefile, ...) were modified since it was
                   3130:         built.
1.7       wiz      3131:
1.1       grant    3132:       * None of the package's required (binary) packages were modified since it
                   3133:         was built.
1.7       wiz      3134:
1.1       grant    3135:     Beware that this target may deinstall all packages installed on a system!
1.7       wiz      3136:
1.1       grant    3137: Chapter 12. Notes on fixes for packages
                   3138:
                   3139: Table of Contents
                   3140:
                   3141: 12.1. General operation
1.7       wiz      3142:
1.1       grant    3143:     12.1.1. How to pull in variables from /etc/mk.conf
                   3144:     12.1.2. Restricted packages
                   3145:     12.1.3. Handling dependencies
                   3146:     12.1.4. Handling conflicts with other packages
                   3147:     12.1.5. Packages that cannot or should not be built
                   3148:     12.1.6. Packages which should not be deleted, once installed
                   3149:     12.1.7. Handling packages with security problems
                   3150:     12.1.8. How to handle compiler bugs
                   3151:     12.1.9. How to handle incrementing versions when fixing an existing package
                   3152:     12.1.10. Portability of packages
1.7       wiz      3153:
1.1       grant    3154: 12.2. Possible downloading issues
1.7       wiz      3155:
1.1       grant    3156:     12.2.1. Packages whose distfiles aren't available for plain downloading
                   3157:     12.2.2. How to handle modified distfiles with the 'old' name
1.7       wiz      3158:
1.1       grant    3159: 12.3. Configuration gotchas
1.7       wiz      3160:
1.1       grant    3161:     12.3.1. Shared libraries - libtool
                   3162:     12.3.2. Using libtool on GNU packages that already support libtool
                   3163:     12.3.3. GNU Autoconf/Automake
1.7       wiz      3164:
1.1       grant    3165: 12.4. Building considerations
1.7       wiz      3166:
1.1       grant    3167:     12.4.1. CPP defines
1.7       wiz      3168:
1.1       grant    3169: 12.5. Package specific actions
1.7       wiz      3170:
1.1       grant    3171:     12.5.1. Package configuration files
1.2       hubertf  3172:     12.5.2. User interaction
1.1       grant    3173:     12.5.3. Handling licenses
                   3174:     12.5.4. Creating an account from a package
                   3175:     12.5.5. Installing score files
                   3176:     12.5.6. Packages providing login shells
                   3177:     12.5.7. Packages containing perl scripts
                   3178:     12.5.8. Packages with hardcoded paths to other interpreters
                   3179:     12.5.9. Packages installing perl modules
                   3180:     12.5.10. Packages installing info files
                   3181:     12.5.11. Packages installing GConf2 data files
                   3182:     12.5.12. Packages installing scrollkeeper data files
                   3183:     12.5.13. Packages installing X11 fonts
                   3184:     12.5.14. Packages installing GTK2 modules
                   3185:     12.5.15. Packages installing SGML or XML data
                   3186:     12.5.16. Packages installing extensions to the MIME database
                   3187:     12.5.17. Packages using intltool
1.7       wiz      3188:
1.1       grant    3189: 12.6. Feedback to the author
                   3190:
                   3191: 12.1. General operation
                   3192:
                   3193: 12.1.1. How to pull in variables from /etc/mk.conf
                   3194:
                   3195: The problem with package-defined variables that can be overridden via MAKECONF
                   3196: or /etc/mk.conf is that make(1) expands a variable as it is used, but evaluates
                   3197: preprocessor like statements (.if, .ifdef and .ifndef) as they are read. So, to
                   3198: use any variable (which may be set in /etc/mk.conf) in one of the .if*
                   3199: statements, the file /etc/mk.conf must be included before that .if* statement.
                   3200:
                   3201: Rather than have a number of ad-hoc ways of including /etc/mk.conf, should it
                   3202: exist, or MAKECONF, should it exist, include the pkgsrc/mk/bsd.prefs.mk file in
                   3203: the package Makefile before any preprocessor-like .if, .ifdef, or .ifndef
                   3204: statements:
                   3205:
                   3206: .include "../../mk/bsd.prefs.mk"
1.7       wiz      3207:
1.1       grant    3208:     .if defined(USE_MENUS)
                   3209:       ...
                   3210:     .endif
                   3211:
                   3212: If you wish to set the CFLAGS variable in /etc/mk.conf please make sure to use:
                   3213:
                   3214: CFLAGS+=  -your -flags
                   3215:
                   3216: Using CFLAGS= (i.e. without the "+") may lead to problems with packages that
                   3217: need to add their own flags. Also, you may want to take a look at the devel/
                   3218: cpuflags package if you're interested in optimization for the current CPU.
                   3219:
                   3220: 12.1.2. Restricted packages
                   3221:
                   3222: Some licenses restrict how software may be re-distributed. In order to satisfy
                   3223: these restrictions, the package system defines five make variables that can be
                   3224: set to note these restrictions:
                   3225:
                   3226:   * RESTRICTED
1.7       wiz      3227:
1.1       grant    3228:     This variable should be set whenever a restriction exists (regardless of
                   3229:     its kind). Set this variable to a string containing the reason for the
                   3230:     restriction.
1.7       wiz      3231:
1.1       grant    3232:   * NO_BIN_ON_CDROM
1.7       wiz      3233:
1.1       grant    3234:     Binaries may not be placed on CD-ROM. Set this variable to ${RESTRICTED}
                   3235:     whenever a binary package may not be included on a CD-ROM.
1.7       wiz      3236:
1.1       grant    3237:   * NO_BIN_ON_FTP
1.7       wiz      3238:
1.1       grant    3239:     Binaries may not be placed on an FTP server. Set this variable to $
                   3240:     {RESTRICTED} whenever a binary package may not not be made available on the
                   3241:     Internet.
1.7       wiz      3242:
1.1       grant    3243:   * NO_SRC_ON_CDROM
1.7       wiz      3244:
1.1       grant    3245:     Distfiles may not be placed on CD-ROM. Set this variable to ${RESTRICTED}
                   3246:     if re-distribution of the source code or other distfile(s) is not allowed
                   3247:     on CD-ROMs.
1.7       wiz      3248:
1.1       grant    3249:   * NO_SRC_ON_FTP
1.7       wiz      3250:
1.1       grant    3251:     Distfiles may not be placed on FTP. Set this variable to ${RESTRICTED} if
                   3252:     re-distribution of the source code or other distfile(s) via the Internet is
                   3253:     not allowed.
1.7       wiz      3254:
1.1       grant    3255: Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic make
                   3256: variables to denote restrictions is deprecated, because they unconditionally
                   3257: prevent users from generating binary packages!
                   3258:
                   3259: 12.1.3. Handling dependencies
                   3260:
                   3261: Your package may depend on some other package being present - and there are
                   3262: various ways of expressing this dependency. pkgsrc supports the BUILD_DEPENDS
                   3263: and DEPENDS definitions, as well as dependencies via buildlink3.mk, which is
                   3264: the preferred way to handle dependencies, and which uses the variables named
                   3265: above. See Chapter 9, Buildlink methodology for more information.
                   3266:
                   3267: The basic difference between the two variables is as follows: The DEPENDS
                   3268: definition registers that pre-requisite in the binary package so it will be
                   3269: pulled in when the binary package is later installed, whilst the BUILD_DEPENDS
                   3270: definition does not, marking a dependency that is only needed for building the
                   3271: package.
                   3272:
                   3273: This means that if you only need a package present whilst you are building, it
                   3274: should be noted as a BUILD_DEPENDS.
                   3275:
                   3276: The format for a BUILD_DEPENDS and a DEPENDS definition is:
                   3277:
                   3278: <pre-req-package-name>:../../<category>/<pre-req-package>
                   3279:
                   3280: Please note that the "pre-req-package-name" may include any of the wildcard
                   3281: version numbers recognised by pkg_info(1).
                   3282:
                   3283:  1. If your package needs another package's binaries or libraries to build or
                   3284:     run, and if that package has a buildlink3.mk file available, use it:
1.7       wiz      3285:
1.1       grant    3286:         .include "../../graphics/jpeg/buildlink3.mk"
1.7       wiz      3287:
                   3288:
1.1       grant    3289:  2. If your package needs to use another package to build itself and there is
                   3290:     no buildlink3.mk file available, use the BUILD_DEPENDS definition:
1.7       wiz      3291:
1.1       grant    3292:     BUILD_DEPENDS+=  autoconf-2.13:../../devel/autoconf
1.7       wiz      3293:
1.1       grant    3294:  3. If your package needs a library with which to link and again there is no
                   3295:     buildlink3.mk file available, this is specified using the DEPENDS
                   3296:     definition. An example of this is the print/lyx package, which uses the xpm
                   3297:     library, version 3.4j to build:
1.7       wiz      3298:
1.1       grant    3299:     DEPENDS+=       xpm-3.4j:../../graphics/xpm
1.7       wiz      3300:
1.1       grant    3301:     You can also use wildcards in package dependences:
1.7       wiz      3302:
1.1       grant    3303:     DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
1.7       wiz      3304:
1.1       grant    3305:     Note that such wildcard dependencies are retained when creating binary
                   3306:     packages. The dependency is checked when installing the binary package and
                   3307:     any package which matches the pattern will be used. Wildcard dependencies
                   3308:     should be used with care.
1.7       wiz      3309:
1.1       grant    3310:     The "-[0-9]*" should be used instead of "-*" to avoid potentially ambiguous
                   3311:     matches such as "tk-postgresql" matching a "tk-*" DEPENDS.
1.7       wiz      3312:
1.1       grant    3313:     Wildcards can also be used to specify that a package will only build
                   3314:     against a certain minimum version of a pre-requisite:
1.7       wiz      3315:
1.1       grant    3316:     DEPENDS+=       tiff>=3.5.4:../../graphics/tiff
1.7       wiz      3317:
1.1       grant    3318:     This means that the package will build against version 3.5.4 of the tiff
                   3319:     library or newer. Such a dependency may be warranted if, for example, the
                   3320:     API of the library has changed with version 3.5.4 and a package would not
                   3321:     compile against an earlier version of tiff.
1.7       wiz      3322:
1.1       grant    3323:     Please note that such dependencies should only be updated if a package
                   3324:     requires a newer pre-requisite, but not to denote recommendations such as
                   3325:     security updates or ABI changes that do not prevent a package from building
                   3326:     correctly. Such recommendations can be expressed using RECOMMENDED:
1.7       wiz      3327:
1.1       grant    3328:     RECOMMENDED+=   tiff>=3.6.1:../../graphics/tiff
1.7       wiz      3329:
1.1       grant    3330:     In addition to the above DEPENDS line, this denotes that while a package
                   3331:     will build against tiff>=3.5.4, at least version 3.6.1 is recommended.
                   3332:     RECOMMENDED entries will be turned into dependencies unless explicitly
                   3333:     ignored (in which case a warning will be printed). Packages that are built
                   3334:     with recommendations ignored may not be uploaded to ftp.NetBSD.org by
                   3335:     developers and should not be used across different systems that may have
                   3336:     different versions of binary packages installed.
1.7       wiz      3337:
1.1       grant    3338:     For security fixes, please update the package vulnerabilities file as well
                   3339:     as setting RECOMMENDED, see Section 12.1.7, "Handling packages with
                   3340:     security problems" for more information.
1.7       wiz      3341:
1.1       grant    3342:  4. If your package needs some executable to be able to run correctly and if
                   3343:     there's agail no buildlink3.mk file, this is specified using the DEPENDS
                   3344:     variable. The print/lyx package needs to be able to execute the latex
                   3345:     binary from the teTeX package when it runs, and that is specified:
1.7       wiz      3346:
1.1       grant    3347:     DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
1.7       wiz      3348:
1.1       grant    3349:     The comment about wildcard dependencies from previous paragraph applies
                   3350:     here, too.
1.7       wiz      3351:
1.1       grant    3352: If your package needs files from another package to build, see the first part
                   3353: of the "do-configure" target print/ghostscript5 package (it relies on the jpeg
                   3354: sources being present in source form during the build):
                   3355:
                   3356: if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \
                   3357:           cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} extract;              \
                   3358:     fi
                   3359:
                   3360: If you build any other packages that way, please make sure the working files
                   3361: are deleted too when this package's working files are cleaned up. The easiest
                   3362: way to do so is by adding a pre-clean target:
                   3363:
                   3364: pre-clean:
                   3365:           cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} clean
                   3366:
                   3367: Please also note the BUILD_USES_MSGFMT and BUILD_USES_GETTEXT_M4 definitions,
                   3368: which are provided as convenience definitions. The former works out whether
                   3369: msgfmt(1) is part of the base system, and, if it isn't, installs the devel/
                   3370: gettext package. The latter adds a build dependency on either an installed
                   3371: version of an older gettext package, or if it isn't, installs the devel/
                   3372: gettext-m4 package.
                   3373:
                   3374: 12.1.4. Handling conflicts with other packages
                   3375:
                   3376: Your package may conflict with other packages a user might already have
                   3377: installed on his system, e.g. if your package installs the same set of files
                   3378: like another package in our pkgsrc tree.
                   3379:
                   3380: In this case you can set CONFLICTS to a space separated list of packages
                   3381: (including version string) your package conflicts with.
                   3382:
                   3383: For example x11/Xaw3d and x11/Xaw-Xpm install provide the same shared library,
                   3384: thus you set in pkgsrc/x11/Xaw3d/Makefile:
                   3385:
                   3386: CONFLICTS=      Xaw-Xpm-[0-9]*
                   3387:
                   3388: and in pkgsrc/x11/Xaw-Xpm/Makefile:
                   3389:
                   3390: CONFLICTS=      Xaw3d-[0-9]*
                   3391:
                   3392: Packages will automatically conflict with other packages with the name prefix
                   3393: and a different version string. "Xaw3d-1.5" e.g. will automatically conflict
                   3394: with the older version "Xaw3d-1.3".
                   3395:
                   3396: 12.1.5. Packages that cannot or should not be built
                   3397:
                   3398: There are several reasons why a package might be instructed to not build under
                   3399: certain circumstances. If the package builds and runs on most platforms, the
                   3400: exceptions should be noted with NOT_FOR_PLATFORM. If the package builds and
                   3401: runs on a small handful of platforms, set ONLY_FOR_PLATFORM instead. If the
                   3402: package should be skipped (for example, because it provides functionality
                   3403: already provided by the system), set PKG_SKIP_REASON to a descriptive message.
                   3404: If the package should fail because some preconditions are not met, set
                   3405: PKG_FAIL_REASON to a descriptive message.
                   3406:
                   3407: IGNORE is deprecated because it didn't provide enough information to determine
                   3408: whether the build should fail.
                   3409:
                   3410: 12.1.6. Packages which should not be deleted, once installed
                   3411:
                   3412: To ensure that a package may not be deleted, once it has been installed, the
                   3413: PKG_PRESERVE definition should be set in the package Makefile. This will be
                   3414: carried into any binary package that is made from this pkgsrc entry. A
                   3415: "preserved" package will not be deleted using pkg_delete(1) unless the "-f"
                   3416: option is used.
                   3417:
                   3418: 12.1.7. Handling packages with security problems
                   3419:
                   3420: When a vulnerability is found, this should be noted in localsrc/security/
                   3421: advisories/pkg-vulnerabilities, and after the commit of that file, it should be
                   3422: copied to both /pub/NetBSD/packages/distfiles/pkg-vulnerabilities and /pub/
                   3423: NetBSD/packages/distfiles/vulnerabilities on ftp.NetBSD.org using localsrc/
                   3424: security/advisories/Makefile. In addition, if a buildlink3.mk file exists for
                   3425: an affected package, bumping PKGREVISION and creating a corresponding
                   3426: BUILDLINK_RECOMMENDED.pkg entry should be considered. See Chapter 9, Buildlink
                   3427: methodology for more information about writing buildlink3.mk files and
                   3428: BUILDLINK_* definitions.
                   3429:
                   3430: Also, if the fix should be applied to the stable pkgsrc branch, be sure to
                   3431: submit a pullup request!
                   3432:
                   3433: 12.1.8. How to handle compiler bugs
                   3434:
                   3435: Some source files trigger bugs in the compiler, based on combinations of
                   3436: compiler version and architecture and almost always relation to optimisation
                   3437: being enabled. Common symptoms are gcc internal errors or never finishing
                   3438: compiling a file.
                   3439:
                   3440: Typically a workaround involves testing the MACHINE_ARCH and compiler version,
                   3441: disabling optimisation for that file/MACHINE_ARCH/compiler combination, and
                   3442: documenting it in pkgsrc/doc/HACKS. See that file for a number of examples!
                   3443:
                   3444: 12.1.9. How to handle incrementing versions when fixing an existing package
                   3445:
                   3446: When making fixes to an existing package it can be useful to change the version
                   3447: number in PKGNAME. To avoid conflicting with future versions by the original
                   3448: author, a "nb1", "nb2", ... suffix can be used on package versions by setting
                   3449: PKGREVISION=1 (2, ...). The "nb" is treated like a "." by the pkg tools. e.g.
                   3450:
                   3451:   DISTNAME= foo-17.42
                   3452:     PKGREVISION=  9
                   3453:
                   3454: will result in a PKGNAME of "foo-17.42nb9".
                   3455:
                   3456: When a new release of the package is released, the PKGREVISION should be
                   3457: removed. e.g. on a new minor release of the above package, things should be
                   3458: like:
                   3459:
                   3460: DISTNAME=   foo-17.43
                   3461:
                   3462: 12.1.10. Portability of packages
                   3463:
                   3464: One appealing feature of pkgsrc is that it runs on many different platforms. As
                   3465: a result, it is important to ensure, where possible, that packages in pkgsrc
                   3466: are portable. There are some particular details you should pay attention to
                   3467: while working on pkgsrc.
                   3468:
                   3469: 12.1.10.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ...
                   3470:
                   3471: The BSD-compatible install supplied with some operating systems will not
                   3472: perform more than one operation at a time. As such, you should call "${INSTALL}
                   3473: ", etc. like this:
                   3474:
                   3475: ${INSTALL_DATA_DIR} ${PREFIX}/dir1
                   3476: ${INSTALL_DATA_DIR} ${PREFIX}/dir2
                   3477:
                   3478: 12.2. Possible downloading issues
                   3479:
                   3480: 12.2.1. Packages whose distfiles aren't available for plain downloading
                   3481:
                   3482: If you need to download from a dynamic URL you can set DYNAMIC_MASTER_SITES and
                   3483: a make fetch will call files/getsite.sh with the name of each file to download
                   3484: as an argument, expecting it to output the URL of the directory from which to
                   3485: download it. graphics/ns-cult3d is an example of this usage.
                   3486:
                   3487: If the download can't be automated, because the user must submit personal
                   3488: information to apply for a password, or must pay for the source, or whatever,
                   3489: you can set _FETCH_MESSAGE to a macro which displays a message explaining the
                   3490: situation. _FETCH_MESSAGE must be executable shell commands, not just a
                   3491: message. (Generally, it executes ${ECHO}). As of this writing, the following
                   3492: packages use this: audio/realplayer, cad/simian, devel/ipv6socket, emulators/
                   3493: vmware-module, fonts/acroread-jpnfont, sysutils/storage-manager, www/
                   3494: ap-aolserver, www/openacs. Try to be consistent with them.
                   3495:
                   3496: 12.2.2. How to handle modified distfiles with the 'old' name
                   3497:
                   3498: Sometimes authors of a software package make some modifications after the
                   3499: software was released, and they put up a new distfile without changing the
                   3500: package's version number. If a package is already in pkgsrc at that time, the
                   3501: md5 checksum will no longer match. The correct way to work around this is to
                   3502: update the package's md5 checksum to match the package on the master site
                   3503: (beware, any mirrors may not be up to date yet!), and to remove the old
                   3504: distfile from ftp.NetBSD.org's /pub/NetBSD/packages/distfiles directory.
                   3505: Furthermore, a mail to the package's author seems appropriate making sure the
                   3506: distfile was really updated on purpose, and that no trojan horse or so crept
                   3507: in.
                   3508:
                   3509: 12.3. Configuration gotchas
                   3510:
                   3511: 12.3.1. Shared libraries - libtool
                   3512:
                   3513: pkgsrc supports many different machines, with different object formats like
                   3514: a.out and ELF, and varying abilities to do shared library and dynamic loading
                   3515: at all. To accompany this, varying commands and options have to be passed to
                   3516: the compiler, linker, etc. to get the Right Thing, which can be pretty annoying
1.7       wiz      3517: especially if you don't have all the machines at your hand to test things. The
1.1       grant    3518: devel/libtool pkg can help here, as it just "knows" how to build both static
                   3519: and dynamic libraries from a set of source files, thus being platform
                   3520: independent.
                   3521:
                   3522: Here's how to use libtool in a pkg in seven simple steps:
                   3523:
                   3524:  1. Add USE_LIBTOOL=yes to the package Makefile.
1.7       wiz      3525:
1.1       grant    3526:  2. For library objects, use "${LIBTOOL} --mode=compile ${CC}" in place of "$
                   3527:     {CC}". You could even add it to the definition of CC, if only libraries are
                   3528:     being built in a given Makefile. This one command will build both PIC and
                   3529:     non-PIC library objects, so you need not have separate shared and
                   3530:     non-shared library rules.
1.7       wiz      3531:
1.1       grant    3532:  3. For the linking of the library, remove any "ar", "ranlib", and "ld
                   3533:     -Bshareable" commands, and instead use:
1.7       wiz      3534:
1.1       grant    3535:     ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} -rpath ${PREFIX}/lib -version-info major:minor
1.7       wiz      3536:
1.1       grant    3537:     Note that the library is changed to have a .la extension, and the objects
                   3538:     are changed to have a .lo extension. Change OBJS as necessary. This
                   3539:     automatically creates all of the .a, .so.major.minor, and ELF symlinks (if
                   3540:     necessary) in the build directory. Be sure to include "-version-info",
                   3541:     especially when major and minor are zero, as libtool will otherwise strip
                   3542:     off the shared library version.
1.7       wiz      3543:
1.1       grant    3544:     From the libtool manual:
1.7       wiz      3545:
1.1       grant    3546:          So, libtool library versions are described by three integers:
1.7       wiz      3547:
1.1       grant    3548:     CURRENT
                   3549:            The most recent interface number that this library implements.
1.7       wiz      3550:
1.1       grant    3551:     REVISION
                   3552:            The implementation number of the CURRENT interface.
1.7       wiz      3553:
1.1       grant    3554:     AGE
                   3555:            The difference between the newest and oldest interfaces that this
                   3556:            library implements.  In other words, the library implements all the
                   3557:            interface numbers in the range from number `CURRENT - AGE' to
                   3558:            `CURRENT'.
1.7       wiz      3559:
1.1       grant    3560:          If two libraries have identical CURRENT and AGE numbers, then the
1.7       wiz      3561:     dynamic linker chooses the library with the greater REVISION number.
                   3562:
1.1       grant    3563:     The "-release" option will produce different results for a.out and ELF
                   3564:     (excluding symlinks) in only one case. An ELF library of the form
                   3565:     "libfoo-release.so.x.y" will have a symlink of "libfoo.so.x.y" on an a.out
                   3566:     platform. This is handled automatically.
1.7       wiz      3567:
1.1       grant    3568:     The "-rpath argument" is the install directory of the library being built.
1.7       wiz      3569:
                   3570:     In the PLIST, include all of the .a, .la, and .so, .so.major and .so.major.
                   3571:     minor files.
                   3572:
1.1       grant    3573:  4. When linking shared object (.so) files, i.e. files that are loaded via
                   3574:     dlopen(3), NOT shared libraries, use "-module -avoid-version" to prevent
                   3575:     them getting version tacked on.
1.7       wiz      3576:
1.1       grant    3577:     The PLIST file gets the foo.so entry.
1.7       wiz      3578:
1.1       grant    3579:  5. When linking programs that depend on these libraries before they are
                   3580:     installed, preface the cc(1) or ld(1) line with "${LIBTOOL} --mode=link",
                   3581:     and it will find the correct libraries (static or shared), but please be
                   3582:     aware that libtool will not allow you to specify a relative path in -L
                   3583:     (such as "-L../somelib"), because it expects you to change that argument to
                   3584:     be the .la file. e.g.
1.7       wiz      3585:
1.1       grant    3586:     ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
1.7       wiz      3587:
1.1       grant    3588:     should be changed to:
1.7       wiz      3589:
1.1       grant    3590:     ${LIBTOOL} --mode=link ${CC} -o someprog ../somelib/somelib.la
1.7       wiz      3591:
1.1       grant    3592:     and it will do the right thing with the libraries.
1.7       wiz      3593:
1.1       grant    3594:  6. When installing libraries, preface the install(1) or cp(1) command with "$
                   3595:     {LIBTOOL} --mode=install", and change the library name to .la. e.g.
1.7       wiz      3596:
1.1       grant    3597:     ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
1.7       wiz      3598:
1.1       grant    3599:     This will install the static .a, shared library, any needed symlinks, and
                   3600:     run ldconfig(8).
1.7       wiz      3601:
1.1       grant    3602:  7. In your PLIST, include all of the .a, .la, and .so, .so.CURRENT and
                   3603:     .so.CURRENT.REVISION files (this is a change from the previous behaviour).
1.7       wiz      3604:
1.1       grant    3605: 12.3.2. Using libtool on GNU packages that already support libtool
                   3606:
                   3607: Add USE_LIBTOOL=yes to the package Makefile. This will override the package's
                   3608: own libtool in most cases. For older libtool using packages, libtool is made by
                   3609: ltconfig script during the do-configure step; you can check the libtool script
                   3610: location by doing make configure; find work*/ -name libtool.
                   3611:
                   3612: LIBTOOL_OVERRIDE specifies which libtool scripts, relative to WRKSRC, to
                   3613: override. By default, it is set to "libtool */libtool */*/libtool". If this
                   3614: does not match the location of the package's libtool script(s), set it as
                   3615: appropriate.
                   3616:
                   3617: If you do not need *.a static libraries built and installed, then use
                   3618: SHLIBTOOL_OVERRIDE instead.
                   3619:
                   3620: If your package makes use of the platform independent library for loading
                   3621: dynamic shared objects, that comes with libtool (libltdl), you should include
                   3622: the libtool buildlink3.mk (and set USE_BUILDLINK3=YES).
                   3623:
                   3624: Some packages use libtool incorrectly so that the package may not work or build
                   3625: in some circumstances. Some of the more common errors are:
                   3626:
                   3627:   * The inclusion of a shared object (-module) as a dependent library in an
                   3628:     executable or library. This in itself isn't a problem if one of two things
                   3629:     has been done:
1.7       wiz      3630:
1.1       grant    3631:      1. The shared object is named correctly, i.e. libfoo.la, not foo.la
1.7       wiz      3632:
1.1       grant    3633:      2. The -dlopen option is used when linking an executable.
1.7       wiz      3634:
1.1       grant    3635:   * The use of libltdl without the correct calls to initialisation routines.
                   3636:     The function lt_dlinit() should be called and the macro
                   3637:     LTDL_SET_PRELOADED_SYMBOLS included in executables.
1.7       wiz      3638:
1.1       grant    3639: 12.3.3. GNU Autoconf/Automake
                   3640:
                   3641: If a package needs GNU autoconf or automake to be executed to regenerate the
                   3642: configure script and Makefile.in makefile templates, then they should be
                   3643: executed in a pre-configure target. Two Makefile fragments are provided in
                   3644: pkgsrc/mk/autoconf.mk and pkgsrc/mk/automake.mk to help dealing with these
                   3645: tools. See comments in these files for details.
                   3646:
                   3647: For packages that need only autoconf:
                   3648:
                   3649: AUTOCONF_REQD=    2.50    # if default version is not good enough
                   3650: ...
                   3651:
                   3652: pre-configure:
                   3653:           cd ${WRKSRC}; ${AUTOCONF}
                   3654:
                   3655: ...
                   3656: .include "../../mk/autoconf.mk"
                   3657:
                   3658: and for packages that need automake and autoconf:
                   3659:
                   3660: AUTOMAKE_REQD=  1.7.1   # if default version is not good enough
                   3661: ...
                   3662:
                   3663: pre-configure:
                   3664:           cd ${WRKSRC};                                           \
                   3665:           ${ACLOCAL};                                             \
                   3666:           ${AUTOHEADER};                                          \
                   3667:           ${AUTOMAKE} -a --foreign -i;                            \
                   3668:           ${AUTOCONF}
                   3669:
                   3670: ...
                   3671: .include "../mk/automake.mk"
                   3672:
                   3673: Packages which use GNU Automake will almost certainly require GNU Make, but
                   3674: that's automatically provided for you in mk/automake.mk.
                   3675:
                   3676: There are times when the configure process makes additional changes to the
                   3677: generated files, which then causes the build process to try to re-execute the
                   3678: automake sequence. This is prevented by touching various files in the configure
                   3679: stage. If this causes problems with your package you can set AUTOMAKE_OVERRIDE=
                   3680: NO in the package Makefile.
                   3681:
                   3682: 12.4. Building considerations
                   3683:
                   3684: 12.4.1. CPP defines
                   3685:
                   3686: To port an application to NetBSD, it's usually necessary for the compiler to be
                   3687: able to judge the system on which it's compiling, and we use definitions so
                   3688: that the C pre-processor can do this.
                   3689:
                   3690: To test whether you are working on a 4.4 BSD-derived system, you should use the
                   3691: BSD definition, which is defined in <sys/param.h> on said systems.
                   3692:
                   3693: #include <sys/param.h>
                   3694:
                   3695: and then you can surround the BSD-specific parts of your package's C/C++ code
                   3696: using this conditional:
                   3697:
                   3698: #if (defined(BSD) && BSD >= 199306)
                   3699:     ...
                   3700: #endif
                   3701:
                   3702: Please use the "__NetBSD__" definition sparingly - it should only apply to
                   3703: features of NetBSD that are not present in other 4.4-lite derived BSDs.
                   3704:
                   3705: 12.5. Package specific actions
                   3706:
                   3707: 12.5.1. Package configuration files
                   3708:
                   3709: Packages should be taught to look for their configuration files in $
                   3710: {PKG_SYSCONFDIR}, which is passed through to the configure and build processes.
                   3711: PKG_SYSCONFDIR may be customized in various ways by setting other make
                   3712: variables:
                   3713:
                   3714:   * PKG_SYSCONFBASE is the main config directory under which all package
                   3715:     configuration files are to be found. This defaults to ${PREFIX}/etc, but
                   3716:     may be overridden in /etc/mk.conf.
1.7       wiz      3717:
1.1       grant    3718:   * PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which the
                   3719:     configuration files for a particular package may be found, e.g. the Apache
                   3720:     configuration files may all be found under the httpd/ subdirectory of $
                   3721:     {PKG_SYSCONFBASE}. This should be set in the package Makefile.
1.7       wiz      3722:
1.1       grant    3723:   * By default, PKG_SYSCONFDIR is set to ${PKG_SYSCONFBASE}/$
                   3724:     {PKG_SYSCONFSUBDIR}, but this may be overridden by setting PKG_SYSCONFDIR.$
                   3725:     {PKG_SYSCONFVAR} for a particular package, where PKG_SYSCONFVAR defaults to
                   3726:     ${PKGBASE}. This is not meant to be set by a package Makefile, but is
                   3727:     reserved for users who wish to override the PKG_SYSCONFDIR setting for a
                   3728:     particular package with a special location.
1.7       wiz      3729:
1.1       grant    3730: The only variables that users should customize are PKG_SYSCONFBASE and
                   3731: PKG_SYSCONFDIR.${PKG_SYSCONFVAR}. Users will typically want to set
                   3732: PKG_SYSCONFBASE to /etc, or to accept the default location of ${PREFIX}/etc.
                   3733:
1.2       hubertf  3734: 12.5.2. User interaction
1.1       grant    3735:
                   3736: Occasionally, packages require interaction from the user, and this can be in a
                   3737: number of ways:
                   3738:
                   3739:   * help in fetching the distfiles
1.7       wiz      3740:
1.1       grant    3741:   * help to configure the package before it is built
1.7       wiz      3742:
1.1       grant    3743:   * help during the build process
1.7       wiz      3744:
1.1       grant    3745:   * help during the installation of a package
1.7       wiz      3746:
1.1       grant    3747: The INTERACTIVE_STAGE definition is provided to notify the pkgsrc mechanism of
                   3748: an interactive stage which will be needed, and this should be set in the
                   3749: package's Makefile. e.g.
                   3750:
                   3751: INTERACTIVE_STAGE= build
                   3752:
                   3753: Multiple interactive stages can be specified:
                   3754:
                   3755: INTERACTIVE_STAGE= configure install
                   3756:
                   3757: 12.5.3. Handling licenses
                   3758:
                   3759: A package may underly a license which the user has or has not agreed to accept.
                   3760: Usually, packages that underly well-known Open Source licenses (e.g. the GNU
                   3761: Public License, GPL) won't have any special license tags added in pkgsrc which
                   3762: require special action by the user of such packages, but there are quite a
                   3763: number of other licenses out there that pkgsrc users may not be able to follow,
                   3764: for whatever reasons. For these cases, pkgsrc contains a mechanism to note that
                   3765: a package underlies a certain license, and the user has to accept the license
                   3766: before the package can be installed.
                   3767:
                   3768: Placing a certain package under a certain license works by setting the LICENSE
                   3769: variable to a string identifying the license, e.g. in graphics/graphviz:
                   3770:
                   3771: LICENSE=        graphviz-license
                   3772:
                   3773: When trying to build, the user will get a notice that the package underlies a
                   3774: license which he hasn't accepted (yet):
                   3775:
                   3776: % make
                   3777: ===> graphviz-1.12 has an unacceptable license: graphviz-license.
                   3778: ===>     To build this package, add this line to your /etc/mk.conf:
                   3779: ===>     ACCEPTABLE_LICENSES+=graphviz-license
                   3780: ===>     To view the license, enter "/usr/bin/make show-license".
                   3781: *** Error code 1
                   3782:
                   3783: The license can be viewed with make show-license, and if it is considered
                   3784: appropriate, the line printed above can be added to /etc/mk.conf to indicate
                   3785: acceptance of the particular license:
                   3786:
                   3787: ACCEPTABLE_LICENSES+=graphviz-license
                   3788:
                   3789: When adding a package with a new license, the license text should be added to
                   3790: pkgsrc/licenses for displaying. A list of known licenses can be seen in this
                   3791: directory as well as by looking at the list of (commented out)
                   3792: ACCEPTABLE_LICENSES variable settings in pkgsrc/mk/bsd.pkg.defaults.mk.
                   3793:
                   3794: Is there is a really pressing need to accept all licenses at once, like when
                   3795: trying to download or mirror all distfiles or doing a bulk build to test if all
                   3796: packages in pkgsrc build, this can be done by setting _ACCEPTABLE=yes.
                   3797:
                   3798: 12.5.4. Creating an account from a package
                   3799:
                   3800: There are two make variables used to control the creation of package-specific
                   3801: groups and users at pre-install time. The first is PKG_GROUPS, which is a list
                   3802: of group[:groupid] elements, where the groupid is optional. The second is
                   3803: PKG_USERS, which is a list of elements of the form:
                   3804:
                   3805: user:group[:[userid][:[description][:[home][:shell]]]]
                   3806:
                   3807: where only the user and group are required, the rest being optional. A simple
                   3808: example is:
                   3809:
                   3810:   PKG_GROUPS=       foogroup
                   3811:     PKG_USERS=    foouser:foogroup
                   3812:
                   3813: A more complex example is that creates two groups and two users is:
                   3814:
                   3815:   PKG_GROUPS=       group1 group2:1005
                   3816:     PKG_USERS=    first:group1::First\\ User                      \
                   3817:                   second:group2::Second\\ User:/home/second:${SH}
                   3818:
                   3819: By default, a new user will have home directory /nonexistent, and login shell /
                   3820: sbin/nologin unless they are specified as part of the user element.
                   3821:
                   3822: The package Makefile must also set USE_PKGINSTALL=YES. This will cause the
                   3823: users and groups to be created at pre-install time, and the admin will be
                   3824: prompted to remove them at post-deinstall time. Automatic creation of the users
                   3825: and groups can be toggled on and off by setting the PKG_CREATE_USERGROUP
                   3826: variable prior to package installation.
                   3827:
                   3828: 12.5.5. Installing score files
                   3829:
                   3830: Certain packages, most of them in the games category, install a score file that
                   3831: allows all users on the system to record their highscores. In order for this to
                   3832: work, the binaries need to be installed setgid and the score files owned by the
                   3833: appropriate group and/or owner (traditionally the "games" user/group). The
                   3834: following variables, documented in more detail in mk/bsd.pkg.defaults.mk,
                   3835: control this behaviour: SETGIDGAME, GAMEDATAMODE, GAMEGRP, GAMEMODE, GAMEOWN.
                   3836:
                   3837: Note that per default, setgid installation of games is disabled; setting
                   3838: SETGIDGAME=YES will set all the other variables accordingly.
                   3839:
                   3840: A package should therefor never hard code file ownership or access permissions
                   3841: but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly.
                   3842:
                   3843: 12.5.6. Packages providing login shells
                   3844:
                   3845: If the purpose of the package is to provide a login shell, the variable
                   3846: PKG_SHELL should contain the full pathname of the shell executable installed by
                   3847: this package. The package Makefile must also set USE_PKGINSTALL=YES to use the
                   3848: automatically generated INSTALL/DEINSTALL scripts.
                   3849:
                   3850: An example taken from shells/zsh:
                   3851:
                   3852:   USE_PKGINSTALL=   YES
                   3853:     PKG_SHELL=    ${PREFIX}/bin/zsh
                   3854:
                   3855: The shell is registered into /etc/shells file automatically in the post-install
                   3856: target by the generated INSTALL script and removed in the deinstall target by
                   3857: the DEINSTALL script.
                   3858:
                   3859: 12.5.7. Packages containing perl scripts
                   3860:
                   3861: If your package contains interpreted perl scripts, set REPLACE_PERL to ensure
                   3862: that the proper interpreter path is set. REPLACE_PERL should contain a list of
                   3863: scripts, relative to WRKSRC, that you want adjusted.
                   3864:
                   3865: 12.5.8. Packages with hardcoded paths to other interpreters
                   3866:
                   3867: Your package may also contain scripts with hardcoded paths to other
                   3868: interpreters besides (or as well as) perl. To correct the full pathname to the
                   3869: script interpreter, you need to set the following definitions in your Makefile
                   3870: (we shall use tclsh in this example):
                   3871:
                   3872:   REPLACE_INTERPRETER+=     tcl
                   3873:     _REPLACE.tcl.old=     .*/bin/tclsh
                   3874:     _REPLACE.tcl.new=     ${PREFIX}/bin/tclsh
                   3875:     _REPLACE_FILES.tcl=   ...list of tcl scripts which need to be fixed,
                   3876:                           relative to ${WRKSRC}, just as in REPLACE_PERL
                   3877:
                   3878: 12.5.9. Packages installing perl modules
                   3879:
                   3880: Makefiles of packages providing perl5 modules should include the Makefile
                   3881: fragment ../../lang/perl5/module.mk. It provides a do-configure target for the
                   3882: standard perl configuration for such modules as well as various hooks to tune
                   3883: this configuration. See comments in this file for details.
                   3884:
                   3885: Perl5 modules will install into different places depending on the version of
                   3886: perl used during the build process. To address this, pkgsrc will append lines
                   3887: to the PLIST corresponding to the files listed in the installed .packlist file
                   3888: generated by most perl5 modules. This is invoked by defining PERL5_PACKLIST to
                   3889: a space-separated list of paths to packlist files, e.g.:
                   3890:
                   3891: PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist
                   3892:
                   3893: The variables PERL5_SITELIB, PERL5_SITEARCH, and PERL5_ARCHLIB represent the
                   3894: three locations in which perl5 modules may be installed, and may be used by
                   3895: perl5 packages that don't have a packlist. These three variables are also
                   3896: substituted for in the PLIST.
                   3897:
                   3898: 12.5.10. Packages installing info files
                   3899:
                   3900: Some packages install info files or use the "makeinfo" or "install-info"
                   3901: commands. Each of the info files:
                   3902:
                   3903:   * is considered to be installed in the directory ${PREFIX}/${INFO_DIR},
1.7       wiz      3904:
1.1       grant    3905:   * is registered in the Info directory file ${PREFIX}/${INFO_DIR}/dir,
1.7       wiz      3906:
1.1       grant    3907:   * and must be listed as a filename in the INFO_FILES variable in the package
                   3908:     Makefile.
1.7       wiz      3909:
1.1       grant    3910: INFO_DIR defaults to "info" and can be overridden in the package Makefile.
                   3911: INSTALL and DEINSTALL scripts will be generated to handle registration of the
                   3912: info files in the Info directory file. The "install-info" command used for the
                   3913: info files registration is either provided by the system, or by a special
                   3914: purpose package automatically added as dependency if needed.
                   3915:
                   3916: A package which needs the "makeinfo" command at build time must define the
                   3917: variable USE_MAKEINFO in its Makefile. If a minimum version of the "makeinfo"
                   3918: command is needed it should be noted with the TEXINFO_REQD variable in the
                   3919: package Makefile. By default, a minimum version of 3.12 is required. If the
                   3920: system does not provide a makeinfo command or if it does not match the required
                   3921: minimum, a build dependency on the devel/gtexinfo package will be added
                   3922: automatically.
                   3923:
                   3924: The build and installation process of the software provided by the package
                   3925: should not use the install-info command as the registration of info files is
1.7       wiz      3926: the task of the package INSTALL script, and it must use the appropriate
1.1       grant    3927: makeinfo command.
                   3928:
                   3929: To achieve this goal the pkgsrc infrastructure creates overriding scripts for
                   3930: the install-info and makeinfo commands in a directory listed early in PATH.
                   3931:
                   3932: The script overriding install-info has no effect except the logging of a
                   3933: message. The script overriding makeinfo logs a message and according to the
                   3934: value of USE_MAKEINFO and TEXINFO_REQD either run the appropriate makeinfo
                   3935: command or exit on error.
                   3936:
                   3937: 12.5.11. Packages installing GConf2 data files
                   3938:
                   3939: If a package installs .schemas or .entries files, used by GConf2, you need to
                   3940: take some extra steps to make sure they get registered in the database:
                   3941:
                   3942:  1. Include ../../devel/GConf2/schemas.mk instead of its buildlink3.mk file.
                   3943:     This takes care of rebuilding the GConf2 database at installation and
                   3944:     deinstallation time, and tells the package where to install GConf2 data
                   3945:     files using some standard configure arguments. It also disallows any access
                   3946:     to the database directly from the package.
1.7       wiz      3947:
1.1       grant    3948:  2. Ensure that the package installs its .schemas files under ${PREFIX}/share/
                   3949:     gconf/schemas. If they get installed under ${PREFIX}/etc, you will need to
                   3950:     manually patch the package.
1.7       wiz      3951:
1.1       grant    3952:  3. Check the PLIST and remove any entries under the etc/gconf directory, as
                   3953:     they will be handled automatically. See Section 6.13, "Configuration files
                   3954:     handling and placement" for more information.
1.7       wiz      3955:
1.1       grant    3956:  4. Define the GCONF2_SCHEMAS variable in your Makefile with a list of all
                   3957:     .schemas files installed by the package, if any. Names must not contain any
                   3958:     directories in them.
1.7       wiz      3959:
1.1       grant    3960:  5. Define the GCONF2_ENTRIES variable in your Makefile with a list of all
                   3961:     .entries files installed by the package, if any. Names must not contain any
                   3962:     directories in them.
1.7       wiz      3963:
1.1       grant    3964: 12.5.12. Packages installing scrollkeeper data files
                   3965:
                   3966: If a package installs .omf files, used by scrollkeeper, you need to take some
                   3967: extra steps to make sure they get registered in the database:
                   3968:
                   3969:  1. Include ../../textproc/scrollkeeper/omf.mk instead of its buildlink3.mk
                   3970:     file. This takes care of rebuilding the scrollkeeper database at
                   3971:     installation and deinstallation time, and disallows any access to it
                   3972:     directly from the package.
1.7       wiz      3973:
1.1       grant    3974:  2. Check the PLIST and remove any entries under the libdata/scrollkeeper
                   3975:     directory, as they will be handled automatically.
1.7       wiz      3976:
1.1       grant    3977:  3. Remove the share/omf directory from the PLIST. It will be handled by
                   3978:     scrollkeeper.
1.7       wiz      3979:
1.1       grant    3980: 12.5.13. Packages installing X11 fonts
                   3981:
                   3982: If a package installs font files, you will need to rebuild the fonts database
                   3983: in the directory where they get installed at installation and deinstallation
                   3984: time. This can be automatically done by using mk/fonts.mk, which you need to
                   3985: include in your Makefile.
                   3986:
                   3987: When the file is included, you can list the directories where fonts are
                   3988: installed in the FONTS_type_DIRS variables, where type can be one of "TTF",
                   3989: "TYPE1" or "X11". Also make sure that the database file fonts.dir is not listed
                   3990: in the PLIST.
                   3991:
                   3992: Note that you should not create new directories for fonts; instead use the
                   3993: standard ones to avoid that the user needs to manually configure his X server
                   3994: to find them.
                   3995:
                   3996: 12.5.14. Packages installing GTK2 modules
                   3997:
                   3998: If a package installs gtk2 immodules or loaders, you need to take some extra
                   3999: steps to get them registered in the GTK2 database properly:
                   4000:
                   4001:  1. Include ../../x11/gtk2/modules.mk instead of its buildlink3.mk file. This
                   4002:     takes care of rebuilding the database at installation and deinstallation
                   4003:     time.
1.7       wiz      4004:
1.1       grant    4005:  2. Set GTK2_IMMODULES=YES if your package installs GTK2 immodules.
1.7       wiz      4006:
1.1       grant    4007:  3. Set GTK2_LOADERS=YES if your package installs GTK2 loaders.
1.7       wiz      4008:
1.1       grant    4009:  4. Patch the package to not touch any of the gtk2 databases directly. These
                   4010:     are:
1.7       wiz      4011:
1.1       grant    4012:       * libdata/gtk-2.0/gdk-pixbuf.loaders
1.7       wiz      4013:
1.1       grant    4014:       * libdata/gtk-2.0/gtk.immodules
1.7       wiz      4015:
1.1       grant    4016:  5. Check the PLIST and remove any entries under the libdata/gtk-2.0 directory,
                   4017:     as they will be handled automatically.
1.7       wiz      4018:
1.1       grant    4019: 12.5.15. Packages installing SGML or XML data
                   4020:
                   4021: If a package installs SGML or XML data files that need to be registered in
                   4022: system-wide catalogs (like DTDs, sub-catalogs, etc.), you need to take some
                   4023: extra steps:
                   4024:
                   4025:  1. Include ../../textproc/xmlcatmgr/catalogs.mk in your Makefile, which takes
                   4026:     care of registering those files in system-wide catalogs at installation and
                   4027:     deinstallation time.
1.7       wiz      4028:
1.1       grant    4029:  2. Set SGML_CATALOGS to the full path of any SGML catalogs installed by the
                   4030:     package.
1.7       wiz      4031:
1.1       grant    4032:  3. Set XML_CATALOGS to the full path of any XML catalogs installed by the
                   4033:     package.
1.7       wiz      4034:
1.1       grant    4035:  4. Set SGML_ENTRIES to individual entries to be added to the SGML catalog.
                   4036:     These come in groups of three strings; see xmlcatmgr(1) for more
                   4037:     information (specifically, arguments recognized by the 'add' action). Note
                   4038:     that you will normally not use this variable.
1.7       wiz      4039:
1.1       grant    4040:  5. Set XML_ENTRIES to individual entries to be added to the XML catalog. These
                   4041:     come in groups of three strings; see xmlcatmgr(1) for more information
                   4042:     (specifically, arguments recognized by the 'add' action). Note that you
                   4043:     will normally not use this variable.
1.7       wiz      4044:
1.1       grant    4045: 12.5.16. Packages installing extensions to the MIME database
                   4046:
                   4047: If a package provides extensions to the MIME database by installing .xml files
                   4048: inside ${PREFIX}/share/mime/packages, you need to take some extra steps to
                   4049: ensure that the database is kept consistent with respect to these new files:
                   4050:
                   4051:  1. Include ../../databases/shared-mime-info/mimedb.mk (avoid using the
                   4052:     buildlink3.mk file from this same directory, which is reserved for
                   4053:     inclusion from other buildlink3.mk files). It takes care of rebuilding the
                   4054:     MIME database at installation and deinstallation time, and disallows any
                   4055:     access to it directly from the package.
1.7       wiz      4056:
                   4057:  2. Check the PLIST and remove any entries under the share/mime directory,
1.1       grant    4058:     except for files saved under share/mime/packages. The former are handled
                   4059:     automatically by the update-mime-database program, but the later are
                   4060:     package-dependent and must be removed by the package that installed them in
                   4061:     the first place.
1.7       wiz      4062:
1.1       grant    4063:  3. Remove any share/mime/* directories from the PLIST. They will be handled by
                   4064:     the shared-mime-info package.
1.7       wiz      4065:
1.1       grant    4066: 12.5.17. Packages using intltool
                   4067:
                   4068: If a package uses intltool during its build, include the ../../textproc/
                   4069: intltool/buildlink3.mk file, which forces it to use the intltool package
                   4070: provided by pkgsrc, instead of the one bundled with the distribution file.
                   4071:
                   4072: This tracks intltool's build-time dependencies and uses the latest available
                   4073: version; this way, the package benefits of any bug fixes that may have appeared
                   4074: since it was released.
                   4075:
                   4076: 12.6. Feedback to the author
                   4077:
                   4078: If you have found any bugs in the package you make available, if you had to do
                   4079: special steps to make it run under NetBSD or if you enhanced the software in
                   4080: various other ways, be sure to report these changes back to the original author
                   4081: of the program! With that kind of support, the next release of the program can
                   4082: incorporate these fixes, and people not using the NetBSD packages system can
                   4083: win from your efforts.
                   4084:
                   4085: Support the idea of free software!
                   4086:
                   4087: Chapter 13. Debugging
                   4088:
                   4089: To check out all the gotchas when building a package, here are the steps that I
                   4090: do in order to get a package working. Please note this is basically the same as
                   4091: what was explained in the previous sections, only with some debugging aids.
                   4092:
                   4093:   * Be sure to set PKG_DEVELOPER=1 in /etc/mk.conf
1.7       wiz      4094:
1.1       grant    4095:   * Install pkgtools/url2pkg, create a directory for a new package, change into
                   4096:     it, then run url2pkg:
1.7       wiz      4097:
1.1       grant    4098:     % mkdir /usr/pkgsrc/category/examplepkg
                   4099:     % cd /usr/pkgsrc/category/examplepkg
                   4100:     % url2pkg http://www.example.com/path/to/distfile.tar.gz
1.7       wiz      4101:
1.1       grant    4102:   * Edit the Makefile as requested.
1.7       wiz      4103:
1.1       grant    4104:   * Fill in the DESCR file
1.7       wiz      4105:
1.1       grant    4106:   * Run make configure
1.7       wiz      4107:
1.1       grant    4108:   * Add any dependencies glimpsed from documentation and the configure step to
                   4109:     the package's Makefile.
1.7       wiz      4110:
1.1       grant    4111:   * Make the package compile, doing multiple rounds of
1.7       wiz      4112:
1.1       grant    4113:     % make
                   4114:     % pkgvi ${WRKSRC}/some/file/that/does/not/compile
                   4115:     % mkpatches
                   4116:     % patchdiff
                   4117:     % mv ${WRKDIR}/.newpatches/* patches
                   4118:     % make mps
                   4119:     % make clean
1.7       wiz      4120:
1.1       grant    4121:     Doing as non-root user will ensure that no files are modified that
1.7       wiz      4122:     shouldn't be, especially during the build phase. mkpatches, patchdiff and
1.1       grant    4123:     pkgvi are from the pkgtools/pkgdiff package.
1.7       wiz      4124:
1.1       grant    4125:   * Look at the Makefile, fix if necessary; see Section 7.1, "Makefile".
1.7       wiz      4126:
1.1       grant    4127:   * Generate a PLIST:
1.7       wiz      4128:
1.1       grant    4129:     # make install
                   4130:     # make print-PLIST >PLIST
                   4131:     # make deinstall
                   4132:     # make install
                   4133:     # make deinstall
1.7       wiz      4134:
1.1       grant    4135:     You usually need to be root to do this. Look if there are any files left:
1.7       wiz      4136:
1.1       grant    4137:     # make print-PLIST
1.7       wiz      4138:
1.1       grant    4139:     If this reveals any files that are missing in PLIST, add them.
1.7       wiz      4140:
1.1       grant    4141:   * Now that the PLIST is OK, install the package again and make a binary
                   4142:     package:
1.7       wiz      4143:
1.1       grant    4144:     # make reinstall
                   4145:     # make package
1.7       wiz      4146:
1.1       grant    4147:   * Delete the installed package:
1.7       wiz      4148:
1.1       grant    4149:     # pkg_delete blub
1.7       wiz      4150:
1.1       grant    4151:   * Repeat the above make print-PLIST command, which shouldn't find anything
                   4152:     now:
1.7       wiz      4153:
1.1       grant    4154:     # make print-PLIST
1.7       wiz      4155:
1.1       grant    4156:   * Reinstall the binary package:
1.7       wiz      4157:
1.1       grant    4158:     # pkgadd .../blub.tgz
1.7       wiz      4159:
1.1       grant    4160:   * Play with it. Make sure everything works.
1.7       wiz      4161:
1.1       grant    4162:   * Run pkglint from pkgtools/pkglint, and fix the problems it reports:
1.7       wiz      4163:
1.1       grant    4164:     # pkglint
1.7       wiz      4165:
1.1       grant    4166:   * Submit (or commit, if you have cvs access); see Chapter 14, Submitting and
                   4167:     Committing.
1.7       wiz      4168:
1.1       grant    4169: Chapter 14. Submitting and Committing
                   4170:
                   4171: Table of Contents
                   4172:
                   4173: 14.1. Submitting your packages
                   4174: 14.2. Committing: Importing a package into CVS
1.2       hubertf  4175: 14.3. Updating a package to a newer version
                   4176: 14.4. Moving a package in pkgsrc
1.1       grant    4177:
                   4178: 14.1. Submitting your packages
                   4179:
                   4180: You have to separate between binary and "normal" (source) packages here:
                   4181:
                   4182:   * precompiled binary packages
1.7       wiz      4183:
1.1       grant    4184:     Our policy is that we accept binaries only from pkgsrc developers to
                   4185:     guarantee that the packages don't contain any trojan horses etc. This is
                   4186:     not to piss anyone off but rather to protect our users! You're still free
                   4187:     to put up your home-made binary packages and tell the world where to get
                   4188:     them.
1.7       wiz      4189:
1.1       grant    4190:   * packages
1.7       wiz      4191:
                   4192:     First, check that your package is complete, compiles and runs well; see
1.1       grant    4193:     Chapter 13, Debugging and the rest of this document. Next, generate an
                   4194:     uuencoded gzipped tar(1) archive, preferably with all files in a single
                   4195:     directory. Finally, send-pr with category "pkg", a synopsis which includes
                   4196:     the package name and version number, a short description of your package
                   4197:     (contents of the COMMENT variable or DESCR file are OK) and attach the
                   4198:     archive to your PR.
1.7       wiz      4199:
1.1       grant    4200:     If you want to submit several packages, please send a separate PR for each
                   4201:     one, it's easier for us to track things that way.
1.7       wiz      4202:
1.1       grant    4203:     Alternatively, you can also import new packages into pkgsrc-wip ("pkgsrc
                   4204:     work-in-progress"); see the homepage at http://pkgsrc-wip.sourceforge.net/
                   4205:     for details.
1.7       wiz      4206:
1.1       grant    4207: 14.2. Committing: Importing a package into CVS
                   4208:
                   4209: This section is only of interest for pkgsrc developers with write access to the
                   4210: pkgsrc repository. Please remember that cvs imports files relative to the
                   4211: current working directory, and that the pathname that you give the cvs import
                   4212: command is so that it knows where to place the files in the repository. Newly
                   4213: created packages should be imported with a vendor tag of "TNF" and a release
                   4214: tag of "pkgsrc-base", e.g:
                   4215:
                   4216:   % cd .../pkgsrc/category/pkgname
                   4217:   % cvs import pkgsrc/category/pkgname TNF pkgsrc-base
                   4218:
                   4219: Remember to move the directory from which you imported out of the way, or cvs
                   4220: will complain the next time you "cvs update" your source tree. Also don't
                   4221: forget to add the new package to the category's Makefile.
                   4222:
                   4223: The commit message of the initial import should include part of the DESCR file,
                   4224: so people reading the mailing lists know what the package is/does.
                   4225:
                   4226: Please note all package updates/additions in pkgsrc/doc/CHANGES. It's very
                   4227: important to keep this file up to date and conforming to the existing format,
1.7       wiz      4228: because it will be used by scripts to automatically update pages on
1.1       grant    4229: www.NetBSD.org and other sites. Additionally, check the pkgsrc/doc/TODO file
                   4230: and remove the entry for the package you updated, in case it was mentioned
                   4231: there.
                   4232:
                   4233: For new packages, "cvs import" is preferred to "cvs add" because the former
                   4234: gets everything with a single command, and provides a consistent tag.
                   4235:
1.2       hubertf  4236: 14.3. Updating a package to a newer version
1.1       grant    4237:
                   4238: Please always put a concise, appropriate and relevant summary of the changes
                   4239: between old and new versions into the commit log when updating a package. There
                   4240: are various reasons for this:
                   4241:
                   4242:   * A URL is volatile, and can change over time. It may go away completely or
                   4243:     its information may be overwritten by newer information.
1.7       wiz      4244:
1.1       grant    4245:   * Having the change information between old and new versions in our CVS
                   4246:     repository is very useful for people who use either cvs or anoncvs.
1.7       wiz      4247:
1.1       grant    4248:   * Having the change information between old and new versions in our CVS
                   4249:     repository is very useful for people who read the pkgsrc-changes mailing
                   4250:     list, so that they can make tactical decisions about when to upgrade the
                   4251:     package.
1.7       wiz      4252:
1.1       grant    4253: Please also recognise that, just because a new version of a package has been
                   4254: released, it should not automatically be upgraded in the CVS repository. We
                   4255: prefer to be conservative in the packages that are included in pkgsrc -
                   4256: development or beta packages are not really the best thing for most places in
                   4257: which pkgsrc is used. Please use your judgement about what should go into
                   4258: pkgsrc, and bear in mind that stability is to be preferred above new and
                   4259: possibly untested features.
                   4260:
1.2       hubertf  4261: 14.4. Moving a package in pkgsrc
1.1       grant    4262:
                   4263:  1. Make a copy of the directory somewhere else.
1.7       wiz      4264:
1.1       grant    4265:  2. Remove all CVS dirs.
1.7       wiz      4266:
1.1       grant    4267:     Alternatively to the first two steps you can also do:
1.7       wiz      4268:
1.1       grant    4269:     % cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package
1.7       wiz      4270:
1.1       grant    4271:     and use that for further work.
1.7       wiz      4272:
1.1       grant    4273:  3. Fix CATEGORIES and any DEPENDS paths that just did "../package" instead of
                   4274:     "../../category/package".
1.7       wiz      4275:
1.1       grant    4276:  4. cvs import the modified package in the new place.
1.7       wiz      4277:
1.1       grant    4278:  5. Check if any package depends on it:
1.7       wiz      4279:
1.1       grant    4280:     % cd /usr/pkgsrc
                   4281:     % grep /package */*/Makefile* */*/buildlink*
1.7       wiz      4282:
1.1       grant    4283:  6. Fix paths in packages from step 5 to point to new location.
1.7       wiz      4284:
1.1       grant    4285:  7. cvs rm (-f) the package at the old location.
1.7       wiz      4286:
1.1       grant    4287:  8. Remove from oldcategory/Makefile.
1.7       wiz      4288:
1.1       grant    4289:  9. Add to newcategory/Makefile.
1.7       wiz      4290:
1.1       grant    4291: 10. Commit the changed and removed files:
1.7       wiz      4292:
1.1       grant    4293:     % cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile
1.7       wiz      4294:
1.1       grant    4295:     (and any packages from step 5, of course).
1.7       wiz      4296:
1.1       grant    4297: Appendix A. A simple example package: bison
                   4298:
                   4299: Table of Contents
                   4300:
                   4301: A.1. files
1.7       wiz      4302:
1.1       grant    4303:     A.1.1. Makefile
                   4304:     A.1.2. DESCR
                   4305:     A.1.3. PLIST
                   4306:     A.1.4. Checking a package with pkglint
1.7       wiz      4307:
1.1       grant    4308: A.2. Steps for building, installing, packaging
                   4309:
                   4310: We checked to find a piece of software that wasn't in the packages collection,
1.7       wiz      4311: and picked GNU bison. Quite why someone would want to have bison when Berkeley
1.1       grant    4312: yacc is already present in the tree is beyond us, but it's useful for the
                   4313: purposes of this exercise.
                   4314:
                   4315: A.1. files
                   4316:
                   4317: A.1.1. Makefile
                   4318:
1.9     ! dillo    4319: # $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant    4320: #
                   4321:
                   4322: DISTNAME=       bison-1.25
                   4323: CATEGORIES=     devel
                   4324: MASTER_SITES=   ${MASTER_SITE_GNU}
                   4325:
                   4326: MAINTAINER=     thorpej@NetBSD.org
                   4327: HOMEPAGE=       http://www.gnu.org/software/bison/bison.html
                   4328: COMMENT=        GNU yacc clone
                   4329:
                   4330: GNU_CONFIGURE=  yes
                   4331: INFO_FILES=     bison.info
                   4332:
                   4333: .include "../../mk/bsd.pkg.mk"
                   4334:
                   4335: A.1.2. DESCR
                   4336:
                   4337: GNU version of yacc.  Can make re-entrant parsers, and numerous other
                   4338: improvements.  Why you would want this when Berkeley yacc(1) is part
                   4339: of the NetBSD source tree is beyond me.
                   4340:
                   4341: A.1.3. PLIST
                   4342:
1.9     ! dillo    4343: @comment $NetBSD: pkgsrc.txt,v 1.8 2004/12/01 09:52:59 wiz Exp $
1.1       grant    4344: bin/bison
                   4345: man/man1/bison.1.gz
                   4346: info/bison.info
                   4347: info/bison.info-1
                   4348: info/bison.info-2
                   4349: info/bison.info-3
                   4350: info/bison.info-4
                   4351: info/bison.info-5
                   4352: share/bison.simple
                   4353: share/bison.hairy
                   4354:
                   4355: A.1.4. Checking a package with pkglint
                   4356:
                   4357: The NetBSD package system comes with pkgtools/pkglint which helps to check the
                   4358: contents of these files. After installation it is quite easy to use, just
                   4359: change to the directory of the package you wish to examine and execute pkglint:
                   4360:
                   4361: $ pkglint
                   4362: OK: checking ./DESCR.
                   4363: OK: checking Makefile.
                   4364: OK: checking distinfo.
                   4365: OK: checking patches/patch-aa.
                   4366: looks fine.
                   4367:
                   4368: Depending on the supplied command line arguments (see pkglint(1)) more verbose
                   4369: checks will be performed. Use e.g. pkglint -v for a very verbose check.
                   4370:
                   4371: A.2. Steps for building, installing, packaging
                   4372:
                   4373: Create the directory where the package lives, plus any auxiliary directories:
                   4374:
                   4375: # cd /usr/pkgsrc/lang
                   4376: # mkdir bison
                   4377: # cd bison
                   4378: # mkdir patches
                   4379:
                   4380: Create Makefile, DESCR and PLIST (see Chapter 7, Package components - files,
                   4381: directories and contents) then continue with fetching the distfile:
                   4382:
                   4383: # make fetch
                   4384: >> bison-1.25.tar.gz doesn't seem to exist on this system.
                   4385: >> Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//.
                   4386: Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
                   4387: ftp: Error retrieving file: 500 Internal error
                   4388:
                   4389: >> Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//.
                   4390: Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
                   4391: ftp: Error retrieving file: 500 Internal error
                   4392:
                   4393: >> Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//.
                   4394: Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
                   4395: Successfully retrieved file.
                   4396:
                   4397: Generate the checksum of the distfile into distinfo:
                   4398:
                   4399: # make makesum
                   4400:
                   4401: Now compile:
                   4402:
                   4403: # make
                   4404: >> Checksum OK for bison-1.25.tar.gz.
                   4405: ===>  Extracting for bison-1.25
                   4406: ===>  Patching for bison-1.25
                   4407: ===>   Ignoring empty patch directory
                   4408: ===>  Configuring for bison-1.25
                   4409: creating cache ./config.cache
                   4410: checking for gcc... cc
                   4411: checking whether we are using GNU C... yes
                   4412: checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin
                   4413: checking how to run the C preprocessor... cc -E
                   4414: checking for minix/config.h... no
                   4415: checking for POSIXized ISC... no
                   4416: checking whether cross-compiling... no
                   4417: checking for ANSI C header files... yes
                   4418: checking for string.h... yes
                   4419: checking for stdlib.h... yes
                   4420: checking for memory.h... yes
                   4421: checking for working const... yes
                   4422: checking for working alloca.h... no
                   4423: checking for alloca... yes
                   4424: checking for strerror... yes
                   4425: updating cache ./config.cache
                   4426: creating ./config.status
                   4427: creating Makefile
                   4428: ===>  Building for bison-1.25
                   4429: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g LR0.c
                   4430: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g allocate.c
                   4431: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g closure.c
                   4432: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g conflicts.c
                   4433: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g derives.c
1.7       wiz      4434: cc -c -DXPFILE=\"/usr/pkg/share/bison.simple\"  -DXPFILE1=\"/usr/pkg/share/bison.hairy\" -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1  -g  ./files.c
1.1       grant    4435: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getargs.c
                   4436: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g gram.c
                   4437: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lalr.c
                   4438: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lex.c
                   4439: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g main.c
                   4440: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g nullable.c
                   4441: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g output.c
                   4442: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g print.c
                   4443: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reader.c
                   4444: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reduce.c
                   4445: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g symtab.c
                   4446: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g warshall.c
                   4447: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g version.c
                   4448: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt.c
                   4449: cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt1.c
                   4450: cc  -g -o bison LR0.o allocate.o closure.o conflicts.o derives.o files.o         getargs.o gram.o lalr.o lex.o                                   main.o nullable.o output.o print.o reader.o reduce.o symtab.o   warshall.o version.o getopt.o getopt1.o
                   4451: ./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp()
                   4452: rm -f bison.s1
                   4453: sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" < ./bison.simple > bison.s1
                   4454:
                   4455: Everything seems OK, so install the files:
                   4456:
                   4457: # make install
                   4458: >> Checksum OK for bison-1.25.tar.gz.
                   4459: ===>  Installing for bison-1.25
                   4460: sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share  /usr/pkg/info /usr/pkg/man/man1
                   4461: rm -f /usr/pkg/bin/bison
                   4462: cd /usr/pkg/share; rm -f bison.simple bison.hairy
                   4463: rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info*
                   4464: install -c  -o bin -g bin -m 555 bison /usr/pkg/bin/bison
                   4465: /usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple
                   4466: /usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy
                   4467: cd .; for f in bison.info*;  do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done
                   4468: /usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1
                   4469: ===>  Registering installation for bison-1.25
                   4470:
                   4471: You can now use bison, and also - if you decide so - remove it with pkg_delete
                   4472: bison. Should you decide that you want a binary package, do this now:
                   4473:
                   4474: # make package
                   4475: >> Checksum OK for bison-1.25.tar.gz.
                   4476: ===>  Building package for bison-1.25
                   4477: Creating package bison-1.25.tgz
                   4478: Registering depends:.
                   4479: Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
                   4480:
                   4481: Now that you don't need the source and object files any more, clean up:
                   4482:
                   4483: # make clean
                   4484: ===>  Cleaning for bison-1.25
                   4485:
                   4486: Appendix B. Build logs
                   4487:
                   4488: Table of Contents
                   4489:
                   4490: B.1. Building figlet
                   4491: B.2. Packaging figlet
                   4492:
                   4493: B.1. Building figlet
                   4494:
                   4495: # make
                   4496: ===> Checking for vulnerabilities in figlet-2.2.1nb2
                   4497: => figlet221.tar.gz doesn't seem to exist on this system.
                   4498: => Attempting to fetch figlet221.tar.gz from ftp://ftp.figlet.org/pub/figlet/program/unix/.
                   4499: => [172219 bytes]
                   4500: Connected to ftp.plig.net.
                   4501: 220 ftp.plig.org NcFTPd Server (licensed copy) ready.
                   4502: 331 Guest login ok, send your complete e-mail address as password.
                   4503: 230-You are user #5 of 500 simultaneous users allowed.
                   4504: 230-
1.7       wiz      4505: 230-  ___ _             _ _
                   4506: 230- |  _| |_ ___   ___| |_|___   ___ ___ ___
1.1       grant    4507: 230- |  _|  _| . |_| . | | | . |_| . |  _| . |
                   4508: 230- |_| |_| |  _|_|  _|_|_|_  |_|___|_| |_  |
                   4509: 230-         |_|   |_|     |___|         |___|
                   4510: 230-
                   4511: 230-** Welcome to ftp.plig.org **
                   4512: 230-
                   4513: 230-Please note that all transfers from this FTP site are logged. If you
                   4514: 230-do not like this, please disconnect now.
                   4515: 230-
                   4516: 230-This arhive is available via
                   4517: 230-
                   4518: 230-HTTP:  http://ftp.plig.org/
                   4519: 230-FTP:   ftp://ftp.plig.org/     (max 500 connections)
                   4520: 230-RSYNC: rsync://ftp.plig.org/   (max  30 connections)
                   4521: 230-
                   4522: 230-Please email comments, bug reports and requests for packages to be
1.7       wiz      4523: 230-mirrored to ftp-admin@plig.org.
1.1       grant    4524: 230-
                   4525: 230-
                   4526: 230 Logged in anonymously.
                   4527: Remote system type is UNIX.
                   4528: Using binary mode to transfer files.
                   4529: 200 Type okay.
                   4530: 250 "/pub" is new cwd.
                   4531: 250-"/pub/figlet" is new cwd.
                   4532: 250-
                   4533: 250-Welcome to the figlet archive at ftp.figlet.org
1.7       wiz      4534: 250-
1.1       grant    4535: 250-    ftp://ftp.figlet.org/pub/figlet/
                   4536: 250-
                   4537: 250-The official FIGlet web page is:
                   4538: 250-    http://www.figlet.org/
                   4539: 250-
                   4540: 250-If you have questions, please mailto:info@figlet.org. If you want to
                   4541: 250-contribute a font or something else, you can email us.
1.7       wiz      4542: 250
1.1       grant    4543: 250 "/pub/figlet/program" is new cwd.
                   4544: 250 "/pub/figlet/program/unix" is new cwd.
                   4545: local: figlet221.tar.gz remote: figlet221.tar.gz
                   4546: 502 Unimplemented command.
                   4547: 227 Entering Passive Mode (195,40,6,41,246,104)
                   4548: 150 Data connection accepted from 84.128.86.72:65131; transfer starting for figlet221.tar.gz (172219 bytes).
                   4549: 38% |**************                       | 65800      64.16 KB/s    00:01 ETA
                   4550: 226 Transfer completed.
                   4551: 172219 bytes received in 00:02 (75.99 KB/s)
                   4552: 221 Goodbye.
                   4553: => Checksum OK for figlet221.tar.gz.
                   4554: ===> Extracting for figlet-2.2.1nb2
                   4555: ===> Required installed package ccache-[0-9]*: ccache-2.3nb1 found
                   4556: ===> Patching for figlet-2.2.1nb2
                   4557: ===> Applying pkgsrc patches for figlet-2.2.1nb2
                   4558: ===> Overriding tools for figlet-2.2.1nb2
                   4559: ===> Creating toolchain wrappers for figlet-2.2.1nb2
                   4560: ===> Configuring for figlet-2.2.1nb2
                   4561: ===> Building for figlet-2.2.1nb2
                   4562: gcc -O2 -DDEFAULTFONTDIR=\"/usr/pkg/share/figlet\"  -DDEFAULTFONTFILE=\"standard.flf\"  figlet.c zipio.c crc.c inflate.c -o figlet
                   4563: chmod a+x figlet
                   4564: gcc -O2 -o chkfont chkfont.c
                   4565: => Unwrapping files-to-be-installed.
                   4566: #
                   4567: # make install
                   4568: ===> Checking for vulnerabilities in figlet-2.2.1nb2
                   4569: ===> Installing for figlet-2.2.1nb2
                   4570: install -d -o root -g wheel -m 755 /usr/pkg/bin
                   4571: install -d -o root -g wheel -m 755 /usr/pkg/man/man6
                   4572: mkdir -p /usr/pkg/share/figlet
                   4573: cp figlet /usr/pkg/bin
                   4574: cp chkfont /usr/pkg/bin
                   4575: chmod 555 figlist showfigfonts
                   4576: cp figlist /usr/pkg/bin
                   4577: cp showfigfonts /usr/pkg/bin
                   4578: cp fonts/*.flf /usr/pkg/share/figlet
                   4579: cp fonts/*.flc /usr/pkg/share/figlet
                   4580: cp figlet.6 /usr/pkg/man/man6
                   4581: ===> Registering installation for figlet-2.2.1nb2
                   4582: #
                   4583:
                   4584: B.2. Packaging figlet
                   4585:
                   4586: # make package
                   4587: ===> Checking for vulnerabilities in figlet-2.2.1nb2
                   4588: ===> Packaging figlet-2.2.1nb2
                   4589: ===> Building binary package for figlet-2.2.1nb2
                   4590: Creating package /home/cvs/pkgsrc/packages/i386/All/figlet-2.2.1nb2.tgz
                   4591: Using SrcDir value of /usr/pkg
1.7       wiz      4592: Registering depends:.
1.1       grant    4593: #
                   4594:
                   4595: Appendix C. Layout of the FTP server's package archive
                   4596:
                   4597: Layout for precompiled binary packages on ftp.NetBSD.org:
                   4598:
                   4599: /pub/NetBSD/packages/
                   4600:                 distfiles/
                   4601:
                   4602:                 # Unpacked pkgsrc trees
                   4603:                 pkgsrc-current -> /pub/NetBSD/NetBSD-current/pkgsrc
                   4604:                 pkgsrc-2003Q4 -> N/A
                   4605:                 pkgsrc-2004Q1/pkgsrc
                   4606:
                   4607:                 # pkgsrc archives
                   4608:                 pkgsrc-current.tar.gz -> ../NetBSD-current/tar_files/pkgsrc.tar.gz
                   4609:                 pkgsrc-2003Q4.tar.gz -> N/A
                   4610:                 pkgsrc-2004Q1.tar.gz -> N/A
                   4611:
                   4612:                 # Per pkgsrc-release/OS-release/arch package archives
                   4613:                 pkgsrc-2003Q4/
                   4614:                         NetBSD-1.6.2/
                   4615:                                 i386/
                   4616:                                         All/
                   4617:                                         archivers/
                   4618:                                                 foo -> ../All/foo
                   4619:                                         ...
                   4620:                 pkgsrc-2004Q1/
                   4621:                         NetBSD-1.6.2/
                   4622:                                 i386/
                   4623:                                         All/
                   4624:                                         ...
                   4625:                         NetBSD-2.0/
                   4626:                                 i386/
                   4627:                                         All/
                   4628:                                         ...
                   4629:                         SunOS-5.9/
                   4630:                                 sparc/
                   4631:                                         All/
                   4632:                                         ...
                   4633:                                 x86/
                   4634:                                         All/
                   4635:                                         ...
                   4636:
                   4637:                 # Per os-release package archive convenience links
                   4638:                 NetBSD-1.6.2 -> 1.6.2
                   4639:                 1.6.2/
                   4640:                         i386 -> ../pkgsrc-2004Q1/NetBSD-1.6.2/i386
                   4641:                         m68k/
                   4642:                                 All/
                   4643:                                 archivers/
                   4644:                                         foo -> ../All/foo
                   4645:                                 ...
                   4646:                         amiga -> m68k
                   4647:                         atari -> m68k
                   4648:                         ...
                   4649:
                   4650:                 2.0 -> NetBSD-2.0       # backward compat, historic
                   4651:                 NetBSD-2.0/
                   4652:                         i386 -> ../pkgsrc-2004Q1/NetBSD-2.0/i386
                   4653:                 SunOS-5.9/
                   4654:                         sparc -> ../pkgsrc-2004Q1/SunOS-5.9/sparc
                   4655:                         x86 -> ../pkgsrc-2004Q1/SunOS-5.9/x86
1.7       wiz      4656:
1.1       grant    4657:
                   4658: To create:
                   4659:
                   4660:  1. Run bulk build, see Section 5.3, "Doing a bulk build of all packages"
1.7       wiz      4661:
1.1       grant    4662:  2. Upload /usr/pkgsrc/packages to
1.7       wiz      4663:
1.1       grant    4664:         ftp://ftp.NetBSD.org/pub/NetBSD/packages/\
                   4665:             pkgsrc-2004Q3/\                         # pkgsrc-branch
                   4666:             `uname -s`-`uname -r`/                  # OS & version
                   4667:             `uname -p`                              # architecture
1.7       wiz      4668:
                   4669:
1.2       hubertf  4670:  3. If necessary, create a symlink ln -s `uname -m` `uname -p` (amiga -> m68k,
                   4671:     ...)
1.7       wiz      4672:
1.2       hubertf  4673: Appendix D. Editing guidelines for the pkgsrc guide
                   4674:
                   4675: Table of Contents
                   4676:
                   4677: D.1. Targets
                   4678: D.2. Procedure
1.1       grant    4679:
1.2       hubertf  4680: This section contains information on editing the pkgsrc guide itself.
1.1       grant    4681:
1.2       hubertf  4682: D.1. Targets
1.1       grant    4683:
1.2       hubertf  4684: The pkgsrc guide's source code is stored in pkgsrc/doc/guide/files, and several
                   4685: files are created from it:
                   4686:
                   4687:   * pkgsrc/doc/pkgsrc.txt, which replaces pkgsrc/Packages.txt
1.7       wiz      4688:
1.2       hubertf  4689:   * pkgsrc/doc/pkgsrc.html
1.7       wiz      4690:
1.2       hubertf  4691:   * http://www.NetBSD.org/Documentation/pkgsrc/: the documentation on the
                   4692:     NetBSD website will be built from pkgsrc and kept up to date on the web
                   4693:     server itself. This means you must make sure that your changes haven't
                   4694:     broken the build!
1.7       wiz      4695:
1.6       hubertf  4696:   * http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf: PDF version of the
                   4697:     pkgsrc guide.
1.7       wiz      4698:
1.6       hubertf  4699:   * http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps: PostScript version of
                   4700:     the pkgsrc guide.
1.7       wiz      4701:
1.2       hubertf  4702: D.2. Procedure
                   4703:
                   4704: The procedure to edit the pkgsrc guide is:
                   4705:
1.6       hubertf  4706:   * Make sure you have the packages needed to re-generate the pkgsrc guide (and
                   4707:     other XML-based NetBSD documentation) installed. These are "pkgsrc-doc" for
                   4708:     creating the ASCII- and HTML-version, and "pkgsrc-doc-print"for the
                   4709:     PostScript- and PDF version. You will need both packages installed, to make
                   4710:     sure documentation is consistent across all formats. The packages can be
                   4711:     found in pkgsrc/meta-pkgs/netbsd-doc and pkgsrc/meta-pkgs/netbsd-doc-print.
1.7       wiz      4712:
1.6       hubertf  4713:   * Edit the XML file(s) in pkgsrc/doc/guide/files.
1.7       wiz      4714:
1.6       hubertf  4715:   * Run make extract && make do-lint in pkgsrc/doc/guide to check the XML
                   4716:     syntax, and fix it if needed.
1.7       wiz      4717:
1.6       hubertf  4718:   * Run make in pkgsrc/doc/guide to build the HTML and ASCII version.
1.7       wiz      4719:
1.4       hubertf  4720:   * If all is well, run make install-doc to put the generated files into pkgsrc
                   4721:     /doc.
1.7       wiz      4722:
1.2       hubertf  4723:   * cvs commit pkgsrc/doc/guide/files
1.7       wiz      4724:
1.6       hubertf  4725:   * cvs commit -m re-generate pkgsrc/doc/pkgsrc.{html,txt}
1.7       wiz      4726:
1.4       hubertf  4727:   * Until the webserver on www.NetBSD.org is really updated automatically to
                   4728:     pick up changes to the pkgsrc guide automatically, also run make
1.6       hubertf  4729:     install-htdoc HTDOCSDIR=../../../htdocs (or similar, adjust HTDOCSDIR!).
1.7       wiz      4730:
1.4       hubertf  4731:   * cvs commit htdocs/Documentation/pkgsrc
1.7       wiz      4732:

CVSweb <webmaster@jp.NetBSD.org>