=head1 NAME

FAQ - Test::Smoke frequently asked questions

=head1 DESCRIPTION

=head2 What is Test::Smoke?

B<Test::Smoke> is the symbolic name for set of scripts and modules
that try to run the perl core tests on as many configurations as
possible and combine the results into an easy to read report.

The basic cycle looks like:

    fetch_sourcetree
    foreach $config ( @configurations ) {
        make distclean
        ./Configure $config
        make
        make test (and log failures)
    }
    create_report()
    mail_report()

=head2 Why is Test::Smoke?

The reports from B<Test::Smoke> give a good picture of the current state
of Perl development. We try to get as many of the supported platforms
as possible.

=head2 Where is Test::Smoke?

On CPAN: L<http://search.cpan.org/authour/ABELTJE/Test-Smoke>

=head2 What are these configuration files about?

B<Test::Smoke> uses two types of configuration files:

=over 4

=item B<smoke-configuration-file>

This is a file that uses a B<_config> suffix and contains settings for
the F<smokeperl.pl> program and is created by F<configsmoke.pl>.

This is basically a Data::Dumper::Dump() of a hash.

=item B<build-configurations-file>

This file contains the information needed to assemble the list of
perl configurations that will be used to build and test perl.

The file is devided into sections separated by a line that starts with
an equals-sign (B<=>). Each line in a section is combined with all
lines from all the other sections. The default build-configurations
file F<perlcurrent.cfg> constist of four (4) sections:

=over 4

=item B<section 1> one (1) (blank) line

=item B<section 2> two (2) lines

=item B<section 3> seven (7) lines

=item B<section 4> two (2) lines (and a policy indicator line)

=back

This file wil yield 1 * 2 * 7 * 2 = 28 configurations. B<Test::Smoke>
will build perl in all of these 28 configurations and run the core
test suite one (1), two (2) or three (3) times for each of those
perls:

=over 4

=item * with C<< $ENV{PERLIO}=stdio >> (allways)

=item * with C<< $ENV{PERLIO}=perlio >> (unless -Uuseperlio)

=item * with C<< $ENV{PERL_UNICODE}="", $ENV{LC_ALL}=xx_YY.utf8 >> (if
specified and !-Uuseperlio) 

=back

=back

=head2 How do I create different smoke-configurations?

By specifying a diffent prefix to F<configsmoke.pl>:

    $ perl configsmoke.pl -p mysmoke

This will create the smokeconfiguration F<mysmoke_config> and a small
shellscript F<mysmoke.sh> (or F<mysmoke.cmd> if you are on Windows).

There are two (2) special prefixes: B<smoke562> and B<smoke58x>. These
will set the default answers for F<configsmoke.pl> to be appropriate
for smoking the maintenance branches for these versions of perl.

=head2 What are all the scripts in the smoke suite for?

=over 4

=item B<smokeperl.pl>

This is a wrapper script that goes through all the steps in the smoke
process.

=item B<synctree.pl>

Small wrapper around B<Test::Smoke::Syncer> that can use the settings
from the smoke-configuration file. It will bring the source-tree in
sync.

=item B<patchtree.pl>

Small wrapper around B<Test::Smoke::Patcher> that can use the settings
from the smoke-configuration file. It will apply the patches that are
specified in the patches-to-be-applied file.

=item B<mktest.pl>

This is the main script that runs I<Configure>, I<make> and S<< I<make
test> >> for all configurations and log the results in F<<
<builddir>/mktest.out >>.

As of 1.17_55 (1.18-to-be) the use of F<mktest.pl> is deprecated in
favour of the new F<runsmoke.pl> frontend to B<Test::Smoke::Smoker>. This
script will not be maintained!

=item B<runsmoke.pl>

Small wrapper around B<Test::Smoke::run_smoke()> that can use the
settings from the smoke-configuration file. It runs the smoke cycle
for all configurations and is a replacement for the now unmaintained
B<mktest.pl>.

=item B<mkovz.pl>

This script generates the report as F<< <builddir>/mktest.rpt >> from
F<< <builddir>/mktest.out >>. It can also send the report, but
F<mailrpt.pl> is the preferred way.

=item B<mailrpt.pl>

Small wrapper around B<Test::Smoke::Mailer> that can use the settings
from the smoke-configuration file. It will check if the report is
already generated and do so if not (by calling F<mkovz.pl>).

=item B<archiverpt.pl>

This script copies the report and the logfile to a configurable place.

=item B<smokestatus.pl>

This script prints a little status report for a smoke confifuration:

    $ ./smokestatus.pl -c smoke58x
    Busy smoking patchlevel 20562.
    13 out of 18 configurations finished in 7 hours 19 minutes.
    10 configuration(s) showed failures (F).
    0 failure(s) in the running configuration.
    5 configuration(s) to finish, in est. 2 hours 49 minutes.

=item B<W32Configure.bat>

Small wrapper around B<Test::Smoke::Util::Configure_win32()> that can
use some of the settings from the smoke-configuration file.

This helps users on Windows to create the F<<
<builddir>/win32/smoke.mk >> makefile for a specific configuration in
a unixy way.

=back

=head2 Can I interrupt a smoke run?

Yes, you can kill all the smoke related processes. Each stage is
directly logged in F<< <builddir>/mktest.out >>.


As of version 1.17.02 you can specify a timeout (if you have alarm())

=head2 Can I still generate a report after an interrupted smoke?

Yes, but some information might be missing (the compiler info).

    $ perl mailrpt.pl -c [configname]

=head2 Where do the reports go?

To the address configured in F<configsmoke.pl>. The default is
<smokers-reports@perl.org>.

There are several ways to monitor the reports send in:

=over 4

=item Subscribe to the mailinglist

You can subscribe to that list by sending an empty message to
<smokers-reports-subscribe@perl.org>.
You do B<not> have to be subscribed to send reports!

=item The WWW archive

The mailinglist has an archive on the web (although this archive seems
to be behind at the moment):
L<http://archive.develooper.com/daily-build-reports@perl.org/>.

=item The usenet mirror

The mailinglist also has a mirror on usenet:
<news:nntp.perl.org/perl.daily-build.reports>

Posts to the newsgroup will also be mirrored on the mailinglist.

=item The usenet WWW archive

The usenet mirror also has an archive on the web:
L<http://nntp.x.perl.org/group/perl.daily-build.reports>

=back

=head2 What's with the "daily-build" and "smokers" names?

There has been enough discussion on the subject, so lets agree to
disagree (it was all before my time).

The case is now that the official name for the mailinglist is
B<daily-build-reports> and there is an alias to B<smokers-reports>.

=head1 REVISION

$Id: FAQ 349 2003-08-08 22:21:16Z abeltje $

=head1 COPYRIGHT

(c) 2002-2003, All rights reserved.

  * Abe Timmerman <abeltje@cpan.org>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

See:

=over 4

=item * L<http://www.perl.com/perl/misc/Artistic.html>

=item * L<http://www.gnu.org/copyleft/gpl.html>

=back

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

=cut
