Imports and Modules

As a program grows, you may want to reuse definitions or calculations from another file. Devlish offers two ways to organize that reuse: Import includes a file’s contents, while Use keeps a module’s names under that module’s name.

This page explains how the compiler finds those files and how to refer to module values. Composition happens during compilation, so the resulting bytecode includes the required sources. Start with Syntax Basics before using qualified module references.

Include another source file

Use Import when definitions or workflow statements in another file should become part of the current compilation. Paths resolve relative to the source file and through configured project search paths. For example, this statement includes a sibling file:

Import "shared_rules.dvl"

Imported content is resolved during compilation. Name collisions and duplicate imports produce diagnostics. For returning intermediate context during execution, see Checkpoints; checkpoints are a separate feature from source reuse.

Modules and Use

Use makes a module available under its own name. A selective form also binds chosen names locally. These are alternative ways to import the bundled math constants:

Use the math module.
Use pi and tau from the math module.

Use brings in a named, namespaced module (DEVL-131). Unlike Import, which inlines a file’s symbols into the flat namespace, a Used module keeps its symbols behind the module name:

• Use the math module. makes the module’s symbols available only through qualified possessive references: math's pi. Module symbols never collide with local names.
• Use pi and tau from the math module. additionally binds the chosen symbols to their plain names at the Use site; binding a name the file already defines is a compile error.
• Module names resolve to the standard library bundled inside the toolchain first (so Use the math module works identically in the CLI, MCP server, and browser WASM compiler, with no filesystem), then to <name>.dvl on the usual search paths (devlish.toml project dirs, DEVLISH_PATH, ~/.devlish/lib/).
• Modules ending in s use the trailing-apostrophe possessive: statistics' mean (this requires a user-supplied statistics module; it is not bundled).
• Repeating Use for the same module is legal; the module body is inlined once per compilation unit.
• Bundled module sources join the artifact’s source_hash closure (listed as stdlib:<name>.dvl in source_files), and the package records the stdlib version and module names under a stdlib key, so governed artifacts stay tamper-evident.

Qualified values

After the corresponding Use statement, read a value through its module:

math's tau times radius

These are expression snippets; use them after equals, Print, or Respond with.

Qualified references to modules that were never Used, or to names a module does not define, are compile errors.