So, even though you have "/home/lib/perl5/site_perl/5.8.5" already in @INC, this does not automatically extend to include the "x86_64-linux-thread-multi" subdirectory of that path, which is where essential components of this module got installed.

To get around that, add to your normal shell environment a setting for "PERL5LIB", which includes both "/home/lib/perl5/site_perl/5.8.5" and "/home/lib/perl5/site_perl/5.8.5/x86_64-linux-thread-multi".

Or, whenever you write a script that uses that module, add "-I" on the shebang line, with that latter path; or push that path onto @INC and then "require" the module.

Both approaches (fixing the shell environment, adding the path in your scripts) have their down-sides for portability (every user has to modify their shell env., or every script has to have hard-coded paths). Maybe there's yet another way that's better, and if so, I hope someone will post that.

(BTW: please use <code> tags, as per Writeup Formatting Tips, not <pre>, so that long strings get wrapped sensibly -- and/or, edit your post to add line breaks to the error message.) Thanks for fixing the formatting.

UPDATE: In testing out the code snippet suggested in my second reply below, I came to understand the difference between these two shell environment variables that control perl's @INC at run-time:

PERLLIB=...  # does NOT interpolate to include OS/build-specific subpa
+ths
PERL5LIB=...  # DOES interpolate to include OS/build-specific subpaths
[download]

But if I "unset PERLLIB" and instead set PERL5LIB to "/Users/graff/perl5/5.8.8", my script doesn't do anything, because @INC already has the "darwin-thread-multi-2level" subdir there.

First, why are you even using Unicode::Map in the first place? What does it do for you that Encode (or PerlIO encoding layers) can't do?

Second, to answer your questions 1 and 3, which I didn't answer in my first reply:

1. This problem comes up for perl programmers who are using a machine where they want to install non-core modules but don't have root privileges (and so cannot write stuff into the standard /usr directory tree). When the desired module involves any sort of OS/cpu dependency (usually, when parts of the module involve compiling code in C), the standard module install process will look at the current perl being used -- i.e. the version/build of perl that is first in the current path -- and create an OS/build-specific place for the compiled code.

This applies to non-root installations, going into some user-writable path like "/home/lib/perl5". It's good for the cases where this path might be shared by multiple machines having different builds of perl (or even by different perl builds available on a single machine, e.g. with and without thread support).

3. I think there would be a fairly easy, generally useful way to "elaborate" your default @INC inventory, but it would involve always using "require" (not "use") for modules that you expect to find in a non-root installation path. Other monks should be able to improve on this in significant ways:

# get the current perl version as a string:
my $pversion = join(".",map{ord()}split //,$^V);

# find paths in @INC that contain or end in that string:
my %inc;
my $build;
for (sort grep m!/\Q$pversion\E(?:/|$)!, @INC) {
    if ( m!/$pversion$! ) {
        $inc{$_} = 0;
    }
    elsif ( m!(.*?$pversion)/([^/]+)$! ) {
        $inc{$1} = 1;
        $build ||= $2;
    }
}
for ( keys %inc ) {
    if ( $inc{$_} == 0 and -d "$_/$build" ) {
        warn "adding $_/$build to INC array\n";
        push @INC, "$_/$build";
    }
}
# now we can "require" modules that have build-specific components
# in paths that have just been added.
[download]

If it's a problem that comes up a lot, I might wrap that in a module... (and make the warning message go away, or only show up when invoked with a "verbose" option).

Even with that, the person writing the script that depends on the "non-root installed" modules still needs to know which modules fall into that category, so as to "require" them after going through the gyrations above, and not just "use" them.

I am absolutely not an expert on this matter. I hope someone more knowledgeable will show us some better way of handling it.