From owner-dev-commits-doc-all@freebsd.org Sat May 1 17:11:05 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id D83A6632685 for ; Sat, 1 May 2021 17:11:05 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4FXbNn5lWTz4jdf; Sat, 1 May 2021 17:11:05 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id B82AE1B27A; Sat, 1 May 2021 17:11:05 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 141HB5EY068660; Sat, 1 May 2021 17:11:05 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 141HB5O0068659; Sat, 1 May 2021 17:11:05 GMT (envelope-from git) Date: Sat, 1 May 2021 17:11:05 GMT Message-Id: <202105011711.141HB5O0068659@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Ryusuke SUZUKI Subject: git: caff9acc27 - main - Delete file checkouted by mistake. MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ryusuke X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: caff9acc27fa7d97f5b05f0220398da70e93c8ab Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 01 May 2021 17:11:05 -0000 The branch main has been updated by ryusuke: URL: https://cgit.FreeBSD.org/doc/commit/?id=caff9acc27fa7d97f5b05f0220398da70e93c8ab commit caff9acc27fa7d97f5b05f0220398da70e93c8ab Author: Ryusuke SUZUKI AuthorDate: 2021-05-01 17:10:31 +0000 Commit: Ryusuke SUZUKI CommitDate: 2021-05-01 17:10:31 +0000 Delete file checkouted by mistake. --- en_US.ISO8859-1/books/handbook/ports/chapter.xml | 1831 ---------------------- 1 file changed, 1831 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml deleted file mode 100644 index 110d47f3b6..0000000000 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml +++ /dev/null @@ -1,1831 +0,0 @@ - - - - - Installing Applications: Packages and Ports - - - Synopsis - - ports - packages - &os; is bundled with a rich collection of system tools as - part of the base system. In addition, &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: - - - - The difference between binary packages and ports. - - - - How to find third-party software that has been ported - to &os;. - - - - How to manage binary packages using - pkg. - - - - How to build third-party software from source using the - Ports Collection. - - - - How to find the files installed with the application - for post-installation configuration. - - - - What to do if a software installation fails. - - - - - - Overview of Software Installation - - The typical steps for installing third-party software on a - &unix; system include: - - - - Find and download the software, which might be - distributed in source code format or as a binary. - - - - Unpack the software from its distribution format. This - is typically a tarball compressed with a program such as - &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or - &man.xz.1;. - - - - Locate the documentation in - INSTALL, README - or some file in a doc/ subdirectory and - read up on how to install the software. - - - - If the software was distributed in source format, - compile it. This may involve editing a - Makefile or running a - configure script. - - - - Test and install the software. - - - - 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. - - If the software has not already been adapted and tested - on &os;, the source code might need editing in - order for it to install and run properly. - - However, over &os.numports; - third-party applications have already been ported to &os;. When - feasible, these applications are made available for download as - pre-compiled packages. - - Packages - can be manipulated with the &os; package management - commands. - - Both packages and ports understand dependencies. If a - package or port is used to install an application and a - dependent library is not already installed, the library will - automatically be installed first. - - 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 the - &man.pkg.8; commands, such as - pkg install. - - While the two technologies are similar, packages and - ports each have their own strengths. Select the technology that - meets your requirements for installing a particular - application. - - - Package Benefits - - - A compressed package tarball is typically smaller than - the compressed tarball containing the source code for the - application. - - - - Packages do not require compilation time. For large - applications, such as Mozilla, - KDE, or - GNOME, this can be important - on a slow system. - - - - Packages do not require any understanding of the process - involved in compiling software on &os;. - - - - - Port Benefits - - - Packages are normally compiled with conservative - 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 - which features are installed. For example, - Apache can be configured with a - 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 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 forbid binary - distribution. Such software must be distributed as source - code which must be compiled by the end-user. - - - - Some people do not trust binary distributions or prefer - to read through source code in order to look for potential - problems. - - - - Source code is needed in - order to apply custom patches. - - - - To keep track of updated ports, subscribe to the - &a.ports; and the &a.ports-bugs;. - - - Before installing any application, check - for security issues related to the application or type - pkg audit -F to check all installed - applications for known vulnerabilities. - - - The remainder of this chapter explains how to use packages - and ports to install and manage third-party software on - &os;. - - - - Finding Software - - &os;'s list of available applications is growing all the - time. There are a number of ways to find software to - install: - - - - The &os; web site maintains an up-to-date searchable - list of all the available applications, at https://www.FreeBSD.org/ports/. - The ports can be searched by application name or by - software category. - - - - FreshPorts - - Dan Langille maintains FreshPorts.org - 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. - - - - SourceForge - - If finding a particular application becomes challenging, - try searching a site like SourceForge.net - or GitHub.com then - check back at the &os; site - to see if the application has been ported. - - - - - pkg - search - - - To search the binary package - repository for an application: - - &prompt.root; pkg search subversion -git-subversion-1.9.2 -java-subversion-1.8.8_2 -p5-subversion-1.8.8_2 -py27-hgsubversion-1.6 -py27-subversion-1.8.8_2 -ruby-subversion-1.8.8_2 -subversion-1.8.8_2 -subversion-book-4515 -subversion-static-1.8.8_2 -subversion16-1.6.23_4 -subversion17-1.7.16_2 - - Package names include the version number and, in the - case of ports based on python, the version number of the - version of python the package was built with. Some ports - also have multiple versions available. In the case of - Subversion, there are different - versions available, as well as different compile options. - In this case, the statically linked version of - Subversion. When indicating - which package to install, it is best to specify the - application by the port origin, which is the path in the - ports tree. Repeat the pkg search with - to list the origin of each - package: - - &prompt.root; pkg search -o subversion -devel/git-subversion -java/java-subversion -devel/p5-subversion -devel/py-hgsubversion -devel/py-subversion -devel/ruby-subversion -devel/subversion16 -devel/subversion17 -devel/subversion -devel/subversion-book -devel/subversion-static - - Searching by shell globs, regular expressions, exact - match, by description, or any other field in the repository - database is also supported by pkg search. - After installing ports-mgmt/pkg or - ports-mgmt/pkg-devel, see - &man.pkg-search.8; for more details. - - - - If the Ports Collection is already installed, there are - several methods to query the local version of the ports - tree. To find out which category a port is in, type - whereis file, - where file is the program to be - installed: - - &prompt.root; whereis lsof -lsof: /usr/ports/sysutils/lsof - - Alternately, an &man.echo.1; statement can be - used: - - &prompt.root; echo /usr/ports/*/*lsof* -/usr/ports/sysutils/lsof - - Note that this will also return any matched files - downloaded into the - /usr/ports/distfiles directory. - - - - 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 -Port: lsof-4.88.d,8 -Path: /usr/ports/sysutils/lsof -Info: Lists information about open files (similar to fstat(1)) -Maint: ler@lerctr.org -Index: sysutils -B-deps: -R-deps: - - - The built-in search mechanism uses a file - of index information. If a message indicates that the - INDEX is required, run - make fetchindex to download the current - index file. With the INDEX present, - make search will be able to perform the - requested search. - - - The Path: line indicates where to find - the port. - - To receive less information, use the - quicksearch feature: - - &prompt.root; cd /usr/ports -&prompt.root; make quicksearch name=lsof -Port: lsof-4.88.d,8 -Path: /usr/ports/sysutils/lsof -Info: Lists information about open files (similar to fstat(1)) - - For more in-depth searching, use - make search - key=string or - make quicksearch - key=string, where - string is some text to search - for. The text can be in comments, descriptions, or - dependencies in order to find ports which relate to a - particular subject when the name of the program is - unknown. - - When using search or - quicksearch, the search string - is case-insensitive. Searching for LSOF will - yield the same results as searching for - lsof. - - - - - - Using <application>pkg</application> for Binary Package - Management - - pkg is the next generation - replacement for the traditional &os; package management tools, - offering many features that make dealing with binary packages - faster and easier. - - For sites wishing to only use prebuilt binary packages - from the &os; mirrors, managing packages with - pkg can be sufficient. - - However, for those sites building from source or using their - own repositories, a separate port management tool - will be needed. - - Since pkg only works with - binary packages, it - is not a replacement for such tools. Those tools can be - used to install software from both binary packages - and the Ports Collection, while - pkg installs only binary - packages. - - - Getting Started with - <application>pkg</application> - - &os; includes a bootstrap utility which can be used to - download and install pkg - and its manual pages. This utility is designed to work - with versions of &os; starting with - 10.X. - - - Not all &os; versions and architectures - support this bootstrap process. The current list is at - . - For other cases, - pkg must instead be installed - from the Ports Collection or as a binary package. - - - - To bootstrap the system, run: - - &prompt.root; /usr/sbin/pkg - - You must have a working Internet connection for the - bootstrap process to succeed. - - Otherwise, to install the port, run: - - &prompt.root; cd /usr/ports/ports-mgmt/pkg -&prompt.root; make -&prompt.root; make install clean - - When upgrading an existing system that originally used the - older pkg_* tools, the database must be converted to the - new format, so that the new tools are aware of the already - installed packages. Once pkg has - been installed, the - package database must be converted from the traditional format - to the new format by running this command: - - &prompt.root; pkg2ng - - This step is not required for new installations that - do not yet have any third-party software - installed. - - - This step is not reversible. Once the package database - has been converted to the pkg - format, the traditional pkg_* tools - should no longer be used. - - - - The package database conversion may emit errors as the - contents are converted to the new version. Generally, these - errors can be safely ignored. However, a list of - software that was not successfully converted - is shown after pkg2ng finishes. - These applications must be manually reinstalled. - - - To ensure that the Ports Collection registers - new software with pkg instead of - the traditional packages database, &os; versions earlier than - 10.X require this line in - /etc/make.conf: - - WITH_PKGNG= yes - - By default, pkg uses the - binary packages from the &os; - package mirrors (the repository). - For information about building a custom - package repository, see - . - - Additional pkg configuration - options are described in &man.pkg.conf.5;. - - Usage information for pkg is - available in the &man.pkg.8; manual page or by running - pkg without additional arguments. - - Each pkg command argument is - documented in a command-specific manual page. To read the - manual page for pkg install, for example, - run either of these commands: - - &prompt.root; pkg help install - - &prompt.root; man pkg-install - - The rest of this section demonstrates common binary - package management tasks which can be performed using - pkg. Each demonstrated command - provides many switches to customize its use. Refer to a - command's help or man page for details and more - examples. - - - - Quarterly and Latest Ports Branches - - The Quarterly branch provides users - with a more predictable and stable experience for port and - package installation and upgrades. This is done essentially - by only allowing non-feature updates. Quarterly branches aim - to receive security fixes (that may be version updates, or - backports of commits), bug fixes and ports compliance or - framework changes. The Quarterly branch is cut from HEAD at - the beginning of every (yearly) quarter in January, April, - July, and October. Branches are named according to the year - (YYYY) and quarter (Q1-4) they are created in. For example, - the quarterly branch created in January 2016, is named 2016Q1. - And the Latest branch provides the latest - versions of the packages to the users. - - To switch from quarterly to latest run the following - commands: - - &prompt.root; cp /etc/pkg/FreeBSD.conf /usr/local/etc/pkg/repos/FreeBSD.conf - - Edit the file - /usr/local/etc/pkg/repos/FreeBSD.conf - and change the string quarterly to - latest in the url: - line. - - The result should be similar to the following: - - FreeBSD: { - url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest", - mirror_type: "srv", - signature_type: "fingerprints", - fingerprints: "/usr/share/keys/pkg", - enabled: yes -} - - And finally run this command to update from the new - (latest) repository metadata. - - &prompt.root; pkg update -f - - - - - Obtaining Information About Installed Packages - - Information about the packages installed on a system - can be viewed by running pkg info which, - when run without any switches, will list the package version - for either all installed packages or the specified - package. - - For example, to see which version of - pkg is installed, run: - - &prompt.root; pkg info pkg -pkg-1.1.4_1 - - - - Installing and Removing Packages - - To install a binary package use the following command, - where packagename is the name of - the package to install: - - &prompt.root; pkg install packagename - - This command uses repository data to determine which - version of the software to install and if it has any - uninstalled dependencies. For example, to install - curl: - - &prompt.root; pkg install curl -Updating repository catalogue -/usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s - -/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s - -Updating repository catalogue -The following 2 packages will be installed: - - Installing ca_root_nss: 3.15.1_1 - Installing curl: 7.31.0_1 - -The installation will require 3 MB more space - -0 B to be downloaded - -Proceed with installing packages [y/N]: y -Checking integrity... done -[1/2] Installing ca_root_nss-3.15.1_1... done -[2/2] Installing curl-7.31.0_1... done -Cleaning up cache files...Done - - The new package and any additional packages that were - installed as dependencies can be seen in the installed - packages list: - - &prompt.root; pkg info -ca_root_nss-3.15.1_1 The root certificate bundle from the Mozilla Project -curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers -pkg-1.1.4_6 New generation package manager - - Packages that are no longer needed can be removed with - pkg delete. For example: - - &prompt.root; pkg delete curl -The following packages will be deleted: - - curl-7.31.0_1 - -The deletion will free 3 MB - -Proceed with deleting packages [y/N]: y -[1/1] Deleting curl-7.31.0_1... done - - - - Upgrading Installed Packages - - Installed packages can be upgraded to their latest - versions by running: - - &prompt.root; pkg upgrade - - This command will compare the installed versions with - those available in the repository catalogue and upgrade them - from the repository. - - - - Auditing Installed Packages - - Software vulnerabilities are regularly discovered - in third-party applications. To address this, - pkg includes a built-in auditing - mechanism. To determine if there are any known - vulnerabilities for the software installed on the system, - run: - - &prompt.root; pkg audit -F - - - - Automatically Removing Unused Packages - - Removing a package may leave behind dependencies which - are no longer required. Unneeded packages that were installed - as dependencies (leaf packages) can be automatically detected - and removed using: - - &prompt.root; pkg autoremove -Packages to be autoremoved: - ca_root_nss-3.15.1_1 - -The autoremoval will free 723 kB - -Proceed with autoremoval of packages [y/N]: y -Deinstalling ca_root_nss-3.15.1_1... done - - Packages installed as dependencies are - called automatic packages. Non-automatic - packages, i.e the packages that were explicity installed not - as a dependency to another package, can be listed - using: - - &prompt.root; pkg prime-list -nginx -openvpn -sudo - - pkg prime-list is an alias command - declared in /usr/local/etc/pkg.conf. - There are many others that can be used to query the package - database of the system. For instance, command - pkg prime-origins can be used to get the - origin port directory of the list mentioned above: - - &prompt.root; pkg prime-origins -www/nginx -security/openvpn -security/sudo - - This list can be used to rebuild all packages - installed on a system using build tools such as - ports-mgmt/poudriere or - ports-mgmt/synth. - - Marking an installed package as automatic can be - done using: - - &prompt.root; pkg set -A 1 devel/cmake - - Once a package is a leaf package and is marked - as automatic, it gets selected by - pkg autoremove. - - Marking an installed package as not - automatic can be done using: - - &prompt.root; pkg set -A 0 devel/cmake - - - - - Restoring the Package Database - - Unlike the traditional package management system, - pkg includes its own package - database backup mechanism. This functionality is enabled by - default. - - - To disable the periodic script from backing up the - package database, set - daily_backup_pkgdb_enable="NO" in - &man.periodic.conf.5;. - - - To restore the contents of a previous package database - backup, run the following command replacing - /path/to/pkg.sql with the location - of the backup: - - &prompt.root; pkg backup -r /path/to/pkg.sql - - - If restoring a backup taken by the periodic script, - it must be decompressed prior to being restored. - - - To run a manual backup of the - pkg database, run the following - command, replacing /path/to/pkg.sql - with a suitable file name and location: - - &prompt.root; pkg backup -d /path/to/pkg.sql - - - - Removing Stale Packages - - By default, pkg stores - binary packages in a cache directory defined by - PKG_CACHEDIR in &man.pkg.conf.5;. Only copies - of the latest installed packages are kept. Older versions of - pkg kept all previous packages. To - remove these outdated binary packages, run: - - &prompt.root; pkg clean - - The entire cache may be cleared by running: - - &prompt.root; pkg clean -a - - - - Modifying Package Metadata - - Software within the &os; Ports Collection can - undergo major version number changes. To address this, - pkg has a built-in command to - update package origins. This can be useful, for example, if - lang/php5 is renamed to - lang/php53 so that - lang/php5 can now - represent version 5.4. - - To change the package origin for the above example, - run: - - &prompt.root; pkg set -o lang/php5:lang/php53 - - As another example, to update - lang/ruby18 to - lang/ruby19, run: - - &prompt.root; pkg set -o lang/ruby18:lang/ruby19 - - As a final example, to change the origin of the - libglut shared libraries from - graphics/libglut to - graphics/freeglut, run: - - &prompt.root; pkg set -o graphics/libglut:graphics/freeglut - - - When changing package origins, it is important to - reinstall packages that are dependent on the package with - the modified origin. To force a reinstallation of dependent - packages, run: - - &prompt.root; pkg install -Rf graphics/freeglut - - - - - - Using the Ports Collection - - The Ports Collection is a set of - Makefiles, patches, and description files. - Each set of these files is used to compile and install an - individual application on &os;, and is called a - port. - - By default, the Ports Collection itself is stored as a - subdirectory of /usr/ports. - - Before an application can be compiled using a port, the - Ports Collection must first be installed. If it was not - installed during the installation of &os;, use one of the - following methods to install it: - - - Portsnap Method - - The base system of &os; includes - Portsnap. This is a fast and - user-friendly tool for retrieving the Ports Collection and - is the recommended choice for most users not running - &os.current;. This utility - connects to a &os; site, verifies the secure key, and - downloads a new copy of the Ports Collection. The key is used - to verify the integrity of all downloaded files. - - - To download a compressed snapshot of the Ports - Collection into - /var/db/portsnap: - - &prompt.root; portsnap fetch - - - - When running Portsnap for the - first time, extract the snapshot into - /usr/ports: - - &prompt.root; portsnap extract - - - - After the first use of - Portsnap has been completed as - shown above, /usr/ports can be updated - as needed by running: - - &prompt.root; portsnap fetch -&prompt.root; portsnap update - - When using fetch, the - extract or the update - operation may be run consecutively, like so: - - &prompt.root; portsnap fetch update - - - - - Subversion Method - - If more control over the ports tree is needed or if local - changes need to be maintained, or if running &os.current;, - Subversion can be used to obtain - the Ports Collection. Refer to the - Subversion Primer for a detailed description of - Subversion. - - - Subversion must be installed - before it can be used to check out the ports tree. If a - copy of the ports tree is already present, install - Subversion like this: - - &prompt.root; cd /usr/ports/devel/subversion -&prompt.root; make install clean - - If the ports tree is not available, or - pkg is being used to manage - packages, Subversion can be - installed as a package: - - &prompt.root; pkg install subversion - - - - - Check out a copy of the ports tree: - - &prompt.root; svn checkout https://svn.FreeBSD.org/ports/head /usr/ports - - - - As needed, update /usr/ports after - the initial Subversion - checkout: - - &prompt.root; svn update /usr/ports - - - - The Ports Collection contains directories - for software categories. Inside each category are - subdirectories for individual applications. Each application - subdirectory contains a set of files that - tells &os; how to compile and install that program, - called a ports skeleton. Each port - skeleton includes these files and directories: - - - - Makefile: contains statements that - specify how the application should be compiled and where - its components should be installed. - - - - distinfo: contains the names and - checksums of the files that must be downloaded 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. - - - - pkg-descr: provides a more detailed - description of the program. - - *** 865 LINES SKIPPED ***