.\"	$NetBSD: packages.7,v 1.39 2000/10/22 08:40:05 rh 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 October 22, 2000
.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.
Many of these may be set in
.Xr mk.conf 5 .
.Bl -tag -indent -width XXXXXXXXX
.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 LOCALBASE
Where non-X11 based packages will be installed.
The default is
.Pa /usr/pkg .
.It CROSSBASE
Where
.Dq cross
category packages will be installed.
The default is
.Pa ${LOCALBASE}/cross .
.It X11BASE
Where X11 is installed on the system, and where
.Dq X11
category packages will be installed.
The default is
.Pa /usr/X11R6 .
.It DISTDIR
Where to get gzip'd, tarballed copies of original sources.  The default is
.Pa ${PKGSRCDIR}/distfiles .
.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 PKG_FC
Set to the path of the desired fortran compiler (default: f2c-f77).
.It XMKMF
Set to path of
.Dq xmkmf
if not in $PATH (default: xmkmf -a).
.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.
.It PKG_DEVELOPER
Run some sanity checks that package developers want:
.Bl -bullet
.It
make sure patches apply with zero fuzz
.It
run check-shlibs to see that all binaries will find their 
shared libs.
.El
.It USE_GLX 
Says that if Mesa is requested, a package should preferably use a
GLX (hardware-accelerated) version of the Mesa library.
.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 ONLY_FOR_ARCHS
If set, it lists the values of MACHINE_ARCH (basic
.Nx
CPU types) that the package will build under.
It can be a glob-style wildcard.
.It NOT_FOR_ARCHS
If set, it lists the values of MACHINE_ARCH (basic
.Nx
CPU types) that the package will not build under.
It can be a glob-style wildcard.
.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 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 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 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_X11BASE
is set, or
.Pa /etc/mtree/BSD.pkg.dist
otherwise.
.It USE_X11
Instructs the package system that the package will use headers and libraries
from
.Dv X11BASE
and so a check must be made that these are available.
If they are not, an IGNORE message will be displayed, and the package
will not be built.
.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 INSTALL_FILE
The name of a script which will be invoked when installing
binary packages. If there is a file called
.Pa ${PKGDIR}/INSTALL ,
that file will be used.
.It DEINSTALL_FILE
The name of a script which will be invoked when de-installing
binary packages. If there is a file called
.Pa ${PKGDIR}/DEINSTALL ,
that file will be used.
.It REQ_FILE
The name of a script that is invoked before installation and de-installation
to ensure things are available.
If there is a file called
.Pa ${PKGDIR}/REQ ,
that file will be used.
.It MESSAGE_FILE
The name of a file which will be displayed when installing
binary packages. If there is a file called
.Pa ${PKGDIR}/MESSAGE ,
that file will be used.
.It NO_BIN_ON_CDROM
Binaries of this package may not be placed on CDROM.  Set this string to
.Pa ${RESTRICTED} .
.It NO_BIN_ON_FTP
Binaries of this package may not be made available via ftp.  Set this string to
.Pa ${RESTRICTED} .
.It NO_BUILD	
Use a dummy (do-nothing) build target.
.It NO_CONFIGURE
Use a dummy (do-nothing) configure target.
.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_SRC_ON_CDROM
Distfile(s) of this package may not be placed on CDROM.  Set this string to
.Pa ${RESTRICTED} .
.It NO_SRC_ON_FTP
Distfile(s) of this package may not be made available via ftp.  Set this string to
.Pa ${RESTRICTED} .
If this variable is set, the distfile will not be mirrored by ftp.netbsd.org.
.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 CHECK_SHLIBS
Do not run 'check-shlibs' even if PKG_DEVELOPER is set. This prevents
errors on emul/compat packages (e.g. Linux binaries, ...).
.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 LICENCE
The package has a non-standard licence, such as shareware, or non-commercial-use
only. This string should be set to the type of licence the package has,
like "shareware", or "non-commercial-use". If LICENCE is set, the
.Dv ACCEPTABLE_LICENCES
variable will be searched, if set, for a string matching the licence.
.It PASSIVE_FETCH	
Uses passive
.Xr ftp 1
to retrieve distribution files.
.It USE_LIBTOOL	
Says that the package uses
.Pa libtool
to manage building of libraries and shared objects, where applicable.
.It LTCONFIG_OVERRIDE
If set, override the specified
.Pa ltconfig
for using
.Pa pkglibtool
instead of the pkg's own
.Pa libtool .
.It LIBTOOL_OVERRIDE
If set, override the specified
.Pa libtool
with our
.Pa pkglibtool .
.It USE_FORTRAN
Says that the package uses a fortran compiler for building.
.It USE_GMAKE	
Says that the package uses
.Pa gmake .
.It USE_JAVA
Says that the package uses a Java virtual machine.
.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_MESA 
Says that the package uses the Mesa library.  This will include all
Mesa components that are not included in the installed X11
distribution.
.It USE_SSL	
Says that the package uses a SSL library. The location of the SSL
installation can be found in
.Dv ${SSLBASE} .
.It USE_X11BASE	
Says that the package installs itself into the X11 base directory
.Dv ${X11BASE} .
This is necessary for packages that install X11 fonts, application
default files or Imake rule or template files. 
.It USE_XAW 
Says that the package uses the Athena widget set.
.It USE_XPM 
Says that the package uses the Xpm library. If it is not included
in the installed X11 distribution the xpm package will be used.
.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 CFLAGS	
Any CFLAGS you wish passed to the configure script and/or sub-make in
build stage.
.It LDFLAGS	
Any LDFLAGS you wish passed to the configure script and/or sub-make in
build stage.  LDFLAGS is pre-loaded with rpath settings for ELF machines
depending on the setting of USE_X11 or USE_MOTIF.  If you do not wish
to override these settings, use LDFLAGS+=.
.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
This definition is deprecated, and is no longer used in the packages
collection. It should be replaced by a simple
.Dq DEPENDS
definition.  
.It LIB_DEPENDS
This definition is deprecated, and is no longer used in the packages
collection. It should be replaced by a simple
.Dq DEPENDS
definition.
.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 .
.It MASTER_SORT
List of suffixes for preferred download locations to sort the MASTER_SITES
accordingly.
.It MASTER_SORT_REGEX
Similar to MASTER_SORT, but takes a list of regular expressions for
finer grained control.
.El
.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 USE_MOTIF
Set this in your package if it requires Motif.
If Motif is not present on your system, the lesstif package will be
installed for you.
.It MOTIFLIB	
Set automatically to the Motif or Lesstif library name.
.El
.Sh PACKAGE DISTFILE REPOSITORIES
.Pp
The following variables allow to override the default package
repositories, they define a space separated list of mirror sites to be
used instead of the defaults to retrieve packages from (usually if
there's a closer or cheaper site).
.Pp
.Sq %SUBDIR%
and
.Sq ${DIST_SUBDIR}
are replaced by a package specific strings.
.Pp
.Bl -tag -width OBJMACHINE
.It Sy MASTER_SITE_BACKUP
Backup sites for packages that are maintained in
.Sq ftp.netbsd.org:/pub/NetBSD/packages/distfiles/${DIST_SUBDIR} .
.It Sy MASTER_SITE_GNU
GNU source mirror.
.It Sy MASTER_SITE_LOCAL
Local package source distributions that are maintained in
.Sq ftp.netbsd.org:/pub/NetBSD/packages/distfiles/LOCAL_PORTS/ .
.It Sy MASTER_SITE_PERL_CPAN
Perl CPAN mirror.
.It Sy MASTER_SITE_TEX_CTAN
TeX CTAN mirror.
.It Sy MASTER_SITE_SUNSITE
sunsite.unc.edu mirror.
.It Sy MASTER_SITE_XCONTRIB
X Window System contributed source mirror.
.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 CLEAR_DIRLIST
If set, cause the
.Dq clean-update
target to completely clean up and lose the list of dependent packages.  Use
with care!
.It DEPENDS_TARGET
The target to execute when a package is calling a dependency.  The default
depends on the target that is used:
.Dq package
for
.Dq make package ,
.Dq update
for
.Dq make update ,
and
.Dq reinstall
for all other targets.
.It NOCLEAN
If set, prevent the
.Dq update
target from cleaning up after itself.
.It PKG_VERBOSE
If set, print out more information about the automatic manual
page handling, and package deletion (see the
.Dq install,
.Dq deinstall
and
.Dq update
targets),
and also sets PATCH_DEBUG as well.
.It REINSTALL
During update, deinstall each package before calling
.Sq ${DEPENDS_TARGET}
(see the
.Dq update
target for more information).
.It UPDATE_TARGET
The target to execute for building a package during
.Dq make update .
Defaults to
.Dq install .
Other good targets are
.Dq package
or
.Dq bin-install .
Do not set this to
.Dq update
or you will get stuck in an endless loop!
.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 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 bin-install	
Install a binary package if available, do a 
.Dq make package
else.
.It reinstall	
Install the results of a build, ignoring
.Dq already installed
flag.
.It deinstall	
Remove the installation.
.It update	
Update the installation of the current and all dependent packages that
are installed on the system.
.It package	
Create a binary package other people can use.
.It clean	
Clean the source tree for a package.
.It clean-depends	
Clean the source tree for a package and the packages it depends upon.
.It clean-update	
Clean the source tree for a package and all dependent packages that
are installed on the system.
.It describe
Try to generate a one-line description for each package for
use in INDEX files and the like.
.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. See
.Pa ${PKGSRCDIR}/Packages.txt
for more details.
.It mirror-distfiles
Mirror the distfile(s) if they are freely redistributable. If
.Dv NO_SRC_ON_FTP
is set in the package's Makefile (usually to 
.Pa ${RESTRICTED} )
then that reason is printed, and the distfile is not mirrored.
.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 SEE ALSO
.Xr make 1 ,
.Xr mk.conf 5
and
.Rs
.%T "Documentation on the NetBSD Package System"
.Re
.Pa ${PKGSRCDIR}/Packages.txt
.Sh HISTORY
This manual page is 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.