NetBSD/share/man/man7/packages.7

.\"	$NetBSD: packages.7,v 1.92 2005/09/11 23:35:17 wiz 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 August 1, 2005
.Dt PACKAGES 7
.Os
.Sh NAME
.Nm packages
.Nd
.Nx
user package variables
.Sh DESCRIPTION
.Em This manual page is obsolete .
.Em Please refer the pkgsrc guide at
.Pa /usr/pkgsrc/doc/pkgsrc.txt
.Em or
.Pa /usr/pkgsrc/doc/pkgsrc.html .
.Em The contents of this manual page will be moved there as time permits .
.Pp
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 PACKAGE SPECIFIC VARIABLES
This section documents variables that typically apply to an individual
package.
Non-Boolean variables without defaults are *mandatory*.
.Bl -tag -offset indent -width XXXXXXXX
.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 SVR4_PKGNAME
Name of the package file to create if the
.Pa ${PKGNAME}
isn't unique enough on a SVR4 system.
The default is
.Pa ${PKGNAME}
which may be shortened when you use gensolpkg.
Only add SVR4_PKGNAME if
.Pa ${PKGNAME}
does not produce an unique package name on a SVR4 system.
The length of SVR4_PKGNAME is limited to 5 characters.
.It PKGREVISION
This number indicates the package's revision within the
.Nx
Packages Collection (pkgsrc).
If set, this will be attached to the PKGNAME variable separated by
a
.Dq nb .
.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} .
Default is
.Pa ${PKGDIR}/PLIST .
.It PLIST_SUBST
Patterns that get automatically expanded during the PLIST creation.
Takes arguments of the form
.Li VARNAME =
.Dq value
and subsequently replaces every occurrence of
.Li ${VARNAME}
with
.Li value .
.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 MESSAGE
The name of a file which will be displayed during the installation
of a package.
No substitution according to MESSAGE_SUBST takes place.
Overrides MESSAGE_SRC.
Should not be used.
.It MESSAGE_SRC
The name of a file which will be displayed when installing
a package.
If neither MESSAGE_SRC nor MESSAGE are set, and there
is a file called
.Pa ${PKGDIR}/MESSAGE ,
that file will be used.
Before displaying the file, substitution according to MESSAGE_SUBST
takes place.
.It MESSAGE_SUBST
This variable takes equations of the form
.Li VARNAME =
.Dq value ,
and replaces all occurrences of
.Li ${VARNAME}
in MESSAGE_SRC with
.Li value .
By default, substitution is performed for
.Li LOCALBASE ,
.Li PKGNAME ,
.Li PREFIX ,
.Li X11BASE ,
and
.Li X11PREFIX .
.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_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_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 MAKEFILE
Name of the Makefile in ${WRKSRC}, used in the default build and
install targets.
Default:
.Dq Makefile .
.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 REPLACE_PERL
Takes a list of files and replaces each occurrence of "/usr/bin/perl", "/usr/local/bin/perl"
and "/usr/pkg/bin/perl" in the named files with the value of ${PERL5}.
This can be used to point perl scripts to the proper interpreter that pkgsrc installs.
Note: it looks for the listed files in ${WRKSRC}.
.It UNLIMIT_RESOURCES
List of process limits which need to be raised to hard limits for building
this package.
So far "datasize" and "stacksize" are supported.
.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 the
.Pa libtool
package instead of the pkg's own
.Pa libtool .
.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 PERL5_REQD
Sets the minimum
.Pa perl5
version required.
The default is 5.0.
.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_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 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 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_IMAKE or USE_X11BASE.
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 INTERACTIVE_STAGE
Set this if your package needs to interact with the user
during its fetch, configure, build or install stages.
Multiple stages may be specified.
The user can then decide to skip this package by
setting
.Dv ${BATCH} .
.It FETCH_DEPENDS
A list of
.Dq path:dir
pairs of other packages this package depends upon 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 packages this package depends upon 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 pre-requisite 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 RECOMMENDED
A list of recommended versions of pre-requisite packages.
This should be used together with
.Dq DEPENDS
to denote which version of a pre-requisite is required and
which version is recommended.
The format of this entry is
.Dq pkgname:dir ,
the same as for
.Dq DEPENDS .
.It IGNORE_RECOMMENDED
If this is set to 
.Dq NO
(the default), then RECOMMENDED pre-requisites will be turned into
dependencies.
If set to
.Dq YES ,
recommendations will be ignored and a warning will be printed that
packages created with this option are not suitable for distribution.
.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 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 __PLATFORM_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 BUILD_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.
.It OSVERSION_SPECIFIC
Used to denote packages, such as LKM's, which are tightly bound to
a specific version of the OS.
Such binary packages are not backwards compatible with
other versions of the OS, and should be uploaded to a version specific
directory on the FTP.
This variable is not currently used by any of the
package system internals, but may be used in the future.
Set this to
.Dq YES
to denote such a package.
.El
.Sh MOTIF SUPPORT
This section documents variables related to the use and installation of
Motif and/or LessTif.
Also, packages that require a Motif installation need
to include motif.buildlink.mk.
.Bl -tag -offset indent -width XXXXXXXX
.It USE_MOTIF12
Set this in your package if it requires Motif-1.2 headers and/or libraries.
If Motif is not present on your system, the lesstif12 package will be
installed for you.
.It MOTIFBASE
If set, it points to an existing Motif-2.0 installation.
Otherwise, this is
set automatically to the directory of the Motif-2.0 installation used.
.It MOTIF12BASE
If set, it points to an existing Motif-1.2 installation.
Otherwise, this is
set automatically to the directory of the Motif-1.2 installation used.
.It MOTIFLIB
Set automatically to the flags and libraries needed to link the Motif or
LessTif library.
.El
.Sh PACKAGE DISTFILE REPOSITORIES
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_SOURCEFORGE
download.sourceforge.net mirror.
.It Sy MASTER_SITE_SUNSITE
sunsite.unc.edu mirror.
.It Sy MASTER_SITE_TEX_CTAN
TeX CTAN 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 -offset indent -width XXXXXXXX
.It ECHO_MSG
Used to print all the
.Dq ===\*[Gt]
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 -offset indent -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 man pages (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 documents variables used to configure the way manual pages
are installed by this package.
.Bl -tag -offset indent -width XXXXXXXX
.It MANCOMPRESSED
Indicates that the package installs man pages in a compressed
form.
The default package installs man pages 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 (e.g., the
.Dq install
target relies on the
.Dq build
target), then these targets will be executed beforehand.
.Bl -tag -offset indent -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 from local disk and via FTP from a list
of sites (see
.Dq BINPKG_SITES
variable), and do a
.Dq make package
if no binary package is available anywhere.
The arguments given to
.Xr pkg_add 1
can be set via
.Dq BIN_INSTALL_FLAGS ,
e.g., to do verbose operation, etc.
.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 package and all dependent packages that
are installed on the system.
.It replace
Update the installation of the current package.
This differs from update in that it does not replace dependent packages.
You will need to install
.Pa pkgsrc/pkgtools/pkg_tarup
for this target to work.
.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}/doc/pkgsrc.txt
for more details.
.It mirror-distfiles
Mirror the distfile(s) if they are freely re-distributable.
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
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 ,
.Pa ${PKGSRCDIR}/mk/defaults/mk.conf
and
.Rs
.%T "Documentation on the NetBSD Package System"
.Re
.Pa ${PKGSRCDIR}/doc/pkgsrc.txt
.Sh HISTORY
This manual page is based upon the comments in the
.Pa bsd.pkg.mk
file, as distributed with
.Nx .
The sources to this are far
and varied across all free BSD projects.