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. - - - - 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 . - - - -