http://qs321.pair.com?node_id=73053

clwolfe has asked for the wisdom of the Perl Monks concerning the following question:

I have perl installed as follows:
/usr/local/bin/perl -> perl-5.6.1 /usr/local/bin/perl-5.005 /usr/local/bin/perl-5.6.0 /usr/local/bin/perl-5.6.1 /usr/local/bin/perl-5.7.0

And likewise for perldoc, and all of the other binaries and scripts in the standard dist. (I also created cpan-5* shell script with obvious behaviour)

/usr/local/lib/perl5 looks like this:
5.005/ 5.6.0/ 5.6.1/ 5.7.0/ site_perl/
FYI, /usr/bin/perl is a link to /usr/local/bin/perl . In other words, I've got multiple installed versions, with 5.6.1 as the default. I was sure to make the cpan scripts call a specific version of perl, ie here's cpan-5.005 :
#!/usr/local/bin/perl-5.005 -MCPAN -e "shell;"
I've doen some sanity checks and testing, and yep, executing cpan-5.6.1 as root really does install to the 5.6.1 library without touching the others. And perl-VERSION -V is correctly configured. To manually install a module ("manual" as opposed to CPAN - relative laziness), it's just:
perl-VERSION< make && make test && make install

And if we forget, we get the default perl lib, which is currently 5.6.1 . Which is very nice way to break.

Now, our own Perl modules use MakeMaker and so forth to build, test, and install, so the above works for our own modules as well. Now it's really easy to test against different versions of perl.

At this point I must pause to give thanks to the designers of the Perl distribution and installed layout. It wouldn't be possible to do this without the good planning and clear thought that went into so many details of the Perl building and distribution system. But I digress.

Now, I'd like to have perldoc-VERSION give documentation about the installed VERSION library, and perldoc give docs about the default (5.6.1) library. Unfortunately, that doesn't seem to work: I always get back the 5.6.1 docs (or at least that's what the header and footer says). Of course, perldoc-VERSION is itself written in perl: so I edited the shebang line to point to specific versions of perl, ie /usr/local/bin/perl-5.7.0 for the bleeding-edge perldoc-5.7.0 . I was hoping this would "just work" - but alas, the header still says 5.6.1 , for all perldoc-VERSION .

My next step is to read the perldoc source code in depth, and to see what I learn that way. If someone knows off the top of their head, I would much appreciate either further pointers to more info, or an in-depth, lavishly illustrated, annotated-bibliography-attached reply (sarcasm).

Before I do that though, I'll do a quick dump of why I'm at a loss. Show me where I stray from the path of wisdom, o masters! (Aside from anthropomorphizing a perl script)

If I were perldoc, I think my job would be to run accross the perl library, and extract the requested docs (presumably in the module itself, in POD format). Since I'm a perl script, all I do is ask my perl interpreter where it would find libraries. There's a number of obvious ways to ask this: @INC, Config.pm.... possibly others. Now, I know for a fact that perl-VERSION -V lists the correct, VERSION-specific @INC, and so it would presumably find the correct, VERSION-specific modules to snarf PODs out of.... && I know I'm calling the right, VERSION-specific perl binary in the shebang at the top of perldoc-VERSION.

Hence, stumped. I now set myself in meditation upon, if you will, a Holy Writing: the source code of perldoc, Perl by those who Make Perl. Oh, the drama!

Replies are listed 'Best First'.
Re: Getting perldoc to recognize different perl versions
by Starky (Chaplain) on Apr 17, 2001 at 09:36 UTC
    perldoc is itself a perl script.

    It searches @INC to find your modules. You just need to stuff your 5.00503 (or whatever you're looking for) directories into the @INC array before the 5.6.1 directories.

    So to look at a module in the 5.00503 tree, you could do something like

      perl -I/usr/lib/perl5/site_perl/5.005 `which perldoc` Foo::Bar::Baz
    
    Hope this helps!
Re: Getting perldoc to recognize different perl versions
by arturo (Vicar) on Apr 17, 2001 at 18:12 UTC

    Here's a possiblity: make symlinks to the 'real' perldoc script as you've suggested. Then, pop in a little wrapper at the top of your real perldoc script that sees how it was called ($0 holds the value you want to check) and adjusts @INC accordingly ...

    Philosophy can be made out of anything. Or less -- Jerry A. Fodor

(tye)Re: Getting perldoc to recognize different perl versions
by tye (Sage) on Apr 17, 2001 at 20:34 UTC

    That should work.

    The only thing I found that makes sense to me that might be breaking it is the

    eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' if 0;
    trickery that is in my copy of perldoc.

    Perhaps you broke the #! line or are using a shell that doesn't honor them.

            - tye (but my friends call me "Tye")
      Aha!
      As many people have responded, and as I noted in my original posting, the shebang of perldoc was the first place to look, which I had already changed.

      I then tried perldoc -v -f foo to see where it was looking. Lo and behold, perldoc-5.7.0 said it was looking in /usr/local/lib/perl5/5.7.0 (etc). Funny...so I tried a more pragmatic test:

      perldoc-5.005 -f our No documentation for perl function 'our' found perldoc-5.7.0 -f our ('our'section of perlfunc appears)
      OK, so it seems to be working! But the footer of the paged output says perl5.6.1, regardless of the actual documentation being displayed! Why???

      So, reading perldoc's sourcecode, we find on line 328, a backtick system call to pod2man. AHA!! Of course, pod2man-VERSION's shebang points to /usr/local/bin/perl, which is really 5.6.1 . pod2man must get that version number from its perl interpreter (reasonably so), and then sticks it in the footer of the output.

      So, I edited perldoc-VERSION to call pod2man-VERSION, and edited pod2man-VERSION to use perl-VERSION in the shebang line.

      Mystery solved. Thanks for all of the responses, and I hope that others have found this to be educational.