From f9f4cdbff7c8260a1b25d63168a3c7f500ed37f2 Mon Sep 17 00:00:00 2001 From: "Jordan K. Hubbard" Date: Wed, 26 Jun 1996 09:24:03 +0000 Subject: [PATCH] Merge from HEAD --- handbook/authors.sgml | 6 +- handbook/contrib.sgml | 10 +- handbook/pgpkeys.sgml | 68 ++-- handbook/ports.sgml | 923 ++++++++++++++++++++++++++++++++++-------- handbook/slips.sgml | 13 +- 5 files changed, 816 insertions(+), 204 deletions(-) diff --git a/handbook/authors.sgml b/handbook/authors.sgml index 8b173b6b28..9f027318a6 100644 --- a/handbook/authors.sgml +++ b/handbook/authors.sgml @@ -1,4 +1,4 @@ - + + FreeBSD contributor list @@ -93,6 +93,7 @@ &a.se; &a.fenner; &a.jfieber; + &a.jhay; &a.lars; &a.tg; &a.graichen; @@ -219,12 +220,10 @@ Jian-Da Li <jdli@FreeBSD.csie.NCTU.edu.tw> Jim Wilson <wilson@moria.cygnus.com> John Capo <jc@irbs.com> - John Hay <jhay@mikom.csir.co.za> John Perry <perry@vishnu.alias.net> Juergen Lock <nox@jelal.hb.north.de> Julian Jenkins <kaveman@magna.com.au> - Julian Stacey <stacey@guug.de> - (fallback: <julian@meepmeep.pcs.com>) + Julian Stacey <jhs@freebsd.org> Keith Bostic <bostic@toe.CS.Berkeley.EDU> Keith Moore <?> Kirk McKusick <mckusick@mckusick.com> @@ -330,8 +329,7 @@ John Woods <jfw@eddie.mit.edu> Jordan K. Hubbard <jkh@whisker.hubbard.ie> Julian Elischer <julian@dialix.oz.au> - Julian Stacey <stacey@guug.de> - (fallback: <julian@meepmeep.pcs.com>) + Julian Stacey <jhs@freebsd.org> Karl Lehenbauer <karl@NeoSoft.com> <karl@one.neosoft.com> Keith Bostic <bostic@toe.CS.Berkeley.EDU> diff --git a/handbook/pgpkeys.sgml b/handbook/pgpkeys.sgml index 49838d9142..ce3fde233a 100644 --- a/handbook/pgpkeys.sgml +++ b/handbook/pgpkeys.sgml @@ -1,4 +1,4 @@ - + PGP keys @@ -145,37 +145,41 @@ Version: 2.6.3ia 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 -RhIG8pXauhAd9zrp2sxXH2RUSHF5NbH8iw72BA== -=ekPo +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 +ldq6EB33OunazFcfZFRIcXk1sfyLDvYE +=4Yu3 -----END PGP PUBLIC KEY BLOCK----- diff --git a/handbook/ports.sgml b/handbook/ports.sgml index fa6942b2e9..b2256d1c89 100644 --- a/handbook/ports.sgml +++ b/handbook/ports.sgml @@ -1,107 +1,446 @@ - + The Ports collection -

Contributed by &a.gpalmer; and &a.jkh;. +

Contributed by &a.jraynard;. - Unfortunately, there are more variations of UN*X than most people -know of, and hence not all software for UN*X available on the Internet -will work on all versions of UN*X (in fact, I can guarantee it!). -Hence, some software needs modifications to work under some UN*Xs. The -process of making those modifications is known as ``porting'' and the -result known as a ``port'' (not to be confused with the sockets on the -back of your computer!). +The FreeBSD Ports collection allows you to compile and install a very +wide range of applications with a minimum of effort. +

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's 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 +``out of the box'', 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... -What is the FreeBSD Ports Collection? +

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've never heard of and then ask you lots of +questions that sound like a final exam in system-level Unix +programming (``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?''). -

When 2.0 was released, the FreeBSD Project decided to attempt to -automate the process of ``porting'' such software to FreeBSD, and the -result is the Ports Collection. The general idea was that a -combination of various programming tools already available in the base -FreeBSD installation would allow you to simply type `make' for a given -port and have the underlying ports mechanism automatically fetch the -port from a FreeBSD mirror site, apply any special configuration -knowledge to it and then build it to result in a fully working version -of the program. +

Fortunately, with the Ports collection, all the hard work involved +has already been done, and you can just type 'make install' and get a +working program. - The ports collection itself normally doesn't have any of the -original source code necessary for the compilation in the tree, just -those shell scripts, Makefiles and source code ``diffs'' that are -necessary to configure and compile the program under FreeBSD. This -keeps the entire system down to a manageable size, with the current -system having over 300 ports in the master source tree and yet taking -up less than twenty megabytes. +Why have a Ports Collection? +

The base FreeBSD system comes with a very wide range of tools and +system utilities, but a lot of popular programs aren't in the base +system, for good reasons:- -How does the system compile with no source code? + +``I can't 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's too subjective (many +people can't stand Emacs and/or never use DOS floppies and seem none +the worse for it). -

The Makefile for a port automatically looks in a central location -on your system (usually /usr/ports/distfiles, though this value can be -customized) for the associated set of original distribution files that -have been ``ported''. Those not found locally are searched for -wherever they are generally provided on the Internet. If you have a -CDROM distribution of FreeBSD then you already have them available -on your CD for ease of use. See if you have such a CDROM -distribution, otherwise skip to . +Too specialised to put in the base system (CAD, databases). -Compiling ports from CDROM +Programs which fall into the ``I wouldn't mind having a look at +that when I get a spare minute'' category, rather than system-critical +ones (some languages, perhaps). -

The ports collection is easy to use from CDROM, and all you need to -do is to create a "link tree" to it using the lndir(1) command that +``Wow fab this is way cool'' fun type programs that couldn't +possibly 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 +FreeBSD distributions would become absolutely enormous). + + +

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. + +

Incidentally, this is an excellent illustration of how ``the Unix way'' +works in practice by combining a set of simple but very flexible tools +into something very powerful. + + How does the Ports collection work? +

+Programs are typically distributed on the Internet as a + 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. +

+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 +`make' program to compile and install the program from the source. +

+FreeBSD ports still use the tarball mechanism, but use a + to hold the "knowledge" +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 +, so that almost every port +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. +(We'll discuss in a minute how to go about ). + +

``How on earth can this do anything?'' I hear you cry. ``There +isn't even any 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've chose `bash', also +known as the Bourne-Again Shell, as that seems fairly typical. + + + # 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 + + +

To avoid confusing the issue, I've 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:- + +

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 +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. + +

Let's go through this and see what the `make' program was doing. + + + Locate the source code If it's not available locally, try to grab it from an +FTP site. + + Run a test on the +tarball to make sure it hasn't been tampered with, accidentally +truncated, struck by neutrinos while in transit, etc. + + Extract the tarball into a temporary work directory. + + Apply any needed to get +the source to compile and run under FreeBSD. + + Run any configuration script required by the build process and +correctly answer any questions it asks. + + (Finally!) Compile the code. + + Install the program executable and other supporting files, man +pages, etc. under the /usr/local hierarchy, where they won't 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. + + Register the installation in a database. This means +that, if you don't like the program, you can cleanly all traces of it from your system. + + + +

See if you can match these steps to the make output. And if you +weren't impressed before, you should be by now! + +Getting a FreeBSD Port +

+There are two ways of getting hold of the FreeBSD port for a +program. One requires a , the other involves using an + +Compiling ports from CDROM +

+If you answered yes to the question ``Do you want to link the ports +collection to your CDROM'' during the FreeBSD installation, the initial +setting up will already have been done for you. +

+If not, make sure the + # mkdir /usr/ports + # cd /usr/ports + # ln -s /cdrom/ports/distfiles distfiles + + +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). +

+Now, suppose you want to install the gnats program from the databases +directory. Here's how to do it:- + + + # cd /usr/ports + # mkdir databases + # cp -R /cdrom/ports/databases/gnats databases + # cd databases/gnats + # make install + + +Or if you're a serious database user and you want to compare all the +ones available in the Ports collection, do + + + # cd /usr/ports + # cp -R /cdrom/ports/databases . + # cd databases + # make install + + +(yes, that really is a dot on its own after the cp command and not a +mistake. It's Unix-ese for ``the current directory'') +

+and the ports make mechanism will automatically compile and install +all the ports in the databases directory for you! +

+If you don't like this method, here's a completely different way of +doing it:- +

+Create a "link tree" to it using the lndir(1) command that comes with the XFree86 distribution. Find a location with some free space and create a directory there, and make a symbolic link -from /usr/ports to that directory. Then invoke the lndir(1) command with -the full pathname of the ``ports'' directory on the CDROM as an -argument (this might be, for example, something like: lndir -/cdrom/ports). Then you can build ports directly off the CDROM by -building them in the link tree you have created. - +from /usr/ports to that directory. Then invoke the +lndir(1) command with the full pathname of the ``ports'' +directory on the CDROM as an argument (this might be, for example, +something like: lndir /cdrom/ports). Then you can build +ports directly off the CDROM by building them in the link tree you +have created. +

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 next section (). +you will need to look at the section on -Compiling ports using an Internet connection +Compiling ports from the Internet +

+If you don't have a CDROM, or you want to make sure you get the very +latest version of the port you want, you'll 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's actually very easy. +

+The key to it is that the FreeBSD FTP server can create on-the-fly + for you. Here's how it works, +with the gnats program in the databases directory as an example (the +bits in square brackets are comments, don't type them in if you're +trying this yourself!):- -

The ports collection can also use an auto-fetch system to keep -your ports collection source tree up to date, updating the central -``distfiles'' version for you the next time you compile the port. + + # cd /usr/ports + # mkdir databases + # 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!] + > cd /pub/FreeBSD/ports/databases + > get gnats.tar.gz [tarballs up the gnats skeleton for us] + > quit + # tar xzf gnats.tar.gz [extract the gnats skeleton] + # cd gnats + # make install [build and install gnats] + - Of course, this assumes you have a permanent network link or do not -mind heavy usage of your telephone. If you do not want heavy network -usage when you compile your ports tree, you can pre-fetch the -necessary tarballs beforehand and put them into /usr/ports/distfiles -by hand. A good way to see what files a port is going to need is to -cd to that ports' directory and do a make fetch-list to see what -it does. The output of make fetch-list can also be used as a -shell script to fetch the ports' tarballs at a well-connected machine. +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. +

+We then extracted the gnats skeleton and went into the gnats directory +to build the port. As we explained , the make process noticed we didn't have a copy of the +source locally, so it fetched one before extracting, patching and +building it. +

+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:- - You can also chose to get the source files either from the master -FTP site as defined in the relevant Makefile (in the MASTER_SITES -line), or some FreeBSD mirror site also carrying a set of distfiles, -as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in -the directory /pub/FreeBSD/distfiles. Note that the files in -that directory are not guaranteed to be kept up to date - this is a -volunteer project! We canno make any guarantees about the mirror -sites either - they are obviously under independent control and do not -even have to mirror the distfiles directory. + + # cd /usr/ports + # 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!] + > cd /pub/FreeBSD/ports/databases + > get databases.tar.gz [tarballs up the databases directory for us] + > quit + # tar xzf databases.tar.gz [extract all the database skeletons] + # cd databases + # make install [build and install all the database ports] + - If you have a non-permanent link, you can fetch all the distfiles by -going to the top of the tree and typing ``make fetch''. +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? +

+If you expect to be installing more than one or two ports, it's +probably worth downloading all the ports directories - this involves +downloading 2 or 3MB, when they're compressed. However, don't get +carried away and type 'get ports.tar.gz' unless you're 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! +Skeletons +

+A team of compulsive hackers who've 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. -It does not work?! +Makefile +

+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's the Makefile for bash:- + + + # 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> + + +The lines beginning with a "#" sign are comments for the benefit +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. +

+`MASTER_SITES" is the URL(s) of the master FTP site, which is +used to retrieve the 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 "officially" distributed +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 + + .include + +says that the other statements and commmands +needed for this port are in a standard file called +`bsd.port.mk". 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. +

+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. + +The files directory +

+The file containing the for +the port is called "md5", after the MD5 algorithm +used for ports checksums. It lives in a directory with the slightly +confusing name of "files". +

+This directory can also contain other miscellaneous files that are required +by the port and don't belong anywhere else. + +The patches directory +

+This directory contains the needed +to make everything work properly under FreeBSD. + +The pkg directory +

+This program contains three quite useful files:- + + + +COMMENT - a one-line description of the program. + + +DESCR - a more detailed description. + + +PLIST - a list of all the files that will be created when the program is installed. + + +It does not work?!

Oh. You can do one of four (4) things : + - Fix it yourself. Technical details can be found in - . - + Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are in no way responsible for the functionality (or lack thereof) of the FreeBSD system as a whole, and especially the ports system, which @@ -109,9 +448,9 @@ going to the top of the tree and typing ``make fetch''. the catalogue, especially the line saying "We cannot offer tech-support on this product") - The e-mail address is the &a.ports;. Please include details of - the port, where you got both the port source & distfile(s) from, and - what the error was. + The e-mail address is the &a.ports;. Please include + details of the port, where you got both the port source & + distfile(s) from, and what the error was. Note: At time of writing, lang/Sather does not seem to work on Pentium machines due to the Intel Curse (aka the Floating Point Division Bug). @@ -122,116 +461,378 @@ going to the top of the tree and typing ``make fetch''. ports can be classified as `essential'! Grab the pre-compiled package from a ftp server. The ``master'' package - collection is in: - ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/ + collection is on FreeBSD's FTP server in the though check your local mirror first, please! These are more likely to work (on the whole) than trying to compile from - source, and a lot faster! Use the pkg_add(1) or pkg_manage(1) program to - install them to your system. + source, and a lot faster! Use the pkg_add(1) or + pkg_manage(1) program to install them to your system. + -I have ported a program and I want to make a port out of it. What now? +I've got this program I'd like to make into a port... -

See the that - contain details of the procedure and structure involved. +

Great! Please see the +for detailed instructions on how to do this. -I have got a good port, what now? +Some Questions and Answers +

+ + +Q. I thought this was going to be a discussion about modems??! +

+A. Ah. You must be thinking of the serial ports on the back of your +computer. We're using `port' here to mean the result of `porting' a +program from one version of Unix to another. (It's an unfortunate bad +habit of computer people to use the same word to refer to several +completely different things). -

Upload the fixed version to ftp://freefall.cdrom.com/pub/incoming or -ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming and send e-mail to -the &a.ports with the filename and details. Someone on the -all-volunteer `ports committee' will (hopefully) look it over and -commit it to the ports collection if they like the looks of it. + +Q. I thought you were supposed to use packages to install extra +programs? +

+A. Yes, that's usually the quickest and easiest way of doing it. + +Q. So why bother with ports then? +

+A. Several reasons:- -I want to leave the compile going overnight, but some ports do not like this. + + The licensing conditions on some software distributions +require that they be distributed as source code, not binaries. + + Some people don't trust binary distributions. At least with +source code you can (in theory) read through it and look for potential +problems yourself. + + If you've got some local patches, you'll need the source to add +them yourself. + + You might have opinions on how a program should be compiled +that differ from the person who did the package - 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. + + 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. + + If you ain't got the source, it ain't software! ;-) + + +

+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 ``delete line 23'', ``add these two lines after line 468'' +or ``change line 197 to this''. Also known as a `diff', since it's +generated by a program of that name. + +

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

+Basically, it's a directory tree that's been archived into a single +file (.tar) and then compressed (.gz). This technique was originally +used for +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:- -

There is a way around this. Before starting the compilation, type: - setenv BATCH yes # (if you use csh/tcsh) or - BATCH=yes; export BATCH # (for sh/bash) + tar tvzf foobar.tar.gz # View contents of foobar.tar.gz + tar xzvf foobar.tar.gz # Extract contents into the current directory - This should skip ports which need user interaction to build. - To compile those ports left out by doing the above, using a -different login shell (or unsetting the above BATCH variable), set the -INTERACTIVE variable instead (you can use the same statements as above -except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This -should now compile only those ports which will definitely ask for user -interaction. +

+A. It's 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's done in a more complicated way +to spot problems like position-swapping, which won't show up with a +simplistic addition). + +Q. I did what you said for and it worked great until I tried to install the kermit +port:- -The ports collection is weak. What can I do to help? - -

First read the bsd.port.mk file (which may be found in -/usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of -the weirdness can be explained properly in there (most of the current -weirdness is due to the lack of assumptions about anything, which is -necessary due to the generic nature of these files). Also check that -you have an up-to-date copy, as the file can change from minute to -minute. The most up-to-date copy can be found in: - - - - If you find that you still need to go in there and alter things, -by all means do so, and then send the diffs to the &a.ports if -you would like them to be a part of the default distribution. Please also -remember that any changes must respect backwards-compatibility with -any and all older Makefiles, unless you want a real nightmare of -/usr/ports munging ahead of you! Large scale changes will generally -not be warmly welcomed unless all the existing makefiles work without -alteration. Sorry! - - -This FAQ is weak. What can I do? - -

Send changes to the &a.ports;. Changes are most welcome! -This FAQ is also very green and should be considered no more than -a `good start' for now. Authors? You can come out of hiding any -time now! :-) - - -How do I get more information on all the ports? - -

One good method is to cd to the top of the ports tree (say /usr/ports) -and type: - make print-index + # make install + >> cku190.tar.gz doesn't seem to exist on this system. + >> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. -This will print a summary of all ports in the tree. -I have heard of a new checksum system. What is this for? +Why can't it find it? Have I got a dud CDROM? +

+A. The licensing terms for kermit don't allow us to put the tarball +for it on the CDROM, so you'll have to fetch it by hand - sorry! +The reason why you got all those error messages was because you +weren't connected to the Internet at the time. Once you've 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). -

For various reasons, when using FTP over the Internet to obtain the -source code, you may not always end up with the same copy of the code -that the original porter worked from, and this can lead to problems. -So a simple checksumming system has been employed to try and highlight -problems in this area. + +Q. I did that, but when I tried to put it into /usr/ports/distfiles I +got some error about not having permission. +

+A. The ports mechanism looks for the tarball in /usr/ports/distfiles, +but you won't be able to copy anything there because it's sym-linked +to the CDROM, which is read-only. You can tell it to look somewhere +else by doing - To check the entire system, go to the top of the ports tree -(defaults to /usr/ports) and type - make checksum + DISTDIR=/where/you/put/it make install -This will give a report on the validity of the files you have FTP'd. If some -are missing, the system will attempt to retrieve them before running the -checksum routine. The same technique can be applied to a single port. - The system will complain if there is no pre-computed checksum available -for that port. Not all ports currently have checksums, but this should be -cured soon. + +Q. Does the ports scheme only work if you have everything in +/usr/ports? My system administrator says I must put everything under +/u/people/guests/wurzburger, but it doesn't seem to work. +

+A. You can use the PORTSDIR and PREFIX variables to tell the ports +mechanism to use different directories. For instance, - Some older versions of the system do not recognize the ``checksum'' -target. In that case, try the command - make check-md5 + PORTSDIR=/u/people/guests/wurzburger/ports make install -(``check-md5'' was the pre-cursor to the ``checksum'' target). If neither -work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from - +will compile the port in /u/people/guests/wurzburger/ports and install +everything under /usr/local. -and install them in /usr/share/mk. This will get you the latest version -of the ports system. + + PREFIX=/u/people/guests/wurzburger/local make install + + +will compile it in /usr/ports and install it in +/u/people/guests/wurzburger/local. + +And of course + + + PORTSDIR=.../ports PREFIX=.../local make install + + +will combine the two (it's too long to fit on the page if I write it +in full, but I'm sure you get the idea). +

+If you don't fancy typing all that in every time you install a port +(and to be honest, who would?), it's a good idea to put these variables +into your environment. + + +Q. I don't have a FreeBSD CDROM, but I'd like to have all the tarballs +handy on my system so I don't have to wait for a download every time I +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 + + + # cd /usr/ports + # make fetch + + +For all the tarballs for a single ports directory, do + + + # cd /usr/ports/directory + # make fetch + + +and for just one port - well, I think you've guessed already. + + +Q. I want to know what files make is going to need before it tries to +pull them down. +

+A. 'make fetch-list' will display a list of the files needed for a port. + + +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's a bit tiresome having +to watch it and hit control-C every time. +

+A. Doing 'make extract' will stop it after it has fetched and +extracted the source code. + + +Q. I'm trying to make my own port and I want to be able to stop it +compiling until I've had a chance to see if my patches worked properly. +Is there something like 'make extract', but for patches? +

+A. Yep, 'make patch' is what you want. And by the way, thank you for +your efforts! + + +Q. I've heard that some compiler options can cause bugs. Is this true? +How can I make sure that I compile ports with the right settings? +

+A. Yes, with version 2.6.3 of gcc (the version shipped with FreeBSD +2.1.0 and 2.1.5), the -O2 option could result in buggy code unless you +used the -fno-strength-reduce option as well. (Most of the ports don't +use -O2). You + # CFLAGS='-O2 -fno-strength-reduce' make install + + +or by editing /etc/make.conf, but this doesn't always seem to get +picked up. 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. + + +Q. There's so many ports it's hard to find the one I want. Is there a +list anywhere of what ports are available? +

+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? +

+A. The 'foo' port needs something that's supplied with 'bar' - for +instance, if 'foo' uses graphics, 'bar' might have a library with +useful graphics processing routines. Or 'bar' might be a tool that's +needed to compile the 'foo' port. + +

+A. No problem, just do + + + pkg_delete grizzle-6.5 + + + +Q. Hang on a minute, you have to know the version number to use that +command. You don't seriously expect me to remember that, do you?? +

+A. Not at all, you can find it out by doing + + + pkg_info -a | grep grizzle + + +And it'll tell you:- + + + Information for grizzle-6.5: + grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game. + + + +Q. Nope, that's still too complicated. +

+A. Do 'pkg_manage' to get a friendly front-end to the package manager. + + +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? +

+A. Yes, if you've installed the program and are fairly certain you +won't need the source again, there's no point in keeping it hanging +around. The best way to do this is + + + # cd /usr/ports + # make clean + + +which will go through all the ports subdirectories and delete +everything except the skeletons for each port. + +Q. I tried that and it still left all those tarballs or whatever you +called them in the distfiles directory. Can I delete those as well? +

+A. Yes, if you're sure you've finished with them, those can go as +well. + + +Q. I like having lots and lots of programs to play with. Is there any +way of installing all the ports in one go? +

+A. Just do + + + # cd /usr/ports + # make install + + + +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? +

+A. No, the problem is that some of the ports need to ask you questions +that we can't 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. + + +Q. I really don't want to spend all day staring at the monitor. Any +better ideas? +

+A. OK, do this before you go to bed/work/the local park:- + + + # cd /usr/ports + # make -DBATCH install + + +This will install every port that does + # cd /usr/ports + # make -DIS_INTERACTIVE install + + +to finish the job. + + +Q. At work, we're using frobble, which is in your ports collection, +but we've 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? +

+A. No problem, assuming you know how to make patches for your changes:- + + + # cd /usr/ports/somewhere/frobble + # make extract + # cd work/frobble-2.8 + [Apply your patches] + # cd ../.. + # make package + + + +Q. This ports stuff is really clever. I'm desperate to find out how +you did it. What's the secret? +

+A. Nothing secret about it at all, just look at the bsd.ports.mk and +bsd.ports.subdir.mk files in your +(Note: readers with an aversion to intricate shell-scripts are advised +not to follow this link...) + diff --git a/handbook/slips.sgml b/handbook/slips.sgml index 3156e98b46..df3dc8db4f 100644 --- a/handbook/slips.sgml +++ b/handbook/slips.sgml @@ -148,13 +148,18 @@ Internet RFC requirements for Internet hosts (see RFC's 1009 [Requirements for Internet Hosts -- Communication Layers], and perhaps 1127 [A Perspective on the Host Requirements RFCs]), so if you want your FreeBSD SLIP Server to act as a -router, you will have to add the line +router, you will have to edit the /etc/sysconfig file and change +the setting of the gateway variable to YES. If you +have an older system which does not have the /etc/sysconfig +file, then add the following command: -sysctl -w net.inet.ip.forwarding = 0 +sysctl -w net.inet.ip.forwarding = 1 -to your rc.local file. +to your /etc/rc.local file. -You will notice that near the end of the default kernel configuration +

You will then need to reboot for the new settings to take effect. + +

You will notice that near the end of the default kernel configuration file (/sys/i386/conf/GENERIC) is a line that reads: