PORTS(7)                   OpenBSD Reference Manual                   PORTS(7)

NAME
     ports - contributed applications

DESCRIPTION
     The OpenBSD Ports Collection is the infrastructure used to create binary
     packages for third party applications.

     For normal usage refer to packages(7), as most ports produce binary pack-
     ages which are available from the official CD-ROM, or on a neighborly FTP
     mirror.

     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.openbsd.org/checklist.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),

     pkglocatedb
                build a pkg_mklocatedb(1) database file and place it in
                ${PORTSDIR}/packages/${MACHINE_ARCH}/ftp, for use by
                locate(1),

     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).

     Starting in OpenBSD 4.0, there is a port, databases/sqlports that builds
     an sqlite database containing most information relevant to every port in
     the ports tree.  This database can be searched using any tool able to ma-
     nipulate such databases, for instance sqlitebrowser, or a script language
     with an sqlite interface, e.g., perl, python, ocaml, lua, php5.

SELECTING A SET OF PORTS
     One can define SUBDIRLIST to point to a file that contains a list of
     FULLPKGPATHs, one per line, to build stuff only in some directories.

     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 example, install all of the net ports.

     The variable SKIPDIR can hold a set of package directories to avoid dur-
     ing 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)).  SKIPDIR is handled by a case statement, and so can
     contain simple wildcards, e.g., SKIPDIR='editors/openoffice*' .

     The variable STARTDIR can hold the path to a starting directory.  The re-
     cursion will skip all directories up to that package path.  This can be
     used to resume a full build at some specific point without having to go
     through thousands of directories first.

     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

     If REPORT_PROBLEM_LOGFILE is non empty, then REPORT_PROBLEM will default
     to:

           echo $$d ($@) >$${REPORT_PROBLEM_LOGFILE}

     That is, any failure will append the faulty directory name together with
     the target that failed to ${REPORT_PROBLEM_LOGFILE} and proceed.

     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 or-
     der automatically.  That is, build will be run (if necessary) by install,
     and so on all the way to fetch.  In typical use, one will only run
     install explicitly (as normal user, with SUDO 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.  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
                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 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.

     print-build-depends print-run-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).  This does not recurse to de-
                 pendencies.

     regress     Runs the ports regression tests.  Usually needs a completed
                 build.

     reinstall   Use this to restore a port after using pkg_delete(1).

     update      Alternative target to install.  Does not install new pack-
                 ages, but updates existing ones.

     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.

LOCK INFRASTRUCTURE
     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 to a proper value will activate it.

     All locks will be stored in ${LOCKDIR}.  LOCK_CMD should be used to ac-
     quire a lock, and UNLOCK_CMD should be used to release it.

     Locks are named ${LOCKDIR}/${FULLPKGNAME}.lock, or ${LOCKDIR}/${DIST-
     FILE}.lock for distfiles fetching.

     The default values of LOCK_CMD and UNLOCK_CMD are appropriate for most
     uses.

     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 in-
     volved, they will invoke top-level targets in other directories, and thus
     acquire some other locks as well.

     The infrastructure contains some protection against acquiring the same
     lock twice, thus recursive locking is not needed for LOCK_CMD.

     Starting with OpenBSD 4.3, the infrastructure supports manual locking:
     the targets lock and unlock can be used to acquire and release individual
     locks.  Both these targets output a shell command that must be used to
     update environment variables.  Manual locking can be used to protect a
     directory against interference by an automated build job, while the user
     is looking at or modifying a given port.

UPDATING PACKAGES
     Instead of deinstalling each package and rebuilding from scratch, the
     ports tree can be used to update installed packages.  The update target
     will replace an installed package using pkg_add(1) in replacement mode.
     If FORCE_UPDATE is set to `Yes', dependencies will also be updated first,
     and packages will always be updated, even if there is no difference be-
     tween the old and the new packages.

     Updates use a mechanism similar to bulk cookies and deposit cookies in
     the UPDATE_COOKIES_DIR.  See the next section for more details, since
     most of the fine points of bulk package building also apply to updates.

     There are bugs in the ports tree, most related to libtool, which make
     some updates prefer the already installed libraries instead of the newly
     built ones.  This shows up as undefined references in libraries, in which
     case there is no choice but to proceed the old way: deinstall the offend-
     ing package and everything built on top of it, build and install new
     packages.

BULK PACKAGE BUILDING
     The ports tree contains some mechanisms to save space when building large
     collections of packages.  If 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, the database of installed pack-
     ages 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.

     Some experimental framework allows for building a new set of packages
     without first uninstalling the old ones: move the old packages away, re-
     move all bulk cookies and update cookies, and use the update target with
     FORCE_UPDATE set to `Yes' for the build.

NETWORK CONFIGURATION
     The variables pertaining to network access have been marshalled into
     ${PORTSDIR}/infrastructure/templates/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 misc/screen 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 fla-
     vors, the package name will be extended with a dash-separated list of the
     selected flavors.

     In this instance, the corresponding package will be called
     screen-4.0.2-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 install
           $ 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 combi-
     nation is needed, careful hand-building of the required set of packages
     is still necessary.

MULTI_PACKAGES
     The OpenBSD ports tree comes with a mechanism called MULTI_PACKAGES.
     This mechanism is used when a larger package is broken down into several
     smaller components referred to as subpackages.

     If a port is "subpackaged", each subpackage will have a corresponding de-
     scription in the pkg/DESCR-subpackage file.

     For example, the database/mysql port comes with subpackages called -main,
     -tests and -server.

     In this instance, the build will yield multiple packages, one correspond-
     ing to each subpackage.  In the case of our mysql example, the packages
     will be called mysql-client-<version>, 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 environ-
     ment of the make(1) command during the install/deinstall phase:

           $ env SUBPACKAGE="-server" make install
           $ env SUBPACKAGE="-server" make deinstall

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.

     PACKAGE_REPOSITORY
                   Used only for the package target; the base directory for
                   the packages tree, normally packages in PORTSDIR.  If this
                   directory exists, the package tree will be (partially) con-
                   structed.

     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.

     UPDATE_COOKIES_DIR
                   Used to store cookies for package updates, defaults to up-
                   date/${MACHINE_ARCH} under PORTSDIR.  If set to empty, it
                   will revert to a file under ${WRKDIR}.

     LOCALBASE     Where to install things in general (usually /usr/local).

     MASTER_SITES  Primary sites for distribution 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).

     FETCH_PACKAGES
                   If set to ``Yes'', try to use pkg_add(1) to install the
                   missing packages from PKG_PATH.

     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.

     USE_SYSTRACE  Set to `Yes' to protect the configure, build, and fake tar-
                   gets 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
     Select read-write partition(s) that can accommodate working directories,
     the distfiles repository, and the built packages.  Set WRKOBJDIR,
     PACKAGE_REPOSITORY, BULK_COOKIES_DIR, UPDATE_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.
     /usr/ports/infrastructure/db/systrace.filter
                          Filter list for systrace.
     /usr/ports/infrastructure/db/user.list
                          List of users and groups created by ports.

SEE ALSO
     make(1), pkg_add(1), pkg_create(1), pkg_delete(1), pkg_info(1),
     bsd.port.mk(5), port-modules(5), packages(7)

     The OpenBSD Ports Mechanism: http://www.openbsd.org/ports.html

     The OpenBSD Porting Checklist: http://www.openbsd.org/checklist.html

HISTORY
     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
     ports@openbsd.org.

AUTHORS
     This man page was originated by David O'Brien, from the FreeBSD project.

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.

     Use of the MANPS and MANZ variables is not supported.

OpenBSD 4.7                    October 11, 2009                              7
