← Back to AILP Home

search paths — Module Resolution

When importing a module via use, the Nitpick compiler must locate the corresponding source file. This process is governed by the module search path algorithm.

File Path vs Logical Path Imports

There are two primary ways to import modules:

  1. File Path Imports: use "path/to/module.npk".*;
  2. Explicitly specifies a file name and path.

  3. Resolved primarily relative to the importing file.

  4. Logical Path Imports: (Coming soon or used via standard configurations)

  5. Specifies a logical namespace.

Resolution Algorithm

When resolving use "path/to/module.npk", the compiler searches directories in the following specific order:

  1. Relative to Importing File: The directory containing the file that issued the use statement. This is evaluated first, making it easy to import adjacent files.
  2. User Search Paths: Any directories explicitly provided to the compiler via the -I <dir> or --search-path <dir> command-line flags.
  3. Standard Library Directory: The compiler's root installation directory and its stdlib/ subdirectory.
  4. System Directories: System-wide installation paths, such as /usr/lib/aria (on Linux).
  5. Environment Variables: Directories listed in the NITPICK_PATH environment variable. (Delimited by : on Unix-like systems and ; on Windows).

If the module cannot be found in any of these locations, the compiler will emit a Failed to load module error.

The tryFindModule() Strategy

Once a base directory is selected from the algorithm above, the compiler employs a two-step lookup strategy to find the exact file:

For an import path like use "network".*;: 1. Direct Match: It first looks for a file named network.npk directly in the base directory. 2. Directory Match: If the direct file is not found, it checks if network is a directory and looks for a mod.npk file inside it: network/mod.npk.

This behavior allows you to seamlessly transition a module from a single file (network.npk) to a multi-file directory structure (network/mod.npk) without breaking any downstream imports.

Related