diff --git a/handbook/ports.sgml b/handbook/ports.sgml index 201f900bfe..31bb7fd0f2 100644 --- a/handbook/ports.sgml +++ b/handbook/ports.sgml @@ -1,4 +1,4 @@ - + Installing Applications: The Ports collection @@ -38,20 +38,18 @@ system utilities, but a lot of popular programs are not in the base system, for good reasons:- -``I can not live without x y and z on my system'' type programs -(eg a certain Lisp-based editor, or the mtools set of programs for -dealing with DOS floppy disks), because it is too subjective (many -people can not stand Emacs and/or never use DOS floppies and seem none -the worse for it). +Programs that some people cannot live without and other people +cannot stand, such as a certain Lisp-based editor. -Too specialised to put in the base system (CAD, databases). +Programs which are too specialised to put in the base system +(CAD, databases). -Programs which fall into the ``I would not mind having a look at +Programs which fall into the ``I must have a look at that when I get a spare minute'' category, rather than system-critical ones (some languages, perhaps). -``Wow fab this is way cool'' fun type programs that could not -possibly be supplied with a serious operating system like FreeBSD ;-) +Programs that are far too much fun to be supplied with a serious +operating system like FreeBSD ;-) However many programs you put in the base system, people will always want more, and a line has to be drawn somewhere (otherwise @@ -88,9 +86,9 @@ user to be able to work it out. They also supply their own customised can be built in the same way.

If you look at a port skeleton (either on or ) 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. @@ -98,54 +96,49 @@ rather unexciting-looking files and directories you find there. name="Getting a port">).

``How on earth can this do anything?'' I hear you cry. ``There -is not even any source code there!'' +is no source code there!''

Fear not, gentle reader, all will become clear (hopefully). Let's -see what happens if we try and install a port. I have chosen `bash', also -known as the Bourne-Again Shell, as that seems fairly typical. +see what happens if we try and install a port. I have chosen `ElectricFence', +a useful tool for developers, as the skeleton is more straightforward than +most. Note if you are trying this at home, you will need to be root. - # cd /usr/ports/shells/bash - # make install - Checksums OK. - ===> Extracting for bash-1.14.5 - ===> Patching for bash-1.14.5 - ===> Applying FreeBSD patches for bash-1.14.5 - ===> Configuring for bash-1.14.5 - ===> Building for bash-1.14.5 - [lots and lots of compiler output here...] - ===> Installing for bash-1.14.5 - make -f bash-Makefile bindir=/usr/local/bin prefix=/usr/local install - (cd ./documentation/; make ) - rm -f 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 bashbug /usr/local/bin/bashbug - ( 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/info ] || mkdir /usr/local/info - ../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 features.info /usr/local/info/bash.info - gzip -9nf /usr/local/man/man1/bash.1 /usr/local/man/man1/bash_builtins.1 - ===> Registering installation for bash-1.14.5 + # cd /usr/ports/devel/ElectricFence +# make install +>> Checksum OK for ElectricFence-2.0.5.tar.gz. +===> Extracting for ElectricFence-2.0.5 +===> Patching for ElectricFence-2.0.5 +===> Applying FreeBSD patches for ElectricFence-2.0.5 +===> Configuring for ElectricFence-2.0.5 +===> Building for ElectricFence-2.0.5 +[lots of compiler output...] +===> Installing for ElectricFence-2.0.5 +===> 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 +===> Compressing manual pages for ElectricFence-2.0.5 +===> Registering installation for ElectricFence-2.0.5 -

To avoid confusing the issue, I have slightly pruned the install -output, as well as completely removing the build output. If you tried -this yourself, you may well have got something like this at the start:- +

To avoid confusing the issue, I have completely removed the build output. +

If you tried this yourself, you may well have got something like this at +the start:-

The `make' 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 (are you starting to feel impressed? 8-)). I already had the +done. I already had the source handy in my example, so it did not need to fetch it.

Let's go through this and see what the `make' program was doing. @@ -157,7 +150,7 @@ FTP site. Run a test on the tarball to make sure it has not been tampered with, accidentally -truncated, struck by neutrinos while in transit, etc. +truncated, downloaded in ASCII mode, struck by neutrinos while in transit, etc. Extract the tarball into a temporary work directory. @@ -181,8 +174,8 @@ id="ports:remove" name="remove"> all traces of it from your system. -

See if you can match these steps to the make output. And if you -were not impressed before, you should be by now! +

Scroll up to the make output and see if you can match these steps to it. +And if you were not impressed before, you should be by now! Getting a FreeBSD Port

@@ -208,7 +201,7 @@ say, /cdrom. Then do to enable the ports make mechanism to find the tarballs (it expects to find them in /usr/ports/distfiles, which is why we sym-linked the -CDROM's tarball directory to there). +CDROM's tarball directory to that directory).

Now, suppose you want to install the gnats program from the databases directory. Here is how to do it:- @@ -264,13 +257,12 @@ 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 for the port. Now this might sound like rather a fiddly job -full of pitfalls, like downloading the patches into the pkg -sub-directory by mistake, but it is actually very easy. +full of pitfalls, but it is actually very easy.

The key to it is that the FreeBSD FTP server can create on-the-fly 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 +bits in square brackets are comments. Do not type them in if you are trying this yourself!):- @@ -279,21 +271,19 @@ trying this yourself!):- # cd databases # ftp ftp.freebsd.org [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 (also known as image) mode!] > cd /pub/FreeBSD/ports/databases - > get gnats.tar.gz [tarballs up the gnats skeleton for us] + > get gnats.tar [tars up the gnats skeleton for us] > quit - # tar xzf gnats.tar.gz [extract the gnats skeleton] + # tar xf gnats.tar [extract the gnats skeleton] # cd gnats # make install [build and install gnats] 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 -`get gnats.tar.gz', the FTP server up the gnats directory for us and even went to the -trouble of compressing it before sending it so we could get our hands -on it a little quicker. +`get gnats.tar', the FTP server up the gnats directory for us.

We then extracted the gnats skeleton and went into the gnats directory to build the port. As we explained cd /pub/FreeBSD/ports - > get databases.tar.gz [tarballs up the databases directory for us] + > get databases.tar [tars up the databases directory for us] > quit - # tar xzf databases.tar.gz [extract all the database skeletons] + # tar xf databases.tar [extract all the database skeletons] # cd databases # make install [build and install all the database ports] @@ -324,12 +314,8 @@ 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?

-If you expect to be installing more than one or two ports, it is -probably worth downloading all the ports directories - this involves -downloading 2 or 3MB, when they are compressed. However, don't get -carried away and type 'get ports.tar.gz' unless you are prepared to -download the distfiles directory as well - this contains the source -code for every single port and will take a very long time to download! +If you expect to be installing many ports, it is +probably worth downloading all the ports directories. Skeletons

@@ -342,29 +328,31 @@ needed to make the ports magic work.

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 bash:- +installed. Here is the Makefile for ElectricFence:- - # New ports collection makefile for: bash - # Version required: 1.14.5 - # Date created: 21 August 1994 - # Whom: jkh - # - # Makefile,v 1.13 1995/10/04 14:45:01 asami Exp - # - - DISTNAME= bash-1.14.5 - CATEGORIES= shells - MASTER_SITES= ftp://slc2.ins.cwru.edu/pub/dist/ - - MAINTAINER= ache@FreeBSD.ORG - - post-install: - .if !defined(NOMANCOMPRESS) - gzip -9nf ${PREFIX}/man/man1/bash.1 ${PREFIX}/man/man1/bash_builtins.1 - .endif - - .include <bsd.port.mk> +# New ports collection makefile for: Electric Fence +# Version required: 2.0.5 +# Date created: 13 November 1997 +# Whom: jraynard +# +# $Id: ports.sgml,v 1.28 1997-12-06 01:35:40 jraynard Exp $ +# + +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 The lines beginning with a "#" sign are comments for the benefit @@ -373,7 +361,8 @@ of human readers (as in most Unix script files). `DISTNAME" specifies the name of the , but without the extension.

-`CATEGORIES" states what kind of program this is. +`CATEGORIES" states what kind of program this is. In this case, a +utility for developers.

`MASTER_SITES" is the URL(s) of the master FTP site, which is used to retrieve the if it is not @@ -384,11 +373,7 @@ on the Internet).

`MAINTAINER" 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. (Note: The title of "maintainer" -is mainly an administrative one; it does please mail -&a.ports; and Skipping over the next few lines for a minute, the line @@ -401,10 +386,12 @@ no point in duplicating them all over the place, so they are kept in a single standard file.

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 -`post-install" over-ride the instructions in bsd.port.mk -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. +how Makefiles work; suffice it to say that the line starting with ``MAN3'' +ensures that the ElectricFence man page is compressed after installation, +to help conserve your precious disk space. The original port did not +provide an ``install'' target, so the three lines from ``do-install'' +ensure that the files produced by this port are placed in the correct +destination. The files directory

@@ -538,11 +525,11 @@ generated by a program of that name.

-A. It is a file ending in .tar.gz (with variations like .tar.Z, or +A. It is a file ending in .tar or .tar.gz (with variations like .tar.Z, or even .tgz if you are trying to squeeze the names into a DOS filesystem).

Basically, it is a directory tree that has been archived into a single -file (.tar) and then compressed (.gz). This technique was originally +file (.tar) and optionally compressed (.gz). This technique was originally used for tar tvzf foobar.tar.gz # View contents of foobar.tar.gz tar xzvf foobar.tar.gz # Extract contents into the current directory + tar tvf foobar.tar # View contents of foobar.tar + tar xvf foobar.tar # Extract contents into the current directory

-A. Yep, 'make patch' is what you want. And by the way, thank you for +A. Yep, 'make patch' is what you want. You will probably find the +PATCH_DEBUG option useful as well. And by the way, thank you for your efforts! @@ -701,11 +691,11 @@ use -O2). You - # CFLAGS='-O2 -fno-strength-reduce' make install + make CFLAGS='-O2 -fno-strength-reduce' install -or by editing /etc/make.conf, but this does not always seem to get -picked up. The surest way is to do 'make configure', then go into the +or by editing /etc/make.conf, but unfortunately not all ports respect +this. The surest way is to do 'make configure', 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. @@ -718,7 +708,7 @@ A. Look in the INDEX file in /usr/ports. Q. I went to install the 'foo' port but the system suddenly stopped -and starting compiling the 'bar' port. What's going on? +compiling it and starting compiling the 'bar' port. What's going on?

A. The 'foo' port needs something that is supplied with 'bar' - for instance, if 'foo' uses graphics, 'bar' might have a library with @@ -793,7 +783,7 @@ computer this morning, it had only done three and a half ports. Did something go wrong?

A. No, the problem is that some of the ports need to ask you questions -that we can not answer for you (eg ``Do you want to print on A4 or US +that we cannot answer for you (eg ``Do you want to print on A4 or US letter sized paper?'') and they need to have someone on hand to answer them.