.. _modules:

Module usage
============

When running Wren programs with the hwren command or embedded into Hare
programs which use the hare-wren runtime via :ref:`wren::api <runtime_api>`,
the default module importer will resolve imports using the following procedure.
Given the following example:

.. code-block:: wren

   import "foo/bar" for Example

The paths searched are, in order:

1. "foo/bar.wren": if, by appending ".wren" and the path relative to the
   current working directory exists, this file is used to resolve the import.
2. "foo/bar.wren", relative to each of the (colon-delimited) elements of the
   ``WRENPATH`` environment variable, or the default paths if unspecified.

If ``WRENPATH`` is not set, the default paths are configured when building and
installing hare-wren, based on the installation prefix. On most Unix systems
this results in:

* /usr/src/wren/third-party
* /usr/src/wren/stdlib

In that order.

Note that the module resolution behavior can be customized by programs which
embed the runtime, so refer to their documentation for the final word in how
modules are located.