What is the difference between -I. and -Ilib in Perl6?

Question

I have a local distribution laid out as follows:

.
├── META6.json
└── lib
    └── Foo.pm6

Both perl6 -I. -e 'use Foo;' and perl6 -Ilib -e 'use Foo;' compile and run, so which one should I use and why?

Answer 1

Another way of asking this question would be "What is the difference betweening -I $dir-with-meta6-file and -I $dir-without-meta6-file?". In this answer -I. will technically refer to -I $dir-with-meta6-file, and -Ilib will refer to -I $dir-without-meta6-file. Also note this covers use lib '.' and use lib 'lib'

The difference between -I. and -Ilib can be briefly be summarized:

• -I. will look to the META6.json for what files/namespaces are provided and their version/api/auth

• -Ilib provides all existing files and maps them to a predictable namespace (Foo/Bar.pm6 -> Foo::Bar) and will match any version/api/auth

Generally -Ilib gets used while developing, particularly when starting, because it is easier than manually adding/removing entries in the META6.json file. If you are writing a local application or something that is not intended to be installed this is mostly ok.

However! -I. should be preferred once a META6.json file has be created for the distribution. This can be slightly more work to maintain manually, but it has a few advantages:

• It provides some basic assurance that it will install; a common problem I see is modules passing their tests but failing to actually install because precompilation on install only has access to the files listed in the META6.json file.

• It allows mapping multiple namespaces to a single file (I'm not encouraging this).

• You can have Perl .pm files next to Perl6 .pm6 files as a type of dual-language distribution since you can explicitly tell Perl6 which files to use. -Ilib must consider all .pm and .pm6 files as Perl6, and that is not compatible with this idea.