Terminology§
This is a point in the Raku journey where we need to get specific with some of the terminology, so here are some of the terms which will be used:
compunit: A compilation unit, or compunit for short, is a piece of Raku code that is analyzed and compiled as a single unit. Typically, this comes from a source file on disk, but what's inside an EVAL also counts as such.
script: A script refers to a compilation unit that is provided to Raku as the entry point for execution. In an invocation like raku foo.raku, we say that foo.raku is first compiled and then executed. In Rakudo Raku, in this case, the results of the compilation only exist in memory.
module: A module refers to a compilation unit that is used by a script, or by another module used from a script. A module must also be compiled before it can be made use of. (There is nothing preventing a given source file serving as both a script and a module depending on how it is used).
distribution: A distribution is a set of zero or more scripts and modules that are released together, along with some metadata and potentially resources and tests.
Basic structure§
Module distributions (in the set of related source files sense) in Raku have the same structure as any distribution in the Perl family of languages: there is a main project directory containing a README and a LICENSE file, a lib directory for the source files, which may be individually referred to as modules and/or may themselves define modules with the module keyword [1]
, a t directory for tests, and possibly a bin directory for executable programs and scripts.
See filename extensions for current and historic extensions for various file types.
Distributions§
It is important in this section to repeat the note at the beginning of this document, namely that there is a difference between a Raku distribution, which approximates a module in other languages, and a Raku module declaration. The reason for this is that a single file may contain a number of class, module, role etc declarations, or these declarations may be spread between different files. In addition, when a distribution is published (see Distributing modules) it may be necessary to provide access to other resources, such as callable utilities.
Raku also allows for a single distribution to provide multiple modules that can be used (or required etc). The information about a distribution is contained in the META6.json file in the distribution's root directory. See below for more about META6.json. Each entity that the distribution allows to be used (or required etc), also called a module, is placed in the provides section of the META6.json (as specified below).
It should also be noted that when writing the depends section of the META6.json file, it is the name of the distribution that is listed, not the name of the module that is desired. Although, for very many entities, the name of the distribution and the name of the module are the same. Another global effect of the depends list in a distribution made available to the Ecosystem, is that package managers, e.g. zef, can look for module names in all distributions available.
Given this arrangement, the rakudo compiler, or a package manager such as zef, can obtain all the information needed about each module from a META6.json file in a directory.
Contact information§
To discuss module development in general, or if your module would fill a need in the ecosystem, naming, etc., you can use the #raku on irc.libera.chat IRC channel.
A repository to discuss tooling issues is available at https://github.com/Raku/toolchain-bikeshed.
More information about Distributions§
An introduction (this document)
You may also be interested in: