From owner-dev-commits-doc-all@freebsd.org Sat May 1 16:54:35 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 E2CCA631CD9 for ; Sat, 1 May 2021 16:54:35 +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 4FXb1l5pcwz4hlZ; Sat, 1 May 2021 16:54:35 +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 BA3361B586; Sat, 1 May 2021 16:54:35 +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 141GsZBe044666; Sat, 1 May 2021 16:54:35 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 141GsZUx044665; Sat, 1 May 2021 16:54:35 GMT (envelope-from git) Date: Sat, 1 May 2021 16:54:35 GMT Message-Id: <202105011654.141GsZUx044665@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Ryusuke SUZUKI Subject: git: ff3df39394 - main - a67af5a97b -> e633f0b9df 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: ff3df39394cc4faf4300a4b19954f93a0fd46868 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 16:54:35 -0000 The branch main has been updated by ryusuke: URL: https://cgit.FreeBSD.org/doc/commit/?id=ff3df39394cc4faf4300a4b19954f93a0fd46868 commit ff3df39394cc4faf4300a4b19954f93a0fd46868 Author: Ryusuke SUZUKI AuthorDate: 2021-05-01 16:51:45 +0000 Commit: Ryusuke SUZUKI CommitDate: 2021-05-01 16:51:45 +0000 a67af5a97b -> e633f0b9df --- en_US.ISO8859-1/books/handbook/ports/chapter.xml | 1831 ++++++++++++++++++++++ website/data/ja/news/news.toml | 8 + 2 files changed, 1839 insertions(+) diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml new file mode 100644 index 0000000000..110d47f3b6 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml @@ -0,0 +1,1831 @@ + + + + + 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. + *** 892 LINES SKIPPED ***