Module Discovery

As previously established, modules typically reside in files within a file system. Since a module is essentially just a file with a .avail extension, modules can obviously exist at arbitrary locations within a file system. It goes without saying then that the compiler cannot automatically discover every existing module. For the compiler to behave so conveniently, it would need to recursively explore every mounted file system. Given the storage capacity of modern devices and the organizational complexity of modern file systems, this kind of nicety is prohibitively expensive. It is the therefore the responsibility of an Avail programmer to seed the module discovery process with reasonable starting points.

Every module visible to the compiler resides, directly or indirectly, within a module root. A module root is an abstract location supplied to the compiler as a starting point for module discovery. Each module root is given a distinct name — the module root name — that the system can use to provide diagnostic messages about modules. The compiler can be seeded with arbitrarily many module roots. If a module is not recursively contained by one of these roots, then it cannot be discovered.

The module roots are supplied to the compiler by means of a module roots path. A module roots path satisfies the ModuleRootsPath syntax diagram:

ModuleRootsPath

A module roots path comprises zero or many module root specifications. A module root specification is a binding between a module root name and a module root path. A module root specification satisfies the nonterminal ModuleRootSpecification, and corresponds to the following syntax diagram,

ModuleRootSpecification

where the terminal moduleRootName denotes a module root name. A module root path conjoins a binary repository path and a source module path. A module root path satisfies the ModuleRootPath nonterminal, and corresponds to the following syntax diagram,

ModuleRootPath

where the terminal binaryPath is a binary repository path and the terminal sourcePath is a source module path. A binary repository path specifies a regular file encoded in the binary repository format used by the compiler and executor. If the binary repository path specifies a location that does not correspond to an existing file, then the compiler will create an appropriate file at this location and populate it with the results of compilation. A source module path specifies a file system directory that recursively contains source modules.

All official Avail tools released and supported by The Avail Foundation, LLC, such as the Avail workbench and the command-line Avail compiler, support specification of the module roots path via the AVAIL_ROOTS environment variable.^[1]

The Avail Foundation, LLC, reserves all single-word module root names for its own usage. At the present time, these are the single-word module root names actually in use:

To avoid collisions between vendors and projects, the Avail Foundation, LLC, strongly recommends that module root names follow the reverse domain name convention. If you have registered sparkling-walrus.com and you sell a product called Virtual Walrus Polisher Plus, then you should choose something like com.sparkling-walrus.polisherplus as the module root name for your product.^[2] If you have not registered a domain name, or are developing an Avail project for personal use, then you are encouraged to use a long, hierarchical name in order to reduce the likelihood of collision.

[1] These tools may also permit the module roots path to be specified by some other means, but they will always honor the AVAIL_ROOTS environment variable.

[2] I am, of course, assuming that you are already using com.sparkling-walrus.polisher for your previous product.