From 40d7f193e5b19690973144246bad88d62cdfb71d Mon Sep 17 00:00:00 2001 From: Dru Lavigne Date: Wed, 30 Jan 2013 14:39:04 +0000 Subject: [PATCH] This patch addresses the following: - fixes missing &os; entities - fixes most redundancy--this required general rewording and tightening - more general tightening and rewording to remove most instances of "you" - a few title fixes - imake section was removed as this is a ports maintainer issue which should not be an end-user problem - reword incorrect usage of pkg_install (this comes with pkgng, not traditional system) Approved by: bcr (mentor) --- .../books/handbook/ports/chapter.xml | 933 ++++++++---------- 1 file changed, 392 insertions(+), 541 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml index 9dba34d705..bc440fcdfc 100644 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml @@ -13,46 +13,43 @@ ports packages - FreeBSD is bundled with a rich collection of system tools as + &os; is bundled with a rich collection of system tools as part of the base system. However, there is only so much one can do before needing to install an additional third-party - application to get real work done. FreeBSD provides two - complementary technologies for installing third-party software - on your system: the FreeBSD Ports Collection (for installing - from source), and packages (for installing from pre-built - binaries). Either method may be used to install the newest - version of your favorite applications from local media or - straight off the network. + application to get real work done. &os; provides two + complementary technologies for installing third-party software: + the &os; Ports Collection (for installing from source), and + packages (for installing from pre-built binaries). Either + method may be used to install software from local media or + from the network. - After reading this chapter, you will know: + After reading this chapter, you will know how to: - How to install third-party binary software - packages. + Install third-party binary software packages. - How to build third-party software from source by using - the ports collection. + Build third-party software from source by using the + Ports Collection. - How to remove previously installed packages or - ports. + Remove previously installed packages or ports. - How to override the default values that the ports - collection uses. + Override the default values used by the Ports + Collection. - How to find the appropriate software package. + Find the appropriate software package. - How to upgrade your applications. + Upgrade installed software. @@ -60,9 +57,8 @@ Overview of Software Installation - If you have used a &unix; system before you will know that - the typical procedure for installing third-party software goes - something like this: + The typical steps for installing third-party software on a + &unix; system include: @@ -77,11 +73,10 @@ - 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. + Locate the documentation in + INSTALL, README + or some file in a doc/ subdirectory and + read up on how to install the software. @@ -96,59 +91,40 @@ - And that is only if everything goes well. If you are - installing a software package that was not deliberately ported - to FreeBSD you may even have to go in and edit the code to make - it work properly. + If you are installing a software package that was not + deliberately ported to &os; you may even have to go in and edit + the code to make it work properly. - 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: - packages and ports. At the time of writing, over &os.numports; - third-party applications have been made available in this - way. + &os; provides two technologies which perform these steps for + you. At the time of writing, over &os.numports; third-party + applications are available. - For any given application, the FreeBSD package for that - application is a single file which you must 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 command. + A &os; package contains pre-compiled copies of all the + commands for an application, as well as any configuration files + and documentation. A package can be manipulated with &os; + package management commands, such as &man.pkg.add.1;, + &man.pkg.delete.1;, and &man.pkg.info.1;. - A FreeBSD port for an application is a collection of files - designed to automate the process of compiling an application - from source code. + A &os; port is a collection of files designed to automate + the process of compiling an application from source code. The + files that comprise a port contain all the necessary information + to automatically download, extract, patch, compile, and install + the application. - Remember that there are a number of steps you would normally - carry 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 - automatically downloaded, extracted, patched, compiled, and - installed for you. - - In fact, the ports system can also be used to generate - packages which can later be manipulated with - pkg_add and the other package management - commands that will be introduced shortly. + The ports system can also be used to generate packages which + can be manipulated with the &os; package management + commands. Both packages and ports understand - dependencies. Suppose you want to install - an application that depends on a specific library being - installed. Both 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 automatically install the library first. + dependencies. If &man.pkg.add.1; or the + Ports Collection is used to install an application and a + dependent library is not already installed, the library will + automatically be installaed first. - Given that the two technologies are quite similar, you might - be wondering why FreeBSD bothers with both. Packages and ports - both have their own strengths, and which one you use will depend - on your own preference. + While the two technologies are quite similar, packages and + ports each have their own strengths. Select the technology that + meets your requirements for installing a particular + application. Package Benefits @@ -160,17 +136,17 @@ - Packages do not require any additional compilation. For - large applications, such as + Packages do not require compilation time. For large + applications, such as Mozilla, KDE, or GNOME this can be important, - particularly if you are on a slow system. + on a slow system. Packages do not require any understanding of the process - involved in compiling software on FreeBSD. + involved in compiling software on &os;. @@ -179,105 +155,89 @@ Packages are normally compiled with conservative - options, because they have to run on the maximum number of - systems. By installing from the port, you can tweak the - compilation options to (for example) generate code that is - specific to a Pentium 4 or Athlon processor. + options because they have to run on the maximum number of + systems. By compiling from the port, one can change the + compilation options. Some applications have compile-time options relating to - what they can and cannot do. For example, + which features are installed. For example, Apache can be configured with a - wide variety of different built-in options. By building - from the port you do not have to accept the default options, - and can set them yourself. + wide variety of different built-in options. In some cases, multiple packages will exist for the same application to specify certain settings. For example, Ghostscript is available as a ghostscript package and a ghostscript-nox11 package, depending on - whether or not you have installed an X11 server. This sort - of rough tweaking is possible with packages, but rapidly - becomes impossible if an application has more than one or - two different compile-time options. + whether or not Xorg is installed. + Creating multiple packages rapidly becomes impossible if an + application has more than one or two different compile-time + options. - The licensing conditions of some software distributions - forbid binary distribution. They must be distributed as - source code. + The licensing conditions of some software forbid binary + distribution. These must be distributed as source code + which must be compiled by the end-user. - Some people do not trust binary distributions. At least - with source code, you can (in theory) read through it and - look for potential problems yourself. + Some people do not trust binary distributions or prefer + to read through source code in order to look for potential + problems. If you have local patches, you will need the source in order to apply them. - - - Some people like having code around, so they can read it - if they get bored, hack it, borrow from it (license - permitting, of course), and so on. - To keep track of updated ports, subscribe to the &a.ports; and the &a.ports-bugs;. - Before installing any application, you should check Before installing any application, check for security issues - related to your application. - - You can also install - ports-mgmt/portaudit - which will automatically check all installed applications for - known vulnerabilities; a check will be also performed before - any port build. Meanwhile, you can use the command - portaudit -F -a after you have installed - some packages. + related to the application or install ports-mgmt/portaudit. Once + installed, type portaudit -F -a to check + all installed applications for known vulnerabilities - The remainder of this chapter will explain how to use - packages and ports to install and manage third-party software on - FreeBSD. + The remainder of this chapter explains how to use packages + and ports to install and manage third-party software on + &os;. - Finding Your Application + Finding Software - Before you can install any applications you need to know - what you want, and what the application is called. - - FreeBSD's list of available applications is growing all the - time. Fortunately, there are a number of ways to find what you - want: + &os;'s list of available applications is growing all the + time. There are a number of ways to find software to + install: - The FreeBSD web site maintains an up-to-date searchable + The &os; web site maintains an up-to-date searchable list of all the available applications, at http://www.FreeBSD.org/ports/. - 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. + The ports can be searched by application name or by + software category. FreshPorts - Dan Langille maintains FreshPorts, at . FreshPorts - tracks changes to the applications in the ports tree as they - happen, allows you to watch one or more - ports, and can send you email when they are updated. + Dan Langille maintains FreshPorts which + provides a comprehensive search utility and also tracks + changes to the applications in the Ports Collection. + Registered users can create a customized watch list in order + to receive an automated email when their watched ports are + updated. @@ -286,32 +246,21 @@ If you do not know the name of the application you want, try using a site like Freecode () to find an - application, then check back at the FreeBSD site to see if + application, then check back at the &os; site to see if the application has been ported yet. - If you know the exact name of the port, but just need to - find out which category it is in, you can use the - &man.whereis.1; command. Simply type + To find out which category a port is in, 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, as follows: + where file is the program to be + installed: &prompt.root; whereis lsof lsof: /usr/ports/sysutils/lsof - This tells us that lsof (a system - utility) can be found in the - /usr/ports/sysutils/lsof - directory. - - - - Additionally, you can use a simple &man.echo.1; - statement to find where a port exists in the ports tree. - For example: + Alternately, a &man.echo.1; statement can be + used: &prompt.root; echo /usr/ports/*/*lsof* /usr/ports/sysutils/lsof @@ -323,15 +272,15 @@ lsof: /usr/ports/sysutils/lsof - 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 - directory, run make search - name=program-name where - program-name is the name of the - program you want to find. For example, if you were looking - for lsof: + Another way to find software is by using the Ports + Collection's built-in search mechanism. To use + the search feature, cd to + /usr/ports then run make + search + name=program-name + where program-name is the name of + the software. For example,to search for + lsof: &prompt.root; cd /usr/ports &prompt.root; make search name=lsof @@ -343,18 +292,11 @@ Index: sysutils B-deps: R-deps: - The part of the output you want to pay particular - attention to is the Path: line, since that - tells you where to find the port. The other information - provided is not needed in order to install the port, so it - will not be covered here. + The Path: line indicates where to find + the port. - Alternatively, there is another search feature from - ports that achieves the same purpose but with less noise, - the quicksearch feature. This feature - accepts the same parameter as the search - feature. For example, searching for lsof - would return: + To receive less information, use the + quicksearch feature: &prompt.root; cd /usr/ports &prompt.root; make quicksearch name=lsof @@ -362,19 +304,18 @@ Port: lsof-4.87.a,7 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) - For more in-depth searching you can also use + For more in-depth searching, use make search key=string or make quicksearch key=string, where string is some text to search - for. This searches port names, comments, descriptions and - dependencies and can be used to find ports which relate to a - particular subject if you do not know the name of the - program you are looking for. + for. The text can be comments, descriptions or dependencies + in order to find ports which relate to a particular subject + when the name of the program is unknown. - In both of these cases (search - and quicksearch), the search string + When using (search and + quicksearch), the search string is case-insensitive. Searching for LSOF will yield the same results as searching for lsof. @@ -394,10 +335,10 @@ Info: Lists information about open files (similar to fstat(1)) - Using the Packages System + Using Binary Packages There are several different tools used to manage packages on - FreeBSD: + &os;: @@ -424,9 +365,8 @@ Info: Lists information about open files (similar to fstat(1)) pkg_add - You can use the &man.pkg.add.1; utility to install a - FreeBSD software package from a local file or from a server on - the network. + Use &man.pkg.add.1; to install a &os; binary package from + a local file or from a server on the network. Downloading a Package Manually and Installing It @@ -457,26 +397,22 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz &prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen> </example> - <para>If you do not have a source of local packages (such as a - FreeBSD CD-ROM set) then it will probably be easier to use the - <option>-r</option> option to &man.pkg.add.1;. This will - cause the utility to automatically determine the correct - object format and release and then fetch and install the - package from an FTP site.</para> + <para>If you do not have a source of local packages, such as a + &os; CD-ROM set, include <option>-r</option> with + &man.pkg.add.1;. This automatically determines the correct + object format and release, and then fetches and installs the + package from an FTP site without any further user + intervention.</para> <indexterm> <primary><command>pkg_add</command></primary> </indexterm> <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen> - <para>The example above would download the correct package and - add it without any further user intervention. If you want to - specify an alternative &os; Packages Mirror, instead of the - main distribution site, you have to set the - <envar>PACKAGESITE</envar> environment variable accordingly, - to override the default settings. &man.pkg.add.1; uses - &man.fetch.3; to download the files, which honors various - environment variables, including + <para>To specify an alternative &os; FTP mirror, specify the + mirror in the <envar>PACKAGESITE</envar> environment variable. + &man.pkg.add.1; uses &man.fetch.3; to download files, which + uses various environment variables, including <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and <envar>FTP_PASSWORD</envar>. You may need to set one or more of these if you are behind a firewall, or need to use an @@ -484,41 +420,32 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz Note that in the example above <literal>lsof</literal> is used instead of <literal>lsof-4.56.4</literal>. When the remote fetching feature is used, the version number of the package - must be removed. &man.pkg.add.1; will automatically fetch the - latest version of the application.</para> + must be removed.</para> <note> - <para>&man.pkg.add.1; will download the latest version of - your application if you are using &os.current; or - &os.stable;. If you run a -RELEASE version, it will grab - the version of the package that was built with your + <para>&man.pkg.add.1; will automatically download the latest + version of the application if you are using &os.current; or + &os.stable;. If you run a -RELEASE version, it instead + installs the version of the package that was built with that release. It is possible to change this behavior by - overriding <envar>PACKAGESITE</envar>. - For example, if you run a &os; 8.1-RELEASE - system, by default &man.pkg.add.1; will try to fetch - packages from + overriding <envar>PACKAGESITE</envar>. For example, on a + &os; 8.1-RELEASE system, by default &man.pkg.add.1; + will try to fetch packages from <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>. - If you want to force &man.pkg.add.1; to download - &os; 8-STABLE packages, set <envar>PACKAGESITE</envar> - to + To force &man.pkg.add.1; to download &os; 8-STABLE + packages, set <envar>PACKAGESITE</envar> to <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.</para> </note> <para>Package files are distributed in <filename>.tgz</filename> - and <filename>.tbz</filename> formats. You can find them at - <ulink + and <filename>.tbz</filename> formats. Packages are + available from <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>, - or on the FreeBSD CD-ROM distribution. Every CD on the - FreeBSD 4-CD set (and the PowerPak, etc.) contains packages in - the <filename>/packages</filename> directory. The layout of - the packages is similar to that of the - <filename>/usr/ports</filename> tree. Each category has its - own directory, and every package can be found within the - <filename>All</filename> directory.</para> - - <para>The directory structure of the package system matches the - ports layout; they work with each other to form the entire - package/port system.</para> + or the <filename>/packages</filename> directory of the &os; + DVD distribution. The layout of the packages is similar to + that of the <filename>/usr/ports</filename> tree. Each + category has its own directory, and every package can be found + within the <filename>All</filename> directory.</para> </sect2> <sect2> @@ -529,8 +456,8 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz <secondary>managing</secondary> </indexterm> - <para>&man.pkg.info.1; is a utility that lists and describes - the various packages installed.</para> + <para>&man.pkg.info.1; can be used to list and describe + installed packages:</para> <indexterm> <primary><command>pkg_info</command></primary> @@ -541,9 +468,9 @@ colordiff-1.0.13 A tool to colorize diff output docbook-1.2 Meta-port for the different versions of the DocBook DTD ...</screen> - <para>&man.pkg.version.1; is a utility that summarizes the - versions of all installed packages. It compares the package - version to the current version found in the ports tree.</para> + <para>&man.pkg.version.1; summarizes the versions of all + installed packages and compares the package version to the + current version found in the ports tree.</para> <indexterm> <primary><command>pkg_version</command></primary> @@ -576,22 +503,22 @@ docbook = <row> <entry><</entry> <entry>The installed version is older than the one - available in the ports tree.</entry> + available in the local ports tree.</entry> </row> <row> <entry>></entry><entry>The installed version is newer - than the one found in the local ports tree. (The - local ports tree is probably out of - date.)</entry> + than the one found in the local ports tree, meaning + that the local ports tree is probably out of + date.</entry> </row> <row> <entry>?</entry> <entry>The installed package cannot be found in the - ports index. (This can happen, for instance, if an - installed port is removed from the Ports Collection or - renamed.)</entry> + ports index. This can happen when an installed port + is removed from the Ports Collection or is + renamed.</entry> </row> <row> @@ -625,18 +552,17 @@ docbook = <secondary>deleting</secondary> </indexterm> - <para>To remove a previously installed software package, use the - &man.pkg.delete.1; utility.</para> + <para>To remove a previously installed software package, use + &man.pkg.delete.1;:</para> <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen> <para>Note that &man.pkg.delete.1; requires the full package name and number; the above command would not work if <replaceable>xchat</replaceable> was given instead of - <replaceable>xchat-1.7.1</replaceable>. It is, however, easy - to use &man.pkg.version.1; to find the version of the - installed package. You could instead simply use a - wildcard:</para> + <replaceable>xchat-1.7.1</replaceable>. Use + &man.pkg.version.1; to find the version of the + installed package, or use a wildcard:</para> <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen> @@ -647,10 +573,9 @@ docbook = <sect2> <title>Miscellaneous - All package information is stored within the - /var/db/pkg directory. The installed - file list and descriptions of each package can be found within - files in this directory. + All package information, including the file list and + descriptions of each installed package is stored within the + /var/db/pkg directory. @@ -659,11 +584,10 @@ docbook = Management pkgng is an improved replacement - for the traditional &os; pkg_install - package management tools, offering many features that make - dealing with binary packages faster and easier. The first - release of pkgng was in August, - 2012. + for the traditional &os; package management tools, offering + many features that make dealing with binary packages faster and + easier. The first release of pkgng + was in August, 2012. pkgng is not a replacement for port management tools like &prompt.root; man pkg-install - Obtaining Information about Installed Packages with + <title>Obtaining Information About Installed Packages with <application>pkgng</application> Information about the packages installed on a system can @@ -939,10 +863,10 @@ Deinstalling ca_root_nss-3.13.5... done Backing Up the <application>pkgng</application> Package Database - Unlike the pkg_install - package management system, pkgng - includes its own package database backup mechanism. To - manually back up the package database contents, run: + Unlike the traditional package management system, + pkgng includes its own package + database backup mechanism. To manually back up the package + database contents, run: &prompt.root; pkg backup -d pkgng.db @@ -1048,11 +972,10 @@ Deinstalling ca_root_nss-3.13.5... done Using the Ports Collection - The following sections provide basic instructions on using - the Ports Collection to install or remove programs from your - system. The detailed description of available - make targets and environment variables is - available in &man.ports.7;. + This section provides basic instructions on using the Ports + Collection to install or remove software. The detailed + description of available make targets and + environment variables is available in &man.ports.7;. As of mid 2012, the &os; Ports Project has migrated @@ -1072,7 +995,7 @@ Deinstalling ca_root_nss-3.13.5... done The Ports Collection is a set of Makefiles, patches, and description files stored in /usr/ports. This set of files - is used for building and installing applications on &os;. The + is used to compile and install applications on &os;. The instructions below show several methods of obtaining the Ports Collection if it was not installed during initial &os; setup. @@ -1312,75 +1235,57 @@ Deinstalling ca_root_nss-3.13.5... done installing - The first thing that should be explained when it comes to - the Ports Collection is what is actually meant by a - skeleton. In a nutshell, a port skeleton is a - minimal set of files that tell your FreeBSD system how to - cleanly compile and install a program. Each port skeleton + A port skeleton is a set of files that tell &os; system + how to compile and install a program. Each port skeleton includes: - A Makefile. The - Makefile contains various statements - that specify how the application should be compiled and - where it should be installed on your system. + Makefile: The + Makefile contains statements that + specify how the application should be compiled and where + its components should be installed. - A distinfo file. This file - contains information about the files that must be - downloaded to build the port, and their checksums - (using &man.sha256.1;), to - verify that files have not been corrupted during the - download. + distinfo: This file contains + information about the files that must be downloaded to + build the port, and their checksums (using + &man.sha256.1;), to verify that files have not been + corrupted during the download. - A files directory. This - directory contains patches to make the program compile and - install on your FreeBSD system. Patches are basically - small files that specify changes to particular files. - They are in plain text format, and basically say - Remove line 10 or Change line 26 to - this .... Patches are also known as - diffs because they are generated by the - &man.diff.1; program. - - This directory may also contain other files used to - build the port. + files/: This directory contains + any patches needed for the program to compile and install + on &os;. This directory may also contain other files used + to build the port. - A pkg-descr file. This is a more - detailed, often multiple-line, description of the - program. + pkg-descr: This file provides a + more detailed description of the program. - A pkg-plist file. This is a list + pkg-plist: This is a list of all the files that will be installed by the port. It also tells the ports system what files to remove upon deinstallation. - Some ports have other files, such as + Some ports include other files, such as pkg-message. The ports system uses these files to handle special situations. If you want more details - on these files, and on ports in general, check out the - FreeBSD + on these files, and on ports in general, refer to the + &os; Porter's Handbook. - The port includes instructions on how to build source - code, but does not include 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. The two methods for - installing a &os; port are described below. + The port does not include the actual source code, also + known as a distfile. Source code is distributed + in whatever manner the software author desires. The two + methods for installing a &os; port are described below. You must be logged in as root to @@ -1388,39 +1293,32 @@ Deinstalling ca_root_nss-3.13.5... done - Before installing any port, you should be sure to have - an up-to-date Ports Collection and you should check - for security - issues related to your port. - - A security vulnerabilities check can be automatically - done by portaudit before any new - application installation. This tool can be found in the - Ports Collection (ports-mgmt/portaudit). Consider - running portaudit -F before installing a - new port, to fetch the current vulnerabilities database. A - security audit and an update of the database will be - performed during the daily security system check. For more - information read the &man.portaudit.1; and &man.periodic.8; - manual pages. + Before compiling any port, be sure to have an + up-to-date Ports Collection and check for security + issues related to your port. If ports-mgmt/portaudit) is + installed, run portaudit -F before + installing a new port, to fetch the current vulnerabilities + database. A security audit and an update of the database + will be performed during the daily security system check. + For more information read the &man.portaudit.1; and + &man.periodic.8; manual pages. - The Ports Collection makes an assumption that you have a - working Internet connection. If you do not, you will need to - put a copy of the distfile into - /usr/ports/distfiles manually. + Using the Ports Collection assumes a working Internet + connection. Otherwise, manually obtain and place a copy of + the distfile into + /usr/ports/distfiles. - To begin, change to the directory for the port you want - to install: + To begin, change to the directory of the port to + be installed: &prompt.root; cd /usr/ports/sysutils/lsof - Once inside the lsof directory, you - will see the port 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: + To compile, or build, the port, type + make at the prompt. You should see + messages similar to the ones in this example: &prompt.root; make >> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. @@ -1442,11 +1340,9 @@ Deinstalling ca_root_nss-3.13.5... done ... &prompt.root; - 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 install: + Once the compile is complete, you are returned to the + prompt. The next step is to install the port using + make install: &prompt.root; make install ===> Installing for lsof-4.57 @@ -1461,18 +1357,18 @@ Deinstalling ca_root_nss-3.13.5... done increased privileges. &prompt.root; - Once you are returned to your prompt, you should be able - to run the application you just installed. Since - lsof is a program that runs with - increased privileges, a security warning is shown. During - the building and installation of ports, you should take heed - of any other warnings that may appear. + Once you are returned to the prompt, you should be able + to run the installed application. Since + lsof is a program that runs with increased + privileges, a security warning is shown. During the building + and installation of ports, take heed of any other warnings + that may appear. It is a good idea to delete the working subdirectory, which contains all the temporary files used during - compilation. Not only does it consume valuable disk space, - but it would also cause problems later when upgrading to the - newer version of the port. + compilation. Doing so saves disk space and minimizes the + chance of problems later when upgrading to the newer version + of the port. &prompt.root; make clean ===> Cleaning for lsof-4.57 @@ -1489,13 +1385,12 @@ Deinstalling ca_root_nss-3.13.5... done - When installing a port, using only + Using only make install - from the beginning means there will potentially be many + means there will potentially be many waiting periods between user interaction as the default - behaviour is to prompt the user for options. When there are - many dependencies, this sometimes makes building a single - port a huge hassle. To avoid this, first run make + behaviour is to prompt the user for options. To avoid this + when there are many dependencies, first run make config-recursive to do the configuration in one batch. Then run make install [clean] @@ -1519,32 +1414,30 @@ Deinstalling ca_root_nss-3.13.5... done available in the directories listed in the PATH environment variable, to speed up lookup operations for the executable file of these commands. If - you are using one of these shells, you might have to use the - rehash command after installing a port, - before the newly installed commands can be used. This - command will work for shells like tcsh. - Use the hash -r command for shells like - sh. Look at the documentation for your - shell for more information. + you are using tcsh, you might have to + type rehash so that a newly installed + command can be used without specifying its full path. Use + hash -r instead for the + sh shell. Refer to the documentation for + the shell for more information. - Some third-party DVD-ROM products such as the FreeBSD - Toolkit from the - FreeBSD Mall - contain distfiles. They can be used with the Ports - Collection. Mount the DVD-ROM on /cdrom. - If you use a different mount point, set - CD_MOUNTPTS make variable. The needed - distfiles will be automatically used if they are present on - the disk. + Some third-party DVD products such as the &os; + Toolkit from the &os; + Mall contain distfiles. They can be used with the + Ports Collection. Mount the DVD on + /cdrom. If you use a different mount + point, set CD_MOUNTPTS make variable. The + needed distfiles will be automatically used if they are + present on the disk. - Please be aware that the licenses of a few ports do - not allow for inclusion on the CD-ROM. This could be - because a registration form needs 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. + The licenses of a few ports do not allow their inclusion + on the DVD. This could be because a registration form + needs to be filled out before downloading or redistribution + is not allowed. If you wish to install a port not included + on the DVD, you will need to be connected to the + Internet. The ports system uses &man.fetch.1; to download the @@ -1557,31 +1450,29 @@ Deinstalling ca_root_nss-3.13.5... done For users which cannot be connected all the time, the make fetch option - is provided. Just run this command at the top level directory - (/usr/ports) and the required files will - be downloaded for you. This command will also work in the - lower level categories, for example: + is provided. Run this command within + /usr/ports and the required files will + be downloaded. This command also works in the + lower level categories, such as /usr/ports/net. Note that if a port - depends on libraries or other ports this will - not fetch the distfiles of those ports - too. Replace fetch with - fetch-recursive if you want to fetch - all the dependencies of a port too. + depends on libraries or other ports, this will + not fetch the distfiles of ports + from another category. Use + makefetch-recursive + fetch to fetch + all the dependencies of a port. You can build all the ports in a category or as a whole by running make in the top level - directory, just like the aforementioned make - fetch method. This is - dangerous, however, as some ports cannot co-exist. In other - cases, some ports can install two different files with the - same filename. + directory. This is dangerous, however, as some ports cannot + co-exist. In other cases, some ports can install two + different files with the same filename. In some rare cases, users may need to acquire the - tarballs from a site other than the - MASTER_SITES (the location where files are - downloaded from). You can override the + tarballs from a site other than the default + MASTER_SITES. You can override the MASTER_SITES option with the following command: @@ -1589,30 +1480,28 @@ Deinstalling ca_root_nss-3.13.5... done &prompt.root; make MASTER_SITE_OVERRIDE= \ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - In this example we change the - MASTER_SITES option to In this example, MASTER_SITES is + changed to ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/. - Some ports allow (or even require) you to provide build - options which can enable/disable parts of the application - which are unneeded, certain security options, and other - customizations. A few which come to mind are + Some ports provide build options which can be used to + enable/disable parts of the application which are unneeded, + provide security options, or allow for other customizations. + Examples include www/firefox, security/gpgme, and mail/sylpheed-claws. A - message will be displayed when options such as these are - available. + menu will be displayed at the beginning of a port + compile when compile options are available. Overriding the Default Ports Directories - Sometimes it is useful (or mandatory) to use a different - working and target directory. The - WRKDIRPREFIX and + The WRKDIRPREFIX and PREFIX variables can override the default - directories. For example: + working and target directories. For example: &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install @@ -1622,52 +1511,35 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch &prompt.root; make PREFIX=/usr/home/example/local install - will compile it in /usr/ports and - install it in + will compile the port in /usr/ports + and install it in /usr/home/example/local. - And of course, + And &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install - will combine the two (it is too long to completely write - on this page, but it should give you the general - idea). + will combine the two. - Alternatively, these variables can also be set as part - of your environment. Read the manual page for your shell - for instructions on doing so. - - - - Dealing with <command>imake</command> - - Some ports that use imake (a part of - the X Window System) do not work well with - PREFIX, and will insist on installing - under /usr/X11R6. Similarly, some Perl - ports ignore PREFIX and install in the - Perl tree. Making these ports respect - PREFIX is a difficult or impossible - job. + Alternatively, these can be set as environmental + variables. Refer to the manual page for your shell + for instructions on how to set an environmental + variable. Reconfiguring Ports - When building certain ports, you may be presented with a - ncurses-based menu from which you can select certain build - options. It is not uncommon for users to wish to revisit - this menu to add, remove, or change these options after a - port has been built. There are many ways to do this. One - option is to go into the directory containing the port and - type - make config, - which will simply present the menu again with the same - options selected. Another option is to use - make showconfig, - which will show you all the configuration options for the - port. Yet another option is to execute + Certain ports provide an ncurses-based menu containing + build options. There are several ways to revisit this menu + in order to add, remove, or change these options after a + port has been built. One method is to + cd into the directory containing the + port and type + make config. + Another option is to use + make showconfig. + Another option is to execute make rmconfig which will remove all selected options and allow you to start over. All of these options, and others, are explained @@ -1683,13 +1555,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch removing - 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 decide that you installed the wrong port. We will - remove our previous example (which was lsof - for those of you not paying attention). Ports are being - removed exactly the same as the packages (discussed in the - Packages section), using + Installed ports and packages are uninstalled using the &man.pkg.delete.1; command: &prompt.root; pkg_delete lsof-4.57 @@ -1737,40 +1603,38 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch designed to easily upgrade installed ports. It is available from the ports-mgmt/portupgrade - port. Install it like any other port, using the + port. Install it like any other port, using make install - clean command: + clean: &prompt.root; cd /usr/ports/ports-mgmt/portupgrade &prompt.root; make install clean - Scan the list of installed ports with the - pkgdb -F command and fix all the - inconsistencies it reports. It is a good idea to do this - regularly, before every upgrade. + Scan the list of installed ports using + pkgdb -F and fix all the inconsistencies + it reports. It is a good idea to do this regularly, before + every upgrade. - When you run portupgrade -a, - portupgrade will begin to upgrade - all the outdated ports installed on your system. Use the - flag if you want to be asked for - confirmation of every individual upgrade. + Use portupgrade -a to upgrade all the + outdated ports installed on the system. Include + to be asked for confirmation of every + individual upgrade. &prompt.root; portupgrade -ai - If you want to upgrade only a certain application, not - all available ports, use portupgrade - pkgname. Include the - flag if - portupgrade should first upgrade - all the ports required by the given application. + To upgrade only a specified application instead of all + available ports, use portupgrade + pkgname. Include + to first upgrade all the ports required + by the given application. &prompt.root; portupgrade -R firefox - To use packages instead of ports for installation, - provide flag. With this option + To use packages instead of ports, include the + flag. With this option, portupgrade searches the local - directories listed in PKG_PATH, or fetches - packages from remote site if it is not found locally. If + directories listed in PKG_PATH, then fetches + packages from a remote site if not found locally. If packages can not be found locally or fetched remotely, portupgrade will use ports. To avoid using ports, specify . @@ -1784,20 +1648,21 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - Upgrading Ports Using Portmaster + Upgrading Ports Using + <application>portmaster</application> portmaster - Portmaster is another utility - for upgrading installed ports. - Portmaster was designed make use - of the tools found in the base system (it - does not depend upon other ports) and uses the information + ports-mgmt/portmaster is another + utility for upgrading installed ports. + portmaster was designed to + use the tools found in the base system + without depending upon other ports. It uses the information in /var/db/pkg/ to - determine which ports to upgrade. It is available from the - ports-mgmt/portmaster + determine which ports to upgrade. To install the port: &prompt.root; cd /usr/ports/ports-mgmt/portmaster @@ -1808,27 +1673,28 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - Root ports (no dependencies, not depended on) + Root ports: no dependencies and is not depended on + by other ports - Trunk ports (no dependencies, are depended - on) + Trunk ports: no dependencies, but other ports depend + upon it - Branch ports (have dependencies, are depended - on) + Branch ports: have dependencies and are depended + upon by other ports - Leaf ports (have dependencies, not depended - on) + Leaf ports: have dependencies but are not depended + upon by other ports - You can list all the installed ports and search - for updates using the option: + To list all installed software and search for updates, + use : &prompt.root; portmaster -L ===>>> Root ports (No dependencies, not depended on) @@ -1853,38 +1719,36 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch ===>>> 83 have new versions available All the installed ports can be upgraded using this - simple command: + command: &prompt.root; portmaster -a - By default, Portmaster will + By default, portmaster will make a backup package before deleting the existing port. If the installation of the new version is successful, - Portmaster will delete the - backup. Using the will instruct - Portmaster not to automatically - delete the backup. Adding the option - will start Portmaster in - interactive mode, prompting you before upgrading each + portmaster will delete the + backup. Using will instruct + portmaster not to automatically + delete the backup. Adding will start + portmaster in interactive mode, + prompting for confirmation before upgrading each port. - If you encounter errors during the upgrade process, you - can use the option to upgrade/rebuild - all ports: + If you encounter errors during the upgrade process, use + to upgrade/rebuild all ports: &prompt.root; portmaster -af - You can also use Portmaster + You can also use portmaster to install new ports on the system, upgrading all dependencies before building and installing the new port: &prompt.root; portmaster shells/bash - Please see &man.portmaster.8; for more - information. + Refer to &man.portmaster.8; for more information. @@ -1897,25 +1761,22 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch Using the Ports Collection will use up disk space over - time. After building and installing software from the ports, - you should always remember to clean up the temporary - work directories using - the make clean - command. You can sweep the whole Ports Collection with the - following command: + time. After building and installing a port, make + clean will clean up the + temporary work + directory. To sweep the whole Ports Collection: &prompt.root; portsclean -C - You will accumulate a lot of old source distribution files - in the distfiles - directory over time. You can remove them by hand, or you can - use the following command to delete all the distfiles that are + A lot of out-dated source distribution files will collect + in distfiles over time. + The following command will delete all the distfiles that are no longer referenced by any ports: &prompt.root; portsclean -D - Or to remove all distfiles not referenced by any port - currently installed on your system: + To remove all distfiles not referenced by any port + currently installed on the system: &prompt.root; portsclean -DD @@ -1924,10 +1785,11 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch portupgrade suite. - Do not forget to remove the installed ports once you no - longer need them. A nice tool to help automate this task is - available from the - ports-mgmt/pkg_cutleaves + ports-mgmt/pkg_cutleaves automates + the task of removing installed ports that are no longer + needed. + port. @@ -1937,9 +1799,8 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch After installing a new application you will normally want to read any documentation it may have included, edit any - configuration files that are required, ensure that the - application starts at boot time (if it is a daemon), and so - on. + required configuration files, and ensure that the + application's service starts at boot time. The exact steps you need to take to configure each application will obviously be different. However, if you have @@ -1955,28 +1816,28 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch &prompt.root; pkg_info -L foopackage-1.0.0 | less will show all the files installed by the package. Pay - special attention to files in man/ - directories, which will be manual pages, - etc/ directories, which will be - configuration files, and doc/, which - will be more comprehensive documentation. + special attention to files located in + man/, which will be manual pages, + etc/, which will be configuration + files, and doc/, which will be more + comprehensive documentation. - If you are not sure which version of the application was - just installed, a command like this + To determine which version of the application was + installed: &prompt.root; pkg_info | grep -i foopackage will find all the installed packages that have foopackage in the package name. - Replace foopackage in your - command line as necessary. + Replace foopackage as + necessary. Once you have identified where the application's manual pages have been installed, review them using &man.man.1;. - Similarly, look over the sample configuration files, and any - additional documentation that may have been provided. + Review the sample configuration files and any additional + documentation that may have been provided. @@ -1992,10 +1853,9 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - Ports that should start at boot (such as Internet - servers) will usually install a sample script in - /usr/local/etc/rc.d. You should - review this script for correctness and edit or rename it if + Ports that should start at boot time usually install a + startup script in /usr/local/etc/rc.d. + Review this script for correctness and edit or rename it if needed. See Starting Services for more information. @@ -2006,8 +1866,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch Dealing with Broken Ports - If you come across a port that does not work for you, - there are a few things you can do, including: + If you come across a port that does not compile: @@ -2023,7 +1882,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch or read the Makefile to find the maintainer's email address. Remember to include the name and version of the port (send the - $FreeBSD: line from the + $&os;: line from the Makefile) and the output leading up to the error when you email the maintainer. @@ -2044,10 +1903,10 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch mailing list. More volunteers are always needed! - If you do not get a response, you can use - &man.send-pr.1; to submit a bug report (see If you do not get a response, use &man.send-pr.1; to + submit a bug report (see Writing - FreeBSD Problem Reports). + &os; Problem Reports). @@ -2059,16 +1918,8 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - Grab the package from an FTP site near you. The - master package collection is on ftp.FreeBSD.org in the packages - directory, but be sure to check your closer mirror sites - first! These are more likely to work - than trying to compile from source and are a lot faster as - well. Use the &man.pkg.add.1; program to install the - package on your system. + Use &man.pkg.add.1; program to instead install the + package.