*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> ports (7)              



NAME    [Toc]    [Back]

     ports - contributed applications

DESCRIPTION    [Toc]    [Back]

     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!
     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-

     For  a  detailed  description  of  the  build  process,  see


     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,

                see mirroring-ports(7),

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


     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,

               port maintained by a given person.

     For  instance, to invoke clean on all ports in the x11 category, one can

                   $ make category=x11 clean

     The index search is done by a perl script,  so  all  regular
     from perlre(1) apply.

TARGETS    [Toc]    [Back]

     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

     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

           $ make REPORT_PROBLEM=true

     The  targets  that  do this are all, build, checksum, clean,
     extract,  fake,  fetch,   install,   distclean,   deinstall,
reinstall, package,
     link-categories, unlink-categories, describe, show, regress,
     check,   homepage-links,   manpages-check,    license-check,
     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.
                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

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

     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

     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

     print-build-depends print-run-depends
                 Print an ordered list of all the compile and run

     clean       Remove the expanded source code.  This does  not
recurse to
                 dependencies  unless  CLEANDEPENDS is defined to

     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

                 Populate the ports tree with symbolic links  for
each category
                 the port belongs to.

                 Remove    the    symbolic   links   created   by


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


     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
     removing  packages  that need to be rebuilt from the base of
     packages, and cleaning up old bulk cookies.

     If any of these conditions is not met, the package build may
run into
     weird problems.


     The  variables  pertaining  to network access have been marshalled into

     To customize that setup, copy that file into
     ${PORTSDIR}/infrastructure/db/network.conf and edit it.

                   If set to Yes, include the master OpenBSD site
when fetching

                   If set to Yes, include the master FreeBSD site
when fetching

                   Go to this site first for all files.

FLAVORS    [Toc]    [Back]

     The  OpenBSD  ports  tree  comes  with  a  mechanism  called
FLAVORS.  Thanks to
     this  mechanism,  users can select specific options provided
by a given

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

     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

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

MULTI_PACKAGES    [Toc]    [Back]

     The  OpenBSD  ports  tree  comes  with  a  mechanism  called

MULTI_PACKAGES.    [Toc]    [Back]

     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

     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

     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

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

PORT VARIABLES    [Toc]    [Back]

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

     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

     DISTDIR         Where   to   find/put   distfiles,  normally
distfiles/ in

                   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

                   PKGFILE        The full path to the package.

                   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

     LOCALBASE     Where to install things  in  general  (usually

     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

     PATCH_DEBUG   If defined, display verbose output when applying each

     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


     Select  read-write partition(s) that can accommodate working
     the distfiles  repository,  and  the  built  packages.   Set
     PACKAGES,  BULK_COOKIES_DIR  and DISTDIR in /etc/mk.conf accordingly.

FILES    [Toc]    [Back]

     /usr/ports           The default ports directory.
     /usr/ports/Makefile  Ports master Makefile.
     /usr/ports/INDEX     Ports index.
                          The ports main engine.
                          Network configuration defaults.
                          Local network configuration.
                          Filter list for systrace.
                          List of users  and  groups  created  by

SEE ALSO    [Toc]    [Back]

     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-

     The OpenBSD Porting Checklist: http://www.openbsd.org/check-

HISTORY    [Toc]    [Back]

     The Ports Collection appeared in FreeBSD 1.0.  It was introduced in
     OpenBSD by Ejovi Nuwere, with much initial effort by Angelos
     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

AUTHORS    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     Ports  documentation  is  split  over  several  places   ---
bsd.port.mk(5), the
     ``Ports  Collection''  section  of the FreeBSD handbook, the
     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 ]
 Similar pages
Name OS Title
sysman_intro Tru64 Introduction of SysMan applications
portal HP-UX a "window to the future" for applications
form_init OpenBSD set hooks for automatic invocation by applications
menu_term OpenBSD set hooks for automatic invocation by applications
menu_init OpenBSD set hooks for automatic invocation by applications
menu_hook OpenBSD set hooks for automatic invocation by applications
item_term OpenBSD set hooks for automatic invocation by applications
item_init OpenBSD set hooks for automatic invocation by applications
field_term OpenBSD set hooks for automatic invocation by applications
form_hook OpenBSD set hooks for automatic invocation by applications
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service