1Test::Smoke::Syncer(3)User Contributed Perl DocumentationTest::Smoke::Syncer(3)
2
6 Test::Smoke::Syncer - OO interface for syncing the perl source-tree
7
9 use Test::Smoke::Syncer;
10 my $type = 'rsync'; # or 'snapshot' or 'copy'
12 my $syncer = Test::Smoke::Syncer->new( $type => %sync_config );
13 my $patch_level = $syncer->sync;
14
16 At this moment we support three basic types of syncing the perl source-
17 tree.
18 rsync
20 This method uses the rsync program with the "--delete" option to
21 get your perl source-tree up to date.
22 snapshot
24 This method uses the Net::FTP or the LWP module to get the latest
25 snapshot. When the server attribute starts with http:// the
26 fetching is done by "LWP::Simple::mirror()". To emulate the "rsync
27 --delete" effect, the current source-tree is removed.
28 The snapshot tarball is handled by either tar/gzip or
30 Archive::Tar/Compress::Zlib.
31 copy
33 This method uses the File::Copy module to copy an existing source-
34 tree from somewhere on the system (in case rsync doesn't work),
35 this also removes the current source-tree first.
36 forest
38 This method will sync the source-tree in one of the above basic
39 methods. After that, it will create an intermediate copy of the
40 master directory as hardlinks and run the regen_headers.pl script.
41 This should yield an up-to-date source-tree. The intermadite
42 directory is now copied as hardlinks to its final directory
43 ({ddir}).
44 This can be used to change the way make distclean is run from
46 mktest.pl (removes all files that are not in the intermediate
47 directory, which may prove faster than traditional make distclean).
48
50 Test::Smoke::Syncer->new( $type, %sync_config )
51 [ Constructor | Public ]
52 Initialise a new object and check all relevant arguments. It
54 returns an object of the appropriate Test::Smoke::Syncer::* class.
55 Test::Smoke::Syncer->config( $key[, $value] )
57 [ Accessor | Public ]
58 "config()" is an interface to the package lexical %CONFIG, which
60 holds all the default values for the "new()" arguments.
61 With the special key all_defaults this returns a reference to a
63 hash holding all the default values.
64 $syncer->_clear_souce_tree( [$tree_dir] )
66 [ Method | private-ish ]
67 "_clear_source_tree()" removes all files in the source-tree using
69 File::Path::rmtree(). (See File::Path for caveats.)
70 If $tree_dir is not specified, "$self->{ddir}" is used.
72 $syncer->_relocate_tree( $source_dir )
74 [ Method | Private-ish ]
75 "_relocate_tree()" uses File::Copy::move() to move the source-tree
77 from $source_dir to its destination ("$self->{ddir}").
78 $syncer->check_dot_patch( )
80 [ Method | Public ]
81 "check_dot_patch()" checks if there is a '.patch' file in the
83 source-tree. It will try to create one if it is not there (this is
84 the case for snapshots).
85 It returns the patchlevel found or "undef".
87 version_from_patchlevel_h( $ddir )
89 "version_from_patchlevel_h()" returns a "dotted" version as derived
90 from the patchlevel.h file in the distribution.
91 $syncer->clean_from_directory( $source_dir[, @leave_these] )
93 "clean_from_directory()" uses File::Find to get the contents of
94 $source_dir and compare these to {ddir} and remove all other files.
95 The contents of @leave_these should be in "MANIFEST-format" (See
97 Test::Smoke::SourceTree).
98 $syncer->pre_sync
100 "pre_sync()" should be called by the "sync()" methos to setup the
101 sync environment. Currently only useful on OpenVMS.
102 $syncer->post_sync
104 "post_sync()" should be called by the "sync()" methos to unset the
105 sync environment. Currently only useful on OpenVMS.
106
108 This handles syncing with the rsync program. It should only be visible
109 from the "parent-package" so no direct user-calls on this.
110 Test::Smoke::Syncer::Rsync->new( %args )
112 This crates the new object. Keys for %args:
113 * ddir: destination directory ( ./perl-current )
115 * source: the rsync source ( ftp.linux.activestate.com::perl-current )
116 * opts: the options for rsync ( -az --delete )
117 * rsync: the full path to the rsync program ( rsync )
118 * v: verbose
119 $object->sync( )
121 Do the actual sync using a call to the rsync program.
122 rsync can also be used as a smart version of copy. If you use a
124 local directory to rsync from, make sure the destination path ends
125 with a path separator! (This does not seem to work for source paths
126 mounted via NFS.)
127
129 This handles syncing from a snapshot with the Net::FTP module. It
130 should only be visible from the "parent-package" so no direct user-
131 calls on this.
132 Test::Smoke::Syncer::Snapshot->new( %args )
134 This crates the new object. Keys for %args:
135 * ddir: destination directory ( ./perl-current )
137 * server: the server to get the snapshot from ( public.activestate.com )
138 * sdir: server directory ( /pub/apc/perl-current-snap )
139 * snapext: the extension used for snapdhots ( tgz )
140 * tar: howto untar ( Archive::Tar or 'gzip -d -c %s | tar x -' )
141 * v: verbose
142 $syncer->sync( )
144 Make a connection to the ftp server, change to the {sdir}
145 directory. Get the list of snapshots ("/^perl@\d+\.tgz$/") and
146 determin the highest patchlevel. Fetch this file. Remove the
147 current source-tree and extract the snapshot.
148 $syncer->_fetch_snapshot( )
150 "_fetch_snapshot()" checks to see if
151 "$self->{server} =~ m|^https?://| && $self->{sfile}". If so let
152 LWP::Simple do the fetching else do the FTP thing.
153 $syncer->_fetch_snapshot_HTTP( )
155 "_fetch_snapshot_HTTP()" simply invokes "LWP::Simple::mirror()".
156 __find_snap_name( $ftp, $snapext[, $verbose] )
158 [Not a method!]
159 Get a list with all the perl@\d+ files, use an ST to sort these and
161 return the one with the highes number.
162 $syncer->_extract_snapshot( )
164 "_extract_snapshot()" checks the tar attribute to find out how to
165 extract the snapshot. This could be an external command or the
166 Archive::Tar/Comperss::Zlib modules.
167 $syncer->_extract_with_Archive_Tar( )
169 "_extract_with_Archive_Tar()" uses the Archive::Tar and
170 Compress::Zlib modules to extract the snapshot. (This tested verry
171 slow on my Linux box!)
172 $syncer->_extract_with_external( )
174 "_extract_with_external()" uses "$self->{tar}" as a sprintf()
175 template to build a command. Yes that might be dangerous!
176 __vms_untargz( $untargz, $tgzfile, $verbose )
178 Gunzip and extract the archive in $tgzfile using a small DCL script
179 $syncer->patch_a_snapshot( $patch_number )
181 "patch_a_snapshot()" tries to fetch all the patches between
182 $patch_number and "perl-current" and apply them. This requires a
183 working patch program.
184 You should pass this extra information to
186 "Test::Smoke::Syncer::Snapshot->new()":
187 * patchup: should we do this? ( 0 )
189 * pserver: which FTP server? ( public.activestate.com )
190 * pdir: directory ( /pub/apc/perl-current-diffs )
191 * unzip: ( gzip ) [ Compress::Zlib ]
192 * patchbin: ( patch )
193 * cleanup: remove patches after applied? ( 1 )
194 $syncer->_get_patches( [$patch_number] )
196 "_get_patches()" sets up the FTP connection and gets all patches
197 beyond $patch_number. Remember that patch numbers do not have to
198 be consecutive.
199 $syncer->_apply_patches( @patch_list )
201 "_apply_patches()" calls the patch program to apply the patch and
202 updates .patch accordingly.
203 @patch_list is a list of filenames of these patches.
205 Checks the unzip attribute to find out how to unzip the patch and
207 uses the Test::Smoke::Patcher module to apply the patch.
208 $syncer->_read_patch( $file )
210 "_read_patch()" unzips the patch and returns the contents.
211 $syncer->_fix_dot_patch( $new_level );
213 "_fix_dot_patch()" updates the .patch file with the new patch
214 level.
215 __get_directory_names( [$dir] )
217 [This is not a method]
218 "__get_directory_names()" retruns all directory names from "$dir ||
220 cwd()". It does not look at symlinks (there should not be any in
221 the perl source-tree).
222
224 This handles syncing with the File::Copy module from a local directory.
225 It uses the MANIFEST file is the source directory to determine which
226 fiels to copy. The current source-tree removed before the actual
227 copying.
228 Test::Smoke::Syncer::Copy->new( %args )
230 This crates the new object. Keys for %args:
231 * ddir: destination directory ( ./perl-current )
233 * cdir: directory to copy from ( undef )
234 * v: verbose
235 $syncer->sync( )
237 This uses Test::Smoke::SourceTree to do the actual copying. After
238 that it will clean up the source-tree (from MANIFEST, but ignoring
239 MANIFEST.SKIP!).
240
242 This handles syncing by copying the source-tree from a local directory
243 using the link function. This can be used as an alternative for make
244 distclean.
245 Thanks to Nicholas Clark for donating this suggestion!
247 Test::Smoke::Syncer::Hardlink->new( %args )
249 Keys for %args:
250 * ddir: destination directory
252 * hdir: source directory
253 * v: verbose
254 $syncer->sync( )
256 "sync()" uses the File::Find module to make the hardlink forest in
257 {ddir}.
258
260 This handles syncing by getting the source-tree from ActiveState's APC
261 repository. It uses the "Test::Smoke::FTPClient" that implements a
262 mirror function.
263 Test::Smoke::Syncer::FTP->new( %args )
265 Known args for this class:
266 * ftphost (public.activestate.com)
268 * ftpusr (anonymous)
269 * ftppwd (smokers@perl.org)
270 * ftpsdir (/pub/apc/perl-????)
271 * ftpcdir (/pub/apc/perl-????-diffs)
272 * ftype (undef|binary|ascii)
273 * ddir
275 * v
276 $syncer->sync()
278 This does the actual syncing:
279 * Check {ftpcdir} for the latest changenumber
281 * Mirror
282 $syncer->create_dat_patch
284 This needs to go to the *-diffs directory on APC and find the patch
285 whith the highest number, that should be our current patchlevel.
286
288 This handles syncing by setting up a master directory that is in sync
289 with either a snapshot or the repository. Then it creates a copy of
290 this master directory as a hardlink forest and the regenheaders.pl
291 script is run (if found). Now the source-tree should be up to date and
292 ready to be copied as a hardlink forest again, to its final
293 destination.
294 Thanks to Nicholas Clark for donating this idea.
296 Test::Smoke::Syncer::Forest->new( %args )
298 Keys for %args:
299 * All keys from the other methods (depending on {fsync})
301 * fsync: which master sync method is to be used
302 * mdir: master directory
303 * fdir: intermediate directory (first hardlink forest)
304 $syncer->sync( )
306 "sync()" starts with a "traditional" sync according to {ftype} in
307 {mdir}. It then creates a copy of {mdir} in {fdir} with hardlinks
308 an tries to run the regen_headers.pl script in {fdir}. This
309 directory should now contain an up to date (working) source-tree
310 wich again using hardlinks is copied to the destination directory
311 {ddir}.
312
314 rsync, gzip, tar, Archive::Tar, Compress::Zlib, File::Copy,
315 Test::Smoke::SourceTree
316
318 (c) 2002-2003, All rights reserved.
319 * Abe Timmerman <abeltje@cpan.org>
321 This library is free software; you can redistribute it and/or modify it
323 under the same terms as Perl itself.
324 See:
326 * <http://www.perl.com/perl/misc/Artistic.html>,
328 * <http://www.gnu.org/copyleft/gpl.html>
329 This program is distributed in the hope that it will be useful, but
331 WITHOUT ANY WARRANTY; without even the implied warranty of
332 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
333perl v5.12.1 2009-02-08 Test::Smoke::Syncer(3)