Modules and Imports

Mux uses Python-style imports for code organization and reuse.

Basic Import Syntax

basic_import.mux

Python-style imports only
Module paths map directly to file paths
Imported symbols can be used immediately

Standard Library Imports

The stdlib uses the std namespace:

stdlib_imports.mux

import std exposes module namespaces like std.assert, std.math, std.io, std.random, std.datetime, std.sync, and std.net
import std.<module> imports a single stdlib module namespace
import std.* performs a flat import of stdlib items into the current scope

Module Resolution

Module paths map to file paths:

module_resolution.mux

File Structure:

project/
├── main.mux
├── math.mux
├── shapes/
│   ├── circle.mux
│   └── rectangle.mux
└── lib/
    └── core/
        └── util.mux

Using Imports

Basic Usage

math_module.mux

main_import.mux

Aliased Imports

Use as to rename imported modules:

aliased_imports.mux

Imports for Side Effects

Use _ when importing only for side effects:

side_effect_import.mux

Name Mangling

Functions from imported modules use mangled names to prevent conflicts:

fibonacci_module.mux

using_imported_func.mux

Generates LLVM function: math_fibonacci (not just fibonacci)

This prevents conflicts when multiple modules define functions with the same name.

Module Initialization

Top-level statements in modules become initialization functions:

module_init.mux

The compiler:

Generates a module init function
Calls it before main() executes
Ensures each module initializes only once

Dependency Resolution

The compiler processes modules in dependency order:

module_a.mux

module_b.mux

module_c.mux

Initialization order: c -> b -> a -> main

Module Scope

Public by Default

All functions and types are public by default:

public_module.mux

Module-Level Variables

module_variables.mux

using_module_vars.mux

Circular Dependencies

Warning: Avoid circular imports:

circular_a.mux

circular_b.mux

Solution: Restructure to remove circular dependencies or extract shared code to a third module.

Common Module Patterns

Utility Module

utility_module.mux

Type Module

type_module.mux

Constants Module

constants_module.mux

Module Organization

Flat Structure

For small projects:

project/
├── main.mux
├── math.mux
├── utils.mux
└── constants.mux

Hierarchical Structure

For larger projects:

project/
├── main.mux
├── lib/
│   ├── core/
│   │   ├── math.mux
│   │   └── utils.mux
│   ├── data/
│   │   ├── parser.mux
│   │   └── validator.mux
│   └── net/
│       ├── http.mux
│       └── tcp.mux
└── config/
    └── settings.mux

Import Best Practices

Import at the top - All imports at file beginning
Avoid circular dependencies - Restructure if needed
Use descriptive module names - math not m
Alias long names - import very.long.module.path as path
Group related functions - Put related utilities in same module
One module per file - Keep file structure simple
Document public APIs - Comment exported functions
Avoid deep nesting - Keep module hierarchy shallow

Example Project

calculator/
├── main.mux
├── operations/
│   ├── basic.mux
│   └── advanced.mux
└── utils/
    └── format.mux

basic_operations.mux

advanced_operations.mux

format_module.mux

calculator_main.mux

Technical Implementation

Module Compilation

Parse imports - Extract all import statements
Build dependency graph - Determine module order
Process modules - Parse and analyze in topological order
Generate init functions - Create module initialization code
Link modules - Combine into final executable

Name Mangling Details

Module functions are prefixed with their module path:

shapes_circle.mux

Generates: shapes_circle_area (module path becomes prefix)

Basic Import Syntax​

Standard Library Imports​

Module Resolution​

Using Imports​

Basic Usage​

Aliased Imports​

Imports for Side Effects​

Name Mangling​

Module Initialization​

Dependency Resolution​

Module Scope​

Public by Default​

Module-Level Variables​

Circular Dependencies​

Common Module Patterns​

Utility Module​

Type Module​

Constants Module​

Module Organization​

Flat Structure​

Hierarchical Structure​

Import Best Practices​

Example Project​

Technical Implementation​

Module Compilation​

Name Mangling Details​

See Also​