The Ports Collection
Package documentation
Once you have installed your port, you'll want to use it. In almost every case, that requires documentation. Most packages have documentation, but unfortunately it's not always obvious where it is. In some cases, the port doesn't install all the documentation.
More generally, there are the following possibilities:
- If the port includes man pages, they will be installed in /usr/X11R6/man, if the package is related to X, and /usr/local/man, if they are not. Typically installing the man pages is the last thing that happens during the installation, so you should see it on the screen. If not, or if you want to check, you can have a look at the package list:
$ cd /var/db/pkg $ pkg_info -L emacs-21.2_l|grep /man/ /usr/local/man/man1/ctags.1.gz /usr/local/man/man1/emacs.1.gz /usr/local/man/man1/etags.1.gz /usr/local/man/man1/gfdl.1.gz
You don't need to change the directory to /var/db/pkg, but if you do, you can use file name completion to finish the name of the package. We use /man/ as the search string, and not simply man, because otherwise other files might match as well.
- If the package includes GNU info pages, you can use the same method to look for them:
$ pkg_info -L emacs-21.2_l|grep /info/ /usr/local/info/ada-mode /usr/local/info/autotype /usr/local/info/ccmode /usr/local/info/cl (many more)
This isn't normally necessary, though: if you're using GNU info, the index page will be updated to include the package.
- If the package includes hard copy documentation, it may or may not be included in the port. The Emacs, documentation also includes a user's guide and a programmer's guide. The user's guide, all 640 pages of it, is in the directory man of the Emacs build directory, but it doesn't get built during installation. This is typical of most ports. In this case you'll have to build the documentation yourself.
Getting binary-only software
A lot of software doesn't need to be ported. For example, if you want Netscape , you can just download it from ftp://ftp.netscape.com. But how, do you install it? Netscape's installation procedures are getting better, but they still leave something to be desired.
The answer's simple: take the port! Although Netscape comes only in binary form, the port handles getting the correct version and installing it for you. Another advantage to using a port instead of installing the package manually is that the port installs the software as a FreeBSD package, which makes it much easier to remove the software later.
This method can be used to install some other software as well, for example Star Office. The moral is simple: always check the Ports Collection before getting a software package from the Net.
Maintaining ports
Once you install a port, you might consider that to be the end of the story. That's seldom the case. For example:
- You might need to replace a port with a newer version. How do you do it? We'll look at that below.
- One day, you might find your disk fills up, so you go looking for old ports you don't use anymore. We'll look at some utility commands on page 178.
Upgrading ports
From time to time, new versions of software will appear. There are a number of approaches to upgrading:
- You can remove the old version of the port and install a new version. The trouble here is that removing the old version might remove any configuration files as well.
- You can install a new version without removing the old version. The trouble here is that you end up with two entries in the packages database /var/db/pkg:
$ pkg_info | grep emacs emacs-21.1_5 GNU editing macros emacs-21.2_1 GNU editing macros
Clearly you don't need emacs-21.15 anymore. In fact, it's not complete anymore, because the program /usr/local/bin/emacs has been overwritten by the new version. But you can't remove it either: that would remove components of emacs-21.2_1, which you want to keep. On the other hand, if you don't remove it, you are left with nearly 50 MB of disk space used up in the directory /usr/local/share/emacs/21.1.
- You can use portupgrade, a program that does some of the upgrading automatically. We'll look at this below.
Using portupgrade
Portupgrade is—what else?—a port. Install it in the usual manner:
# cd /usr/ports/sysutils/portupgrade # make install
Before you can perform the upgrade, you should first back up /var/db/pkg, then build a ports database with pkgdb. A typical build might look like this:
# cd /var/db # tar czvf db.pkg.tar.gz pkg/ # pkgdb -F [Updating the pkgdb <format:bdb1_btree> in /var/db/pkg ... - 181 packages found (-5 +92) (...)...............done] Checking the origin of AbiWord-1.0.3 Checking the origin of ImageMagick-5.5.1.1 Checking the origin of ORBit-0.5.17 ... Checking the origin of xv-3.10a_3 Checking the origin of zip-2.3_1 Checking for origin duplicates Checking AbiWord-1.0.3 Checking ImageMagick-5.5.1.1 Stale dependency: ImageMagick-5.5.1.1 -> ghostscript-gnu-7.05_3: ghostscript-gnu-6.52_4 (score:64%) ? ([y]es/[n]o/[a]ll) [no] y Fixed. (-> ghostscript-gnu-6.52_4) Checking ORBit-0.5.17 Checking XFree86-4.2.0_1,1 Checking bonobo-1.0.21_1 Stale dependency: bonobo-1.0.21_1 -> ghostscript-gnu-7.05_3: ghostscript-gnu-6.52_4 ? ([y]es/[n]o/[a]ll) [yes] Enter pressed Fixed. (-> ghostscript-gnu-6.52_4) Checking cdrtools-1.11.a28 ... Checking xv-3.10a_3 Checking zip-2.3_1 Regenerating +REQUIRED_BY files Checking for cyclic dependencies
In this example, the port ghostscript-gnu-7.05 3 had been replaced by the earlier version ghostscript-gnu-6.52_4, since ghostscript Release 7 has some annoying bugs. The dialogue shows how pkgdb, recognized the discrepancy, and how it recovered from it.
Now you can start the upgrade. To upgrade a specific port, simply specify its base name, without the version number. This example uses the -v, option to show additional information:
# portupgrade -v bison ---> Upgrade of devel/bison started at: Mon, 04 Nov 2002 13:20:52 +1030 ---> Upgrading 'bison-1.35_1' to 'bison-1.75' (devel/bison) ---> Build of devel/bison started at: Mon, 04 Nov 2002 13:20:52 +1030 ... normal port build output ===> Registering installation for bison-1.75 make clean issued by portupgrade ===> Cleaning for libiconv-1.8_2 ===> Cleaning for gettext-0.11.5_1 ... ---> Removing the temporary backup files ---> Installation of devel/bison ended at: Mon, 04 Nov 2002 13:23:00 +1030 (consume d00:00:06) ---> Removing the obsoleted dependencies ---> Cleaning out obsolete shared libraries ---> Upgrade of devel/bison ended at: Mon, 04 Nov 2002 13:23:01 +1030 (consumed 00: 02:08) ---> Reporting the results ( + :succeeded / -:ignored / *:skipped / !:failed) +devel/bison (bison-1.35_1)
If the port is already up to date, you'll see something like this:
# portupgrade -v perl-5.8.0_3 ** No need to upgrade 'perl-5.8.0_3' (>= perl-5.8.0_3). (specify -f to force) ---> Reporting the results ( + :succeeded / -:ignored / *:skipped / !:failed) -lang/perl5.8 (perl-5.8.0_3)
To upgrade all ports, use the command:
# portupgrade -a
Controlling installed ports
We've already seen the program pkg_add, when installing pre-compiled packages. There are a number of other pkg_ programs that can help you maintain installed ports, whether they have been installed by pkg_add, or by make install from the Ports Collection:
-
pkg_info, tells you which ports are installed. For example:
$ pkg_info | less AbiWord-1.0.3 An open-source, cross-platform WYSIWYG word proces ImageMagick-5.5.1.1 Image processing tools (interactive optional--misc ORBit-0.5.17 High-performance CORBA ORB with support for the C XFree86-4.2.0_1,1 X11/XFree86 core distribution (complete, using min ... etc bash-2.05b.004 The GNU Bourne Again Shell bison-1.75 A parser generator from FSF, (mostly) compatible w bonobo-1.0.21_1 The component and compound document system for GNO cdrtools-1.11.a28 Cdrecord, mkisofs and several other programs to re ... etc elm-2.4ME+22 ELM Mail User Agent elm-2.4ME+32 ELM Mail User Agent
Note that the last two entries in this example show that two versions of elm, are installed. This can't be right; it happens when you install a new version without removing the old version and without running portupgrade. We'll discuss this matter further below.
- If you have the ports tree installed, you can use pkg_version, to check whether your ports are up to date. pkg_version, is a little cryptic in its output:
The symbols to the right of the package names have the following meanings:
- There are two ways to remove a port: if you've built it from source, and you're in the build directory, you can write:
# make deinstall
Alternatively, you can remove any installed package with pkg_delete. For example, the list above shows two versions of the elm, mail user agent. To remove the older one, we enter:
# pkg_delete elm-2.4ME+22 File Vusr/local/man/manl/answer.l' doesn't really exist. Unable to completely remove file '/usr/local/man/manl/answer.1' File Vusr/local/man/manl/checkalias.l' doesn't really exist. Unable to completely remove file '/usr/local/man/manl/checkalias.l' ... etc Couldn't entirely delete package (perhaps the packing list is incorrectly specified?)
In this case, it looks as if somebody has tried to remove the files before, so pkg_delete, couldn't do so.
Another problem with pkg_delete, is that it might delete files of the same name that have been replaced by newer packages. After performing this operation, we try:
$ elm bash: elm: command not found
Oops! We tried to delete the old version, but we deleted at least part of the new version. Now we need to install it again.
The moral of this story is that things aren't as simple as they might be. When you install a new version of a package, you may want to test it before you commit to using it all the time. You can't just go and delete the old version. One possibility would be to install the new package, and try it out. When you've finished testing, delete both, packages and re-install the one you want to keep.
Keeping track of updates
The best way to find out about updates is to subscribe to the FreeBSD-ports mailing list. That way, you will get notification every time something changes. If you're tracking the ports tree with CVSup, you also get the updates to the ports tree automatically. Otherwise you will have to download the port. In either case, to update your installed port, just repeat the build.
Submitting a new port
The Ports Collection is constantly growing. Hardly a day goes by without a new port being added to the list. Maybe you want to submit the next one? If you have something interesting that isn't already in the Ports Collection, you can find instructions on how to prepare the port in the FreeBSD Porter's Handbook. The latest version is available on the FreeBSD web site, but you'll also find it on your system as /usr/share/doc/en/porters-handbook/index.html.