Document the FreeBSD src Tinderbox from the FreeBSD wiki.
This work was done as part of Google Code-In (GCIN) 2011. GCIN student: Isabell Long (isabell121 gmail com) GCIN task mentors: des, gjb Minor changes by: gjb
This commit is contained in:
Glen Barber
parent
0622501d94
commit
a557e8e13e
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38487
1 changed files with 281 additions and 0 deletions
|
|
@ -211,6 +211,287 @@
|
|||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section id="testing-tinderbox">
|
||||
<title>The &os; Source Tinderbox</title>
|
||||
|
||||
<para>The source Tinderbox consists of:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>A build script, <filename>tinderbox</filename>, that
|
||||
automates checking out a specific version of the &os; source
|
||||
tree and building it.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A supervisor script, <filename>tbmaster</filename>, that
|
||||
monitors individual Tinderbox instances, logs their output,
|
||||
and emails failure notices.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A <acronym>CGI</acronym> script named
|
||||
<filename>index.cgi</filename> that reads a set of tbmaster
|
||||
logs and presents an easy-to-read <acronym>HTML</acronym>
|
||||
summary of them.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A set of build servers that continually test the tip of
|
||||
the most important &os; code branches.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A webserver that keeps a complete set of Tinderbox logs
|
||||
and displays an up-to-date summary.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The scripts are maintained and were developed by &a.des;,
|
||||
and are now written in Perl, a move on from their original
|
||||
incarnation as shell scripts. All scripts and configuration
|
||||
files are kept in <ulink
|
||||
url="http://www.freebsd.org/cgi/cvsweb.cgi/projects/tinderbox/">/projects/tinderbox/</ulink>.</para>
|
||||
|
||||
<para>For more information about the tinderbox and tbmaster
|
||||
scripts at this stage, see their respective man pages:
|
||||
tinderbox(1) and tbmaster(1).</para>
|
||||
|
||||
<section>
|
||||
<title>The <filename>index.cgi</filename> Script</title>
|
||||
|
||||
<para>The <filename>index.cgi</filename> script generates the
|
||||
<acronym>HTML</acronym> summary of tinderbox and tbmaster
|
||||
logs. Although originally intended to be used as a
|
||||
<acronym>CGI</acronym> script, as indicated by its name, this
|
||||
script can also be run from the command line or from a
|
||||
&man.cron.8; job, in which case it will look for logs in the
|
||||
directory where the script is located. It will automatically
|
||||
detect context, generating <acronym>HTTP</acronym> headers
|
||||
when it is run as a <acronym>CGI</acronym> script. It
|
||||
conforms to <acronym>XHTML</acronym> standards and is styled
|
||||
using <acronym>CSS</acronym>.</para>
|
||||
|
||||
<para>The script starts in the <function>main()</function> block
|
||||
by attempting to verify that it is running on the official
|
||||
Tinderbox website. If it is not, a page indicating it is not
|
||||
an official website is produced, and a <acronym>URL</acronym>
|
||||
to the official site is provided.</para>
|
||||
|
||||
<para>Next, it scans the log directory to get an inventory of
|
||||
configurations, branches and architectures for which log files
|
||||
exist, to avoid hard-coding a list into the script and
|
||||
potentially ending up with blank rows or columns. This
|
||||
information is derived from the names of the log files
|
||||
matching the following pattern:</para>
|
||||
|
||||
<programlisting>tinderbox-$config-$branch-$arch-$machine.{brief,full}</programlisting>
|
||||
|
||||
<para>The configurations used on the official Tinderbox build
|
||||
servers are named for the branches they build. For example,
|
||||
the <literal>releng_8</literal> configuration is used to build
|
||||
<literal>RELENG_8</literal> as well as all still-supported
|
||||
release branches.</para>
|
||||
|
||||
<para>Once all of this startup procedure has been successfully
|
||||
completed, <function>do_config()</function> is called for each
|
||||
configuration.</para>
|
||||
|
||||
<para>The <function>do_config()</function> function generates
|
||||
<acronym>HTML</acronym> for a single Tinderbox
|
||||
configuration.</para>
|
||||
|
||||
<para>It works by first generating a header row, then iterating
|
||||
over each branch build with the specified configuration,
|
||||
producing a single row of results for each in the following
|
||||
manner:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>For each item:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>For each machine within that architecture:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>If a brief log file exists, then:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Call <function>success()</function> to
|
||||
detemine the outcome of the build.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Output the modification size.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Output the size of the brief log file with
|
||||
a link to the log file itself.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>If a full log file also exists,
|
||||
then:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Output the size of the full log file
|
||||
with a link to the log file itself.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Otherwise:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>No output.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The <function>success()</function> function mentioned
|
||||
above scans a brief log file for the string <quote>tinderbox
|
||||
run completed</quote> in order to determine whether the
|
||||
build was successful.</para>
|
||||
|
||||
<para>Configurations and branches are sorted according to their
|
||||
branch rank. This is computed as follows:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>HEAD</literal> and <literal>CURRENT</literal>
|
||||
have rank 9999.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_<replaceable>x</replaceable></literal>
|
||||
has rank <replaceable>xx</replaceable>99.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_<replaceable>x</replaceable>_<replaceable>y</replaceable></literal>
|
||||
has rank <replaceable>xxyy</replaceable>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>Tthis means that <literal>HEAD</literal> always ranks
|
||||
highest, and <literal>RELENG</literal> branches are ranked in
|
||||
numerical order, with each <literal>STABLE</literal> branch
|
||||
ranking higher than the release branches forked off of it.
|
||||
For instance, for &os; 8, the order from highest to
|
||||
lowest would be:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8</literal> (branch rank 899).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8_3</literal> (branch rank
|
||||
803).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8_2</literal> (branch rank
|
||||
802).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8_1</literal> (branch rank
|
||||
801).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8_0</literal> (branch rank
|
||||
800).</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The colors that Tinderbox uses for each cell in the table
|
||||
are defined by <acronym>CSS</acronym>. Successful builds are
|
||||
displayed with green text; unsuccessful builds are displayed
|
||||
with red text. The color fades as time passes since the
|
||||
corresponding build, with every half an hour bringing the
|
||||
color closer to grey.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Official Build Servers</title>
|
||||
|
||||
<para>The official Tinderbox build servers are hosted by <ulink
|
||||
url="http://www.sentex.ca">Sentex Data
|
||||
Communications</ulink>, who also host the <ulink
|
||||
url="http://www.freebsd.org/projects/netperf/cluster.html">&os;
|
||||
Netperf Cluster</ulink>.</para>
|
||||
|
||||
<para>Three build servers currently exist:</para>
|
||||
|
||||
<para><emphasis>freebsd-current.sentex.ca</emphasis>
|
||||
builds:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>HEAD</literal> for amd64, arm, i386,
|
||||
i386/pc98, ia64, mips, powerpc, powerpc64, and sparc64,
|
||||
which takes approximately four hours.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>RELENG_9</literal> and supported
|
||||
9.<replaceable>X</replaceable> branches for amd64, arm,
|
||||
i386, i386/pc98, ia64, mips, powerpc, powerpc64, and
|
||||
sparc64, which takes approximately three and a half
|
||||
hours.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><emphasis>freebsd-stable.sentex.ca</emphasis>
|
||||
builds:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>RELENG_8</literal> and supported
|
||||
8.<replaceable>X</replaceable> branches for amd64, i386,
|
||||
i386/pc98, ia64, mips, powerpc and sparc64, and each
|
||||
branch takes approximately six hours.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><emphasis>freebsd-legacy.sentex.ca</emphasis>
|
||||
builds:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>RELENG_7</literal> and supported
|
||||
7.<replaceable>X</replaceable> branches for amd64, i386,
|
||||
i386/pc98, ia64, powerpc, and sparc64, and each branch
|
||||
takes approximately three hours.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Official Summary Site</title>
|
||||
|
||||
<para>Summaries and logs from the official build servers are
|
||||
available online at <ulink
|
||||
url="http://tinderbox.FreeBSD.org">http://tinderbox.FreeBSD.org</ulink>,
|
||||
hosted by &a.des; and set up as follows:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>A &man.cron.8; job checks the build servers at regular
|
||||
intervals and downloads any new log files using
|
||||
&man.rsync.1;.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Apache is set up to use <filename>index.cgi</filename>
|
||||
as <literal>DirectoryIndex</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A <ulink
|
||||
url="https://www.varnish-cache.org/">Varnish</ulink>
|
||||
instance in front of Apache ensures that
|
||||
<filename>index.cgi</filename> does not need to run more
|
||||
than once every two minutes.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue