ActiveState::RelocateTree - Relocate a Perl tree, substituting paths at the same time.

- NAME
- SYNOPSIS
- DESCRIPTION
- Using ActiveState::RelocateTree

- The `relocate()` Function
- The `move_tree()` Function
- The `check()` Function
- The `edit()` Function
- The `spongedir()` Function

- SEE ALSO
- AUTHOR
- COPYRIGHT

# NAME

ActiveState::RelocateTree - Relocate a Perl tree, substituting paths at the same time.

# SYNOPSIS

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

# DESCRIPTION

ActiveState::RelocateTree relocates a Perl distribution wholesale into a new distribution. It comes with the script reloc_perl, which is used to install the ActivePerl distribution into the final install location.

Perl can't just be copied into a new location without relocating some files. In Windows this is less of a problem because the executable knows its actual location and uses that to find its library tree. On Unix, the location of the libraries must be encoded within the perl binary. Most scripts also contain a ``shebang'' line of the form `#!/path/to/perl`, which points at the absolute path of the Perl executable.

# Using ActiveState::RelocateTree

The module exports four functions you can use to relocate Perl trees. You can also use these functions to search for and replace arbitrary strings in all files in a directory tree.

## The `relocate()` Function

       relocate(%options);

This is the main entry point that applications will use. It has reasonable defaults, so in most cases you probably just call it like this:

       relocate(to => $to_path);

The following are all recognized options:

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 required.

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 `move_tree()` Function

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

This is the function used to copy the tree from one place to another. It accepts the following parameters:

$from
  The source tree.

$to
  The destination tree.

$delete_after
  A boolean: if true, the tree at $from will be removed.

$verbose
  A boolean: if true, it will print out a message when deleting the $from tree.

## The `check()` Function

       check($file, $regexp, $is_binary);

`check()` checks for occurrences of $from in $file. It is used by `relocate()` to search for files which should be edited. It accepts the following parameters:

$file
  The file to check.

$regexp
  The regular expression to search for in the file.

$is_binary
  A boolean: if true, `check()` uses `binmode()` on the filehandle before reading chunks of the file.

## The `edit()` Function

       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.

## The `spongedir()` Function

       spongedir($name)

The `spongedir()` function returns the spongedir associated with a particular product. Currently, it only knows about PPM's spongedir.

$name
  The name of the spongedir you're interested in. It's case-insensitive, so you can ask for 'PPM', 'Ppm', or 'ppm', too.

  The following spongedirs are defined:

  ppm
    The sponge directory for PPM.

  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

See also reloc_perl.

# AUTHOR

ActiveState Corporation (support@ActiveState.com)

# COPYRIGHT

Copyright (c) 2002, ActiveState SRL. All Rights Reserved.

ActiveState::RelocateTree - Relocate a Perl tree, substituting paths at the same time.