Differential D40258 Diff 122381 documentation/content/en/books/handbook/ports/_index.adoc

Changeset View

Standalone View

documentation/content/en/books/handbook/ports/_index.adoc

	Show First 20 Lines • Show All 951 Lines • ▼ Show 20 Lines

	[[ports-upgrading-tools]]			[[ports-upgrading-tools]]
	==== Tools to Upgrade and Manage Ports			==== Tools to Upgrade and Manage Ports

	The Ports Collection contains several utilities to perform the actual upgrade.			The Ports Collection contains several utilities to perform the actual upgrade.
	Each has its strengths and weaknesses.			Each has its strengths and weaknesses.

	Historically, most installations used either Portmaster or Portupgrade.			Historically, most installations used either Portmaster or Portupgrade.
	Synth is a newer alternative.			Poudriere is the tool used by the package builders, while Synth is an alternative.

	[NOTE]			[NOTE]
	====			====
	The choice of which tool is best for a particular system is up to the system administrator.			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.			It is recommended practice to back up your data before using any of these tools.
	====			====

	[[portmaster]]
	==== Upgrading Ports Using Portmaster

	package:ports-mgmt/portmaster[] is a very small utility for upgrading installed ports.
	It is designed to use the tools installed with the FreeBSD base system without depending on other ports or databases.
	To install this utility as a port:

	[source,shell]
	....
	# cd /usr/ports/ports-mgmt/portmaster
	# 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:

	[source,shell]
	....
	# 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:

	[source,shell]
	....
	# portmaster -a
	....

	[NOTE]
	====
	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 `-b` instructs Portmaster not to automatically delete the backup.
	Adding `-i` 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 `-f` to upgrade and rebuild all ports:

	[source,shell]
	....
	# 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:

	[source,shell]
	....
	# portmaster shells/bash
	....

	More information about package:ports-mgmt/portmaster[] may be found in its `pkg-descr`.

	[[portupgrade]]
	==== Upgrading Ports Using Portupgrade

	package: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:

	[source,shell]
	....
	# cd /usr/ports/ports-mgmt/portupgrade
	# 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 `-i` to be asked for confirmation of every individual upgrade:

	[source,shell]
	....
	# portupgrade -ai
	....

	To upgrade only a specified application instead of all available ports, use `portupgrade _pkgname_`.
	It is very important to include `-R` to first upgrade all the ports required by the given application:

	[source,shell]
	....
	# portupgrade -R firefox
	....

	If `-P` 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 `-PP`.
	This last set of options tells Portupgrade to abort if no packages are available:

	[source,shell]
	....
	# portupgrade -PP gnome3
	....

	To just fetch the port distfiles, or packages, if `-P` is specified, without building or installing anything, use `-F`.
	For further information on all of the available switches, refer to the manual page for `portupgrade`.

	More information about package:ports-mgmt/portupgrade[] may be found in its `pkg-descr`.

	[[ports-disk-space]]			[[ports-disk-space]]
	=== Ports and Disk Space			=== Ports and Disk Space

	Using the Ports Collection will use up disk space over time.			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.			After building and installing a port, running `make clean` within the ports skeleton will clean up the temporary `work` directory.
				pauamma_gundo.comUnsubmitted Not Done Inline Actions This doesn't explain how to remove all work directories, only that of a single port (and its dependencies, although that's left unsaid). Since some of the text removed (`portsclean -C`) did that, maybe mention running `make clean` in the root of the ports tree? Could be a follow-up review. pauamma_gundo.com: This doesn't explain how to remove all work directories, only that of a single port (and its…
				fernapeUnsubmitted Not Done Inline Actions Yes, it should be from the root or the sentence should specify that `make clean` cleans working directories recursively. fernape: Yes, it should be from the root or the sentence should specify that `make clean` cleans working…
				vishwinAuthorUnsubmitted Done Inline Actions Yeah I wanted to see what we have left after removing those sections entirely. Some revising to have `make clean` and even distfile management (because some of them are disk space hogs too) make sense is needed and should be part of this review. vishwin: Yeah I wanted to see what we have left after removing those sections entirely. Some revising to…
	If Portmaster is used to install a port, it will automatically remove this directory unless `-K` is specified.
	If Portupgrade is installed, this command will remove all `work` directories found within the local copy of the Ports Collection:

	[source,shell]
	....
	# 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:

	[source,shell]
	....
	# portsclean -D
	....

	Portupgrade can remove all distfiles not referenced by any port currently installed on the system:

	[source,shell]
	....
	# portsclean -DD
	....

	If Portmaster is installed, use:

	[source,shell]
	....
	# 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, package:ports-mgmt/pkg_cutleaves[] automates the task of removing installed ports that are no longer needed.

	[[ports-poudriere]]			[[ports-poudriere]]
	== Building Packages with Poudriere			== Building Packages with Poudriere

	Poudriere is a `BSD`-licensed utility for creating and testing FreeBSD packages.			Poudriere is a `BSD`-licensed utility for creating and testing FreeBSD packages.
	It uses FreeBSD jails to set up isolated compilation environments.			It uses FreeBSD jails to set up isolated compilation environments.
	These jails can be used to build packages for versions of FreeBSD that are different from the system on which it is installed, and also to build packages for i386 if the host is an amd64 system.			These jails can be used to build packages for versions of FreeBSD that are different from the system on which it is installed, and also to build packages for i386 if the host is an amd64 system.
	Once the packages are built, they are in a layout identical to the official mirrors.			Once the packages are built, they are in a layout identical to the official mirrors.
	▲ Show 20 Lines • Show All 196 Lines • Show Last 20 Lines