1 # $NetBSD: Packages.txt,v 1.358 2004/09/15 20:18:26 minskim Exp $
2 ###########################################################################
4 ==========================
7 ==========================
9 Hubert Feyrer, Alistair Crooks
15 Run this command to produce a table of contents:
16 sed '/^.====/{g;p;};h;d' Packages.txt
22 There is a lot of software freely available for Unix based systems, which
23 usually runs on NetBSD, too, sometimes with some modifications. The NetBSD
24 packages collection incorporates any such changes necessary to make that
25 software run on NetBSD, and makes the installation (and re-installation) of
26 the software package easy by means of a single command.
28 The NetBSD package system is used to enable such freely available
29 third-party software to be built easily on NetBSD hosts. Once the software
30 has been built, it is manipulated with the pkg_* tools so that installation
31 and de-installation, printing of an inventory of all installed packages and
32 retrieval of one-line comments or more verbose descriptions are all simple.
34 Both the NetBSD packages collection and the NetBSD package system are
41 This document is divided into two parts. The first, "User's Guide",
42 describes how one can use one of the packages in the Package
43 Collection, either by installing a precompiled binary package, or
44 by building one's copy using the NetBSD package system. The
45 second part, "Package Constructor's Guide", explains how to prepare
46 a package so it can be easily built by other NetBSD users without
47 knowing about the package's building details.
53 There has been a lot of talk about "ports", "packages", etc. so far. Here
54 is a description of all the terminology used within this document:
57 A set of files and building instructions that describe what's necessary
58 to build a certain piece of software using the NetBSD package
59 system. Packages are traditionally stored under /usr/pkgsrc.
61 * The NetBSD package system:
62 This is the part of the NetBSD operating system handling building
63 (compiling), installing, and removing of packages.
66 This term describes the file or files that are provided by the author
67 of the piece of freely available software to distribute his work. All
68 the changes necessary to build on NetBSD are reflected in the
69 corresponding package. Usually the distfile is in the form of a
70 compressed tar-archive, but other types are possible, too. Distfiles
71 are stored below /usr/pkgsrc/distfiles.
74 This is the term used by FreeBSD people for what we call a package.
75 In NetBSD terminology, "port" refers to a different architecture.
77 * Precompiled (binary) package:
78 A set of binaries built by the NetBSD package system from a distfile
79 using the NetBSD package system and stuffed together in a single .tgz
80 file so it can be installed on machines of the same machine architecture
81 without the need to recompile. Packages are generated in
82 /usr/pkgsrc/packages by the NetBSD package system; there is also an
83 archive on ftp.netbsd.org.
85 Sometimes, this is referred to by the term "package" too,
86 especially in the context of precompiled packages.
89 The piece of software to be installed which will be constructed from
90 all the files in the Distfile by the actions defined in the
91 corresponding package.
94 Some files in a package contain RCS IDs to reflect which version of
95 that file this is (inserted automatically by cvs). These IDs are used
96 in several examples within this document, but as this document itself
97 is managed by CVS, it can't list the RCS IDs in plaintext. Instead, the
98 $s are written as <$>, resulting in <$>NetBSD<$> and <$>Id<$>.
104 Right now this document is written in plain ASCII text, and there's not
105 much typography applied here. It's being moved to DocBook.
107 When giving examples for commands, shell prompts are used to show if the
108 command should/can be issued as root, or if "normal" user privileges are
109 sufficient. We use a "#" for root's shell prompt, and a "%" for users'
110 shell prompt, assuming they use the C-shell or tcsh.
117 1 Installing a precompiled binary package
118 =========================================
120 This section describes how to find, retrieve and install a precompiled
121 binary package that someone else already prepared for your type of machine.
127 Precompiled packages are stored on ftp.netbsd.org and its mirrors in the
128 directory /pub/NetBSD/packages for anon FTP access. Please pick the right
129 subdirectory there as indicated by "uname -p". In that directory, there
130 is a subdirectory for each category plus a subdirectory "All" which includes
131 the actual binaries in .tgz-files. The category subdirectories use symbolic
132 links to those files. (This is the same directory layout as in
133 /usr/pkgsrc/packages).
135 This same directory layout applies for CDROM distributions, only that the
136 directory may be rooted somewhere else, probably somewhere below /cdrom.
137 Please consult your CDROM's documentation for the exact location!
143 If you have the files on a CDROM or downloaded them to your hard disk, you
144 can install them with the following command (be sure to su to root first):
146 # pkg_add /path/to/package.tgz
148 If you have FTP access and you don't want to download the packages via FTP
149 prior to installation, you can do this automatically by giving pkg_add an
152 # pkg_add ftp://ftp.netbsd.org/pub/NetBSD/packages/<OS Ver>/<arch>/All/package.tgz
154 If there is any doubt, the uname utility can be used to determine the
155 <OS Ver>, and <arch> by running "uname -rp".
157 Also note that any prerequisite packages needed to run the package in
158 question will be installed, too, assuming they are present where you install
161 After you've installed packages, be sure to have /usr/pkg/bin in your $PATH
162 so you can actually start the just installed program.
165 1.3 A word of warning
166 =====================
168 Please pay very careful attention to the warnings expressed in that manual
169 page about the inherent dangers of installing binary packages which you did
170 not create yourself, and the security holes that can be introduced onto
171 your system by indiscriminate adding of such files.
174 2 Installing by Building
175 ========================
177 This assumes that the package is already part of the NetBSD package system.
178 If it is not, then you are advised to read part II of this document,
179 "Package Constructor's Guide".
185 To build packages from source on a NetBSD system the "comp" and the "text"
186 distribution sets must be installed. If you want to build X11 related
187 packages the "xbase" and "xcomp" distribution sets are required, too.
190 2.2 Where to get pkgsrc
191 =======================
193 There are three ways to get pkgsrc. Either as a tar file, via SUP, or
194 via CVS. All three ways are described here.
196 To get the package source going, you need to get the pkgsrc.tar.gz file
197 from ftp://ftp.netbsd.org/pub/NetBSD-current/tar_files/pkgsrc.tar.gz and
200 As an alternative, you can get pkgsrc via the Software Update Protocol,
201 SUP. To do so, make sure your supfile has a line saying "release=pkgsrc" in
202 it, see the examples in /usr/share/examples/supfiles, and that the
203 directory /usr/pkgsrc does exist. Then, simply start "sup -v
204 /path/to/your/supfile".
206 To get pkgsrc via CVS, make sure you have cvs installed. If not present on
207 your system, it can be found as precompiled binary on ftp.netbsd.org.
208 To do an initial (full) checkout of pkgsrc, do the following steps:
210 % setenv CVSROOT anoncvs@anoncvs.netbsd.org:/cvsroot
213 % cvs checkout -P pkgsrc
215 This will create the "pkgsrc" directory in your /usr, and all the
216 package source will be stored under /usr/pkgsrc. To update pkgsrc
217 after the initial checkout, make sure you have CVS_RSH set as above,
223 Please also note that it is possible to have multiple copies of the
224 pkgsrc hierarchy in use at any one time - all work is done relatively
225 within the pkgsrc tree.
228 2.3 Fetching distfiles
229 ======================
231 There is one gotcha: The distribution file (i.e. the unmodified source)
232 must exist on your system for the packages system to be able to build it.
233 If it does not, then ftp(1) is used to fetch the distribution files
236 You can overwrite some of the major distribution sites to fit to sites
237 that are close to your own. Have a look at
238 pkgsrc/mk/bsd.pkg.defaults.mk to find some examples - in particular,
239 look for the MASTER_SORT, MASTER_SORT_REGEX and INET_COUNTRY
240 definitions. This may save some of your bandwidth and time.
242 You can change these settings either in your shell's environment, or,
243 if you want to keep the settings, by editing the /etc/mk.conf file,
244 and adding the definitions there.
246 If you don't have a permanent Internet connection and you want to know
247 which files to download, "make fetch-list" will tell you what you'll need.
248 Put these distfiles into /usr/pkgsrc/distfiles.
251 2.4 How to build and install
252 ============================
254 Assuming that the distfile has been fetched (see previous section), become
255 root and change into the relevant directory. Then you can type
259 at the shell prompt to build the various components of the package, and
263 at the shell prompt to install the various components into the correct
264 places on your system.
266 Taking the top system utility as an example, we can install it on our
267 system by building as shown in appendix A.1.
269 The program is installed under the default root of the packages tree -
270 /usr/pkg. Should this not conform to your tastes, simply set the LOCALBASE
271 variable in your environment, and it will use that value as the root of
272 your packages tree. So, to use /usr/local, set
276 in your environment. Please note that you should use a root which is
277 dedicated to packages and not shared with other programs (ie, do not try
278 and use LOCALBASE=/usr). Also, you should not try to add any of your
279 own files or directories (such as, for example, src, obj, or pkgsrc) below
280 the LOCALBASE tree. This is to prevent possible conflicts between programs
281 and other files installed by the package system and whatever else may have
282 been installed there.
284 There is, of course, one exception to this - X11 packages are traditionally
285 installed in the X11 tree. The definition used to identify the root of the
286 X11 tree is the X11BASE definition.
288 It is possible to install X11 packages in the LOCALBASE tree, for
289 which you must install the xpkgwedge package
290 (pkgsrc/pkgtools/xpkgwedge) - see section 7.1 for further details.
292 Some packages look in /etc/mk.conf to alter some configuration options
293 at build time. Have a look at pkgsrc/mk/bsd.pkg.defaults.mk to
294 get an overview of what will be set there by default. Environment
295 variables such as LOCALBASE, and X11BASE can be set in /etc/mk.conf to
296 save having to remember to set them each time you want to use pkgsrc.
298 Occasionally, people want to "look under the covers" to see what is
299 going on when a package is building or being installed. This may be
300 for debugging purposes, or out of simple curiosity. A number of utility
301 values have been added to help with this.
303 (1) If you invoke the make(1) command with PKG_DEBUG_LEVEL=2, then a
304 huge amount of information will be displayed. As a worked example,
306 make patch PKG_DEBUG_LEVEL=2
308 will show all the commands that are invoked, up to and including the
311 (2) If you want to know the value of a certain make(1) definition, then
312 the VARNAME definition should be used, in conjunction with the show-var
315 make show-var VARNAME=DISTFILES
317 will show the expansion of the make(1) variable "DISTFILES".
319 If you want to de-install and re-install a binary package that you've
320 created (see next section), that you put into pkgsrc/packages manually or
321 that's located on a remote FTP server, you can use the the "bin-install"
322 target. This target will install a binary package - if available - via
323 pkg_add, and do a "make package" else. The list of remote FTP sites
324 searched is kept in the variable BINPKG_SITE, which defaults to
325 ftp.netbsd.org. Any flags that should be added to pkg_add(8) can be put
326 into BIN_INSTALL_FLAGS. See pkgsrc/mk/bsd.pkg.defaults.mk for more details.
328 A final word of warning: If you setup a system that has a non-standard
329 setting for LOCALBASE (or X11BASE, for that matter), be sure to set that
330 before any packages are installed, as you can not use several directories
331 for the same purpose. Doing so will result in pkgsrc not being able to
332 properly detect your installed packages, and fail miserably. Note also that
333 precompiled binary packages are usually built with the default LOCALBASE of
334 /usr/pkg, and that you should *not* install any if you use a non-standard
338 2.5 Selecting the compiler
339 ==========================
341 By default, pkgsrc will use GCC to build packages. This may be
342 overridden by setting the following variables in /etc/mk.conf:
345 This is a list of values specifying the chain of compilers to invoke
346 when building packages. Valid values are:
348 distcc distributed C/C++ (chainable)
349 ccache compiler cache (chainable)
351 mipspro Silicon Graphics, Inc. MIPSpro (n32/n64)
352 mipspro-ucode Silicon Graphics, Inc. MIPSpro (o32)
353 sunpro Sun Microsystems, Inc. WorkShip/Forte/Sun
356 The default is "gcc". You can use ccache and/or distcc with an
357 appropriate PKGSRC_COMPILER setting, e.g. "ccache gcc". This variable
358 should always be terminated with a value for a real compiler.
361 This specifies the minimum version of GCC to use when building
362 packages. If the system GCC doesn't satisfy this requirement, then
363 pkgsrc will build and install one of the GCC packages to use instead.
366 3 Making precompiled packages
367 =============================
370 3.1 Packaging a single package
371 ==============================
373 Once you have built and installed the package as mentioned above, you can
374 build it into a "binary package" - you might want to do this so that you
375 can use the binaries you have just built on another NetBSD system, or to
376 provide a simple means for others to use your binary package instead of
377 wasting CPU time - this is done by changing to the appropriate directory in
378 the pkgsrc tree, and typing the command
382 at the shell prompt. This will build and install your package (if not
383 already done), and then construct a binary package out of the results so
384 that you can use the pkg_* tools to manipulate this. The binary package is
385 stored under /usr/pkgsrc/packages, it's in the form of a gzipped file at
386 the present time. See appendix A.2 for a continuation of the above top
389 Please see the "submitting" section later in this document on how to submit
390 such a binary package.
393 3.2 Doing a bulk build of all packages
394 ======================================
396 If you want to get a full set of precompiled binary packages, this section
397 describes how to get them. Beware that the bulk build will remove all
398 currently installed packages from your system! Having a FTP server
399 configured either on the machine doing the bulk builds or on a nearby NFS
400 server can help to make the packages available to everyone. See ftpd(8) for
401 more information. If you use a remote NFS server's storage, be sure to not
402 actually compile on NFS storage, as this slows things down a lot.
411 You may want to set things in /etc/mk.conf. Look at
412 pkgsrc/mk/bsd.pkg.defaults.mk for details of the default settings.
413 You will want to make sure that ACCEPTABLE_LICENSES meet your local
416 PACKAGES?= ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
417 WRKOBJDIR?= /usr/tmp/pkgsrc # build here instead of in pkgsrc
419 BSDXSRCDIR= /usr/xsrc # for x11/xservers
420 OBJHOSTNAME?= yes # use work.`hostname`
421 FAILOVER_FETCH= yes # insist on the correct checksum
425 Other packages which must be installed during the bulk build to modify the
426 build behaviour may be added to the BULK_PREREQ variable. Note that currently
427 the only package for which BULK_PREREQ makes sense is xpkgwedge.
433 In pkgsrc/mk/bulk, copy ``build.conf-example'' to ``build.conf'' and
434 edit it, following the comments in that file. This is the config
435 file that determines where log files are generated after the build,
436 where to mail the build report, where your pkgsrc is located and
437 which user to su(8) to to do a 'cvs update'.
439 3.2.1.3 pre-build.local
440 =======================
442 It is possible to configure the bulk build to perform certain site
443 specific tasks at the end of the pre-build stage. If the file
444 ``pre-build.local'' exists in pkgsrc/mk/bulk it will be executed
445 (as a sh(1) script) at the end of the usual pre-build stage. An
446 example use of pre-build.local is to have the line:
448 # echo "I do not have enough disk space to build this pig." \
449 > games/crafty-book-enormous/$BROKENF
451 to prevent the system from trying to build a particular package
452 which requires nearly 3 Gb of disk space.
454 3.2.2 Other environmental considerations
455 ========================================
457 As /usr/pkg will be completely deleted at the start of bulk builds,
458 make sure your login shell is placed somewhere else. Either drop it into
459 /usr/local/bin (and adjust your login shell in the password file), or
460 (re-)install it via pkg_add from /etc/rc.local, so you can login after a
461 reboot (remember that your current process won't die if the package is
462 removed, you just can't start any new instances of the shell any more).
463 Also, if you use a OS version below 1.5 or you still want to use the
464 pkgsrc version of ssh for some reason, be sure to install ssh before
465 starting it from rc.local:
467 ( cd /usr/pkgsrc/security/ssh ; make bulk-install )
468 if [ -f /usr/pkg/etc/rc.d/sshd ]; then
469 /usr/pkg/etc/rc.d/sshd
472 Not doing so will result in you being not able to log in via ssh
473 after the bulk build is finished or if the machine gets rebooted
474 or crashes. You have been warned! :)
480 Make sure you don't need any of the packages still installed.
481 BEWARE: During the bulk build, ALL packages will be removed!!!
482 Be sure to remove all other things that might interfere with builds, like
483 some libs installed in /usr/local, etc. then become root and type:
488 If for some reason your last build didn't complete (power failure,
489 system panic, ...), you can continue it by running:
491 # sh mk/bulk/build restart
493 At the end of the bulk run, you will get a summary via mail, and find
494 build logs in the directory specified by "FTP" in the "build.conf"
501 The bulk builds consist of three steps:
503 1. pre-build: The script updates your pkgsrc via (anon)cvs, then cleans
504 out any broken distfiles, and removes all packages installed.
506 2. the bulk build: This is basically 'make bulk-package' with an optimised
507 order in which packages will be built. Packages that don't require
508 other packages will be built first, and packages with many depends
511 3. post-build: Generates a report that's placed in the directory specified
512 in the build.conf file named ``broken.html'', a short version of
513 that report will also be mailed to the build's admin.
515 During the build, a list of broken packages will be compiled in
516 /usr/pkgsrc/.broken (or .../.broken.${MACHINE} if OBJMACHINE is set),
517 individual build logs of broken builds can be found in the package's
518 directory. These files are used by the bulk-targets to mark broken builds
519 to not waste time trying to rebuild them, and they can be used to debug
520 these broken package builds later.
523 3.2.5 Disk space requirements
524 =============================
526 Currently, roughly the following requirements are valid for
527 1.6.1/i386 as of 20031003:
529 * Distfiles: 5 GB (NFS ok)
530 * Full set of all binaries: 5 GB (NFS ok)
531 * Temp space for compiling: 2 GB (local disk recommended)
535 * Full set of all binaries: 1300MB (NFS ok)
537 Note that all pkgs will be de-installed as soon as they are turned into a
538 binary package, and that work-sources are removed, so there is no huge
539 demand to disk space. Afterwards, if the package is needed again, it will
540 be installed via pkg_add instead of building again, so there are no cycles
541 wasted by recompiling.
544 3.2.6 Setting up a sandbox for chroot'ed builds
545 ===============================================
547 If you don't want all the pkgs nuked from a machine (rendering it useless
548 for anything but pkg compiling), there is the possibility of doing the pkg
549 bulk build inside a chroot environment.
551 The first step to do so is setting up a chroot sandbox, e.g. /usr/sandbox.
552 Extract all sets from a NetBSD installation or doing a "make distribution
553 DESTDIR=/usr/sandbox" in src/etc, also don't forget to install X - if you
554 are a developer and want to upload the resulting binary packages to
555 ftp.netbsd.org, make sure you are using the default X version for your
556 architecture and release (up to 1.6, that is 3.3.6 for all architectures).
557 Then, make sure the following items are present and properly configured:
560 cp /netbsd /usr/sandbox
562 cd /usr/sandbox/dev ; sh MAKEDEV all
563 * /etc/resolv.conf (for security/smtpd and mail):
564 cp /etc/resolv.conf /usr/sandbox/etc
565 * working(!) mail config (hostname, sendmail.cf):
566 cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail
567 * /etc/localtime (for security/smtpd):
568 ln -sf /usr/share/zoneinfo/GMT /usr/sandbox/etc/localtime
569 * /usr/src (system sources, for sysutils/aperture, net/ppp-mppe):
571 ln -s cvs/src-1.6 src
573 * create /var/db/pkg (not part of default install):
574 mkdir /usr/sandbox/var/db/pkg
575 * create /usr/pkg (not part of default install)
576 mkdir /usr/sandbox/usr/pkg
577 * checkout pkgsrc from cvs, into /usr/sandbox/usr/pkgsrc
578 cvs -d cvs.netbsd.org:/cvsroot co pkgsrc
579 Do not mount/link this to the copy of your pkgsrc tree you do
580 development in, as this will likely cause problems!
581 * /usr/pkgsrc/packages & .../distfiles (point outside of sandbox)
582 * /etc/mk.conf, see 3.2.1.1
583 * adjust .../mk/bulk/build.conf
584 * If you have set CVS_USER in build.conf, make sure that account exists
585 and can do a "cvs ${CVS_FLAGS} update" properly!
587 When the chroot sandbox is setup, you can start the build with the following
590 # cd /usr/sandbox/usr/pkgsrc
591 # sh mk/bulk/do-sandbox-build
593 This will just jump inside the sandbox and start thrash^Wbuilding.
594 At the end of the build, mail will be sent with the results of the build.
595 Created binary pkgs will be in /usr/sandbox/usr/pkgsrc/packages (wherever
596 that points/mounts to/from).
598 3.2.7 Building a partial set of packages
599 ========================================
601 In addition to building a complete set of all packages in pkgsrc, the
602 pkgsrc/mk/bulk/build script may be used to build a subset of the
603 packages contained in pkgsrc. By setting defining SPECIFIC_PKGS
604 in /etc/mk.conf, the variables
611 will define the set of packages which should be built. The bulk build
612 code will also include any packages which are needed as dependencies
613 for the explicitly listed packages.
615 One use is to do a bulk build with SPECIFIC_PKGS in a chroot sandbox
616 periodically to have a complete set of the binary packages needed for
617 your site available without the overhead of building extra packages
620 3.3 Creating a multiple CD-ROM packages collection
621 ==================================================
623 After your bulk pkgsrc build has completed, you may wish to create a CD-ROM
624 set of the resulting binary packages to assist in installing packages on
625 other machines. The package pkgsrc/pkgtools/cdpack provides a simple tool for
626 creating the ISO 9660 images. `cdpack' arranges the packages on the CD-ROM's
627 in a way that keeps all the dependencies for given package on the same
631 3.3.1 Example of cdpack
632 =======================
634 Complete documentation for cdpack is found in cdpack(1). The following
635 short example assumes that the binary packages are left in
636 /usr/pkgsrc/packages/All and that sufficient disk space exists in /u2
637 to hold the ISO 9660 images.
640 # pkg_add /usr/pkgsrc/packages/All/cdpack
641 # cdpack /usr/pkgsrc/packages/All /u2/images
643 If you wish to include a common set of files (COPYRIGHT, README, etc)
644 on each CD in the collection, then you need to create a directory which
645 contains these files. For example
648 # echo "This is a README" > /tmp/common/README
649 # echo "Another file" > /tmp/common/COPYING
650 # mkdir /tmp/common/bin
651 # echo "#!/bin/sh" > /tmp/common/bin/myscript
652 # echo "echo Hello world" >> /tmp/common/bin/myscript
653 # chmod 755 /tmp/common/bin/myscript
655 Now create the images with
657 # cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images
659 and each image will contain "README", "COPYING", and "bin/myscript"
660 in their root directories.
663 ====================================
664 Part II: Package Constructor's Guide
665 ====================================
667 4 Package components - files, directories and contents
668 ======================================================
670 Whenever you're preparing a package, there are a number of files involved
671 which are described in the following sections.
677 Building, installation and creation of a binary package are all controlled
678 by the package's Makefile.
680 There is a Makefile for each package. This file includes the standard
681 bsd.pkg.mk file (referenced as "../../mk/bsd.pkg.mk"), which sets all the
682 definitions and actions necessary for the package to compile and install
683 itself. The mandatory fields are the DISTNAME which specifies the base name
684 of the distribution file to be downloaded from the site on the Internet,
685 MASTER_SITES which specifies that site, CATEGORIES which denotes the
686 categories into which the package falls, PKGNAME which is the name of the
687 package, the MAINTAINER name, and the COMMENT variable, which should
688 contain a one-line description of the package (the package name should not
689 appear, it will be added automatically). The maintainer variable is there
690 so that anyone who quibbles with the (always completely correct) decisions
691 taken by the guy who maintains the port can complain vigorously.
693 The MASTER_SITES may be set to one of the predefined sites:
695 ${MASTER_SITE_APACHE}
696 ${MASTER_SITE_DEBIAN}
699 ${MASTER_SITE_GNUSTEP}
700 ${MASTER_SITE_MOZILLA}
701 ${MASTER_SITE_PERL_CPAN}
702 ${MASTER_SITE_SOURCEFORGE}
703 ${MASTER_SITE_SUNSITE}
704 ${MASTER_SITE_R_CRAN}
706 ${MASTER_SITE_TEX_CTAN}
707 ${MASTER_SITE_XCONTRIB}
708 ${MASTER_SITE_XEMACS}
710 If one of these predefined sites is chosen, you may require the ability to
711 specify a subdirectory of that site. This is in fact almost always the
712 case with all of the above. Since these macros may expand to more than one
713 actual site, you MUST use the following construct to specify a
716 ${MASTER_SITE_GNU:=subdirectory/name/}
717 ${MASTER_SITE_SOURCEFORGE:=project_name/}
719 (Note the trailing slash after the subdirectory name.) Use of the deprecated
720 MASTER_SITE_SUBDIR will not work.
722 If the package has multiple DISTFILES or multiple PATCHFILES from different
723 sites, set SITES_foo to a list of URI's where file "foo" may be found. "foo"
724 includes the suffix, e.g.
726 DISTFILES=${DISTNAME}${EXTRACT_SUFX}
727 DISTFILES+=foo-file.tar.gz
728 SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
729 http://www.somewhereelse.com/mirror/somehow/
731 Note, that the normal default setting of DISTFILES must be made explicit
732 if you want to add to it (rather than replace it), as you usually would.
734 Currently the following values are available for CATEGORIES. If more than
735 one is used, they need to be separated by spaces:
779 See the NetBSD packages(7) manual page for a description of all available
780 options and variables.
782 Please pay attention to the following gotchas:
784 - Add MANCOMPRESSED (if not already there) if manpages are installed in
785 compressed form by the package; see comment in bsd.pkg.mk
786 - Replace /usr/local by ${PREFIX} in all files (see patches below)
787 - If the package installs any info files, see the section `Packages providing
788 info files' in this document.
789 - Adjust MAINTAINER to be either yourself, if you plan to maintain the
790 package for future updates, or set it to the default MAINTAINER
792 - If there exists a home page for the software in question, please
793 add the variable HOMEPAGE right after MAINTAINER. The value of this
794 variable should be the URL for the home page.
795 - Please also set the COMMENT variable to a short description of the
796 package. The description should start with a capital letter.
802 Most important, the mandatory message digest, or checksum, of all the
803 distfiles needed for the package to compile, confirming they match the
804 original file distributed by the author. This ensures that the
805 distfile retrieved from the Internet has not been corrupted during
806 transfer or altered by a malign force to introduce a security hole.
807 It is best generated using the "make makesum" command. The digest
808 algorithm used was, at one stage, md5, but that was felt lacking
809 compared to sha1, and so sha1 is now the default algorithm. The
810 distfile size is also generated and stored in new distinfo files.
811 The pkgsrc/pkgtools/digest utility calculates all of the digests
812 in the distinfo file, and it provides various different algorithms.
813 At the current time, the algorithms provided are:
815 md5, rmd160, sha1, sha256, sha384 and sha512
817 Some packages have different sets of distfiles on a per architecture
818 basis. (A good example is pkgsrc/www/navigator). These are kept in the
819 same distinfo file and care should be taken when upgrading such a
820 package to ensure distfile information is not lost.
822 The message digest/checksum for all the official patches found in the
823 patches/ directory (see section 4.3) for the package is also stored in
824 the distinfo file. This is a message digest/checksum of all lines in
825 the patch file except the NetBSD RCS Id. This file is generated by
826 invoking "make makepatchsum".
832 This directory contains files that are used by the patch(1) command to
833 modify the sources as distributed in the distribution file into a form that
834 will compile and run perfectly on NetBSD. The files are applied
835 successively in alphabetic order (as returned by a shell "patches/patch-*"
836 glob expansion), so patch-aa is applied before patch-ab etc.
838 Patch files which are optional and will depend on local site configuration
839 can be included with names matching the pattern "patches/patch-optional-*".
840 Their suffixes should match the configuration options. The selected
841 optional patch file names should be assigned to the variable
842 $OPTIONAL_PATCHFILES. They will not be applied by default.
844 For example if a package data file needs patching to indicate the default
845 local printer paper size as specified in the $PAPERSIZE file you can
846 include patches for all the possible paper sizes other than the one the
847 package comes configured for by default. In this case you might have a
848 patch called "patch-optional-Letter-papersize" and/or another patch called
849 "patch-optional-A4-papersize". In your Makefile you would select between
850 them with the following construct:
852 PATCHDIR= ${.CURDIR}/patches
853 .if exists(${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize)
854 OPTIONAL_PATCHFILES+= ${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize
857 Note that you have to define the value of $PATCHDIR in order to use it in a
858 ".if" statement like this as otherwise it's not defined until too late
859 during the processing of the Makefile. You should use a ".if" statement in
860 order to avoid problems should the configuration item ($PAPERSIZE in this
861 example) be set to an unexpected value.
863 The patch-* files should be in "diff -bu" format, and apply without a fuzz
864 to avoid problems (to force patches to apply with fuzz you can set
865 PATCH_FUZZ_FACTOR=-F2). Furthermore, do not put changes for more than one
866 file into a single patch-file, as this will make future modifications more
869 Similar, a file should be patched at most once, not several times by
870 several different patches. If a file needs several patches, they should
871 be combined into one file.
873 One important thing to mention is to pay attention that no RCS IDs
874 get stored in the patch files, as these will cause problems when
875 later checked into the NetBSD CVS tree. To avoid this, use either
876 the "-U 2" or "-U 1" option to diff, or let the 'pkgdiff' command
877 from pkgsrc/pkgtools/pkgdiff help you.
879 If you don't want to worry about the problems in the last two paragraphs
880 yourself, use pkgdiff from the pkgsrc/pkgtools/pkgdiff package, which takes
881 care of any RCS Ids by itself.
883 For even more automation, we recommend using mkpatches from the same
884 package to make a whole set of patches. You just have to backup files
885 before you edit them to "filename.orig", e.g. with "cp -p filename
886 filename.orig" or, easier, by using pkgvi from the same package. If you
887 upgrade a package this way, you can easily compare the new set of patches
888 with the previously existing one with patchdiff.
890 When you have finished a package, remember to generate the checksums
891 for the patch files by using the "make makepatchsum" command, see
894 Patch files that are distributed by the author or other maintainers can be
895 listed in $PATCHFILES.
897 If it is desired to store any patches that should not be committed into
898 pkgsrc, they can be kept outside the pkgsrc tree in the $LOCALPATCHES
899 directory. The directory tree there is expected to have the same
900 "category/package" structure as pkgsrc, and patches are expected to be
901 stored inside these dirs (also known as $LOCALPATCHES/$PKGPATH). For
902 example if you want to keep a private patch for pkgsrc/graphics/png, keep
903 it in $LOCALPATCHES/graphics/png/mypatch. All files in the named directory
904 are expected to be patch files, and they are applied after the "normal"
905 pkgsrc patches are applied.
908 4.4 Other mandatory files
909 =========================
912 A multi-line description of the piece of software. This should include
913 any credits where they are due. Please bear in mind that others do not
914 share your sense of humour (or spelling idiosyncrasies), and that others
915 will read everything that you write here.
918 This file governs the files that are installed on your system: all the
919 binaries, manual pages, etc. There are other directives which may be
920 entered in this file, to control the creation and deletion of
921 directories, and the location of inserted files.
928 Shell script invoked twice during pkg_add. First time after package
929 extraction and before files are moved in place, the second time after
930 the files to install are moved in place. This can be used to do any
931 custom procedures not possible with @exec commands in PLIST. See
932 pkg_add(1) and pkg_create(1) for more information.
935 This script is executed before and after any files are removed. It is
936 this script's responsibility to clean up any additional messy details
937 around the package's installation, since all pkg_delete knows is how to
938 delete the files created in the original distribution. See pkg_delete(1)
939 and pkg_create(1) for more information.
942 Display this file after installation of the package.
943 Useful for things like legal notices on almost-free software, etc.
944 Please note that you can modify variables in it easily by using
945 MESSAGE_SUBST in the package's Makefile:
947 MESSAGE_SUBST+= SOMEVAR="somevalue"
953 in MESSAGE with "somevalue" before displaying the message.
959 When you type "make" the distribution files are unpacked into this
960 directory. It can be removed by typing
964 at the shell prompt. Also, this directory is used to keep various
971 If you have any files that you wish to be placed in the package prior
972 to configuration or building, you could place these files here and use
973 a ${CP} command in the pre-configure target to achieve this.
974 Alternatively, you could simply diff the file against /dev/null and
975 use the patch mechanism to manage the creation of this file.
981 This section addresses some special issues that one needs to pay attention
982 to when dealing with the PLIST file (or files, see below!).
989 Be sure to add a RCS ID line as the first thing in any PLIST file you
992 @comment <$>NetBSD<$>
994 * ${MACHINE_ARCH}, ${MACHINE_GNU_ARCH}:
995 Some packages like emacs and perl embed information about which
996 architecture they were built on into the pathnames where they install
997 their file. To handle this case, PLIST will be preprocessed before
998 actually used, and the symbol "${MACHINE_ARCH}" will be replaced by
999 what "uname -p" gives. The same is done if the string ${MACHINE_GNU_ARCH}
1000 is embedded in PLIST somewhere - use this on packages that have GNU
1001 autoconf created configure scripts.
1003 Legacy note: There used to be a symbol "<$ARCH>" that was replaced by
1004 the output of "uname -m", but that's no longer supported and has been
1007 * ${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION}:
1008 Some packages want to embed the OS name and version into some paths.
1009 To do this, use these variables in the PLIST:
1011 * ${OPSYS} - output of "uname -s"
1012 * ${LOWER_OPSYS} - lowercase common name (eg. "solaris")
1013 * ${OS_VERSION} - "uname -r"
1016 Packages that install locale files should list them in the PLIST as
1017 "${PKGLOCALEDIR}/locale/de/LC_MESSAGES/..." instead of
1018 "share/locale/de/LC_MESSAGES/...". This properly handles the fact that
1019 different OSes expect locale files to be either in "share" or "lib" by
1022 * Manpage-compression:
1023 Manpages should be installed in compressed form if MANZ is set (in
1024 bsd.own.mk), and uncompressed otherwise. To handle this in the PLIST
1025 file, the suffix ".gz" is appended/removed automatically for manpages
1026 according to MANZ and MANCOMPRESSED being set or not, see above for
1027 details. This modification of the PLIST file is done on a copy of it,
1030 * Platform specific and differing PLISTs:
1031 Some packages decide to install a different set of files based on
1032 the operating system being used. These differences can be
1033 automatically handled by using the following files:
1039 If PLIST.${OPSYS} exists, these files are used instead of PLIST. This
1040 allows packages which behave in this way to be handled gracefully.
1041 Manually overriding PLIST_SRC for other more exotic uses is also
1044 * Semi-automatic PLIST generation:
1045 You can use the "make print-PLIST" command to output a PLIST that matches
1046 any new files since the package was extracted. See below for more
1047 information on this target.
1053 To use one or more files as source for the PLIST used in generating the
1054 binary package, set the variable PLIST_SRC to the names of that file(s).
1055 The files are later concatenated using cat(1), and order of things is
1061 Similar to MESSAGE_SUBST (see above), you can add variables and their
1062 expansions to this variable in the following way:
1064 PLIST_SUBST+= SOMEVAR="somevalue"
1066 which replaces all occurrences of ${SOMEVAR} in the PLIST with "somevalue".
1067 For the values which are replaced by default, please look in bsd.pkg.mk
1068 (and search for PLIST_SUBST).
1073 Makefile of packages providing perl5 modules should include the
1074 makefile fragment lang/perl5/module.mk. It provides a do-configure
1075 target for the standard perl configuration for such modules as well
1076 as various hooks to tune this configuration. See comments in this
1079 Perl5 modules will install into different places depending on the version
1080 of perl used during the build process. To address this, the NetBSD
1081 packages system will append lines to the PLIST corresponding to the files
1082 listed in the installed .packlist file generated by most perl5 modules.
1083 This is invoked by defining PERL5_PACKLIST to a space-separated list of
1084 paths to packlist files:
1086 PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
1088 The variables PERL5_SITELIB, PERL5_SITEARCH, and PERL5_ARCHLIB represent
1089 the three locations in which perl5 modules may be installed, and may be
1090 used by perl5 packages that don't have a packlist. These three variables
1091 are also substituted for in the PLIST.
1093 5.5 User Interaction
1094 ====================
1096 Occasionally, packages require interaction from the user, and this can be
1097 in a number of ways:
1099 + help in fetching the distfiles
1100 + help to configure the package before it is built
1101 + help during the build process
1102 + help during the installation of a package
1104 The INTERACTIVE_STAGE definition is provided, to notify the pkgsrc mechanism
1105 of an interactive stage which will be needed, and this should be set in the
1106 package's Makefile. e.g.
1108 INTERACTIVE_STAGE= build
1110 Multiple interactive stages can be specified:
1112 INTERACTIVE_STAGE= configure install
1115 6 Notes on fixes for packages
1116 =============================
1121 To port an application to NetBSD, it's usually necessary for the compiler
1122 to be able to judge the system on which it's compiling, and we use
1123 definitions so that the C pre-processor can do this.
1125 To test whether you are working on a 4.4 BSD-derived system, you should use
1126 the BSD definition, which is defined in <sys/param.h> on said systems.
1128 #include <sys/param.h>
1130 and then you can surround the BSD-specific parts of your port using the
1133 #if (defined(BSD) && BSD >= 199306)
1137 Please use the __NetBSD__ definition sparingly - it should only apply to
1138 features of NetBSD that are not present in other 4.4-lite derived BSDs.
1140 6.2 Shared libraries - libtool
1141 ==============================
1143 Pkgsrc supports many different machines, with different object formats
1144 like a.out and ELF, and varying abilities to do shared library and
1145 dynamic loading at all. To accompany this, varying commands and options
1146 have to be passed to the compiler, linker etc. to get the Right Thing,
1147 which can be pretty annoying especially if you don't have all the
1148 machines at your hand to test things. The "libtool" pkg can help
1149 here, as it just "knows" how to build both static and dynamic
1150 libraries from a set of source files, thus being platform
1153 Here's how to use libtool in a pkg in seven simple steps:
1155 1. Add USE_LIBTOOL= yes to the package Makefile.
1157 2. For library objects, use "${LIBTOOL} --mode=compile ${CC}" in place of
1158 ${CC}. You could even add it to the definition of CC, if only
1159 libraries are being built in a given Makefile. This one command will
1160 build both PIC and non-PIC library objects, so you need not have
1161 separate shared and non-shared library rules.
1163 3. For the linking of the library, remove any "ar", "ranlib", and "ld
1164 -Bshareable" commands, and use instead:
1166 ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} -rpath ${PREFIX}/lib -version-info CURRENT:REVISION:AGE
1168 Note that the library is changed to have a .la extension, and the
1169 objects are changed to have a .lo extension. Change OBJS as necessary.
1170 This automatically creates all of the .a, .so.major.minor, and ELF
1171 symlinks (if necessary) in the build directory. Be sure to include
1172 the -version-info especially when major and minor are zero, as libtool
1173 will otherwise strip off the shared library version.
1175 PLIST gets all of the .a, .la and so, .so.major and .so.major.minor
1178 From the libtool manual:
1180 libtool library versions are described by three integers:
1183 The most recent interface number that this library implements.
1186 The implementation number of the CURRENT interface.
1189 The difference between the newest and oldest interfaces that this
1190 library implements. In other words, the library implements all the
1191 interface numbers in the range from number `CURRENT - AGE' to
1194 If two libraries have identical CURRENT and AGE numbers, then the
1195 dynamic linker chooses the library with the greater REVISION
1198 The "-release" option will produce different results for a.out and ELF
1199 (excluding symlinks) in only one case. An ELF library of the form
1200 libfoo-release.so.x.y will have a symlink of libfoo.so.x.y on an a.out
1201 platform. This is handled automatically.
1203 The -rpath argument is the install directory of the library being built.
1205 PLIST should include all of the .a, .la and so, .so.major and
1206 .so.major.minor entries.
1208 4. When linking shared object (.so) files, i.e. files that are loaded via
1209 dlopen(3), NOT shared libraries, use "-module -avoid-version" to prevent
1210 them getting version tacked on.
1212 PLIST gets the foo.so entry.
1214 5. When linking programs that depend on these libraries _before_ they are
1215 installed, preface the cc or ld line with "${LIBTOOL} --mode=link", and
1216 it will find the correct libraries (static or shared), but please be
1217 aware that libtool will not allow you to specify a relative path in -L
1218 (such as -L../somelib), because it expects you to change that argument
1219 to be the .la file. For example:
1221 ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
1223 should be changed to:
1225 ${LIBTOOL} --mode=link ${CC} -o someprog ../somelib/somelib.la
1227 and it will DTRT with the libraries.
1229 6. When installing libraries, preface the install or cp command with
1230 "${LIBTOOL} --mode=install", and change the library name to .la. For
1233 ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
1235 This will install the static .a, shared library, any needed symlinks,
1238 7. In your PLIST, include all of the .a, .la, and so, .so.CURRENT and
1239 .so.CURRENT.REVISION files (this is a change from the previous
1243 6.3 Using libtool on GNU packages that already support libtool
1244 ==============================================================
1246 Add USE_LIBTOOL=yes to the package Makefile. This will override the
1247 package's own libtool in most cases. For older libtool using packages,
1248 libtool is made by ltconfig script during the do-configure step; you can
1249 check the libtool script location by doing "make configure; find work*/
1252 LIBTOOL_OVERRIDE specifies which libtool scripts, relative to WRKSRC, to
1253 override. By default, it is set to "libtool */libtool */*/libtool". If
1254 this does not match the location of the package's libtool script(s), set
1257 If you do not need *.a static libraries built and installed, then use
1258 SHLIBTOOL_OVERRIDE instead.
1260 If your package makes use of the platform independent library for loading
1261 dynamic shared objects, that comes with libtool (libltdl), you should
1262 include the libtool buildlink3.mk (and set USE_BUILDLINK3 to "yes").
1264 Some packages use libtool incorrectly so that the package may not work or
1265 build in some circumstances. Some common errors are
1267 * The inclusion of a shared object (-module) as a dependent library in an
1268 executable or library. This in itself isn't a problem if one of two things
1271 1. The shared object is named correctly, i.e. libfoo.la and not foo.la
1273 2. The -dlopen option is used when linking an executable.
1275 * The use of libltdl without the correct calls to initialisation routines.
1276 The function lt_dlinit() should be called and the macro
1277 LTDL_SET_PRELOADED_SYMBOLS included in executables.
1280 6.4 GNU Autoconf/Automake
1281 =========================
1283 If a package needs GNU autoconf or automake to be executed to regenerate
1284 the configure script and Makefile.in makefile templates, then they should
1285 be executed in a pre-configure target. Two makefile fragments are provided
1286 in pkgsrc/mk/autoconf.mk and pkgsrc/mk/automake.mk to help dealing with
1287 these tools. See comments in these files for details.
1289 For packages that need only autoconf:
1291 AUTOCONF_REQD= 2.50 # if default version is not good enough
1295 cd ${WRKSRC}; ${AUTOCONF}
1298 .include "../../mk/autoconf.mk"
1300 and for packages that need automake and autoconf:
1302 AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
1309 ${AUTOMAKE} -a --foreign -i; \
1313 .include "../mk/automake.mk"
1315 Packages which use GNU Automake will almost certainly require GNU Make, but
1316 that's automatically provided for you in "mk/automake.mk".
1318 There are times when the configure process makes additional changes to the
1319 generated files, which then causes the build process to try to re-execute
1320 the automake sequence. This is prevented by touching various files in
1321 the configure stage. If this causes problems with your package you can set
1322 AUTOMAKE_OVERRIDE to NO in the package Makefile.
1325 6.5 Package configuration files
1326 ===============================
1328 Packages should be taught to look for their configuration files in
1329 ${PKG_SYSCONFDIR}, which is passed through to the configure and build
1330 processes. PKG_SYSCONFDIR may be customized in various ways by setting
1331 other make variables:
1333 * PKG_SYSCONFBASE is the main config directory under which all package
1334 configuration files are to be found. This defaults to ${PREFIX}/etc, but
1335 may be overridden in /etc/mk.conf.
1337 * PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which the
1338 configuration files for a particular package may be found, e.g. the
1339 Apache configuration files may all be found under the "httpd" subdirectory
1340 of ${PKG_SYSCONFBASE}. This is meant to be set in a package Makefile.
1342 * By default PKG_SYSCONFDIR=${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}, but
1343 the default may be overridden by setting PKG_SYSCONFDIR.${PKG_SYSCONFVAR}
1344 for a particular package, where PKG_SYSCONFVAR defaults to ${PKGBASE}.
1345 This is not meant to be set by a package Makefile, but is reserved for
1346 users who wish to override the PKG_SYSCONFDIR setting for a particular
1347 package with a special location.
1349 The only variables that users should customize are PKG_SYSCONFBASE and
1350 PKG_SYSCONFDIR.${PKG_SYSCONFVAR}. Users will typically want to set
1351 PKG_SYSCONFBASE to /etc, or to accept the default location of ${PREFIX}/etc.
1354 6.6 Feedback to the author
1355 ==========================
1357 If you have found any bugs in the package you make available, if you had to
1358 do special steps to make it run under NetBSD or if you enhanced the software
1359 in various other ways, be sure to report these changes back to the original
1360 author of the program! With that kind of support, the next release of the
1361 program can incorporate these fixes, and people not using the NetBSD packages
1362 system can win from your efforts.
1364 Support the idea of free software!
1370 The basic steps for building a program are always the same. First the
1371 program's source (distfile) must be brought to the local system and
1372 then extracted. After any patches to compile properly on NetBSD are
1373 applied, the software can be configured, then built (usually by
1374 compiling), and finally the generated binaries etc. can be put into
1375 place on the system. These are exactly the steps performed by the
1376 NetBSD package system, which is implemented as a series of targets in
1377 a central Makefile, pkgsrc/mk/bsd.pkg.mk.
1380 7.1 Program location
1381 ====================
1383 Before outlining the process performed by the NetBSD package system in the
1384 next section, here's a brief discussion on where programs are installed,
1385 and which variables influence this.
1387 The automatic variable PREFIX indicates where all files of the final
1388 program shall be installed. It is usually set to $LOCALBASE (/usr/pkg),
1389 or $CROSSBASE for pkgs in the "cross" category, though its value becomes
1390 that of $X11BASE if USE_IMAKE or USE_X11BASE is set. The value ${PREFIX}
1391 needs to be put into the various places in the program's source where paths
1392 to these files are encoded; see sections 4.3 and 6.2 for details on this.
1394 When choosing which of these variables to use, follow the following rules:
1396 * ${PREFIX} always points to the location where the current pkg will be
1397 installed. When referring to a pkg's own installation path, use ${PREFIX}.
1399 * ${LOCALBASE} is where all non-X11 pkgs are installed. If you need to
1400 construct a -I or -L argument to the compiler to find includes and
1401 libraries installed by another non-X11 pkg, use ${LOCALBASE}.
1403 * ${X11BASE} is where the actual X11 distribution (from xsrc etc.) is installed.
1404 When looking for _standard_ X11 includes (not those installed by a pkg), use
1407 * X11 based pkgs are special in that they may be installed in either
1408 X11BASE or LOCALBASE.
1410 Usually, X11 packages should be installed under LOCALBASE whenever
1411 possible. Note that you will need to set USE_X11 in them to request
1412 the presence of X11 and to get the right compilation flags.
1414 Even though, there are some packages that cannot be installed under
1415 LOCALBASE: those that come with app-defaults files. These packages are
1416 special and they must be placed under X11BASE. To accomplish this,
1417 set either USE_X11BASE or USE_IMAKE in your package.
1419 Some notes: USE_X11 and USE_X11BASE are mutually exclusive. If you need
1420 to find includes or libraries installed by a pkg that has USE_IMAKE or
1421 USE_X11BASE in its pkg Makefile, you need to use _both_ ${X11BASE} and
1422 ${LOCALBASE}. To install all X11 packages in LOCALBASE, simply install
1423 the xpkgwedge package (pkgsrc/pkgtools/xpkgwedge).
1425 * ${X11PREFIX} should be used to refer to the installed location of an X11
1426 package. X11PREFIX will be set to ${X11BASE} if xpkgwedge is not installed,
1427 and to ${LOCALBASE} if xpkgwedge is installed.
1429 * If xpkgwedge is installed, it is possible to have some packages installed in
1430 X11BASE and some in LOCALBASE. To determine the prefix of an installed
1431 package, the EVAL_PREFIX definition can be used. It takes pairs in the
1432 format DIRNAME=<package>, and the make(1) variable DIRNAME will be set
1433 to the prefix of the installed package <package>, or ${X11PREFIX} if the
1434 package is not installed.
1436 This is best illustrated by example.
1438 The following lines are taken from pkgsrc/wm/scwm/Makefile:
1440 EVAL_PREFIX+= GTKDIR=gtk+
1441 CONFIGURE_ARGS+= --with-guile-prefix=${LOCALBASE} \
1442 --with-gtk-prefix="${GTKDIR}" \
1445 Specific defaults can be defined for the packages evaluated using
1446 EVAL_PREFIX, by using a definition of the form:
1448 GTKDIR_DEFAULT= ${LOCALBASE}
1450 where "GTKDIR" corresponds to the first definition in the EVAL_PREFIX pair.
1452 * Within ${PREFIX}, packages should install files according to hier(7), with
1453 the exception that manual pages go into ${PREFIX}/man, not
1454 ${PREFIX}/share/man.
1459 The main targets used during the build process defined in bsd.pkg.mk are:
1462 This will check if the file(s) given in the variables DISTFILES and
1463 PATCHFILES (as defined in the package's Makefile) are present on the
1464 local system in /usr/pkgsrc/distfiles. If they are not present, an
1465 attempt will be made to fetch them using commands of the form
1467 ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
1469 where ${site} varies through several possibilities in turn: first,
1470 ${MASTER_SITE_OVERRIDE} is tried, then the sites specified in either
1471 ${SITES_file}, if defined, else ${MASTER_SITES} or ${PATCH_SITES}, as
1472 applies, then finally the value of ${MASTER_SITE_BACKUP}. The order of
1473 all except the first can be optionally sorted by the user, via setting
1474 either ${MASTER_SORT_AWK} or ${MASTER_SORT_REGEX}.
1477 After the distfile(s) are fetched, their checksum is generated and
1478 compared with the checksums stored in the distinfo file. If the
1479 checksums don't match, the build is aborted. This is to ensure the same
1480 distfile is used for building, and that the distfile wasn't changed,
1481 e.g. by some malign force, deliberately changed distfiles on the master
1482 distribution site or network lossage.
1485 When the distfiles are present on the local system, they need to be
1486 extracted, as they are usually in the form of some compressed archive
1487 format, most commonly .tar.gz. If only some of the distfiles need to be
1488 uncompressed, the files to be uncompressed should be put into
1489 EXTRACT_ONLY. If the distfiles are not in .tar.gz format, they can be
1490 extracted by setting EXTRACT_CMD.
1493 After extraction, all the patches named by the PATCHFILES, those present
1494 in the patches subdirectory of the package as well as in
1495 $LOCALPATCHES/$PKGPATH (e.g. /usr/local/patches/graphics/png) are
1496 applied. Patchfiles ending in .Z or .gz are uncompressed before they are
1497 applied, files ending in .orig or .rej are ignored. Any special options
1498 to patch(1) can be handed in PATCH_DIST_ARGS. See section 4.3 for more
1501 By default patch is given special args to make it fail if the
1502 patches with some lines of fuzz. Please fix (regen) the patches
1503 so that they apply cleanly. The rationale behind this is that
1504 patches that apply cleanly may end up being applied in the wrong
1505 place, and cause severe harm there.
1508 Most pieces of software need information on the header files,
1509 system calls, and library routines which are available in NetBSD.
1510 This is the process known as configuration, and is usually
1511 automated. In most cases, a script is supplied with the source,
1512 and its invocation results in generation of header files,
1515 If the program's distfile contains its own configure script, this can
1516 be invoked by setting HAS_CONFIGURE. If the configure script is a GNU
1517 autoconf script, GNU_CONFIGURE should be specified instead. In either
1518 case, any arguments to the configure script can be specified in the
1519 CONFIGURE_ARGS variable, and the configure script's name can be set in
1520 CONFIGURE_SCRIPT if it differs from the default "configure".
1522 If the program uses an Imakefile for configuration, the appropriate
1523 steps can be invoked by setting USE_IMAKE to YES. (If you only want the
1524 package installed in $X11PREFIX but xmkmf not being run, set USE_X11BASE
1528 Once configuration has taken place, the software can be built on
1529 NetBSD by invoking $MAKE_PROGRAM on $MAKEFILE with $ALL_TARGET as
1530 the target to build. The default MAKE_PROGRAM is "gmake" if
1531 USE_GNU_TOOLS 'make' is set, "make" otherwise. MAKEFILE is set to
1532 "Makefile" by default, and ALL_TARGET defaults to "all". Any of
1533 these variables can be set to change the default build process.
1536 Once the build stage has completed, the final step is to install
1537 the software in public directories, for users. As in the
1538 build-target, $MAKE_PROGRAM is invoked on $MAKEFILE here, but with
1539 the $INSTALL_TARGET instead, the latter defaulting to "install"
1540 (plus "install.man", if USE_IMAKE is set).
1542 If no target is specified, the default is "build". If a subsequent stage
1543 is requested, all prior stages are made: e.g. "make build" will also
1544 perform the equivalent of:
1554 7.3 Other helpful targets
1555 =========================
1558 For any of the main targets described in the previous section, two
1559 auxiliary targets exist with "pre-" and "post-" used as a prefix
1560 for the main target's name. These targets are invoked before and
1561 after the main target is called, allowing extra configuration or
1562 installation steps, for example, which program's configure script
1563 or install target omitted.
1566 Should one of the main targets do the wrong thing, and should there
1567 be no variable to fix this, you can redefine it with the do-*
1568 target. (Note that redefining the target itself instead of the
1569 do-* target is a bad idea, as the pre-* and post-* targets won't be
1570 called anymore, etc.) You will not usually need to do this.
1573 If you did a "make install" and you noticed some file was not installed
1574 properly, you can repeat the installation with this target, which will
1575 ignore the "already installed" flag.
1578 This target does a pkg_delete(1) in the current directory,
1579 effectively de-installing the package. The following variables can
1580 be used either on the command line or in /etc/mk.conf to tune the
1584 Add a "-v" to the pkg_delete(1) command.
1587 Remove all packages that require (depend on) the given package.
1588 This can be used to remove any packages that may have been pulled in
1589 by a given package, e.g. if "make deinstall DEINSTALLDEPENDS=1" is
1590 done in pkgsrc/x11/kde, this is likely to remove whole KDE. Works by
1591 adding a "-R" to the pkg_delete command line.
1594 This target causes the current package to be updated to the latest
1595 version. The package and all depending packages first get de-installed,
1596 then current versions of the corresponding packages get compiled and
1597 installed. This is similar to manually noting which packages are
1598 currently installed, then performing a series of "make deinstall" and
1599 "make install" (or whatever UPDATE_TARGET is set to) for these packages.
1601 You can use the "update" target to resume package updating in case a
1602 previous "make update" was interrupted for some reason. However, in
1603 this case, make sure you don't call "make clean" or otherwise remove
1604 the list of dependent packages in ${WRKDIR}. Otherwise you lose the
1605 ability to automatically update the current package along with the
1606 dependent packages you have installed.
1608 Resuming an interrupted "make update" will only work as long as the
1609 package tree remains unchanged. If the source code for one of the
1610 packages to be updated has been changed, resuming "make update" will
1611 most certainly fail!
1613 The following variables can be used either on the command line or in
1614 /etc/mk.conf to alter the behaviour of "make update":
1617 Install target to recursively use for the updated package and the
1618 dependent packages. Defaults to ${DEPENDS_TARGET} if set, "install"
1619 otherwise for "make update".
1620 E.g. "make update UPDATE_TARGET=package"
1623 Don't clean up after updating. Useful if you want to leave the
1624 work sources of the updated packages around for inspection or
1625 other purposes. Be sure you eventually clean up the source
1626 tree (see the "clean-update" target below) or you may run into
1627 troubles with old source code still lying around on your next
1628 "make" or "make update".
1631 Deinstall each package before installing (making ${DEPENDS_TARGET}).
1632 This may be necessary if the "clean-update" target (see below) was
1633 called after interrupting a running "make update".
1636 Allows you to disable recursion and hardcode the target for
1637 packages. The default is "update" for the update target,
1638 facilitating a recursive update of prerequisite packages.
1639 Only set DEPENDS_TARGET if you want to disable recursive updates.
1640 Use "UPDATE_TARGET" instead to just set a specific target for
1641 each package to be installed during "make update" (see above).
1644 Clean the source tree for all packages that would get updated if
1645 "make update" was called from the current directory. This target
1646 should not be used if the current package (or any of its depending
1647 packages) have already been de-installed (e.g., after calling "make
1648 update") or you may lose some packages you intended to update.
1649 As a rule of thumb: only use this target _before_ the first time
1650 you call "make update" and only if you have a dirty package tree
1651 (e.g., if you used NOCLEAN).
1653 If you unsure about whether your tree is clean you can either perform
1654 a "make clean" at the top of the tree, or use the following sequence
1655 of commands from the directory of the package you want to update
1656 (*before* running "make update" for the first time, otherwise you lose
1657 all the packages you wanted to update!):
1660 make clean CLEANDEPENDS=YES
1663 The following variables can be used either on the command line or in
1664 /etc/mk.conf to alter the behaviour of "make clean-update":
1667 After "make clean", do not reconstruct the list of directories to
1668 update for this package. Only use this if "make update" successfully
1669 installed all packages you wanted to update. Normally, this is done
1670 automatically on "make update", but may have been suppressed by the
1671 NOCLEAN variable (see above).
1674 This target invokes "pkg_info" for the current package. You can use this
1675 e.g. to check which version of a package is installed.
1678 This target generates a README.html file, which can be viewed using a
1679 browser such as navigator (pkgsrc/www/navigator) or lynx
1680 (pkgsrc/www/lynx). The generated files contain references to any
1681 packages which are in the ${PACKAGES} directory on the local host. The
1682 generated files can be made to refer to URLs based on FTP_PKG_URL_HOST
1683 and FTP_PKG_URL_DIR. For example, if I wanted to generate README.html
1684 files which pointed to binary packages on the local machine, in the
1685 directory /usr/packages, set FTP_PKG_URL_HOST=file://localhost and
1686 FTP_PKG_URL_DIR=/usr/packages. The ${PACKAGES} directory and its
1687 subdirectories will be searched for all the binary packages.
1690 Use this target to create a file README-all.html which contains a
1691 list of all packages currently available in the NetBSD Packages
1692 Collection, together with the category they belong to and a short
1693 description. This file is compiled from the pkgsrc/*/README.html
1694 files, so be sure to run this _after_ a "make readme".
1697 This is very much the same as the readme: target (see above), but is
1698 to be used when generating a pkgsrc tree to be written to a CD-ROM.
1699 This target also produces README.html files, and can be made to refer
1700 to URLs based on CDROM_PKG_URL_HOST and CDROM_PKG_URL_DIR.
1703 This target shows which distfiles and patchfiles are needed to build
1704 the package. (DISTFILES and PATCHFILES, but not patches/*)
1707 This target shows nothing if the package is not installed. If a version
1708 of this package is installed, but is not the version provided in this
1709 version of pkgsrc, then a warning message is displayed. This target can
1710 be used to show which of your installed packages are downlevel, and so
1711 the old versions can be deleted, and the current ones added.
1714 This target shows the directory in the pkgsrc hierarchy from which the
1715 package can be built and installed. This may not be the same directory
1716 as the one from which the package was installed. This target is intended
1717 to be used by people who may wish to upgrade many packages on a single
1718 host, and can be invoked from the top-level pkgsrc Makefile by using the
1719 target "show-host-specific-pkgs"
1721 * show-installed-depends:
1722 This target shows which installed packages match the current package's
1723 DEPENDS. Useful if out of date DEPENDS are causing build problems.
1726 After a package is installed, check all its binaries and (on ELF
1727 platforms) shared libraries to see if they find the shared libs they need.
1728 Run by default if PKG_DEVELOPER is set in /etc/mk.conf.
1731 After a 'make install' from a new or upgraded pkg, this prints out an
1732 attempt to generate a new PLIST from a 'find -newer work/.extract_done'.
1733 (Note that it will not descend into different filesystems.)
1734 An attempt is made to care for shared libs etc., but it is STRONGLY
1735 recommended to review the result before putting it into PLIST. On
1736 upgrades, it's useful to diff the output of this command against an already
1737 existing PLIST file.
1739 If the package installs files via tar(1) or other methods that don't update
1740 file access times, be sure to add these files manually to your PLIST,
1741 as 'find -newer' won't catch them!
1744 Used to do bulk builds. If an appropriate binary package already exists,
1745 no action is taken. If not, this target will compile, install and
1746 package it (and its dependencies, if PKG_DEPENDS is set properly; see
1747 section 3.2.1). After creating the binary package, the sources, the
1748 just-installed package and its dependencies are removed to preserve
1752 Used during bulk-installs to install required packages. If an
1753 appropriate binary package is available, it will be installed via
1754 pkg_add. If not, "make bulk-package" will be executed, but the installed
1755 binary not be removed. A binary package is "appropriate" to be installed
1758 - None of the package's files (Makefile, ...) were modified since it
1760 - None of the package's required (binary) packages were modified since
1764 8 buildlink3 methodology
1765 ========================
1767 "buildlink3" is a pkgsrc framework that controls what headers and libraries
1768 are seen by a package's configure and build processes. This is implemented
1769 in a two step process:
1771 (1) Symlink headers and libraries for dependencies into ${BUILDLINK_DIR},
1772 which by default is a subdirectory of ${WRKDIR};
1774 (2) Create wrapper scripts that are used in place of the normal compiler
1775 tools that translate -I${LOCALBASE}/include and -L${LOCALBASE}/lib
1776 into references into ${BUILDLINK_DIR}. The wrapper scripts also make
1777 native compiler on some operating systems look like GCC, so that
1778 packages that expect GCC won't require modifications to build with
1779 those native compilers.
1781 This normalizes the environment in which a package is built so that the
1782 package may be built consistently despite what may other software may
1783 installed. Please note that the normal system header and library paths,
1784 e.g. /usr/include, /usr/lib, etc., are always searched -- buildlink3 is
1785 designed to insulate the package build from non-system-supplied software.
1788 8.1 Converting packages to use buildlink3
1789 =========================================
1791 The process of "bl3ifying" a package, or converting a package to use
1792 the buildlink3 framework, is surprisingly easy. The things to keep in
1795 (1) Set USE_BUILDLINK3 to "yes".
1797 (2) Ensure that the build always calls the wrapper scripts instead of
1798 the actual toolchain. Some packages are tricky, and the only way to
1799 know for sure is the check ${WRKDIR}/.work.log to see if the
1800 wrappers are being invoked.
1802 (3) Don't override PREFIX from within the package Makefile, e.g.
1803 Java VMs, standalone shells, etc., because the code to symlink
1804 files into ${BUILDLINK_DIR} looks for files relative to
1805 "pkg_info -qp <pkgname>".
1807 (4) Remember that _only_ the buildlink3.mk files that you list in a
1808 package's Makefile are added as dependencies for that package.
1810 If a dependency on a particular package is required for its libraries and
1811 headers, then we replace:
1813 DEPENDS+= foo>=1.1.0:../../category/foo
1815 .include "../../category/foo/buildlink3.mk"
1817 There are several buildlink3.mk files in pkgsrc/mk that handle special
1820 * bdb.buildlink3.mk chooses either the native or a pkgsrc Berkeley DB
1821 implementation based on the values of BDB_ACCEPTED and BDB_DEFAULT.
1823 * krb5.buildlink3.mk uses the value of KRB5_ACCEPTED to choose between
1824 adding a dependency on Heimdal or MIT-krb5 for packages that require
1825 a Kerberos 5 implementation.
1827 * motif.buildlink3.mk checks for a system-provided Motif installation
1828 or adds a dependency on x11/lesstif or x11/openmotif;
1830 * ossaudio.buildlink3.mk defines several variables that may be used by
1831 packages that use the Open Sound System (OSS) API;
1833 * pthread.buildlink3.mk uses the value of PTHREAD_OPTS and checks for
1834 native pthreads or adds a dependency on devel/pth as needed;
1836 * xaw.buildlink3.mk uses the value of XAW_TYPE to choose a particular
1837 Athena widgets library.
1839 The comments in those *.buildlink3.mk files provide a more complete
1840 description of how to use them properly.
1843 8.2 Writing buildlink3.mk files
1844 ===============================
1846 A package's buildlink3.mk file is included by Makefiles to indicate the
1847 need to compile and link against header files and libraries provided by
1848 the package. A buildlink3.mk file should always provide enough information
1849 to add the correct type of dependency relationship and include any other
1850 buildlink3.mk files that it needs to find headers and libraries that it
1853 To generate an initial buildlink3.mk file for further editing, Rene Hexel's
1854 pkgtools/createbuildlink package is highly recommended. For most packages,
1855 the following command will generate a good starting point for buildlink3.mk
1858 cd pkgsrc/category/pkgdir; createbuildlink -3 > buildlink3.mk
1861 8.3.1 Anatomy of a buildlink3.mk file
1862 =====================================
1864 The following real-life example buildlink3.mk is taken from graphics/tiff:
1866 ------------8<------------8<------------8<------------8<------------
1867 # <$>NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp <$>
1869 BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH}+
1870 TIFF_BUILDLINK3_MK:= ${TIFF_BUILDLINK3_MK}+
1872 .if !empty(BUILDLINK_DEPTH:M+)
1873 BUILDLINK_DEPENDS+= tiff
1876 BUILDLINK_PACKAGES:= ${BUILDLINK_PACKAGES:Ntiff}
1877 BUILDLINK_PACKAGES+= tiff
1879 .if !empty(TIFF_BUILDLINK3_MK:M+)
1880 BUILDLINK_DEPENDS.tiff+= tiff>=3.6.1
1881 BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
1882 .endif # TIFF_BUILDLINK3_MK
1884 .include "../../devel/zlib/buildlink3.mk"
1885 .include "../../graphics/jpeg/buildlink3.mk"
1887 BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH:S/+$//}
1888 ------------8<------------8<------------8<------------8<------------
1890 The header and footer manipulate BUILDLINK_DEPTH, which is common across
1891 all buildlink3.mk files and is used to track at what depth we are including
1892 buildlink3.mk files.
1894 The first section controls if the dependency on <pkg> is added.
1895 BUILDLINK_DEPENDS is the global list of packages for which dependencies
1896 are added by buildlink3.
1898 The second section advises pkgsrc that the buildlink3.mk file for <pkg>
1899 has been included at some point. BUILDLINK_PACKAGES is the global list
1900 of packages for which buildlink3.mk files have been included. It must
1901 _always_ be appended to within a buildlink3.mk file.
1903 The third section is protected from multiple inclusion and controls how
1904 the dependency on <pkg> is added. Several important variables are set in
1907 (1) BUILDLINK_DEPENDS.<pkg> is the actual dependency recorded in the
1908 installed package; this should always be set using += to ensure that
1909 we're appending to any pre-existing list of values. This variable
1910 should be set to the first version of the package that had the last
1911 change in the major number of a shared library or that had a major
1914 (2) BUILDLINK_PKGSRCDIR.<pkg> is the location of the <pkg> pkgsrc
1917 (3) BUILDLINK_DEPMETHOD.<pkg> (not shown above) controls whether we use
1918 BUILD_DEPENDS or DEPENDS to add the dependency on <pkg>. The build
1919 dependency is selected by setting BUILDLINK_DEPMETHOD.<pkg> to
1920 "build". By default, the full dependency is used.
1922 (4) BUILDLINK_INCDIRS.<pkg> and BUILDLINK_LIBDIRS.<pkg> (not shown above)
1923 are lists of subdirectories of ${BUILDLINK_PREFIX.<pkg>} to add the
1924 header and library search paths. These default to "include" and
1927 (5) BUILDLINK_CPPFLAGS.<pkg> (not shown above) is the list of
1928 preprocessor flags to add to CPPFLAGS, which are passed on to the
1929 configure and build phases. The "-I" option should be avoided and
1930 instead be handled using BUILDLINK_INCDIRS.<pkg> as above.
1932 The following variables are all optionally defined within this second
1933 section (protected against multiple inclusion) and control which package
1934 files are symlinked into ${BUILDLINK_DIR} and how their names are
1935 transformed during the symlinking:
1937 (6) BUILDLINK_FILES.<pkg> (not shown above) is a shell glob pattern
1938 relative to ${BUILDLINK_PREFIX.<pkg>} to be symlinked into
1939 ${BUILDLINK_DIR}, e.g. include/*.h
1941 (7) BUILDLINK_FILES_CMD.<pkg> (not shown above) is a shell pipeline that
1942 outputs to stdout a list of files relative to
1943 ${BUILDLINK_PREFIX.<pkg>}. The resulting files are to be symlinked
1944 into ${BUILDLINK_DIR}. By default, this takes the +CONTENTS of a
1945 <pkg> and filters it through ${BUILDLINK_CONTENTS_FILTER.<pkg>}.
1947 (8) BUILDLINK_CONTENTS_FILTER.<pkg> (not shown above) is a filter command
1948 that filters +CONTENTS input into a list of files relative to
1949 ${BUILDLINK_PREFIX.<pkg>} on stdout. By default for overwrite
1950 packages, BUILDLINK_CONTENTS_FILTER.<pkg> outputs the contents of
1951 the include and lib directories in the package +CONTENTS, and for
1952 pkgviews packages, it outputs any libtool archives in lib
1955 (9) BUILDLINK_TRANSFORM.<pkg> (not shown above) is a list of sed
1956 arguments used to transform the name of the source filename into a
1957 destination filename, e.g. -e "s|/curses.h|/ncurses.h|g"
1959 The last section includes any buildlink3.mk needed for <pkg>'s library
1960 dependencies. Including these buildlink3.mk files means that the headers
1961 and libraries for these dependencies are also symlinked into
1962 ${BUILDLINK_DIR} whenever the <pkg> buildlink3.mk file is included.
1965 8.3.2 Updating BUILDLINK_DEPENDS.<pkg> in buildlink3.mk files
1966 =============================================================
1968 There are two situations that require increasing the dependency listed
1969 in BUILDLINK_DEPENDS.<pkg> after a package update:
1971 (1) if the sonames (major number of the library version) of any installed
1972 shared libraries change;
1974 (2) if the API or interface to the header files change.
1976 In these cases, BUILDLINK_DEPENDS.<pkg> should be adjusted to require at
1977 least the new package version. In some cases, the packages that depend
1978 on this new version may need their PKGREVISIONs increased and, if they
1979 have buildlink3.mk files, their BUILDLINK_DEPENDS.<pkg> adjusted, too.
1980 This is needed so that binary packages made using it will require the
1981 correct package dependency and not settle for an older one which will not
1982 contain the necessary shared libraries.
1984 Please take careful consideration before adjusting BUILDLINK_DEPENDS.<pkg>
1985 as we don't want to cause unneeded package deletions and rebuilds. In
1986 many cases, new versions of packages work just fine with older
1987 dependencies. See section 11 for more information about dependencies on
1988 other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED
1992 8.4 Writing builtin.mk files
1993 ============================
1995 Some packages in pkgsrc install headers and libraries that coincide with
1996 headers and libraries present in the base system. Aside from a
1997 buildlink3.mk file, these packages should also include a builtin.mk file
1998 that includes the necessary checks to decide whether using the built-in
1999 software or the pkgsrc software is appropriate.
2001 The only requirements of a builtin.mk file for <pkg> are:
2003 (1) It should set USE_BUILTIN.<pkg> to either "yes" or "no" after it
2006 (2) It should *not* override any USE_BUILTIN.<pkg> which is already
2007 set before the builtin.mk file is included.
2009 (3) It should be written to allow multiple inclusion. This is _very_
2010 important and takes careful attention to Makefile coding.
2013 8.4.1 Anatomy of a builtin.mk file
2014 ==================================
2016 The following is the recommended template for builtin.mk files:
2018 -------------8<-------------8<-------------8<-------------8<-------------
2019 .if !defined(IS_BUILTIN.foo)
2021 # IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
2022 # genuinely exists in the system or not.
2026 # BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
2027 # version can be determined.
2029 . if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
2030 BUILTIN_PKG.foo?= foo-1.0
2032 .endif # IS_BUILTIN.foo
2034 .if !defined(USE_BUILTIN.foo)
2035 USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
2036 . if defined(BUILTIN_PKG.foo)
2037 . for _depend_ in ${BUILDLINK_DEPENDS.foo}
2038 . if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
2040 if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \
2048 .endif # USE_BUILTIN.foo
2050 CHECK_BUILTIN.foo?= no
2051 .if !empty(CHECK_BUILTIN.foo:M[nN][oO])
2053 # Here we place code that depends on whether USE_BUILTIN.foo is set to
2056 .endif # CHECK_BUILTIN.foo
2057 -------------8<-------------8<-------------8<-------------8<-------------
2059 The first section sets IS_BUILTIN.<pkg> depending on if <pkg> really exists
2060 in the base system. This should not be a base system software with similar
2061 functionality to <pkg>; it should only be "yes" if the actual package is
2062 included as part of the base system. This variable is only used internally
2063 within the builtin.mk file.
2065 The second section sets BUILTIN_PKG.<pkg> to the version of <pkg> in the
2066 base system if it exists (if IS_BUILTIN.<pkg> is "yes"). This variable
2067 is only used internally within the builtin.mk file.
2069 The third section sets USE_BUILTIN.<pkg> and is _required_ in all
2070 builtin.mk files. The code in this section must make the determination
2071 whether the built-in software is adequate to satisfy the dependencies
2072 listed in BUILDLINK_DEPENDS.<pkg>. This is typically done by comparing
2073 BUILTIN_PKG.<pkg> against each of the dependencies in
2074 BUILDLINK_DEPENDS.<pkg>. USE_BUILTIN.<pkg> _must_ be set to the correct
2075 value by the end of the builtin.mk file. Note that USE_BUILTIN.<pkg> may
2076 be "yes" even if IS_BUILTIN.<pkg> is "no" because we may make the
2077 determination that the built-in version of the software is similar enough
2078 to be used as a replacement.
2080 The last section is guarded by CHECK_BUILTIN.<pkg>, and includes code that
2081 uses the value of USE_BUILTIN.<pkg> set in the previous section. This
2082 typically includes, e.g., adding additional dependency restrictions and
2083 listing additional files to symlink into ${BUILDLINK_DIR} (via
2084 BUILDLINK_FILES.<pkg>).
2087 8.4.2 Global preferences for native or pkgsrc software
2088 ======================================================
2090 When building packages, it's possible to choose whether to set a global
2091 preference for using either the built-in (native) version or the pkgsrc
2092 version of software to satisfy a dependency. This is controlled by setting
2093 PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either
2094 "yes", "no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use
2095 the pkgsrc versions of software, while PREFER_NATIVE tells pkgsrc to use
2096 the built-in versions. Preferences are determined by the most specific
2097 instance of the package in either PREFER_PKGSRC or PREFER_NATIVE. If a
2098 package is specified in neither or in both variables, then PREFER_PKGSRC
2099 has precedence over PREFER_NATIVE. For example, to require using pkgsrc
2100 versions of software for all but the most basic bits on a NetBSD system,
2104 PREFER_NATIVE= getopt skey tcp_wrappers
2106 A package _must_ have a builtin.mk file to be listed in PREFER_NATIVE,
2107 otherwise it is simply ignored in that list.
2113 Many packages have the ability to be built to support different sets
2114 of features. bsd.options.mk is a pkgsrc framework that provides
2115 generic handling of those options that determine different ways in
2116 which the packages can be built. It's possible for the user to specify
2117 exactly which sets of options will be built into a package or to allow
2118 a set of global default options apply.
2121 9.1 Global default options
2122 ==========================
2124 Global default options are listed in PKG_DEFAULT_OPTIONS, which is a
2125 list of the options that should be built into every package if that
2126 option is supported. This variable should be set in /etc/mk.conf.
2129 9.2 Converting packages to use bsd.options.mk
2130 =============================================
2132 The following example shows how bsd.options.mk should be use in a package
2133 Makefile, or in a file, e.g. options.mk, that is included by the main
2136 -------------8<-------------8<-------------8<-------------8<-------------
2137 # Global and legacy options
2138 .if defined(WIBBLE_USE_OPENLDAP) && !empty(WIBBLE_USE_OPENLDAP:M[yY][eE][sS])
2139 PKG_DEFAULT_OPTIONS+= ldap
2141 .if defined(USE_SASL2) && !empty(USE_SASL2:M[yY][eE][sS])
2142 PKG_DEFAULT_OPTIONS+= sasl
2145 PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
2146 PKG_SUPPORTED_OPTIONS= ldap sasl
2148 # Default options for "wibble" package.
2150 .if !defined(PKG_OPTIONS.wibble)
2151 PKG_DEFAULT_OPTIONS+= sasl
2153 .include "../../mk/bsd.options.mk"
2155 # Package-specific option-handling
2160 .if !empty(PKG_OPTIONS:Mldap)
2161 . include "../../databases/openldap/buildlink3.mk"
2162 CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap}
2166 ### SASL authentication
2168 .if !empty(PKG_OPTIONS:Msasl)
2169 . include "../../security/cyrus-sasl2/buildlink3.mk"
2170 CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl}
2172 # -------------8<-------------8<-------------8<-------------8<-------------
2174 The first section only exists if you are converting a package that
2175 had its own ad-hoc options handling to use bsd.options.mk. It converts
2176 global or legacy options variables into an equivalent PKG_OPTIONS.<pkg>
2177 value. These sections will be removed over time as the old options
2178 are in turn deprecated and removed.
2180 The second section contains the information about which build options
2181 are supported by the package, and any default options settings if
2184 (1) PKG_OPTIONS_VAR is a list of the name of the make(1) variables
2185 that contain the options the user wishes to select. The
2186 recommended value is "PKG_OPTIONS.<pkg>" but any package-specific
2187 value may be used. This variable should be set in a package
2190 (2) PKG_SUPPORTED_OPTIONS is a list of build options supported by
2191 the package. This variable should be set in a package Makefile.
2193 (3) ${PKG_OPTIONS_VAR} (the variables named in PKG_OPTIONS_VAR) are
2194 variables that list the selected build options and override any
2195 default options given in PKG_DEFAULT_OPTIONS. If any of the
2196 options begin with a '-', then that option is always removed
2197 from the selected build options, e.g.
2199 PKG_DEFAULT_OPTIONS= kerberos ldap sasl
2200 PKG_OPTIONS_VAR= WIBBLE_OPTIONS
2201 WIBBLE_OPTIONS= ${PKG_DEFAULT_OPTIONS} -sasl
2202 # implies PKG_OPTIONS == "kerberos ldap"
2206 PKG_OPTIONS_VAR= WIBBLE_OPTIONS
2207 WIBBLE_OPTIONS= kerberos -ldap ldap
2208 # implies PKG_OPTIONS == "kerberos"
2210 This variable should be set in /etc/mk.conf.
2212 After the inclusion of bsd.options.mk, the following variables are set:
2214 * PKG_OPTIONS contains the list of the selected build options,
2215 properly filtered to remove unsupported and duplicate options.
2217 The remaining sections contain the logic that is specific to each
2218 option. There should be a check for every option listed in
2219 PKG_SUPPORTED_OPTIONS, and there should be clear documentation on what
2220 turning on the option will do in the comments preceding each section.
2221 The correct way to check for an option is to check whether it is listed
2228 To check out all the gotchas when building a package, here are the steps
2229 that I do in order to get a package working. Please note this is basically
2230 the same as what was explained in the previous sections, only with some
2233 * Make sure PKG_DEVELOPER=1 is in /etc/mk.conf
2234 * Create a new directory, and run
2236 # url2pkg http://www.example.com/path/to/distfile.tar.gz
2238 You'll need to have pkgsrc/pkgtools/url2pkg installed for that.
2239 * Edit the Makefile as requested.
2241 * ``make configure''
2242 * Add any dependencies glimpsed from the configure step to the package's
2244 * Make the package compile, doing multiple rounds of
2247 # pkgvi ${WRKSRC}/some/file/that/does/not/compile
2250 # mv ${WRKDIR}/.newpatches/* patches
2253 [ mkpatches, patchdiff and pkgvi are from pkgsrc/pkgtools/pkgdiff ]
2255 Doing as non-root user will assure that no files are modified that
2256 shouldn't, esp. not during the build phase.
2257 * Look at Makefile, fix if necessary; see section 4.1.
2261 # make print-PLIST > PLIST
2266 You usually need to be root to do this.
2267 * Look if there are any files left:
2271 If this brings up any files that are missing in PLIST, add them.
2272 * Now that the PLIST is ok, install the package again and make a binary
2275 # make reinstall && make package
2277 * Delete the installed package:
2281 * Repeat the above find command, which shouldn't find anything now:
2285 * Reinstall the binary package:
2287 # pkg_add ..../blub.tgz
2289 * Play with it. Make sure everything works.
2290 * Run pkglint from pkgsrc/pkgtools/pkglint, and fix the problems it reports.
2294 * Submit (or commit, if you have cvs access); see section 11.
2297 11 FAQs & features of the package system
2298 ========================================
2300 11.1 Packages using GNU autoconf
2301 ================================
2303 If your package uses GNU autoconf created configure scripts, add the following
2304 to your package's Makefile:
2308 Note that this appends --prefix=${PREFIX} to CONFIGURE_ARGS, so you don't
2309 have to do that yourself, and this may not be what you want.
2312 11.2 Other distrib methods than .tar.gz
2313 =======================================
2315 If your package uses a different distribution method from .tar.gz, take a
2316 look at the package for pkgsrc/editors/sam, which uses a gzipped shell archive
2317 (shar), but the quick solution is to set EXTRACT_SUFX to the name after the
2318 DISTNAME field, and add the following to your package's Makefile:
2320 EXTRACT_SUFX= .msg.gz
2321 EXTRACT_CMD= zcat -d < ${DOWNLOADED_DISTFILE} | ${SH}
2324 11.3 Packages not creating their own subdirectory
2325 =================================================
2327 Your package doesn't create a subdirectory for itself (like GNU software
2328 does, for instance), but extracts itself in the current directory: see
2329 pkgsrc/editors/sam again, but the quick answer is:
2333 Please note that the old
2337 has been deprecated and should not be used.
2340 11.4 Custom configuration process
2341 =================================
2343 Your package uses a weird Configure script: See the top package, but the
2347 CONFIGURE_SCRIPT= Configure
2348 CONFIGURE_ARGS+= netbsd13
2351 11.5 Packages not building in their DISTNAME directory
2352 ======================================================
2354 Your package builds in a different directory from its base DISTNAME - see
2355 tcl and tk packages:
2357 WRKSRC= ${WRKDIR}/${DISTNAME}/unix
2360 11.6 How to fetch all distfiles at once
2361 =======================================
2363 You would like to download all the distfiles in a single batch from work or
2364 university, where you can't run a "make fetch". But there's no archive of
2365 the distfiles on ftp.netbsd.org and the one on ftp.freebsd.org contains
2366 many distfiles for which there are no ports (yet).
2368 The answer here is to do a "make fetch-list" in /usr/pkgsrc, carry the
2369 resulting list to your machine at work/school and use it there. If you don't
2370 have a NetBSD-compatible ftp(1) (like lukemftp) at work, don't forget to
2371 set FETCH_CMD to something that fetches an URL:
2376 % make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh
2377 % scp /tmp/fetch.sh work:/tmp
2382 % tar up /tmp/distfiles and take it home
2384 If you have a machine running NetBSD, and you want to get *all* distfiles
2385 (even ones that aren't for your machine architecture), you can do so by
2386 using the above-mentioned 'make fetch-list'-approach, or fetch the distfiles
2389 % make mirror-distfiles
2391 If you even decide to ignore NO_{SRC,BIN}_ON_{FTP,CDROM}, then you can
2392 get all & everything by typing
2394 % make fetch NO_SKIP=yes
2397 11.7 How to fetch files from behind a firewall
2398 ==============================================
2400 If you are sitting behind a firewall which does not allow direct connections
2401 to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts.
2402 This is done using an environment variable in the form of a URL
2403 e.g. in Amdahl, the machine orpheus.amdahl.com is one of the firewalls, and
2404 it uses port 80 as the proxy port number. So the proxy environment
2405 variables look like:
2407 ftp_proxy=ftp://orpheus.amdahl.com:80/
2408 http_proxy=http://orpheus.amdahl.com:80/
2411 11.8 If your patch contains an RCS ID
2412 =====================================
2414 See section 4.3 on how to remove RCS IDs from patch files.
2417 11.9 How to pull in variables from /etc/mk.conf
2418 ===============================================
2420 The problem with package-defined variables that can be overridden via
2421 MAKECONF or /etc/mk.conf is that make(1) expands a variable as it is
2422 used, but evaluates preprocessor like statements (.if, .ifdef and
2423 .ifndef) as they are read. So, to use any variable (which may be set
2424 in /etc/mk.conf) in one of the .if* statements, the file /etc/mk.conf
2425 must be included before that .if* statement.
2427 Rather than have a number of ad-hoc ways of including /etc/mk.conf,
2428 should it exist, or MAKECONF, should it exist, include the
2429 pkgsrc/mk/bsd.prefs.mk file in the package Makefile before any
2430 preprocessor-like .if, .ifdef, or .ifndef statements:
2432 .include "../../mk/bsd.prefs.mk"
2434 .if defined(USE_MENUS)
2438 If you wish to set the CFLAGS variable in /etc/mk.conf please make sure
2441 CFLAGS+= -your -flags
2443 Using 'CFLAGS=' (ie without the '+') may lead to problems with packages
2444 that need to add their own flags. Also, you may want to take a look at
2445 the devel/cpuflags package, if you're interested in optimization for the
2449 11.10 Is there a mailing list for pkg-related discussion?
2450 =========================================================
2452 Yes. We are using tech-pkg@NetBSD.org for discussing package related
2453 issues. To subscribe do:
2455 % echo subscribe tech-pkg | mail majordomo@netbsd.org
2458 11.11 How do i tell "make fetch" to do passive FTP?
2459 ===================================================
2461 This depends on which utility is used to retrieve distfiles. From
2462 bsd.pkg.mk, FETCH_CMD is assigned the first available command from the
2466 ${LOCALBASE}/bsd/bin/ftp
2469 On a default NetBSD install, this will be /usr/bin/ftp, which automatically
2470 tries passive connections first, and falls back to active connections if the
2471 server refuses to do passive. For the other tools, add the following to your
2472 /etc/mk.conf file: PASSIVE_FETCH=1
2474 Having that option present will prevent /usr/bin/ftp from falling back to
2478 11.12 Dependencies on other packages
2479 ====================================
2481 Your package may depend on some other package being present - and there are
2482 various ways of expressing this dependency. NetBSD supports the
2483 BUILD_DEPENDS and DEPENDS definitions, as well as dependencies via
2484 buildlink3.mk (see section 8).
2486 The basic difference between the two definitions is as follows: The
2487 DEPENDS definition registers that pre-requisite in the binary package,
2488 whilst the BUILD_DEPENDS definition does not.
2490 This means that if you only need a package present whilst you are building,
2491 it should be noted as a BUILD_DEPENDS.
2493 The format for a BUILD_DEPENDS and a DEPENDS definition is:
2495 <pre-req-package-name>:../../<category>/<pre-req-package>
2497 Please note that the "pre-req-package-name" may include any of the wildcard
2498 version numbers recognised by pkg_info(1).
2500 (a) If your package needs to use another package to build itself, this
2501 is specified using the BUILD_DEPENDS definition.
2503 BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
2505 (b) If your package needs a library with which to link, this is specified
2506 using the DEPENDS definition. An example of this is the pkgsrc/print/lyx
2507 package, which uses the xpm library, version 3.4j to build.
2509 DEPENDS+= xpm-3.4j:../../graphics/xpm
2511 You can also use wildcards in package dependences:
2513 DEPENDS+= xpm-[0-9]*:../../graphics/xpm
2515 Note that such wildcard dependencies are retained when creating binary
2516 packages. The dependency is checked when installing the binary
2517 package and any package which matches the pattern will be used.
2518 Wildcard dependencies should be used with care.
2520 The -[0-9]* should be used instead of -* to avoid potentially
2521 ambiguous matches such as tk-postgresql matching a tk-* DEPEND.
2523 Wildcards can also be used to specify that a package will only build against
2524 a certain minimum version of a pre-requisite:
2526 DEPENDS+= tiff>=3.5.4:../../graphics/tiff
2528 This means that the package will build against version 3.5.4 of the tiff library
2529 or newer. Such a dependency may be warranted if, for example, the API of the
2530 library has changed with version 3.5.4 and a package would not compile against
2531 an earlier version of tiff.
2533 Please note that such dependencies should only be updated if a package requires
2534 a newer pre-requisite, but not to denote recommendations such as security
2535 updates or ABI changes that do not prevent a package from building correctly.
2536 Such recommendations can be expressed using RECOMMENDED:
2538 RECOMMENDED+= tiff>=3.6.1:../../graphics/tiff
2540 In addition to the above DEPENDS line, this denotes that while a package will
2541 build against tiff>=3.5.4, at least version 3.6.1 is recommended. RECOMMENDED
2542 entries will be turned into dependencies unless explicitly ignored (in which
2543 case a warning will be printed). Packages that are built with recommendations
2544 ignored may not be uploaded to ftp.netbsd.org by developers and should not be
2545 used across different systems that may have different versions of binary
2548 For security fixes, please update the package vulnerabilities file as well as
2549 setting RECOMMENDED (see section 11.21 for more information). Also, if
2550 applicable, please submit for pullup to the stable branch.
2552 (c) If your package needs some executable to be able to run correctly, this
2553 is specified using the DEPENDS definition. The pkgsrc/print/lyx package needs
2554 to be able to execute the latex binary from the teTeX package when it runs,
2555 and that is specified:
2557 DEPENDS+= teTeX-[0-9]*:../../print/teTeX
2559 The comment about wildcard dependencies from previous paragraph
2562 If your package needs files from another package to build, see the
2563 first part of the "do-configure" target pkgsrc/print/ghostscript5 package
2564 (it relies on the jpeg sources being present in source form during the
2567 if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \
2568 cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} extract; \
2571 If you build any other packages that way, please make sure the working
2572 files are deleted too when this package's working files are cleaned up.
2573 The easiest way to do so is by adding a pre-clean target:
2576 cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} clean
2578 Please also note the BUILD_USES_MSGFMT and BUILD_USES_GETTEXT_M4 definitions,
2579 which are provided as convenience definitions. The former works out whether
2580 msgfmt(1) is part of the base system, and, if it isn't, installs the
2581 pkgsrc/devel/gettext package. The latter adds a build dependency on either an
2582 installed version of an older gettext package, or if it isn't, installs the
2583 pkgsrc/devel/gettext-m4 package.
2586 11.13 Conflicts with other packages
2587 ===================================
2589 Your package may conflict with other packages a user might already have
2590 installed on his system, e.g. if your package installs the same set of
2591 files like another package in our pkgsrc tree.
2593 In this case you can set CONFLICTS to a space separated list of packages
2594 (including version string) your package conflicts with.
2596 For example pkgsrc/x11/Xaw3d and pkgsrc/x11/Xaw-Xpm install provide the
2597 same shared library, thus you set in pkgsrc/x11/Xaw3d/Makefile:
2599 CONFLICTS= Xaw-Xpm-[0-9]*
2601 and in pkgsrc/x11/Xaw-Xpm/Makefile:
2603 CONFLICTS= Xaw3d-[0-9]*
2605 Packages will automatically conflict with other packages with the name prefix
2606 and a different version string. "Xaw3d-1.5" e.g. will automatically conflict
2607 with the older version "Xaw3d-1.3".
2610 11.14 Software which has a WWW Home Page
2611 ========================================
2613 The NetBSD packages system now supports a variable called HOMEPAGE.
2614 If the software being packaged has a home page, the Makefile should
2615 include the URL for that page in the HOMEPAGE variable. The definition
2616 of the variable should be placed immediately after the MAINTAINER
2620 11.15 How to handle modified distfiles with the 'old' name
2621 ==========================================================
2623 Sometimes authors of a software package make some modifications after the
2624 software was released, and they put up a new distfile without changing the
2625 package's version number. If a package is already in pkgsrc at that time,
2626 the md5 checksum will no longer match. The correct way to work around this
2627 is to update the package's md5 checksum to match the package on the master
2628 site (beware, any mirrors may not be up to date yet!), and to remove the
2629 old distfile from ftp.netbsd.org's /pub/NetBSD/packages/distfiles directory.
2630 Furthermore, a mail to the package's author seems appropriate making sure
2631 the distfile was really updated on purpose, and that no trojan horse or so
2635 11.16 What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
2636 =========================================================================
2638 When compiling the pkgsrc/pkgtools/pkg_install package, you get the error
2639 from make that it doesn't know how to make /usr/share/tmac/tmac.andoc? This
2640 indicates that you don't have installed the "text" set on your machine
2641 (nroff, ...). It is recommended that you do that.
2643 In the case of the pkg_install package, you can get away with setting
2644 NOMAN=YES either in the environment or in /etc/mk.conf.
2647 11.17 How to handle incrementing versions when fixing an existing package
2648 =========================================================================
2650 When making fixes to an existing package it can be useful to change
2651 the version number in PKGNAME. To avoid conflicting with future versions
2652 by the original author, a 'nb1' ('nb2', ...) suffix can be used on package
2653 versions by setting PKGREVISION=1 (2,. ..). The "nb" is treated like a "."
2654 by the pkg tools. E.g.
2659 will result in a PKGNAME of foo-17.42nb9.
2661 When a new release of the package is released, the PKGREVISION should be
2662 removed. E.g. on a new minor release of the above package, things should
2668 11.18 "Could not find bsd.own.mk" - what's wrong?
2669 =================================================
2671 You didn't install the compiler set, comp.tgz, when you installed your
2672 NetBSD machine. Please get it and install it, by extracting it in /:
2674 # tar --unlink -pvxf .../comp.tgz
2676 comp.tgz is part of every NetBSD release, please get the one matching
2677 the release you have installed (determine via "uname -r").
2680 11.19 Restricted packages
2681 =========================
2683 Some licenses restrict how software may be re-distributed. In order to
2684 satisfy these restrictions, the package system defines five make variables
2685 that can be set to note these restrictions:
2688 This variable should be set whenever a restriction exists
2689 (regardless of its kind). Set this variable to a string
2690 containing the reason for the restriction.
2693 Binaries may not be placed on CD-ROM. Set this variable to
2694 ${RESTRICTED} whenever a binary package may not be included
2698 Binaries may not be placed on an ftp server. Set this
2699 variable to ${RESTRICTED} whenever a binary package may not
2700 not be made available on the Internet.
2703 Distfiles may not be placed on CD-ROM. Set this variable to
2704 ${RESTRICTED} if re-distribution of the source code or other
2705 distfile(s) is not allowed on CD-ROMs.
2708 Distfiles may not be placed on FTP. Set this variable to
2709 ${RESTRICTED} if re-distribution of the source code or other
2710 distfile(s) via the Internet is not allowed.
2712 Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic
2713 make variables to denote restrictions is deprecated, because they
2714 unconditionally prevent users from generating binary packages!
2717 11.20 Packages using (n)curses
2718 ==============================
2720 Some packages need curses functionality that wasn't present in NetBSD's own
2721 curses prior to 1.4Y.
2723 If ../../devel/ncurses/buildlink3.mk is included in a package's Makefile,
2724 then a curses library and headers with ncurses functionality are linked
2725 into ${BUILDLINK_DIR} at pre-configure time. If ncurses is actually
2726 required, then define USE_NCURSES in the package's Makefile:
2728 USE_NCURSES= # KEY_RESIZE
2730 The comment should indicate which functions are missing.
2733 11.21 Automated security check
2734 ==============================
2736 Please be aware that there can often be bugs in third-party software,
2737 and some of these bugs can leave a machine vulnerable to exploitation
2738 by attackers. In an effort to lessen the exposure, the NetBSD
2739 packages team maintains a database of known-exploits to packages which
2740 have at one time been included in pkgsrc. The database can be
2741 downloaded automatically, and a security audit of all packages
2742 installed on a system can take place. To do this, install the
2743 pkgsrc/security/audit-packages package. It has two components:
2745 (1) download-vulnerability-list, an easy way to download a list of the
2746 security vulnerabilities information. This list is kept up to date by
2747 the NetBSD security officer and the NetBSD packages team, and is
2748 distributed from the NetBSD ftp server:
2750 ftp://ftp.netbsd.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities
2752 (2) audit-packages, an easy way to audit the current machine, checking
2753 each vulnerability which is known. If a vulnerable package is
2754 installed, it will be shown by output to stdout, including a
2755 description of the type of vulnerability, and a URL containing more
2758 Use of the audit-packages package is strongly recommended.
2760 The following message is displayed as part of the audit-packages
2761 installation procedure:
2763 ======================================================================
2764 You may wish to have the vulnerabilities file downloaded daily so that
2765 it remains current. This may be done by adding an appropriate entry
2766 to the root users crontab(5) entry. For example the entry
2768 # download vulnerabilities file
2769 0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1
2771 will update the vulnerability list every day at 3AM.
2773 In addition, you may wish to run the package audit from the daily
2774 security script. This may be accomplished by adding the following
2775 lines to /etc/security.local
2777 if [ -x ${PREFIX}/sbin/audit-packages ]; then
2778 ${PREFIX}/sbin/audit-packages
2780 ======================================================================
2783 Note to package developers: When a vulnerability is found, this should
2784 be noted in localsrc/security/advisories/pkg-vulnerabilities, and after
2785 the commit of that file, it should be copied to both
2786 /pub/NetBSD/packages/distfiles/pkg-vulnerabilities and vulnerabilities
2787 on ftp.netbsd.org by localsrc/security/advisories/Makefile. In addition,
2788 if a buildlink3.mk file exists for an affected package, bumping PKGREVISION
2789 and creating a corresponding BUILDLINK_RECOMMENDED.<pkg> entry should
2790 be considered. See section 8 for more information about writing
2791 buildlink3.mk files and BUILDLINK_* definitions. Also if the fix should
2792 be made in the stable pkgsrc branch, be sure to submit a pullup request.
2795 11.22 What's the proper way to create an account from a package?
2796 ================================================================
2798 There are two make variables used to control the creation of package-specific
2799 groups and users at pre-install time. The first is PKG_GROUPS, which is a
2800 list of group[:groupid] elements, where the groupid is optional. The second
2801 is PKG_USERS, which is a list of elements of the form:
2803 user:group[:[userid][:[description][:[home][:shell]]]]
2805 where only the user and group are required, the rest being optional. A
2808 PKG_GROUPS= foogroup
2809 PKG_USERS= foouser:foogroup
2811 A more complex example is that creates two groups and two users is:
2813 PKG_GROUPS= group1 group2:1005
2814 PKG_USERS= first:group1::First\\ User \
2815 second:group2::Second\\ User:/home/second:${SH}
2817 By default, a new user will have home directory /nonexistent, and login shell
2818 /sbin/nologin unless they are specified as part of the user element.
2820 The package Makefile must also set USE_PKGINSTALL to "YES" prior to the
2821 inclusion of bsd.pkg.mk. This will cause the users and groups to be created
2822 at pre-install time, and the admin will be prompted to remove them at
2823 post-deinstall time. Automatic creation of the users and groups can be
2824 toggled on and off by setting the environment variable PKG_CREATE_USERGROUP
2825 prior to package installation.
2828 11.23 How to handle compiler bugs
2829 =================================
2831 Some source files trigger bugs in the compiler, based on combinations
2832 of compiler version and architecture and almost always relation to
2833 optimisation being enabled. Common symptoms are gcc internal errors
2834 or never finishing compiling a file.
2836 Typically a workaround involves testing the MACHINE_ARCH and compiler
2837 version, disabling optimisation for that file/MACHINE_ARCH/compiler
2838 combination, and documenting it in doc/HACKS. See doc/HACKS for
2842 11.24 Packages providing info files
2843 ===================================
2845 Some packages install info files or use the makeinfo or install-info
2846 commands. Each of the info files:
2848 - is considered to be installed in the directory
2849 ${PREFIX}/${INFO_DIR};
2850 - is registered in the Info directory file
2851 ${PREFIX}/${INFO_DIR}/dir;
2852 - and must be listed as a filename in the INFO_FILES variable
2853 in the package Makefile.
2855 INFO_DIR defaults to `info' and can be overridden in the package Makefile.
2856 INSTALL and DEINSTALL scripts will be generated to handle the registration
2857 of the info files in the Info directory file.
2858 The install-info command (used for the info files registration) is either
2859 provided by the system or by a special purpose package automatically
2860 added as dependency if needed.
2862 A package which needs the makeinfo command at build time must define
2863 the variable USE_MAKEINFO in its Makefile. If a minimum version of
2864 the makeinfo command is needed, it should be noted with the
2865 TEXINFO_REQD variable in the package Makefile. By default a minimum
2866 version of 3.12 is required. If the system does not provide a
2867 makeinfo command or if it does not match the required minimum, a build
2868 dependency on the devel/gtexinfo package will be added automatically.
2870 The build and installation process of the software provided by the package
2871 should not use the install-info command as the registration of info files
2872 is the task of the package INSTALL script, and it must use the appropriate
2875 To achieve this goal the pkgsrc infrastructure creates overriding scripts
2876 for the install-info and makeinfo command in a directory listed early in PATH.
2878 The script overriding install-info has no effect except the logging of a
2879 message. The script overriding makeinfo logs a message and according to the
2880 value of USE_MAKEINFO and TEXINFO_REQD either run the appropriate makeinfo
2881 command or exit on error.
2883 11.25 Packages whose distfiles aren't available for plain downloading
2884 =====================================================================
2886 If you need to download from a dynamic URL you can set DYNAMIC_MASTER_SITES
2887 and a 'make fetch' will call files/getsite.sh with the name of each file
2888 to download as an argument, expecting it to output the URL of the directory
2889 from which to download it. graphics/ns-cult3d is an example of this usage.
2891 If the download can't be automated, because the user must submit personal
2892 information to apply for a password, or must pay for the source, or whatever,
2893 you can set _FETCH_MESSAGE to a macro which displays a message explaining
2894 the situation. _FETCH_MESSAGE must be executable shell commands, not just a
2895 message. (Generally, it executes ${ECHO}). As of this writing, the following
2896 packages use this: audio/realplayer, cad/simian, devel/ipv6socket,
2897 emulators/vmare-module, fonts/acroread-jpnfont, sysutils/storage-manager,
2898 www/ap-aolserver, www/openacs. Try to be consistent with them.
2901 11.26 Using pkgsrc on non-NetBSD (Darwin, FreeBSD, IRIX, Linux, OpenBSD, Solaris)
2902 =================================================================================
2904 In order to use pkgsrc on a non-NetBSD operating system, you must first
2905 bootstrap the necessary utilities (BSD make, pkg_*, ...). See
2906 http://www.netbsd.org/Documentation/software/packages.html#bootstrap
2907 for information on boostrapping. Binary bootstrap-kits are available from that
2908 URL as well. If your Operating System is not yet supported, we encourage you to
2909 port the bootstrap-kit and submit your changes.
2912 11.27 Configuration files handling and placement
2913 ================================================
2915 The global variable PKG_SYSCONFBASE (and some others) can be set by the
2916 system administrator in /etc/mk.conf to define the place where
2917 configuration files get installed. Therefore, packages must be adapted to
2918 support this feature. Keep in mind that you should only install files that
2919 are strictly necessary in the configuration directory, files that can
2920 go to $PREFIX/share should go there.
2922 We will take a look at available variables first (bsd.pkg.mk contains more
2923 information). PKG_SYSCONFDIR is where the configuration files for a package
2924 may be found (that is, the full path, e.g. /etc or /usr/pkg/etc). This
2925 value may be customized in various ways:
2927 1) PKG_SYSCONFBASE is the main config directory under which all package
2928 configuration files are to be found. Users will typically want to set
2929 it to /etc, or accept the default location of $PREFIX/etc.
2931 2) PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which
2932 the configuration files for a particular package may be found. Defaults
2935 3) PKG_SYSCONFVAR is the special suffix used to distinguish any overriding
2936 values for a particular package (see next item). It defaults to
2937 ${PKGBASE}, but for a collection of related packages that should all
2938 have the same PKG_SYSCONFDIR value, it can be set in each of the
2939 package Makefiles to a common value.
2941 4) PKG_SYSCONFDIR.${PKG_SYSCONFVAR} overrides the value of
2942 ${PKG_SYSCONFDIR} for packages with the same value for PKG_SYSCONFVAR.
2944 As an example, all the various KDE packages may want to set
2945 PKG_SYSCONFVAR to "kde" so admins can set ${PKG_SYSCONFDIR.kde} in
2946 /etc/mk.conf to define where to install KDE config files.
2948 Programs' configuration directory should be defined during the configure
2949 stage. Packages that use GNU autoconf can usually do this by using the
2950 --sysconfdir parameter, but this brings some problems as we will see now.
2951 When you change this pathname in packages, you should not allow them to
2952 install files in that directory directly. Instead they need to install
2953 those files under share/examples/${PKGNAME} so PLIST can register them.
2955 Once you have the required configuration files in place (under the
2956 share/examples directory) the variable CONF_FILES should be set to copy
2957 them into PKG_SYSCONFDIR. The contents of this variable is formed by pairs
2958 of filenames; the first element of the pair specifies the file inside the
2959 examples directory (registered by PLIST) and the second element specifies
2960 the target file. This is done this way to allow binary packages to place
2961 files in the right directory using INSTALL/DEINSTALL scripts which are
2962 created automatically. The package Makefile must also set USE_PKGINSTALL
2963 to "YES" prior to the inclusion of bsd.pkg.mk to use these automatically
2964 generated scripts. The automatic copying of config files can be toggled by
2965 setting the environment variable PKG_CONFIG prior to package installation.
2967 Here is an example, taken from mail/mutt/Makefile:
2969 EGDIR= ${PREFIX}/share/doc/mutt/samples
2970 CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
2972 As you can see, this package installs configuration files inside EGDIR,
2973 which are registered by PLIST. After that, the variable CONF_FILES lists
2974 the installed file first and then the target file. Users will also get an
2975 automatic message when files are installed using this method.
2978 11.28 Packages providing login shells
2979 =====================================
2981 If the purpose of the package is to provide a login shell, the variable
2982 PKG_SHELL should contain the full pathname of the shell executable installed
2983 by this package. The package Makefile also must set USE_PKGINSTALL to "YES"
2984 prior to the inclusion of bsd.pkg.mk to use the automatically generated
2985 INSTALL/DEINSTALL scripts.
2987 An example taken from shells/zsh:
2990 PKG_SHELL= ${PREFIX}/bin/zsh
2992 The shell is registered into /etc/shells file automatically in the
2993 post-install step by the auto-generated INSTALL script and removed in the
2994 deinstall step by the DEINSTALL script.
2997 11.29 Packages providing locale catalogues
2998 ==========================================
3000 If the package provides its own locale catalogues, the variable
3001 USE_PKGLOCALEDIR should be defined. It will ensure that the package's
3002 Makefile template files are fixed and point to the correct locale
3003 directories (which may vary, depending on OS), if necessary. See also
3004 section 5.1 for details about ${PKGLOCALEDIR}.
3007 11.30 Using 'sudo' with pkgsrc
3008 ==============================
3010 When installing packages as non-root user and using the just-in-time
3011 su(1) feature of pkgsrc, it can become annoying to type in the root
3012 password for each required package installed. To avoid this, the sudo
3013 package can be used, which does password caching over a limited time.
3014 To use it, install sudo (either as binary package or from
3015 pkgsrc/security/sudo) and then put the following into your /etc/mk.conf:
3017 .if exists(/usr/pkg/bin/sudo)
3018 SU_CMD=/usr/pkg/bin/sudo /bin/sh -c
3022 11.31 Packages that cannot or should not be built
3023 =================================================
3025 There are several reasons why a package might be instructed to not
3026 build under certain circumstances. If the package builds and runs
3027 on most platforms, the exceptions should be noted with NOT_FOR_PLATFORM.
3028 If the package builds and runs on a small handful of platforms,
3029 set ONLY_FOR_PLATFORM instead. If the package should be skipped
3030 (for example, because it provides functionality already provided
3031 by the system), set PKG_SKIP_REASON to a descriptive message. If
3032 the package should fail because some preconditions are not met,
3033 set PKG_FAIL_REASON to a descriptive message.
3035 IGNORE is deprecated because it didn't provide enough information
3036 to determine whether the build should fail.
3039 11.32 Packages which should not be deleted, once installed
3040 ==========================================================
3042 To ensure that a package may not be deleted, once it has been installed,
3043 the PKG_PRESERVE definition should be set in the package Makefile. This
3044 will be carried into any binary package that is made from this pkgsrc
3045 entry. A "preserved" package will not be deleted using pkg_delete(1),
3046 unless the "-f" option is used.
3048 11.33 Packages containing perl scripts
3049 ======================================
3051 If your package contains interpreted perl scripts, set REPLACE_PERL to
3052 ensure that the proper interpreter path is set. REPLACE_PERL should
3053 contain a list of scripts, relative to WRKSRC, that you want adjusted.
3056 11.34 Packages with hardcoded paths to other interpreters
3057 =========================================================
3059 Your package may also contain scripts with hardcoded paths to other
3060 interpreters besides (or as well as) perl. To correct the full
3061 pathname to the script interpreter, you need to set the following
3062 definitions in your Makefile (we shall use tclsh in this example):
3064 REPLACE_INTERPRETER+= tcl
3065 _REPLACE.tcl.old= .*/bin/tclsh
3066 _REPLACE.tcl.new= ${PREFIX}/bin/tclsh
3067 _REPLACE_FILES.tcl= ...list of tcl scripts which need to be fixed,
3068 relative to ${WRKSRC}, just as in REPLACE_PERL
3071 11.35 Utilities for package management (pkgtools)
3072 =================================================
3074 The directory pkgtools contains a number of useful utilities. This section
3075 attempts only to make the reader aware of the utilities and when they might
3076 be useful, and not to duplicate the documentation that comes with each
3079 Utilities used by pkgsrc (automatically installed when needed):
3080 x11-links - symlinks for use by buildlink
3082 OS tool augmentation (automatically installed when needed):
3083 digest - calculates SHA1 checksums (and other kinds)
3084 use on operating systems where pkg_install is not present
3085 libnbcompat - compat library for pkg tools
3086 mtree - installed on non-BSD systems due to lack of native mtree
3087 pkg_install - up-to-date replacement for /usr/sbin/pkg_install, or for
3089 Utilities used by pkgsrc (not automatically installed):
3090 pkg_tarup - create a binary package from an already-installed package.
3091 used by 'make replace' to save the old package
3092 xpkgwedge - put X11 packages someplace else (see above)
3094 Utilities for keeping track of installed packages, being up to date, etc:
3095 pkgchk - installs pkg_chk, which reports on packages whose installed
3096 versions do not match the latest pkgsrc entries
3097 pkgdep - makes dependency graphs of packages, to aid in choosing a
3098 strategy for updating
3099 pkgdepgraph - make graph from above (uses graphviz)
3100 pkglint - This provides two distinct abilities:
3101 check a pkgsrc entry for correctness (pkglint)
3102 check for and remove out-of-date distfiles and binary
3103 packages (lintpkgsrc)
3104 pkgsurvey - report what packages you have installed
3106 Utilities for people maintaining or creating individual packages:
3107 pkgdiff - automate making and maintaining patches for a package
3108 rpm2pkg, url2pkg - aids in converting to pkgsrc
3109 gensolpkg - convert pkgsrc to a Solaris package
3111 Utilities for people maintaining pkgsrc (or more obscure pkg utilities)
3112 pkgconflict - find packages that conflict but aren't marked as such
3113 pkgcomp - build packages in a chrooted area
3114 libkver - spoof kernel version for chrooted cross builds
3117 11.36 How to use pkgsrc as non-root?
3118 ====================================
3120 If you want to use pkgsrc as non-root user, you can set some variables
3121 to make pkgsrc work under these conditions. Please see
3122 http://mail-index.netbsd.org/tech-pkg/2003/09/27/0023.html
3126 11.37 Packages installing GConf2 data files
3127 ===========================================
3129 If a package installs .schemas or .entries files, used by GConf2, you need
3130 to take some extra steps to make sure they get registered in the database:
3132 1) Include "../../devel/GConf2/schemas.mk" instead of its buildlink[23].mk
3133 file. This takes care of rebuilding the GConf2 database at installation
3134 and deinstallation time, and tells the package where to install GConf2
3135 data files using some standard configure arguments. It also disallows
3136 any access to the database directly from the package.
3138 2) Ensure that the package installs its .schemas files under
3139 ${PREFIX}/share/gconf/schemas. If they get installed under ${PREFIX}/etc,
3140 you will need to manually patch the package. Please send your changes
3143 3) Check the PLIST and remove any entries under the etc/gconf directory,
3144 as they will be handled automatically. See section 11.27 for more
3147 4) Define the GCONF2_SCHEMAS variable in your Makefile with a list of all
3148 .schemas files installed by the package, if any. Names must not contain
3149 any directories in them.
3151 5) Define the GCONF2_ENTRIES variable in your Makefile with a list of all
3152 .entries files installed by the package, if any. Names must not contain
3153 any directories in them.
3156 11.38 Packages installing scrollkeeper data files
3157 =================================================
3159 If a package installs .omf files, used by scrollkeeper, you need to take some
3160 extra steps to make sure they get registered in the database:
3162 1) Include "../../textproc/scrollkeeper/omf.mk" instead of its
3163 buildlink[23].mk file. This takes care of rebuilding the scrollkeeper
3164 database at installation and deinstallation time, and disallows any
3165 access to it directly from the package.
3167 2) Check the PLIST and remove any entries under the libdata/scrollkeeper
3168 directory, as they will be handled automatically.
3170 3) Remove the share/omf directory from the PLIST. It will be handled by
3174 11.39 Packages installing X11 fonts
3175 ===================================
3177 If a package installs font files, you will need to rebuild the fonts database
3178 in the directory where they get installed at installation and deinstallation
3179 time. This can be automatically done by using mk/fonts.mk, which you need to
3180 include in your Makefile.
3182 When the file is included, you can list the directories where fonts are
3183 installed in the FONTS_<TYPE>_DIRS variables, where <TYPE> can be one of TTF,
3184 TYPE1 or X11. Also make sure that the database file "fonts.dir" is not listed
3187 Note that you should not create new directories for fonts; instead use the
3188 standard ones to avoid the user having the manually configure the X server
3192 11.40 Packages installing GTK2 modules
3193 ======================================
3195 If a package installs gtk2 immodules or loaders, you need to take some extra
3196 steps to get them registered in the GTK2 database properly:
3198 1) Include "../../x11/gtk2/modules.mk" instead of its buildlink[23].mk file.
3199 This takes care of rebuilding the database at installation and
3200 deinstallation time.
3202 2) Set GTK2_IMMODULES to YES if your package installs GTK2 immodules.
3204 3) Set GTK2_LOADERS to YES if your package installs GTK2 loaders.
3206 4) Patch the package to not touch any of the gtk2 databases directly. These
3209 * libdata/gtk-2.0/gdk-pixbuf.loaders
3210 * libdata/gtk-2.0/gtk.immodules
3212 4) Check the PLIST and remove any entries under the libdata/gtk-2.0 directory,
3213 as they will be handled automatically.
3216 11.41 Packages installing SGML or XML data
3217 ==========================================
3219 If a package installs SGML or XML data files that need to be registered in
3220 system-wide catalogs (like DTDs, sub-catalogs, etc.), you need to take some
3223 1) Include "../../textproc/xmlcatmgr/catalogs.mk" in your Makefile, which
3224 takes care of registering those files in system-wide catalogs at
3225 installation and deinstallation time.
3227 2) Set SGML_CATALOGS to the full path of any SGML catalogs installed by
3230 3) Set XML_CATALOGS to the full path of any XML catalogs installed by
3233 4) Set SGML_ENTRIES to individual entries to be added to the SGML catalog.
3234 These come in groups of three strings; see xmlcatmgr(1) for more
3235 information (specifically, arguments recognized by the 'add' action).
3236 Note that you will normally not use this variable.
3238 5) Set XML_ENTRIES to individual entries to be added to the XML catalog.
3239 These come in groups of three strings; see xmlcatmgr(1) for more
3240 information (specifically, arguments recognized by the 'add' action).
3241 Note that you will normally not use this variable.
3244 11.42 Packages using intltool
3245 =============================
3247 If a package uses intltool during its build, include the
3248 "../../textproc/intltool/buildlink3.mk" file, which forces it to use the
3249 intltool package provided by pkgsrc, instead of the one bundled with the
3252 This tracks intltool's build-time dependencies and uses the latest available
3253 version; this way, the package benefits of any bug fixes that may have appeared
3254 since it was released.
3257 11.43 How can I install/use XFree86 from pkgsrc?
3258 ================================================
3260 If you want to use XFree86 from pkgsrc instead of your system's own
3261 X11 (/usr/X11R6, /usr/openwin, ...), you will have to add the following
3266 11.44 How can I install/use X.org from pkgsrc?
3267 ==============================================
3269 If you want to use X.org from pkgsrc instead of your system's own
3270 X11 (/usr/X11R6, /usr/openwin, ...) you will have to add the following
3275 11.45 Where's the pkgviews documentation?
3276 =========================================
3278 Pkgviews is tightly integrated with buildlink. You can find a
3279 pkgviews User's Guide in pkgsrc/mk/buildlink3/PKGVIEWS_UG.
3282 11.46 How do I handle common shared directories?
3283 ================================================
3285 A "shared directory" is a directory where multiple (and unrelated)
3286 packages install files. These directories are problematic because
3287 you have to add special tricks in the PLIST to conditionally remove
3288 them, or have some centralized package handle them.
3290 Within pkgsrc, you'll find both approaches. If a directory is
3291 shared by a few unrelated packages, it's often not worth to add an
3292 extra package to remove it. Therefore, one simply does:
3294 @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE}
3296 in the PLISTs of all affected packages, instead of the regular "@dirrm" line.
3298 However, if the directory is shared across many packages, two different
3299 solutions are available:
3301 1) If the packages have a common dependency, the directory can be removed
3302 in that. For example, see textproc/scrollkeeper, which removes the
3303 shared directory share/omf.
3305 2) If the packages using the directory are not related at all (they have no
3306 common dependencies), a *-dirs package is used.
3308 From now on, we'll discuss the second solution. To get an idea of the
3309 *-dirs packages available, issue:
3314 Their use from other packages is very simple. The USE_DIRS variable takes
3315 a list of package names (without the -dirs part) together with the required
3316 version number (always pick the latest one when writting new packages).
3318 For example, if a package installs files under share/applications, it should
3319 have the following line in it:
3323 After regenerating the PLIST using 'make print-PLIST', you should get the
3324 right (commented out) lines.
3326 Note that, even if your package is using X11BASE, it must not depend on
3327 the *-x11-dirs packages. Just specify the name without that part and pkgsrc
3328 (in particular, mk/dirs.mk) will take care of it.
3331 11.47 How can I tweak 'make print-PLIST' output?
3332 ================================================
3334 If you have used any of the *-dirs packages, as explained in 11.45, you
3335 may have noticed that 'make print-PLIST' outputs a set of @comment's
3336 instead of real @dirrm lines. You can also do this for specific directories
3337 and files, so that the results of that command are very close to reality.
3338 This helps _a lot_ during the update of packages.
3340 The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that
3341 are used to filter the output of print-PLIST. You can _append_ any chunk
3342 of AWK scripting you like to it, but be careful with quoting.
3344 For example, to get all files inside the libdata/foo directory removed from
3345 the resulting PLIST:
3347 PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
3349 And to get all the @dirrm lines referring to a specific (shared) directory
3350 converted to @comment's:
3352 PRINT_PLIST_AWK+= /^@dirrm share\/special/ { print "@comment " $$0; next; }
3355 11.48 Packages that install score files
3356 =======================================
3358 Certain packages, most of them in the games category, install a score file
3359 that allows all users on the system to record their highscores. In order for
3360 this to work, the binaries need to be installed setgid and the score files
3361 owned by the appropriate group and/or owner (traditionally the "games"
3362 user/group). The following variables, documented in more detail in
3363 mk/bsd.pkg.defaults.mk, control this behaviour: SETGIDGAME, GAMEDATAMODE,
3364 GAMEGRP, GAMEMODE, GAMEOWN.
3366 Note that per default, setgid installation of games is disabled; setting
3367 SETGIDGAME=YES will set all the other variables accordingly.
3369 A package should therefor never hard code file ownership or access permissions
3370 but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly.
3373 11.49 Packages installing extensions to the MIME database
3374 =========================================================
3376 If a package provides extensions to the MIME database by installing .xml
3377 files inside ${PREFIX}/share/mime/packages, you need to take some extra
3378 steps to ensure that the database is kept consistent with respect to these
3381 1) Include "../../databases/shared-mime-info/mimedb.mk" (avoid using
3382 the buildlink3.mk file from this same directory, which is reserved
3383 for inclusion from other buildlink3.mk files). It takes care of
3384 rebuilding the MIME database at installation and deinstallation time,
3385 and disallows any access to it directly from the package.
3387 2) Check the PLIST and remove any entries under the share/mime directory,
3388 _except_ for files saved under share/mime/packages. The former are
3389 handled automatically by the update-mime-database program, but the
3390 later are package-dependent and must be removed by the package that
3391 installed them in the first place.
3393 3) Remove any share/mime/* directories from the PLIST. They will be
3394 handled by the shared-mime-info package.
3397 12 Submitting & Committing
3398 ==========================
3400 12.1 Submitting your packages
3401 =============================
3403 You have to separate between binary and "normal" (source) packages here:
3405 * precompiled binary packages:
3406 Our policy is that we accept binaries only from NetBSD developers to
3407 guarantee that the packages don't contain any trojan horses etc.
3408 This is not to piss anyone off but rather to protect our users!
3409 You're still free to put up your home-made binary packages and tell
3410 the world where to get them.
3413 First, check that your package is complete, compiles and runs well; see
3414 section 9 and the rest of this document. Next, generate an uuencoded
3415 gzipped tar(1) archive, preferably with all files in a single directory.
3416 Finally, send-pr(1) with category "pkg", a synopsis which includes the
3417 package name and version number, a short description of your package
3418 (contents of the COMMENT variable or DESCR file are OK) and attach the
3421 If you want to submit several packages, please send a separate PR for
3422 each one, it's easier for us to track things that way.
3424 Alternatively, you can also import new packages into pkgsrc-wip
3425 (pkgsrc work-in-progress); see the homepage at
3426 http://pkgsrc-wip.sourceforge.net/
3430 12.2 Committing: Importing the package into CVS
3431 ===============================================
3433 This section is only of interest for NetBSD developers with write
3434 access to the NetBSD pkgsrc repository. Please remember that cvs
3435 imports files relative to the cwd, and that the pathname that you
3436 give the "cvs import" command is so that it knows where to place
3437 the files in the repository. Newly created packages should be
3438 imported with a vendor tag of "TNF" and a release tag of "pkgsrc-base",
3441 % cd .../pkgsrc/<category>/<pkgname>
3442 % cvs import pkgsrc/<category>/<pkgname> TNF pkgsrc-base
3444 and remember to move the directory from which you imported out of
3445 the way, or cvs will complain the next time you "cvs update" your
3446 source tree. Also don't forget to add the new package to the
3447 category's Makefile.
3449 The commit message of the initial import should include part of the
3450 DESCR file, so people reading the mailing lists know what the package
3453 Please note all package updates/additions in pkgsrc/doc/CHANGES! It's very
3454 important to keep this file up to date and conforming to the existing
3455 format, because it will be used by scripts to automatically update pages on
3456 www.netbsd.org and other sites. Additionally, check the pkgsrc/doc/TODO
3457 file and remove the entry for the package you updated, in case it was
3460 For new packages, "cvs import" is preferred to "cvs add" because
3461 the former gets everything with a single command, and provides a
3465 12.3 Updating a Package to a Newer Version
3466 ==========================================
3468 Please always put a concise, appropriate and relevant summary of the
3469 changes between old and new versions into the commit log when updating
3470 a package. There are various reasons for this:
3472 + a URL is volatile, and can change over time. It may go away completely,
3473 or its information may be overwritten by newer information.
3475 + having the change information between old and new versions in our CVS
3476 repository is very useful for people who use either cvs or anoncvs.
3478 + having the change information between old and new versions in our CVS
3479 repository is very useful for people who read the pkgsrc-changes mailing
3480 list, so that they can make tactical decisions about when to upgrade
3483 Please also recognise that, just because a new version of a package
3484 has been released, it should not automatically be upgraded in the CVS
3485 repository. We prefer to be conservative in the packages that are
3486 included in pkgsrc - development or beta packages are not really the
3487 best thing for most places in which pkgsrc is used. Please use your
3488 judgement about what should go into pkgsrc, and bear in mind that
3489 stability is to be preferred above new and possibly untested features.
3492 12.4 Moving a Package in pkgsrc
3493 ===============================
3495 1. Make a copy of the directory somewhere else.
3496 2. Remove all CVS dirs.
3497 Alternatively to the first two steps you can also do:
3498 cvs -d user@cvs.netbsd.org:/cvsroot export -D today pkgsrc/category/package
3499 and use that for further work.
3500 3. Fix CATEGORIES and any DEPENDS paths that just did ../package
3501 instead of ../../category/package.
3502 4. "cvs import" the modified package in the new place.
3503 5. Check if any package depends on it:
3505 grep /package */*/Makefile* */*/buildlink*
3506 6. Fix paths in packages from step 5 to point to new location.
3507 7. "cvs rm (-f)" the package at the old location.
3508 8. Remove from oldcategory/Makefile.
3509 9. Add to newcategory/Makefile.
3510 10. Commit the changed and removed files:
3511 cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile
3512 and any packages from step 5, of course.
3515 13 A simple example of a package: bison
3516 =======================================
3518 I checked to find a piece of software that wasn't in the packages
3519 collection, and picked GNU bison. Quite why someone would want to have
3520 bison when Berkeley yacc is already present in the tree is beyond me, but
3521 it's useful for the purposes of this exercise.
3527 The file contents in this section must be used without the "> " prefix.
3535 DISTNAME= bison-1.25
3537 MASTER_SITES= ${MASTER_SITE_GNU}
3538 MAINTAINER= thorpej@NetBSD.org
3539 HOMEPAGE= http://www.gnu.org/software/bison/bison.html
3540 COMMENT= GNU yacc clone
3543 INFO_FILES= bison.info
3545 .include "../../mk/bsd.pkg.mk"
3551 GNU version of yacc. Can make re-entrant parsers, and numerous other
3552 improvements. Why you would want this when Berkeley yacc(1) is part
3553 of the NetBSD source tree is beyond me.
3559 @comment <$>NetBSD<$>
3572 13.1.4 Checking a package "pkglint"
3573 ===================================
3575 The NetBSD package system comes with a tool called "pkglint" (located in the
3576 directory "pkgsrc/pkgtools/pkglint") which helps to check the contents of these
3577 files. After installation it is quite easy to use, just change to the
3578 directory of the package you wish to examine and execute "pkglint":
3581 OK: checking ./DESCR.
3582 OK: checking Makefile.
3583 OK: checking distinfo.
3584 OK: checking patches/patch-aa.
3587 Depending on the supplied command line arguments (see "man pkglint") more
3588 verbose checks will be performed. Use e.g. "pkglint -v" for a very verbose
3592 13.2 Steps for building, installing, packaging
3593 ==============================================
3595 Create the directory where the package lives, plus any auxiliary directories:
3597 # cd /usr/pkgsrc/lang
3602 Create Makefile, DESCR and PLIST, then continue with fetching the distfile:
3605 >> bison-1.25.tar.gz doesn't seem to exist on this system.
3606 >> Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//.
3607 Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
3608 ftp: Error retrieving file: 500 Internal error
3610 >> Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//.
3611 Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
3612 ftp: Error retrieving file: 500 Internal error
3614 >> Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//.
3615 Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
3616 Successfully retrieved file.
3618 Generate the checksum of the distfile into distinfo:
3625 >> Checksum OK for bison-1.25.tar.gz.
3626 ===> Extracting for bison-1.25
3627 ===> Patching for bison-1.25
3628 ===> Ignoring empty patch directory
3629 ===> Configuring for bison-1.25
3630 creating cache ./config.cache
3631 checking for gcc... cc
3632 checking whether we are using GNU C... yes
3633 checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin
3634 checking how to run the C preprocessor... cc -E
3635 checking for minix/config.h... no
3636 checking for POSIXized ISC... no
3637 checking whether cross-compiling... no
3638 checking for ANSI C header files... yes
3639 checking for string.h... yes
3640 checking for stdlib.h... yes
3641 checking for memory.h... yes
3642 checking for working const... yes
3643 checking for working alloca.h... no
3644 checking for alloca... yes
3645 checking for strerror... yes
3646 updating cache ./config.cache
3647 creating ./config.status
3649 ===> Building for bison-1.25
3650 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
3651 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
3652 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
3653 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
3654 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
3655 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
3656 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
3657 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
3658 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
3659 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
3660 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
3661 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
3662 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
3663 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
3664 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
3665 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
3666 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
3667 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
3668 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
3669 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
3670 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
3671 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
3672 ./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp()
3674 sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" < ./bison.simple > bison.s1
3676 Everything seems OK, so install the files:
3679 >> Checksum OK for bison-1.25.tar.gz.
3680 ===> Installing for bison-1.25
3681 sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share /usr/pkg/info /usr/pkg/man/man1
3682 rm -f /usr/pkg/bin/bison
3683 cd /usr/pkg/share; rm -f bison.simple bison.hairy
3684 rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info*
3685 install -c -o bin -g bin -m 555 bison /usr/pkg/bin/bison
3686 /usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple
3687 /usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy
3688 cd .; for f in bison.info*; do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done
3689 /usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1
3690 ===> Registering installation for bison-1.25
3692 You can now use bison, and also - if you decide so - remove it with
3693 "pkg_delete bison-1.25". Should you decide that you want a binary package,
3697 >> Checksum OK for bison-1.25.tar.gz.
3698 ===> Building package for bison-1.25
3699 Creating package bison-1.25.tgz
3700 Registering depends:.
3701 Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
3703 Now that you don't need the source and object files any more, clean up:
3706 ===> Cleaning for bison-1.25
3709 ======================
3710 Appendix A: build logs
3711 ======================
3717 >> top-3.5beta5.tar.gz doesn't seem to exist on this system.
3718 >> Attempting to fetch from ftp://ftp.groupsys.com/pub/top/.
3719 Requesting ftp://ftp.groupsys.com/pub/top/top-3.5beta5.tar.gz (via ftp://orpheus.amdahl.com:80/)
3720 Successfully retrieved file.
3721 >> Checksum OK for top-3.5beta5.tar.gz.
3722 ===> Extracting for top-3.5beta5
3723 ===> Patching for top-3.5beta5
3724 ===> Applying NetBSD patches for top-3.5beta5
3725 ===> Configuring for top-3.5beta5
3726 /bin/cp /u/pkgsrc/sysutils/top/files/defaults /u/pkgsrc/sysutils/top/work/top-3.5beta5/.defaults
3727 chmod a-x /u/pkgsrc/sysutils/top/work/top-3.5beta5/install
3729 Reading configuration from last time...
3731 Using these settings:
3732 Bourne Shell /bin/sh
3734 Compiler options -DHAVE_GETOPT -O
3736 Install command /usr/bin/install
3743 Random passwd access yes
3748 bin directory $(PREFIX)/bin
3749 man directory $(PREFIX)/man/man1
3753 Building Makefile...
3754 Building top.local.h...
3756 Doing a "make clean".
3757 rm -f *.o top core core.* sigdesc.h
3758 To create the executable, type "make".
3759 To install the executable, type "make install".
3760 ===> Building for top-3.5beta5
3761 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c top.c
3762 awk -f sigconv.awk /usr/include/sys/signal.h >sigdesc.h
3763 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c commands.c
3764 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c display.c
3765 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c screen.c
3766 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c username.c
3767 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c utils.c
3768 utils.c: In function `errmsg':
3769 utils.c:348: warning: return discards `const' from pointer target type
3770 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c version.c
3771 cc -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c getopt.c
3772 cc "-DOSREV=12G" -DHAVE_GETOPT -DORDER -DHAVE_GETOPT -O -c machine.c
3774 cc -o top top.o commands.o display.o screen.o username.o utils.o version.o getopt.o machine.o -ltermcap -lm -lkvm
3780 >> Checksum OK for top-3.5beta5.tar.gz.
3781 ===> Installing for top-3.5beta5
3782 /usr/bin/install -o root -m 2755 -g kmem top /usr/pkg/bin
3783 /usr/bin/install top.1 /usr/pkg/man/man1/top.1
3784 strip /usr/pkg/bin/top
3785 ===> Registering installation for top-3.5beta5
3793 >> Checksum OK for top-3.5beta5.tar.gz.
3794 ===> Building package for top-3.5beta5
3795 Creating package top-3.5beta5.tgz
3796 Registering depends:.
3797 Creating gzip'd tar ball in '/u/pkgsrc/sysutils/top/top-3.5beta5.tgz'
3800 ======================================================
3801 Appendix B: Layout of the FTP server's package archive
3802 ======================================================
3804 Layout for precompiled binary packages on ftp.netbsd.org:
3806 /pub/NetBSD/packages/
3809 # Unpacked pkgsrc trees
3810 pkgsrc-current -> /pub/NetBSD/NetBSD-current/pkgsrc
3811 pkgsrc-2003Q4 -> N/A
3812 pkgsrc-2004Q1/pkgsrc
3815 pkgsrc-current.tar.gz -> ../NetBSD-current/tar_files/pkgsrc.tar.gz
3816 pkgsrc-2003Q4.tar.gz -> N/A
3817 pkgsrc-2004Q1.tar.gz -> N/A
3819 # Per pkgsrc-release/OS-release/arch package archives
3844 # Per os-release package archive convenience links
3845 NetBSD-1.6.2 -> 1.6.2
3847 i386 -> ../pkgsrc-2004Q1/NetBSD-1.6.2/i386
3857 2.0 -> NetBSD-2.0 # backward compat, historic
3859 i386 -> ../pkgsrc-2004Q1/NetBSD-2.0/i386
3861 sparc -> ../pkgsrc-2004Q1/SunOS-5.9/sparc
3862 x86 -> ../pkgsrc-2004Q1/SunOS-5.9/x86
3865 - Run bulk build, see #3.2
3866 - Upload /usr/pkgsrc/packages to
3867 ftp://ftp.netbsd.org/pub/NetBSD/packages/\
3868 pkgsrc-2004Q1/\ # pkgsrc-branch
3869 `uname -s`-`uname -r`/ # OS & version
3870 `uname -p` # architecture
3871 - if necessary ln -s `uname -m` `uname -p` # amiga -> m68k, ...
3873 Disk space needed: unknown.
3876 ###########################################################################
3878 # mode: Indented-Text
3880 # sentence-end-double-space: t