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 BSD.  Compiling an appli-
     cation 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).  For information about creating new
     ports, see Building an OpenBSD Port (http://www.openbsd.org/port-
     ing.html).  Other excellent resources are the ports and porting sections
     of the FreeBSD Handbook (http://www.freebsd.org/handbook/ports.html and
     http://www.freebsd.org/handbook/porting.html) as well as the NetBSD Pack-
     age System documentation (http://www.netbsd.org/Documentation/netb-
     sd/Packages.txt).

     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.

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.

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.  This is /usr/ports on FreeBSD
                   and OpenBSD and /usr/pkgsrc on NetBSD.

     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/${ARCH} in PORTSDIR.
                   If this directory exists, the package tree will be (par-
                   tially) constructed.  This directory does not have to ex-
                   ist; if it doesn't, packages will be placed into the cur-
                   rent directory, or define one of

                   PKGREPOSITORY  Directory to put the package in.

                   PKGFILE        The full path to the package.

     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 and DISTDIR in /etc/mk.conf accordingly.  do a cd /usr/ports &&
     make obj to create working directories stubs.  /usr/ports may now be re-
     mounted read-only.

FILES
     /usr/ports           The default ports directory ( FreeBSD and OpenBSD ).
     /usr/pkgsrc          The default ports directory ( NetBSD ).
     /usr/ports/Makefile  Ports master Makefile.
     /usr/ports/INDEX     Ports index.
     /usr/ports/infrastructure/mk/bsd.port.mk
                          The ports main engine ( OpenBSD ).
     /usr/ports/infrastructure/templates/network.conf.template
                          Network configuration defaults ( OpenBSD ).
     /usr/ports/infrastructure/db/network.conf
                          Local network configuration ( OpenBSD ).

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

     The FreeBSD handbook.

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, it is currently managed by
     Christopher Turan, with much help from Marc Espie, Kevin Lo, Brad Smith,
     Christian Weisgerber, and a host of others found at ports@openbsd.org.

BUGS
     Ports documentation is split over several places ---
     /usr/share/mk/bsd.port.mk, the ``Ports Collection'' section of the FreeB-
     SD 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.0                    January 25, 1998                              4
