path: root/en_US.ISO8859-1/books/porters-handbook/book.sgml

    <chapter id="ports">
      <title>Installing Applications: The Ports collection</title>
      
      <para><emphasis>Contributed by &a.jraynard;.</emphasis></para>
      
      <para>The FreeBSD Ports collection allows you to compile and install a
	very wide range of applications with a minimum of effort.</para>
      
      <para>For all the hype about open standards, getting a program to work
	on different versions of Unix in the real world can be a tedious and
	tricky business, as anyone who has tried it will know. You may be
	lucky enough to find that the program you want will compile cleanly on
	your system, install itself in all the right places and run flawlessly
	&ldquo;out of the box&rdquo;, but this is unfortunately rather rare. With most
	programs, you will find yourself doing a fair bit of head-scratching,
	and there are quite a few programs that will result in premature
	greying, or even chronic alopecia...</para>
      
      <para>Some software distributions have attacked this problem by
	providing configuration scripts. Some of these are very clever, but
	they have an unfortunate tendency to triumphantly announce that your
	system is something you have never heard of and then ask you lots of
	questions that sound like a final exam in system-level Unix
	programming (<literal>Does your system's gethitlist function return a const
	pointer to a fromboz or a pointer to a const fromboz? Do you have
	Foonix style unacceptable exception handling? And if not, why
	not?</literal>).</para>
      
      <para>Fortunately, with the Ports collection, all the hard work
	involved has already been done, and you can just type <command>make install</command>
	and get a working program.</para>
      
      
      <sect1>
	<title>Why Have a Ports Collection?</title>
	
	<para>The base FreeBSD system comes with a very wide range of tools
	  and system utilities, but a lot of popular programs are not in the
	  base system, for good reasons:-</para>
	
	
	  <orderedlist>
	    
	    <listitem>
	      <para>Programs that some people cannot live without and other
		people cannot stand, such as a certain Lisp-based editor.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Programs which are too specialised to put in the base
		system (CAD, databases).</para>
	    </listitem>
	    
	    <listitem>
	      <para>Programs which fall into the &ldquo;I must have a look at that
		when I get a spare minute&rdquo; category, rather than
		system-critical ones (some languages, perhaps).</para>
	    </listitem>
	    
	    <listitem>
	      <para>Programs that are far too much fun to be supplied with a
		serious operating system like FreeBSD ;-)</para>
	    </listitem>
	    
	    <listitem>
	      <para>However many programs you put in the base system, people
		will always want more, and a line has to be drawn somewhere
		(otherwise FreeBSD distributions would become absolutely
		enormous).</para>
	    </listitem>
	    
	  </orderedlist>
	
	
	<para>Obviously it would be unreasonable to expect everyone to port
	  their favourite programs by hand (not to mention a tremendous amount
	  of duplicated work), so the FreeBSD Project came up with an
	  ingenious way of using standard tools that would automate the
	  process.</para>
	
	<para>Incidentally, this is an excellent illustration of how &ldquo;the
	  Unix way&rdquo; works in practice by combining a set of simple but very
	  flexible tools into something very powerful.</para>
	
      </sect1>
      
      <sect1>
	<title>How Does the Ports Collection Work?</title>
	
	<para>Programs are typically distributed on the Internet as a 
	  <xref linkend="ports-tarball" remap="tarball"> consisting of a
	  Makefile and the source code for the program and usually some
	  instructions (which are unfortunately not always as instructive as
	  they could be), with perhaps a configuration script.</para>
	
	<para>The standard scenario is that you FTP down the tarball, extract
	  it  somewhere, glance through the instructions, make any changes
	  that seem  necessary, run the configure script to set things up and
	  use the standard  <command>make</command> program to compile and install the program
	  from the source.</para>
	
	<para>FreeBSD ports still use the tarball mechanism, but use a 
	  <xref linkend="ports-skeleton" remap="skeleton"> to hold the
	  &quot;knowledge&quot; of how to get the program working on FreeBSD,
	  rather than expecting the user to be able to work it out. They also
	  supply their own customised
	  <xref linkend="ports-makefile" remap="Makefile">, so that almost
	  every port can be built in the same way.</para>
	
	<para>If you look at a port skeleton (either on <ulink
	    URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
	    system</ulink> or <ulink
	    URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
	    linkend="ports-getting" remap="Getting a port">).</para>
	
	<para>&ldquo;How on earth can this do anything?&rdquo; I hear you cry. &ldquo;There
	  is no source code there!&rdquo;</para>
	
	<para>Fear not, gentle reader, all will become clear (hopefully).
	  Let's see what happens if we try and install a port. I have chosen
	  <application>ElectricFence</application>, a useful tool for developers, as the skeleton is
	  more straightforward than most.</para>
	
	<note>
	  <para>If you are trying this at home, you
	  will need to be root.</para>
	</note>
	
	<informalexample>
	  <screen>&prompt.root; <userinput>cd /usr/ports/devel/ElectricFence</userinput>
&prompt.root; <userinput>make install</userinput>
&gt;&gt; Checksum OK for ElectricFence-2.0.5.tar.gz.
===&gt;  Extracting for ElectricFence-2.0.5
===&gt;  Patching for ElectricFence-2.0.5
===&gt;  Applying FreeBSD patches for ElectricFence-2.0.5
===&gt;  Configuring for ElectricFence-2.0.5
===&gt;  Building for ElectricFence-2.0.5
[lots of compiler output...]
===&gt;  Installing for ElectricFence-2.0.5
===&gt;  Warning: your umask is "0002". If this is not desired, set it to
      an appropriate value and install this port again by ``make reinstall''.
install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.a /usr/local/lib
install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.3 /usr/local/man/man3
===&gt;  Compressing manual pages for ElectricFence-2.0.5
===&gt;  Registering installation for ElectricFence-2.0.5</screen>
	</informalexample>
	
	<para>To avoid confusing the issue, I have completely removed the
	  build output.</para>
	
	<para>If you tried this yourself, you may well have got something like
	  this at the start:-</para>
	
	
	  <informalexample id="ports-fetch">
	    <screen>&prompt.root; <userinput>make install</userinput>
&gt;&gt; ElectricFence-2.0.5.tar.gz doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from ftp://ftp.doc.ic.ac.uk/Mirrors/sunsite.unc.edu/pub/Linux/devel/lang/c/.</screen>
	  </informalexample>
	
	
	<para>The <command>make</command> program has noticed that you did not have a local
	  copy of the source code and tried to FTP it down so it could get the
	  job done. I already had the source handy in my example, so it did
	  not need to fetch it.</para>
	
	<para>Let's go through this and see what the <command>make</command> program was
	  doing.</para>
	
	
	  <procedure>
	    
	    <step>
	      <para>Locate the source code <xref linkend="ports-tarball"
		  remap="tarball."> If it is not available locally, try to
		grab it from an FTP site.</para>
	    </step>
	    
	    <step>
	      <para>Run a <xref linkend="ports-checksum" remap="checksum">
		test on the tarball to make sure it has not been tampered
		with, accidentally truncated, downloaded in ASCII mode, struck
		by neutrinos while in transit, etc.</para>
	    </step>
	    
	    <step>
	      <para>Extract the tarball into a temporary work directory.</para>
	    </step>
	    
	    <step>
	      <para>Apply any <xref linkend="ports-patch" remap="patches">
		needed to get the source to compile and run under FreeBSD.</para>
	    </step>
	    
	    <step>
	      <para>Run any configuration script required by the build
		process and correctly answer any questions it asks.</para>
	    </step>
	    
	    <step>
	      <para>(Finally!) Compile the code.</para>
	    </step>
	    
	    <step>
	      <para>Install the program executable and other supporting
		files, man pages, etc. under the
		<filename>/usr/local</filename> hierarchy, where they will not
		get mixed up with system programs. This also makes sure that
		all the ports you install will go in the same place, instead
		of being flung all over your system.</para>
	    </step>
	    
	    <step>
	      <para>Register the installation in a database. This means that,
		if you do not like the program, you can cleanly <xref
		  linkend="ports-remove" remap="remove"> all traces of it from
		your system.</para>
	    </step>
	    
	  </procedure>
	
	
	<para>Scroll up to the <command>make</command> output and see if you can match these
	  steps to it. And if you were not impressed before, you should be by
	  now!</para>
	
      </sect1>
      
      <sect1 id="ports-getting">
	<title>Getting a FreeBSD Port</title>
	
	<para>There are two ways of getting hold of the FreeBSD port for a
	  program. One requires a <xref linkend="ports-cd" remap="FreeBSD
	    CDROM">, the other involves using an <xref linkend="ports-inet"
	    remap="Internet Connection."></para>
	
	
	<sect2 id="ports-cd">
	  <title>Compiling ports from CDROM</title>
	  
	  <para>If you answered yes to the question &ldquo;Do you want to link the
	    ports  collection to your CDROM&rdquo; during the FreeBSD installation,
	    the initial setting up will already have been done for you.</para>
	  
	  <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
	    the drive and mounted on, say, <filename>/cdrom</filename>. Then
	    do</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
	  </informalexample>
	  
	  <para>to enable the ports make mechanism to find the tarballs (it
	    expects to find them in <filename>/usr/ports/distfiles</filename>,
	    which is why we sym-linked the CDROM's tarball directory to that
	    directory).</para>
	  
	  <para>Now, suppose you want to install the gnats program from the
	    databases directory. Here is how to do it:-</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>mkdir databases</userinput>
&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
&prompt.root; <userinput>cd databases/gnats</userinput>
&prompt.root; <userinput>make install</userinput></screen>
	  </informalexample>
	  
	  <para>Or if you are a serious database user and you want to compare
	    all the ones available in the Ports collection, do</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
&prompt.root; <userinput>cd databases</userinput>
&prompt.root; <userinput>make install</userinput></screen>
	  </informalexample>
	  
	  <para>(yes, that really is a dot on its own after the <command>cp</command> command and
	    not a mistake. It is Unix-ese for &ldquo;the current
	    directory&rdquo;) and the ports make mechanism will automatically compile and
	    install all the ports in the databases directory for you!</para>
	  
	  <para>If you do not like this method, here is a completely different
	    way of doing it:-</para>
	  
	  <para>Create a &ldquo;link tree&rdquo; to it using the
	    <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
	    <emphasis>XFree86</emphasis> distribution. Find a location with
	    some free space, create a directory there and then cd to it. Then
	    invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
	    pathname of the <filename>ports</filename> directory on the CDROM as the first
	    argument and . (the current directory) as the second. This might
	    be, for example, something like:</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
	    </informalexample>
	  
	  <para>Then you can build ports directly off the CDROM by building
	    them in the link tree you have created.</para>
	  
	  <para>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 section on <xref
	      linkend="ports-inet"
	      remap="Compiling ports using an Internet connection."></para>
	  
	</sect2>
	
	<sect2 id="ports-inet">
	  <title>Compiling ports from the Internet</title>
	  
	  <para>If you do not have a CDROM, or you want to make sure you get
	    the very latest version of the port you want, you will need to
	    download the
	    <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
	    this  might sound like rather a fiddly job full of pitfalls, but
	    it is actually very easy.</para>
	  
	  <para>The key to it is that the FreeBSD FTP server can create
	    on-the-fly
	    <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
	    how it works, with the gnats program in the databases directory as
	    an example (the bits in square brackets are comments. Do not type
	    them in if you are trying this yourself!):-</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>mkdir databases</userinput>
&prompt.root; <userinput>cd databases</userinput>
&prompt.root; <userinput>ftp ftp.freebsd.org</userinput>
[log in as `ftp' and give your email address when asked for a
password. Remember to use binary (also known as image) mode!]
<prompt>&gt;</prompt> <userinput>cd /pub/FreeBSD/ports/databases</userinput>
<prompt>&gt;</prompt> <userinput>get gnats.tar</userinput>
[tars up the gnats skeleton for us]
<prompt>&gt;</prompt> <userinput>quit</userinput>
&prompt.root; <userinput>tar xf gnats.tar</userinput>
[extract the gnats skeleton]
&prompt.root; <userinput>cd gnats</userinput>
&prompt.root; <userinput>make install</userinput>
[build and install gnats]</screen>
	  </informalexample>
	  
	  <para>What happened here? We connected to the FTP server in the
	    usual way and went to its <filename>databases</filename> sub-directory. When we gave it
	    the command <command>get gnats.tar</command>, the FTP server <xref
	      linkend="ports-tarball"
	      remap="tarred"> up the gnats directory for us.</para>
	  
	  <para>We then extracted the gnats skeleton and went into the gnats
	    directory to build the port. As we explained <xref
	      linkend="ports-fetch"
	      remap="earlier">, the make process noticed we did not have a
	    copy of the source locally, so it fetched one before extracting,
	    patching and building it.</para>
	  
	  <para>Let's try something more ambitious now. Instead of getting a
	    single port skeleton, let's get a whole sub-directory, for example
	    all the database skeletons in the ports collection. It looks
	    almost the same:-</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>ftp ftp.freebsd.org</userinput>
[log in as `ftp' and give your email address when asked for a
password. Remember to use binary (also known as image) mode!]
<prompt>&gt;</prompt> <userinput>cd /pub/FreeBSD/ports</userinput>
<prompt>&gt;</prompt> <userinput>get databases.tar</userinput>
[tars up the databases directory for us]
<prompt>&gt;</prompt> <userinput>quit</userinput>
&prompt.root; <userinput>tar xf databases.tar</userinput>
[extract all the database skeletons]
&prompt.root; <userinput>cd databases</userinput>
&prompt.root; <userinput>make install</userinput>
[build and install all the database ports]</screen>
	  </informalexample>
	  
	  <para>With half a dozen straightforward commands, we have now got a
	    set of database programs on our FreeBSD machine! All we did that
	    was different from getting a single port skeleton and building it
	    was that we got a whole directory at once, and compiled everything
	    in it at once. Pretty impressive, no?</para>
	  
	  <para>If you expect to be installing many ports, it is probably
	    worth downloading all the ports directories.</para>
	  
	</sect2>
      </sect1>
      
      <sect1 id="ports-skeleton">
	<title>Skeletons</title>
	
	<para>A team of compulsive hackers who have forgotten to eat in a
	  frantic attempt to make a deadline? Something unpleasant lurking in
	  the FreeBSD  attic? No, a skeleton here is a minimal framework that
	  supplies everything needed to make the ports magic work.</para>
	
	
	<sect2 id="ports-makefile">
	  <title><filename>Makefile</filename></title>
	  
	  <para>The most important component of a skeleton is the Makefile.
	    This contains various statements that specify how the port should
	    be compiled and installed. Here is the Makefile for
	    ElectricFence:-</para>
	  
	  <programlisting>
# New ports collection makefile for:  Electric Fence
# Version required:	2.0.5
# Date created: 	13 November 1997
# Whom:			jraynard
#
# &#36;Id&#36;
#

DISTNAME=       ElectricFence-2.0.5
CATEGORIES=     devel
MASTER_SITES=   ${MASTER_SITE_SUNSITE}
MASTER_SITE_SUBDIR=	devel/lang/c

MAINTAINER=	jraynard@freebsd.org

MAN3=           libefence.3

do-install:
        ${INSTALL_DATA} ${WRKSRC}/libefence.a ${PREFIX}/lib
        ${INSTALL_MAN} ${WRKSRC}/libefence.3 ${PREFIX}/man/man3

.include &lt;bsd.port.mk&gt;</programlisting>
	  
	  <para>The lines beginning with a &quot;#&quot; sign are comments for
	    the benefit of human readers (as in most Unix script
	    files).</para>
	  
	  <para><literal>DISTNAME</literal> specifies the name of the <xref
	      linkend="ports-tarball" remap="tarball">, but without the
	    extension.</para>
	  
	  <para><literal>CATEGORIES</literal> states what kind of program this is. In
	    this case, a utility for developers.</para>
	  
	  <para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
	    which is used to retrieve the <xref linkend="ports-tarball"
	      remap="tarball"> if it is not available on the local system.
	    This is a site which is regarded as reputable, and is normally the
	    one from which the program is officially  distributed (in so far
	    as any software is &quot;officially&quot; distributed on the
	    Internet).</para>
	  
	  <para><literal>MAINTAINER</literal> is the email address of the person who is
	    responsible for updating the skeleton if, for example a new
	    version of the program comes out.</para>
	  
	  <para>Skipping over the next few lines for a minute, the line
	    <literal>.include &lt;bsd.port.mk&gt;</literal> says
	    that the other statements and commands  needed for this port are
	    in a standard file called <filename>bsd.port.mk</filename>. As
	    these are the same for all ports, there is no point in duplicating
	    them all over the place, so they are kept in a single standard
	    file.</para>
	  
	  <para>This is probably not the place to go into a detailed
	    examination of how Makefiles work; suffice it to say that the line
	    starting with <literal>MAN3</literal> ensures that the ElectricFence man page is
	    compressed after installation, to help conserve your precious disk
	    space. The original port did not provide an <maketarget>install</maketarget> target,
	    so the three lines from <maketarget>do-install</maketarget> ensure that the files
	    produced by this port are placed in the correct
	    destination.</para>
	  
	</sect2>
	
	<sect2>
	  <title>The <filename>files</filename> directory</title>
	  
	  <para>The file containing the <xref linkend="ports-checksum"
	      remap="checksum"> for the port is called
	    <filename>md5</filename>, after the MD5 algorithm used for ports
	    checksums. It lives in a directory with the slightly confusing
	    name of <filename>files</filename>.</para>
	  
	  <para>This directory can also contain other miscellaneous files that
	    are required by the port and do not belong anywhere else.</para>
	  
	</sect2>
	
	<sect2>
	  <title>The <filename>patches</filename> directory</title>
	  
	  <para>This directory contains the <xref linkend="ports-patch"
	      remap="patches"> needed to make everything work properly under
	    FreeBSD.</para>
	  
	</sect2>
	
	<sect2>
	  <title>The <filename>pkg</filename> directory</title>
	  
	  <para>This program contains three quite useful files:-</para>
	  
	  
	    <itemizedlist>
	      
	      <listitem>
		<para><filename>COMMENT</filename> &mdash; a one-line description of
		  the program.</para>
	      </listitem>
	      
	      <listitem>
		<para><filename>DESCR</filename> &mdash; a more detailed description.</para>
	      </listitem>
	      
	      <listitem>
		<para><filename>PLIST</filename> &mdash; a list of all the files
		  that will be created when the program is installed.</para>
	      </listitem>
	      
	    </itemizedlist>
	  
	  
	</sect2>
      </sect1>
      
      <sect1 id="ports-troubleshooting">
	<title>What to do when a port does not work.</title>
	
	<para>Oh. You can do one of four (4) things :</para>
	
	
	  <orderedlist>
	    
	    <listitem>
	      <para>Fix it yourself. Technical details on how ports work can
		be found in
		<xref linkend="porting" remap="Porting applications."></para>
	    </listitem>
	    
	    <listitem>
	      <para>Gripe. This is done by e-mail <emphasis>only</emphasis>! Send such e-mail to
		the &a.ports; and please include the name/version of the port,
		where you got both the port source &amp; distfile(s) from, and
		what the text of the error was.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Forget it. This is the easiest for most &mdash; very few of the
		programs in ports can be classified as essential!</para>
	    </listitem>
	    
	    <listitem>
	      <para>Grab the pre-compiled package from a ftp server. The
		&ldquo;master&rdquo; package collection is on FreeBSD's FTP server in
		the <ulink
		  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/">packages
		  directory</ulink>, 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 besides! Use
		the <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry>  program to install a
		package file on your system.</para>
	    </listitem>
	    
	  </orderedlist>
	
	
      </sect1>
      
      <sect1>
	<title>I Want to Make a Port!</title>
	
	<para>Great! Please see the <xref linkend="porting"
	    remap="guidelines"> for detailed instructions on how to do
	  this.</para>
	
      </sect1>
      
      <sect1>
	<title>Some Questions and Answers</title>
	
	
	  <itemizedlist>
	    
	    <listitem>
	      <para>Q. I thought this was going to be a discussion about
		modems??!</para>
	      
	      <para>A. Ah. You must be thinking of the serial ports on the
		back of your computer. We are using &ldquo;port&rdquo; here to mean the
		result of &ldquo;porting&rdquo; a program from one version of Unix to
		another. (It is an unfortunate bad habit of computer people to
		use the same word to refer to several completely different
		things).</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I thought you were supposed to use packages to install
		extra programs?</para>
	      
	      <para>A. Yes, that is usually the quickest and easiest way of
		doing it.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. So why bother with ports then?</para>
	      
	      <para>A. Several reasons:-</para>
	      
	      
		<orderedlist>
		  
		  <listitem>
		    <para>The licensing conditions on some software
		      distributions require that they be distributed as source
		      code, not binaries.</para>
		  </listitem>
		  
		  <listitem>
		    <para>Some people do not trust binary distributions. At
		      least with source code you can (in theory) read through
		      it and look for potential problems yourself.</para>
		  </listitem>
		  
		  <listitem>
		    <para>If you have some local patches, you will need the
		      source to add them yourself.</para>
		  </listitem>
		  
		  <listitem>
		    <para>You might have opinions on how a program should be
		      compiled that differ from the person who did the package
		      &mdash; some people have strong views on what optimisation
		      setting should be used, whether to build debug versions
		      and then strip them or not, etc. etc.</para>
		  </listitem>
		  
		  <listitem>
		    <para>Some people like having code around, so they can
		      read it if they get bored, hack around with it, borrow
		      from it (licence terms permitting, of course!) and so
		      on.</para>
		  </listitem>
		  
		  <listitem>
		    <para>If you ain't got the source, it ain't software!
		      <!-- smiley -->;-)</para>
		  </listitem>
		  
		</orderedlist>
	      
	    </listitem>
	    
	    <listitem>
	      <para><anchor id="ports-patch"> Q. What is a patch?</para>
	      
	      <para>A. A patch is a small (usually) file that specifies how to
		go from one version of a file to another. It contains text
		that says, in effect, things like &ldquo;delete line 23&rdquo;, &ldquo;add
		these two lines after line 468&rdquo; or &ldquo;change line 197 to
		  this&rdquo;. Also known as a &ldquo;diff&rdquo;, since it is generated by a
		program of that name.</para>
	    </listitem>
	    
	    <listitem>
	      <para><anchor id="ports-tarball"> Q. What is all this about
		tarballs?</para>
	      
	      <para>A. It is a file ending in <filename>.tar</filename> or
		<filename>.tar.gz</filename> (with variations like
		<filename>.tar.Z</filename>, or even <filename>.tgz</filename>
		if you are trying to squeeze the names into a DOS
		filesystem).</para>
	      
	      <para>Basically, it is a directory tree that has been archived
		into a single file (<filename>.tar</filename>) and optionally
		compressed (<filename>.gz</filename>). This technique was
		originally used for <emphasis>T</emphasis>ape
		<emphasis>AR</emphasis>chives (hence the name <command>tar</command>), but it is
		a widely used way of distributing program source code around
		the Internet.</para>
	      
	      <para>You can see what files are in them, or even extract them
		yourself, by using the standard Unix tar program, which comes
		with the base FreeBSD system, like this:-</para>
	      
	      <informalexample>
		<screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput>		
&prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput>
&prompt.user; <userinput>tar tvf foobar.tar</userinput>
&prompt.user; <userinput>tar xvf foobar.tar</userinput>
		</screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para><anchor id="ports-checksum"> Q. And a checksum?</para>
	      
	      <para>A. It is a number generated by adding up all the data in
		the file you want to check. If any of the characters change,
		the checksum will no longer be equal to the total, so a simple
		comparison will allow you to spot the difference. (In
		practice, it is done in a more complicated way to spot
		problems like position-swapping, which will not show up with a
		simplistic addition).</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I did what you said for <xref linkend="ports-cd"
		  remap="compiling ports from a CDROM"> and it worked great
		until I tried to install the kermit port:-</para>

		<informalexample>
		  <screen>&prompt.root; <userinput>make install</userinput>
&gt;&gt; cku190.tar.gz doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen>
		</informalexample>
		<para>Why can it not be found? Have I got a dud CDROM?</para>
	      
	      <para>A. The licensing terms for kermit do not allow us to put
		the tarball for it on the CDROM, so you will have to fetch it
		by hand &mdash; sorry! The reason why you got all those error
		messages was because you were not connected to the Internet at
		the time. Once you have downloaded it from any of the sites
		above, you can re-start the process (try and choose the
		nearest site to you, though, to save your time and the
		Internet's bandwidth).</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I did that, but when I tried to put it into
		<filename>/usr/ports/distfiles</filename> I got some error
		about not having permission.</para>
	      
	      <para>A. The ports mechanism looks for the tarball in
		<filename>/usr/ports/distfiles</filename>, but you will not be
		able to copy anything there because it is sym-linked to the
		CDROM, which is read-only. You can tell it to look somewhere
		else by doing</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>make  DISTDIR=/where/you/put/it install</userinput></screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>Q. Does the ports scheme only work if you have everything
		in <filename>/usr/ports</filename>? My system administrator
		says I must put everything under
		<filename>/u/people/guests/wurzburger</filename>, but it does
		not seem to work.</para>
	      
	      <para>A. You can use the <makevar>PORTSDIR</makevar> and <makevar>PREFIX</makevar> variables to tell
		the ports mechanism to use different directories. For
		instance,</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen>
	      </informalexample>
	      
	      <para>will compile the port in
		<filename>/u/people/guests/wurzburger/ports</filename> and
		install everything under <filename>/usr/local</filename>.</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen>
	      </informalexample>
	      
	      <para>will compile it in <filename>/usr/ports</filename> and
		install it in
		<filename>/u/people/guests/wurzburger/local</filename>.</para>
	      
	      <para>And of course</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>make PORTSDIR=.../ports PREFIX=.../local install</userinput></screen>
	      </informalexample>
	      
	      <para>will combine the two (it is too long to fit on the page if
		I write it in full, but I am sure you get the idea).</para>
	      
	      <para>If you do not fancy typing all that in every time you
		install a port (and to be honest, who would?), it is a good
		idea to put these variables into your environment.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I do not have a FreeBSD CDROM, but I would like to have
		all the tarballs handy on my system so I do not have to wait
		for a download every time I install a port. Is there an easy
		way to get them all at once?</para>
	      
	      <para>A. To get every single tarball for the ports collection,
		do</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make fetch</userinput></screen>
	      </informalexample>
	      
	      <para>For all the tarballs for a single ports directory,
		do</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>cd /usr/ports/directory</userinput>
&prompt.root; <userinput>make fetch</userinput></screen>
	      </informalexample>
	      
	      <para>and for just one port &mdash; well, I think you have guessed
		already.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I know it is probably faster to fetch the tarballs from
		one of the FreeBSD mirror sites close by. Is there any way to
		tell the port to fetch them from servers other than ones
		listed in the MASTER_SITES?</para>
	      
	      <para>A. Yes. If you know, for example, <hostid role="fqdn">ftp.FreeBSD.ORG</hostid> is much
		closer than sites listed in <makevar>MASTER_SITES</makevar>, do as following
		example.</para>

		<informalexample>
		  <screen>&prompt.root; <userinput>cd /usr/ports/directory</userinput>
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE=ftp://ftp.FreeBSD.ORG/pub/FreeBSD/distfiles/ fetch</userinput></screen>
		</informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I want to know what files make is going to need before
		it tries to pull them down.</para>
	      
	      <para>A. <command>make fetch-list</command> will display a list of the files
		needed for a port.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. Is there any way to stop the port from compiling? I
		want to do some hacking on the source before I install it, but
		it is a bit tiresome having  to watch it and hit control-C
		every time.</para>
	      
	      <para>A. Doing <command>make extract</command> will stop it after it has fetched
		and extracted the source code.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I am trying to make my own port and I want to be able
		to stop it compiling until I have had a chance to see if my
		patches worked properly. Is there something like <command>make
		extract</command>, but for patches?</para>
	      
	      <para>A. Yep, <command>make patch</command> is what you want. You will probably
		find the <makevar>PATCH_DEBUG</makevar> option useful as well. And by the way,
		thank you for your efforts!</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I have heard that some compiler options can cause bugs.
		Is this true? How can I make sure that I compile ports with
		the right settings?</para>
	      
	      <para>A. Yes, with version 2.6.3 of <command>gcc</command> (the version shipped
		with FreeBSD 2.1.0 and 2.1.5), the <option>-O2</option> option could result in
		buggy code unless you used the <option>-fno-strength-reduce</option> option as
		well. (Most of the ports don't use <option>-O2</option>). You
		<emphasis>should</emphasis> be able to specify the compiler
		options used by something like</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>
	      </informalexample>
	      
	      <para>or by editing <filename>/etc/make.conf</filename>, but
		unfortunately not all ports respect this. The surest way is to
		do <command>make configure</command>, then go into the source directory and
		inspect the Makefiles by hand, but this can get tedious if the
		source has lots of sub-directories, each with their own
		Makefiles.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. There are so many ports it is hard to find the one I
		want. Is there a list anywhere of what ports are available?</para>
	      
	      <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I went to install the <literal>foo</literal> port but the system
		suddenly stopped compiling it and starting compiling the
		<literal>bar</literal>
		port. What's going on?</para>
	      
	      <para>A. The <literal>foo</literal> port needs something that is supplied with
		<literal>bar</literal> &mdash; for instance, if <literal>foo</literal> uses graphics, <literal>bar</literal> might have
		a library with useful graphics processing routines. Or <literal>bar</literal>
		might be a tool that is needed to compile the <literal>foo</literal>
		port.</para>
	    </listitem>
	    
	    <listitem>
	      <para><anchor id="ports-remove">  Q. I installed the <literal>grizzle</literal>
		program from the ports and frankly it is a complete waste of
		disk space. I want to delete it but I do not know where it put
		all the files. Any clues?</para>
	      
	      <para>A. No problem, just do</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>
		Q. Hang on a minute, you have to know the version number to
		use that command. You do not seriously expect me to remember
		that, do you??</para>
	      
	      <para>A. Not at all, you can find it out by doing</para>
	      
	      <informalexample>
		<screen>&prompt.root; <userinput>pkg_info -a | grep grizzle</userinput>
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game.</screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>Q. Talking of disk space, the ports directory seems to be
		taking up an awful lot of room. Is it safe to go in there and
		delete things?</para>
	      
	      <para>A. Yes, if you have installed the program and are fairly
		certain you will not need the source again, there is no point
		in keeping it hanging around. The best way to do this
		is</para>
	      
	      <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make clean</userinput></screen>
	      </informalexample>
	      
	      <para>which will go through all the ports subdirectories and
		delete everything except the skeletons for each port.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I tried that and it still left all those tarballs or
		whatever you called them in the <filename>distfiles</filename>
		directory. Can I delete those as well?</para>
	      
	      <para>A. Yes, if you are sure you have finished with them, those
		can go as well.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I like having lots and lots of programs to play with.
		Is there any way of installing all the ports in one go?</para>
	      
	      <para>A. Just do</para>
	      
	      <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make install</userinput></screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>Q. OK, I tried that, but I thought it would take a very
		long time so I went to bed and left it to get on with it. When
		I looked at the computer this morning, it had only done three
		and a half ports. Did something go wrong?</para>
	      
	      <para>A. No, the problem is that some of the ports need to ask
		you questions that we cannot answer for you (eg &ldquo;Do you want
		to print on A4 or US letter sized paper?&rdquo;) and they need to
		have someone on hand to answer them.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. I really do not want to spend all day staring at the
		monitor. Any better ideas?</para>
	      
	      <para>A. OK, do this before you go to bed/work/the local
		park:-</para>
	      
	      <informalexample>
	    <screen>&prompt.root <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make -DBATCH install</userinput></screen>
	      </informalexample>
	      
	      <para>This will install every port that does
		<emphasis>not</emphasis> require user input. Then, when you
		come back, do</para>
	      
	      <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make -DIS_INTERACTIVE install</userinput></screen>
	      </informalexample>
	      
	      <para>to finish the job.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Q. At work, we are using <literal>frobble</literal>, which is in your ports
		collection, but we have altered it quite a bit to get it to do
		what we need. Is there any way of making our own packages, so
		we can distribute it more easily around our sites?</para>
	      
	      <para>A. No problem, assuming you know how to make patches for
		your changes:-</para>
	      
	      <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/ports/somewhere/frobble</userinput>
&prompt.root; <userinput>make extract</userinput>
&prompt.root; <userinput>cd work/frobble-2.8</userinput>
[Apply your patches]
&prompt.root; <userinput>cd ../..</userinput>
&prompt.root; <userinput>make package</userinput></screen>
	      </informalexample>
	    </listitem>
	    
	    <listitem>
	      <para>Q. This ports stuff is really clever. I am desperate to
		find out how you did it. What is the secret?</para>
	      
	      <para>A. Nothing secret about it at all, just look at the
		<filename>bsd.ports.mk</filename> and
		<filename>bsd.ports.subdir.mk</filename> files in your <ulink
		  URL="file://localhost/usr/share/mk/">makefiles
		  directory.</ulink></para>

	      <note>
		<para>Readers with an aversion to intricate shell-scripts are
		  advised not to follow this link...)</para>
	      </note>
	    </listitem>
	    
	  </itemizedlist>
	  
	
	
      </sect1>
    </chapter>


<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil 
     sgml-shorttag: nil 
     sgml-always-quote-attributes: t 
     sgml-minimize-attributes: max
     sgml-parent-document: ("../handbook.sgml" "part" "chapter")
     End: 
-->