os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Finally:

Browse source 
Remove the mini-FAQ.  All the usefull bits have been merged into the
main content.

Fix a screen tag in another part of the chapter.
This commit is contained in:
Tom Rhodes 2003-05-20 20:12:48 +00:00
parent 39adab85e5
commit d0f50c8b42
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=17000
1 changed files with 4 additions and 548 deletions
Download patch file Download diff file Expand all files Collapse all files

552
en_US.ISO8859-1/books/handbook/ports/chapter.sgml
View file

@ -905,8 +905,8 @@ Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
where files are downloaded from). You can override the
<makevar>MASTER_SITES</makevar> option with the following command:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
<para>In this example we change the <makevar>MASTER_SITES</makevar> option to
@ -1111,551 +1111,8 @@ Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
</itemizedlist>
</sect1>
<sect1 id="ports-trouble">
<title>Troubleshooting</title>
<para>The following sections cover some of the more frequently asked
questions about the ports collection and some basic troubleshooting
techniques, and what do to if a <link
linkend="ports-broken">port is broken</link>.</para>
<sect2 id="ports-questions">
<title>Some Questions and Answers</title>
<qandaset>
<qandaentry>
<question>
<para>I thought this was going to be a discussion about
modems??!</para>
</question>
<answer>
<para>Ah, you must be thinking of the serial ports on the back
of your computer. We are using <quote>port</quote> here to
mean the result of <quote>porting</quote> a program from one
operating system to another.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para id="ports-patch">What is a patch?</para>
</question>
<answer>
<para>A patch is a small file that specifies how to go from
one version of a file to another. It contains plain text,
and basically says things like <quote>delete line 23</quote>,
<quote>add these two lines after line 468</quote>, and
<quote>change line 197 to this</quote>. They are also known
as diffs because they are generated by the
&man.diff.1; program.</para>
</answer>
</qandaentry>
<indexterm><primary>tarball</primary></indexterm>
<qandaentry>
<question>
<para id="ports-tarball">What is all this about
tarballs?</para>
</question>
<answer>
<para>It is a file ending in <filename>.tar</filename>, or
with variations such as <filename>.tar.gz</filename>,
<filename>.tar.Z</filename>, <filename>.tar.bz2</filename>,
and even <filename>.tgz</filename>.</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
&man.tar.1; program, which comes with the base
FreeBSD system, like this:</para>
<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>
</answer>
</qandaentry>
<indexterm><primary>checksum</primary></indexterm>
<qandaentry>
<question>
<para id="ports-checksum">And checksums?</para>
</question>
<answer>
<para>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.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I did what you said for compiling ports from a CDROM and
it worked great until I tried to install the <application>Kermit</application>
port.</para>
<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>
<para>Why can it not be found? Have I got a dud CDROM?</para>
</question>
<answer>
<para>As explained in the <link
linkend="ports-cd">installing ports from CDROM</link>
section, some ports cannot be put on the CDROM set
due to licensing restrictions. <application>Kermit</application> is an example of
that. The licensing terms for <application>Kermit</application> do not allow us to put
the tarball for it on the CDROM, so you will have to fetch
it by hand&mdash;sorry!</para>
<para>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 <makevar>MASTER_SITES</makevar>
(listed in the <filename>Makefile</filename>), you can restart the install
process.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>The ports mechanism will download distribution
tarballs into <filename>/usr/ports/distfiles</filename>,
but many system administrators will symlink this directory
to a remote file server or local read-only CD-ROM media.
If this is the case, then you should specify a different
directory to be used for storing distfiles with the
following command:</para>
<screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/local/dir/with/write/permission</replaceable> install</userinput></screen>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>You can use the <makevar>PORTSDIR</makevar> and
<makevar>PREFIX</makevar> variables to tell the ports
mechanism to use different directories. For
instance,</para>
<screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen>
<para>will compile the port in
<filename>/u/people/guests/wurzburger/ports</filename> and
install everything under
<filename>/usr/local</filename>.</para>
<screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen>
<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>
<screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen>
<para>will combine the two (it is too long to write fully on
the page, but it should give you the general idea).</para>
<indexterm><primary>imake</primary></indexterm>
<para>Some ports that use &man.imake.1; (a part of the X Windows
System) do not work well with <makevar>PREFIX</makevar>, and will insist on
installing under <filename>/usr/X11R6</filename>. Similarly, some Perl ports
ignore <makevar>PREFIX</makevar> and install in the Perl tree. Making these
ports respect <makevar>PREFIX</makevar> is a difficult or impossible
job.</para>
<para>If you do not fancy typing all that in every time you
install a port, you can put these variables
into your environment. Read the manual page for your shell for
instructions on doing so.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I do not have a FreeBSD CD-ROM, 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 any
way to get them all at once?</para>
</question>
<answer>
<para>To get every single tarball for the ports collection,
do:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make fetch</userinput></screen>
<para>For all the tarballs for a single ports directory,
do:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make fetch</userinput></screen>
<para>and for just one port&mdash;well, you have probably
guessed already.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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 the
ones listed in the <makevar>MASTER_SITES</makevar>?</para>
</question>
<answer>
<para>Yes. If you know, for example, that <hostid
role="fqdn">ftp.FreeBSD.org</hostid> is much closer to you
than the sites listed in <makevar>MASTER_SITES</makevar>,
do as follows:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I want to know what files <command>make</command> is
going to need before it tries to pull them down.</para>
</question>
<answer>
<para><command>make fetch-list</command> will display a list
of the files needed for a port.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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 to watch it and hit
<keycombo action="simul">
<keycap>Ctrl</keycap>
<keycap>C</keycap>
</keycombo>
every time.</para>
</question>
<answer>
<para>Doing <command>make extract</command> will stop it
after it has fetched and extracted the source code.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>Yes, <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>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>Yes, with version 2.6.3 of <command>gcc</command> (the
version shipped with FreeBSD&nbsp;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 do not use
<option>-O2</option>). You <emphasis>should</emphasis> be
able to specify compiler options with something
like:</para>
<screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>
<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 <filename>Makefile</filename>s by hand, but
this can get tedious if the source has lots of
sub-directories, each with their own <filename>Makefile</filename>s.</para>
<para>The default FreeBSD compiler options are quite conservative,
so if you have not changed them you should not have any
problems.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>Look in the <filename>INDEX</filename> file in
<filename>/usr/ports</filename>. If you would like to
search the ports collection for a keyword, you can do that
too. For example, you can find ports relevant to the LISP
programming language using:</para>
<screen>&prompt.user; <userinput>cd /usr/ports</userinput>
&prompt.user; <userinput>make search key=lisp</userinput></screen>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I tried to install the <literal>foo</literal> port but
the system suddenly stopped compiling it and starting
compiling the <literal>bar</literal> port. What is going
on?</para>
</question>
<answer>
<para>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. Once <literal>bar</literal> is finished, your system should automatically resume building <literal>foo</literal>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para id="ports-remove"> 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>
</question>
<answer>
<para>No problem, just type:</para>
<screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen>
<para>Alternatively, you can type:</para>
<screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput>
&prompt.root; <userinput>make deinstall</userinput></screen>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>Not at all, you can find it out by doing:</para>
<screen>&prompt.root; <userinput>pkg_info -I 'grizzle*'</userinput>
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.</screen>
<para>The version number can be found either by using the
<command>pkg_info</command> or by typing:
<command>ls /var/db/pkg</command></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Speaking 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>
</question>
<answer>
<para>Yes, if you have installed a program and are fairly
certain you will not need the source again, there is no
point in keeping it hanging around. The surest way to do
this is:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make clean</userinput></screen>
<para>which will go through all the ports subdirectories and
delete everything except the skeletons for each
port.</para>
<tip><para>It is possible to achieve the same effect without
recursively calling each <filename>Makefile</filename>. For example, you
can delete all of the <filename>work/</filename> subdirectories directly
with the following command:
<screen>&prompt.root; <userinput>find /usr/ports -depth -name work -exec rm -rf {} \;</userinput></screen></para>
</tip>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>Yes, if you are sure you have finished with them,
those can go as well. They can be removed manually, or by
using <command>make distclean</command>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I like having lots and lots of programs to play with.
Is there any way of installing all the ports in one
go?</para>
</question>
<answer>
<para>Just do:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make install</userinput></screen>
<para>Be careful, as some ports may install files with the same
name. If you install two graphics ports and they both install
<filename>/usr/local/bin/plot</filename> then you will obviously
have problems.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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>
</question>
<answer>
<para>No, the problem is that some of the ports need to ask
you questions that we cannot answer for you (e.g., <quote>Do
you want to print on A4 or US letter sized paper?</quote>)
and they need to have someone on hand to answer
them.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I really do not want to spend all day staring at the
monitor. Any better ideas?</para>
</question>
<answer>
<para>OK, do this before you go to bed/work/the local
park:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make -DBATCH install</userinput></screen>
<para>This will install every port that does
<emphasis>not</emphasis> require user input. Then, when
you come back, do:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make -DINTERACTIVE install</userinput></screen>
<para>to finish the job.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>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 package, so we can distribute it more easily around
our sites?</para>
</question>
<answer>
<para>No problem, assuming you know how to make patches for
your changes:</para>
<screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></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>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>This ports stuff is really clever. I am desperate to
find out how you did it. What is the secret?</para>
</question>
<answer>
<para>Nothing secret about it at all, just look at the
<filename>bsd.port.mk</filename> and
<filename>bsd.port.subdir.mk</filename> files in
<filename>/usr/ports/Mk/</filename>.</para>
<para>(Readers with an aversion to intricate shell-scripts are
advised not to look at the files in this directory.)</para>
</answer>
</qandaentry>
</qandaset>
</sect2>
<sect2 id="ports-broken">
<title>Help! This Port Is Broken!</title>
<sect1 id="ports-broken">
<title>Dealing with Broken Ports</title>
<para>If you come across a port that does not work for you, there are
a few things you can do, including:</para>
@ -1694,7 +1151,6 @@ arcade game.</screen>
on your system.</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
</chapter>