- NAME
- SYNOPSIS
- DESCRIPTION
- SEE ALSO
- COPYRIGHT

# NAME

ActiveState::RelocateTree - copy tree substituting paths at the same time

# SYNOPSIS

       use ActiveState::RelocateTree qw(relocate);
       relocate(from => 'C:\Perl', to => 'D:\lang\perl');

# DESCRIPTION

When a perl installation is copied into a new location, some of its files need to be modified accordingly. The `ActiveState::RelocateTree` module provide functions that helps you do this.

The following functions are provided. None of them are exported by default.

relocate( %options )

  This is the main entry point that applications will use. The following options are recognized:

  `to`

    The tree which must be transformed. Unless the `inplace` option is true, it will copy the tree at `from` to `to` before transforming it. This option is the only one required. The other options have reasonable defaults, so in most cases this is the only option you need to provide.

  `from`

    The path from which to copy the perl tree. Defaults to `$Config{prefix}` , the home of the currently executing perl interpreter.

  `search`

    This is the path which will be searched for and replaced in `to`. This defaults to the value of `from`.

  `replace`

    The replacement value for `search`. This defaults to the value of `to`.

  `inplace`

    If the tree at `to` already exists and you just want to transform it in-situ, use this option. It skips the copying step and just transforms the tree. If `from` equals `to`, it is set to true and cannot be unset. Otherwise it defaults to false.

  `killorig`

    If you're really moving the tree, this option will remove `from` after copying and transforming `to`. Use with care! Defaults to false.

  `bak`

    While relocating the tree, relocate() creates a backup file for each file being edited. This option allows you to specify the extension of backup files. Defaults to `.~1~`.

  `savebaks`

    Normally relocate() deletes the backup files before returning. `savebaks` skips that step, leaving the backup files alone. Defaults to false (backups are deleted).

  `textonly`

    Normally relocate() edits both text and binary files. Text files are replaced using a normal search-and-replace algorithm, but binary files are NULL-padded so that all offsets remain the same. By default, `textonly` is false, i.e. relocate() operates on both text and binary files.

  `ranlib`

    If `ranlib` is true, relocate() will call `ranlib` on binary files which look like library files (have the `$Config{_a}` extension). Defaults to true.

  `verbose`

    If `verbose` is true, relocate() emits warning messages as it performs certain operations. This may be useful for debugging, or for command-line tools, where user feedback is a good thing.

  `quiet`

    Normally, relocate() prints out some status messages even with `verbose` disabled. If `quiet` is true, all messages (except error messages) are temporarily silenced. This option overrides `verbose`, so there isn't much point calling relocate() with both `quiet` and `verbose` set. By default, `quiet` is false.

  `filelist`

    If specified, relocate() will write a list of the files modified to `filelist`, one filename per line. The lines are prefixed with "B " for binary files and "T " for text files.

move_tree( $from, $to )
move_tree( $from, $to, $delete_after, $verbose )

  This function will copy the directory tree at $from to the location $to.

  If $delete_after is TRUE, then tree at $from will be removed after the copy completes. If $verbose is TRUE, then print a message when deleting the $from tree.

check( $file, $regexp, $is_binary )

  Returns TRUE if there are occurrences of $regexp in $file. It is used by relocate() to search for files which should be edited. If $is_binary is TRUE, then read the file in binmode.

edit( $regexp, $from, $dest, $bak, $are_binary, @files )

  edit() is designed to rip though a set of files, efficiently replacing $from with $dest. It operates on the whole set of files, which all need to be of the same type (binary or text). It accepts the following parameters:

  $regexp

    The regular expression to search for. Matching text will be replaced with $dest.

  $from

    The path to search for and replace. If $are_binary is true, this is used to calculate the amount of NUL-padding required to preserve the length of strings. It is not used otherwise.

  $dest

    The replacement string. If $are_binary is true and $dest is shorter than $from, then it inserts a NULL-pad to preserve the original length of the strings.

  $bak

    The extension to use when storing backup files.

  $are_binary

    A boolean: if true, the files are edited with binary semantics: the filehandles are set to binmode, and strings are NULL-padded. Otherwise a plain-old substitution occurs.

  @files

    A list of files to edit.

spongedir( $name )

  Returns the spongedir associated with a particular product. The $name is the spongedir you're interested in. It's case-insensitive. The following spongedirs are known:

  ppm

    The sponge directory to be used in PPM packages.

  thisperl

    The original directory in which this copy of Perl was built. This allows relocate() to detect when a replacement path will not fit into the binary.

# SEE ALSO

reloc_perl

# COPYRIGHT

Copyright 2002 ActiveState Software Inc. All Rights Reserved.