Distributions: an introduction
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.
Documentation about Modules
Want to distribute your modules?
Distributions: An introduction (this page)
[1]As synopsis S11 says: Confusing? Yes it is.