Updated documentation, added --tar command-line option
authorFlavio Poletti <flavio@polettix.it>
Sat, 9 Aug 2008 00:02:19 +0000 (9 02:02 +0200)
committerFlavio Poletti <flavio@polettix.it>
Sat, 9 Aug 2008 00:02:19 +0000 (9 02:02 +0200)
deployable

index 5f9e7c5..924f246 100755 (executable)
@@ -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 <program>] [--heredir|-H <dirname>]
               [--include-archive-tar|-T] [--output|-o <filename>]
               [--root|-r <dirname>] [--rootdir|-R <dirname>]
+              [--tarfile|--tar|-t <filename>]
               [--workdir|-w <path>] [ 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</--tarfile>. 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<tmpdir>, whatever its initial path
-was.
+was;
 
 =item *
 
 specify the name of a directory on the command line. In this case,
 C<tar> 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<tmpdir> when extraction is performed.
+be re-created under I<tmpdir> when extraction is performed;
 
 =item *
 
@@ -444,6 +463,35 @@ C<dirname>. 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 <filename> >>
+
+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 C<eval>ed, 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 <path> >>
 
 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 <dirname> >>
 
 just extract all the stuff into <dirname> 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<dirname>
 
-=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<tar> 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<deploy script>:
 
    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<tar> 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</--include-archive-tar>, the module L<Archive::Tar> will
+be included as well. This should ease your life and avoid you to have
+B<tar> on the target machine. On the other hand, if you already know
+that B<tar> will be available, you can avoid including C<Archive::Tar>
+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<version> 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<CONFIGURATION AND ENVIRONMENT> for a slight limitation
+about the availability of the B<remote> script.
 
 =head1 AUTHOR