Date: Wed, 30 Jan 2013 14:39:04 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40822 - head/en_US.ISO8859-1/books/handbook/ports Message-ID: <201301301439.r0UEd4ZH068102@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Wed Jan 30 14:39:04 2013 New Revision: 40822 URL: http://svnweb.freebsd.org/changeset/doc/40822 Log: 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) Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Wed Jan 30 14:36:55 2013 (r40821) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Wed Jan 30 14:39:04 2013 (r40822) @@ -13,46 +13,43 @@ <indexterm><primary>ports</primary></indexterm> <indexterm><primary>packages</primary></indexterm> - <para>FreeBSD is bundled with a rich collection of system tools as + <para>&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.</para> + 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.</para> - <para>After reading this chapter, you will know:</para> + <para>After reading this chapter, you will know how to:</para> <itemizedlist> <listitem> - <para>How to install third-party binary software - packages.</para> + <para>Install third-party binary software packages.</para> </listitem> <listitem> - <para>How to build third-party software from source by using - the ports collection.</para> + <para>Build third-party software from source by using the + Ports Collection.</para> </listitem> <listitem> - <para>How to remove previously installed packages or - ports.</para> + <para>Remove previously installed packages or ports.</para> </listitem> <listitem> - <para>How to override the default values that the ports - collection uses.</para> + <para>Override the default values used by the Ports + Collection.</para> </listitem> <listitem> - <para>How to find the appropriate software package.</para> + <para>Find the appropriate software package.</para> </listitem> <listitem> - <para>How to upgrade your applications.</para> + <para>Upgrade installed software.</para> </listitem> </itemizedlist> </sect1> @@ -60,9 +57,8 @@ <sect1 id="ports-overview"> <title>Overview of Software Installation</title> - <para>If you have used a &unix; system before you will know that - the typical procedure for installing third-party software goes - something like this:</para> + <para>The typical steps for installing third-party software on a + &unix; system include:</para> <procedure> <step> @@ -77,11 +73,10 @@ </step> <step> - <para>Locate the documentation (perhaps an - <filename>INSTALL</filename> or <filename>README</filename> - file, or some files in a <filename>doc/</filename> - subdirectory) and read up on how to install the - software.</para> + <para>Locate the documentation in + <filename>INSTALL</filename>, <filename>README</filename> + or some file in a <filename>doc/</filename> subdirectory and + read up on how to install the software.</para> </step> <step> @@ -96,59 +91,40 @@ </step> </procedure> - <para>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.</para> - - <para>Should you want to, you can continue to install software the - <quote>traditional</quote> 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.</para> - - <para>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.</para> - - <para>A FreeBSD port for an application is a collection of files - designed to automate the process of compiling an application - from source code.</para> - - <para>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.</para> - - <para>In fact, the ports system can also be used to generate - packages which can later be manipulated with - <command>pkg_add</command> and the other package management - commands that will be introduced shortly.</para> + <para>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.</para> + + <para>&os; provides two technologies which perform these steps for + you. At the time of writing, over &os.numports; third-party + applications are available.</para> + + <para>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;.</para> + + <para>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.</para> + + <para>The ports system can also be used to generate packages which + can be manipulated with the &os; package management + commands.</para> <para>Both packages and ports understand - <emphasis>dependencies</emphasis>. 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 - <command>pkg_add</command> 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.</para> - - <para>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.</para> + <emphasis>dependencies</emphasis>. 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.</para> + + <para>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.</para> <itemizedlist> <title>Package Benefits</title> @@ -160,17 +136,17 @@ </listitem> <listitem> - <para>Packages do not require any additional compilation. For - large applications, such as + <para>Packages do not require compilation time. For large + applications, such as <application>Mozilla</application>, <application>KDE</application>, or <application>GNOME</application> this can be important, - particularly if you are on a slow system.</para> + on a slow system.</para> </listitem> <listitem> <para>Packages do not require any understanding of the process - involved in compiling software on FreeBSD.</para> + involved in compiling software on &os;.</para> </listitem> </itemizedlist> @@ -179,105 +155,89 @@ <listitem> <para>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.</para> + options because they have to run on the maximum number of + systems. By compiling from the port, one can change the + compilation options.</para> </listitem> <listitem> <para>Some applications have compile-time options relating to - what they can and cannot do. For example, + which features are installed. For example, <application>Apache</application> 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.</para> + wide variety of different built-in options.</para> <para>In some cases, multiple packages will exist for the same application to specify certain settings. For example, <application>Ghostscript</application> is available as a <filename>ghostscript</filename> package and a <filename>ghostscript-nox11</filename> 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.</para> + whether or not <application>Xorg</application> is installed. + Creating multiple packages rapidly becomes impossible if an + application has more than one or two different compile-time + options.</para> </listitem> <listitem> - <para>The licensing conditions of some software distributions - forbid binary distribution. They must be distributed as - source code.</para> + <para>The licensing conditions of some software forbid binary + distribution. These must be distributed as source code + which must be compiled by the end-user.</para> </listitem> <listitem> - <para>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.</para> + <para>Some people do not trust binary distributions or prefer + to read through source code in order to look for potential + problems.</para> </listitem> <listitem> <para>If you have local patches, you will need the source in order to apply them.</para> </listitem> - - <listitem> - <para>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.</para> - </listitem> </itemizedlist> <para>To keep track of updated ports, subscribe to the &a.ports; and the &a.ports-bugs;.</para> <warning> - <para>Before installing any application, you should check <ulink + <para>Before installing any application, check <ulink url="http://vuxml.freebsd.org/"></ulink>; for security issues - related to your application.</para> - - <para>You can also install - <filename role="package">ports-mgmt/portaudit</filename> - 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 - <command>portaudit -F -a</command> after you have installed - some packages.</para> + related to the application or install <filename + role="package">ports-mgmt/portaudit</filename>. Once + installed, type <command>portaudit -F -a</command> to check + all installed applications for known vulnerabilities</para> </warning> - <para>The remainder of this chapter will explain how to use - packages and ports to install and manage third-party software on - FreeBSD.</para> + <para>The remainder of this chapter explains how to use packages + and ports to install and manage third-party software on + &os;.</para> </sect1> <sect1 id="ports-finding-applications"> - <title>Finding Your Application</title> + <title>Finding Software</title> - <para>Before you can install any applications you need to know - what you want, and what the application is called.</para> - - <para>FreeBSD's list of available applications is growing all the - time. Fortunately, there are a number of ways to find what you - want:</para> + <para>&os;'s list of available applications is growing all the + time. There are a number of ways to find software to + install:</para> <itemizedlist> <listitem> - <para>The FreeBSD web site maintains an up-to-date searchable + <para>The &os; web site maintains an up-to-date searchable list of all the available applications, at <ulink url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>. - 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.</para> + The ports can be searched by application name or by + software category.</para> </listitem> <listitem> <indexterm><primary>FreshPorts</primary></indexterm> - <para>Dan Langille maintains FreshPorts, at <ulink - url="http://www.FreshPorts.org/"></ulink>. FreshPorts - tracks changes to the applications in the ports tree as they - happen, allows you to <quote>watch</quote> one or more - ports, and can send you email when they are updated.</para> + <para>Dan Langille maintains <ulink + url="http://www.FreshPorts.org/">FreshPorts</ulink>; 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.</para> </listitem> <listitem> @@ -286,32 +246,21 @@ <para>If you do not know the name of the application you want, try using a site like Freecode (<ulink url="http://www.freecode.com/"></ulink>) 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.</para> </listitem> <listitem> - <para>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 + <para>To find out which category a port is in, type <command>whereis <replaceable>file</replaceable></command>, - where <replaceable>file</replaceable> is the program you - want to install. If it is found on your system, you will be - told where it is, as follows:</para> + where <replaceable>file</replaceable> is the program to be + installed:</para> <screen>&prompt.root; <userinput>whereis lsof</userinput> lsof: /usr/ports/sysutils/lsof</screen> - <para>This tells us that <command>lsof</command> (a system - utility) can be found in the - <filename>/usr/ports/sysutils/lsof</filename> - directory.</para> - </listitem> - - <listitem> - <para>Additionally, you can use a simple &man.echo.1; - statement to find where a port exists in the ports tree. - For example:</para> + <para>Alternately, a &man.echo.1; statement can be + used:</para> <screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput> /usr/ports/sysutils/lsof</screen> @@ -323,15 +272,15 @@ lsof: /usr/ports/sysutils/lsof</screen> </listitem> <listitem> - <para>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 - <filename>/usr/ports</filename> directory. Once in that - directory, run <command>make <maketarget>search</maketarget> - name=<replaceable>program-name</replaceable></command> where - <replaceable>program-name</replaceable> is the name of the - program you want to find. For example, if you were looking - for <command>lsof</command>:</para> + <para>Another way to find software is by using the Ports + Collection's built-in search mechanism. To use + the search feature, <application>cd</application> to + <filename>/usr/ports</filename> then run <command>make + <maketarget>search</maketarget> + name=<replaceable>program-name</replaceable></command> + where <replaceable>program-name</replaceable> is the name of + the software. For example,to search for + <command>lsof</command>:</para> <screen>&prompt.root; <userinput>cd /usr/ports</userinput> &prompt.root; <userinput>make search name=lsof</userinput> @@ -343,18 +292,11 @@ Index: sysutils B-deps: R-deps: </screen> - <para>The part of the output you want to pay particular - attention to is the <quote>Path:</quote> 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.</para> - - <para>Alternatively, there is another search feature from - ports that achieves the same purpose but with less noise, - the <command>quicksearch</command> feature. This feature - accepts the same parameter as the <command>search</command> - feature. For example, searching for <command>lsof</command> - would return:</para> + <para>The <quote>Path:</quote> line indicates where to find + the port.</para> + + <para>To receive less information, use the + <command>quicksearch</command> feature:</para> <screen>&prompt.root; <userinput>cd /usr/ports</userinput> &prompt.root; <userinput>make quicksearch name=lsof</userinput> @@ -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))</screen> - <para>For more in-depth searching you can also use + <para>For more in-depth searching, use <command>make <maketarget>search</maketarget> key=<replaceable>string</replaceable></command> or <command>make <maketarget>quicksearch</maketarget> key=<replaceable>string</replaceable></command>, where <replaceable>string</replaceable> 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.</para> + 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.</para> - <para>In both of these cases (<maketarget>search</maketarget> - and <maketarget>quicksearch</maketarget>), the search string + <para>When using (<maketarget>search</maketarget> and + <maketarget>quicksearch</maketarget>), the search string is case-insensitive. Searching for <quote>LSOF</quote> will yield the same results as searching for <quote>lsof</quote>.</para> @@ -394,10 +335,10 @@ Info: Lists information about open fil <!-- 30 Mar 2001 --> </sect1info> - <title>Using the Packages System</title> + <title>Using Binary Packages</title> <para>There are several different tools used to manage packages on - FreeBSD:</para> + &os;:</para> <itemizedlist> <listitem> @@ -424,9 +365,8 @@ Info: Lists information about open fil <indexterm> <primary><command>pkg_add</command></primary> </indexterm> - <para>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.</para> + <para>Use &man.pkg.add.1; to install a &os; binary package from + a local file or from a server on the network.</para> <example> <title>Downloading a Package Manually and Installing It @@ -457,26 +397,22 @@ local: lsof-4.56.4.tgz remote: lsof-4.56 &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 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 <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 d 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</title> - <para>All package information is stored within the - <filename>/var/db/pkg</filename> directory. The installed - file list and descriptions of each package can be found within - files in this directory.</para> + <para>All package information, including the file list and + descriptions of each installed package is stored within the + <filename>/var/db/pkg</filename> directory.</para> </sect2> </sect1> @@ -659,11 +584,10 @@ docbook = Management</title> <para><application>pkgng</application> is an improved replacement - for the traditional &os; <application>pkg_install</application> - package management tools, offering many features that make - dealing with binary packages faster and easier. The first - release of <application>pkgng</application> was in August, - 2012.</para> + for the traditional &os; package management tools, offering + many features that make dealing with binary packages faster and + easier. The first release of <application>pkgng</application> + was in August, 2012.</para> <para><application>pkgng</application> is not a replacement for port management tools like <filename @@ -777,7 +701,7 @@ docbook = <screen>&prompt.root; <userinput>man pkg-install</userinput></screen> <sect3 id="pkgng-pkg-info"> - <title>Obtaining Information about Installed Packages with + <title>Obtaining Information About Installed Packages with <application>pkgng</application></title> <para>Information about the packages installed on a system can @@ -939,10 +863,10 @@ Deinstalling ca_root_nss-3.13.5... done< <title>Backing Up the <application>pkgng</application> Package Database</title> - <para>Unlike the <application>pkg_install</application> - package management system, <application>pkgng</application> - includes its own package database backup mechanism. To - manually back up the package database contents, run:</para> + <para>Unlike the traditional package management system, + <application>pkgng</application> includes its own package + database backup mechanism. To manually back up the package + database contents, run:</para> <screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen> @@ -1048,11 +972,10 @@ Deinstalling ca_root_nss-3.13.5... done< <sect1 id="ports-using"> <title>Using the Ports Collection</title> - <para>The following sections provide basic instructions on using - the Ports Collection to install or remove programs from your - system. The detailed description of available - <command>make</command> targets and environment variables is - available in &man.ports.7;.</para> + <para>This section provides basic instructions on using the Ports + Collection to install or remove software. The detailed + description of available <command>make</command> targets and + environment variables is available in &man.ports.7;.</para> <warning> <para>As of mid 2012, the &os; Ports Project has migrated @@ -1072,7 +995,7 @@ Deinstalling ca_root_nss-3.13.5... done< <para>The Ports Collection is a set of <filename>Makefiles</filename>, patches, and description files stored in <filename>/usr/ports</filename>. 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.</para> @@ -1312,75 +1235,57 @@ Deinstalling ca_root_nss-3.13.5... done< <secondary>installing</secondary> </indexterm> - <para>The first thing that should be explained when it comes to - the Ports Collection is what is actually meant by a - <quote>skeleton</quote>. 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 + <para>A port skeleton is a set of files that tell &os; system + how to compile and install a program. Each port skeleton includes:</para> <itemizedlist> <listitem> - <para>A <filename>Makefile</filename>. The - <filename>Makefile</filename> contains various statements - that specify how the application should be compiled and - where it should be installed on your system.</para> + <para><filename>Makefile</filename>: The + <filename>Makefile</filename> contains statements that + specify how the application should be compiled and where + its components should be installed.</para> </listitem> <listitem> - <para>A <filename>distinfo</filename> 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.</para> + <para><filename>distinfo</filename>: 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.</para> </listitem> <listitem> - <para>A <filename>files</filename> 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 - <quote>Remove line 10</quote> or <quote>Change line 26 to - this ...</quote>. Patches are also known as - <quote>diffs</quote> because they are generated by the - &man.diff.1; program.</para> - - <para>This directory may also contain other files used to - build the port.</para> + <para><filename>files/</filename>: 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.</para> </listitem> <listitem> - <para>A <filename>pkg-descr</filename> file. This is a more - detailed, often multiple-line, description of the - program.</para> + <para><filename>pkg-descr</filename>: This file provides a + more detailed description of the program.</para> </listitem> <listitem> - <para>A <filename>pkg-plist</filename> file. This is a list + <para><filename>pkg-plist</filename>: 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.</para> </listitem> </itemizedlist> - <para>Some ports have other files, such as + <para>Some ports include other files, such as <filename>pkg-message</filename>. 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 - <ulink url="&url.books.porters-handbook;/index.html">FreeBSD + on these files, and on ports in general, refer to the + <ulink url="&url.books.porters-handbook;/index.html">&os; Porter's Handbook</ulink>.</para> - <para>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 <quote>distfile</quote>. The two methods for - installing a &os; port are described below.</para> + <para>The port does not include the actual source code, also + known as a <quote>distfile</quote>. Source code is distributed + in whatever manner the software author desires. The two + methods for installing a &os; port are described below.</para> <note> <para>You must be logged in as <username>root</username> to @@ -1388,39 +1293,32 @@ Deinstalling ca_root_nss-3.13.5... done< </note> <warning> - <para>Before installing any port, you should be sure to have - an up-to-date Ports Collection and you should check - <ulink url="http://vuxml.freebsd.org/"></ulink>; for security - issues related to your port.</para> - - <para>A security vulnerabilities check can be automatically - done by <application>portaudit</application> before any new - application installation. This tool can be found in the - Ports Collection (<filename - role="package">ports-mgmt/portaudit</filename>). Consider - running <command>portaudit -F</command> 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.</para> + <para>Before compiling any port, be sure to have an + up-to-date Ports Collection and check <ulink + url="http://vuxml.freebsd.org/"></ulink>; for security + issues related to your port. If <filename + role="package">ports-mgmt/portaudit</filename>) is + installed, run <command>portaudit -F</command> 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.</para> </warning> - <para>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 - <filename>/usr/ports/distfiles</filename> manually.</para> + <para>Using the Ports Collection assumes a working Internet + connection. Otherwise, manually obtain and place a copy of + the distfile into + <filename>/usr/ports/distfiles</filename>.</para> - <para>To begin, change to the directory for the port you want - to install:</para> + <para>To begin, change to the directory of the port to + be installed:</para> <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen> - <para>Once inside the <filename>lsof</filename> directory, you - will see the port skeleton. The next step is to compile, or - <quote>build</quote>, the port. This is done by simply - typing <command>make</command> at the prompt. Once you have - done so, you should see something like this:</para> + <para>To compile, or <quote>build</quote>, the port, type + <command>make</command> at the prompt. You should see + messages similar to the ones in this example:</para> <screen>&prompt.root; <userinput>make</userinput> >> 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;</screen> - <para>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 <command>make</command> command, and that word - is <maketarget>install</maketarget>:</para> + <para>Once the compile is complete, you are returned to the + prompt. The next step is to install the port using + <maketarget>make install</maketarget>:</para> <screen>&prompt.root; <userinput>make install</userinput> ===> Installing for lsof-4.57 @@ -1461,18 +1357,18 @@ Deinstalling ca_root_nss-3.13.5... done< increased privileges. &prompt.root;</screen> - <para>Once you are returned to your prompt, you should be able - to run the application you just installed. Since - <command>lsof</command> 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.</para> + <para>Once you are returned to the prompt, you should be able + to run the installed application. Since + <command>lsof</command> 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.</para> <para>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.</para> + compilation. Doing so saves disk space and minimizes the + chance of problems later when upgrading to the newer version + of the port.</para> <screen>&prompt.root; <userinput>make clean</userinput> ===> Cleaning for lsof-4.57 @@ -1489,13 +1385,12 @@ Deinstalling ca_root_nss-3.13.5... done< </note> <note> - <para>When installing a port, using only + <para>Using only <command>make <maketarget>install</maketarget></command> - 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 <command>make + behaviour is to prompt the user for options. To avoid this + when there are many dependencies, first run <command>make <maketarget>config-recursive</maketarget></command> to do the configuration in one batch. Then run <command>make <maketarget>install [clean]</maketarget></command> @@ -1519,32 +1414,30 @@ Deinstalling ca_root_nss-3.13.5... done< available in the directories listed in the <envar>PATH</envar> 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 - <command>rehash</command> command after installing a port, - before the newly installed commands can be used. This - command will work for shells like <command>tcsh</command>. - Use the <command>hash -r</command> command for shells like - <command>sh</command>. Look at the documentation for your - shell for more information.</para> + you are using <command>tcsh</command>, you might have to + type <command>rehash</command> so that a newly installed + command can be used without specifying its full path. Use + <command>hash -r</command> instead for the + <command>sh</command> shell. Refer to the documentation for + the shell for more information.</para> </note> - <para>Some third-party DVD-ROM products such as the FreeBSD - Toolkit from the - <ulink url="http://www.freebsdmall.com/">FreeBSD Mall</ulink> - contain distfiles. They can be used with the Ports - Collection. Mount the DVD-ROM on <filename>/cdrom</filename>. - If you use a different mount point, set - <makevar>CD_MOUNTPTS</makevar> make variable. The needed - distfiles will be automatically used if they are present on - the disk.</para> + <para>Some third-party DVD products such as the &os; + Toolkit from the <ulink url="http://www.freebsdmall.com/">&os; + Mall</ulink> contain distfiles. They can be used with the + Ports Collection. Mount the DVD on + <filename>/cdrom</filename>. If you use a different mount + point, set <makevar>CD_MOUNTPTS</makevar> make variable. The + needed distfiles will be automatically used if they are + present on the disk.</para> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201301301439.r0UEd4ZH068102>