4.5 Using the PortsCollection

The following sections provide basic instructions on using the ports collection toinstall or remove programs from your system.

4.5.1 Obtaining the PortsCollection

Before you can install ports, you must first obtain the ports collection--which isessentially a set of Makefiles, patches, and description filesplaced in /usr/ports.

When installing your FreeBSD system, sysinstall asked ifyou would like to install the ports collection. If you chose no, you can follow theseinstructions to obtain the ports collection:

Sysinstall Method

This method involves using sysinstall again to manuallyinstall the ports collection.

As root, run /stand/sysinstall asshown below:
```
# /stand/sysinstall
```
Scroll down and select Configure, press Enter.
Scroll down and select Distributions, press Enter.
Scroll down to ports, press Space.
Scroll up to Exit, press Enter.
Select your desired installation media, such as CDROM, FTP, and so on.
Scroll up to Exit and press Enter.
Press X to exit sysinstall.

The alternative method to obtain and keep your ports collection up to date is by usingCVSup. Look at the ports CVSupfile, /usr/share/examples/cvsup/ports-supfile. See Using CVSup (Section A.5) for moreinformation on using CVSup and this file.

CVSup Method

This is a quick method for getting the ports collection using CVSup. If you want to keep your ports tree up to date, or learnmore about CVSup, read the previously mentioned sections.

Install the net/cvsup port. See CVSupInstallation (Section A.5.2) for moredetails.
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 mirrorsites.
Run cvsup:
```
# cvsup -g -L 2 /root/ports-supfile
```
Running this command later will download and apply all the recent changes to yourports collection, except actually rebuilding the ports for your own system.

4.5.2 InstallingPorts

The first thing that should be explained when it comes to the ports collection is whatis actually meant by a ``skeleton''. In a nutshell, a port skeleton is a minimal set offiles that tell your FreeBSD system how to cleanly compile and install a program. Eachport skeleton includes:

A Makefile. The Makefile containsvarious statements that specify how the application should be compiled and where itshould be installed on your system.
A distinfo file. This file contains information about thefiles that must be downloaded to build the port and their checksums, to verify that fileshave not been corrupted during the download using md5(1).
A files directory. This directory contains patches to makethe program compile and install on your FreeBSD system. Patches are basically small filesthat specify changes to particular files. They are in plain text format, and basicallysay ``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, oftenmultiple-line, description of the program.
A pkg-plist file. This is a list of all the files that willbe installed by the port. It also tells the ports system what files to remove upondeinstallation.

Some ports have other files, such as pkg-message. The portssystem uses these files to handle special situations. If you want more details on thesefiles, and on ports in general, check out the FreeBSD Porter's Handbook.

Now that you have enough background information to know what the ports collection isused for, you are ready to install your first port. There are two ways this can be done,and each is explained below.

Before we get into that, however, you will need to choose a port to install. There area few ways to do this, with the easiest method being the ports listing on the FreeBSD website. You can browse through the ports listed there or use the search function on thesite. Each port also includes a description so you can read a bit about each port beforedeciding to install it.

Another method is to use the whereis(1) command.Simply type whereis file, wherefile is the program you want to install. If it is found onyour system, you will be told where it is, as follows:

# whereis lsoflsof: /usr/ports/sysutils/lsof

This tells us that lsof (a system utility) can be found inthe /usr/ports/sysutils/lsof directory.

Yet another way to find a particular port is by using the ports collection's built-insearch mechanism. To use the search feature, you will need to be in the /usr/ports directory. Once in that directory, run make search name=program-name whereprogram-name is the name of the program you want to find.For example, if you were looking for lsof:

# cd /usr/ports# make search name=lsofPort:   lsof-4.56.4Path:   /usr/ports/sysutils/lsofInfo:   Lists information about open files (similar to fstat(1))Maint:  obrien@FreeBSD.orgIndex:  sysutilsB-deps: R-deps:

The part of the output you want to pay particular attention to is the ``Path:'' line,since that tells you where to find the port. The other information provided is not neededin order to install the port, so it will not be covered here.

For more in-depth searching you can also use make search key=string where string is sometext to search for. This searches port names, comments, descriptions and dependencies andcan be used to find ports which relate to a particular subject if you don't know the nameof the program you are looking for.

In both of these cases, the search string is case-insensitive. Searching for ``LSOF''will yield the same results as searching for ``lsof''.

Note: You must be logged in as root to installports.

Now that you have found a port you would like to install, you are ready to do theactual installation. The port includes instructions on how to build source code, but doesnot include the actual source code. You can get the source code from a CD-ROM or from theInternet. 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 othertool or even uncompressed. The program source code, whatever form it comes in, is calleda ``distfile''. You can get the distfile from a CD-ROM or from the Internet.

Warning: Before installing any port, you should be sure to have an up-to-dateports collection and you should check http://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 canbe found in the ports collection (security/portaudit). Consider running portaudit -F before installing a new port, to fetch the currentvulnerabilities database. A security audit and an update of the database will beperformed during the daily security system check. For more informations read the portaudit(1) andperiodic(8) manualpages.

4.5.2.1 Installing Ports from aCD-ROM

The FreeBSD Project's official CD-ROM images no longer include distfiles. They take upa lot of room that is better used for precompiled packages. CD-ROM products such as theFreeBSD PowerPak do include distfiles, and you can order these sets from a vendor such asthe FreeBSD Mall. This sectionassumes you have such a FreeBSD CD-ROM set.

Place your FreeBSD CD-ROM in the drive. Mount it on /cdrom.(If you use a different mount point, the install will not work.) To begin, change to thedirectory for the port you want to install:

# cd /usr/ports/sysutils/lsof

Once inside the lsof directory, you will see the portskeleton. The next step is to compile, or ``build'', the port. This is done by simplytyping make at the prompt. Once you have done so, you should seesomething like this:

# make>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.>> Attempting to fetch from file:/cdrom/ports/distfiles/.===>  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 nextstep is to install the port. In order to install it, you simply need to tack one wordonto 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 youjust installed. Since lsof is a program that runs with increasedprivileges, a security warning is shown. During the building and installation of ports,you should take heed of any other warnings that may appear.

Note: You can save an extra step by just running makeinstall instead of make and makeinstall as two separate steps.

Note: Some shells keep a cache of the commands that are available in thedirectories listed in the PATH environment variable, to speed uplookup operations for the executable file of these commands. If you are using one ofthese shells, you might have to use the rehash command afterinstalling a port, before the newly installed commands can be used. This is true for bothshells that are part of the base-system (such as tcsh) andshells that are available as ports (for instance, shells/zsh).

Note: Please be aware that the licenses of a few ports do not allow forinclusion on the CD-ROM. This could be because a registration form needs to be filled outbefore downloading or redistribution is not allowed, or for another reason. If you wishto install a port not included on the CD-ROM, you will need to be online in order to doso (see the next section).

4.5.2.2 Installing Ports from theInternet

As with the last section, this section makes an assumption that you have a workingInternet connection. If you do not, you will need to perform the CD-ROM installation, or put a copy of the distfileinto /usr/ports/distfiles manually.

Installing a port from the Internet is done exactly the same way as it would be if youwere installing from a CD-ROM. The only difference between the two is that the distfileis downloaded from the Internet instead of read from the CD-ROM.

The steps involved are identical:

# make install>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.>> Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%439860 bytes transferred in 18.0 seconds (23.90 kBps)===>  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]...===>  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.#

As you can see, the only difference is the line that tells you where the system isfetching the port distfile from.

The ports system uses fetch(1) to downloadthe 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 arebehind a firewall, or need to use an FTP/HTTP proxy. See fetch(3) for thecomplete list.

For users which cannot be connected all the time, the make fetch option is provided. Just run this command at the toplevel directory (/usr/ports) and the required files will bedownloaded for you. This command will also work in the lower level categories, forexample: /usr/ports/net. Note that if a port depends onlibraries or other ports this will not fetch the distfiles of those ports too. Replace fetch with fetch-recursive if youwant 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 twodifferent files with the same filename.

In some rare cases, users may need to acquire the tarballs from a site other than theMASTER_SITES (the location where files are downloaded from). Youcan override the MASTER_SITES option with the followingcommand:

# 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 canenable/disable parts of the application which are unneeded, certain security options, andother customizations. A few which come to mind are www/mozilla, security/gpgme, and mail/sylpheed-claws. A message will be displayed when optionssuch as these are available.

4.5.2.3 Overriding the Default PortsDirectories

Sometimes it is useful (or mandatory) to use a different distfiles and portsdirectory. The PORTSDIR and PREFIXvariables can override the default directories. For example:

# make PORTSDIR=/usr/home/example/ports install

will compile the port in /usr/home/example/ports and installeverything 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 PORTSDIR=../ports PREFIX=../local install

will combine the two (it is too long to completely write on this page, but it shouldgive you the general idea).

Alternatively, these variables can also be set as part of your environment. Read themanual page for your shell for instructions on doing so.

4.5.2.4 Dealing with imake

Some ports that use imake (a part of the X Window System) donot 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.

4.5.3 Removing InstalledPorts

Now that you know how to install ports, you are probably wondering how to remove them,just in case you install one and later on decide that you installed the wrong port. Wewill remove our previous example (which was lsof for those ofyou not paying attention). As with installing ports, the first thing you must do ischange to the port directory, /usr/ports/sysutils/lsof. Afteryou change directories, you are ready to uninstall lsof. This isdone with the make deinstall command:

# cd /usr/ports/sysutils/lsof# make deinstall===>  Deinstalling for lsof-4.57

That was easy enough. You have removed lsof from your system.If you would like to reinstall it, you can do so by running makereinstall from the /usr/ports/sysutils/lsof directory.

The make deinstall and makereinstall sequence does not work once you have run makeclean. If you want to deinstall a port after cleaning, use pkg_delete(1) asdiscussed in the Packages section of the Handbook.

4.5.4 Ports and DiskSpace

Using the ports collection can defiantly eat up your disk space. For this reason youshould always remember to clean up the work directories using the make clean option. This will remove the work directory after a port has been built, and installed. You canalso remove the tar files from the distfiles directory, andremove the installed ports when their use has delimited.

Some users choose to limit the port categories by placing an entry in the refuse file. This way when they run the CVSup application, it will not download the files in thatcategory.

4.5.5 UpgradingPorts

Note: Once you updated your ports collection, before attempting a port upgrade,you should check the /usr/ports/UPDATING file. This filedescribes various issues and additional steps users may encounter and need to performwhen updating a port.

Keeping your ports up to date can be a tedious job. For instance, to upgrade a portyou would go to the ports directory, build the port, deinstall the old port, install thenew port, and then clean up after the build. Imagine doing that for five ports, tediousright? This was a large problem for system administrators to deal with, and now we haveutilities which do this for us. For instance the sysutils/portupgrade utility will do everything for you! Justinstall it like you would any other port, using the make install clean command.

Now create a database with the pkgdb -F command. This willread the list of installed ports and create a database file in the /var/db/pkg directory. Now when you run portupgrade -a, it will read this and the ports INDEX file. Finally, portupgrade willbegin to download, build, backup, install, and clean the ports which have been updated.portupgrade comes with a lot of options for different usecases, the most important ones will be presented below.

If you want to upgrade only a certain application, not the complete database, use portupgrade pkgname, include theflags -r if portupgrade should acton all those packages depending on the given package as well, and -R to act on all packages required by the given packages. To usepackages instead of ports for installation, provide -P and tojust fetch distfiles without building or installing anything, use -F. For further information see portupgrade(1).

Note: It is important to regularly update the package database using pkgdb -F to fix inconsistencies, especially when portupgrade asks you to. Do not abort portupgrade while it is updating the package database, this willleave you an inconsistent database.

Other utilities exist which will do this, check out the ports/sysutils directory and see what you come up with.

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.