require-at-inc.txt

=title How does require find the module to be loaded?
=timestamp 2017-01-22T00:30:11
=indexes @INC, require, -V
=books advanced
=tags screencast
=status show
=author szabgab
=comments_disqus_enable 0

=abstract start

Now you know <a href="/modules">how to create a module in Perl</a>, but it is not yet clear how did perl find the <hl>Calc.pm</hl>
file in the previous example? After all we only wrote <hl>require Calc;</hl>.

=abstract end

<slidecast file="advanced-perl/libraries-and-modules/require-at-inc"  youtube="ZDLkN2kCx2Y" />


Before going further though two things:

You probably have already used modules in Perl and you have probably used the <hl>use</hl> keyword to load the
modules. Don't worry, everything you see here about <hl>require</hl> also applies to <hl>use</hl> as internally <hl>use</hl>
calls <hl>require</hl>.

You have probably also seen modules with one or more double-colon pairs between names. So not only <hl>Calc</hl>, but
<hl>Math::Calc</hl>, and even <hl>Math::Calc::Clever</hl> are possible names.

When you write <hl>require Calc;</hl> perl will look through the directories listed in the array called <hl>@INC</hl>
for a file called <hl>Calc.pm</hl>.

The content of <hl>@INC</hl> was embedded in perl when perl itself was compiled. Later we'll see how can
we change it to <a href="/how-to-change-inc-to-find-perl-modules-in-non-standard-locations">find module in non-standard locations</a>
or in a <a href="/how-to-add-a-relative-directory-to-inc">directory relative to our script</a>

If you'd like to find out what is in <hl>@INC</hl>, you can run <hl>perl -V</hl> on the command line. At the end of the output you will
see the list of directories. For example on OSX I got this:

<code>
  @INC:
    /Library/Perl/5.18/darwin-thread-multi-2level
    /Library/Perl/5.18
    /Network/Library/Perl/5.18/darwin-thread-multi-2level
    /Network/Library/Perl/5.18
    /Library/Perl/Updates/5.18.2
    /System/Library/Perl/5.18/darwin-thread-multi-2level
    /System/Library/Perl/5.18
    /System/Library/Perl/Extras/5.18/darwin-thread-multi-2level
    /System/Library/Perl/Extras/5.18
    .
</code>

On MS Windows using <a href="http://strawberryperl.com/">Strawberry Perl</a> I got this:

<code>
  @INC:
    C:/strawberry/perl/lib
    C:/strawberry/perl/site/lib
    C:\strawberry\perl\vendor\lib
    .
</code>

Note, in both cases the <hl>.</hl> indicating the current directory can be found in the list at the last position. This means
if the module is in the current directory, perl will find it. On the other hand, if the module is in the <hl>lib/</hl> subdirectory
then perl won't find it without some extra help.


If you require a module that has a double-colon in its name, for example <hl>Math::Calc</hl> then perl will look for a subdirectory
called <hl>Math</hl> in the directories listed in <hl>@INC</hl>, and within that <hl>Math</hl> subdirectory it will look
for a file called <hl>Calc.pm</hl>.

The first one it finds will be loaded into memory. So there might be several such files in the directories listed in <hl>@INC</hl>,
but perl will find the first one and disregard the rest.

If you <hl>require Math::Calc::Clever;</hl> then perl will look for a subdirectory called <hl>Math</hl> in the directories listed
in <hl>@INC</hl>. Inside the <hl>Math</hl> directory it will look for a directory called <hl>Calc</hl> and in that directory
a file called <hl>Clever.pm</hl>.

If perl cannot find the right file in any of the directories it will throw an exception
<a href="/cant-locate-in-inc">Can't locate ... in @INC</a>.