NAME

Test::Smoke::Syncer - OO interface for syncing the perl source-tree

SYNOPSIS

use Test::Smoke::Syncer;

my $type = 'rsync'; # or 'snapshot' or 'copy'
my $syncer = Test::Smoke::Syncer->new( $type => %sync_config );
my $patch_level = $syncer->sync;

DESCRIPTION

At this moment we support three basic types of syncing the perl source-tree.

rsync

This method uses the rsync program with the --delete option to get your perl source-tree up to date.

snapshot

This method uses the Net::FTP or the LWP module to get the latest snapshot. When the server attribute starts with http:// the fetching is done by LWP::Simple::mirror(). To emulate the rsync --delete effect, the current source-tree is removed.

The snapshot tarball is handled by either tar/gzip or Archive::Tar/Compress::Zlib.

copy

This method uses the File::Copy module to copy an existing source-tree from somewhere on the system (in case rsync doesn't work), this also removes the current source-tree first.

forest

This method will sync the source-tree in one of the above basic methods. After that, it will create an intermediate copy of the master directory as hardlinks and run the regen_headers.pl script. This should yield an up-to-date source-tree. The intermadite directory is now copied as hardlinks to its final directory ({ddir}).

This can be used to change the way make distclean is run from mktest.pl (removes all files that are not in the intermediate directory, which may prove faster than traditional make distclean).

METHODS

Test::Smoke::Syncer->new( $type, %sync_config )

[ Constructor | Public ]

Initialise a new object and check all relevant arguments. It returns an object of the appropriate Test::Smoke::Syncer::* class.

Test::Smoke::Syncer->config( $key[, $value] )

[ Accessor | Public ]

config() is an interface to the package lexical %CONFIG, which holds all the default values for the new() arguments.

With the special key all_defaults this returns a reference to a hash holding all the default values.

$syncer->_clear_souce_tree( [$tree_dir] )

[ Method | private-ish ]

_clear_source_tree() removes all files in the source-tree using File::Path::rmtree(). (See File::Path for caveats.)

If $tree_dir is not specified, $self->{ddir} is used.

$syncer->_relocate_tree( $source_dir )

[ Method | Private-ish ]

_relocate_tree() uses File::Copy::move() to move the source-tree from $source_dir to its destination ($self->{ddir}).

$syncer->check_dot_patch( )

[ Method | Public ]

check_dot_patch() checks if there is a '.patch' file in the source-tree. It will try to create one if it is not there (this is the case for snapshots).

It returns the patchlevel found or undef.

version_from_patchlevel_h( $ddir )

version_from_patchlevel_h() returns a "dotted" version as derived from the patchlevel.h file in the distribution.

$syncer->clean_from_directory( $source_dir[, @leave_these] )

clean_from_directory() uses File::Find to get the contents of $source_dir and compare these to {ddir} and remove all other files.

The contents of @leave_these should be in "MANIFEST-format" (See Test::Smoke::SourceTree).

$syncer->pre_sync

pre_sync() should be called by the sync() methods to setup the sync environment. Currently only useful on OpenVMS.

$syncer->post_sync

post_sync() should be called by the sync() methods to unset the sync environment. Currently only useful on OpenVMS.

Test::Smoke::Syncer::Rsync

This handles syncing with the rsync program. It should only be visible from the "parent-package" so no direct user-calls on this.

Test::Smoke::Syncer::Rsync->new( %args )

This crates the new object. Keys for %args:

* ddir:   destination directory ( ./perl-current )
* source: the rsync source ( ftp.linux.activestate.com::perl-current )
* opts:   the options for rsync ( -az --delete )
* rsync:  the full path to the rsync program ( rsync )
* v:      verbose

$object->sync( )

Do the actual sync using a call to the rsync program.

rsync can also be used as a smart version of copy. If you use a local directory to rsync from, make sure the destination path ends with a path separator! (This does not seem to work for source paths mounted via NFS.)

Test::Smoke::Syncer::Snapshot

This handles syncing from a snapshot with the Net::FTP module. It should only be visible from the "parent-package" so no direct user-calls on this.

Test::Smoke::Syncer::Snapshot->new( %args )

This crates the new object. Keys for %args:

* ddir:    destination directory ( ./perl-current )
* server:  the server to get the snapshot from ( public.activestate.com )
* sdir:    server directory ( /pub/apc/perl-current-snap )
* snapext: the extension used for snapdhots ( tgz )
* tar:     howto untar ( Archive::Tar or 'gzip -d -c %s | tar x -' )
* v:       verbose

$syncer->sync( )

Make a connection to the ftp server, change to the {sdir} directory. Get the list of snapshots (/^perl@\d+\.tgz$/) and determin the highest patchlevel. Fetch this file. Remove the current source-tree and extract the snapshot.

$syncer->_fetch_snapshot( )

_fetch_snapshot() checks to see if $self->{server} =~ m|^https?://| && $self->{sfile}. If so let LWP::Simple do the fetching else do the FTP thing.

$syncer->_fetch_snapshot_HTTP( )

_fetch_snapshot_HTTP() simply invokes LWP::Simple::mirror().

__find_snap_name( $ftp, $snapext[, $verbose] )

[Not a method!]

Get a list with all the perl@\d+ files, use an ST to sort these and return the one with the highes number.

$syncer->_extract_snapshot( )

_extract_snapshot() checks the tar attribute to find out how to extract the snapshot. This could be an external command or the Archive::Tar/Comperss::Zlib modules.

$syncer->_extract_with_Archive_Tar( )

_extract_with_Archive_Tar() uses the Archive::Tar and Compress::Zlib modules to extract the snapshot. (This tested verry slow on my Linux box!)

$syncer->_extract_with_external( )

_extract_with_external() uses $self->{tar} as a sprintf() template to build a command. Yes that might be dangerous!

__vms_untargz( $untargz, $tgzfile, $verbose )

Gunzip and extract the archive in $tgzfile using a small DCL script

$syncer->patch_a_snapshot( $patch_number )

patch_a_snapshot() tries to fetch all the patches between $patch_number and perl-current and apply them. This requires a working patch program.

You should pass this extra information to Test::Smoke::Syncer::Snapshot->new():

* patchup:  should we do this? ( 0 )
* pserver:  which FTP server? ( public.activestate.com )
* pdir:     directory ( /pub/apc/perl-current-diffs )
* unzip:    ( gzip ) [ Compress::Zlib ]
* patchbin: ( patch )
* cleanup:  remove patches after applied? ( 1 )

$syncer->_get_patches( [$patch_number] )

_get_patches() sets up the FTP connection and gets all patches beyond $patch_number. Remember that patch numbers do not have to be consecutive.

$syncer->_apply_patches( @patch_list )

_apply_patches() calls the patch program to apply the patch and updates .patch accordingly.

@patch_list is a list of filenames of these patches.

Checks the unzip attribute to find out how to unzip the patch and uses the Test::Smoke::Patcher module to apply the patch.

$syncer->_read_patch( $file )

_read_patch() unzips the patch and returns the contents.

$syncer->_fix_dot_patch( $new_level );

_fix_dot_patch() updates the .patch file with the new patch level.

__get_directory_names( [$dir] )

[This is not a method]

__get_directory_names() retruns all directory names from $dir || cwd(). It does not look at symlinks (there should not be any in the perl source-tree).

Test::Smoke::Syncer::Copy

This handles syncing with the File::Copy module from a local directory. It uses the MANIFEST file is the source directory to determine which fiels to copy. The current source-tree removed before the actual copying.

Test::Smoke::Syncer::Copy->new( %args )

This crates the new object. Keys for %args:

* ddir:    destination directory ( ./perl-current )
* cdir:    directory to copy from ( undef )
* v:       verbose

$syncer->sync( )

This uses Test::Smoke::SourceTree to do the actual copying. After that it will clean up the source-tree (from MANIFEST, but ignoring MANIFEST.SKIP!).

Test::Smoke::Syncer::Hardlink

This handles syncing by copying the source-tree from a local directory using the link function. This can be used as an alternative for make distclean.

Thanks to Nicholas Clark for donating this suggestion!

Test::Smoke::Syncer::Hardlink->new( %args )

Keys for %args:

* ddir: destination directory
* hdir: source directory
* v:    verbose

$syncer->sync( )

sync() uses the File::Find module to make the hardlink forest in {ddir}.

Test::Smoke::Syncer::FTP

This handles syncing by getting the source-tree from ActiveState's APC repository. It uses the Test::Smoke::FTPClient that implements a mirror function.

Test::Smoke::Syncer::FTP->new( %args )

Known args for this class:

* ftphost (public.activestate.com)
* ftpusr  (anonymous)
* ftppwd  (smokers@perl.org)
* ftpsdir (/pub/apc/perl-????)
* ftpcdir (/pub/apc/perl-????-diffs)
* ftype (undef|binary|ascii)

* ddir
* v

$syncer->sync()

This does the actual syncing:

* Check {ftpcdir} for the latest changenumber
* Mirror

$syncer->create_dat_patch

This needs to go to the *-diffs directory on APC and find the patch whith the highest number, that should be our current patchlevel.

Test::Smoke::Syncer::Git

This handles syncing with git repositories.

Test::Smoke::Syncer::Git->new( %args )

Keys for %args:

* gitorigin
* gitdir

$syncer->sync()

Do the actual syncing.

New clone git clone <gitorigin> <gitdir> git clone <gitdir> --reference <gitdir> <ddir>
Existing clone cd <ddir> git pull

Test::Smoke::Syncer::Forest

This handles syncing by setting up a master directory that is in sync with either a snapshot or the repository. Then it creates a copy of this master directory as a hardlink forest and the regenheaders.pl script is run (if found). Now the source-tree should be up to date and ready to be copied as a hardlink forest again, to its final destination.

Thanks to Nicholas Clark for donating this idea.

Test::Smoke::Syncer::Forest->new( %args )

Keys for %args:

* All keys from the other methods (depending on {fsync})
* fsync: which master sync method is to be used
* mdir:  master directory
* fdir:  intermediate directory (first hardlink forest)

$syncer->sync( )

sync() starts with a "traditional" sync according to {ftype} in {mdir}. It then creates a copy of {mdir} in {fdir} with hardlinks an tries to run the regen_headers.pl script in {fdir}. This directory should now contain an up to date (working) source-tree wich again using hardlinks is copied to the destination directory {ddir}.

COPYRIGHT

* 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:

* <http://www.perl.com/perl/misc/Artistic.html>,
* <http://www.gnu.org/copyleft/gpl.html>

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.

To install Test::Smoke, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::Smoke

CPAN shell

perl -MCPAN -e shell
install Test::Smoke

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

Test::Smoke::Syncer::Rsync

Test::Smoke::Syncer::Snapshot

Test::Smoke::Syncer::Copy

Test::Smoke::Syncer::Hardlink

Test::Smoke::Syncer::FTP

Test::Smoke::Syncer::FTP->new( %args )

$syncer->sync()

$syncer->create_dat_patch

Test::Smoke::Syncer::Git

Test::Smoke::Syncer::Git->new( %args )

$syncer->sync()

Test::Smoke::Syncer::Forest

SEE ALSO

COPYRIGHT

Module Install Instructions