The following sections provide basic instructions on using the Ports Collection to
install or remove programs from your system. The detailed description of available make targets and environment variables is available in ports(7).
Before you can install ports, you must first obtain the Ports Collection--which is
essentially a set of Makefiles, patches, and description files
placed in /usr/ports.
When installing your FreeBSD system, sysinstall asked if
you would like to install the Ports Collection. If you chose no, you can follow these
instructions to obtain the ports collection:
CVSup Method
This is a quick method for getting and keeping your copy of the Ports Collection up to
date using CVSup protocol. If you want to learn more about CVSup, see Using CVSup.
Note: The implementation of CVSup protocol included
with the FreeBSD system is called csup. It first appeared in
FreeBSD 6.2. Users of older FreeBSD releases can install it via the net/csup port/package.
Make sure /usr/ports is empty before you run csup for the first time! If you already have the Ports Collection
present, obtained from another source, csup will not prune
removed patch files.
-
Run csup:
# csup -L 2 -h cvsup.FreeBSD.org /usr/share/examples/cvsup/ports-supfile
Change cvsup.FreeBSD.org to a CVSup server near you. See CVSup Mirrors (Section A.5.7) for a complete listing of mirror
sites.
Note: One may want to use his own ports-supfile, for
example to avoid the need of passing the CVSup server on the
command line.
-
In this case, as root, copy /usr/share/examples/cvsup/ports-supfile to a new location, such as
/root or your home directory.
-
Edit ports-supfile.
-
Change CHANGE_THIS.FreeBSD.org to a CVSup server near you. See CVSup Mirrors (Section A.5.7) for a complete listing of mirror
sites.
-
And now to run csup, use the following:
# csup -L 2 /root/ports-supfile
-
Running the csup(1) command later
will download and apply all the recent changes to your Ports Collection, except actually
rebuilding the ports for your own system.
Portsnap Method
Portsnap is an alternative system for distributing the
Ports Collection. It was first included in FreeBSD 6.0. On older systems, you can
install it from ports-mgmt/portsnap package:
# pkg_add -r portsnap
Please refer to Using Portsnap for a detailed description
of all Portsnap features.
-
Since FreeBSD 6.1-RELEASE and with recent versions of the Portsnap port or package, you can safely skip this step. The /usr/ports will be created automatically at first use of the portsnap(8) command.
With previous versions of Portsnap, you will have to create an
empty directory /usr/ports if it does not exists:
# mkdir /usr/ports
-
Download a compressed snapshot of the Ports Collection into /var/db/portsnap. You can disconnect from the Internet after this
step, if you wish.
# portsnap fetch
-
If you are running Portsnap for the first time, extract the
snapshot into /usr/ports:
# portsnap extract
If you already have a populated /usr/ports and you are just
updating, run the following command instead:
# portsnap update
Sysinstall Method
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 (/stand/sysinstall in FreeBSD versions older than 5.2) as shown
below:
# sysinstall
-
Scroll down and select , press Enter.
-
Scroll down and select , press Enter.
-
Scroll down to , press Space.
-
Scroll up to , press Enter.
-
Select your desired installation media, such as CDROM, FTP, and so on.
-
Scroll up to and press Enter.
-
Press X to exit sysinstall.
The first thing that should be explained when it comes to the Ports Collection is what
is actually meant by a “skeleton”. In a nutshell, a port skeleton is a
minimal set of files that tell your FreeBSD system how to cleanly compile and install a
program. Each port skeleton includes:
-
A Makefile. The Makefile contains
various statements that specify how the application should be compiled and where it
should be installed on your system.
-
A distinfo file. This file contains information about the
files that must be downloaded to build the port, and their checksums (using md5(1) and sha256(1)), to verify
that files have not been corrupted during the download.
-
A files directory. This directory contains patches to make
the program compile and install on your FreeBSD system. Patches are basically small files
that specify changes to particular files. They are in plain text format, and basically
say “Remove line 10” or “Change line 26 to this ...”. Patches are
also known as “diffs” because they are generated by the diff(1) program.
This directory may also contain other files used to build the port.
-
A pkg-descr file. This is a more detailed, often
multiple-line, description of the program.
-
A pkg-plist file. 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 have 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, check out the FreeBSD Porter's Handbook.
The port includes instructions on how to build source code, but does not include the
actual source code. You can get the source code from a CD-ROM or from the Internet.
Source code is distributed in whatever manner the software author desires. Frequently
this is a tarred and gzipped file, but it might be compressed with some other tool or
even uncompressed. The program source code, whatever form it comes in, is called a
“distfile”. The two methods for installing a FreeBSD port are described
below.
Note: You must be logged in as root to install
ports.
Warning: Before installing any port, you should be sure to have an up-to-date
Ports Collection and you should check https://vuxml.freebsd.org/ for security issues related to your port.
A security vulnerabilities check can be automatically done by portaudit before any new application installation. This tool can
be found in the Ports Collection (ports-mgmt/portaudit). Consider running 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.
The Ports Collection makes an assumption that you have a working Internet connection.
If you do not, you will need to put a copy of the distfile into /usr/ports/distfiles manually.
To begin, change to the directory for the port you want to install:
# cd /usr/ports/sysutils/lsof
Once inside the lsof directory, you will see the port
skeleton. The next step is to compile, or “build”, the port. This is done by
simply typing make at the prompt. Once you have done so, you
should see something like this:
# 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]
...
#
Notice that once the compile is complete you are returned to your prompt. The next
step is to install the port. In order to install it, you simply need to tack one word
onto the make command, and that word is 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 your prompt, you should be able to run the application you
just installed. Since lsof is a program that runs with increased
privileges, a security warning is shown. During the building and installation of ports,
you should 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. Not only does it consume valuable disk space, but it would
also cause problems later when upgrading to the newer version of the port.
# make clean
===> Cleaning for lsof-4.57
#
Note: You can save two extra steps by just running make install clean instead of make, make install and make clean as three separate steps.
Note: 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 one of
these shells, you might have to use the rehash command after
installing a port, before the newly installed commands can be used. This command will
work for shells like tcsh. Use the hash
-r command for shells like sh. Look at the documentation
for your shell for more information.
Some third-party DVD-ROM products such as the FreeBSD Toolkit from the FreeBSD Mall contain distfiles. They
can be used with the Ports Collection. Mount the DVD-ROM 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.
Note: Please be aware that the licenses of a few ports do not allow for
inclusion on the CD-ROM. This could be because a registration form needs to be filled out
before downloading or redistribution is not allowed, or for another reason. If you wish
to install a port not included on the CD-ROM, you will need to be online in order to do
so.
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 fetch option is provided. Just run this command at the top
level directory (/usr/ports) and the required files will be
downloaded for you. This command will also work in the lower level categories, for
example: /usr/ports/net. Note that if a port depends on
libraries or other ports this will not fetch the distfiles of those ports too. Replace fetch with fetch-recursive if you
want to fetch all the dependencies of a port too.
Note: You can build all the ports in a category or as a whole by running make in the top level directory, just like the aforementioned make fetch method. 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
MASTER_SITES (the location where files are downloaded from). 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 we change the MASTER_SITES option to ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
Note: Some ports allow (or even require) you to provide build options which can
enable/disable parts of the application which are unneeded, certain security options, and
other customizations. A few which come to mind are www/mozilla, security/gpgme, and mail/sylpheed-claws. A message will be displayed when options
such as these are available.
Sometimes it is useful (or mandatory) to use a different working and target directory.
The WRKDIRPREFIX and PREFIX variables
can override the default 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 it in /usr/ports and install it in /usr/home/example/local.
And of course,
# make WRKDIRPREFIX=../ports PREFIX=../local install
will combine the two (it is too long to completely write on this page, but it should
give you the general idea).
Alternatively, these variables can also be set as part of your environment. Read the
manual page for your shell for instructions on doing so.
Some ports that use imake (a part of the X Window System) do
not work well with PREFIX, and will insist on installing under
/usr/X11R6. Similarly, some Perl ports ignore PREFIX and install in the Perl tree. Making these ports respect PREFIX is a difficult or impossible job.
When building certain ports, you may be presented with a ncurses-based menu from which
you can select certain build options. It is not uncommon for users to wish to revisit
this menu to add, remove, or change these options after a port has been built. There are
many ways to do this. One option is to go into the directory containing the port and type
make config, which will simply
present the menu again with the same options selected. Another option is to use make showconfig, which will show you all
the configuration options for the port. Yet another option is to execute make rmconfig which will remove all
selected options and allow you to start over. All of these options, and others, are
explained in great detail in in the man page for ports(7).
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 the make install clean
command:
# cd /usr/ports/ports-mgmt/portupgrade
# make install clean
Scan the list of installed ports with the pkgdb -F command
and fix all the inconsistencies it reports. It is a good idea to do this regularly,
before every upgrade.
When you run portupgrade -a, portupgrade will begin to upgrade all the outdated ports
installed on your system. Use the -i flag if you want to be
asked for confirmation of every individual upgrade.
# portupgrade -ai
If you want to upgrade only a certain application, not all available ports, use portupgrade pkgname. Include the
-R flag if portupgrade should
first upgrade all the ports required by the given application.
# portupgrade -R firefox
To use packages instead of ports for installation, provide -P flag. With this option portupgrade
searches the local directories listed in PKG_PATH, or fetches
packages from remote site if it is 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).
Portmanager is another utility for easy upgrading of
installed ports. It is available from the ports-mgmt/portmanager port:
# cd /usr/ports/ports-mgmt/portmanager
# make install clean
All the installed ports can be upgraded using this simple command:
# portmanager -u
You can add the -ui flag to get asked for confirmation of
every step Portmanager will perform. Portmanager can also be used to install new ports on the system.
Unlike the usual make install clean
command, it will upgrade all the dependencies prior to building and installing the
selected port.
# portmanager x11/gnome2
If there are any problems regarding the dependencies for the selected port, you can
use Portmanager to rebuild all of them in the correct order.
Once finished, the problematic port will be rebuilt too.
# portmanager graphics/gimp -f
For further information see
portmanager(1).
Portmaster is another utility for upgrading installed
ports. Portmaster was designed make use of the tools found in
the “base” system (it does not depend upon other ports) and uses the
information in /var/db/pkg/ to determine which ports to
upgrade. It is available from the ports-mgmt/portmaster port:
# cd /usr/ports/ports-mgmt/portmaster
# make install clean
Portmaster groups ports into four categories:
-
Root ports (no dependencies, not depended on)
-
Trunk ports (no dependencies, are depended on)
-
Branch ports (have dependencies, are depended on)
-
Leaf ports (have dependencies, not depended on)
You can list all the installed ports and search for updates using the -L option:
# 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)
===>>> apache-2.2.3
===>>> New version available: apache-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 available
All the installed ports can be upgraded using this simple command:
# portmaster -a
Note: 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 the -b will instruct Portmaster not to
automatically delete the backup. Adding the -i option will
start Portmaster in interactive mode, prompting you before
upgrading each port.
If you encounter errors during the upgrade process, you can use the -f option 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
Please see
portmaster(8)
for more information.
