######################################################################
    Sysadm::Install 0.04
######################################################################

NAME
    Sysadm::Install - Typical installation tasks for system administrators

SYNOPSIS
      use Sysadm::Install;

      my $INST_DIR = '/home/me/install/';

      cd($INST_DIR);
      cp("/deliver/someproj.tgz", ".");
      untar("someproj.tgz");
      cd("someproj");

         # Write out ...
      blurt("Builder: Mike\nDate: Today\n", "build.dat");

         # Slurp back in ...
      my $data = slurp("build.dat");

         # or edit in place ...
      pie(sub { s/Today/scalar localtime()/ge; $_; }, "build.dat");

      make("test install");

DESCRIPTION
    Have you ever wished for your installation shell scripts to run
    reproducably, without much programming fuzz, and even with optional
    logging enabled? Then give up shell programming, use Perl.

    "Sysadm::Install" executes shell-like commands performing typical
    installation tasks: Copying files, extracting tarballs, calling "make".
    It has a "fail once and die" policy, meticulously checking the result of
    every operation and calling "die()" immeditatly if anything fails.

  FUNCTIONS

    "cp($source, $target)"
        Copy a file from "$source" to "$target". "target" can be a
        directory.

    "download($url)"
        Download a file specified by "$url" and store it under the name
        returned by "basename($url)".

    "untar($tgz_file)"
        Untar the tarball in "$tgz_file", which typically adheres to the
        "someproject-X.XX.tgz" convention. But regardless of whether the
        archive actually contains a top directory "someproject-X.XX", this
        function will behave if it had one. If it doesn't have one, a new
        directory is created before the unpacking takes place. Unpacks the
        tarball into the current directory, no matter where the tarfile is
        located.

    "mkd($dir)"
        Create a directory of arbitrary depth, just like
        "File::Path::mkpath".

    "rmf($dir)"
        Delete a directory and all of its descendents, just like "rm -rf" in
        the shell.

    "cd($dir)"
        chdir to the given directory.

    "cdback()"
        chdir back to the last directory before a previous "cd".

    "make()"
        Call "make" in the shell.

    "pie($coderef, $filename, ...)"
        Simulate "perl -pie 'do something' file". Edits files in-place.
        Expects a reference to a subroutine as its first argument. It will
        read out the file "$filename" line by line and calls the subroutine
        setting a localized "$_" to the current line. The return value of
        the subroutine will replace the previous value of the line.

        Example:

            # Replace all 'foo's by 'bar' in test.dat
                pie(sub { s/foo/bar/g; $_; }, "test.dat");

        Works with one or more file names.

    "my $data = slurp($file)"
        Slurps in the file and returns a scalar with the file's content.

    "blurt($data, $file, $append)"
        Opens a new file, prints the data in "$data" to it and closes the
        file. If "$append" is set to a true value, data will be appended to
        the file. Default is false, existing files will be overwritten.

AUTHOR
    Mike Schilli, <m@perlmeister.com>

COPYRIGHT AND LICENSE
    Copyright (C) 2004 by Mike Schilli

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.3 or, at
    your option, any later version of Perl 5 you may have available.

