NAME

File::RdistByRsync - read rdist distfiles, emulate using rsync

SYNOPSIS

        use File::RdistByRsync

        @dist_blocks = parse_rdist($distfile, %options)

        ($args, $extras, @dist_blocks) = rdist(@ARGV);

        rsync(@ARGV)

        perl -MFile::RdistByRsync -e 'rsync(qw/rdist command flags/)'

DESCRIPTION

File::RdistByRsync parses and understands rdist distfiles and command lines.

It can share it's understanding by returning what it got (parse_rdist() and rdist()) or it can attempt to emulate rdist using rsync.

Why?

Well, because rdist is so slow it's unusable and rsync has such a limited interface that it's unusable. I'm sure a better specification language than rdist's could be developed, but rdist's language already exists so I used it to drive rsync.

WARNING

As of this writing, this code is still green. Use the -D -n and -v options and look at the output. Look carefully. If it looks good, then try running it for real. If it deletes all your files, then you didn't look carefully enough. Don't blame me. See the LICENSE.

DATA STRUCTURE

The main return value from rdist is an array of distribution blocks.

They look like:

        {
                HOSTS           => [ host1 user@host2 host3 etc...],
                FILES           => [ /etc/rc.* /etc/hosts /usr etc...],
                EXCEPT          => [
                        # tuples of type & file
                        EXCEPT_PAT      /etc/p.*d       # regular expression
                        EXCEPT          /etc/rc.local   # glob
                        RSYNC_EXCLUDE   /etc/rc.loc*    # glob-style pattern exclusions
                        RSYNC_INCLUDE   /etc/rc.*       # glob-style pattern inclusions
                ]
                SPECIAL         => [
                            {
                                FILES   => /etc/login.conf      # glob okay
                                COMMAND => "cap_mkdb $FILE"     # a command to run
                            },
                            {
                                FILES   => /etc/named.conf      # glob okay
                                COMMAND => "ndc reload"         # a command to run
                            },
                        ]
                RSYNC_OPTION    => [ --dry-run --verbose ]
                INSTALL         => [
                            {
                                DESTINATION => /usr             # where to install
                                FLAGS       => {
                                        R => 1,                 # remove extra
                                        w => 1,                 # append whole path
                                }
                            }
                TSFILE          => /some/file                   # touch file name
        }

DETAILS

        @dist_blocks = parse_rdist($distfile, %options)

There is one "dist_block" for each :: or -> entry in the distfile.

The options supported by parse_rdist are DEFINES => {} which override variable definitions made in the distfile and TARGETS => [] which filters the results so that entries that don't match label targets (if any match) and files that don't match file targets are removed.

        ($args, $extras, @dist_blocks) = rdist(@ARGV);

$args comes from Getopt::Declare. See the grammer inside File::RdistByRsync for full details, but basically $args-{"-y"}> is true if @ARGV contained -y.

$extras is a hash of a few items that are sometimes useful. $extras-{HOSTS}> is the list of hosts specified with the -m option. $extras-{DEFINES}> is a hash of -d variable definitions. $extras-{RSYNCOPT}> is a list of rsync options specified in @ARGV. $extra-{TARGETS}> is a list of distfile entries (by label) or filenames given in @ARGV to limit the scope of the invocation. $extra-{CFLAG}> is a dist_block created if there is a command-line style distfile.

        rsync(@ARGV)

The rsync() function does the whole job. The @ARGV parameter should be an rdist-style command line.

COMPATABILITY

All rdist switches except -i are honored. The output is quite different from rdist. Multiple invocations of rsync can be required to do a single rdist.

Two features of rdist are currently ignored: email notification and timestamp checking with :: productions.

There are some additional features that are useful when using rsync().

First, the long-form of rsync command line arguments are noticed by rdist() and used by rsync().

Second, in the -> productions, three new commands are available:

        'rsync_options' <options> ';'
        'rsync_include' <name list> ';'
        'rsync_exclude' <name list> ';'

Rsync_options will be passed to any rsync commands called by rsync() that operate on the block in question.

Rsync_include and rsync_exclude will be passed to rsync with "- " prepended for the excludes and "+ " prepended for the includes. When building rsync exclusion lists, the order of the 'rsync_include', 'rsync_exclude', 'except', and 'except_pat' are taken into account and preserved.

LICENSE

Copyright (C) 2002 David Muir Sharnoff. License hereby granted for anyone to use, modify or redistribute this module at their own risk. Use of this module consitutes an agreement to indemnify and hold harmless the author(s) for whatever might happen when using this code. Please feed useful changes back to muir@idiom.com.