How does a Perl program know where to find the file containing Perl module it uses?

by

Perl interpreter (which runs your perl program) will use a special array called @INC to search for a file containing the module.

Each value in the @INC array is a directory name (but see note below); Perl will search within those directories in a loop using the rules specified below. (Please refer to this SO post for details of how the contents of @INC are determined).

If the module’s file is not found after exhausting @INC, the program’s compilation will be aborted with an error. If the module’s file is found in one of the directories specified in @INC, the search is finished without looking at the rest of @INC.

The way Perl searches for a module file within each of the directories listed in @INC is as follows:

  • First, it will separate the module name’s hierarchical components (words separated by ::), into the last component – which will be used to form a file name – and a hierarchy path (all the components preceding the last ::).

    In case the module name has only one component (no ::, e.g. MyModule1 above), the hierarchy path is empty and the filename is the name of the module. In the second example in this question, the last component is MyModule2 and hierarchy path will be This::Here.

  • The expected file name will be determined by appending the last component of the module name with a .pm extension. E.g. MyModule1.pm and MyModule2.pm in our examples.

    NOTE: Module names are obviously case sensitive on Unix and other operating systems where file/directory naming is case sensitive.

  • The module’s directory will be determined by:

    1. Taking the next directory from @INC – let’s say /usr/lib/perl as an example

    2. Forming a sub-directory of that directory by taking the hierarchy path of the module name (if any) and replacing “::” with / or whatever character the operating system uses as directory separator. In our two examples, the first module will be searched for in /usr/lib/perl (no sub-directory) and the second in /usr/lib/perl/This/Here.

    3. NOTE: the above is a slight simplification – @INC may also contain subroutine references and object references, which load the modules as their custom code specifies instead of performing the lookup in the directory as specified in #2 logic above. That functionality appears to be very seldom used and this article assumes that entire @INC only contains directories.

Let’s go over a specific example, assuming that your @INC contains two sub-directories:
("/usr/lib/perl", "/opt/custom/lib").

Then Perl would search as follows:

==========================================================================
| Module                | Try # | File to try               
==========================================================================
| MyModule1             | Try 1 | /usr/lib/perl/MyModule1.pm
| MyModule1             | Try 2 | /opt/custom/lib/MyModule1.pm
==========================================================================
| This::Here::MyModule2 | Try 1 | /usr/lib/perl/This/Here/MyModule2.pm
| This::Here::MyModule2 | Try 2 | /opt/custom/lib/This/Here/MyModule2.pm
==========================================================================

Please recall that Perl interpreter will STOP trying to search once it finds the file in one of the locations, without trying to see if the file is in later locations as well. E.g. if /usr/lib/perl/This/Here/MyModule2.pm exists, then Perl will not look for, nor care about the existence, of /opt/custom/lib/This/Here/MyModule2.pm.

NOTE: @INC is used whenever Perl interpreter is using require-like mechanism for importing Perl modules. This includes:

  • require directive itself
  • use MyModule statement (equivalent to require+import)
  • use base (equivalent to require+”push @ISA”)
  • -M command line parameter

More Related Contents:

  1. How is Perl’s @INC constructed? (aka What are all the ways of affecting where Perl modules are searched for?)
  2. How do I include functions from another file in my Perl script?
  3. Manual installation of a Perl Module
  4. How do I get the full path to a Perl script that is executing?
  5. Which framework should I use to write modules? [closed]
  6. Converting relative path into absolute path?
  7. Convert Bash script to Perl/VBS/any other windows compatible language [closed]
  8. Redirecting the perl script
  9. How can I troubleshoot my Perl CGI script?
  10. How can I install Perl modules without root privileges?
  11. How to add include path in Qt Creator?
  12. How do I compare two strings in Perl?
  13. What is the difference between ‘my’ and ‘our’ in Perl?
  14. Difference between &function and function() in perl [duplicate]
  15. How do you round a floating point number in Perl?
  16. Why do I have to specify the -i switch with a backup extension when using ActivePerl?
  17. Why is this program valid? I was trying to create a syntax error
  18. Find size of an array in Perl
  19. What does the -> arrow do in Perl?
  20. What’s the difference between iterating over a file with foreach or while in Perl?
  21. What’s the differences between system and backticks and pipes in Perl?
  22. How to ignore ‘Certificate Verify Failed’ error in perl?
  23. How do I make Perl scripts recognize command-line parameters in the Win32 cmd console?
  24. How can I get a call stack listing in Perl?
  25. How can I find the version of an installed Perl module?
  26. root path doesn’t work with php include
  27. How can I escape an arbitrary string for use as a command line argument in Bash?
  28. What does “select((select(s),$|=1)[0])” do in Perl?
  29. Nested subroutines and Scoping in Perl
  30. Why doesn’t print output anything on each iteration of a loop when I use sleep?

Leave a Comment