freebsd-dev/share/doc/handbook/ports.sgml

<!-- $Id: ports.sgml,v 1.9 1996/05/09 23:04:49 mpp Exp $ -->
<!-- The FreeBSD Documentation Project -->

<sect><heading>The Ports collection<label id="ports"></heading>

<p><em>Contributed by &a.gpalmer; and &a.jkh;.</em>

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


<sect1><heading>What is the FreeBSD Ports Collection?</heading>

<p> When 2.0 was released, the FreeBSD Project decided to attempt to
automate the process of ``porting'' such software to FreeBSD, and the
result is the Ports Collection.  The general idea was that a
combination of various programming tools already available in the base
FreeBSD installation would allow you to simply type `make' for a given
port and have the underlying ports mechanism automatically fetch the
port from a FreeBSD mirror site, apply any special configuration
knowledge to it and then build it to result in a fully working version
of the 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 configure and compile the program under FreeBSD.  This
keeps the entire system down to a manageable size, with the current
system having over 300 ports in the master source tree and yet taking
up less than twenty megabytes.


<sect1><heading>How does the system compile with no source code?</heading>

<p> The Makefile for a port 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''.  Those not found locally are searched for
wherever they are generally provided on the Internet.  If you have a
CDROM distribution of FreeBSD then you already have them available
on your CD for ease of use.  See <ref id="ports:cd"
name="Compiling ports from CD"> if you have such a CDROM
distribution, otherwise skip to <ref id="ports:inet" 
name="Compiling ports using an Internet connection">.

<sect1><heading>Compiling ports from CDROM<label id="ports:cd"></heading>

<p>The ports collection is easy to use from CDROM, and all you need to
do is to create a "link tree" to it using the <tt>lndir(1)</tt> command that
comes with the <em>XFree86</em> distribution.  Find a location with
some free space and create a directory there, and make a symbolic link
from <tt>/usr/ports</tt> to that directory.  Then invoke the <tt>lndir(1)</tt> command with
the full pathname of the ``ports'' directory on the CDROM as an
argument (this might be, for example, something like: <tt>lndir
/cdrom/ports</tt>).  Then you can build ports directly off the CDROM by
building them in the link tree you have created.

Note that there are some ports for which we cannot provide the original
source in the CDROM due to licensing limitations.  In that case,
you will need to look at the next section (<ref id="ports:inet"
name="Compiling ports using an Internet connection">).

<sect1><heading>Compiling ports using an Internet connection<label id="ports:inet"></heading>

<p>    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 assumes you have a permanent network link or do not
mind heavy usage of your telephone.  If you do not 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
by hand.  A good way to see what files a port is going to need is to
cd to that ports' directory and do a <tt>make fetch-list</tt> to see what
it does.  The output of <tt>make fetch-list</tt> can also be used as a
shell script to fetch the ports' tarballs at a well-connected machine.

    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 <tt>/pub/FreeBSD/distfiles</tt>.  Note that the files in
that directory are not guaranteed to be kept up to date - this is a
volunteer project!  We canno make any guarantees about the mirror
sites either - they are obviously under independent control and do not
even have to mirror the distfiles directory.

    If you have a non-permanent link, you can fetch all the distfiles by
going to the top of the tree and typing ``make fetch''.


<sect1><heading>It does not work?!</heading>

<p>Oh. You can do one of four (4) things :
<enum>

<item> Fix it yourself. Technical details can be found in
  <ref id="porting" name="Porting applications">.

<item> 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 do not believe me, check
   the catalogue, especially the line saying "We cannot offer tech-support
   on this product")

   The e-mail address is the &a.ports;.  Please include details of
   the port, where you got both the port source &amp; distfile(s) from, and
   what the error was.

   Note: At time of writing, lang/Sather does not seem to work on Pentium
   machines due to the Intel Curse (aka the Floating Point Division Bug).
   Please do not tell us about this - gripe to Intel instead - it is their
   bug!

<item> Forget it. This is the easiest for most - very few of the programs in
   ports can be classified as `essential'!

<item> 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!  Use the <tt>pkg_add(1)</tt> or <tt>pkg_manage(1)</tt> program to 
   install them to your system.
</enum>

<sect1><heading>I have ported a program and I want to make a port out of it. What now?</heading>

<p>   See the <ref id="porting:starting" name="guidelines"> that
      contain details of the procedure and structure involved.

<sect1><heading>I have got a good port, what now?</heading>

<p>Upload the fixed version to <tt>ftp://freefall.cdrom.com/pub/incoming</tt> or
<tt>ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming</tt> and send e-mail to
the &a.ports 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.


<sect1><heading>I want to leave the compile going overnight, but some ports do not like this.</heading>

<p>   There is a way around this. Before starting the compilation, type:
<verb>
	setenv BATCH yes # (if you use csh/tcsh) or
	BATCH=yes; export BATCH # (for sh/bash)
</verb>
    This should skip ports which need user interaction to build.

    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.


<sect1><heading>The ports collection is weak.  What can I do to help?</heading>

<p>    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.  The most up-to-date copy can be found in:

  <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/share/mk">

    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 the &a.ports if
you would like them to be a part of the default distribution.  Please also
remember that any changes must respect backwards-compatibility 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!


<sect1><heading>This FAQ is weak.  What can I do?</heading>

<p>    Send changes to the &a.ports;.  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! :-)


<sect1><heading>How do I get more information on all the ports?</heading>

<p>    One good method is to cd to the top of the ports tree (say /usr/ports)
and type:
<verb>
	make print-index
</verb>
This will print a summary of all ports in the tree.

<sect1><heading>I have heard of a new checksum system. What is this for?</heading>

<p>    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 original 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
<verb>
	make checksum
</verb>
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 do not recognize the ``checksum''
target. In that case, try the command
<verb>
	make check-md5
</verb>
(``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

   <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/share/mk">

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