.. _readme-module_search:

Module Search Paths
===================

This README describes how modules are located by the current Cray implementation
of Chapel.

Internal modules are always loaded by a chapel program *as if* the
statement ``use ChapelStandard;`` has been inserted ahead of the first
statement in the main module.  Unlike standard modules, internal modules cannot
be overridden.

The compiler uses three module search paths: one for internal modules, one for
standard modules and one for user modules.  The user path first includes all the
paths used to specify module files directly on the ``chpl`` command line and
then includes the paths specified via ``-M`` commands or through
the ``CHPL_MODULE_PATH`` environment variable.

The module search paths are initialized as follows:

    * Internal
        * ``$CHPL_HOME/modules/internal/localeModels/$CHPL_LOCALE_MODEL``
        * ``$CHPL_HOME/modules/internal/tasks/$CHPL_TASKS``
        * ``$CHPL_HOME/modules/internal/comm/$CHPL_COMM``
        * ``$CHPL_HOME/modules/internal``

    * Standard
        * ``$CHPL_HOME/modules/standard/gen/$CHPL_TARGET_PLATFORM-$CHPL_TARGET_COMPILER``
        * ``$CHPL_HOME/modules/standard``
        * ``$CHPL_HOME/modules/layouts``
        * ``$CHPL_HOME/modules/dists``
        * ``$CHPL_HOME/modules/dists/dims``
    * User
        * ``$CHPL_MODULE_PATH``
        * ``(User paths)``

When the root internal module *ChapelStandard* and its dependencies are
loaded, the internal module path is searched first.  If a module is found there,
it is marked as internal.  Otherwise, it is skipped.

The user's modules are parsed next.  If a module named in a use statement is not
found, the standard version is loaded instead if it exists.  Otherwise, a
file-not-found error will be issued.  If both user and standard versions of a
module exist, the user is warned that the standard version is being overridden.
