ports - contributed applications
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 original
application source code compile and run on OpenBSD.
Compiling an application
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 patches,
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.openb-
sd.org/checklist.html).
For a detailed description of the build process, see
bsd.port.mk(5).
PORTS MASTER MAKEFILE [Toc] [Back] 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 userfriendly way,
search invoked with a key, e.g., make search key=foo,
retrieve information
relevant to a given port (obsolescent).
SELECTING A SET OF PORTS [Toc] [Back] 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.
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.
The variable SKIPDIR can hold a set of package directories
to avoid during
recursion. These are always specified relative to the
root of the
ports tree, and can contain a flavor or subpackage part (see
packages-specs(7)).
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 all, build, checksum, clean,
configure,
extract, fake, fetch, install, distclean, deinstall,
reinstall, package,
link-categories, unlink-categories, describe, show, regress,
lib-depends-
check, homepage-links, manpages-check, license-check,
all-dir-depends,
build-dir-depends, run-dir-depends and readmes.
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 order
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, indexed
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 dependencies
of the current port. When called by
the extract,
install or fetch targets, this is run in scattered pieces as
lib-depends, build-depends and run-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 package
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.
print-build-depends print-run-depends
Print an ordered list of all the compile and run
dependencies.
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 operation.
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.
The ports tree can be used concurrently for building several
ports at the
same time, thanks to a locking mechanism. By default, this
mechanism is
disabled. Defining LOCKDIR, LOCK_CMD, and UNLOCK_CMD to
proper values
will activate it.
All locks will be stored in ${LOCKDIR}. LOCK_CMD should be
used to acquire
a lock, and UNLOCK_CMD should be used to release it.
Locks are named ${LOCKDIR}/${FULLPKGNAME}.lock, or ${LOCKDIR}/${DISTFILE}.lock
for distfiles fetching.
The locking protocol follows a big-lock model: each top-level target in a
port directory will acquire the corresponding lock, complete
its job,
then release the lock, e.g., running
$ make build
will acquire the lock, run the port through fetch, checksum,
extract,
patch, configure, build, then release the lock. If dependencies are involved,
they will invoke top-level targets in other directories, and thus
acquire some other locks as well.
At no moment should a given invocation of make(1) acquire
the same lock
twice, thus recursive locking is not needed for LOCK_CMD.
BULK PACKAGE BUILDING [Toc] [Back] 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 [Toc] [Back] 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 fetching
files.
MASTER_SITE_FREEBSD
If set to Yes, include the master FreeBSD site
when fetching
files.
MASTER_SITE_OVERRIDE
Go to this site first for all files.
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
program will be built. To avoid confusion with other packages or flavors,
the package name will be extended with a dash-separated list of the
selected 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 environment
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 X11 requirement and accordingly have a
no_x11 flavor.
Flavor settings are not propagated to dependencies. If a
specific combination
is needed, careful hand-building of the required set
of packages
is still necessary.
The OpenBSD ports tree comes with a mechanism called This mechanism is used when a larger package is broken down
into several
smaller components referred to as subpackages.
If a port is "subpackaged", in addition to the main package,
each subpackage
will have a corresponding description in the
pkg/DESCR-subpackage
file.
For example, the database/mysql port comes with subpackages
called tests
and server.
In this instance, the build will yield multiple packages,
one corresponding
to each subpackage. In the case of our mysql example,
the subpackages
will be called mysql-tests-<version> and
mysql-server-<version>.
To install/deinstall a specific subpackage of a port, you
may pkg_add(1)
them manually, or alternatively, you may set SUBPACKAGE in
the environment
of the make(1) command during the install/deinstall
phase:
$ env SUBPACKAGE="-server" make install
$ env SUBPACKAGE="-server" make deinstall
These can be changed in the environment, or in /etc/mk.conf
for persistence.
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 notice.
PORTSDIR Location of the ports tree (usually
/usr/ports)
DISTDIR Where to find/put distfiles, normally
distfiles/ in
PORTSDIR.
PKGREPOSITORYBASE
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 already
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.
FETCH_CMD Command to use to fetch files. Normally
ftp(1).
PATCH_DEBUG If defined, display verbose output when applying each
patch.
INTERACTIVE If defined, only operate on a port if it requires interaction.
BATCH If defined, only operate on a port if it can
be installed
100% automatically.
USE_SYSTRACE Set to `Yes' to protect the configure, build,
and fake targets
with systrace(1). This way it is ensured
that ports
do not make any network connections during
build or write
outside some well defined directories. The
filter list is
stored in
${PORTSDIR}/infrastructure/db/systrace.filter.
USING A READ-ONLY PORTS TREE [Toc] [Back] 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.
/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.
/usr/ports/infrastructure/db/systrace.filter
Filter list for systrace.
/usr/ports/infrastructure/db/user.list
List of users and groups created by
ports.
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.openb-
sd.org/ports.html
The OpenBSD Porting Checklist: http://www.openbsd.org/check-
list.html
The Ports Collection appeared in FreeBSD 1.0. It was introduced in
OpenBSD 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 Weisgerber, along with a host of others found
at
[email protected].
This man page was originated by David O'Brien, from the
FreeBSD project.
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.6 January 25, 1998
[ Back ] |
