My personal favorite “pitfall of Perl” is how to set up CPAN when you are starting on new projects on a new computer, or in a new login-account (say, project specific) on an existing machine. Here’s a quick summary of my lessons-learned, offered as pragmatic wisdom and meant to be “correct enough,” to wit:
Start by searching here for “Perl as a non-root user.” Make sure that you are prepared ... knowing how the cpan command works and what things like o conf do in that context; knowing what @INC means, and what things like the PERL5LIB environment variable do; issuing the perl -V command (with a capital “V”) and knowing the implications of what you see there. If not, do your research first. You will have yourself to thank, and many hair follicles will be saved. (At my age, anyhow, they’re precious indeed.)
Choose the location of your personal private CPAN repository, allocate the directory and make sure that you have access to it without being root. Set the PERL5LIB variable properly to refer to it now, in the proper manner for Linux/Unix vs. Windows, such that this environment variable setting will always be re-established at login and that it is also in place right now before you proceed further. perl -V should reflect your change; see that it does.
If you don’t do this, subsequent module installations won’t seem to “stick,” or prerequisites just-installed(!) won’t appear to be installed at all ... because Perl is not looking for modules in the places where it is installing modules! Perl uses your o conf setting to establish build-locations, but PERL5LIB to determine where to search for modules, yes, even while the cpan command is running. So you must be certain that the desired setting will be established at login a-n-d that it is in effect right now! (Oooh, ouch, how badly that one has bit me!)
There are two different ways to build modules in Perl. Both of them are referred-to in CPAN and both of them ought to be configured because you just can’t be 100% sure which one a particular module might try to use. The most important settings will be ones that cause modules to be installed into your CPAN repository instead of the system-provided one.
CPAN will offer to guess the proper settings for you. While it’s okay to let it run through those initially, then go back and review every one of the settings because many of them will require changes.
I always think that it’s a good idea to set up your own private CPAN for any project, and to do so “per project” so that whatever you do for Client-X does not affect what you are doing for Client-Y. And, never modify anything that the system might provide, except by using whatever “package” installation mechanism your system uses. Many system maintenance tools are built in Perl, and you really don’t want to do anything to jeopardize them. For the same reason, you may or may not want to modify global definitions of PERL5LIB or introduce global definitions of your own, i.e. that might be “seen” by the user that is responsible for running maintenance commands. (At the very least, you need to be fully aware of what is going on, when you run those commands.) Sometimes that software takes matters into its own hands with a use lib statement, but sometimes it may not. There may be no negative side effects, or there may be.
... anyone else chime in?