PORTS(7) BSD Reference Manual PORTS(7)
NAME
ports - contributed applications
DESCRIPTION
MirPorts, the MirBSD Ports Collection (shamelessly stolen from the
OpenBSD Ports Collection, which in turn was inspired by FreeBSD) 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 MirBSD, Ox, Darwin (Mac OS X) and Interix.
Compiling an application is as simple as typing mmake in the port direc-
tory! The Makefile automatically fetches the application source code, ei-
ther from a local disk or via ftp, unpacks it on the local system, ap-
plies the patches, and compiles it. If all goes well, simply type mmake
install to install the application.
For more information about using ports, see http://mirbsd.de/ports, 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 also the OpenBSD Porting Checklist
(http://www.openbsd.org/checklist.html).
For a detailed description of the build process and all the variables in
a port Makefile, see bsd.port.mk(5). For a detailed description of the
packing list (PLIST) format, see pkg_create(1).
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., mmake search key=foo, retrieve in-
formation 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:
$ mmake 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.
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 flavour 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.
$ mmake 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 ord-
er 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/mmake.cfg), 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
$ mmake 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 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) 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.
FLAVOURS
MirPorts comes with a mechanism called FLAVOURS. Thanks to this mechan-
ism, users can select specific options provided by a given port.
If a port is "flavoured", there should be a terse description of avail-
able flavours in the pkg/DESCR file.
For example, the shells/tcsh port comes with a flavour 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-
vours, the package name will be extended with a dash-separated list of
the selected flavours.
In this instance, the corresponding package will be called
tcsh-6.13.00-0-static.
To build a port with a specific flavour, just pass FLAVOUR in the en-
vironment of the make(1) command:
$ env FLAVOUR="static" mmake package
and of course, use the same settings for the subsequent invocations of
make:
$ env FLAVOUR="static" mmake package
$ env FLAVOUR="static" mmake clean
More than one flavour may be specified:
$ cd /usr/ports/mail/exim
$ env FLAVOUR="mysql ldap" mmake package
Specifying a flavour that does not exist is an error. Additionally, some
ports impose some further restrictions on flavour combinations, when such
combinations do not make sense.
Lots of ports can be built without X11 requirement and accordingly have a
no_x11 flavour.
Flavour 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
MirPorts 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", in addition to the main package, each sub-
package 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 correspond-
ing to each subpackage. In the case of our mysql example, the subpackages
will be called mysql-tests-<version> and mysql-server-<version>.
When mmake install is invoked, all subpackages are installed by default.
See PREFER_SUBPKG_INSTALL below for how to change this. 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" mmake install
$ env SUBPACKAGE="-server" mmake deinstall
PORT VARIABLES
These can be changed in the environment, or in /etc/mmake.cfg for per-
sistence. They can also be set on make's command line, e.g., mmake
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.
BATCH If defined, only operate on a port if it can be installed
100% automatically.
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.
CLEANDEPENDS If set to Yes, let 'clean' recurse to dependencies.
DISTDIR Where to find/put distfiles, normally Distfiles/ in
PORTSDIR.
FETCH_CMD Command to use to fetch files. Normally ftp(1). Actually,
"ftp -o".
INTERACTIVE If defined, only operate on a port if it requires interac-
tion.
LOCALBASE Where to install things in general (usually /usr/local).
MASTER_SITES Primary sites for distribution files if not found locally.
PATCH_DEBUG If defined, display verbose output when applying each
patch.
PATCH_SITES Primary location(s) for distribution patch files if not
found locally.
PKGREPOSITORYBASE
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. This directory does not have to exist; if it
doesn't, packages will be placed into the current directo-
ry, or define one of
PKGREPOSITORY Directory to put the package in.
PKGFILE The full path to the package.
PORTSDIR Location of the ports tree (usually /usr/ports).
PREFER_SUBPKG_INSTALL
If set to No, don't install all subpackages when executing
mmake install. Default is Yes.
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 out-
side some well defined directories. The filter list is
stored in ${PORTSDIR}/infrastructure/db/systrace.filter.
VMEM_AUTOUNLOCK
Set to 'Yes' to raise the ulimit values for datasize and
memory automatically for building ports with VMEM_WARNING
set.
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/mmake.cfg accordingly.
FILES
/etc/mmake.cfg Default MirMake configuration file.
/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), packages(7)
The MirPorts Homepage: http://mirbsd.de/ports
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. MirPorts is currently main-
tained by Benny Siegert and Thorsten Glaser.
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.
MirBSD #10-current September 4, 2020 5