From owner-svn-doc-all@FreeBSD.ORG Tue Oct 8 19:48:28 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id B056B690; Tue, 8 Oct 2013 19:48:28 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 9A6752BF9; Tue, 8 Oct 2013 19:48:28 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r98JmSY2025118; Tue, 8 Oct 2013 19:48:28 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r98JmS9b025117; Tue, 8 Oct 2013 19:48:28 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201310081948.r98JmS9b025117@svn.freebsd.org> From: Dru Lavigne Date: Tue, 8 Oct 2013 19:48:28 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42903 - head/en_US.ISO8859-1/books/handbook/ports X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 08 Oct 2013 19:48:28 -0000 Author: dru Date: Tue Oct 8 19:48:28 2013 New Revision: 42903 URL: http://svnweb.freebsd.org/changeset/doc/42903 Log: This patch does the following to the first half of 5.6. Using the Ports Collection: - as per discussion with portmgr, removes csup warnings and how-tos - as per discussion on IRC, remove Method 3 as sysinstall is being phased out - adds some text and word-smithing to make unclear instructions a bit clearer - some tag cleanup - updated lsof listing - some text shuffling to improve flow 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 Tue Oct 8 17:39:20 2013 (r42902) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Tue Oct 8 19:48:28 2013 (r42903) @@ -888,41 +888,22 @@ Deinstalling ca_root_nss-3.15.1_1... don Using the Ports Collection - 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 - revision control systems from CVS to Subversion. The - preferred method for obtaining and maintaining the ports tree - is Portsnap. Users requiring local - customization of ports (that is, maintaining additional local - patches) will probably prefer to use Subversion directly. The - CVSup service was phased out - as of February 28, 2013. - - - - Obtaining the Ports Collection - The Ports Collection is a set of Makefiles, patches, and description files - stored in /usr/ports. This set of files - 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. + stored in /usr/ports. This set of files + is used to compile and install applications on &os;. Before + an application can be compiled using a port, the Ports + Collection must first be installed. If it was not installed during the installatio of &os;, + use one of the following methods to install it: Portsnap Method Portsnap is a fast and - user-friendly tool for retrieving the Ports Collection, the - preferred choice for most users. See - Using - Portsnap for a detailed description of + user-friendly tool for retrieving the Ports Collection and is the + recommended choice for most users. See + + for a detailed description of Portsnap. @@ -946,7 +927,7 @@ Deinstalling ca_root_nss-3.15.1_1... don Portsnap has been completed as shown above, /usr/ports can be - updated with: + updated as needed by running: &prompt.root; portsnap fetch &prompt.root; portsnap update @@ -956,8 +937,8 @@ Deinstalling ca_root_nss-3.15.1_1... don Subversion Method - If more control over the ports tree is needed (for - example, for maintaining local changes), + If more control over the ports tree is needed or if + local changes need to be maintained, Subversion can be used to obtain the Ports Collection. Refer to the @@ -988,22 +969,17 @@ Deinstalling ca_root_nss-3.15.1_1... don - Check out a copy of the ports tree. Use a specific + Check out a copy of the ports tree. For better performance, + replace svn0.us-east.FreeBSD.org with a Subversion - mirror close to your geographic location instead - of svn0.us-east.FreeBSD.org in the - command below for better performance. Committers should - read the Subversion - Primer first to be sure the correct protocol is - chosen. + mirror close to your geographic location: &prompt.root; svn checkout https://svn0.us-east.FreeBSD.org/ports/head /usr/ports - To update + As needed, update /usr/ports after the initial Subversion checkout: @@ -1012,411 +988,259 @@ Deinstalling ca_root_nss-3.15.1_1... don - - Sysinstall Method - - This method involves using - sysinstall to install the Ports - Collection from the installation media. Note that the old - copy of Ports Collection from the date of the release will - be installed. If you have Internet access, you should - always use one of the methods mentioned above. - - - As root, run - sysinstall as shown below: - - &prompt.root; sysinstall - - - - Scroll down and select - Configure, press - Enter. - - - - Scroll down and select - Distributions, press - Enter. - - - - Scroll down to ports, press - Space. - - - - Scroll up to Exit, press - Enter. - - - - Select your desired installation media, such as CDROM, - FTP, and so on. - - - - Scroll up to Exit and press - Enter. - - - - Press X to exit - sysinstall. - - - - - - Migrating from - <application>CVSup</application>/<application>csup</application> - to <application>portsnap</application> - - - By February 28, 2013, the ports tree will no longer be - exported to CVS and therefore - CVSup and - csup will no longer provide - updates for the ports tree. - - - - Migration to Portsnap - - The migration will require about 1 GB of disk space - on /usr, plus - Portsnap requires about - 150 MB disk space on /var. - - - Disable any automated ports updates you may use, such - as a &man.cron.8; job calling - CVSup or - csup. - - - - Move the existing ports tree to a temporary - location: - - &prompt.root; mv /usr/ports /usr/ports.old - - - - Fetch the new ports tree with - Portsnap and extract it to - /usr/ports: - - &prompt.root; portsnap fetch extract - - - - Move distfiles and saved packages to the new ports - tree: - - &prompt.root; mv /usr/ports.old/distfiles /usr/ports -&prompt.root; mv /usr/ports.old/packages /usr/ports - - - - Delete the old ports tree: - - &prompt.root; rm -rf /usr/ports.old - - - - If CVSup was used before, - it can now be uninstalled: - - &prompt.root; pkg_delete -r -v cvsup-without-gui-\* - - Users of pkgng can use the - following command: - - &prompt.root; pkg delete cvsup-without-gui - - - - See Using - Portsnap for a detailed description of - Portsnap and how to update the - ports tree with Portsnap. - - - - Installing Ports - - - ports - installing - - - A port skeleton is a set of files that tell &os; system - how to compile and install a program. Each port skeleton - includes: + The Ports Collection installs a series of directories + representing software categories with each category having + a subdirectory for each application. Each subdirectory, also + referred to as a ports skeleton, contains a set of files that tell &os; + how to compile and install that program. Each port skeleton + includes these files and directories: - Makefile: The - Makefile contains statements that + Makefile: contains statements that specify how the application should be compiled and where its components should be installed. - 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. + distinfo: contains the names + and checksums of the files that must be downloaded to + build the port. - files/: This directory contains + 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. - pkg-descr: This file provides a + pkg-descr: provides a more detailed description of the program. - pkg-plist: This is a list + pkg-plist: a list of all the files that will be installed by the port. It - also tells the ports system what files to remove upon + also tells the ports system which files to remove upon deinstallation. - Some ports include other files, such as - pkg-message. The ports system uses these - files to handle special situations. If you want more details + Some ports include + pkg-message or other + files to handle special situations. For more details on these files, and on ports in general, refer to the &os; Porter's Handbook. 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. + known as a distfile. The extract portion + of building a port will automatically save the downloaded + source to /usr/ports/distfiles. - - You must be logged in as root to - install ports. - + + Installing Ports + + + ports + installing + + + 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;. - Before compiling any port, be sure to have an - up-to-date Ports Collection and check for security - issues related to your port. If Before compiling any port, be sure to update the + Ports Collection as described in the previous section. + Since the installation of any third-party software can + introduce security vulnerabilities, it is recommended to + first check for known security + issues related to the port. Alternately, 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. + installing a new port. This command can be configured to + automatically perform a security audit and an update of the vulnerability database + during the daily security system check. + For more information, refer to the manual page for portaudit and + &man.periodic.8;. Using the Ports Collection assumes a working Internet - connection. Otherwise, manually obtain and place a copy of - the distfile into - /usr/ports/distfiles. + connection. It also requires + superuser privilege. - To begin, change to the directory of the port to - be installed: - - &prompt.root; cd /usr/ports/sysutils/lsof - - 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/. + Some third-party DVD products such as the &os; + Toolkit from freebsdmall.com + contain distfiles which can be used to install ports + without an Internet connection. + Mount the DVD on + /cdrom. If you use a different mount + point, set the CD_MOUNTPTS make variable. The + needed distfiles will be automatically used if they are + present on the disk. However, 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. In order to install a port not included + on the DVD, a connection to the + Internet will still be required. + + To compile and install the port, change to the directory of the port to + be installed, then type + make install at the prompt. Messages will + indicate the progress: + + &prompt.root; cd /usr/ports/sysutils/lsof +&prompt.root; make install +>> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. -===> Extracting for lsof-4.57 +===> Extracting for lsof-4.88 ... [extraction output snipped] ... ->> Checksum OK for lsof_4.57D.freebsd.tar.gz. -===> Patching for lsof-4.57 -===> Applying FreeBSD patches for lsof-4.57 -===> Configuring for lsof-4.57 +>> Checksum OK for lsof_4.88D.freebsd.tar.gz. +===> Patching for lsof-4.88.d,8 +===> Applying FreeBSD patches for lsof-4.88.d,8 +===> Configuring for lsof-4.88.d,8 ... [configure output snipped] ... -===> Building for lsof-4.57 +===> Building for lsof-4.88.d,8 ... [compilation output snipped] ... -&prompt.root; - - 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 +===> Installing for lsof-4.88.d,8 ... [installation output snipped] ... ===> Generating temporary packing list -===> Compressing manual pages for lsof-4.57 -===> Registering installation for lsof-4.57 +===> Compressing manual pages for lsof-4.88.d,8 +===> Registering installation for lsof-4.88.d,8 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. +/usr/local/sbin/lsof &prompt.root; - Once you are returned to the prompt, you should be able - to run the installed application. Since + 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. + privileges, a security warning is displayed as it is installed. + Once the installation is complete, the prompt will be + returned. - It is a good idea to delete the working subdirectory, + Some shells keep a cache of the commands that are + available in the directories listed in the + PATH environment variable, to speed up lookup + operations for the executable file of these commands. Users + of the tcsh shell should + 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. + + During installation, a working subdirectory is created which contains all the temporary files used during - compilation. Doing so saves disk space and minimizes the + compilation. Removing this directory saves disk space and minimizes the chance of problems later when upgrading to the newer version - of the port. + of the port: &prompt.root; make clean -===> Cleaning for lsof-4.57 +===> Cleaning for lsof-88.d,8 &prompt.root; - You can save two extra steps by just running + To save this extra step, instead use make - install clean - instead of make, - make install - and make clean - as three separate steps. + install clean when + compiling the port. + + + Customizing Ports Installation - - Using only - make install - means there will potentially be many - waiting periods between user interaction as the default - behaviour is to prompt the user for options. To avoid this - when there are many dependencies, first run make + Some ports provide build options which can be used to + enable or disable application components, + provide security options, or allow for other customizations. + Examples include + www/firefox, + security/gpgme, and + mail/sylpheed-claws. + If the port has configurable options, it may pause + several times for + user interaction as the default + behavior is to prompt the user to select options from a menu. + To avoid this, + run make config-recursive to do - the configuration in one batch. Then run make + this configuration in one batch. Then, run make install [clean] - afterwards. - + to compile and install the port. When using config-recursive, the list of ports to configure are gathered by the - all-depends-list &man.make.1; - target. It is often recommended to run make + all-depends-list + target. It is recommended to run make config-recursive until all dependent ports options have been defined, and - ports options &man.dialog.1; screens no longer - appear, to be certain all ports options have been - configured as intended. + ports options screens no longer + appear, to be certain that all dependency options have been + configured. - - Some shells keep a cache of the commands that are - 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 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 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. - - - 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. - + There are several ways to revisit a port's build options 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 + in great detail in &man.ports.7;. The ports system uses &man.fetch.1; to download the - files, which honors various environment variables, including + source files, which supports various environment variables. The FTP_PASSIVE_MODE, FTP_PROXY, and - FTP_PASSWORD. You may need to set one or more - of these if you are behind a firewall, or need to use an + FTP_PASSWORD variables may need to be set if the &os; system + is behind a firewall or FTP/HTTP proxy. See &man.fetch.3; for the complete - list. + list of supported variables. - For users which cannot be connected all the time, the - make fetch option - 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 + For users who cannot be connected to the Internet all the time, + make fetch can be run + within + /usr/ports, to fetch all distfiles, or within + a category, such as + /usr/ports/net, or within the + specific port skeleton. Note that if a port has any dependencies, + running this command in a category or ports skeleton will not fetch the distfiles of ports - from another category. Use + from another category. Instead, use make fetch-recursive - to fetch + to also fetch the distfiles for 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. 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 default - MASTER_SITES. You can override the - MASTER_SITES option with the following - command: + In rare cases, such as when an organization has a local + distfiles repository, the + MASTER_SITES variable can be used to override the + download locations specified in the Makefile. + When using, specify the alternate location: &prompt.root; cd /usr/ports/directory &prompt.root; make MASTER_SITE_OVERRIDE= \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - - In this example, MASTER_SITES is - changed to ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/. - - - 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 - menu will be displayed at the beginning of a port - compile when compile options are available. - - - - Overriding the Default Ports Directories +ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch The WRKDIRPREFIX and PREFIX variables can override the default @@ -1425,44 +1249,24 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install will compile the port in - /usr/home/example/ports and install - everything under /usr/local. + /usr/home/example/ports and install + everything under /usr/local. &prompt.root; make PREFIX=/usr/home/example/local install - will compile the port in /usr/ports + will compile the port in /usr/ports and install it in - /usr/home/example/local. - - And + /usr/home/example/local. And: &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install will combine the two. - Alternatively, these can be set as environmental + These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable. - - - - Reconfiguring Ports - 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 - in great detail in the manual page for &man.ports.7;. @@ -1474,10 +1278,34 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ removing - Installed ports and packages are uninstalled using - the &man.pkg.delete.1; command: - - &prompt.root; pkg_delete lsof-4.57 + Installed ports can be uninstalled using + &man.pkg.delete.1;. Alternately, if the &os; system has been + configured to use pkg, a port can be + uninstalled using pkg delete. Examples + for using these commands can be found in and + + Alternately, make deinstall can be + run in the port's directory: + + &prompt.root; cd /usr/ports/sysutils/lsof +make deinstall +===> Deinstalling for sysutils/lsof +===> Deinstalling +Deinstallation has been requested for the following 1 packages: + + lsof-4.88.d,8 + +The deinstallation will free 229 kB +[1/1] Deleting lsof-4.88.d,8... done + + It is recommended to read the messages as the port is + uninstalled. If the port has any applications that depend + upon it, this information will be displayed but the + uninstallation will proceed. In such cases, it may be better + to reinstall the application in order to prevent broken + dependencies.