This section provides basic instructions on using the Ports
Collection to install or remove software. The detailed
description of available make
targets and
environment variables is available in ports(7).
As of mid 2012, the FreeBSD Ports Project has migrated revision control systems from CVS to Subversion. The preferred method for obtaining and maintaining the ports tree is Portsnap. Users requiring local customization of ports (that is, maintaining additional local patches) will probably prefer to use Subversion directly. The CVSup service was phased out as of February 28, 2013.
The Ports Collection is a set of
Makefiles
, patches, and description files
stored in /usr/ports
. This set of files
is used to compile and install applications on FreeBSD. The
instructions below show several methods of obtaining the Ports
Collection if it was not installed during initial FreeBSD
setup.
Portsnap is a fast and user-friendly tool for retrieving the Ports Collection, the preferred choice for most users. See Using Portsnap for a detailed description of Portsnap.
Download a compressed snapshot of the Ports Collection
into /var/db/portsnap
.
#
portsnap fetch
When running Portsnap
for the first time, extract the snapshot into
/usr/ports
:
#
portsnap extract
After the first use of
Portsnap has been completed as
shown above,
/usr/ports
can be
updated with:
#
portsnap fetch
#
portsnap update
If more control over the ports tree is needed (for example, for maintaining local changes), Subversion can be used to obtain the Ports Collection. Refer to the Subversion Primer for a detailed description of Subversion.
Subversion must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Subversion like this:
#
cd /usr/ports/devel/subversion
#
make install clean
If the ports tree is not available, Subversion can be installed as a package:
#
pkg_add -r subversion
If pkgng is being used to manage packages, Subversion can be installed with it instead:
#
pkg install subversion
Check out a copy of the ports tree. Use a specific
Subversion
mirror close to your geographic location instead
of svn0.us-east.FreeBSD.org
in the
command below for better performance. Committers should
read the Subversion
Primer first to be sure the correct protocol is
chosen.
#
svn checkout https://svn0.us-east.FreeBSD.org
/ports/head /usr/ports
To update
/usr/ports
after
the initial Subversion
checkout:
#
svn update /usr/ports
This method involves using sysinstall to install the Ports Collection from the installation media. Note that the old copy of Ports Collection from the date of the release will be installed. If you have Internet access, you should always use one of the methods mentioned above.
As root
, run
sysinstall
as shown below:
#
sysinstall
Scroll down and select Enter.
, pressScroll down and select Enter.
, pressScroll down to Space.
, pressScroll up to Enter.
, pressSelect your desired installation media, such as CDROM, FTP, and so on.
Scroll up to Enter.
and pressPress X to exit sysinstall.
By February 28, 2013, the ports tree will no longer be exported to CVS and therefore CVSup and csup will no longer provide updates for the ports tree.
The migration will require about 1 GB of disk space
on /usr
, plus
Portsnap requires about
150 MB disk space on /var
.
Disable any automated ports updates you may use, such as a cron(8) job calling CVSup or csup.
Move the existing ports tree to a temporary location:
#
mv /usr/ports /usr/ports.old
Fetch the new ports tree with
Portsnap and extract it to
/usr/ports
:
#
portsnap fetch extract
Move distfiles and saved packages to the new ports tree:
#
mv /usr/ports.old/distfiles /usr/ports
#
mv /usr/ports.old/packages /usr/ports
Delete the old ports tree:
#
rm -rf /usr/ports.old
If CVSup was used before, it can now be uninstalled:
#
pkg_delete -r -v cvsup-without-gui-\*
Users of pkgng can use the following command:
#
pkg delete cvsup-without-gui
See Using Portsnap for a detailed description of Portsnap and how to update the ports tree with Portsnap.
A port skeleton is a set of files that tell FreeBSD system how to compile and install a program. Each port skeleton includes:
Makefile
: The
Makefile
contains statements that
specify how the application should be compiled and where
its components should be installed.
distinfo
: This file contains
information about the files that must be downloaded to
build the port, and their checksums (using
sha256(1)), to verify that files have not been
corrupted during the download.
files/
: This directory contains
any patches needed for the program to compile and install
on FreeBSD. This directory may also contain other files used
to build the port.
pkg-descr
: This file provides a
more detailed description of the program.
pkg-plist
: This is a list
of all the files that will be installed by the port. It
also tells the ports system what files to remove upon
deinstallation.
Some ports include other files, such as
pkg-message
. The ports system uses these
files to handle special situations. If you want more details
on these files, and on ports in general, refer to the
FreeBSD
Porter's Handbook.
The port does not include the actual source code, also known as a “distfile”. Source code is distributed in whatever manner the software author desires. The two methods for installing a FreeBSD port are described below.
You must be logged in as root
to
install ports.
Before compiling any port, be sure to have an
up-to-date Ports Collection and check http://vuxml.freebsd.org/ for security
issues related to your port. If ports-mgmt/portaudit
is
installed, run portaudit -F
before
installing a new port, to fetch the current vulnerabilities
database. A security audit and an update of the database
will be performed during the daily security system check.
For more information read the portaudit(1) and
periodic(8) manual pages.
Using the Ports Collection assumes a working Internet
connection. Otherwise, manually obtain and place a copy of
the distfile into
/usr/ports/distfiles
.
To begin, change to the directory of the port to be installed:
#
cd /usr/ports/sysutils/lsof
To compile, or “build”, the port, type
make
at the prompt. You should see
messages similar to the ones in this example:
#
make
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation output snipped]
...
#
Once the compile is complete, you are returned to the
prompt. The next step is to install the port using
make
:install
#
make install
===> Installing for lsof-4.57
...
[installation output snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
#
Once you are returned to the prompt, you should be able
to run the installed application. Since
lsof
is a program that runs with increased
privileges, a security warning is shown. During the building
and installation of ports, take heed of any other warnings
that may appear.
It is a good idea to delete the working subdirectory, which contains all the temporary files used during compilation. Doing so saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port.
#
make clean
===> Cleaning for lsof-4.57
#
You can save two extra steps by just running
make
instead of install clean
make
,
make
and install
make
as three separate steps.clean
Using only
make
means there will potentially be many
waiting periods between user interaction as the default
behaviour is to prompt the user for options. To avoid this
when there are many dependencies, first run install
make
to do
the configuration in one batch. Then run config-recursive
make
afterwards.install [clean]
When using config-recursive
,
the list of ports to configure are gathered by the
all-depends-list
make(1)
target. It is often recommended to run make
until all dependent ports options have been defined, and
ports options dialog(1) screens no longer
appear, to be certain all ports options have been
configured as intended.config-recursive
Some shells keep a cache of the commands that are
available in the directories listed in the
PATH
environment variable, to speed up lookup
operations for the executable file of these commands. If
you are using tcsh
, you might have to
type rehash
so that a newly installed
command can be used without specifying its full path. Use
hash -r
instead for the
sh
shell. Refer to the documentation for
the shell for more information.
Some third-party DVD products such as the FreeBSD
Toolkit from the FreeBSD
Mall contain distfiles. They can be used with the
Ports Collection. Mount the DVD on
/cdrom
. If you use a different mount
point, set CD_MOUNTPTS
make variable. The
needed distfiles will be automatically used if they are
present on the disk.
The licenses of a few ports do not allow their inclusion on the DVD. This could be because a registration form needs to be filled out before downloading or redistribution is not allowed. If you wish to install a port not included on the DVD, you will need to be connected to the Internet.
The ports system uses fetch(1) to download the
files, which honors various environment variables, including
FTP_PASSIVE_MODE
, FTP_PROXY
, and
FTP_PASSWORD
. You may need to set one or more
of these if you are behind a firewall, or need to use an
FTP/HTTP proxy. See fetch(3) for the complete
list.
For users which cannot be connected all the time, the
make
option
is provided. Run this command within
fetch
/usr/ports
and the required files will
be downloaded. This command also works in the
lower level categories, such as
/usr/ports/net
. Note that if a port
depends on libraries or other ports, this will
not fetch the distfiles of ports
from another category. Use
make
to fetch
all the dependencies of a port.fetch-recursive
You can build all the ports in a category or as a
whole by running make
in the top level
directory. This is dangerous, however, as some ports cannot
co-exist. In other cases, some ports can install two
different files with the same filename.
In some rare cases, users may need to acquire the
tarballs from a site other than the default
MASTER_SITES
. You can override the
MASTER_SITES
option with the following
command:
#
cd /usr/ports/directory
#
make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch
In this example, MASTER_SITES
is
changed to ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/
.
Some ports provide build options which can be used to
enable/disable parts of the application which are unneeded,
provide security options, or allow for other customizations.
Examples include
www/firefox
,
security/gpgme
, and
mail/sylpheed-claws
. A
menu will be displayed at the beginning of a port
compile when compile options are available.
The WRKDIRPREFIX
and
PREFIX
variables can override the default
working and target directories. For example:
#
make WRKDIRPREFIX=/usr/home/example/ports install
will compile the port in
/usr/home/example/ports
and install
everything under /usr/local
.
#
make PREFIX=/usr/home/example/local install
will compile the port in /usr/ports
and install it in
/usr/home/example/local
.
And
#
make WRKDIRPREFIX=../ports PREFIX=../local install
will combine the two.
Alternatively, these can be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable.
Certain ports provide an ncurses-based menu containing
build options. There are several ways to revisit this menu
in order to add, remove, or change these options after a
port has been built. One method is to
cd
into the directory containing the
port and type
make
.
Another option is to use
config
make
.
Another option is to execute
showconfig
make
which will remove all selected options and allow you to
start over. All of these options, and others, are explained
in great detail in the manual page for ports(7).rmconfig
First, list outdated ports that have a newer version available in the Ports Collection with the pkg_version(1) command:
#
pkg_version -v
Once you have updated your Ports Collection, before
attempting a port upgrade, you should check
/usr/ports/UPDATING
. This file
describes various issues and additional steps users may
encounter and need to perform when updating a port,
including such things as file format changes, changes in
locations of configuration files, or other such
incompatibilities with previous versions.
If UPDATING
contradicts something
you read here, UPDATING
takes
precedence.
The portupgrade utility is
designed to easily upgrade installed ports. It is available
from the
ports-mgmt/portupgrade
port. Install it like any other port, using
make
:install
clean
#
cd /usr/ports/ports-mgmt/portupgrade
#
make install clean
Scan the list of installed ports using
pkgdb -F
and fix all the inconsistencies
it reports. It is a good idea to do this regularly, before
every upgrade.
Use portupgrade -a
to upgrade all the
outdated ports installed on the system. Include
-i
to be asked for confirmation of every
individual upgrade.
#
portupgrade -ai
To upgrade only a specified application instead of all
available ports, use portupgrade
. Include
pkgname
-R
to first upgrade all the ports required
by the given application.
#
portupgrade -R firefox
To use packages instead of ports, include the
-P
flag. With this option,
portupgrade searches the local
directories listed in PKG_PATH
, then fetches
packages from a remote site if not found locally. If
packages can not be found locally or fetched remotely,
portupgrade will use ports. To
avoid using ports, specify -PP
.
#
portupgrade -PP gnome2
To just fetch distfiles (or packages, if
-P
is specified) without building or
installing anything, use -F
. For further
information see portupgrade(1).
ports-mgmt/portmaster
is another
utility for upgrading installed ports.
portmaster was designed to
use the tools found in the “base” system
without depending upon other ports. It uses the information
in /var/db/pkg/
to
determine which ports to upgrade. To install the
port:
#
cd /usr/ports/ports-mgmt/portmaster
#
make install clean
Portmaster groups ports into four categories:
Root ports: no dependencies and is not depended on by other ports
Trunk ports: no dependencies, but other ports depend upon it
Branch ports: have dependencies and are depended upon by other ports
Leaf ports: have dependencies but are not depended upon by other ports
To list all installed software and search for updates,
use -L
:
#
portmaster -L
===>>> Root ports (No dependencies, not depended on)
===>>> ispell-3.2.06_18
===>>> screen-4.0.3
===>>> New version available: screen-4.0.3_1
===>>> tcpflow-0.21_1
===>>> 7 root ports
...
===>>> Branch ports (Have dependencies, are depended on)
===>>> apache22-2.2.3
===>>> New version available: apache22-2.2.8
...
===>>> Leaf ports (Have dependencies, not depended on)
===>>> automake-1.9.6_2
===>>> bash-3.1.17
===>>> New version available: bash-3.2.33
...
===>>> 32 leaf ports
===>>> 137 total installed ports
===>>> 83 have new versions availableAll the installed ports can be upgraded using this command:
#
portmaster -a
By default, portmaster will
make a backup package before deleting the existing port.
If the installation of the new version is successful,
portmaster will delete the
backup. Using -b
will instruct
portmaster not to automatically
delete the backup. Adding -i
will start
portmaster in interactive mode,
prompting for confirmation before upgrading each
port.
If you encounter errors during the upgrade process, use
-f
to upgrade/rebuild all ports:
#
portmaster -af
You can also use portmaster to install new ports on the system, upgrading all dependencies before building and installing the new port:
#
portmaster shells/bash
Refer to portmaster(8) for more information.
Using the Ports Collection will use up disk space over
time. After building and installing a port, make
will clean up the
temporary clean
work
directory. To sweep the whole Ports Collection:
#
portsclean -C
A lot of out-dated source distribution files will collect
in distfiles
over time.
The following command will delete all the distfiles that are
no longer referenced by any ports:
#
portsclean -D
To remove all distfiles not referenced by any port currently installed on the system:
#
portsclean -DD
The portsclean
utility is part of the
ports-mgmt/portupgrade
suite.
ports-mgmt/pkg_cutleaves
automates
the task of removing installed ports that are no longer
needed.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.