In Variables§

See primary documentation in context for %?RESOURCES

%?RESOURCES is a compile-time variable available to the code of a Distribution.

It contains a hash that provides compile and runtime access to files associated with the Distribution of the current compilation unit. This hash is used to access a special storage for Distribution-wide static files (such as examples of configuration files, templates or data files).

Files available via this variable need to be placed under the Distribution's resources directory:

Module-Foo/
├── lib
│   └── Module
│       └── Foo.rakumod
├── META6.json
├── README.md
└── resources
    └── images
        └── foo.jpg

Additionally, a relative path (starting from the root resources directory of a distribution) to a file may be specified under the "resources" field in the META6.json file:

"resources": [
    "images/foo.jpg"
]

Every resource file is added to an installed Distribution and is accessible using a Hash-like access to %?RESOURCES, returning a Distribution::Resources object:

my $foo-IO = %?RESOURCES<images/foo.jpg>;          # gets an object you can slurp
my $foo-IO = %?RESOURCES<images/foo.jpg>.absolute; # gets an absolute path to a file
my $foo-IO = %?RESOURCES<images/foo.jpg>.open;     # gets an opened IO::Handle to work with

Note that paths and names of resource files can be mangled in an installed distribution, so do not rely on their values in any other case besides using them as keys for the %?RESOURCES variable.

The %?RESOURCES variable is not implemented as a plain Hash, but as an instance of the Distribution::Resources type, so do not expect to see all available resource files in a distribution by printing or by using other ways to inspect its value. Instead, use the API described above to access particular files.

The %?RESOURCES variable is only accessible inside of modules. If you want to access %?RESOURCES outside of a module, you'll need to expose that API yourself. One way to do that is to create a routine in the lib directory to return its value:

unit module MyLib;
sub my-resources is export {
    %?RESOURCES
}

Then create a test file, say, t/resources.t, with contents:

use Test;
use MyLib;

my $resources = my-resources;
isa-ok $resources, Distribution::Resources;

The contents of the compile-time hash are thus exposed to the runtime code.