freebsd-dev/share/FAQ/Text/ports.FAQ

			The FreeBSD Ports FAQ file

Revision: $Id: ports.FAQ,v 1.2 1995/01/06 19:24:13 gpalmer 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).


12) I've heard of a new checksum system. What is this for?

    For various reasons, when using FTP over the Internet to obtain the
source code, you may not always end up with the same copy of the code
that the origional porter worked from, and this can lead to problems.
So a simple checksumming system has been employed to try and highlight
problems in this area.

    To check the entire system, go to the top of the ports tree
(defaults to /usr/ports) and type

	make checksum

This will give a report on the validity of the files you have FTP'd. If some
are missing, the system will attempt to retrieve them before running the
checksum routine. The same technique can be applied to a single port.

    The system will complain if there is no pre-computed checksum available
for that port. Not all ports currently have checksums, but this should be
cured soon.

    Some older versions of the system don't recognise the ``checksum''
target. In that case, try the command

	make check-md5

(``check-md5'' was the pre-cursor to the ``checksum'' target). If neither
work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from

   ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk/bsd.port*

and install them in /usr/share/mk. This will get you the latest version
of the ports system.