The FreeBSD Ports FAQ file Revision: $Id: PORTS.FAQ,v 1.1 1995/01/04 00:43:35 jkh Exp $ The ports system is kinda new, so there haven't been too many FAQ's to date, but hopefully this document will pre-empt (some|most) of them!! The ports system is constantly changing, but hopefully this document will be kept reasonably up to date (and you never know, it might even make sense!). - Gary Palmer & jkh 1) What is a port? Unfortunately, there are more variations of UN*X than most people know of, and hence not all software for UN*X available on the Internet will work on all versions of UN*X (in fact, I can guarantee it!). Hence, some software needs modifications to work under some UN*Xs. The process of making those modifications is known as ``porting'' and the result known as a ``port'' (not to be confused with the sockets on the back of your computer!). 2) What is the FreeBSD Ports Collection? People who (allegedly) know what they are doing have automated the process of ``porting'' software to FreeBSD, and the result is the Ports Collection. The general idea is that a combination of various programming tools available in the base FreeBSD installation will allow you to fetch the port from a FreeBSD mirror site, type ``make'' and get the fully working program. The ports collection itself normally doesn't have any of the original source code necessary for the compilation in the tree, just those shell scripts, Makefiles and source code ``diffs'' that are necessary to compile the program under FreeBSD. This is meant to keep the entire system down to a manageable size, and the current system has over 100 ports in the master source tree, and yet a compressed tar file of that tree is about 2 megabytes (all the source code needed is over 100Mb's!). 3) How does the system compile with no source code? A ports' Makefile automatically looks in a central location on your system (usually /usr/ports/distfiles, though this value can be customized) for the associated set of original distribution files that have been ``ported''. These are generally provided at various places on the Internet, though if you have a CDROM distribution of FreeBSD then you've already got them available on your CD for ease of use. See section 3.1 if you have such a CD distribution, otherwise skip to section 3.2. 3.1 Compiling ports from CD Type something profound here. 3.2 Compiling ports using an Internet connection The ports collection can also use an auto-fetch system to keep your ports collection source tree up to date, updating the central ``distfiles'' version for you the next time you compile the port. Of course, this always assumes you have a permanent network link, or don't mind heavy usage of your telephone. If you don't want heavy network usage when you compile your ports tree, you can pre-fetch the necessary tarballs beforehand and put them into /usr/ports/distfiles (or wherever DISTDIR points) by hand. A good way to see what files a port is going to need is to cd to that port's directory and do a ``make -n fetch'' to see what it does. You can also chose to get the source files either from the master FTP site as defined in the relevant Makefile (in the MASTER_SITES line), or some FreeBSD mirror site also carrying a set of distfiles, as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in the directory /pub/FreeBSD/ports/distfiles. Note that the files in that directory are not guarenteed to be kept up to date - this is a volunteer project! We can't make any guarantees about the mirror sites either - they are obviously under independant control and don't even have to mirror the distfiles directory. If you have a non-permanant link, you can fetch all the distfiles by going to the top of the tree and typing ``make fetch''. 4) It doesn't work?! Oh. You can do one of four (4) things : a) Fix it yourself. Technical details can be found in the GUIDELINES file, available from URL ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES b) Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are in no way responsible for the functionality (or lack thereof) of the FreeBSD system as a whole, and especially the ports system, which is mainly contributed by 3rd parties. (If you don't believe me, check the catalogue, especially the line saying "We cannot offer tech-support on this product") The e-mail address is Ports@FreeBSD.org. Please include details of the port, where you got both the port source & distfile(s) from, and what the error was. Note: At time of writing, lang/Sather doesn't seem to work on Pentium machines due to the Intel Curse (aka the Floating Point Division Bug). Please don't tell us about this - gripe to Intel instead - it's their bug! c) Forget it. This is the easiest for most - very few of the programs in ports can be classed as `essential'! d) Grab the pre-compiled package from a ftp server. The ``master'' package collection is in: ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/ though check your local mirror first, please! These are more likely to work (on the whole) than trying to compile from source, and a lot faster! 5) I've ported a program and I want to make a port out of it. What now? See the file GUIDELINES, in: ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES This contains details of the procedure and structure involved. 6) I've got a good port, what now? Upload the fixed version to freefall.cdrom.com /pub/incoming or ftp.FreeBSD.org /pub/FreeBSD/incoming and send e-mail to ports@FreeBSD.org with the filename and details. Someone on the all-volunteer `ports committee' will (hopefully) look it over and commit it to the ports collection if they like the looks of it. 7) Things go funny during the fetch stage of compilation! We know. Please don't blame us. There is a program called `ncftp' which is used instead of the normal ftp as it can do so-called ``background'' or ``batch'' transfers, ideal for this situation. Unfortunately it can do strange things, and has crashed at least one machine (during circumstances stranger than most, I'll admit, but it was still responsible). Hopefully a future release of ncftp will fix these problems (it is not maintained by the main FreeBSD team, but a third party, who is I believe aware of its shortcomings) 8) I want to leave the compile going overnight, but some ports don't like this. There is a way around this. Before starting the compilation, type: setenv BATCH yes # (if you use csh/tcsh) or BATCH=yes # (for sh/bash) This should miss out ports which need user interaction. Unfortunately, ncftp doesn't know about this trick, and can often screw up and ask stupid questions in unattended batch mode. See (7). To compile those ports left out by doing the above, using a different login shell (or unsetting the above BATCH variable), set the INTERACTIVE variable instead (you can use the same statements as above except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This should now compile only those ports which will definitely ask for user interaction. 9) The ports collection is weak. What can I do to help? First read the bsd.port.mk file (which may be found in /usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of the weirdness can be explained properly in there (most of the current weirdness is due to the lack of assumptions about anything, which is necessary due to the generic nature of these files). Also check that you have an up-to-date copy, as the file can change from minute to minute. A reasonably up-to-date copy can be found in: ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk/bsd.port* If you find that you still need to go in there and alter things, by all means do so, and then send the diffs to ports@FreeBSD.org if you'd like them to be a part of the default distribution. Please also remember that any changes must respect backwards-compatability with any and all older Makefiles, unless you want a real nightmare of /usr/ports munging ahead of you! Large scale changes will generally not be warmly welcomed unless all the existing makefiles work without alteration. Sorry! 10) This FAQ is weak. What can I do? Send changes to ports@FreeBSD.org. Changes are most welcome! This FAQ is also very green and should be considered no more than a `good start' for now. Authors? You can come out of hiding any time now! :-) 11) How do I get more information on all the ports? One good method is to cd to the top of the ports tree (say /usr/ports) and type something like: make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 The ``make describe'' will try to extract the one-line description from each port, and the ``sed'' will delete the extraneous output. ``expand'' just makes it a little more readable (sort of - you may want to season the output of this more to taste).