4.3. Troubleshooting

Ah, you must be thinking of the serial ports on the back of your computer. We are using ``port'' here to mean the result of ``porting'' a program from one version of UNIX to another.

Yes, that is usually the quickest and easiest way of doing it.

Several reasons:

1. The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.

2. Some people do not trust binary distributions. At least with source code, you can (in theory) read through it and look for potential problems yourself.

3. If you have local patches, you will need the source in order to apply them.

4. You might have opinions on how a program should be compiled that differ from the person who did the package--some people have strong views on what optimization settings should be used, whether to build debug versions and then strip them or not, and so on.

5. Packages are normally built with quite conservative settings. If a port has a compilation option to use code for a specific processor, or a particular add-on board you can enable this yourself in the port, without the people making the package having to produce many, many different packaged versions.

   The most obvious exception to this rule is paper sizes. If a package can be provided with default support for different paper sizes we will often provide multiple packages, one per paper size.

6. Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on.

7. If you ain't got the source, it ain't software! ;-)

A patch is a small file that specifies how to go from one version of a file to another. It contains plain text, and basically says things like ``delete line 23'', ``add these two lines after line 468'', or ``change line 197 to this''. They are also known as diffs because they are generated by the diff program.

It is a file ending in .tar, or with variations such as .tar.gz, .tar.Z, .tar.bz2, and even .tgz.

Basically, it is a directory tree that has been archived into a single file (.tar) and optionally compressed (.gz). This technique was originally used for Tape ARchives (hence the name tar), but it is a widely used way of distributing program source code around the Internet.

You can see what files are in them, or even extract them yourself by using the standard UNIX tar program, which comes with the base FreeBSD system, like this:

    % tar tvzf foobar.tar.gz
    % tar xzvf foobar.tar.gz
    % tar tvf foobar.tar
    % tar xvf foobar.tar

It is a number generated by adding up all the data in the file you want to check. If any of the characters change, the checksum will no longer be equal to the total, so a simple comparison will allow you to spot the difference.

As was explained in the compiling ports from CDROM section, some ports cannot be put on the CDROM set due to licensing restrictions. Kermit is an example of that. The licensing terms for kermit do not allow us to put the tarball for it on the CDROM, so you will have to fetch it by hand--sorry!

The reason why you got all those error messages was because you were not connected to the Internet at the time. Once you have downloaded it from any of the MASTER_SITES (listed in the Makefile), you can restart the install process.

The ports mechanism looks for the tarball in /usr/ports/distfiles, but you will not be able to copy anything there because it is symlinked to the CDROM, which is read-only. You can tell it to look somewhere else by doing:

    # make DISTDIR=/where/you/put/it install

You can use the PORTSDIR and PREFIX variables to tell the ports mechanism to use different directories. For instance,

    # make PORTSDIR=/u/people/guests/wurzburger/ports install

will compile the port in /u/people/guests/wurzburger/ports and install everything under /usr/local.

    # make PREFIX=/u/people/guests/wurzburger/local install

will compile it in /usr/ports and install it in /u/people/guests/wurzburger/local.

And of course,

    # make PORTSDIR=../ports PREFIX=../local install

will combine the two (it is too long to write fully on the page, but it should give you the general idea).

If you do not fancy typing all that in every time you install a port, it is a good idea to put these variables into your environment. Read the man page for your shell for instructions on doing so.

To get every single tarball for the Ports collection, do:

    # cd /usr/ports
    # make fetch

For all the tarballs for a single ports directory, do:

    # cd /usr/ports/directory
    # make fetch

and for just one port--well, I think you have guessed already.

Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you than the sites listed in MASTER_SITES, do as follows:

    # cd /usr/ports/directory
    # make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch

make fetch-list will display a list of the files needed for a port.

Doing make extract will stop it after it has fetched and extracted the source code.

Yep, make patch is what you want. You will probably find the PATCH_DEBUG option useful as well. And by the way, thank you for your efforts!

Yes, with version 2.6.3 of gcc (the version shipped with FreeBSD 2.1.0 and 2.1.5), the -O2 option could result in buggy code unless you used the -fno-strength-reduce option as well. (Most of the ports do not use -O2). You should be able to specify the compiler options used by something like:

    # make CFLAGS='-O2 -fno-strength-reduce' install

or by editing /etc/make.conf, but unfortunately not all ports respect this. The surest way is to do make configure, then go into the source directory and inspect the Makefiles by hand, but this can get tedious if the source has lots of sub-directories, each with their own Makefiles.

The default FreeBSD compiler options are quite conservative, so if you have not changed them you should not have any problems.

Look in the INDEX file in /usr/ports. If you would like to search the ports collection for a keyword, you can do that too. For example, you can find ports relevant to the LISP programming language using:

    % cd /usr/ports
    % make search key=lisp

The foo port needs something that is supplied with bar -- for instance, if foo uses graphics, bar might have a library with useful graphics processing routines. Or bar might be a tool that is needed to compile the foo port.

No problem, just do:

    # pkg_delete grizzle-6.5

Alternatively, you can do:

    # cd /usr/ports/somewhere/grizzle
    # make deinstall

Not at all, you can find it out by doing:

    # pkg_info -a | grep grizzle
    Information for grizzle-6.5:
    grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
    arcade game.

Yes, if you have installed the program and are fairly certain you will not need the source again, there is no point in keeping it hanging around. The best way to do this is:

    # cd /usr/ports
    # make clean

which will go through all the ports subdirectories and delete everything except the skeletons for each port.

Yes, if you are sure you have finished with them, those can go as well. They can be removed manually, or by using make distclean.

Just do:

    # cd /usr/ports
    # make install

Be careful, as some ports may install files with the same name. If you install two graphics ports and they both install /usr/local/bin/plot then you will obviously have problems.

No, the problem is that some of the ports need to ask you questions that we cannot answer for you (e.g., ``Do you want to print on A4 or US letter sized paper?'') and they need to have someone on hand to answer them.

OK, do this before you go to bed/work/the local park:

    # cd /usr/ports
    # make -DBATCH install

This will install every port that does not require user input. Then, when you come back, do:

    # cd /usr/ports
    # make -DIS_INTERACTIVE install

to finish the job.

No problem, assuming you know how to make patches for your changes:

    # cd /usr/ports/somewhere/frobble
    # make extract
    # cd work/frobble-2.8
    [Apply your patches]
    # cd ../..
    # make package

Nothing secret about it at all, just look at the bsd.port.mk and bsd.port.subdir.mk files in your makefiles directory.

(Readers with an aversion to intricate shell-scripts are advised not to follow this link...)