From c5314b3dfb72450b420c0039d887c961f6731329 Mon Sep 17 00:00:00 2001 From: jkh Date: Wed, 4 Jan 1995 00:43:35 +0000 Subject: [PATCH] The ports collection FAQ. Submitted by: gpalmer & jkh --- share/FAQ/PORTS.FAQ | 198 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 share/FAQ/PORTS.FAQ diff --git a/share/FAQ/PORTS.FAQ b/share/FAQ/PORTS.FAQ new file mode 100644 index 000000000000..81e21c13f9c6 --- /dev/null +++ b/share/FAQ/PORTS.FAQ @@ -0,0 +1,198 @@ + The FreeBSD Ports FAQ file + +Revision: $Id$ + +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! :-)