.\"	$NetBSD: packages.7,v 1.1 1998/06/05 12:29:03 mrg Exp $
.\"
.\" from: NetBSD: bsd.pkg.mk,v 1.89 1998/06/01 21:30:10 hubertf Exp
.\"
.\"	This file is in the public domain.
.\"
.Dd June 4, 1998
.Dt PACKAGES 7
.Os
.Sh NAME
.Nm packages
.Nd
.Nx
user package variables
.Sh DESCRIPTION
This manual page describes the variables that users of the
.Nx
packages system can set to alter the configuration of the package system,
and individual packages.
.Sh COMMON VARIABLES
This section documents variables that typically apply to all packages.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It ONLY_FOR_ARCHS
If set, it lists the
.Nx
ports that the package will build under.
.It ARCH
The architecture, as returned by
.Dq uname -m .
See
.Xr uname 1 .
.It OPSYS
The operating system name, as returned by 
.Dq uname -s .
.It DISTDIR
Where to get gzip'd, tarballed copies of original sources.  The default is
.Pa ${PKGSRCDIR}/distfiles .
.It PREFIX
Where to install things in general.  The
.Nx
default is
.Pa /usr/pkg .
.It MASTER_SITES
Primary location(s) for distribution files if not found locally.
.It MASTER_SITE_SUBDIR
Directory that
.Dq %SUBDIR%
in MASTER_SITES is replaced by.
.It PATCH_SITES
Primary location(s) for distribution patch files (see
.Dv It PATCHFILES
below) if not found locally.
.It PATCH_SITE_SUBDIR
Directory that
.Dq %SUBDIR%
in PATCH_SITES is replaced by.
.It MASTER_SITE_BACKUP
Backup location(s) for distribution files and patch files if not found
locally and ${MASTER_SITES}/${PATCH_SITES}.  The Defaults are
.Pa ftp://ftp.netbsd.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/
and
.Pa ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/ .
.It MASTER_SITE_OVERRIDE
If set, override the MASTER_SITES setting with this value.
.It PACKAGES
A top level directory where all packages go (rather than going locally
to each package).  The default is
.Pa ${PKGSRCDIR}/packages .
.It GMAKE
Set to path of GNU make if not in $PATH (default: gmake).
.It XMKMF
Set to path of
.Dq xmkmf
if not in $PATH (default: xmkmf -a).
.It MAINTAINER
The e-mail address of the contact person for this package.  The default
is packages@NetBSD.ORG.
.It CATEGORIES
A list of descriptive categories into which this package falls.
.It WRKOBJDIR
A top level directory where, if defined, the separate working
directories will get created, and symbolically linked to from
.Pa 
${WRKDIR}
(see below).  This is useful for building packages on several
architectures, then
.Pa ${PKGSRCDIR}
can be NFS-mounted while
.Pa ${WRKOBJDIR}
is local to every arch.
.El
.Sh PACKAGE SPECIFIC VARIABLES
This section documents variables that typically apply to an individual
package.  Non-Boolean variables without defaults are *mandatory*.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It WRKDIR
A temporary working directory that gets *clobbered* on clean.  The default is
.Pa ${.CURDIR}/work .
.It WRKSRC
A subdirectory of ${WRKDIR} where the distribution actually
unpacks to.  The default is
.Pa ${WRKDIR}/${DISTNAME}
unless
.Dv NO_WRKSUBDIR
is set, in which case simply
.Pa ${WRKDIR} .
.It DISTNAME
Name of package or distribution.
.It DISTFILES
Name(s) of archive file(s) containing distribution.  The default is
.Pa ${DISTNAME}${EXTRACT_SUFX} .
.It PATCHFILES
Name(s) of additional files that contain distribution patches
There is no default.  Make will look for them at
.Dv PATCH_SITES
(see above).  They will automatically be uncompressed before patching if
the names end with
.Dq .gz
or
.Dq .Z .
.It DIST_SUBDIR
Suffix to
.Pa ${DISTDIR} .
If set, all
.Pa ${DISTFILES} 
and
.Pa ${PATCHFILES}
will be put in this subdirectory of
.Pa ${DISTDIR}.
.It ALLFILES	
All of
.Pa ${DISTFILES}
and
.Pa ${PATCHFILES} .
.It MIRROR_DISTFILE
Whether the distfile is redistributable without restrictions.
Defaults to
.Dq yes ,
set this to
.Dq no
if restrictions exist.
.It IGNOREFILES
If some of the
.Pa ${ALLFILES}
are not checksum-able, set this variable to their names.
.It PKGNAME	
Name of the package file to create if the
.Pa ${DISTNAME}
isn't really relevant for the package.  The default is
.Pa ${DISTNAME} .
.It EXTRACT_ONLY
If defined, a subset of
.Pa ${DISTFILES}
you want to actually extract.
.It PATCHDIR 	
A directory containing any additional patches you made
to package this software.  The default is
.Pa ${.CURDIR}/patches .
.It SCRIPTDIR 
A directory containing any auxiliary scripts.  The default is
.Pa ${.CURDIR}/scripts .
.It FILESDIR 	
A directory containing any miscellaneous additional files.  The default is
.Pa ${.CURDIR}/files .
.It PKGDIR 	
A direction containing any package creation files.  The default is
.Pa ${.CURDIR}/pkg .
.It PKG_DBDIR	
Where package installation is recorded.  The default is
.Pa /var/db/pkg .
.It FORCE_PKG_REGISTER
If set, it will overwrite any existing package registration information in
.Pa ${PKG_DBDIR}/${PKGNAME} .
.It NO_MTREE	
If set, will not invoke mtree from
.Pa bsd.pkg.mk
from the
.Dq install
target.
.It MTREE_FILE
The name of the mtree file.  The default is
.Pa /etc/mtree/BSD.x11.dist
if
.Dv USE_IMAKE
or
.Dv USE_X11
is set, or
.Pa /etc/mtree/BSD.pkg.dist
otherwise.
.It PLIST_SRC	   
Which file(s) to use to build
.Pa ${PLIST} .
Either
.Pa ${PKGDIR}/PLIST
or
.Pa ${PKGDIR}/PLIST-mi
plus
.Pa ${PKGDIR}/PLIST-md.shared
or
.Pa ${PKGDIR}/PLIST-md.static ,
if not set otherwise.
.It NO_BUILD	
Use a dummy (do-nothing) build target.
.It NO_CONFIGURE
Use a dummy (do-nothing) configure target.
.It NO_CDROM	
Package may not go on CDROM.  Set this string to reason.
.It NO_DESCRIBE
Use a dummy (do-nothing) describe target.
.It NO_EXTRACT
Use a dummy (do-nothing) extract target.
.It NO_INSTALL
Use a dummy (do-nothing) install target.
.It NO_PACKAGE
Use a dummy (do-nothing) package target.
.It NO_PKG_REGISTER
Don't register a package install as a package.
.It NO_WRKSUBDIR
Assume package unpacks directly into
.Pa ${WRKDIR} .
.It NO_WRKDIR	
There's no work directory at all; package does this someplace else.
.It NO_DEPENDS
Don't verify build of dependencies.
.It NOCLEANDEPENDS
Don't clean dependent packages
.It BROKEN	
Package is broken.  Set this string to the reason why.
.It RESTRICTED
Package is restricted.  Set this string to the reason why.
.It PASSIVE_FETCH	
Uses passive
.Xr ftp 1
to retrieve distribution files.
.It USE_GMAKE	
Says that the package uses
.Pa gmake .
.It USE_PERL5	
Says that the package uses
.Pa perl5
for building and running.
.It USE_IMAKE	
Says that the package uses
.Pa imake .
.It USE_X11	
Says that the package uses X11 (i.e., installs in
.Dv ${X11BASE} ) .
.It USE_GTEXINFO	
Says that the package uses gtexinfo.
.It USE_MOTIF
Says that the package uses Motif (it will use lesstif if
Motif is unavailable)
.It NO_INSTALL_MANPAGES
For imake packages that don't like the install.man target.
.It HAS_CONFIGURE
Says that the package has its own configure script.
.It GNU_CONFIGURE
Set if you are using GNU configure (optional).
.It CONFIGURE_SCRIPT
Name of configure script, defaults to
.Pa configure .
.It CONFIGURE_ARGS
Pass these args to configure if ${HAS_CONFIGURE} is set.
.It CONFIGURE_ENV
Pass these env (shell-like) to configure if
.Pa ${HAS_CONFIGURE}
is set.
.It SCRIPTS_ENV
Additional environment variables passed to scripts in
.Pa ${SCRIPTDIR}
executed by
.Pa bsd.pkg.mk .
.It MAKE_ENV	
Additional environment variables passed to sub-make in build stage.
.It IS_INTERACTIVE
Set this if your package needs to interact with the user
during a build.  User can then decide to skip this package by
setting
.Dv ${BATCH} ,
or compiling only the interactive package by setting
.Dv ${INTERACTIVE} .
.It FETCH_DEPENDS
A list of
.Dq path:dir
pairs of other package this package depends in the
.Dq fetch
stage. 
.Dq path
is the name of a file if it starts with a slash
(/), an executable otherwise.  make will test for the existence (if it
is a full pathname) or search for it in your
.Dv $PATH
(if it is an executable) and go into
.Dq dir
to do a
.Dq make all install
if it's not found.
.It BUILD_DEPENDS
A list of
.Dq path:dir
pairs of other package this package depends to build
(between the
.Dq extract
and
.Dq build
stages, inclusive).  The test done to
determine the existence of the dependency is the same as
.Dv FETCH_DEPENDS .
.It RUN_DEPENDS
A list of
.Dq path:dir
pairs of other packages this package depends to run.
The test done to determine the existence of the dependency is the same as
.Dv FETCH_DEPENDS .
This will be checked during the
.Dq install
stage and the name of the
dependency will be put into the package as well.
.It LIB_DEPENDS
A list of
.Dq lib:dir
pairs of other packages this package depends on.
.Dq lib
is the name of a shared library.  make will use
.Dq ldconfig -r
to
search for the library.  Note that lib can be any regular expression.
.It DEPENDS
A list of prerequisite packages. The format of this entry is
.Dq pkgname:dir .
If the
.Dq pkgname
package is not installed, then it will be built and
installed from the source package in
.Dq dir .
.It CONFLICTS          
A list of other ports this package conflicts with. Use this for packages
that install identical set of files. The format of this entry is
.Dq pkgname .
.It EXTRACT_CMD
Command for extracting archive.  The default is
.Xr tar 1 .
.It EXTRACT_SUFX
Suffix for archive names.  The default is
.Dq .tar.gz .
.It EXTRACT_BEFORE_ARGS
Arguments to
.Dv ${EXTRACT_CMD}
before the filename argument.  The default is
.Dq -xzf .
.It EXTRACT_AFTER_ARGS
Arguments to
.Dv ${EXTRACT_CMD}
following the filename argument.  There is no default.
.It FETCH_CMD		 
Full path to ftp/http command if not in
.Dv $PATH .
The default is
.Pa /usr/bin/ftp .
.It NO_IGNORE    
Set this to
.Dq YES
(most probably in a
.Dq make fetch
in
.Pa ${PKGSRCDIR} )
if you want to fetch all distfiles, even for packages not built due to
limitation by absent X or Motif.
.\" XXXmrg -- this shouldn't be documented.  if we want to export the
.\" feature, give it a different name, or something.
.It __ARCH_OK    
Internal variable set if the package is ok to build on this architecture. Set
to
.Dq YES
to insist on e.g. fetching all distfiles (for interactive use in
.Pa ${PKGSRCDIR} ,
mostly. 
.It ALL_TARGET
The target to pass to make in the package when building.  The default is
.Dq all .
.It INSTALL_TARGET
The target to pass to make in the package when installing.  The default is
.Dq install .
.Sh MOTIF SUPPORT
This section documents variables related to the use and installation of
Motif and/or LessTiF.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It REQUIRES_MOTIF
Set this in your package if it requires Motif.  It will  be
built only if
.Dv HAVE_MOTIF
is set.
.It HAVE_MOTIF
If set, means system has Motif.  Typically set in
.Pa /etc/mk.conf
or
.Dv ${MAKECONF} .
.It MOTIF_STATIC
If set, link libXm statically; otherwise, link it
dynamically.  Typically set in
.Pa /etc/mk.conf
or
.Dv ${MAKECONF} .
.It MOTIFLIB	
Set automatically to appropriate value depending on
.Dv ${MOTIF_STATIC} .
Substitute references to -lXm with patches to make your package conform to
our standards.
.It MOTIF_ONLY
If set, build Motif packages only.  Not much use except for building packages.
.El
.Sh SPECIAL VARIABLES
Variables to change if you want a special behavior:
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It ECHO_MSG	
Used to print all the
.Dq ===>
style prompts - override this
to turn them off.  The default is
.Pa /bin/echo .
.It DEPENDS_TARGET
The target to execute when a package is calling a dependency.  The default
is
.Dq install .
.It PATCH_DEBUG
If set, print out more information about the patches as it attempts to
apply them.
.El
.Sh INSTALL VARIABLES
This section documents variables that serve as convenient aliases.
for your *-install targets.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It INSTALL_PROGRAM	
A command to install binary executables.
Use these like:
.Dq ${INSTALL_PROGRAM} ${WRKSRC}/prog ${PREFIX}/bin .
.It INSTALL_SCRIPT	
A command to install executable scripts.
.It INSTALL_DATA		
A command to install sharable data.
.It INSTALL_MAN		
A command to install manpages (doesn't compress).
.It INSTALL_PROGRAM_DIR
Create a directory for storing programs>
.It INSTALL_SCRIPT_DIR
Create a directory for storing scripts.
.It INSTALL_DATA_DIR	
Create a directory for storing arbitrary data.
.It INSTALL_MAN_DIR	
Create a directory for storing man pages.
.El
.Sh MANUAL PAGE VARIABLES
This section docuemnts variables used to configure the way manual pages
are installed by this package.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It MANCOMPRESSED
Indicates that the package installs manpages in a compressed
form.  The default package installs manpages uncompressed.
.It MANLANG	
List of language-subdirs for
.Pa $PREFIX/man ,
into which the pkg will install it's man-pages, resulting in
.Pa $PREFIX/man/lang1/catX ,
etc.  There is no default.
.It MAN<sect>	
A list of manpages, categorized by section.  For example, if your package
has
.Dq man/man1/foo.1
and
.Dq man/mann/bar.n
set
.Dq MAN1=foo.1
and
.Dq MANN=bar.n

The available sections chars are
.Dq 123456789LN .
.It CAT<sect>    
The same as MAN<sect>, only for formatted manpages.
.It MANPREFIX	
The directory prefix for
.Dv ${MAN<sect>}.
The default is
.Dv ${PREFIX} .
.It CATPREFIX    
The directory prefix for
.Dv ${CAT<sect>}
The default is
.Dv ${PREFIX} .
.It INFO_FILES	
set to the base names of the info files you wish to be installed in the
info dir file. Automatically sets
.Dv USE_GTEXINFO .
.El
.Sh PACKAGE TARGETS
This section documents the default targets and their behaviors.  If any
target relies on another target for completion (eg, the
.Dq install
target relies on the
.Dq build
target), then these targets will be executed beforehand.
.Bl -tag -indent XXXXXXXX -width XXXXXXXX
.It fetch		
Retrieves
.Dv ${DISTFILES}
and
.Dv ${PATCHFILES}
into
.Pa ${DISTDIR}
as necessary.
.It fetch-list
Show list of files that would be retrieved by fetch.
.It extract	
Unpacks
.Dv ${DISTFILES} into
.Pa ${WRKDIR}.
.It patch		
Apply any provided patches to the source.
.It configure	
Runs either GNU configure, one or more local configure scripts or
nothing, depending on what's available.
.It build		
Actually compile the sources.
.It install	
Install the results of a build.
.It reinstall	
Install the results of a build, ignoring
.Dq already installed
flag.
.It deinstall	
Remove the installation.
.It package	
Create a binary package other people can use.
.It describe
Try to generate a one-line description for each package for
use in INDEX files and the like.
.It checkpatch
Do a
.Dq patch -C
instead of a
.Dq patch .
Note that it may give incorrect
results if multiple patches deal with the same file.
.It checksum	
Use
.Pa files/md5
to ensure that your distfiles are valid.
.It makesum	
Generate
.Pa files/md5
(only do this for your own packages!).
.It readme	
Create a README.html file describing the category or package
.It mirror-distfiles
Mirror the distfile(s) if they are freely redistributable.  Setting
.Dv MIRROR_DISTFILE
to
.Dq no
in the package Makefile will override the default
.Dq yes , and
the distfile will not be fetched.
.El
.Pp
Default sequence for
.Dq all
is:  fetch checksum extract patch configure build.
.Pp
.\" Please read the comments in the targets section below, you
.\" should be able to use the pre-* or post-* targets/scripts
.\" (which are available for every stage except checksum) or
.\" override the do-* targets to do pretty much anything you want.
NEVER override the
.Dq regular
targets unless you want to open a major can of worms.
.Sh HISTORY
This manual page based upon the comments in the
.Pa bsd.pkg.mk
file, as distributed with NetBSD.  The sources to this are far
and varied across all free BSD projects.