Enhance the Poudriere chapter a great bit.
Differential Revision: https://reviews.freebsd.org/D770 Submitted by: riggs Reviewed by: wblock Sponsored by: Absolight
This commit is contained in:
Mathieu Arnold
parent
df56018912
commit
62d91d6373
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=45951
1 changed files with 722 additions and 19 deletions
|
|
@ -187,6 +187,728 @@
|
||||||
</tip>
|
</tip>
|
||||||
</sect1>
|
</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@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">
|
<sect1 xml:id="testing-tinderbox">
|
||||||
<title>Tinderbox</title>
|
<title>Tinderbox</title>
|
||||||
|
|
||||||
|
|
@ -202,23 +924,4 @@
|
||||||
<link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox
|
<link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox
|
||||||
website</link> for more details.</para>
|
website</link> for more details.</para>
|
||||||
</sect1>
|
</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>
|
</chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue