view release on metacpan or  search on metacpan

lib/Doit.pod  view on Meta::CPAN

E<0x2014> making it possible to write "converging" scripts

=item * Command execution is logged E<0x2014> like with Bourne shell's
C<set -x> or make's default mode

=item * There's a dry-run mode which just shows what would happen
E<0x2014> like make's C<-n> switch

=back

Doit scripts are normal Perl scripts which happen to run Doit commands
E<0x2014> no limiting DSL involved, but the full expressiveness of
Perl is available.

To achieve the principles it's required to wrap existing functions. A
number of Perl builtins and module functions which do side-effects on
a system (mostly changes on the file system) are available as Doit
commands. Additionally there's a L<component system|/COMPONENTS> for
supporting typical tasks like managing system packages, adding users,
dealing with source repositories.

Additionally it's possible to run Doit functionality on L<remote
servers|/REMOTE AND USER-SWITCHING FUNCTIONS> (through L<ssh(1)>) or
as L<different users|/REMOTE AND USER-SWITCHING FUNCTIONS> (using
L<sudo(8)>).

It is possible to create Doit scripts for running in bootstrapping
situations. This means that prerequisites for Doit should be minimal.
No mandatory CPAN modules are required, just standard Perl modules.
Only for remote connections L<Net::OpenSSH> is needed on the local
side. For convenient system command execution L<IPC::Run> may be used.
Scripts run with Perl 5.8.x (maybe even 5.6.x is possible).

=head2 CONSTRUCTOR

    my $doit = Doit->init;

Generates an object (technically it's a C<Doit::Runner> object) which
is used for calling Doit commands. The constructor looks for a
command-line option C<--dry-run> (or the short C<-n> alias) and
configures the runner for dry-run mode (just print what would be
executed), otherwise for real mode (actually execute everything).
Other command-line options are still available and may be used in the
script, e.g. by using L<Getopt::Long> or looking into C<@ARGV>:

    use Doit;
    use Getopt::Long;
    my $doit = Doit->init; # already handles --dry-run and -n
    GetOptions(...)
        or die "usage: ...";
    my @files = @ARGV
        or die "usage: ...";

=head2 CORE COMMANDS

All core commands throw exceptions on errors. If not stated otherwise,
then the return value is the number of changes, typically the number
of files affected --- in dry-run mode it's the number of changes which
would be done, and in real mode it's the number of changes performed.

=head3 chmod

    $doit->chmod($mode, $file ...);
    $doit->chmod({quiet => $bool}, $mode, $file ...);

Make sure that the permission of the listed files is set to I<$mode>
(which is typically expressed as an octal number). Fails if not all
files could be changed. If C<quiet> is set to a true value, then no
logging is done. See L<perlfunc/chmod> for more details.

=head3 chown

    $doit->chown($user, $group, $file ...);
    $doit->chown({quiet => $bool}, $user, $group, $file ...);

Make sure that the owner (and group) of the listed files is set to the
given values. The user and group may be specified as uid/gid or as
username/groupname. A value of -1 or C<undef> for I<$user> and
I<$group> is interpreted to leave that value unchanged. This command
is not useful on Windows systems. If C<quiet> is set to a true value,
then no logging is done. See L<perlfunc/chown> for more details.

=head3 create_file_if_nonexisting

    $doit->create_file_if_nonexisting($file ...);

Make sure that the listed files exist. Contrary to L<the Doit touch
command|/touch> and the system command L<touch(1)> this does nothing
if the file already exists.

=head3 copy

    $doit->copy($from, $to);
    $doit->copy({quiet => $bool}, $from, $to);

Make sure that the file I<$from> is copied to I<$to> unless there's
already a file with same contents. Copying is done with
L<File::Copy::copy|File::Copy/copy>. File attributes are not copied
E<0x2014> this can be done using
L<Doit::Util::copy_stat|Doit::Util/copy_stat>.

The logging includes a diff between both files, if the L<diff(1)>
utility is available. This can be turned off by specifying the C<<
quiet=>1 >> option.

=head3 ln_nsf

    $doit->ln_nsf($oldfile, $newfile);

Make sure that I<$newfile> is a symlink pointing to I<$oldfile>,
possibly replacing an existing symlink. Implemented by running the
system's C<ln -nsf>. See L<ln(1)> for more details and L</symlink> for
an alternative.

=head3 make_path

    $doit->make_path($directory ...);
    $doit->make_path($directory ..., { key => val ... });

Make sure that the listed directories exist, together with any missing
intermediate directories. Additional options may be specified as
key-value pairs in a hashref, and will be passed to
L<File::Path::make_path|File::Path/make_path>.

Note that it's possible to set the directory permissions with the
C<mode> option, but the C<make_path> command does not check if an
already existing directory has these permission bits set.

See also L</mkdir>.