From pepper@guest.reppep.com Sun Jun 9 20:58:21 2002 Return-Path: Received: from guest.reppep.com (guest.reppep.com [64.81.19.110]) by hub.freebsd.org (Postfix) with ESMTP id E555F37B404 for ; Sun, 9 Jun 2002 20:58:18 -0700 (PDT) Received: (from pepper@localhost) by guest.reppep.com (8.11.6/8.11.6) id g5A3wSB44445; Sun, 9 Jun 2002 23:58:28 -0400 (EDT) (envelope-from pepper) Message-Id: <200206100358.g5A3wSB44445@guest.reppep.com> Date: Sun, 9 Jun 2002 23:58:28 -0400 (EDT) From: Chris Pepper Reply-To: Chris Pepper To: FreeBSD-gnats-submit@freebsd.org Cc: Subject: Various tweaks to doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml X-Send-Pr-Version: 3.113 X-GNATS-Notify: >Number: 39084 >Category: docs >Synopsis: Various tweaks to doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: closed >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sun Jun 09 21:00:05 PDT 2002 >Closed-Date: Thu Oct 03 17:35:04 PDT 2002 >Last-Modified: Thu Oct 03 17:35:04 PDT 2002 >Originator: Chris Pepper >Release: FreeBSD 4.6-RC i386 >Organization: >Environment: System: FreeBSD guest.reppep.com 4.6-RC FreeBSD 4.6-RC #0: Fri Jun 7 21:51:10 EDT 2002 root@guest.reppep.com:/usr/obj/usr/src/sys/GENERIC i386 >Description: >How-To-Repeat: >Fix: Various textual tweaks & cleanups. Mention INSTALL files. Point out that ports & packages are related earlier in the text. Replace "name space" reference, not meaningful to new users. Replace "CDROM" with "CD-ROM". Move pkg_delete after pkg_info, since pkg_info is required to find the full pkg name for pkg_delete (wildcards are not mentioned yet at this point). Fill out checksum explanation. Separately, suggested removing & redownloading Mention that distfile can be grabbed manually. Clarified that make continues after satisfying dependencies. Question: says Kermit's distfile would be on the CD, but "4.5.2.1 Installing Ports from a CD-ROM" seems to say that distfiles wouldn't be on the CD-ROM anyway. Should this be removed or reworded? "The FreeBSD Project's official CD-ROM images no longer include distfiles. They take up a lot of room that is better used for precompiled packages. CD-ROM products such as the FreeBSD PowerPak do include distfiles, and you can order these sets from a vendor such as the FreeBSD Mall. This section assumes you have such a FreeBSD CD-ROM set." --- chapter.sgml.diff begins here --- Index: chapter.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml,v retrieving revision 1.167 diff -u -r1.167 chapter.sgml --- chapter.sgml 2002/06/09 10:47:41 1.167 +++ chapter.sgml 2002/06/10 03:10:17 @@ -57,7 +57,7 @@ - Locate the documentation (perhaps a README + Locate the documentation (perhaps an INSTALL or README file, or some files in a doc/ subdirectory) and read up on how to install the software. @@ -79,19 +79,19 @@ Should you want to, you can continue to install software the traditional way with FreeBSD. However, FreeBSD - provides two technologies which can save you a lot of effort; + provides two related technologies which can save you a lot of effort: packages and ports. At the time of writing, over &os.numports; third party applications have been made available in this way. For any given application, the FreeBSD package for that application - is a single file which you must download. The package contains + is a single file which you may download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with FreeBSD package management commands, such as &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on. - Installing a new application can be carried out with a single + Installing a new application can be carried out with a single &man.pkg.add.1; command. A FreeBSD port for an application is a collection of files designed @@ -99,7 +99,7 @@ code. Remember that there are a number of steps you would normally carry - out if you compiled a program yourself (unpacking, patching, compiling, + out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a port contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is @@ -117,7 +117,7 @@ the application and the library have been made available as FreeBSD ports and packages. If you use the pkg_add command or the ports system to add the application, both will notice that the - library has not been installed, and the commands will install the + library has not been installed, and automatically install the library first. Given that the two technologies are quite similar, you might be @@ -221,8 +221,8 @@ The FreeBSD web site maintains an up-to-date searchable list of all the available applications, at http://www.FreeBSD.org/ports/. - The name space is divided into categories, and you may either - search for an application by name (if you know it), or you can list + The ports are divided into categories, and you may either + search for an application by name (if you know it), or see all the applications available in a category. @@ -232,8 +232,8 @@ Dan Langille maintains FreshPorts, at http://www.FreshPorts.org/. FreshPorts tracks changes to the applications in the ports tree as - they happen, and allows you to watch one or more - ports, and will send you an email when they are updated. + they happen, allows you to watch one or more + ports, and can send you email when they are updated. FreshMeat @@ -277,7 +277,7 @@ the network. - Downloading a Package and then Installing It Locally + Downloading a Package Manually and then Installing It Locally &prompt.root; ftp -a ftp2.FreeBSD.org Connected to ftp2.FreeBSD.org. @@ -305,10 +305,10 @@ If you do not have a source of local packages (such as a - FreeBSD CDROM set) then it will probably be easier to use the + FreeBSD CD-ROM set) then it will probably be easier to use the option to &man.pkg.add.1;. This will cause the utility to automatically determine the correct object format and release - and then to fetch and install the package from an FTP site. + and then fetch and install the package from an FTP site. @@ -322,8 +322,8 @@ find them at ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/, - or on the FreeBSD CDROM distribution. Every CD on the - FreeBSD 4-CD set (and PowerPak, etc) contains packages in + or on the FreeBSD CD-ROM distribution. Every CD on the + FreeBSD 4-CD set (and the PowerPak, etc.) contains packages in the /packages directory. The layout of the packages is similar to that of the /usr/ports tree. Each category has its @@ -331,30 +331,14 @@ All directory. - The directory structure of the package system is identical - to that of the ports; they work with each other to form the entire + The directory structure of the package system matches + the ports layout; they work with each other to form the entire package/port system. - Deleting a Package - - pkg_delete - - - packages - deleting - - To remove a previously installed software package, use the - &man.pkg.delete.1; utility. - - - &prompt.root; pkg_delete xchat-1.7.1 - - - Managing Packages @@ -425,6 +409,22 @@ + Deleting a Package + + pkg_delete + + + packages + deleting + + To remove a previously installed software package, use the + &man.pkg.delete.1; utility. + + + &prompt.root; pkg_delete xchat-1.7.1 + + + Miscellaneous All package information is stored within the /var/db/pkg directory. The installed @@ -471,27 +471,27 @@ Scroll down and select Configure, - press Enter. + then press Enter. Scroll down and select - Distributions, press Enter. + Distributions, then press Enter. - Scroll down to ports, press + Scroll down to ports, then press Space. - Scroll up to Exit, press + Scroll up to Exit, then press Enter. - Select your desired installation media, such as CDROM, - FTP, and so on. + Select your desired installation media, such as CD-ROM, + FTP, or something else. @@ -506,12 +506,12 @@ /usr/share/examples/cvsup/ports-supfile. See Using CVSup () for more information on using - CVSup and the mentioned file. + CVSup and this file. CVSup Method - This is a quick method to getting the ports collection + This is a quick method for getting the ports collection using CVSup. If you want to keep your ports tree up to date, or learn more about CVSup, read the previously @@ -536,7 +536,7 @@ Change CHANGE_THIS.FreeBSD.org to a - CVSup near you. See CVSup server near you. See CVSup Mirrors () for a complete listing of mirror sites. @@ -549,9 +549,9 @@ - Running this consequent times at later dates will - download all the recent changes to your ports - collection. + Running this command later will + download and apply all the recent changes to your ports + collection, except actually rebuilding the ports for your own system. @@ -580,7 +580,7 @@ A distinfo file. This file contains information about the files that must be downloaded to build the - port, and checksums, to ensure that those files have not been + port and their checksums, to verify that files have not been corrupted during the download. @@ -594,7 +594,7 @@ known as diffs because they are generated by the diff program. - This directory may also contain other files used in building + This directory may also contain other files used to build the port. @@ -627,7 +627,7 @@ first port. There are two ways this can be done, and each is explained below. - Before we get into that however, you will need to choose a + Before we get into that, however, you will need to choose a port to install. There are a few ways to do this, with the easiest method being the ports listing on the FreeBSD @@ -640,7 +640,7 @@ command. Simply type whereis file, where file is the program you want to install. If it is found on - your system, you will be told where it is, like so: + your system, you will be told where it is, as follows: &prompt.root; whereis lsof lsof: /usr/ports/sysutils/lsof @@ -649,7 +649,7 @@ can be found in the /usr/ports/sysutils/lsof directory. - Yet another way of finding a particular port is by using the + Yet another way to find a particular port is by using the ports collection's built-in search mechanism. To use the search feature, you will need to be in the /usr/ports directory. Once in that @@ -670,8 +670,8 @@ The part of the output you want to pay particular attention to is the Path: line, since that tells you where to - find it. The other information provided is not needed in order - to install the port directly, so it will not be covered + find the port. The other information provided is not needed in order + to install the port, so it will not be covered here. For more in-depth searching you can also use @@ -686,39 +686,39 @@ searching for lsof. - You must be the root user to install + You must be logged in as root to install ports. Now that you have found a port you would like to install, you are ready to do the actual installation. The port - includes instructions on how to build source code, but no - actual source code. You can get the source code from a CDROM + includes instructions on how to build source code, but not the + actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a distfile. You can get the distfile from a - CDROM or from the Internet. + CD-ROM or from the Internet. - Installing Ports from a CDROM + Installing Ports from a CD-ROM ports - installing from CDROM + installing from CD-ROM - The FreeBSD Project's official CDROM images no longer + The FreeBSD Project's official CD-ROM images no longer include distfiles. They take up a lot of room that is - better used by precompiled packages. CDROM products such as + better used for precompiled packages. CD-ROM products such as the FreeBSD PowerPak do include distfiles, and you can order these sets from a vendor such as the FreeBSD Mall. - This section assumes you have such a FreeBSD CDROM + This section assumes you have such a FreeBSD CD-ROM set. - Place your FreeBSD CDROM in the drive. Mount it on + Place your FreeBSD CD-ROM in the drive. Mount it on /cdrom. (If you use a different mount point, the install will not work.) To begin, change to the directory for the port you want to install: @@ -727,7 +727,7 @@ Once inside the lsof directory, you will see the port - skeleton. The next step is to compile (also called build) the + skeleton. The next step is to compile, or build, the port. This is done by simply typing make at the prompt. Once you have done so, you should see something like this: @@ -752,7 +752,7 @@ ... &prompt.root; - Take notice that once the compile is complete you are + Notice that once the compile is complete you are returned to your prompt. The next step is to install the port. In order to install it, you simply need to tack one word onto the make command, and that word is @@ -787,11 +787,11 @@ Please be aware that the licenses of a few ports do not - allow for inclusion on the CDROM. This could be because a + allow for inclusion on the CD-ROM. This could be because a registration form needs - to be filled out before downloading, redistribution is not - allowed, and so on. If you wish to install a port not - included on the CDROM, you will need to be online in order to + to be filled out before downloading or redistribution is not + allowed, or for another reason. If you wish to install a port not + included on the CD-ROM, you will need to be online in order to do so (see the next section). @@ -802,14 +802,14 @@ As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, - you will need to perform the CDROM - installation. + you will need to perform the CD-ROM + installation, or put a copy of the distfile into /usr/ports/distfiles manually. Installing a port from the Internet is done exactly the same - way as it would be if you were installing from a CDROM. The - only difference between the two is that the port distfile - is downloaded from the Internet instead of pulled from the - CDROM. + way as it would be if you were installing from a CD-ROM. The + only difference between the two is that the distfile + is downloaded from the Internet instead of read from the + CD-ROM. The steps involved are identical: @@ -863,7 +863,7 @@ Now that you know how to install ports, you are probably wondering how to remove them, just in case you install one and - later on you decide that you installed the wrong port. + later on decide that you installed the wrong port. We will remove our previous example (which was lsof for those of you not paying attention). As with installing ports, @@ -908,7 +908,7 @@ Use &man.pkg.info.1; to find out which files were installed, - and where they were installed to. For example, if you have just + and where. For example, if you have just installed FooPackage version 1.0.0, then this command &prompt.root; pkg_info -L foopackage-1.0.0 | less @@ -926,7 +926,7 @@ will find all the installed packages that have foopackage in the package name. Replace - foopackage in your commandline as + foopackage in your command line as necessary. @@ -939,14 +939,14 @@ If the application has a web site, check it for additional - documentation, frequently asked question files, and so forth. If + documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from &prompt.root; pkg_info foopackage-1.0.0 - will often include a WWW: line with the URL - of the application's web site. + A WWW: line, if present, should provide a URL + for the application's web site. @@ -973,7 +973,7 @@ Ah, you must be thinking of the serial ports on the back of your computer. We are using port here to mean the result of porting a program from one - version of Unix to another. + operating system to another. @@ -986,7 +986,7 @@ 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 delete line 23, - add these two lines after line 468, or + add these two lines after line 468, and change line 197 to this. They are also known as diffs because they are generated by the diff program. @@ -1001,21 +1001,20 @@ - It is a file ending in .tar, or - with variations such as .tar.gz, + A tarball is a file, with a name generally ending in .tar, .tar.gz, .tar.Z, .tar.bz2, - and even .tgz. + or even .tgz. - Basically, it is a directory tree that has been archived + Basically, a tarball is a directory tree that has been archived into a single file (.tar) and - optionally compressed (.gz). This + optionally compressed (.gz, .Z, or .bz2). This technique was originally used for Tape ARchives (hence the name - tar), but it is a widely used way of + tar), but it is a common way of distributing program source code around the Internet. - You can see what files are in them, or even extract - them yourself by using the standard Unix + You can see what files are in tarballs, or even extract + the contents yourself, by using the standard Unix tar program, which comes with the base FreeBSD system, like this: @@ -1029,7 +1028,7 @@ checksum - And a checksum? + And checksums? @@ -1038,12 +1037,18 @@ change, the checksum will no longer be equal to the total, so a simple comparison will allow you to spot the difference. + + If a stored checksum matches the checksum calculated + for a file, such as a tarball, the file matches the + original for which the checksum was calculated. If there's + a discrepancy, there's a problem, such as file corruption; + removing the tarball and redownloading may fix the problem. - I did what you said for compiling ports from a CDROM and + I did what you said for compiling ports from a CD-ROM and it worked great until I tried to install the kermit port. @@ -1051,21 +1056,21 @@ >> cku190.tar.gz doesn't seem to exist on this system. >> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. - Why can it not be found? Have I got a dud CDROM? + Why can it not be found? Have I got a dud CD-ROM? As explained in the compiling ports from CDROM - section, some ports cannot be put on the CDROM set + linkend="ports-cd">compiling ports from CD-ROM + section, some distfiles cannot be put on the CD-ROM set due to licensing restrictions. Kermit is an example of that. The licensing terms for kermit do not allow us to put - the tarball for it on the CDROM, so you will have to fetch + the tarball for it on the CD-ROM, so you will have to fetch it by hand—sorry! The reason why you got all those error messages was because you were not connected to the Internet at the time. - Once you have downloaded it from any of the MASTER_SITES + Once you have downloaded the distfile from any of the MASTER_SITES (listed in the Makefile), you can restart the install process. @@ -1082,7 +1087,7 @@ The ports mechanism will download distribution tarballs into /usr/ports/distfiles, but many system administrators will symlink this directory - to a remote file server or local read-only CDROM media. + 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: @@ -1136,7 +1141,7 @@ job. If you do not fancy typing all that in every time you - install a port, it is a good idea to put these variables + install a port, you can put these variables into your environment. Read the manual page for your shell for instructions on doing so. @@ -1144,7 +1149,7 @@ - I do not have a FreeBSD CDROM, but I would like to have + 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? @@ -1248,7 +1253,7 @@ unless you used the option as well. (Most of the ports do not use ). You should be - able to specify the compiler options used by something + able to specify compiler options with something like: &prompt.root; make CFLAGS='-O2 -fno-strength-reduce' install @@ -1258,7 +1263,7 @@ 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. + sub-directories, each with its own Makefile. The default FreeBSD compiler options are quite conservative, so if you have not changed them you should not have any @@ -1287,7 +1292,7 @@ - I went to install the foo port but + I tried to install the foo port but the system suddenly stopped compiling it and starting compiling the bar port. What is going on? @@ -1300,7 +1305,7 @@ bar might have a library with useful graphics processing routines. Or bar might be a tool that is needed to compile the - foo port. + foo port. Once bar is finished, your system should automatically resume building foo. @@ -1340,7 +1345,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game. - The version number can also be found using the + The version number can also be found using pkg_info or by typing: ls /var/db/pkg @@ -1349,7 +1354,7 @@ - Talking of disk space, the ports directory seems to be + 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? --- chapter.sgml.diff ends here --- >Release-Note: >Audit-Trail: State-Changed-From-To: open->closed State-Changed-By: trhodes State-Changed-When: Thu Oct 3 17:34:24 PDT 2002 State-Changed-Why: I've merged almost all of the patch fixes. The failed 8 hunks will go in here soon. Thanks for the submission! http://www.freebsd.org/cgi/query-pr.cgi?pr=39084 >Unformatted: