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

Add some formatting bug work-arounds.

Browse source
This commit is contained in:
John Fieber 1996-06-26 03:28:51 +00:00
parent c473aa2c00
commit bc6841f182
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=380
1 changed files with 127 additions and 127 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

254
handbook/ports.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: ports.sgml,v 1.11 1996-06-26 01:18:53 jraynard Exp $ --> <!-- $Id: ports.sgml,v 1.12 1996-06-26 03:28:51 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project --> <!-- The FreeBSD Documentation Project -->
<sect><heading>The Ports collection<label id="ports"></heading> <sect><heading>The Ports collection<label id="ports"></heading>
@ -78,7 +78,7 @@ as they could be), with perhaps a configuration script.
The standard scenario is that you FTP down the tarball, extract it The standard scenario is that you FTP down the tarball, extract it
somewhere, glance through the instructions, make any changes that seem somewhere, glance through the instructions, make any changes that seem
necessary, run the configure script to set things up and use the standard necessary, run the configure script to set things up and use the standard
'make' program to compile and install the program from the source. `make' program to compile and install the program from the source.
<p> <p>
FreeBSD ports still use the tarball mechanism, but use a FreeBSD ports still use the tarball mechanism, but use a
<ref id="ports:skeleton" name="skeleton"> to hold the &quot;knowledge&quot; <ref id="ports:skeleton" name="skeleton"> to hold the &quot;knowledge&quot;
@ -107,30 +107,30 @@ known as the Bourne-Again Shell, as that seems fairly typical.
<em /Note/ if you're trying this at home, you'll need to be root. <em /Note/ if you're trying this at home, you'll need to be root.
<verb> <verb>
# cd /usr/ports/shells/bash # cd /usr/ports/shells/bash
# make install # make install
Checksums OK. Checksums OK.
===> Extracting for bash-1.14.5 ===> Extracting for bash-1.14.5
===> Patching for bash-1.14.5 ===> Patching for bash-1.14.5
===> Applying FreeBSD patches for bash-1.14.5 ===> Applying FreeBSD patches for bash-1.14.5
===> Configuring for bash-1.14.5 ===> Configuring for bash-1.14.5
===> Building for bash-1.14.5 ===> Building for bash-1.14.5
[lots and lots of compiler output here...] [lots and lots of compiler output here...]
===> Installing for bash-1.14.5 ===> Installing for bash-1.14.5
make -f bash-Makefile bindir=/usr/local/bin prefix=/usr/local install make -f bash-Makefile bindir=/usr/local/bin prefix=/usr/local install
(cd ./documentation/; make ) (cd ./documentation/; make )
rm -f builtins.txt rm -f builtins.txt
nroff -man builtins.1 > builtins.txt nroff -man builtins.1 > builtins.txt
install -c -o bin -g bin -m 555 bash /usr/local/bin/bash install -c -o bin -g bin -m 555 bash /usr/local/bin/bash
install -c -o bin -g bin -m 555 bashbug /usr/local/bin/bashbug install -c -o bin -g bin -m 555 bashbug /usr/local/bin/bashbug
( cd ./documentation/ ; make mandir=/usr/local/man/man1 man3dir=/usr/local/man/man3 infodir=/usr/local/info install ) ( cd ./documentation/ ; make mandir=/usr/local/man/man1 man3dir=/usr/local/man/man3 infodir=/usr/local/info install )
[ -d /usr/local/man/man1 ] || mkdir /usr/local/man/man1 [ -d /usr/local/man/man1 ] || mkdir /usr/local/man/man1
[ -d /usr/local/info ] || mkdir /usr/local/info [ -d /usr/local/info ] || mkdir /usr/local/info
../support/install.sh -c -m 644 bash.1 /usr/local/man/man1 ../support/install.sh -c -m 644 bash.1 /usr/local/man/man1
../support/install.sh -c -m 644 builtins.1 /usr/local/man/man1/bash_builtins.1 ../support/install.sh -c -m 644 builtins.1 /usr/local/man/man1/bash_builtins.1
../support/install.sh -c -m 644 features.info /usr/local/info/bash.info ../support/install.sh -c -m 644 features.info /usr/local/info/bash.info
gzip -9nf /usr/local/man/man1/bash.1 /usr/local/man/man1/bash_builtins.1 gzip -9nf /usr/local/man/man1/bash.1 /usr/local/man/man1/bash_builtins.1
===> Registering installation for bash-1.14.5 ===> Registering installation for bash-1.14.5
</verb> </verb>
<p> To avoid confusing the issue, I've slightly pruned the install <p> To avoid confusing the issue, I've slightly pruned the install
@ -139,16 +139,16 @@ this yourself, you may well have got something like this at the start:-
<label id="ports:fetch"> <label id="ports:fetch">
<verb> <verb>
>> bash-1.14.5.tar.gz doesn't seem to exist on this system. >> bash-1.14.5.tar.gz doesn't seem to exist on this system.
>> Attempting to fetch from ftp://slc2.ins.cwru.edu/pub/dist/. >> Attempting to fetch from ftp://slc2.ins.cwru.edu/pub/dist/.
</verb> </verb>
<p> The 'make' program has noticed that you didn't have a local copy <p> The `make' program has noticed that you didn't have a local copy
of the source code and tried to FTP it down so it could get the job of the source code and tried to FTP it down so it could get the job
done (are you starting to feel impressed? 8-)). I already had the done (are you starting to feel impressed? 8-)). I already had the
source handy in my example, so it didn't need to fetch it. source handy in my example, so it didn't need to fetch it.
<p> Let's go through this and see what the 'make' program was doing. <p> Let's go through this and see what the `make' program was doing.
<enum> <enum>
<item> Locate the source code <ref id="ports:tarball" <item> Locate the source code <ref id="ports:tarball"
@ -201,9 +201,9 @@ If not, make sure the <em /FreeBSD/ CDROM is in the drive and mounted on,
say, /cdrom. Then do say, /cdrom. Then do
<verb> <verb>
# mkdir /usr/ports # mkdir /usr/ports
# cd /usr/ports # cd /usr/ports
# ln -s /cdrom/ports/distfiles distfiles # ln -s /cdrom/ports/distfiles distfiles
</verb> </verb>
to enable the ports make mechanism to find the tarballs (it expects to to enable the ports make mechanism to find the tarballs (it expects to
@ -214,21 +214,21 @@ Now, suppose you want to install the gnats program from the databases
directory. Here's how to do it:- directory. Here's how to do it:-
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# mkdir databases # mkdir databases
# cp -R /cdrom/ports/databases/gnats databases # cp -R /cdrom/ports/databases/gnats databases
# cd databases/gnats # cd databases/gnats
# make install # make install
</verb> </verb>
Or if you're a serious database user and you want to compare all the Or if you're a serious database user and you want to compare all the
ones available in the Ports collection, do ones available in the Ports collection, do
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# cp -R /cdrom/ports/databases . # cp -R /cdrom/ports/databases .
# cd databases # cd databases
# make install # make install
</verb> </verb>
(yes, that really is a dot on its own after the cp command and not a (yes, that really is a dot on its own after the cp command and not a
@ -272,23 +272,23 @@ bits in square brackets are comments, don't type them in if you're
trying this yourself!):- trying this yourself!):-
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# mkdir databases # mkdir databases
# cd databases # cd databases
# ftp ftp.freebsd.org # ftp ftp.freebsd.org
[log in as `ftp' and give your email address when asked for a [log in as `ftp' and give your email address when asked for a
password. Remember to use binary (aka image) mode!] password. Remember to use binary (aka image) mode!]
> cd /pub/FreeBSD/ports/databases > cd /pub/FreeBSD/ports/databases
> get gnats.tar.gz [tarballs up the gnats skeleton for us] > get gnats.tar.gz [tarballs up the gnats skeleton for us]
> quit > quit
# tar xzf gnats.tar.gz [extract the gnats skeleton] # tar xzf gnats.tar.gz [extract the gnats skeleton]
# cd gnats # cd gnats
# make install [build and install gnats] # make install [build and install gnats]
</verb> </verb>
What happened here? We connected to the FTP server in the usual way What happened here? We connected to the FTP server in the usual way
and went to its databases sub-directory. When we gave it the command and went to its databases sub-directory. When we gave it the command
'get gnats.tar.gz', the FTP server <ref id="ports:tarball" `get gnats.tar.gz', the FTP server <ref id="ports:tarball"
name="tarballed"> up the gnats directory for us and even went to the name="tarballed"> up the gnats directory for us and even went to the
trouble of compressing it before sending it so we could get our hands trouble of compressing it before sending it so we could get our hands
on it a little quicker. on it a little quicker.
@ -304,16 +304,16 @@ port skeleton, let's get a whole sub-directory, for example all the
database skeletons in the ports collection. It looks almost the same:- database skeletons in the ports collection. It looks almost the same:-
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# ftp ftp.freebsd.org # ftp ftp.freebsd.org
[log in as `ftp' and give your email address when asked for a [log in as `ftp' and give your email address when asked for a
password. Remember to use binary (aka image) mode!] password. Remember to use binary (aka image) mode!]
> cd /pub/FreeBSD/ports/databases > cd /pub/FreeBSD/ports/databases
> get databases.tar.gz [tarballs up the databases directory for us] > get databases.tar.gz [tarballs up the databases directory for us]
> quit > quit
# tar xzf databases.tar.gz [extract all the database skeletons] # tar xzf databases.tar.gz [extract all the database skeletons]
# cd databases # cd databases
# make install [build and install all the database ports] # make install [build and install all the database ports]
</verb> </verb>
With half a dozen straightforward commands, we have now got a set of With half a dozen straightforward commands, we have now got a set of
@ -343,44 +343,44 @@ various statements that specify how the port should be compiled and
installed. Here's the Makefile for bash:- installed. Here's the Makefile for bash:-
<verb> <verb>
# New ports collection makefile for: bash # New ports collection makefile for: bash
# Version required: 1.14.5 # Version required: 1.14.5
# Date created: 21 August 1994 # Date created: 21 August 1994
# Whom: jkh # Whom: jkh
# #
# Makefile,v 1.13 1995/10/04 14:45:01 asami Exp # Makefile,v 1.13 1995/10/04 14:45:01 asami Exp
# #
DISTNAME= bash-1.14.5 DISTNAME= bash-1.14.5
CATEGORIES+= shells CATEGORIES+= shells
MASTER_SITES= ftp://slc2.ins.cwru.edu/pub/dist/ MASTER_SITES= ftp://slc2.ins.cwru.edu/pub/dist/
MAINTAINER= ache@FreeBSD.ORG MAINTAINER= ache@FreeBSD.ORG
post-install: post-install:
.if !defined(NOMANCOMPRESS) .if !defined(NOMANCOMPRESS)
gzip -9nf ${PREFIX}/man/man1/bash.1 ${PREFIX}/man/man1/bash_builtins.1 gzip -9nf ${PREFIX}/man/man1/bash.1 ${PREFIX}/man/man1/bash_builtins.1
.endif .endif
.include <bsd.port.mk> .include &lt;bsd.port.mk>
</verb> </verb>
The lines beginning with a &quot;#&quot; sign are comments for the benefit The lines beginning with a &quot;#&quot; sign are comments for the benefit
of human readers (as in most Unix script files). of human readers (as in most Unix script files).
<p> <p>
&quot;DISTNAME&quot; specifies the name of the <ref id="ports:tarball" `DISTNAME&quot; specifies the name of the <ref id="ports:tarball"
name="tarball">, but without the extension. name="tarball">, but without the extension.
<p> <p>
&quot;CATEGORIES&quot; states what kind of program this is. `CATEGORIES&quot; states what kind of program this is.
<p> <p>
&quot;MASTER_SITES&quot; is the URL(s) of the master FTP site, which is `MASTER_SITES&quot; is the URL(s) of the master FTP site, which is
used to retrieve the <ref id="ports:tarball" name="tarball"> if it is not used to retrieve the <ref id="ports:tarball" name="tarball"> if it is not
available on the local system. This is a site which is regarded as 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 reputable, and is normally the one from which the program is officially
distributed (in so far as any software is &quot;officially&quot; distributed distributed (in so far as any software is &quot;officially&quot; distributed
on the Internet). on the Internet).
<p> <p>
&quot;MAINTAINER&quot; is the email address of the person who is `MAINTAINER&quot; is the email address of the person who is
responsible for updating the skeleton if, for example a new version responsible for updating the skeleton if, for example a new version
of the program comes out. (Note: The title of &quot;maintainer&quot; of the program comes out. (Note: The title of &quot;maintainer&quot;
is mainly an administrative one; it does <em /not/ mean the person is mainly an administrative one; it does <em /not/ mean the person
@ -390,17 +390,17 @@ concerned is responsible for supporting the program. If you have any
<p> <p>
Skipping over the next few lines for a minute, the line Skipping over the next few lines for a minute, the line
<verb> <verb>
.include <bsd.port.mk> .include <bsd.port.mk>
</verb> </verb>
says that the other statements and commmands says that the other statements and commmands
needed for this port are in a standard file called needed for this port are in a standard file called
&quot;bsd.port.mk&quot;. As these are the same for all ports, there is `bsd.port.mk&quot;. 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 no point in duplicating them all over the place, so they are kept in a
single standard file. single standard file.
<p> <p>
This is probably not the place to go into a detailed examination of This is probably not the place to go into a detailed examination of
how Makefiles work; suffice it to say that the lines starting with how Makefiles work; suffice it to say that the lines starting with
&quot;post-install&quot; over-ride the instructions in bsd.port.mk `post-install&quot; over-ride the instructions in bsd.port.mk
about what to do after installing the program, so that the man pages about what to do after installing the program, so that the man pages
can be compressed after they have been put in their final destination. can be compressed after they have been put in their final destination.
@ -434,7 +434,7 @@ DESCR - a more detailed description.
PLIST - a list of all the files that will be created when the program is installed. PLIST - a list of all the files that will be created when the program is installed.
</itemize> </itemize>
<sect1><heading>It does not work?!<label id="kaput"></heading> <sect1><heading>It does not work?!<label id="ports:kaput"></heading>
<p>Oh. You can do one of four (4) things : <p>Oh. You can do one of four (4) things :
@ -536,8 +536,8 @@ generated by a program of that name.
<item><label id="ports:tarball"> <item><label id="ports:tarball">
Q. What's all this about tarballs? Q. What's all this about tarballs?
<p> <p>
A. It's a file ending in .tar.gz (with variations like .tar.Z, or even A. It's a file ending in .tar.gz (with variations like .tar.Z, or
.tgz if you're trying to squeeze the names into a DOS filesystem). even .tgz if you're trying to squeeze the names into a DOS filesystem).
<p> <p>
Basically, it's a directory tree that's been archived into a single Basically, it's a directory tree that's been archived into a single
file (.tar) and then compressed (.gz). This technique was originally file (.tar) and then compressed (.gz). This technique was originally
@ -550,8 +550,8 @@ using the standard Unix tar program, which comes with the base FreeBSD
system, like this:- system, like this:-
<verb> <verb>
tar tvzf foobar.tar.gz # View contents of foobar.tar.gz tar tvzf foobar.tar.gz # View contents of foobar.tar.gz
tar xzvf foobar.tar.gz # Extract contents into the current directory tar xzvf foobar.tar.gz # Extract contents into the current directory
</verb> </verb>
<item><label id="ports:checksum"> <item><label id="ports:checksum">
@ -570,9 +570,9 @@ from a CDROM"> and it worked great until I tried to install the kermit
port:- port:-
<verb> <verb>
# make install # make install
>> cku190.tar.gz doesn't seem to exist on this system. >> cku190.tar.gz doesn't seem to exist on this system.
>> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. >> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.
</verb> </verb>
Why can't it find it? Have I got a dud CDROM? Why can't it find it? Have I got a dud CDROM?
@ -595,7 +595,7 @@ to the CDROM, which is read-only. You can tell it to look somewhere
else by doing else by doing
<verb> <verb>
DISTDIR=/where/you/put/it make install DISTDIR=/where/you/put/it make install
</verb> </verb>
<item> <item>
@ -607,14 +607,14 @@ A. You can use the PORTSDIR and PREFIX variables to tell the ports
mechanism to use different directories. For instance, mechanism to use different directories. For instance,
<verb> <verb>
PORTSDIR=/u/people/guests/wurzburger/ports make install PORTSDIR=/u/people/guests/wurzburger/ports make install
</verb> </verb>
will compile the port in /u/people/guests/wurzburger/ports and install will compile the port in /u/people/guests/wurzburger/ports and install
everything under /usr/local. everything under /usr/local.
<verb> <verb>
PREFIX=/u/people/guests/wurzburger/local make install PREFIX=/u/people/guests/wurzburger/local make install
</verb> </verb>
will compile it in /usr/ports and install it in will compile it in /usr/ports and install it in
@ -623,7 +623,7 @@ will compile it in /usr/ports and install it in
And of course And of course
<verb> <verb>
PORTSDIR=.../ports PREFIX=.../local make install PORTSDIR=.../ports PREFIX=.../local make install
</verb> </verb>
will combine the two (it's too long to fit on the page if I write it will combine the two (it's too long to fit on the page if I write it
@ -641,15 +641,15 @@ install a port. Is there an easy way to get them all at once?
A. To get every single tarball for the ports collection, do A. To get every single tarball for the ports collection, do
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# make fetch # make fetch
</verb> </verb>
For all the tarballs for a single ports directory, do For all the tarballs for a single ports directory, do
<verb> <verb>
# cd /usr/ports/directory # cd /usr/ports/directory
# make fetch # make fetch
</verb> </verb>
and for just one port - well, I think you've guessed already. and for just one port - well, I think you've guessed already.
@ -687,7 +687,7 @@ use -O2). You <em /should/ be able to specify the compiler options
used by something like used by something like
<verb> <verb>
# CFLAGS='-O2 -fno-strength-reduce' make install # CFLAGS='-O2 -fno-strength-reduce' make install
</verb> </verb>
or by editing /etc/make.conf, but this doesn't always seem to get or by editing /etc/make.conf, but this doesn't always seem to get
@ -719,7 +719,7 @@ where it put all the files. Any clues?
A. No problem, just do A. No problem, just do
<verb> <verb>
pkg_delete grizzle-6.5 pkg_delete grizzle-6.5
</verb> </verb>
<item> <item>
@ -729,14 +729,14 @@ command. You don't seriously expect me to remember that, do you??
A. Not at all, you can find it out by doing A. Not at all, you can find it out by doing
<verb> <verb>
pkg_info -a | grep grizzle pkg_info -a | grep grizzle
</verb> </verb>
And it'll tell you:- And it'll tell you:-
<verb> <verb>
Information for grizzle-6.5: Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game. grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game.
</verb> </verb>
<item> <item>
@ -753,8 +753,8 @@ won't need the source again, there's no point in keeping it hanging
around. The best way to do this is around. The best way to do this is
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# make clean # make clean
</verb> </verb>
which will go through all the ports subdirectories and delete which will go through all the ports subdirectories and delete
@ -773,8 +773,8 @@ way of installing all the ports in one go?
A. Just do A. Just do
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# make install # make install
</verb> </verb>
<item> <item>
@ -795,16 +795,16 @@ better ideas?
A. OK, do this before you go to bed/work/the local park:- A. OK, do this before you go to bed/work/the local park:-
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# make -DBATCH install # make -DBATCH install
</verb> </verb>
This will install every port that does <em /not/ require user This will install every port that does <em /not/ require user
input. Then, when you come back, do input. Then, when you come back, do
<verb> <verb>
# cd /usr/ports # cd /usr/ports
# make -DIS_INTERACTIVE install # make -DIS_INTERACTIVE install
</verb> </verb>
to finish the job. to finish the job.
@ -818,12 +818,12 @@ easily around our sites?
A. No problem, assuming you know how to make patches for your changes:- A. No problem, assuming you know how to make patches for your changes:-
<verb> <verb>
# cd /usr/ports/somewhere/frobble # cd /usr/ports/somewhere/frobble
# make extract # make extract
# cd work/frobble-2.8 # cd work/frobble-2.8
[Apply your patches] [Apply your patches]
# cd ../.. # cd ../..
# make package # make package
</verb> </verb>
<item> <item>