Convert PORTS.FAQ to ports.FAQ.

All "FAQ" items should be lowercase prefix and upcase FAQ suffix.

1 files changed, 211 insertions, 0 deletions

diff --git a/share/FAQ/ports.FAQ b/share/FAQ/ports.FAQ
new file mode 100644
index 0000000..f889954
--- /dev/null
+++ b/share/FAQ/ports.FAQ
@@ -0,0 +1,211 @@
+			The FreeBSD Ports FAQ file
+
+Revision: $Id: PORTS.FAQ,v 1.2 1995/01/04 07:38:40 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).