From 2f2198d17ad5b06616a7a8768b037cae9956a496 Mon Sep 17 00:00:00 2001 From: Flavio Poletti Date: Sat, 9 Aug 2008 02:02:19 +0200 Subject: [PATCH] Updated documentation, added --tar command-line option --- deployable | 135 ++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 107 insertions(+), 28 deletions(-) diff --git a/deployable b/deployable index 5f9e7c5..924f246 100755 --- a/deployable +++ b/deployable @@ -37,6 +37,7 @@ GetOptions( output|o=s root|r=s@ rootdir|R=s@ + tarfile|tar=s workdir|work-directory|deploy-directory|w=s ), ); @@ -65,6 +66,29 @@ if ($config{'include-archive-tar'}) { } } +# Establish output channel +my $out_fh = \*STDOUT; +if ($config{output} ne '-') { + open my $fh, '>', $config{output} ## no critic + or croak "open('$config{output}'): $OS_ERROR"; + $out_fh = $fh; +} +binmode $out_fh; + +# Emit script code to be executed remotely. It is guaranteed to end +# with __END__, so that all what comes next is data +print {$out_fh} get_remote_script(); + +# If a tarfile was given, simply put it and exit +if ($config{tarfile}) { + open my $fh, '<', $config{tarfile} + or croak "open('$config{tarfile}'): $OS_ERROR"; + print {$out_fh} <$fh>; + close $fh; + close $out_fh; + exit 0; +} + # Where all the data will be kept my $tar = Archive::Tar->new(); @@ -113,19 +137,6 @@ for my $root (@{$config{root}}) { save_directory($tar, $root, '.', 'root'); } -# Establish output channel -my $out_fh = \*STDOUT; -if ($config{output} ne '-') { - open my $fh, '>', $config{output} ## no critic - or croak "open('$config{output}'): $OS_ERROR"; - $out_fh = $fh; -} -binmode $out_fh; - -# Emit script code to be executed remotely. It is guaranteed to end -# with __END__, so that all what comes next is data -print {$out_fh} get_remote_script(); - # Save tar file, it will close the filehandle as well $tar->write($out_fh); @@ -192,6 +203,7 @@ See version at beginning of script, variable $VERSION, or call [--deploy|--exec|d ] [--heredir|-H ] [--include-archive-tar|-T] [--output|-o ] [--root|-r ] [--rootdir|-R ] + [--tarfile|--tar|-t ] [--workdir|-w ] [ files or directories... ] =head1 EXAMPLES @@ -241,16 +253,23 @@ There are several ways to embed files to be shipped: =item * +pass the name of an already-prepared tar file via L. This is +by far the most flexible of the options, but it requires more work on +your side. If you pass this option, all other input files/directories will +be ignored; + +=item * + specify the file name directly on the command line. A file given in this way will always be extracted into the I, whatever its initial path -was. +was; =item * specify the name of a directory on the command line. In this case, C will be used to archive the directory, with the usual option to turn absolute paths into relative ones; this means that directories will -be re-created under I when extraction is performed. +be re-created under I when extraction is performed; =item * @@ -444,6 +463,35 @@ C. During deployment, hop into C and extract the tarball. This is useful if you have a directory (or a group of directories) that you want to deploy directly under the root. +=item B<< --tarfile | --tar | -t >> + +Use the given file as the only contents for the deployed script. The +filename should point to a valid tar file, which will be the only +one stored into the resulting script (i.e. all other files/directories +will be ignored). This requires more work on your side, but gives you +full flexibility. + +Note that the generated script will interpret the generated tar file +as follows: + +=over + +=item B<< deployable/config.pl >> (file) + +will be Ced, expecting to receive a reference to an anonymous +hash with the configurations; + +=item B<< here >> (directory) + +will be normally deployed into the working directory in the target +system; + +=item B<< root >> (directory) + +will be normally deployed under C in the target system. + +=back + =item B<< --workdir | --deploy-directory | -w >> Set the working directory for the deploy. @@ -489,10 +537,19 @@ to be executed perform / don't perform temporary directory cleanup after work done +=item B<< --deploy | --no-deploy >> + +deploy scripts are executed by default (same as specifying '--deploy') +but you can prevent it. + =item B<--dryrun | --dry-run> print final options and exit +=item B<< --filelist | --list | -l >> + +print a list of files that are shipped in the deploy script + =item B<< --inspect >> just extract all the stuff into for inspection. Implies @@ -500,20 +557,22 @@ C<--no-deploy>, C<--no-tempdir>, ignores C<--bundle> (as a consequence of C<--no-deploy>), disables C<--cleanup> and sets the working directory to C -=item B<--no-deploy> +=item B<--show | --show-options | -s> -prevent execution of deploy scripts (they are executed by default) +print configured options and exit -=item B<--no-workdir> +=item B<< --tar | -t >> -execute directly in workdir (see below), without creating the -temporary directory +print out the tar file that contains all the shipped files, useful +to redirect to file or pipe to the B program -=item B<--show | --show-options | -s> +=item B<< --tempdir | --no-tempdir >> -print configured options and exit +by default a temporary directory is created (same as specifying +C<--tempdir>), but you can execute directly in the workdir (see below) +without creating it. -=item B<--workdir | -w> +=item B<--workdir | --work-directory | --deploy-directory | -w> working base directory (a temporary subdirectory will be created there anyway) @@ -540,6 +599,15 @@ If you just want to see which configurations are in the I: shell$ ./deploy.pl --show +To see which files are included, you have two options. One is asking the +script: + + shell$ ./deploy.pl --filelist + +the other is piping to tar: + + shell$ ./deploy.pl --tar | tar tvf - + Extract contents of the script in a temp directory and simply inspect what's inside: @@ -548,11 +616,13 @@ what's inside: =head2 Deploy Script Requirements -Care has been taken to make the requirements of the deploy script as low -as possible. The result is that you'll need a working Perl with version -at least 5.6.2, and GNU B with support for options C<--touch> and -C<--no-same-owner>. Good luck. +You'll need a working Perl with version at least 5.6.2. +If you specify L, the module L will +be included as well. This should ease your life and avoid you to have +B on the target machine. On the other hand, if you already know +that B will be available, you can avoid including C +and have the generated script use it (it could be rather slower anyway). =head1 DIAGNOSTICS @@ -575,8 +645,15 @@ hard links, of course. =head1 DEPENDENCIES -All core modules, apart from L which is nearly-core. +All core modules, apart the following: + +=over +=item B<< Archive::Tar >> + +=item B<< File::Find::Rule >> + +=back =head1 BUGS AND LIMITATIONS @@ -584,6 +661,8 @@ No bugs have been reported. Please report any bugs or feature requests to the AUTHOR below. +Be sure to read L for a slight limitation +about the availability of the B script. =head1 AUTHOR -- 2.11.4.GIT