From ff3df39394cc4faf4300a4b19954f93a0fd46868 Mon Sep 17 00:00:00 2001 From: Ryusuke SUZUKI Date: Sun, 2 May 2021 01:51:45 +0900 Subject: a67af5a97b -> e633f0b9df --- en_US.ISO8859-1/books/handbook/ports/chapter.xml | 1831 ++++++++++++++++++++++ 1 file changed, 1831 insertions(+) create mode 100644 en_US.ISO8859-1/books/handbook/ports/chapter.xml (limited to 'en_US.ISO8859-1') 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. + + + + pkg-plist: a list of all the + files that will be installed by the port. It also tells + the ports system which files to remove upon + deinstallation. + + + + 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. The extract portion + of building a port will automatically save the downloaded + source to /usr/ports/distfiles. + + + 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 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, + run pkg audit -F before 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 &man.pkg-audit.8; and + &man.periodic.8;. + + + Using the Ports Collection assumes a working Internet + connection. It also requires superuser privilege. + + 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.88 +... +[extraction output snipped] +... +>> 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.88.d,8 +... +[compilation output snipped] +... + +===> Installing for lsof-4.88.d,8 +... +[installation output snipped] +... +===> Generating temporary packing list +===> 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; + + Since lsof is a program that runs + with increased privileges, a security warning is displayed + as it is installed. Once the installation is complete, the + prompt will be returned. + + 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. Removing this directory saves disk space and + minimizes the chance of problems later when upgrading to the + newer version of the port: + + &prompt.root; make clean +===> Cleaning for lsof-88.d,8 +&prompt.root; + + + To save this extra step, instead use make + install clean when compiling the port. + + + + Customizing Ports Installation + + 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 depends + upon other ports which have 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 and do all of the configuration in one + batch, run make config-recursive within + the port skeleton. Then, run make install + [clean] to compile and install the port. + + + When using + config-recursive, the list of + ports to configure are gathered by the + all-depends-list target. It is + recommended to run make + config-recursive until all dependent ports + options have been defined, and ports options screens no + longer appear, to be certain that all dependency options + have been configured. + + + 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 + source files, which supports various environment variables. + The FTP_PASSIVE_MODE, + FTP_PROXY, and 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 of supported variables. + + 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. Instead, use make + fetch-recursive to also fetch the distfiles for + all the dependencies of a port. + + 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.organization.org/pub/FreeBSD/ports/distfiles/ fetch + + The WRKDIRPREFIX and + PREFIX variables can override the default + working and target directories. For example: + + &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install + + will compile the port in + /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 + and install it in + /usr/home/example/local. And: + + &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install + + will combine the two. + + 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. + + + + + Removing Installed Ports + + + ports + removing + + + Installed ports can be uninstalled using pkg + delete. Examples for using this command can be + found in the &man.pkg-delete.8; manual page. + + Alternately, make deinstall can be + run in the port's directory: + + &prompt.root; cd /usr/ports/sysutils/lsof +&prompt.root; 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. + + + + Upgrading Ports + + + ports + upgrading + + + Over time, newer versions of software become available + in the Ports Collection. This section describes how to + determine which software can be upgraded and how to perform + the upgrade. + + To determine if newer versions of installed ports are + available, ensure that the latest version of the ports tree is + installed, using the updating command described in either + or + . On &os; 10 + and later, or if the system has been converted to + pkg, the following command will + list the installed ports which are out of date: + + &prompt.root; pkg version -l "<" + + For &os; 9.X and lower, the + following command will list the installed ports that are out + of date: + + &prompt.root; pkg_version -l "<" + + + Before + attempting an upgrade, read + /usr/ports/UPDATING from the top of + the file to the date closest to the last time ports were + upgraded or the system was installed. This file describes + various issues and additional steps users may encounter and + need to perform when updating a port, including such things + as file format changes, changes in locations of + configuration files, or any incompatibilities with previous + versions. Make note of any instructions which match any of + the ports that need upgrading and follow these instructions + when performing the upgrade. + + + + Tools to Upgrade and Manage Ports + + + ports + upgrading-tools + + + The Ports Collection contains several utilities to + perform the actual upgrade. Each has its strengths and + weaknesses. + + Historically, most installations used either + Portmaster or + Portupgrade. + Synth is a newer + alternative. + + + The choice of which tool is best for a particular + system is up to the system administrator. It is + recommended practice to back up your data before using any + of these tools. + + + + + + Upgrading Ports Using + <application>Portmaster</application> + + + portmaster + + + ports-mgmt/portmaster is a very + small utility for upgrading installed ports. + It is designed to use the tools installed with the &os; + base system + without depending on other ports or databases. + To install this utility + as a port: + + &prompt.root; cd /usr/ports/ports-mgmt/portmaster +&prompt.root; make install clean + + Portmaster defines four + categories of ports: + + + + Root port: has no dependencies and is not a + dependency of any other ports. + + + + Trunk port: has no dependencies, but other ports + depend upon it. + + + + Branch port: has dependencies and other ports + depend upon it. + + + + Leaf port: has dependencies but no other ports + depend upon it. + + + + To list these categories and search for updates: + + &prompt.root; portmaster -L +===>>> Root ports (No dependencies, not depended on) +===>>> ispell-3.2.06_18 +===>>> screen-4.0.3 + ===>>> New version available: screen-4.0.3_1 +===>>> tcpflow-0.21_1 +===>>> 7 root ports +... +===>>> Branch ports (Have dependencies, are depended on) +===>>> apache22-2.2.3 + ===>>> New version available: apache22-2.2.8 +... +===>>> Leaf ports (Have dependencies, not depended on) +===>>> automake-1.9.6_2 +===>>> bash-3.1.17 + ===>>> New version available: bash-3.2.33 +... +===>>> 32 leaf ports + +===>>> 137 total installed ports + ===>>> 83 have new versions available + + This command is used to upgrade all outdated + ports: + + &prompt.root; portmaster -a + + + By default, Portmaster + makes a backup package before deleting the existing port. + If the installation of the new version is successful, + Portmaster deletes the + backup. Using instructs + Portmaster not to automatically + delete the backup. Adding starts + Portmaster in interactive mode, + prompting for confirmation before upgrading each port. + Many other options are available. Read through the + manual page for &man.portmaster.8; for details regarding + their usage. + + + If errors are encountered during the upgrade process, + add to upgrade and rebuild all + ports: + + &prompt.root; portmaster -af + + Portmaster can also be used + to install new ports on the system, upgrading all + dependencies before building and installing the new + port. To use this function, specify the location of the + port in the Ports Collection: + + &prompt.root; portmaster shells/bash + + More information about + ports-mgmt/portmaster may be found in its + pkg-descr. + + + + Upgrading Ports Using Portupgrade + + + portupgrade + + + ports-mgmt/portupgrade is another + utility that can be used to upgrade ports. It installs a + suite of applications which can be used to manage ports. + However, it is dependent upon Ruby. To install the + port: + + &prompt.root; cd /usr/ports/ports-mgmt/portupgrade +&prompt.root; make install clean + + Before performing an upgrade using this utility, it is + recommended to scan the list of installed ports using + pkgdb -F and to fix all the + inconsistencies it reports. + + To upgrade all the outdated ports installed on the + system, use portupgrade -a. Alternately, + include to be asked for confirmation + of every individual upgrade: + + &prompt.root; portupgrade -ai + + To upgrade only a specified application instead of all + available ports, use portupgrade + pkgname. It is very + important to include to first upgrade + all the ports required by the given application: + + &prompt.root; portupgrade -R firefox + + If + is included, + Portupgrade searches for + available packages in the local directories listed in + PKG_PATH. If none are available locally, it + then fetches packages from a remote site. If packages can + not be found locally or fetched remotely, + Portupgrade will use ports. To + avoid using ports entirely, specify . + This last set of options tells + Portupgrade to abort if no + packages are available: + + &prompt.root; portupgrade -PP gnome3 + + To just fetch the port distfiles, or packages, if + is specified, without building or + installing anything, use . For further + information on all of the available switches, refer to the + manual page for portupgrade. + + More information about + ports-mgmt/portupgrade may be found in + its pkg-descr. + + + + + + Ports and Disk Space + + + ports + disk-space + + + Using the Ports Collection will use up disk space over + time. After building and installing a port, running + make clean within the ports skeleton will + clean up the temporary work directory. + If Portmaster is used to install a + port, it will automatically remove this directory unless + is specified. If + Portupgrade is installed, this + command will remove all work directories + found within the local copy of the Ports Collection: + + &prompt.root; portsclean -C + + In addition, outdated source distribution files + accumulate in /usr/ports/distfiles over + time. To use Portupgrade to + delete all the distfiles that are no longer + referenced by any ports: + + &prompt.root; portsclean -D + + Portupgrade can remove + all distfiles not referenced by any port currently installed + on the system: + + &prompt.root; portsclean -DD + + If Portmaster is installed, + use: + + &prompt.root; portmaster --clean-distfiles + + By default, this command is interactive and prompts + the user to confirm if a distfile should be deleted. + + In addition to these commands, + ports-mgmt/pkg_cutleaves + automates the task of removing installed ports that are no + longer needed. + + + + + Building Packages with + <application>Poudriere</application> + + Poudriere is a + BSD-licensed utility for creating and testing + &os; packages. It uses &os; jails to set up isolated + compilation environments. These jails can be used to build + packages for versions of &os; that are different from the system + on which it is installed, and also to build packages for i386 if + the host is an &arch.amd64; system. Once the packages are + built, they are in a layout identical to the official mirrors. + These packages are usable by &man.pkg.8; and other package + management tools. + + Poudriere is installed using + the ports-mgmt/poudriere package + or port. The installation includes a sample configuration + file /usr/local/etc/poudriere.conf.sample. + Copy this file to + /usr/local/etc/poudriere.conf. Edit the + copied file to suit the local configuration. + + While ZFS is not required on the system + running poudriere, it is beneficial. + When ZFS is used, + ZPOOL must be specified in + /usr/local/etc/poudriere.conf and + FREEBSD_HOST should be set to a nearby + mirror. Defining CCACHE_DIR enables the use + of devel/ccache to cache + compilation and reduce build times for frequently-compiled code. + It may be convenient to put + poudriere datasets in an isolated + tree mounted at /poudriere. Defaults for the + other configuration values are adequate. + + The number of processor cores detected is used to define how + many builds will run in parallel. Supply enough virtual memory, + either with RAM or swap space. If virtual + memory runs out, the compilation jails will stop and be torn + down, resulting in weird error messages. + + + Initialize Jails and Port Trees + + After configuration, initialize + poudriere so that it installs a + jail with the required &os; tree and a ports tree. Specify a + name for the jail using and the &os; + version with . On systems running + &os;/&arch.amd64;, the architecture can be set with + to either i386 or + amd64. The default is the + architecture shown by uname. + + &prompt.root; poudriere jail -c -j 11amd64 -v 11.4-RELEASE +[00:00:00] Creating 11amd64 fs at /poudriere/jails/11amd64... done +[00:00:00] Using pre-distributed MANIFEST for FreeBSD 11.4-RELEASE amd64 +[00:00:00] Fetching base for FreeBSD 11.4-RELEASE amd64 +/poudriere/jails/11amd64/fromftp/base.txz 125 MB 4110 kBps 31s +[00:00:33] Extracting base... done +[00:00:54] Fetching src for FreeBSD 11.4-RELEASE amd64 +/poudriere/jails/11amd64/fromftp/src.txz 154 MB 4178 kBps 38s +[00:01:33] Extracting src... done +[00:02:31] Fetching lib32 for FreeBSD 11.4-RELEASE amd64 +/poudriere/jails/11amd64/fromftp/lib32.txz 24 MB 3969 kBps 06s +[00:02:38] Extracting lib32... done +[00:02:42] Cleaning up... done +[00:02:42] Recording filesystem state for clean... done +[00:02:42] Upgrading using ftp +/etc/resolv.conf -> /poudriere/jails/11amd64/etc/resolv.conf +Looking up update.FreeBSD.org mirrors... 3 mirrors found. +Fetching public key from update4.freebsd.org... done. +Fetching metadata signature for 11.4-RELEASE from update4.freebsd.org... done. +Fetching metadata index... done. +Fetching 2 metadata files... done. +Inspecting system... done. +Preparing to download files... done. +Fetching 124 patches.....10....20....30....40....50....60....70....80....90....100....110....120.. done. +Applying patches... done. +Fetching 6 files... done. +The following files will be added as part of updating to +11.4-RELEASE-p1: +/usr/src/contrib/unbound/.github +/usr/src/contrib/unbound/.github/FUNDING.yml +/usr/src/contrib/unbound/contrib/drop2rpz +/usr/src/contrib/unbound/contrib/unbound_portable.service.in +/usr/src/contrib/unbound/services/rpz.c +/usr/src/contrib/unbound/services/rpz.h +/usr/src/lib/libc/tests/gen/spawnp_enoexec.sh +The following files will be updated as part of updating to +11.4-RELEASE-p1: +[…] +Installing updates...Scanning //usr/share/certs/blacklisted for certificates... +Scanning //usr/share/certs/trusted for certificates... + done. +11.4-RELEASE-p1 +[00:04:06] Recording filesystem state for clean... done +[00:04:07] Jail 11amd64 11.4-RELEASE-p1 amd64 is ready to be used + + &prompt.root; poudriere ports -c -p local -m svn+https +[00:00:00] Creating local fs at /poudriere/ports/local... done +[00:00:00] Checking out the ports tree... done + + On a single computer, poudriere + can build ports with multiple configurations, in multiple + jails, and from different port trees. Custom configurations + for these combinations are called sets. + See the CUSTOMIZATION section of &man.poudriere.8; for details + after ports-mgmt/poudriere or + ports-mgmt/poudriere-devel is + installed. + + The basic configuration shown here puts a single jail-, + port-, and set-specific make.conf in + /usr/local/etc/poudriere.d. + The filename in this example is created by combining the jail + name, port name, and set name: + 11amd64-local-workstation-make.conf. + The system make.conf and this new file + are combined at build time to create the + make.conf used by the build jail. + + Packages to be built are entered in + 11amd64-local-workstation-pkglist: + + editors/emacs +devel/git +ports-mgmt/pkg +... + + Options and dependencies for the specified ports are + configured: + + &prompt.root; poudriere options -j 11amd64 -p local -z workstation -f 11amd64-local-workstation-pkglist + + Finally, packages are built and a package + repository is created: + + &prompt.root; poudriere bulk -j 11amd64 -p local -z workstation -f 11amd64-local-workstation-pkglist + + While running, pressing Ctrlt + displays the current state of the build. + Poudriere also builds files in + /poudriere/logs/bulk/jailname + that can be used with a web server to display build + information. + + After completion, the new packages are now available for + installation from the poudriere + repository. + + For more information on using + poudriere, see &man.poudriere.8; + and the main web site, . + + + Configuring pkg Clients to Use a Poudriere + Repository + + While it is possible to use both a custom repository along + side of the official repository, sometimes it is useful to + disable the official repository. This is done by creating a + configuration file that overrides and disables the official + configuration file. Create + /usr/local/etc/pkg/repos/FreeBSD.conf + that contains the following: + + FreeBSD: { + enabled: no +} + + Usually it is easiest to serve a poudriere repository to + the client machines via HTTP. Set up a webserver to serve up + the package directory, for instance: + /usr/local/poudriere/data/packages/11amd64, + where 11amd64 + is the name of the build. + + If the URL to the package repository is: + http://pkg.example.com/11amd64, then the + repository configuration file in + /usr/local/etc/pkg/repos/custom.conf + would look like: + + custom: { + url: "http://pkg.example.com/11amd64", + enabled: yes, +} + + + + + Post-Installation Considerations + + Regardless of whether the software was installed from a + binary package or port, most third-party applications require + some level of configuration after installation. The following + commands and locations can be used to help determine what was + installed with the application. + + + + Most applications install at least one default + configuration file in /usr/local/etc. + In cases where an application has a large number of + configuration files, a subdirectory will be created to hold + them. Often, sample configuration files are installed which + end with a suffix such as .sample. The + configuration files should be reviewed and possibly + edited to meet the system's needs. To edit a sample file, + first copy it without the .sample + extension. + + + + Applications which provide documentation will install + it into /usr/local/share/doc and many + applications also install manual pages. This documentation + should be consulted before continuing. + + + + Some applications run services which must be added + to /etc/rc.conf before starting the + application. These applications usually install a startup + script in /usr/local/etc/rc.d. See + Starting + Services for more information. + + + By design, applications do not run their startup + script upon installation, nor do they run their stop + script upon deinstallation or upgrade. This decision + is left to the individual system administrator. + + + + + + Users of &man.csh.1; should run + rehash to rebuild the known binary list + in the shells PATH. + + + + Use pkg info to determine which + files, man pages, and binaries were installed with the + application. + + + + + + Dealing with Broken Ports + + When a port does not build or + install, try the following: + + + + Search to see if there is a fix pending for the port in + the Problem + Report database. If so, implementing the proposed + fix may fix the issue. + + + + Ask the maintainer of the port for help. Type + make maintainer + in the ports skeleton or read the port's + Makefile to find the maintainer's + email address. Remember to include the + $FreeBSD: line from the port's + Makefile and the output leading up to + the error in the email to the maintainer. + + + Some ports are not maintained by an individual but + instead by a group maintainer represented by a mailing + list. Many, but not all, of these addresses look + like freebsd-listname@FreeBSD.org. + Please take this into account when sending an + email. + + In particular, ports maintained by + ports@FreeBSD.org are not + maintained by a specific individual. Instead, any fixes + and support come from the general community who subscribe + to that mailing list. More volunteers are always + needed! + + + If there is no response to the email, use + Bugzilla to submit a bug report using the + instructions in Writing + &os; Problem Reports. + + + + Fix it! The Porter's + Handbook includes detailed information on the + ports infrastructure so that you can fix the occasional + broken port or even submit your own! + + + + Install the package instead of the port using the + instructions in . + + + + -- cgit v1.2.3