svn commit: r45951 - head/en_US.ISO8859-1/books/porters-handbook/testing
Mathieu Arnold
mat at FreeBSD.org
Fri Nov 7 22:06:53 UTC 2014
Author: mat (ports committer)
Date: Fri Nov 7 22:06:52 2014
New Revision: 45951
URL: https://svnweb.freebsd.org/changeset/doc/45951
Log:
Enhance the Poudriere chapter a great bit.
Differential Revision: https://reviews.freebsd.org/D770
Submitted by: riggs
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Fri Nov 7 22:02:59 2014 (r45950)
+++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Fri Nov 7 22:06:52 2014 (r45951)
@@ -187,6 +187,728 @@
</tip>
</sect1>
+ <sect1 xml:id="testing-poudriere">
+ <title><application>Poudriere</application></title>
+
+ <para>For a ports contributor,
+ <application>Poudriere</application> is one of the most
+ important and helpful testing and build tools. Its main
+ features include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Bulk building of the entire ports tree, specific subsets
+ of the ports tree, or a single port including its
+ dependencies</para>
+ </listitem>
+
+ <listitem>
+ <para>Automatic packaging of build results</para>
+ </listitem>
+
+ <listitem>
+ <para>Generation of build log files per port</para>
+ </listitem>
+
+ <listitem>
+ <para>Providing a signed &man.pkg.8; repository</para>
+ </listitem>
+
+ <listitem>
+ <para>Testing of port builds before submitting a patch to the
+ &os; bug tracker or committing to the ports tree</para>
+ </listitem>
+
+ <listitem>
+ <para>Testing for successful ports builds using different
+ options</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Because <application>Poudriere</application> 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:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>No pollution of the host environment: No leftover files,
+ no accidental removals, no changes of existing configuration
+ files.</para>
+ </listitem>
+
+ <listitem>
+ <para>Verify <filename>pkg-plist</filename> for missing or
+ superfluous entries</para>
+ </listitem>
+
+ <listitem>
+ <para>Ports committers sometimes ask for a
+ <application>Poudriere</application> log alongside a patch
+ submission to assess whether the patch is ready for
+ integration into the ports tree</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>It is also quite straightforward to set up and use, has no
+ dependencies, and will run on any supported &os; release. This
+ section shows how to install, configure, and run
+ <application>Poudriere</application> as part of the normal
+ workflow of a ports contributor.</para>
+
+ <para>The examples in this section show a default file layout, as
+ standard in &os;. Substitute any local changes accordingly.
+ The ports tree, represented by <varname>${PORTSDIR}</varname>,
+ is located in <filename>/usr/ports</filename>. Both
+ <varname>${LOCALBASE}</varname> and <varname>${PREFIX}</varname>
+ are <filename>/usr/local</filename> by default.</para>
+
+ <sect2 xml:id="testing-poudriere-installing">
+ <title>Installing <application>Poudriere</application></title>
+
+ <para><application>Poudriere</application> is available in the
+ ports tree in <package
+ role="port">ports-mgmt/poudriere</package>. It can be
+ installed using &man.pkg.8; or from ports:</para>
+
+ <screen>&prompt.root; <userinput>pkg install poudriere</userinput></screen>
+
+ <para>or</para>
+
+ <screen>&prompt.root; <userinput>make -C /usr/ports/ports-mgmt/poudriere install clean</userinput></screen>
+
+ <para>There is also a work-in-progress version of
+ <application>Poudriere</application> which will eventually
+ become the next release. It is available in <package
+ role="port">ports-mgmt/poudriere-devel</package>. This
+ development version is used for the official &os; package
+ builds, so it is well tested. 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 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, in a way that
+ will shorten a full build from 18 hours to 17 hours when using
+ a high end 32 <acronym>CPU</acronym> server with 128GB of
+ <acronym>RAM</acronym>. Those optimizations will not matter a
+ lot when building ports on a desktop machine.</para>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-setup">
+ <title>Setting Up <application>Poudriere</application></title>
+
+ <para>The port installs a default configuration file,
+ <filename>/usr/local/etc/poudriere.conf</filename>. Each
+ parameter is documented in the configuration file and in
+ &man.poudriere.8;. Here is a minimal example config
+ file:</para>
+
+ <programlisting>ZPOOL=tank
+ZROOTFS=/poudriere
+BASEFS=/poudriere
+DISTFILES_CACHE=/usr/ports/distfiles
+RESOLV_CONF=/etc/resolv.conf
+FREEBSD_HOST=ftp://ftp.freebsd.org
+SVN_HOST=svn0.eu.FreeBSD.org</programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>ZPOOL</varname></term>
+
+ <listitem>
+ <para>The name of the <acronym>ZFS</acronym> storage pool
+ which <application>Poudriere</application> shall use.
+ Must be listed in the output of <command>zpool
+ status</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ZROOTFS</varname></term>
+
+ <listitem>
+ <para>The root of
+ <application>Poudriere</application>-managed file
+ systems. This entry will cause
+ <application>Poudriere</application> to create
+ &man.zfs.8; file systems under
+ <literal>tank/poudriere</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>BASEFS</varname></term>
+
+ <listitem>
+ <para>The root mount point for
+ <application>Poudriere</application> file systems. This
+ entry will cause <application>Poudriere</application> to
+ mount <literal>tank/poudriere</literal> to
+ <literal>/poudriere</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>DISTFILES_CACHE</varname></term>
+
+ <listitem>
+ <para>Defines where distfiles are stored. In this
+ example, <application>Poudriere</application> and the
+ host share the distfiles storage directory. This avoids
+ downloading tarballs which are already present on the
+ system.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RESOLV_CONF</varname></term>
+
+ <listitem>
+ <para>Use the host <filename>/etc/resolv.conf</filename>
+ inside jails for <acronym>DNS</acronym>. This is needed
+ so jails can resolve the <acronym>URL</acronym>s of
+ distfiles when downloading. It is not needed when using
+ a proxy. Refer to the default configuration file for
+ proxy configuration.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FREEBSD_HOST</varname></term>
+
+ <listitem>
+ <para>The <acronym>FTP</acronym>/<acronym>HTTP</acronym>
+ server to use when the jails are installed from &os;
+ 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
+ <literal>ftp.au.freebsd.org</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SVN_HOST</varname></term>
+
+ <listitem>
+ <para>The server from where jails are installed and
+ updated when using
+ <application>Subversion</application>. Also used for
+ ports tree when not using &man.portsnap.8;. Again,
+ choose a nearby location. A list of official
+ <application>Subversion</application> mirrors can be
+ found in the <link
+ xlink:href="&url.books.handbook;/svn.html#svn-mirrors">&os;
+ Handbook <application>Subversion</application>
+ section</link>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-create-jails">
+ <title>Creating <application>Poudriere</application>
+ Jails</title>
+
+ <para>Create the base jails which
+ <application>Poudriere</application> will use for
+ building:</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -c -j 93Ramd64 -v 9.3-RELEASE -a amd64</userinput></screen>
+
+ <para>Fetch a <literal>9.3-RELEASE</literal> for
+ <literal>amd64</literal> from the <acronym>FTP</acronym>
+ server given by <varname>FREEBSD_HOST</varname> in
+ <filename>poudriere.conf</filename>, create the zfs file
+ system <literal>tank/poudriere/jails/93Ramd64</literal>, mount
+ it on <filename>/poudriere/jails/93Ramd64</filename> and
+ extract the <literal>9.3-RELEASE</literal> tarballs into this
+ file system.</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -c -j 10i386 -v stable/10 -a i386 -m svn+https</userinput></screen>
+
+ <para>Create <literal>tank/poudriere/jails/10i386</literal>,
+ mount it on <filename>/poudriere/jails/10i386</filename>, then
+ check out the tip of the <application>Subversion</application>
+ branch of <literal>&os;-10-STABLE</literal> from
+ <literal>SVN_HOST</literal> in
+ <filename>poudriere.conf</filename> into
+ <filename>/poudriere/jails/10i386/usr/src</filename>, then
+ complete a <buildtarget>buildworld</buildtarget> and install
+ it into <filename>/poudriere/jails/10i386</filename>.</para>
+
+ <tip>
+ <para>If a specific <application>Subversion</application>
+ revision is needed, append it to the version string. For
+ example:</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -c -j 10i386 -v stable/10 at 123456 -a i386 -m svn+https</userinput></screen>
+ </tip>
+
+ <note>
+ <para>While it is possible to build a newer version of &os; on
+ an older version, most of the time it will not run. For
+ example, if a <literal>stable/10</literal> jail is needed,
+ the host will have to run <literal>stable/10</literal> too.
+ Running <literal>10.0-RELEASE</literal> is not
+ enough.</para>
+ </note>
+
+ <caution>
+ <para>The default <literal>svn</literal> protocol works but is
+ not very secure. Using <literal>svn+https</literal> along
+ with verifying the remote server's <acronym>SSL</acronym>
+ fingerprint is advised. It will ensure that the files used
+ for building the jail are from a trusted source.</para>
+ </caution>
+
+ <para>A list of jails currently known to
+ <application>Poudriere</application> can be shown with
+ <command>poudriere jail -l</command>:</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -l</userinput>
+JAILNAME VERSION ARCH METHOD
+93Ramd64 9.3-RELEASE amd64 ftp
+10i386 10.0-STABLE i386 svn+https</screen>
+ </sect2>
+
+
+ <sect2 xml:id="testing-poudriere-maintaining-jails">
+ <title>Keeping <application>Poudriere</application> Jails
+ Updated</title>
+
+ <para>Managing updates is very straightforward. The
+ command:</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -u -j <replaceable>JAILNAME</replaceable></userinput></screen>
+
+ <para>updates the specified jail to the latest version
+ available. For &os; releases, update to the latest patchlevel
+ with &man.freebsd-update.8;. For &os; versions built from
+ source, update to the latest
+ <application>Subversion</application> revision in the
+ branch.</para>
+
+ <tip>
+ <para>For jails employing a
+ <literal>svn+<replaceable>*</replaceable></literal> method,
+ it is helpful to add <command>-J
+ <replaceable>NumberOfParallelBuildJobs</replaceable></command>
+ to speed up the build by increasing the number of parallel
+ compile jobs used. For example, if the building machine has
+ 6 <acronym>CPU</acronym>s, use:</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -u -J 6 -j <replaceable>JAILNAME</replaceable></userinput></screen>
+ </tip>
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-ports-tree">
+ <title>Setting Up Ports Trees for Use with
+ <application>Poudriere</application></title>
+
+ <para>There are multiple ways to use ports trees in
+ <application>Poudriere</application>. The most
+ straightforward way is to have
+ <application>Poudriere</application> create a default ports
+ tree for itself:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -c</userinput></screen>
+
+ <para>This command creates
+ <literal>tank/poudriere/ports/default</literal>, mount it on
+ <filename>/poudriere/ports/default</filename>, and populate it
+ using &man.portsnap.8;. Afterward it is included in the list
+ of known ports trees:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -l</userinput>
+PORTSTREE METHOD PATH
+default portsnap /poudriere/ports/default</screen>
+
+ <note>
+ <para>Note that the <quote>default</quote> ports tree is
+ special. Each of the build commands explained later will
+ implicitly use this ports tree unless specifically specified
+ otherwise. To use another tree, add <command>-p
+ <replaceable>treename</replaceable></command> to the
+ commands.</para>
+ </note>
+
+ <para>While useful for regular bulk builds, having this default
+ ports tree with the &man.portsnap.8; method may not be the
+ best way to deal with local modifications for a ports
+ contributor. 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, checking out the tree via
+ <application>Subversion</application> is possible:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -c -m svn+https -p subversive</userinput></screen>
+
+ <para>Creates <literal>tank/poudriere/ports/subversive</literal>
+ and mounts it on
+ <filename>/poudriere/ports/subversive</filename>. It is then
+ populated using <application>Subversion</application>.
+ Finally, it is added to the list of known ports trees:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -l</userinput>
+PORTSTREE METHOD PATH
+default portsnap /poudriere/ports/default
+subversive svn+https /poudriere/ports/subversive</screen>
+
+ <tip>
+ <para>The <literal>svn</literal> method allows extra
+ qualifiers to tell <application>Subversion</application>
+ exactly how to fetch data. This is explained in
+ &man.poudriere.8;. For instance, <command>poudriere ports
+ -c -m svn+ssh -p subversive</command> uses
+ <application>SSH</application> for the checkout.</para>
+ </tip>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-ports-tree-manual">
+ <title>Using Manually Managed Ports Trees with Poudriere</title>
+
+ <para>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</filename>, point
+ <application>Poudriere</application> to the location:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -c -F -f none -M /work/ports -p development</userinput></screen>
+
+ <para>This will be listed in the table of known trees:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -l</userinput>
+PORTSTREE METHOD PATH
+development - /work/ports</screen>
+
+ <note>
+ <para>The dash in the <literal>METHOD</literal> column means
+ that <application>Poudriere</application> 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.</para>
+ </note>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-ports-tree-updating">
+ <title>Keeping Poudriere Ports Trees Updated</title>
+
+ <para>As straightforward as with jails described earlier:</para>
+
+ <screen>&prompt.root; <userinput>poudriere ports -u -p <replaceable>PORTSTREE</replaceable></userinput></screen>
+
+ <para>Will update the given
+ <replaceable>PORTSTREE</replaceable>, one tree given by the
+ output of <command>poudriere -l</command>, to the latest
+ revision available on the official servers.</para>
+
+ <note>
+ <para>Ports trees without a method, see <xref
+ linkend="testing-poudriere-ports-tree-manual"/>, cannot be
+ updated like this. They must be updated manually by the
+ porter.</para>
+ </note>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-testing-ports">
+ <title>Testing Ports</title>
+
+ <para>After jails and ports trees have been set up, the result
+ of a contributor's modifications to the ports tree can be
+ tested.</para>
+
+ <para>For example, local modifications to the <package
+ role="port">www/firefox</package> port located in
+ <filename>/work/ports/www/firefox</filename> can be tested in
+ the previously created 9.3-RELEASE jail:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -j 93Ramd64 -p development -o www/firefox</userinput></screen>
+
+ <para>This will build all dependencies of
+ <application>Firefox</application>. If a dependency has been
+ built previously and is still up-to-date, the pre-built
+ package is installed. If a dependency has no up-to-date
+ package, one will be built with default options in a jail.
+ Then <application>Firefox</application> itself is
+ built.</para>
+
+ <para>The complete build of every port is logged to
+ <filename>/poudriere/data/logs/bulk/93Ri386-development/<replaceable>build-time</replaceable>/logs</filename>.</para>
+
+ <para>The directory name <literal>93Ri386-development</literal>
+ is derived from the arguments to <literal>-j</literal> and
+ <literal>-p</literal>, respectively. For convenience, a
+ symbolic link
+ <filename>/poudriere/data/logs/bulk/93Ri386-development/latest</filename>
+ is also maintained. The link points to the latest
+ <replaceable>build-time</replaceable> directory. Also in this
+ directory is an <filename>index.html</filename> for observing
+ the build process with a web browser.</para>
+
+ <para>By default, <application>Poudriere</application> 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 <option>-i</option> to
+ <command>testport</command>:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -j 93Ramd64 -p development -i -o www/firefox</userinput></screen>
+
+ <para>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.
+ <application>Poudriere</application> can be told to leave the
+ jail running after the build finishes with
+ <option>-I</option>. <application>Poudriere</application>
+ will show the command to run when the jail is no longer
+ needed. It is then possible to &man.jexec.8; into it:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -j 93Ramd64 -p development -I -o www/firefox</userinput>
+[...]
+====>> Installing local Pkg repository to /usr/local/etc/pkg/repos
+====>> Leaving jail 93Ramd64-development-n running, mounted at /poudriere/data/.m/93Ramd64-development/ref for interactive run testing
+====>> To enter jail: jexec 93Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root
+====>> To stop jail: poudriere jail -k -j 93Ramd64 -p development
+&prompt.root; <userinput>jexec 93Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root</userinput>
+&prompt.root; <userinput><replaceable>[do some stuff in the jail]</replaceable></userinput>
+&prompt.root; <userinput>exit</userinput>
+&prompt.root; <userinput>poudriere jail -k -j 93Ramd64 -p development</userinput>
+====>> Umounting file systems</screen>
+
+ <para>An integral part of the &os; ports build infrastructure is
+ the ability to tweak ports to personal preferences with
+ options. These can be tested with
+ <application>Poudriere</application> as well. Adding the
+ <option>-c</option>:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -c -o www/firefox</userinput></screen>
+
+ <para>Presents the port configuration dialog before the port is
+ built. The ports given after <option>-o</option> in the
+ format
+ <literal><replaceable>category</replaceable>/<replaceable>portname</replaceable></literal>
+ 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 <xref
+ linkend="testing-poudriere-sets"/>.</para>
+
+ <tip>
+ <para>When testing ports where <filename>pkg-plist</filename>
+ is altered during build depending on the selected options,
+ it is recommended to perform a test run with all options
+ selected <emphasis>and</emphasis> one with all options
+ deselected.</para>
+ </tip>
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-sets">
+ <title>Using Sets</title>
+
+ <para>For all actions involving builds, a so-called
+ <emphasis>set</emphasis> can be specified using <literal>-z
+ <replaceable>setname</replaceable></literal>. A set refers
+ to a fully independent build. This allows, for instance,
+ usage of <command>testport</command> with non-standard options
+ for the dependent ports.</para>
+
+ <para>To use sets, <application>Poudriere</application> expects
+ an existing directory structure similar to
+ <varname>PORT_DBDIR</varname>, defaults to
+ <filename>/var/db/ports</filename> in its configuration
+ directory. This directory is then nullfs-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 <varname>PORT_DBDIR</varname>
+ to
+ <filename>/usr/local/etc/poudriere.d/<replaceable>jailname</replaceable>-<replaceable>portname</replaceable>-<replaceable>setname</replaceable>-options</filename>.
+ This is described in detail in &man.poudriere.8;. For
+ instance, testing <package role="port">www/firefox</package>
+ in a specific set named <literal>devset</literal>, add the
+ <literal>-z devset</literal> parameter to the testport
+ command:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -j 93Ramd64 -p development -z devset -o www/firefox</userinput></screen>
+
+ <para>This will look for the existence of these directories in
+ this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-development-devset-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-devset-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-development-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/devset-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/development-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-options</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/options</filename></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>From this list, <application>Poudriere</application>
+ nullfs-mounts the <emphasis>first existing</emphasis>
+ directory tree into the <filename>/var/db/ports</filename>
+ directory of the build jails. Hence, all custom options are
+ used for all the ports during this run of
+ <command>testport</command>.</para>
+
+ <para>After the directory structure for a set is provided, the
+ options for a particular port can be altered. For
+ example:</para>
+
+ <screen>&prompt.root; <userinput>poudriere options -c www/firefox -z devset</userinput></screen>
+
+ <para>The configuration dialog for <package
+ role="port">www/firefox</package> is shown, and options can
+ be edited. The selected options are saved to the
+ <literal>devset</literal> set.</para>
+
+ <note>
+ <para><application>Poudriere</application> is very flexible in
+ the option configuration. They can be set for particular
+ jails, ports trees, and for multiple ports by one command.
+ Refer to &man.poudriere.8; for details.</para>
+ </note>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-make-conf">
+ <title>Providing a Custom <filename>make.conf</filename>
+ File</title>
+
+ <para>Similar to using sets,
+ <application>Poudriere</application> will also use a custom
+ <filename>make.conf</filename> if it is provided. No special
+ command line argument is necessary. Instead,
+ <application>Poudriere</application> looks for existing files
+ matching a name scheme derived from the command line. For
+ instance:</para>
+
+ <screen>&prompt.root; <userinput>poudriere testport -j 93Ramd64 -p development -z devset -o www/firefox</userinput></screen>
+
+ <para>causes <application>Poudriere</application> to check for
+ the existence of these files in this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/devset-make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/development-make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-development-make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-devset-make.conf</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>/usr/local/etc/poudriere.d/93Ramd64-development-devset-make.conf</filename></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Unlike with sets, all of the found files will be appended,
+ <emphasis>in that order</emphasis>, into one
+ <filename>make.conf</filename> inside the build jails. It is
+ hence possible to have general make variables, intended to
+ affect all builds in
+ <filename>/usr/local/etc/poudriere.d/make.conf</filename>.
+ Special variables, intended to affect only certain jails or
+ sets can be set in specialised <filename>make.conf</filename>
+ files, such as
+ <filename>/usr/local/etc/poudriere.d/93Ramd64-development-devset-make.conf</filename>.</para>
+
+ <example xml:id="testing-poudriere-sets-perl">
+ <title>Using <filename>make.conf</filename> to Change Default
+ <application>Perl</application></title>
+
+ <para>To build a set with a non default
+ <application>Perl</application> version, for example,
+ <literal>5.20</literal>, using a set named
+ <literal>perl5-20</literal>, create a
+ <filename>perl5-20-make.conf</filename> with this
+ line:</para>
+
+ <programlisting>DEFAULT_VERSIONS+= perl=5.20</programlisting>
+
+ <note>
+ <para>Note the use of <literal>+=</literal> so that if the
+ variable is already set in the default
+ <filename>make.conf</filename> its content will not be
+ overwritten.</para>
+ </note>
+ </example>
+
+ </sect2>
+
+ <sect2 xml:id="testing-poudriere-pruning-distfiles">
+ <title>Pruning no Longer Needed Distfiles</title>
+
+ <para><application>Poudriere</application> comes with a built-in
+ mechanism to remove outdated distfiles that are no longer used
+ by any port of a given tree. The command</para>
+
+ <screen>&prompt.root; <userinput>poudriere distclean -p <replaceable>portstree</replaceable></userinput></screen>
+
+ <para>will scan the distfiles folder,
+ <varname>DISTFILES_CACHE</varname> in
+ <filename>poudriere.conf</filename>, versus the ports tree
+ given by the <literal>-p
+ <replaceable>portstree</replaceable></literal> argument and
+ prompt for removal of those distfiles. To skip the prompt and
+ remove all unused files unconditionally, the
+ <literal>-y</literal> argument can be added:</para>
+
+ <screen>&prompt.root; <userinput>poudriere distclean -p <replaceable>portstree</replaceable> -y</userinput></screen>
+ </sect2>
+
+ <!--
+Tricks
+
+
+TODO
+- ZFS clones for ports tree modifications during builds
+
+ -->
+
+ </sect1>
+
<sect1 xml:id="testing-tinderbox">
<title>Tinderbox</title>
@@ -202,23 +924,4 @@
<link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox
website</link> for more details.</para>
</sect1>
-
- <sect1 xml:id="testing-poudriere">
- <title>Poudriere</title>
-
- <para>As a ports contributor, consider installing
- <application>poudriere</application>. It is a powerful
- system for building and testing ports.
- <application>Poudriere</application> can be installed with
- <package role="port">ports-mgmt/poudriere</package>.</para>
-
- <para>There is also a <package
- role="port">ports-mgmt/poudriere-devel</package> that often
- has newer features that are mostly helpful when testing
- ports.</para>
-
- <para>Visit the <link
- xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere
- website</link> for more details.</para>
- </sect1>
</chapter>
More information about the svn-doc-all
mailing list