Chapter 9 introduced you to Ports Console, which provides a safe environment for installing software that has been ported to FreeBSD on your PC-BSD system. Chapter 9 also demonstrated how to find, install, and manage FreeBSD packages. Although FreeBSD packages are managed from the command line, they are relatively easy to use and are considered the recommended way to install additional software that is not currently available within the PBI system.
This chapter teaches you how to compile and manage FreeBSD ports.[55] This chapter is intended for power users who want to customize their software applications. Much of the information in Chapter 9 applies to this chapter as well. For example, you can use FreshPorts to find the software you would like to compile, you still issue all of the commands within Ports Console, and pkg_info will tell you what was installed. However, you will use the make command to compile and install FreeBSD ports instead of the pkg_add command.
If you're wondering whether you should install the package or compile a port for a given piece of software, you probably want to install the package. If you find yourself compiling ports without passing any make targets (that will make more sense as this chapter progresses), you definitely should be installing the package instead of compiling the port. Packages provide several advantages over ports:
They are quick to install. With the exception of very large packages such as KDE or GNOME, most packages install in under a few minutes. Depending on the number of dependencies and your hardware, the same port may take several hours to compile.
If you aren't customizing the port, you will end up with the same binary as the package would have installed, meaning you needlessly waited longer to install the software on your system.
However, at times you do want to install the port, when, for example, the following occur:
A package is not available.
You want to compile a binary with a known security vulnerability.
You want to override a license restriction. For example, the license may allow you to compile the binary for personal use but does not allow the FreeBSD project (an organization) to distribute the binary package.
You need to customize the options that are compiled into the binary; this is often done with server applications such as Apache or PostgreSQL.
So what exactly is compiling a port? Software applications are created from source code,[56] or text files written in a programming language. Those files are considered human readable, at least for those humans who understand the syntax of the programming language used. The source code must be converted into a form that the computer understands by using a program known as a compiler; the end result is the binary executable of the program. When compiling a FreeBSD port, you use the following components:
The gcc[57] compiler.
The make[58] program to manage the dependencies that are needed when a binary is compiled.
A Makefile that contains all of the instructions needed to compile the FreeBSD port.
A directory structure, known as the ports tree, containing a subdirectory for each port. Each subdirectory includes the port's Makefile, a working area, any needed patches, the post-installation message, the package description, and the checksums for the archive containing the source code.
gcc and make were installed with your PC-BSD system. However, before you can compile any ports, you have to install the ports directory structure.
To install the ports collection, choose Kickoff
Note that this operation will take some time because the ports collection is a very large tar file that needs to be downloaded and untarred to /usr/ports.
This section will familiarize you with the contents and layout of the ports directory structure. After you have the ports collection, open Ports Console and become the superuser. Figure 10-2 shows a listing of /usr/ports/.
The files and directories highlighted by the yellow square contain the information needed for the ports collection to work. If you are interested in the inner workings of the FreeBSD ports process, read Mk/bsd.port.mk (the master file used by the ports system). You will also find useful information in man ports.
The remainder of the listing is composed of directories that represent the same categories found at FreshPorts. If you list a directory, you'll find that it contains subdirectories. Each subdirectory represents a port that can be compiled, and it contains all of the information needed to compile that port. Figure 10-3 shows a listing of the /usr/ports/databases/couchdb directory.
This directory contains the following:
- Makefile:
Contains the instructions[59] make needs to compile the application.
- distinfo:
Contains the MD5 and SHA256 checksums, the size, and the name of the archive containing the source code that will be fetched from the Internet. For security reasons, the ports system will refuse to fetch an archive that doesn't match the information in this file.
- files:
This directory contains patches the software requires to compile.
- pkg-descr:
Contains the description of the software. pkg_info[60] -d can also be used to display the contents of this file.
- pkg-install:
Optional script used during the installation. pkg_info -i can also be used to display the contents of this file.
- pkg-message:
Optional message (usually containing post-installation configuration information) that will be displayed at the end of the installation. If you missed the message or wish to reread it, you can find it here. pkg_info -D can also be used to display the contents of this file.
- pkg-plist:
Contains the paths to the files that are installed with the application. /usr/local is assumed to be at the beginning of each path. For example, if the file gives a location of bin/couchdb, the actual path is /usr/local/bin/couchdb.
Let's compare this information to Figure 10-4, which shows the CVSWeb page for couchdb at FreshPorts.
Note that FreshPorts contains the same files, enabling you to research your ports online before compiling them. CVSWeb has an added advantage in that it shows the entire history for each file. For example, if you click the Makefile link, you will see a history of the Makefile for every version of the port, along with the commit messages that indicate which changes were made and when. If you want to see only the current Makefile, click on the number in the Rev. (revision) column instead—in this example, the Makefile is at revision 1.7.
To compile a port, simply cd to its subdirectory and type make. Wait until the messages stop, and if all goes well, you'll receive your prompt back without any errors.
To understand what actually happened and how you can customize what happens, you should know a bit about make targets. Targets are the words that follow the make command. The most commonly used targets[61] are summarized in Table 10-1. Note that targets are optional but very useful. For example, if you just type make, the port will compile, but it won't install unless you add the install target (that is, type make install).
Table 10-1. Useful make Targets
Target | Description |
|---|---|
clean | make will create a work subdirectory when you compile a port. This target tells make to remove that directory before returning your prompt. Use the clean-depends target if you also want to clean out the work directory for each dependency. |
config | Some ports provide a menu of options that enable you to choose which features to compile into the application (see Figure 10-5 for an example). Your original selection is saved in a subdirectory of /var/db/ports/. If you want to change your selection, use this target to access the port's menu screen. Use the config- recursive target if you want to see all the menus for each dependency. |
deinstall | If you try to install a port that is already installed, you will receive an error message. Use this target first to uninstall the port. For example: make deinstall && make install. |
fetch | This target downloads the source code and patches for the port but does not compile anything. The source code will be saved to /usr/ports/distfiles/. Use fetch-recursive if you want to also fetch the source for the port's dependencies. |
install | This target tells make to install the files listed in pkg-plist to their locations in /usr/local/. This can take some time because they need to be compiled first. |
package | Creates a FreeBSD package in the current directory (the file will end in .tbz). This is useful if you need to install the same software on multiple machines because you have to compile it only once. If you would like to compile all of the package's dependencies as well, use the package-recursive target instead. |
Figure 10-5 shows the configuration options for /usr/ports/www/apache22. Those options with an X will be compiled into the application. Use your arrow key to highlight an option and the Enter key to toggle between X and a blank. When finished, use the Tab key to jump to OK and press Enter.
Tip
If you run make config-recursive and don't receive any menus, you might as well save yourself some time and install the package because there isn't anything to customize for that port.
The TARGETS section of man ports indicates that some targets build upon each other in order. For example, make install is equivalent to make config fetch checksum depends extract patch configure build install. In other words, if you use a target within that ordered list, it will "automagically" include all of the targets that precede it. This means that if you type make config, make will only display the port's options menu, if it exists. It will not fetch or build any source because those targets come after the config target. However, if you type make install, make will go through all of the targets, starting with config, then fetch, all the way up to install.
You may have noticed that each category directory also has a Makefile. This means that you could (if you had a lot of time) install every port in that category by typing make install. For example, to build all www ports, issue the command cd /usr/ports/www && make install.
Tip
make reads only the Makefile in the current directory. If there is no Makefile in your current directory, make will give the error "make: no target to make." This means you should cd to the desired directory and try again.
There are make targets that are useful within a category directory or the /usr/ports/ directory itself. One is make readmes, which creates a local HTML copy of the specified ports structure. Figure 10-6 shows the resulting web page from running the make readmes command from the /usr/ports/ directory. You can click on each category to see a listing of its ports.
Another useful target to use from /usr/ports/ is search. The first time you run make search, you may be asked to run make fetchindex first. Figure 10-7 shows the results from running make search name=youtube | more from /usr/ports/.
The name= keyword in this command tells make to search for port names matching your search pattern. The search results will show the following:
- Port:
The name and version of the port
- Path:
The port's location within the ports directory
- Info:
A one-line description of the port
- Maint:
The e-mail address of the port's maintainer
- B-deps:
The names and version numbers of the dependencies required to build the port
- R-deps:
The names and version numbers of the dependencies required to run the application compiled by the port
- WWW:
The URL to the website for the software
Like packages, ports have been pretested for you and should compile on your system without errors. Occasionally you will receive an error message indicating that the port did not compile. If you receive the error almost immediately, one of the variables in Table 10-2 is probably set in the port's Makefile.
Table 10-2. Makefile Variables You Should Be Aware Of
Variable | Description |
|---|---|
BROKEN= | This line in the Makefile will indicate the reason why the port is considered broken. You should probably look for a newer version or another port with similar functionality as this port is waiting for the maintainer to fix the problem. |
CONFLICTS= | The Makefile will indicate which application the port conflicts with. If you uninstall the conflicting software, the error will disappear. |
DEPRECATED= | This won't stop the compile but will give the message "This port is deprecated; you may wish to reconsider installing it." This typically means that there is a newer version of the port that you should be using instead. |
EXPIRATION_DATE= | This won't result in an error, but you should check for this in a Makefile. If this line exists, consider another version of the port or a similar port because this one will be disappearing soon. |
The Makefile will indicate why the port is forbidden. | |
RESTRICTED= | This won't result in an error, but you should read the message if this line is in the Makefile because it may indicate a patent or license restriction that affects your use or distribution of the application. |
Of course, you can remove the offending variable from the Makefile to force the port to compile, but that won't change the underlying reason for including the variable.
If you receive a "Couldn't fetch it – please try to retrieve this port manually into /usr/ports/distfiles/ and try again" error, double-check your Internet connection and try again.
Note
Ports Console assumes you are running the default pf firewall. If you have disabled pf, you will have to type pfctl -ef /etc/pf.conf in Konsole in order to have Internet connectivity within Ports Console.
If your error does not seem to be connected with the Makefile or Internet connectivity, try googling the error message to see if there is a known fix. Or try installing another version of the port. If you're still not having any luck, send an e-mail to the FreeBSD ports mailing list.[62] If this is your first e-mail to the list, be sure to read How to Get Best Results from the FreeBSD-Questions Mailing List[63] first as the information it contains applies to all of the FreeBSD mailing lists.
The ports collection is constantly being updated, with new ports being added daily, broken ports being fixed (and sometimes working ports becoming broken), and ports being updated to newer versions of the software. The csup utility enables you to sync with the current version of the ports tree whenever you wish.[64] In order to use csup, you need a configuration file. A well-commented configuration file is located in /usr/share/examples/cvsup/ports-supfile. If this is your first time using csup, take the time to read through the comments in the example file because they explain the meaning of each line in the file. Figure 10-8 demonstrates a customized configuration file saved as /root/cvs-supfile, as well as the csup command used to connect to the specified mirror (in this case, cvsup.FreeBSD.org) to sync the local ports tree with the latest release version (RELENG_8) of the ports tree.
Once connected, csup will compare the files on the mirror with your local copy of the ports collection and will download only the files that have changed or are missing.
Tip
Power users who would like to keep their ports tree updated on a regular basis should consider adding that csup -L2 command to their crontab within Ports Console.
If you keep your ports tree up-to-date with csup, you can use the portupgrade application to update your installed ports to their latest versions. But first you need to know which ports have newer versions. In this section, you'll create a notification script and then learn how to use portupgrade.
Although PC-BSD's Software Manager won't tell you when newer versions of FreeBSD ports or packages are available, it is easy to create a custom script to do this for you. First, you should install some useful packages by using pkg_add:
- portaudit:
Used to compare your installed software to the VuXML database of software vulnerabilities. (Chapter 9 discussed VuXML.)
- portupgrade:
Used to upgrade both your installed ports and packages to their latest versions.
Figure 10-9 shows an example script, and Figure 10-10 shows the results of running the script.
In this example, none of the installed software has any known security vulnerabilities, as portaudit indicates "0 problem(s) in your installed packages found." If there was a known vulnerability, portaudit would have displayed the name of the software and a description of the vulnerability. Two ports, however, need upgrading: portaudit and ruby.
If you have software that needs updating, you can use portupgrade to upgrade it. It doesn't matter whether you installed the software from a package or compiled it from a port—it can still be upgraded. Table 10-3 shows the most common switches used with portupgrade. See man portupgrade for a description of all available switches.
Table 10-3. Commonly Used portupgrade Switches
Switch | Description |
|---|---|
a | Upgrade all installed software that has a newer version. Otherwise, specify the name of the software to upgrade. |
b | Make a backup package of the old version. This is very handy should something go wrong and you need to revert to the original version. You'll find the package in /usr/ports/packages/All. |
n | Allows you to do a "dry run" as it creates a report of what would be upgraded without actually upgrading anything. |
P | First tries to upgrade by using a package, meaning the upgrade process will be quicker if a package is available. If there is no package, portupgrade will compile the port. |
r | Also upgrades any software that depends on the software being upgraded. |
R | Also upgrades any software required by the software being upgraded. |
portupgrade switches can be stacked, and order does not matter unless the switch requires that it is followed by a variable (add those switches and their variables individually after your stacked switches). For example, you can type portupgrade -an instead of portupgrade -a -n. It is recommended that you always include -rR to make sure all dependent software is also upgraded. If you don't, over time you may run into dependency issues. It is also recommended that you include -b just in case something goes wrong. If you have problems with the new software, use pkg_delete to uninstall the new version and pkg_add to install the backed-up package of the original software.
Warning
Never upgrade a port without first reading /usr/ports/UPDATING to see if there are any known gotchas or upgrade hints for that software. Always follow any instructions in this file that apply to the software you are trying to upgrade.
The upgrade process usually goes like this:
Use your notification script to get the latest version of the ports tree and ports index and to determine which software is vulnerable or has a newer version.
Decide whether you want to upgrade all of your outdated software or only a specific application.
Read /usr/ports/UPDATING to see whether there are any special instructions for the software you wish to upgrade.
If you have customized configuration files for the software being updated (for example, a customized httpd.conf for Apache), make sure you have a backup of those files.
Run a command such as portupgrade -abrR to upgrade all software, or portupgrade -brR name_of_software to upgrade only the specified software.
Your software upgrade should "just work." If you run across an error, double-check your Internet connectivity, check that you didn't miss anything in /usr/ports/UPDATING, or try googling the error. You can also try waiting a day or so and rerunning csup because sometimes a missing patch will be added to the ports tree. On the off chance that the new version doesn't work, you'll be glad that you saved a backup package of the old version. This last scenario is rare, but it is always best to be safe rather than sorry!
To uninstall a port, cd into its directory and type make deinstall. FreshPorts or pkg_info -ox will tell you the port's location in the ports tree.
Alternately, you can delete the port by using pkg_delete. Either way, you can then use pkg_info to verify that the software has been uninstalled.
Warning
The pkg_delete command will not let you uninstall software that is required by other applications. However, make deinstall will. If you're worried about inadvertently uninstalling dependencies, use pkg_delete instead.
This chapter covered the basics of the FreeBSD ports system. Power users seeking additional information should read through the resources mentioned in the footnotes of this chapter. This chapter also concludes the "Software" section of this book. The next section deals with community, and Chapter 11 will introduce you to the PC-BSD community.
[55] See www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html for further information about managing ports.
[56] http://en.wikipedia.org/wiki/Source_code
[57] http://en.wikipedia.org/wiki/GNU_Compiler_Collection
[58] See make for Nonprogrammers for more information: http://onlamp.com/pub/a/bsd/2005/03/24/FreeBSD_Basics.html
[59] A Makefile's contents are described in more detail in www.freebsd.org/doc/en/books/porters-handbook/book.html#MAKEFILE.
[60] man pkg_info is well worth reading. Try each of its switches to discover which are useful to you.
[61] The complete list of targets is listed in /usr/ports/Mk/bsd.port.mk and man ports.
[62] http://lists.freebsd.org/mailman/listinfo/freebsd-ports
[63] www.freebsd.org/doc/en_US.ISO8859-1/articles/freebsd-questions/article.html
[64] The FreeBSD Handbook covers this utility in more detail: www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/cvsup.html.