240 lines
11 KiB
Plaintext
240 lines
11 KiB
Plaintext
<!-- $Id: ports.sgml,v 1.6 1995/07/12 15:01:38 jfieber 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 ten 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're generally provided on the Internet. If you have a
|
|
CDROM distribution of FreeBSD then you've already got 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've created.
|
|
|
|
Note that there are some ports for which we can't provide the original
|
|
source in the CDROM due to licensing limitations. In that case,
|
|
you'll 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 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
|
|
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 can't make any guarantees about the mirror
|
|
sites either - they are obviously under independent control and don't
|
|
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 doesn't 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 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!
|
|
|
|
<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've ported a program and I want to make a port out of it. What now?</heading>
|
|
|
|
<p> See the file GUIDELINES, in:
|
|
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES
|
|
This contains details of the procedure and structure involved.
|
|
|
|
|
|
<sect1><heading>I've 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
|
|
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.
|
|
|
|
|
|
<sect1><heading>I want to leave the compile going overnight, but some ports don't 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 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-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 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! :-)
|
|
|
|
|
|
<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've 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 don't 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.
|