Differential D40134 Diff 122043 documentation/content/en/books/porters-handbook/testing/_index.adoc

Changeset View

Standalone View

documentation/content/en/books/porters-handbook/testing/_index.adoc

	Show First 20 Lines • Show All 73 Lines • ▼ Show 20 Lines

	Portfmt is a tool for automatically formatting [.filename]#Makefile#.			Portfmt is a tool for automatically formatting [.filename]#Makefile#.

	[[testing-portlint]]			[[testing-portlint]]
	== Portlint			== Portlint

	Do check the port with crossref:quick-porting[porting-portlint,`portlint`] before submitting or committing it.			Do check the port with crossref:quick-porting[porting-portlint,`portlint`] before submitting or committing it.
	`portlint` warns about many common errors, both functional and stylistic.			`portlint` warns about many common errors, both functional and stylistic.
	For a new (or repocopied) port, `portlint -A` is the most thorough; for an existing port, `portlint -C` is sufficient.			For a new port, `portlint -A` is the most thorough; for an existing port, `portlint -C` is sufficient.

	Since `portlint` uses heuristics to try to figure out errors, it can produce false positive warnings.			Since `portlint` uses heuristics to try to figure out errors, it can produce false positive warnings.
	In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework.			In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework.
				pass:[<!-- vale Vale.Terms = NO -->]
	When in doubt, the best thing to do is ask on {freebsd-ports}.			When in doubt, the best thing to do is ask on {freebsd-ports}.
				pass:[<!-- vale Vale.Terms = YES -->]

	[[testing-porttools]]			[[testing-porttools]]
	== Port Tools			== Port Tools

	The package:ports-mgmt/porttools[] program is part of the Ports Collection.			The package:ports-mgmt/porttools[] program is part of the Ports Collection.

	`port` is the front-end script, which can help simplify the testing job.			`port` is the front-end script, which can help simplify the testing job.
	Whenever a new port or an update to an existing one needs testing, use `port test` to test the port, including the <<testing-portlint,`portlint`>> checking.			Whenever a new port or an update to an existing one needs testing, use `port test` to test the port, including the <<testing-portlint,`portlint`>> checking.
	This command also detects and lists any files that are not listed in [.filename]#pkg-plist#. For example:			This command also detects and lists any files that are not listed in [.filename]#pkg-plist#.
				For example:

	[source,shell]			[source,shell]
	....			....
	# port test /usr/ports/net/csup			# port test /usr/ports/net/csup
	....			....

	[[porting-prefix]]			[[porting-prefix]]
	== `PREFIX` and `DESTDIR`			== `PREFIX` and `DESTDIR`
	Show All 30 Lines
	....			....
	% make stage && make check-plist && make stage-qa && make package			% make stage && make check-plist && make stage-qa && make package
	....			....

	* `check-plist` checks for files missing from the plist, and files in the plist that are not installed by the port.			* `check-plist` checks for files missing from the plist, and files in the plist that are not installed by the port.
	* `stage-qa` checks for common problems like bad shebang, symlinks pointing outside the stage directory, setuid files, and non-stripped libraries...			* `stage-qa` checks for common problems like bad shebang, symlinks pointing outside the stage directory, setuid files, and non-stripped libraries...

	These tests will not find hard-coded paths inside the port's files, nor will it verify that `LOCALBASE` is being used to correctly refer to files from other ports.			These tests will not find hard-coded paths inside the port's files, nor will it verify that `LOCALBASE` is being used to correctly refer to files from other ports.
	The temporarily-installed port in [.filename]#/var/tmp/`make -V PORTNAME`# must be tested for proper operation to make sure there are no problems with paths.			The temporarily installed port in [.filename]#/var/tmp/`make -V PORTNAME`# must be tested for proper operation to make sure there are no problems with paths.

	`PREFIX` must not be set explicitly in a port's [.filename]#Makefile#.			`PREFIX` must not be set explicitly in a port's [.filename]#Makefile#.
	Users installing the port may have set `PREFIX` to a custom location, and the port must respect that setting.			Users installing the port may have set `PREFIX` to a custom location, and the port must respect that setting.

	Refer to programs and files from other ports with the variables mentioned above, not explicit pathnames.			Refer to programs and files from other ports with the variables mentioned above, not explicit pathnames.
	For instance, if the port requires a macro `PAGER` to have the full pathname of `less`, do not use a literal path of [.filename]#/usr/local/bin/less#.			For instance, if the port requires a macro `PAGER` to have the full pathname of `less`, do not use a literal path of [.filename]#/usr/local/bin/less#.
	Instead, use `${LOCALBASE}`:			Instead, use `${LOCALBASE}`:

	[.programlisting]			[.programlisting]
	....			....
	-DPAGER=\"${LOCALBASE}/bin/less\"			-DPAGER=\"${LOCALBASE}/bin/less\"
	....			....

	The path with `LOCALBASE` is more likely to still work if the system administrator has moved the whole [.filename]#/usr/local# tree somewhere else.			The path with `LOCALBASE` is more likely to still work if the system administrator has moved the whole [.filename]#/usr/local# tree somewhere else.

	[TIP]			[TIP]
	====			====
	All these tests are done automatically when running `poudriere testport` or `poudriere bulk -t`.			All these tests are done automatically when running `poudriere testport` or `poudriere bulk -t`.
	It is highly recommended that every ports contributor install and test their ports with it.			It is highly recommended that every ports contributor install and test their ports with it.
	See <<testing-poudriere>> for more information.			See <<testing-poudriere>> for more information.
	====			====

	[[testing-poudriere]]			[[testing-poudriere]]
	== Poudriere			== poudriere

	For a ports contributor, Poudriere is one of the most important and helpful testing and build tools.			For a ports contributor, poudriere is one of the most important and helpful testing and build tools.
	Its main features include:			Its main features include:

	* Bulk building of the entire ports tree, specific subsets of the ports tree, or a single port including its dependencies			* Bulk building of the entire ports tree, specific subsets of the ports tree, or a single port including its dependencies
	* Automatic packaging of build results			* Automatic packaging of build results
	* Generation of build log files per port			* Generation of build log files per port
	* Providing a signed man:pkg[8] repository			* Providing a signed man:pkg[8] repository
	* Testing of port builds before submitting a patch to the FreeBSD bug tracker or committing to the ports tree			* Testing of port builds before submitting a patch to the FreeBSD bug tracker or committing to the ports tree
	* Testing for successful ports builds using different options			* Testing for successful ports builds using different options

	Because Poudriere performs its building in a clean man:jail[8] environment and uses man:zfs[8] features,			Because poudriere performs its building in a clean man:jail[8] environment and uses man:zfs[8] features,
	it has several advantages over traditional testing on the host system:			it has several advantages over traditional testing on the host system:

	* No pollution of the host environment: No leftover files, no accidental removals, no changes of existing configuration files.			* No pollution of the host environment: No leftover files, no accidental removals, no changes of existing configuration files.
	* Verify [.filename]#pkg-plist# for missing or superfluous entries			* Verify [.filename]#pkg-plist# for missing or superfluous entries
	* Ports committers sometimes ask for a Poudriere log alongside a patch submission to assess whether the patch is ready for integration into the ports tree			* Ports committers sometimes ask for a poudriere log alongside a patch submission to assess whether the patch is ready for integration into the ports tree

	It is also quite straightforward to set up and use, has no dependencies, and will run on any supported FreeBSD release.			It is also quite straightforward to set up and use, has no dependencies, and will run on any supported FreeBSD release.
	This section shows how to install, configure, and run Poudriere as part of the normal workflow of a ports contributor.			This section shows how to install, configure, and run poudriere as part of the normal workflow of a ports contributor.

	The examples in this section show a default file layout, as standard in FreeBSD.			The examples in this section show a default file layout, as standard in FreeBSD.
	Substitute any local changes accordingly.			Substitute any local changes accordingly.
	The ports tree, represented by `${PORTSDIR}`, is located in [.filename]#/usr/ports#.			The ports tree, represented by `${PORTSDIR}`, is located in [.filename]#/usr/ports#.
	Both `${LOCALBASE}` and `${PREFIX}` are [.filename]#/usr/local# by default.			Both `${LOCALBASE}` and `${PREFIX}` are [.filename]#/usr/local# by default.

	[[testing-poudriere-installing]]			[[testing-poudriere-installing]]
	=== Installing Poudriere			=== Installing poudriere

	Poudriere is available in the ports tree in package:ports-mgmt/poudriere[].			poudriere is available in the ports tree in package:ports-mgmt/poudriere[].
	It can be installed using man:pkg[8] or from ports:			It can be installed using man:pkg[8] or from ports:

	[source,shell]			[source,shell]
	....			....
	# pkg install poudriere			# pkg install poudriere
	....			....

	or			or

	[source,shell]			[source,shell]
	....			....
	# make -C /usr/ports/ports-mgmt/poudriere install clean			# make -C /usr/ports/ports-mgmt/poudriere install clean
	....			....

	There is also a work-in-progress version of Poudriere which will eventually become the next release.			There is also a work-in-progress version of poudriere which will eventually become the next release.
	It is available in package:ports-mgmt/poudriere-devel[].			It is available in package:ports-mgmt/poudriere-devel[].
	This development version is used for the official FreeBSD package builds, so it is well tested.			This development version is used for the official FreeBSD package builds, so it is well tested.
	It often has newer interesting features.			It often has newer interesting features.
	A ports committer will want to use the development version because it is what is used in production, and has all the new features that will make sure everything is exactly right.			A ports committer will want to use the development version because it is what is used in production, and has all the new features that will make sure everything is exactly right.
	A contributor will not necessarily need those as the most important fixes are backported to released version.			A contributor will not necessarily need those as the most important fixes are backported to released version.
	The main reason for the use of the development version to build the official package is because it is faster,			The main reason for the use of the development version to build the official package is because it is faster,
	in a way that will shorten a full build from 18 hours to 17 hours when using a high end 32 CPU server with 128GB of RAM.			in a way that will shorten a full build from 18 hours to 17 hours when using a high end 32 CPU server with 128GB of RAM.
	Those optimizations will not matter a lot when building ports on a desktop machine.			Those optimizations will not matter a lot when building ports on a desktop machine.

	[[testing-poudriere-setup]]			[[testing-poudriere-setup]]
	=== Setting Up Poudriere			=== Setting Up poudriere

	The port installs a default configuration file, [.filename]#/usr/local/etc/poudriere.conf#.			The port installs a default configuration file, [.filename]#/usr/local/etc/poudriere.conf#.
	Each parameter is documented in the configuration file and in man:poudriere[8].			Each parameter is documented in the configuration file and in man:poudriere[8].
	Here is a minimal example config file:			Here is a minimal example config file:

	[.programlisting]			[.programlisting]
	....			....
	ZPOOL=tank			ZPOOL=tank
	ZROOTFS=/poudriere
	BASEFS=/poudriere			BASEFS=/poudriere
	DISTFILES_CACHE=/usr/ports/distfiles			DISTFILES_CACHE=/usr/ports/distfiles
	RESOLV_CONF=/etc/resolv.conf			RESOLV_CONF=/etc/resolv.conf
	FREEBSD_HOST=ftp://ftp.freebsd.org
	SVN_HOST=svn.FreeBSD.org
	....			....

	`ZPOOL`::			`ZPOOL`::
	The name of the ZFS storage pool which Poudriere shall use.			The name of the ZFS storage pool which poudriere shall use.
	Must be listed in the output of `zpool status`.			Must be listed in the output of `zpool status`.

	`ZROOTFS`::
	The root of Poudriere-managed file systems.
	This entry will cause Poudriere to create man:zfs[8] file systems under `tank/poudriere`.

	`BASEFS`::			`BASEFS`::
	The root mount point for Poudriere file systems.			The root mount point for poudriere file systems.
	This entry will cause Poudriere to mount `tank/poudriere` to `/poudriere`.			This entry will cause poudriere to mount `tank/poudriere` to `/poudriere`.

	`DISTFILES_CACHE`::			`DISTFILES_CACHE`::
	Defines where distfiles are stored.			Defines where distfiles are stored.
	In this example, Poudriere and the host share the distfiles storage directory.			In this example, poudriere and the host share the distfiles storage directory.
	This avoids downloading tarballs which are already present on the system.			This avoids downloading tarballs which are already present on the system.
	Please create this directory if it does not already exist so that Poudriere can find it.			Please create this directory if it does not already exist so that poudriere can find it.

	`RESOLV_CONF`::			`RESOLV_CONF`::
	Use the host [.filename]#/etc/resolv.conf# inside jails for DNS.			Use the host [.filename]#/etc/resolv.conf# inside jails for DNS.
	This is needed so jails can resolve the URLs of distfiles when downloading.			This is needed so jails can resolve the URLs of distfiles when downloading.
	It is not needed when using a proxy.			It is not needed when using a proxy.
	Refer to the default configuration file for proxy configuration.			Refer to the default configuration file for proxy configuration.

	`FREEBSD_HOST`::
	The FTP/HTTP server to use when the jails are installed from FreeBSD releases and updated with man:freebsd-update[8].
	Choose a server location which is close, for example if the machine is located in Australia, use `ftp.au.freebsd.org`.

	`SVN_HOST`::
	The server from where jails are installed and updated when using Subversion.
	Again, choose a nearby location.
	A list of official Subversion mirrors can be found in the extref:{handbook}[FreeBSD Handbook Subversion section, svn-mirrors].

	[[testing-poudriere-create-jails]]			[[testing-poudriere-create-jails]]
	=== Creating Poudriere Jails			=== Creating poudriere Jails

	Create the base jails which Poudriere will use for building:			Create the base jails which poudriere will use for building:

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -c -j 131Ramd64 -v 13.1-RELEASE -a amd64			# poudriere jail -c -j 131Ramd64 -v 13.1-RELEASE -a amd64
	....			....

	Fetch a `13.1-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#,			Fetch a `13.1-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#,
	create the zfs file system `tank/poudriere/jails/131Ramd64`,			create the zfs file system `tank/poudriere/jails/131Ramd64`,
	mount it on [.filename]#/poudriere/jails/131Ramd64# and extract the `13.1-RELEASE` tarballs into this file system.			mount it on [.filename]#/poudriere/jails/131Ramd64# and extract the `13.1-RELEASE` tarballs into this file system.

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -c -j 12i386 -v stable/12 -a i386 -m git+https			# poudriere jail -c -j 12i386 -v stable/12 -a i386 -m git+https
	....			....

	Create `tank/poudriere/jails/12i386`, mount it on [.filename]#/poudriere/jails/12i386#,			Create `tank/poudriere/jails/12i386`, mount it on [.filename]#/poudriere/jails/12i386#,
	then check out the tip of the Subversion branch of `FreeBSD-12-STABLE` from `SVN_HOST` in [.filename]#poudriere.conf# into [.filename]#/poudriere/jails/12i386/usr/src#,			then check out the tip of the Git branch of `FreeBSD-12-STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default `git.freebsd.org` into [.filename]#/poudriere/jails/12i386/usr/src#,
	then complete a `buildworld` and install it into [.filename]#/poudriere/jails/12i386#.			then complete a `buildworld` and install it into [.filename]#/poudriere/jails/12i386#.

	[TIP]
	====
	If a specific Subversion revision is needed, append it to the version string.
	For example:

	[source,shell]
	....
	# poudriere jail -c -j 12i386 -v stable/12@123456 -a i386 -m git+https
	....

	====

	[NOTE]			[NOTE]
	====			====
	While it is possible to build a newer version of FreeBSD on an older version, most of the time it will not run.			While it is possible to build a newer version of FreeBSD on an older version, most of the time it will not run.
	For example, if a `stable/13` jail is needed, the host will have to run `stable/13` too.			For example, if a `stable/13` jail is needed, the host will have to run `stable/13` too.
	Running `13.1-RELEASE` is not enough.			Running `13.1-RELEASE` is not enough.
	====			====

	[NOTE]			[NOTE]
	====			====
	To create a Poudriere jail for `14.0-CURRENT`:			To create a poudriere jail for `14.0-CURRENT`:

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -c -j 14amd64 -v main -a amd64 -m git+https			# poudriere jail -c -j 14amd64 -v main -a amd64 -m git+https
	....			....

	In order to run a `14.0-CURRENT` Poudriere jail you must be running `14.0-CURRENT`.			In order to run a `14.0-CURRENT` poudriere jail the host must be running `14.0-CURRENT`.
	In general, newer kernels can build and run older jails.			In general, newer kernels can build and run older jails.
	For instance, a `14.0-CURRENT` kernel can build and run a `12.3-STABLE`.			For instance, a `14.0-CURRENT` kernel can build and run a `12.4-STABLE` if the `COMPAT_FREEBSD12` kernel option was compiled in (on by default in `14.0-CURRENT`[.filename]#GENERIC# kernel config).
	Poudriere jail if the `COMPAT_FREEBSD12` kernel option was compiled in (on by default in `14.0-CURRENT`[.filename]#GENERIC# kernel config).
	====			====

	[CAUTION]			A list of jails currently known to poudriere can be shown with `poudriere jail -l`:
	====
	The default `svn` protocol works but is not very secure.
	Using `svn+https` along with verifying the remote server's SSL fingerprint is advised.
	It will ensure that the files used for building the jail are from a trusted source.
	====

	A list of jails currently known to Poudriere can be shown with `poudriere jail -l`:

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -l			# poudriere jail -l
	JAILNAME VERSION ARCH METHOD			JAILNAME VERSION ARCH METHOD
	131Ramd64 13.1-RELEASE amd64 ftp			131Ramd64 13.1-RELEASE amd64 ftp
	12i386 12.3-STABLE i386 git+https			12i386 12.4-STABLE i386 git+https
	....			....

	[[testing-poudriere-maintaining-jails]]			[[testing-poudriere-maintaining-jails]]
	=== Keeping Poudriere Jails Updated			=== Keeping poudriere Jails Updated

	Managing updates is very straightforward.			Managing updates is very straightforward.
	The command:			The command:

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -u -j JAILNAME			# poudriere jail -u -j JAILNAME
	....			....

	updates the specified jail to the latest version available.			updates the specified jail to the latest version available.
				pass:[<!-- vale Vale.Terms = NO -->]
	For FreeBSD releases, update to the latest patchlevel with man:freebsd-update[8].			For FreeBSD releases, update to the latest patchlevel with man:freebsd-update[8].
	For FreeBSD versions built from source, update to the latest Subversion revision in the branch.			pass:[<!-- vale Vale.Terms = YES -->]
				For FreeBSD versions built from source, update to the latest git revision in the branch.

	[TIP]			[TIP]
	====			====
	For jails employing a `git+*` method, it is helpful to add `-J _NumberOfParallelBuildJobs_` to speed up the build by increasing the number of parallel compile jobs used.			For jails employing a `git+*` method, it is helpful to add `-J _NumberOfParallelBuildJobs_` to speed up the build by increasing the number of parallel compile jobs used.
	For example, if the building machine has 6 CPUs, use:			For example, if the building machine has 6 CPUs, use:

	[source,shell]			[source,shell]
	....			....
	# poudriere jail -u -J 6 -j JAILNAME			# poudriere jail -u -J 6 -j JAILNAME
	....			....

	====			====

	[[testing-poudriere-ports-tree]]			[[testing-poudriere-ports-tree]]
	=== Setting Up Ports Trees for Use with Poudriere			=== Setting Up Ports Trees for Use with poudriere

	There are multiple ways to use ports trees in Poudriere.			There are multiple ways to use ports trees in poudriere.
	The most straightforward way is to have Poudriere create a default ports tree for itself, using link:{handbook}mirrors/#git[Git]:			The most straightforward way is to have poudriere create a default ports tree for itself, using link:{handbook}mirrors/#git[Git]:

	[source,shell]			[source,shell]
	....			....
	# poudriere ports -c -m git+https -B main			# poudriere ports -c -m git+https -B main
	....			....

	These commands create `tank/poudriere/ports/default`, mount it on [.filename]#/poudriere/ports/default#, and populate it using Git.			These commands create `tank/poudriere/ports/default`, mount it on [.filename]#/poudriere/ports/default#, and populate it using Git.
	Afterward it is included in the list of known ports trees:			Afterward it is included in the list of known ports trees:
	Show All 9 Lines
	====			====
	Note that the "default" ports tree is special.			Note that the "default" ports tree is special.
	Each of the build commands explained later will implicitly use this ports tree unless specifically specified otherwise.			Each of the build commands explained later will implicitly use this ports tree unless specifically specified otherwise.
	To use another tree, add `-p _treename_` to the commands.			To use another tree, add `-p _treename_` to the commands.
	====			====

	The best way to deal with local modifications for a ports contributor is to use link:{handbook}mirrors/#git[Git].			The best way to deal with local modifications for a ports contributor is to use link:{handbook}mirrors/#git[Git].
	As with the creation of jails, it is possible to use a different method for creating the ports tree.			As with the creation of jails, it is possible to use a different method for creating the ports tree.
	To add an additional ports tree for testing local modifications and ports development,			To add an additional ports tree for testing local modifications and ports development, checking out the tree via git (as described above) is preferable.
	checking out the tree via Subversion (as described above) is preferable.

	[NOTE]
	====
	The http and https methods need package:devel/subversion[] built with the `SERF` option enabled.
	It is enabled by default.
	====

	[TIP]
	====
	The `svn` method allows extra qualifiers to tell Subversion exactly how to fetch data.
	This is explained in man:poudriere[8].
	For instance, `poudriere ports -c -m svn+ssh -p subversive` uses SSH for the checkout.
	====

	[[testing-poudriere-ports-tree-manual]]			[[testing-poudriere-ports-tree-manual]]
	=== Using Manually Managed Ports Trees with Poudriere			=== Using Manually Managed Ports Trees with poudriere

	Depending on the workflow, it can be extremely helpful to use ports trees which are maintained manually.			Depending on the workflow, it can be extremely helpful to use ports trees which are maintained manually.
	For instance, if there is a local copy of the ports tree in [.filename]#/work/ports#, point Poudriere to the location:			For instance, if there is a local copy of the ports tree in [.filename]#/work/ports#, point poudriere to the location:

	* For Poudriere older than version 3.1.20:
	+
	[source,shell]			[source,shell]
	....			....
	# poudriere ports -c -F -f none -M /work/ports -p development
	....

	* For Poudriere version 3.1.20 and later:
	+
	[source,shell]
	....
	# poudriere ports -c -m null -M /work/ports -p development			# poudriere ports -c -m null -M /work/ports -p development
	....			....

	This will be listed in the table of known trees:			This will be listed in the table of known trees:

	[source,shell]			[source,shell]
	....			....
	# poudriere ports -l			# poudriere ports -l
	PORTSTREE METHOD TIMESTAMP PATH			PORTSTREE METHOD TIMESTAMP PATH
	development null 2020-07-20 05:06:33 /work/ports			development null 2020-07-20 05:06:33 /work/ports
	....			....

	[NOTE]			[NOTE]
	====			====
	The dash or `null` in the `METHOD` column means that Poudriere will not update or change this ports tree, ever.			The dash or `null` in the `METHOD` column means that poudriere will not update or change this ports tree, ever.
	It is completely up to the user to maintain this tree, including all local modifications that may be used for testing new ports and submitting patches.			It is completely up to the user to maintain this tree, including all local modifications that may be used for testing new ports and submitting patches.
	====			====

	[[testing-poudriere-ports-tree-updating]]			[[testing-poudriere-ports-tree-updating]]
	=== Keeping Poudriere Ports Trees Updated			=== Keeping poudriere Ports Trees Updated

	As straightforward as with jails described earlier:			As straightforward as with jails described earlier:

	[source,shell]			[source,shell]
	....			....
	# poudriere ports -u -p PORTSTREE			# poudriere ports -u -p PORTSTREE
	....			....

	Will update the given _PORTSTREE_, one tree given by the output of `poudriere -l`, to the latest revision available on the official servers.			Will update the given _PORTSTREE_, one tree given by the output of `poudriere -l`, to the latest revision available on the official servers.

	[NOTE]			[NOTE]
	====			====
	Ports trees without a method, see <<testing-poudriere-ports-tree-manual>>, cannot be updated like this.			Ports trees without a method, see <<testing-poudriere-ports-tree-manual>>, cannot be updated like this and must be updated manually by the porter.
	They must be updated manually by the porter.
	====			====

	[[testing-poudriere-testing-ports]]			[[testing-poudriere-testing-ports]]
	=== Testing Ports			=== Testing Ports

	After jails and ports trees have been set up, the result of a contributor's modifications to the ports tree can be tested.			After jails and ports trees have been set up, the result of a contributor's modifications to the ports tree can be tested.

	For example, local modifications to the package:www/firefox[] port located in [.filename]#/work/ports/www/firefox# can be tested in the previously created 13.1-RELEASE jail:			For example, local modifications to the package:www/firefox[] port located in [.filename]#/work/ports/www/firefox# can be tested in the previously created 13.1-RELEASE jail:
	Show All 10 Lines

	The complete build of every port is logged to [.filename]#/poudriere/data/logs/bulk/131Ri386-development/build-time/logs#.			The complete build of every port is logged to [.filename]#/poudriere/data/logs/bulk/131Ri386-development/build-time/logs#.

	The directory name `131Ri386-development` is derived from the arguments to `-j` and `-p`, respectively.			The directory name `131Ri386-development` is derived from the arguments to `-j` and `-p`, respectively.
	For convenience, a symbolic link [.filename]#/poudriere/data/logs/bulk/131Ri386-development/latest# is also maintained.			For convenience, a symbolic link [.filename]#/poudriere/data/logs/bulk/131Ri386-development/latest# is also maintained.
	The link points to the latest _build-time_ directory.			The link points to the latest _build-time_ directory.
	Also in this directory is an [.filename]#index.html# for observing the build process with a web browser.			Also in this directory is an [.filename]#index.html# for observing the build process with a web browser.

	By default, Poudriere cleans up the jails and leaves log files in the directories mentioned above.			By default, poudriere cleans up the jails and leaves log files in the directories mentioned above.
	To ease investigation, jails can be kept running after the build by adding `-i` to `testport`:			To ease investigation, jails can be kept running after the build by adding `-i` to `testport`:

	[source,shell]			[source,shell]
	....			....
	# poudriere testport -j 131Ramd64 -p development -i -o www/firefox			# poudriere testport -j 131Ramd64 -p development -i -o www/firefox
	....			....

	After the build completes, and regardless of whether it was successful, a shell is provided within the jail.			After the build completes, and regardless of whether it was successful, a shell is provided within the jail.
	The shell is used to investigate further.			The shell is used to investigate further.
	Poudriere can be told to leave the jail running after the build finishes with `-I`.			poudriere can be told to leave the jail running after the build finishes with `-I`.
	Poudriere will show the command to run when the jail is no longer needed.			poudriere will show the command to run when the jail is no longer needed.
	It is then possible to man:jexec[8] into it:			It is then possible to man:jexec[8] into it:

	[source,shell]			[source,shell]
	....			....
	# poudriere testport -j 131Ramd64 -p development -I -o www/firefox			# poudriere testport -j 131Ramd64 -p development -I -o www/firefox
	[...]			[...]
	====>> Installing local Pkg repository to /usr/local/etc/pkg/repos			====>> Installing local Pkg repository to /usr/local/etc/pkg/repos
	====>> Leaving jail 131Ramd64-development-n running, mounted at /poudriere/data/.m/131Ramd64-development/ref for interactive run testing			====>> Leaving jail 131Ramd64-development-n running, mounted at /poudriere/data/.m/131Ramd64-development/ref for interactive run testing
	====>> To enter jail: jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root			====>> To enter jail: jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root
	====>> To stop jail: poudriere jail -k -j 131Ramd64 -p development			====>> To stop jail: poudriere jail -k -j 131Ramd64 -p development
	# jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root			# jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root
	# [do some stuff in the jail]			# [do some stuff in the jail]
	# exit			# exit
	# poudriere jail -k -j 131Ramd64 -p development			# poudriere jail -k -j 131Ramd64 -p development
	====>> Umounting file systems			====>> Umounting file systems
	....			....

	An integral part of the FreeBSD ports build infrastructure is the ability to tweak ports to personal preferences with options.			An integral part of the FreeBSD ports build infrastructure is the ability to tweak ports to personal preferences with options.
	These can be tested with Poudriere as well. Adding the `-c`:			These can be tested with poudriere as well.
				Adding the `-c`:

	[source,shell]			[source,shell]
	....			....
	# poudriere testport -c -o www/firefox			# poudriere testport -c -o www/firefox
	....			....

	Presents the port configuration dialog before the port is built.			Presents the port configuration dialog before the port is built.
	The ports given after `-o` in the format `_category_/_portname_` will use the specified options, all dependencies will use the default options.			The ports given after `-o` in the format `_category_/_portname_` will use the specified options, all dependencies will use the default options.
	Testing dependent ports with non-default options can be accomplished using sets, see <<testing-poudriere-sets>>.			Testing dependent ports with non-default options can be accomplished using sets, see <<testing-poudriere-sets>>.

	[TIP]			[TIP]
	====			====
	When testing ports where [.filename]#pkg-plist# is altered during build depending on the selected options,			When testing ports where [.filename]#pkg-plist# is altered during build depending on the selected options,
	it is recommended to perform a test run with all options selected _and_ one with all options deselected.			it is recommended to perform a test run with all options selected _and_ one with all options deselected.
	====			====

	[[testing-poudriere-sets]]			[[testing-poudriere-sets]]
	=== Using Sets			=== Using Sets

	For all actions involving builds, a so-called _set_ can be specified using `-z _setname_`.			For all actions involving builds, a so-called _set_ can be specified using `-z _setname_`.
	A set refers to a fully independent build.			A set refers to a fully independent build.
	This allows, for instance, usage of `testport` with non-standard options for the dependent ports.			This allows, for instance, usage of `testport` with non-standard options for the dependent ports.

	To use sets, Poudriere expects an existing directory structure similar to `PORT_DBDIR`, defaults to [.filename]#/var/db/ports# in its configuration directory.			To use sets, poudriere expects an existing directory structure similar to `PORT_DBDIR`, defaults to [.filename]#/var/db/ports# in its configuration directory.
	This directory is then man:nullfs[5]-mounted into the jails where the ports and their dependencies are built.			This directory is then man:nullfs[5]-mounted into the jails where the ports and their dependencies are built.
	Usually a suitable starting point can be obtained by recursively copying the existing `PORT_DBDIR` to [.filename]#/usr/local/etc/poudriere.d/jailname-portname-setname-options#.			Usually a suitable starting point can be obtained by recursively copying the existing `PORT_DBDIR` to [.filename]#/usr/local/etc/poudriere.d/jailname-portname-setname-options#.
	This is described in detail in man:poudriere[8].			This is described in detail in man:poudriere[8].
	For instance, testing package:www/firefox[] in a specific set named `devset`, add the `-z devset` parameter to the testport command:			For instance, testing package:www/firefox[] in a specific set named `devset`, add the `-z devset` parameter to the `testport` command:

	[source,shell]			[source,shell]
	....			....
	# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox			# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox
	....			....

	This will look for the existence of these directories in this order:			This will look for the existence of these directories in this order:

	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-options#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-options#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-options#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-options#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-options#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-options#
	* [.filename]#/usr/local/etc/poudriere.d/devset-options#			* [.filename]#/usr/local/etc/poudriere.d/devset-options#
	* [.filename]#/usr/local/etc/poudriere.d/development-options#			* [.filename]#/usr/local/etc/poudriere.d/development-options#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-options#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-options#
	* [.filename]#/usr/local/etc/poudriere.d/options#			* [.filename]#/usr/local/etc/poudriere.d/options#

	From this list, Poudriere man:nullfs[5]-mounts the _first existing_ directory tree into the [.filename]#/var/db/ports# directory of the build jails.			From this list, poudriere man:nullfs[5]-mounts the _first existing_ directory tree into the [.filename]#/var/db/ports# directory of the build jails.
	Hence, all custom options are used for all the ports during this run of `testport`.			Hence, all custom options are used for all the ports during this run of `testport`.

	After the directory structure for a set is provided, the options for a particular port can be altered.			After the directory structure for a set is provided, the options for a particular port can be altered.
	For example:			For example:

	[source,shell]			[source,shell]
	....			....
	# poudriere options -c www/firefox -z devset			# poudriere options -c www/firefox -z devset
	....			....

	The configuration dialog for package:www/firefox[] is shown, and options can be edited.			The configuration dialog for package:www/firefox[] is shown, and options can be edited.
	The selected options are saved to the `devset` set.			The selected options are saved to the `devset` set.

	[NOTE]			[NOTE]
	====			====
	Poudriere is very flexible in the option configuration.			poudriere is very flexible in the option configuration.
	They can be set for particular jails, ports trees, and for multiple ports by one command.			poudriere can be set for particular jails, ports trees, and for multiple ports by one command.
	Refer to man:poudriere[8] for details.			Refer to man:poudriere[8] for details.
	====			====

	[[testing-poudriere-make-conf]]			[[testing-poudriere-make-conf]]
	=== Providing a Custom [.filename]#make.conf# File			=== Providing a Custom [.filename]#make.conf# File

	Similar to using sets, Poudriere will also use a custom [.filename]#make.conf# if it is provided.			Similar to using sets, poudriere will also use a custom [.filename]#make.conf# if it is provided.
	No special command line argument is necessary.			No special command line argument is necessary.
	Instead, Poudriere looks for existing files matching a name scheme derived from the command line. For instance:			Instead, poudriere looks for existing files matching a name scheme derived from the command line.
				For instance:

	[source,shell]			[source,shell]
	....			....
	# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox			# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox
	....			....

	causes Poudriere to check for the existence of these files in this order:			causes poudriere to check for the existence of these files in this order:

	* [.filename]#/usr/local/etc/poudriere.d/make.conf#			* [.filename]#/usr/local/etc/poudriere.d/make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/devset-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/devset-make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/development-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/development-make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-make.conf#
	* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-make.conf#			* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-make.conf#
	Show All 18 Lines
	Note the use of `+=` so that if the variable is already set in the default [.filename]#make.conf# its content will not be overwritten.			Note the use of `+=` so that if the variable is already set in the default [.filename]#make.conf# its content will not be overwritten.
	****			****

	====			====

	[[testing-poudriere-pruning-distfiles]]			[[testing-poudriere-pruning-distfiles]]
	=== Pruning no Longer Needed Distfiles			=== Pruning no Longer Needed Distfiles

	Poudriere comes with a built-in mechanism to remove outdated distfiles that are no longer used by any port of a given tree.			poudriere comes with a built-in mechanism to remove outdated distfiles that are no longer used by any port of a given tree.
	The command			The command

	[source,shell]			[source,shell]
	....			....
	# poudriere distclean -p portstree			# poudriere distclean -p portstree
	....			....

	will scan the distfiles folder, `DISTFILES_CACHE` in [.filename]#poudriere.conf#,			will scan the distfiles folder, `DISTFILES_CACHE` in [.filename]#poudriere.conf#,
	versus the ports tree given by the `-p _portstree_` argument and prompt for removal of those distfiles.			versus the ports tree given by the `-p _portstree_` argument and prompt for removal of those distfiles.
	To skip the prompt and remove all unused files unconditionally, the `-y` argument can be added:			To skip the prompt and remove all unused files unconditionally, the `-y` argument can be added:

	[source,shell]			[source,shell]
	....			....
	# poudriere distclean -p portstree -y			# poudriere distclean -p portstree -y
	....			....