PORTS(7) OpenBSD Reference Manual PORTS(7)
NAME
ports - contributed applications
DESCRIPTION
The OpenBSD Ports Collection (shamelessly stolen from the FreeBSD Ports
Collection) offers a simple way for users and administrators to install
applications. Each port contains any patches necessary to make the orig-
inal application source code compile and run on OpenBSD. Compiling an ap-
plication is as simple as typing make in the port directory! The
Makefile automatically fetches the application source code, either from a
local disk or via ftp, unpacks it on the local system, applies the patch-
es, and compiles it. If all goes well, simply type sudo make install to
install the application.
For more information about using ports, see The OpenBSD Ports Mechanism
(http://www.openbsd.org/ports.html) and the OpenBSD FAQ
(http://www.openbsd.org/faq/). For information about creating new ports,
see the OpenBSD Porting Checklist (http://www.openbsd.org/check-
list.html).
For a detailed description of the build process, see bsd.port.mk(5).
PORTS MASTER MAKEFILE
The ports master Makefile, normally located in /usr/ports/Makefile (but
see PORTSDIR below) offers a few useful targets.
index rebuild the ports complete index, /usr/ports/INDEX
mirror-maker
see mirroring-ports(7),
print-index
display the contents of the index in a user-friendly way,
search invoked with a key, e.g., make search key=foo, retrieve infor-
mation relevant to a given port (obsolescent).
SELECTING A SET OF PORTS
If /usr/ports/INDEX is up to date, it is possible to select subsets by
setting the following variables on the command line:
key package name matching the given key,
category port belonging to category,
maintainer
port maintained by a given person.
For instance, to invoke clean on all ports in the x11 category, one can
say:
$ make category=x11 clean
The index search is done by a perl script, so all regular expressions
from perlre(1) apply.
TARGETS
Individual ports are controlled through a few documented targets. Some
of these targets work recursively through subdirectories, so that someone
can, for examples, install all of the net ports.
In case of failure in a subdirectory, the shell fragment held in
REPORT_PROBLEM is executed. Default behavior is to call exit, but this
can be overridden on the command line, e.g., to avoid stopping after each
problem.
$ make REPORT_PROBLEM=true
The targets that do this are build, checksum, clean, configure, extract
install, distclean, deinstall, reinstall, mirror-distfiles, obj, package,
cdrom-packages, link-categories, unlink-categories, and ftp-packages.
Target names starting with _ are private to the ports infrastructure,
should not be invoked directly, and are liable to change without notice.
In the following list, each target will run the preceding targets in or-
der automatically. That is, build will be run (if necessary) by install,
and so on all the way to fetch. Typical use only runs install explicitly
(if root or SUDO is defined in /etc/mk.conf), or build (as user), then
install (as root).
fetch Fetch all of the files needed to build this port from the
site(s) listed in MASTER_SITES and PATCH_SITES. See FETCH_CMD
and MASTER_SITE_OVERRIDE.
checksum Verify that the fetched distfile matches the one the port was
tested against. Defining NO_CHECKSUM to Yes will skip this
step. Sometimes, distfiles change without warning. The main
OpenBSD mirror should still hold a copy of old distfiles, in-
dexed by checksum. Using
$ make checksum REFETCH=true
will try to get a set of distfiles that match the recorded
checksum.
depends Install (or package if only compilation is necessary) any de-
pendencies of the current port. When called by the extract,
install or fetch targets, this is run in scattered pieces as
fetch-depends, lib-depends, build-depends, run-depends and
misc-depends. Defining NO_DEPENDS to Yes will skip this step.
extract Expand the distfile into a work directory.
patch Apply any patches that are necessary for the port.
configure Configure the port. Some ports will ask questions during this
stage. See INTERACTIVE and BATCH.
build Build the port. This is the same as calling the all target.
fake Pretend to install the port under a subdirectory of the work
directory.
package Create a binary package from the fake installation. The pack-
age is a .tgz file that can be used to install the port on
several machines with pkg_add(1).
install Install the resulting package.
The following targets are not run during the normal install process.
depends-list package-depends
Print an ordered list of all the compile and run dependen-
cies.
clean Remove the expanded source code. This does not recurse to
dependencies unless CLEANDEPENDS is defined to Yes.
distclean Remove the port's distfile(s) and perform the clean opera-
tion. This does not recurse to dependencies.
reinstall Use this to restore a port after using pkg_delete(1).
link-categories
Populate the ports tree with symbolic links for each category
the port belongs to.
unlink-categories
Remove the symbolic links created by link-categories.
BULK PACKAGE BUILDING
The ports tree contains some mechanisms to save space when building large
collections of packages. If BIN_PACKAGES, TRUST_PACKAGES, and BULK are
set to `Yes' for a package build, some shortcuts are taken to allow
cleaning up working directories on the fly.
Some important caveats apply: the packages already built in the package
repository are assumed to be up-to-date (BIN_PACKAGES), the database of
installed packages is assumed to be accurate (TRUST_PACKAGES), and the
bulk cookies are assumed to be up-to-date (BULK).
This means that newer iterations of package buildings should make sure
those conditions are met, which entails erasing old package repository,
removing packages that need to be rebuilt from the base of installed
packages, and cleaning up old bulk cookies.
If any of these conditions is not met, the package build may run into
weird problems.
NETWORK CONFIGURATION
The variables pertaining to network access have been marshalled into
${PORTSDIR}/infrastructure/template/network.conf.template.
To customize that setup, copy that file into
${PORTSDIR}/infrastructure/db/network.conf and edit it.
MASTER_SITE_OPENBSD
If set to Yes, include the master OpenBSD site when fetch-
ing files.
MASTER_SITE_FREEBSD
If set to Yes, include the master FreeBSD site when fetch-
ing files.
MASTER_SITE_OVERRIDE
Go to this site first for all files.
FLAVORS
The OpenBSD ports tree comes with a mechanism called FLAVORS. Thanks to
this mechanism, users can select specific options provided by a given
port.
If a port is "flavored", there should be a terse description of available
flavors in the pkg/DESCR file.
For example, the shells/bash port comes with a flavor called static. This
changes the building process so a statically compiled version of the pro-
gram will be built. To avoid confusion with other packages or flavors,
the package name will be extended with a dash-separated list of the se-
lected flavors.
In this instance, the corresponding package will be called
bash-1.14.7p1-static.
To build a port with a specific flavor, just pass FLAVOR in the environ-
ment of the make(1) command:
$ env FLAVOR="static" make package
and of course, use the same settings for the subsequent invocations of
make:
$ env FLAVOR="static" make package
$ env FLAVOR="static" make clean
More than one flavor may be specified:
$ cd /usr/ports/mail/exim
$ env FLAVOR="mysql ldap" make package
Specifying a flavor that does not exist is an error. Additionally, some
ports impose some further restrictions on flavor combinations, when such
combinations do not make sense.
Lots of ports can be built without X Windows requirement and accordingly
have a no_x11 flavor.
Flavor settings are not propagated to dependencies. If a specific combi-
nation is needed, careful hand-building of the required set of packages
is still necessary.
PORT VARIABLES
These can be changed in the environment, or in /etc/mk.conf for persis-
tence. They can also be set on make's command line, e.g., make
VAR_FOO=foo
Boolean variables should be set to Yes instead of simply being defined,
for uniformity and future compatibility.
Variable names starting with _ are private to the ports infrastructure,
should not be changed by the user, and are liable to change without no-
tice.
PORTSDIR Location of the ports tree (usually /usr/ports)
DISTDIR Where to find/put distfiles, normally distfiles/ in
PORTSDIR.
PACKAGES Used only for the package target; the base directory for
the packages tree, normally packages/${MACHINE_ARCH} in
PORTSDIR. If this directory exists, the package tree will
be (partially) constructed. This directory does not have
to exist; if it doesn't, packages will be placed into the
current directory, or define one of
PKGREPOSITORY Directory to put the package in.
PKGFILE The full path to the package.
BULK_COOKIES_DIR
During bulk package building, used to store cookies for al-
ready built packages to avoid rebuilding them, since the
actual working directory will already have been cleaned
out. Defaults to bulk/${MACHINE_ARCH} under PORTSDIR.
LOCALBASE Where to install things in general (usually /usr/local)
MASTER_SITES Primary sites for distribution files if not found locally.
PATCH_SITES Primary location(s) for distribution patch files if not
found locally.
CLEANDEPENDS If set to Yes, let `clean' recurse to dependencies.
NOCLEANDEPENDS
If defined, don't let `clean' recurse to dependencies (dep-
recated, use CLEANDEPENDS instead).
FETCH_CMD Command to use to fetch files. Normally ftp(1).
FORCE_PKG_REGISTER
If set, overwrite any existing package registration on the
system. (Not recommended.)
PATCH_DEBUG If defined, display verbose output when applying each
patch.
INTERACTIVE If defined, only operate on a port if it requires interac-
tion.
BATCH If defined, only operate on a port if it can be installed
100% automatically.
USING A READ-ONLY PORTS TREE
Select read-write partition(s) that can accommodate working directories,
the distfiles repository, and the built packages. Set WRKOBJDIR,
PACKAGES, BULK_COOKIES_DIR and DISTDIR in /etc/mk.conf accordingly.
FILES
/usr/ports The default ports directory.
/usr/ports/Makefile Ports master Makefile.
/usr/ports/INDEX Ports index.
/usr/ports/infrastructure/mk/bsd.port.mk
The ports main engine.
/usr/ports/infrastructure/templates/network.conf.template
Network configuration defaults.
/usr/ports/infrastructure/db/network.conf
Local network configuration.
SEE ALSO
make(1), pkg_add(1), pkg_create(1), pkg_delete(1), pkg_info(1),
bsd.port.mk(5), packages(7)
The OpenBSD Ports Mechanism: http://www.openbsd.org/ports.html
The OpenBSD Porting Checklist: http://www.openbsd.org/checklist.html
AUTHORS
This man page was originated by David O'Brien, from the FreeBSD project.
HISTORY
The Ports Collection appeared in FreeBSD 1.0. It was introduced in OpenB-
SD by Ejovi Nuwere, with much initial effort by Angelos D. Keromytis.
Maintenance passed then to Marco S. Hyman, and then to Christopher Turan.
It is currently managed by Marc Espie, Brad Smith, and Christian Weisger-
ber, along with a host of others found at ports@openbsd.org.
BUGS
Ports documentation is split over several places --- bsd.port.mk(5), the
``Ports Collection'' section of the FreeBSD handbook, the ``Porting
Existing Software'' section of the FreeBSD handbook, and some man pages.
OpenBSD adds a few web pages to further confuse the issue.
OpenBSD 3.3 January 25, 1998 5