REMOTETEST(1)

NAME
remotetest.pl - make tests on a remote machine

SYNOPSYS
  remotetest.pl MyInteresting-Dist-1.107.tar.gz machine1.domain machine2.domain
  remotetest.pl  -l some.preamble.pl MyInteresting-Dist-1.107.tar.gz machine1.domain ...
  remotetest.pl  -rep reportfile MyInteresting-Dist-1.107.tar.gz machine1.domain ...

MOTIVATION
Check your Perl distribution on diferent platforms avoiding the familiar excuse It works on my machine.

REQUIREMENTS
The script assumes that automatic authentification via SSH has been set up with each of the remote UNIX machines.

DESCRIPTION
The script "remotetest.pl" copies the specified Perl distribution

                MyInteresting-Dist-1.107.tar.gz

(see ExtUtils::MakeMaker and Module::Build) to each of the listed machines "machine1.domain", "machine2.domain", etc. and proceeeds to test the distribution ("make test") on these machines. Namely, it does the following steps:

•   Evals a preamble Perl file named by default "local.preamble.pl". Use that file to init any configuration variables and set up things in both the local and remote machines

•   For each of the machines "machine1.domain", "machine2.domain", etc.

    - A "ssh" connection is open. If a file with name "preamble.$machine.pl" exists (being $machine the name of the machine) it will be evaluated in the remote machine $machine. A temporary directory is created and the distribution is transferred (using "scp") to that directory
    - The distribution is unpacked using "tar" and "gunzip". The program then changes directory to the distribution directory
    - If a file "Makefile.PL" exists, the classical sequence
                              perl Makefile.PL
                              make
                              make test

        takes place. Otherwise, if a file "Build.PL" exists, the default sequence is

                              perl Build.Pl
                              ./Build
                              ./Build test

        Options can be passed in each of these steps setting some variables in "local.preamble.pl" (See section "SPECIAL VARIABLES")

    - In case of error the program will proceed with the next machine in the list of arguments
    - After reporting the test results, the temporary directories and files are removed

THE LOCAL PREAMBLE FILE
The local preamble file (by default "local.premable.pl") can be used to initialize the state both in the local and remote machines. If the command option "--localpreamble filename" is specified "filename" will be used instead of "local.premable.pl"

If exists the preamble file is used to set the variables that govern the execution and the environment in which the tests will be performed. The public variables are:

  SPECIAL VARIABLES
The following variables have a special meaning:

•   $makebuilder

    the name of the Perl program that builds the builder. Defaults to "Makefile.PL" if the distribution has one. Otherwise it defaults to "Build.PL" if the distribution has one. If you set a value for $makebuilder and $build these will be used instead.

•   $build

    defaults to "make" or "./Build"

•   $makebuilder_arg

    arguments for "perl Makefile.PL" or "perl Build.PL"

•   $build_arg

    arguments for "make" or "./Build"

•   $build_test_arg

    arguments for "make test" or "./Build test"

•   %preamble

    hash indexed in the machine IPs/names. Values are strings containing the preamble code that will be evaluated in the corresponding machine when the SSH connection is set

THE REMOTE PREAMBLE FILES
When conecting to "machine1.domain" the program checks if a file with name "machine1.domain.premable.pl" exists. If so it will be loaded and evaluated in such machine before running the tests. Settings in this file take precedence over the ones in the hash %preamble

LIMITATIONS

•   No input from "STDIN" is allowed either in your "Makefile.PL" (or "Build.PL") or during any of the testing phases, i.e. your programs must run in batch mode

•   The current version does not allow to change the arguments for "perl Makefile.PL", etc. on a machine basis. The sequence of commands is the the same in each machine

EXAMPLE
I have a file named "local.preamble.pl" in the distribution directory of "GRID::Machine":

  pp2@nereida:~/LGRID_Machine$ cat -n local.preamble.pl
     1  # This code is executed in the local machine
     2
     3  # Redefine them if needed
     4  #our $makebuilder = 'Makefile:PL';
     5  #our $build = 'make';
     6  #our $makebuilder_arg = ''; # s.t. like INSTALL_BASE=~/personalmodules
     7  #our $build_arg = '';       # arguments for "make"/"Build"
     8
     9  our $build_test_arg = 'TEST_VERBOSE=1';
    10
    11  # This code will be executed in the remote servers
    12  our %preamble = (
    13    beowulf => q{ $ENV{GRID_REMOTE_MACHINE} = "orion"; },
    14    orion   => q{ $ENV{GRID_REMOTE_MACHINE} = "beowulf"; },
    15  );

Now when I run "remotetest.pl" for a distribution in machine "beowulf" the environment variable "GRID_REMOTE_MACHINE" will be set in "beowulf" prior to the execution of the tests and the tests will run with "TEST_VERBOSE=1":

  pp2@nereida:~/LGRID_Machine$ remotetest.pl GRID-Machine-0.091.tar.gz beowulf
  ************beowulf************
  Checking if your kit is complete...
  Looks good
  Writing Makefile for GRID::Machine
  cp lib/GRID/Machine.pm blib/lib/GRID/Machine.pm
  ...............................................................
  /usr/bin/perl "-MExtUtils::MY" -e "MY->fixin(shift)" blib/script/remotetest.pl
  Manifying blib/man1/remotetest.pl.1p
  ...............................................................
  PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" \
    "-e" "test_harness(1, 'blib/lib', 'blib/arch')" t/*.t
  t/01synopsis..............1..10
  ok 1 - use GRID::Machine;
  ok 2 - No fatals creating a GRID::Machine object
  ok 3 - installed sub on remote machine
  ok 4 - RPC didn't died
  ok 5 - nested structures
  ok 6 - Remote died gracefully
  ok 7 - Syntax error correctly catched
  ok 8 - Undefined subroutine error correctly catched
  ok 9 - Equal local references look equal on the remote side
  ok 10 - Equal remote references look equal on the local side
  ok
  t/02pod...................1..138
  ............................................................
  All tests successful.
  Files=12, Tests=213, 19 wallclock secs ( 3.12 cusr +  0.32 csys =  3.44 CPU)

To make things more comfortable, I usually set in function "MY::postamble" inside the "Makefile.PL" a target "remotetest" (see ExtUtils::MakeMaker)

  sub MY::postamble {
          my @machines = qw{orion beowulf};

  remotetest:
          remotetest.pl \${DISTVNAME}.tar.gz @machines
  EOT
  }

this way I can simply run the remote test by writing :

  pp2@nereida:~/LGRID_Machine$ make remotetest
  scripts/remotetest.pl GRID-Machine-0.091.tar.gz orion beowulf
  ************orion************
  Checking if your kit is complete...
  Looks good
  ...................................

AUTHOR
Casiano Rodriguez Leon <casiano@ull.es>

COPYRIGHT
(c) Copyright 2008 Casiano Rodriguez-Leon

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.