An Introduction to Ports

James Howard

The FreeBSD Ports Tree

The FreeBSD Ports Collection offers a simple and convenient method to prepackage software applications for the FreeBSD operating environment. Using a standard format and installation paradigm, the Ports Collection is an easy way for system administrators to install and update over 3200 applications, utilities, and system tools.

These 3200 programs are listed using a special directory tree under /usr/ports, where they are listed by category. Some categories include "databases", "java", "math", and "security". Other categories, such as "chinese", "german", "russian", and "vietnamese", include programs written or modified to handle international users. There are also a number of programming language specific categories for Tcl/Tk, Perl, and Python.

However, the most important feature of the Ports Collection is its ease of use. To install a port, you simply change to the directory the port lives in and type "make install". For an example, we will use a system utility called UWATCH. The following commands will install the port:

cd /usr/ports/sysutils/uwatch
make install

Since the programs in the Ports Collection are often very large, the program data is not a part of the port. This is where the magic happens. The Ports Collection knows to look on the CD for the source tarball if a CD is in the system. If it cannot find the source code on the CD, it also knows several locations on the Internet where it could be. Therefore, if your system is connected to the Internet, the port's source code will be automatically downloaded as part of the installation process.

The Ports Collection ease of use comes from another solved problem: port interdependency. If a port was written using the Tcl/Tk programming language and you do not have Tcl/Tk installed, the Ports Collection will also download and install the required version of it. This greatly simplifies the way applications are installed and makes even the most complicated software packages easy to work with.

An Anatomy of a Port

A basic port has a very simple structure. For an example, we'll look at a port called UWATCH. This is considered a system utility, therefore the port information is located in /usr/ports/ sysutils/uwatch. The port itself has the following structure:

Makefile
files
files/md5
pkg
pkg/COMMENT
pkg/DESCR
pkg/PLIST
patches
patches/patch-aa

Each of these files contains information essential to a port. The following is a breakdown of the information contained in each file.

• Makefile

  This is the file read in by the make install command. It contains the port's name, location, creator, and what other ports it depends on. The Makefile from UWATCH is very simple:

  
  # New ports collection makefile for: uwatch 
  # Date created: 3 November 1999
  # Whom: James Howard <howardjp@wam.umd.edu>
  #
  # $FreeBSD: ports/sysutils/uwatch/Makefile,v 1.3 2000/04/22 10:13:31 mharo Exp $
  #
  
  

  This preamble lists the name of the port, the date it was created, and the creator. This is meant to be human readable. The information contained between dollar signs ("$") is version control information from CVS and tells the last time the file was modified and who modified it.

  
  PORTNAME=    uwatch
  PORTVERSION= 1.0
  CATEGORIES=  sysutils
  
  

  These two variables set the name of the port and the most recently available version. The CATEGORIES variable lists all the possible categories this port belongs in.

  
  MASTER_SITES= ftp://ftp.wam.umd.edu/pub/howardjp/software/uwatch/ \
  	      http://www.wam.umd.edu/howardjp/software/uwatch/ \
  	      ftp://dragon.ham.muohio.edu/pub/howardjp/software/uwatch/
  
  

  This variable lists a number of URLs where the port can be downloaded from if it is not already on the system.

  
  MAINTAINER= howardjp@wam.umd.edu
  
  

  This lists the email address of the creator of the port. In this case, my email address is listed.

  
  MAN1=          uwatch.1
  MANCOMPRESSED= yes
  
  

  This is information for the online documentation set, usually called the man pages.

  
  .include <bsd.port.mk>
  
  

  This is the last line of every port's Makefile and it instructs make to call the system-wide Ports Makefile which does the heavy lifting.

• files

  This is a directory which contains files needed to build the port. Usually, this directory contains a single file, md5.

  • files/md5

    This file contains an MD5 electronic signature of the port. This is used to verify the integrity of a port before it is built. If the signatures do not match, the build will be stopped.

• patches

  This directory holds information on patching the program to run on FreeBSD. Some ports were not developed natively on FreeBSD and those may require some changes before the build. There can be a number of patch files listed all named patch-?? where "??" are two letters. The patches are applied in alphabetical order.

  • patches/patch-aa

    This port only has one patch instructing the UWATCH Makefile where to install the finished program.

• pkg

  The Ports Collection has a twin known as the Packages Collection. The Packages Collection is a set of pre-made ports which only need to be installed. Almost all packages are built from ports and some data is needed for the packages to be created. This data lives in the pkg directory.

  • pkg/COMMENT

    This is a one sentence description of the package. In this example, the description is:

    
    Monitor user logins and logouts
    
    

  • pkg/DESCR

    This is a longer description of the package and may be several paragraphs long. Since UWATCH is a simple program, this description is still relatively short.

    
    Uwatch gives notifications when all, or selected users login and logout of
    the system. It can also give the time, port, and calling host of the
    login.
    
    

  • pkg/PLIST

    This final file lists all the other files installed. In this case, only one other file is installed, the actual program. This list is used when deleting a package from the system.

    
    bin/uwatch
    
    

  Later, if you want to uninstall this port, those files listed in pkg/PLIST will be removed.

Using a Port

Now, installing this program is a simple process as shown above. The steps listed above will yield this output:

root@byzantine:# cd /usr/ports/sysutils/uwatch/
root@byzantine:/usr/ports/sysutils/uwatch# make install
>> uwatch-1.0.tar.gz doesn't seem to exist on this system. 
>>Attempting to fetch from ftp://ftp.wam.umd.edu/pub/howardjp/software/uwatch/. 
Receiving uwatch-1.0.tar.gz (4373 bytes): 100% 
4373 bytes transferred in 0.2 seconds (22.73 Kbytes/s) 
===> Extracting for uwatch-1.0 
>> Checksum OK for uwatch-1.0.tar.gz. 
===> Patching for uwatch-1.0 
===> Applying FreeBSD patches for uwatch-1.0 
===> Configuring for uwatch-1.0 
===> Building for uwatch-1.0 
Warning: Object directory not changed from original usr/ports/sysutils/uwatch/work/uwatch-1.0 
cc -Wall -I/usr/local/usr/include -c uwatch.c 
cc -Wall -I/usr/local/usr/include -o uwatch uwatch.o 
gzip -cn uwatch.1 > uwatch.1.gz 
===> Installing for uwatch-1.0 
install -c -s -o root -g wheel -m 555 uwatch /usr/local/bin 
install -c -o root -g wheel -m 444 uwatch.1.gz /usr/local/man/man1 
===> Generating temporary packing list 
===> Registering installation for uwatch-1.0 
root@byzantine:/usr/ports/sysutils/uwatch#

At this point, the application is ready to be run. If we wish to remove the application, we simply run make deinstall.

root@byzantine:/usr/ports/sysutils/uwatch# make deinstall 
===> Deinstalling for uwatch-1.0 
root@byzantine:/usr/ports/sysutils/uwatch#

And the application has been removed.

Using the Ports Collection simplifies the work required to install and maintain third-party applications and greatly reduces the time required by the system administrator to install and configure software. This makes the Ports Ports Collection one of the most attractive reasons to use FreeBSD.