Module not found when extracting documentation

Question

Let's say I have the following two .pm6 files in a directory Foo:

• Vehicle.pm6 - an interface for a vehicle.

=TITLE C<Vehicle> interface

unit role Foo::Vehicle;

#| Get the vehicle to move
method run(--> Nil) { ... }

#| Get fuel into the vehicle
method get-fuel(--> Nil) { ... }

• Car.pm6 - a class that implements the Vehicle interface.

=TITLE C<Car> class

use Foo::Vehicle;
unit class Foo::Car does Foo::Vehicle;

has $!speed = 2;

#| Get the car to move
method run(--> Str) { 
    "{::?CLASS.perl} is moving at {$!speed}km/h."
}

#| Get fuel into the car
method get-fuel(--> Str) { 
    "Getting some fuel..."
}

In the same level as Foo, I have a main.p6 file which instantiates the Car class:

#!/usr/bin/env perl6

use lib '.';
use Foo::Car;

my Foo::Car $car .= new;

say $car.run;       #=> Foo::Car is moving at 2km/h.
say $car.get-fuel;  #=> Getting some fuel...

Up to this point, everything works fine. However when I try to get the documentation from Car.pm6 (with p6doc Foo/Car.pm6), I get the following error:

===SORRY!===
Could not find Foo::Vehicle at line 1 in:
    /home/cosmos/.perl6
    /opt/rakudo/install/share/perl6/site
    /opt/rakudo/install/share/perl6/vendor
    /opt/rakudo/install/share/perl6
    CompUnit::Repository::AbsolutePath<94376788126208>
    CompUnit::Repository::NQP<94376768814296>
    CompUnit::Repository::Perl5<94376768814336>

Answer 1

TL;DR I think this is intended to be a security feature. The error message is LTA. The comments on your question explain what you need to do:

Since you are using use lib '.' in your script, I think you need to add the current directory to the perl6 search path in order for p6doc to find your module – Håkon Hægland

to set perl6 search path to current directory do: PERL6LIB=. p6doc Foo/Car.pm6 – Valle Lukas

This answer provides what I think is the rationale.

I think this issue should perhaps be discussed further with a view toward improving one or more of the error message, the P6 documentation, p6doc and/or the P6 compiler.

I shall be exploring the compiler's source code to better understand what's going on and plan to update this answer at a later date.

---

The acronym/word "pod" was coined for the original Perl series and stood for "plain old documentation". In P6 it's become Pod (note the adjusted spelling convention to distinguish it from the original P5 pod/POD). Pod looks similar to pod/POD but it's a different format.

In particular, it's no longer plain or old -- it's code. Assume it stands for "Produces optimal documentation" or some such.

Per the P6 documentation of Pod it is:

An easy-to-use markup language for documenting Perl modules and programs

Imo it's fairly easy to read in its source form and fairly easy to write. (Though like most of us I've gotten used to the markdown I'm using to write this...)

But imo Pod's most salient characteristic, at least in the context of using it, is that it's code. So it's as easy to use as code. Which is to say, not necessarily easy at all given the issue of malicious code and the security features that keep things safe.

An SO that begins with "The documentation in Perl 6 programs, using the Pod 6 DSL, is actually parsed as part of the code" is a step toward being clear about this. But it's important to realize that it's not just parsed but compiled and that compilation involves running the compiler and, in P6, may even involve running code in the program being compiled.

This is due to the nature of P6 syntax and semantics.

Per wikipedia's page on markup languages they are a system for:

annotating a document in a way that is syntactically distinguishable from the text

But P6 syntax (and semantics) can be dynamically modified by modules. This has compelling upsides¹ but it also means that P6 code must be compiled for the compiler to figure out for sure how to parse it.

And this includes figuring out both what's Pod and how to parse that Pod. Also, the Pod can call P6 code at compile time. So the Pod (and any code it calls) must also be compiled and some of it may have to be run to figure out what the final Pod data is.

You can of course read the Pod in situ by using text viewing tools. It's deliberately designed to be fairly easy to read in raw form.

But if you use p6doc you are compiling P6 code. (In fact, p6doc is a very simple wrapper around the compiler.)

And because in P6 compiling can include running code, the same security policies that one applies to running code in general must apply to using p6doc to extract P6 Pod.

From a security point of view, one should never run code that searches directories on your system and runs code it finds there without your say so.

When you write p6doc foo/bar, you are considered to be telling p6doc that it's OK to compile foo/bar and run any code that is part of compiling that code.

But the use lib pragma is deliberately ignored when the --doc option is provided to the compiler. Hence the answer to your SO in the comments on it.

Footnotes

¹ This makes P6 capable of limitless mutation, both within a single program and as a language that evolves over time. As with any turing complete language, which means just about all of them, if it can be done, P6 can do it. Unlike almost all languages, if you do it and feel it belongs in the language rather than as a module, you can tweak the P6 language to absorb it into your copy of P6. And if P6 folk want your language tweak to be absorbed into everyone's P6, your tweak can then become part of the language's future. Thus P6 makes it easy to modify P6 itself, and is maximally open to future language improvement and essentially eliminates one of the things that can waste a lot of time and energy, namely fighting over what features belong in the language.