Updating and Maintaining Your Ports
| Software changesand in the open-source community, it changes all the time. There are nearly 14,000 ports in the collection, and each one of them is undergoing development (some at much faster rates than others). A fact of system administration is that you can't install or upgrade software fast enough to keep up with the rate of development. The best you can hope to do is keep your ports collection up to date and use the built-in tools, such as pkg_version, to keep track of what needs to be upgraded. Tip If you regularly build software from the ports, you should be in the habit of reading the regularly updated /usr/ports/UPDATING file and skimming it for changes to ports that pertain to you. Pay special attention to the AFFECTS: line in each update, as it describes the particular users of various ports that will need to know about special upgrading instructions or important security notices. Keeping Ports Up to Date with CVSupTo keep your ports synchronized, the best tool for the job is CVSup. In Chapter 19, you'll learn about CVSup in detail. Because CVSup is an essential tool for working efficiently with ports, it's important that you know some of its simplest usesand there really isn't much to it. First, install the cvsup package, either by using the package system or by building it from the ports. In fact, it's better to use the package version because CVSup is a tool written in Modula-3, meaning that building it from source involves building several large Modula-3 dependencies, which takes forever and installs a ton of libraries that you'll probably never need for anything else. Use the package installation to get past that for now. Note A lot of ports have the same problem as CVSup: they require huge dependency programs, which you might not need or want on your system, to be built and installed. For instance, building a simple graphics library can cause the entire X11 system to be downloaded, compiled, and installed without your foreknowledge. For this reason, you should lean towards using the packages rather than the ports if you can help it. The next step is to create a CVSup config file, known as a supfile. The purpose of this task is to update your ports, so call the file ports-supfile. As with other configuration files that you create for tasks that aren't part of the basic system, it's best to put this file in /usr/local/etc. Listing 16.7 shows the contents of a suitable supfile for updating your ports. Listing 16.7. A CVSup Config File for Updating Your Ports (/usr/local/etc/portssupfile)
The supfile has a number of tunable options, most of which you'll learn about in Chapter 19. For now, the only one you need to worry about is the *default host= line, which should point to one of the central FreeBSD CVSup servers. There are 18 of these servers, named cvsup1 tHRough cvsup18, each one an alias for a source repository host located at some discrete location in the world. It's difficult to know where each host is without doing a host lookup (host cvsup12.freebsd.org) to see if the hostname to which it resolves gives a clue to its location, but it might be worth it to you to use this technique to examine each of the CVSup hosts to find the one nearest to you. Now, run the CVSup update: # /usr/local/bin/cvsup -L 2 /usr/local/etc/ports-supfileCVSup connects to the selected CVSup server and begins synchronizing your ports collection. Because of the -L 2 option (specifying the highest level of verbosity), you will see all changes between your installed version and the current one scroll by. CVSup operates by updating only files that have changed and then by updating only the changed pieces (by using diff patches). This allows you to update the entire ports collection while transferring only a minimum of data and using a minimal amount of bandwidth. A CVSup update can be done efficiently and quickly even over a very small network link. Tip If you're running CVSup within an X11 session, it will use a GUI client interface in a separate window, giving you statistics about the update process as it runs. You can disable this behavior and force CVSup to remain in CLI mode by adding the -g option to the command line. After the synchronization is complete, your ports collection is current and "up to the minute." You can now run pkg_version -v to see which ports or packages you need to update. You will probably want to make this synchronization process a part of your system's daily routine so that your ports will never be more than 24 hours out of date. To do this, add the preceding CVSup command to your daily periodic files (see "Using the Periodic Task Scheduler," in Chapter 15, "Performance Monitoring, Process Control, and Job Automation"). If it doesn't exist already, create a directory called periodic in /usr/local/etc and then another directory called daily underneath that. Inside the daily directory, create a file called something such as 100.cvsup-ports and put these lines in it: #!/bin/sh /usr/local/bin/cvsup -g -L 2 /usr/local/etc/cvsupfile Now, every night when the daily periodic script is executed, your ports collection will be synchronized. The output of CVSup is mailed to you in your daily system status update. If you prefer not to get an email after every night's regular CVSup run, you can suppress its output using the -L 0 option instead of -L 2; that way, the only conditions under which you'll get an email is if errors occurred. Notes on Forbidden PortsSometimes a port is present in the ports collection but the system doesn't allow you to build it. This is controlled by the FORBIDDEN variable in the makefile. If this variable is present, whatever text string it is set to is displayed when you try to build the port, and the build process is cancelled: # cd /usr/ports/databases/gnats # make ===> gnats-3.113.1_12 is forbidden: Security issues. A port can be marked "forbidden" for many reasons. In this example, it's because the program in question has some intractable security problems that make it dangerous to install it. In other cases, a port might be forbidden because it has been made a part of the core system, and building it from the ports would be redundant and possibly ruin the system's operation. In either case, this is a good illustration of the need to keep your ports synchronized to the CVSup server as regularly as possible. It's seldom a good idea to force the installation of a forbidden port, but it's possible to do so by simply removing the FORBIDDEN line from the makefile. Some forbidden ports do provide a built-in way to override the block by setting an environment variable, such as in this example of the security/ssh port (which no longer has this behavior, but other ports might still work this way): # cd /usr/ports/security/ssh # make ===> ssh-1.2.27_3 is forbidden: OpenSSH is a superior version of SSH which has been included in the FreeBSD base system since 4.0-RELEASE. This port is now deprecated and will be removed at some point in the future. To override this warning set the REALLY_WANT_SSH environment variable and rebuild. As the instructions say, set the indicated environment variable and try again. Here's how if you're using csh or tcsh: # setenv REALLY_WANT_SSH yesAnd here's how if you're using bash: # REALLY_WANT_SSH=yesAfter setting the variable, run make again. The port should build cleanly. Reclaiming Hard Disk Space Used by the Port-Building ProcessAfter you're done building and installing a port, the work directory is still sitting there, filled with the unpacked tree of source code and compiled binary objects. This can take up a fair amount of disk space. It's always advisable to clean this directory out after installationreturning the port to its original pristine stateby running one more make command, this time with the clean target: # make cleanThis deletes the work directory and everything in it. It also cleans out the port directory for each dependency listed. However, it does not remove the tarball files from /usr/ports/distfiles; you'll have to remove these files yourself. Tip Unless you really need the disk space, you might want to leave the tarballs intact in the /usr/ports/distfiles directory. You can save a lot of time this wayif you should ever need to rebuild or reinstall a port, the system can use the file it already has, instead of having to download it again. The beauty of ports is that if a security hole or critical bug is fixed in a port that you have installed, the ports collection might solve it by placing a patch file in the files directory of the port, not by bumping the revision number of the entire distribution file (and causing you to have to download a new tarball). A simple rebuild allows you to incorporate the new patch into your old sources. Periodically, you may want to issue a top-level recursive make clean on the entire ports collection. There's a makefile at both the /usr/ports level and in each directory in the category level below it that enables you to do odd tasks such as building all the ports in a category at once (for example, building every www port by running make from inside /usr/ports/www). More usefully, it lets you clean every port at once, in one very long recursive process. You do this simply by going to /usr/ports and entering make clean. You can now go and get a sandwich if you want; like cleaning an oven, this process will be worthwhile but usually takes forever. When a Port Will Not Build: Searching for SolutionsAs convenient as the ports collection is, it's not perfectand with the amount of change that goes on in the tree, especially with so many ports (such as the ones related to GNOME and KDE) interrelated and constantly evolving, chances are that you'll run into some stumbling blocks now and then. The general failure behavior is for the compile process to exit abruptly with "*** Error code 1" or a similar message. When this happens, you can try a number of things. First, make sure you're starting from a clean port. If there is a pre-existing work directory, it's possible that you've mixed new sources with old, resulting in an unbuildable port. Run make clean to start over from a clean slate. It's also important to make sure you have the very latest ports tree available. If a port doesn't build, it's possible that it's a temporary condition that will have affected many other FreeBSD users besides yourself. A new version of the ported software might have been released since the version your ports refer to, for example, or perhaps your ports refer to a version that was newly released at the time your ports tree was installed, and some of the patches (written for a previous version) might have inadvertently become incompatible. If your ports tree is even a few days out of date, the chances are good that the port has been fixed in the meantime. Synchronize your ports tree as discussed earlier in this chapter and try building the port again (make sure you run make clean first). If this doesn't work, it's time to seek outside assistance. Head to the FreeBSD website at http://www.freebsd.org and go to the Mailing Lists link, where you can search the mailing list archives for information about the port you're trying to build. Make sure you select the Ports check box as one of the search criteria. Then perform the search on the name of your port and some of the relevant text in the last few lines of the compiler output. If there's anything commonly failing that other people have noticed, you'll probably find something useful this way. Still no luck? There's one more good recourse: the port maintainer. Look in the port's Makefile for the MAINTAINER variable, which is set to the email address of the maintainer. Send off a politely worded, undemanding email containing the last (relevant) part of the compiler output, as well as information about your system (the output of uname -a, for instance). The maintainer is usually a very overworked, underappreciated individual, so be sure to express your gratitude for any help! |
