4.6 Troubleshooting

The following sections cover some of the more frequently asked questions about the ports collection and some basic troubleshooting techniques, and what do to if a port is broken.

4.6.1 Some Questions and Answers

4.6.1.1. I thought this was going to be a discussion about modems??!
4.6.1.2. What is a patch?
4.6.1.3. What is all this about tarballs?
4.6.1.4. And a checksum?
4.6.1.5. I did what you said for compiling ports from a CDROM and it worked great until I tried to install the kermit port.
4.6.1.6. I did that, but when I tried to put it into /usr/ports/distfiles I got some error about not having permission.
4.6.1.7. Does the ports scheme only work if you have everything in /usr/ports? My system administrator says I must put everything under /u/people/guests/wurzburger, but it does not seem to work.
4.6.1.8. I do not have a FreeBSD CDROM, but I would like to have all the tarballs handy on my system so I do not have to wait for a download every time I install a port. Is there any way to get them all at once?
4.6.1.9. I know it is probably faster to fetch the tarballs from one of the FreeBSD mirror sites close by. Is there any way to tell the port to fetch them from servers other than the ones listed in the MASTER_SITES?
4.6.1.10. I want to know what files make is going to need before it tries to pull them down.
4.6.1.11. Is there any way to stop the port from compiling? I want to do some hacking on the source before I install it, but it is a bit tiresome to watch it and hit control-C every time.
4.6.1.12. I am trying to make my own port and I want to be able to stop it compiling until I have had a chance to see if my patches worked properly. Is there something like make extract, but for patches?
4.6.1.13. I have heard that some compiler options can cause bugs. Is this true? How can I make sure that I compile ports with the right settings?
4.6.1.14. There are so many ports it is hard to find the one I want. Is there a list anywhere of what ports are available?
4.6.1.15. I went to install the foo port but the system suddenly stopped compiling it and starting compiling the bar port. What is going on?
4.6.1.16. I installed the grizzle program from the ports and frankly it is a complete waste of disk space. I want to delete it but I do not know where it put all the files. Any clues?
4.6.1.17. Hang on a minute, you have to know the version number to use that command. You do not seriously expect me to remember that, do you?
4.6.1.18. Talking of disk space, the ports directory seems to be taking up an awful lot of room. Is it safe to go in there and delete things?
4.6.1.19. I tried that and it still left all those tarballs or whatever you called them in the distfiles directory. Can I delete those as well?
4.6.1.20. I like having lots and lots of programs to play with. Is there any way of installing all the ports in one go?
4.6.1.21. OK, I tried that, but I thought it would take a very long time so I went to bed and left it to get on with it. When I looked at the computer this morning, it had only done three and a half ports. Did something go wrong?
4.6.1.22. I really do not want to spend all day staring at the monitor. Any better ideas?
4.6.1.23. At work, we are using frobble, which is in your ports collection, but we have altered it quite a bit to get it to do what we need. Is there any way of making our own packages, so we can distribute it more easily around our sites?
4.6.1.24. This ports stuff is really clever. I am desperate to find out how you did it. What is the secret?

4.6.1.1. I thought this was going to be a discussion about modems??!

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.

4.6.1.2. What is a patch?

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.

4.6.1.3. What is all this about tarballs?

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

4.6.1.4. And a checksum?

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.

4.6.1.5. I did what you said for compiling ports from a CDROM and it worked great until I tried to install the kermit port.

    # make install
    >> cku190.tar.gz doesn't seem to exist on this system.
    >> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.

Why can it not be found? Have I got a dud CDROM?

As 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.

4.6.1.6. I did that, but when I tried to put it into /usr/ports/distfiles I got some error about not having permission.

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

4.6.1.7. Does the ports scheme only work if you have everything in /usr/ports? My system administrator says I must put everything under /u/people/guests/wurzburger, but it does not seem to work.

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).

Some ports that use imake(1) (a part of the X Windows System) do not work well with PREFIX, and will insist on installing under /usr/X11R6. Similarly, some Perl ports ignore PREFIX and install in the Perl tree. Making these ports respect PREFIX is a difficult or impossible job.

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 manual page for your shell for instructions on doing so.

4.6.1.8. I do not have a FreeBSD CDROM, but I would like to have all the tarballs handy on my system so I do not have to wait for a download every time I install a port. Is there any way to get them all at once?

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, you have probably guessed already.

4.6.1.9. I know it is probably faster to fetch the tarballs from one of the FreeBSD mirror sites close by. Is there any way to tell the port to fetch them from servers other than the ones listed in the MASTER_SITES?

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

4.6.1.10. I want to know what files make is going to need before it tries to pull them down.

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

4.6.1.11. Is there any way to stop the port from compiling? I want to do some hacking on the source before I install it, but it is a bit tiresome to watch it and hit control-C every time.

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

4.6.1.12. I am trying to make my own port and I want to be able to stop it compiling until I have had a chance to see if my patches worked properly. Is there something like make extract, but for patches?

Yes, 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!

4.6.1.13. I have heard that some compiler options can cause bugs. Is this true? How can I make sure that I compile ports with the right settings?

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.

4.6.1.14. There are so many ports it is hard to find the one I want. Is there a list anywhere of what ports are available?

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

4.6.1.15. I went to install the foo port but the system suddenly stopped compiling it and starting compiling the bar port. What is going on?

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.

4.6.1.16. I installed the grizzle program from the ports and frankly it is a complete waste of disk space. I want to delete it but I do not know where it put all the files. Any clues?

No problem, just type:

    # pkg_delete grizzle-6.5

Alternatively, you can type:

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

4.6.1.17. Hang on a minute, you have to know the version number to use that command. You do not seriously expect me to remember that, do you?

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

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

The version number can also be found using the pkg_info or by typing: ls /var/db/pkg

4.6.1.18. Talking of disk space, the ports directory seems to be taking up an awful lot of room. Is it safe to go in there and delete things?

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 surest 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.

Tip: It is possible to achieve the same effect without recursively calling each makefile. For example, you can delete all of the work subdirectories directly with the following command:

    # find /usr/ports -depth -name work -exec rm -rf {} \;


4.6.1.19. I tried that and it still left all those tarballs or whatever you called them in the distfiles directory. Can I delete those as well?

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.

4.6.1.20. I like having lots and lots of programs to play with. Is there any way of installing all the ports in one go?

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.

4.6.1.21. OK, I tried that, but I thought it would take a very long time so I went to bed and left it to get on with it. When I looked at the computer this morning, it had only done three and a half ports. Did something go wrong?

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.

4.6.1.22. I really do not want to spend all day staring at the monitor. Any better ideas?

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 -DINTERACTIVE install

to finish the job.

4.6.1.23. At work, we are using frobble, which is in your ports collection, but we have altered it quite a bit to get it to do what we need. Is there any way of making our own packages, so we can distribute it more easily around our sites?

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

4.6.1.24. This ports stuff is really clever. I am desperate to find out how you did it. What is the secret?

Nothing secret about it at all, just look at the bsd.port.mk and bsd.port.subdir.mk files in /usr/ports/Mk/.

(Readers with an aversion to intricate shell-scripts are advised not to look at the files in this directory.)

4.6.2 Help! This Port Is Broken!

If you come across a port that does not work for you, there are a few things you can do, including:

  1. Fix it! The Porter's Handbook includes detailed information on the "Ports" infrastructure so that you can fix the occasional broken port or even submit your own!

  2. Gripe--by email only! Send email to the maintainer of the port first. Type make maintainer or read the Makefile to find the maintainer's email address. Remember to include the name and version of the port (send the $FreeBSD: line from the Makefile) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can use send-pr to submit a bug report.

  3. Grab the package from an ftp site near you. The ``master'' package collection is on ftp.FreeBSD.org in the packages directory, but be sure to check your local mirror first! These are more likely to work than trying to compile from source and are a lot faster as well. Use the pkg_add(1) program to install the package on your system.

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.