MiniLang Python reference compiler

MiniLang compiles .ml programs directly to native Windows x64 (PE32+) or Linux x64 (ELF64) executables. This repository contains the Python bootstrap and reference compiler. The self-hosted compiler is written in MiniLang and provides ready-to-run compiler packages.

The reference compiler is distributed as source. See the latest release, release notes and changelog.

Quick start

Save this as hello.ml:

function main(args)
  print "Hello from MiniLang!"
  return 0
end function

From the repository root, on Windows:

python mlc_win64.py hello.ml hello.exe -I .
.\hello.exe

On Linux (Python 3.11 or newer):

python3 mlc_win64.py hello.ml hello --target linux-x64 -I .
./hello

The default target is Windows x64, even when the compiler runs on Linux. Set --target linux-x64 to produce a Linux executable. The output runs on its selected target OS. Top-level statements also work without main; if present, main(args) runs after module initialization and its integer return value becomes the process exit code.

Language and runtime

• Dynamic values with optional checked type annotations, functions, closures, arrays, bytes, structs, enums, packages and imports.
• Classes with single inheritance, virtual methods, override, super, abstract and final members, constructors, visibility rules and inherited interfaces. See the OOP guide.
• Native threads, synchronization, managed tasks and a shared garbage-collected heap on both targets.
• Standard-library modules under std/, native FFI, conditional compilation, typed inline x64 assembly, and error/try propagation.

For example, virtual dispatch calls the derived method:

class Animal
  function speak() returns string
    return "animal"
  end function
end class

class Dog extends Animal
  override function speak() returns string
    return super.speak() + " / dog"
  end function
end class

function main(args)
  pet as Animal = Dog()
  print pet.speak()
  return 0
end function

See the language reference for syntax and the standard-library API reference for generated API documentation.

Compile a project

python mlc_win64.py src/main.ml build/app.exe -I . -I src
python mlc_win64.py --project minilang.toml
python mlc_win64.py --version
python mlc_win64.py --help

A shared project manifest can be used with either compiler:

[project]
entry = "src/main.ml"
output = "build/app.exe"
include = ["src", "vendor"]
target = "windows-x64"
incremental = true
cache_dir = ".minilang-cache"

Paths in the manifest are relative to the manifest file. --project requires Python 3.11 or newer. A direct build can opt into native-function reuse with --incremental-cache DIR; --no-incremental bypasses the cache. See the incremental-build guide.

Option	Use
--target windows-x64|linux-x64	Select the output platform.
-I DIR	Add an import root; repeat as needed.
-DNAME[=VALUE]	Set a typed conditional-compilation option.
--subsystem windows	Build a Windows GUI application.
--asm, --asm-data	Emit an assembly listing and optional data sections.
--heap-reserve SIZE, --gc-limit SIZE	Configure the native runtime.
--profile-calls, --pgo-profile FILE	Collect call counts and guide inlining.

--object-pipeline is accepted for shared build commands but the Python compiler emits the equivalent monolithic image. The self-hosted compiler can also emit and link .mlo objects. Both compiler implementations are expected to produce identical target bytes for the same supported inputs, options and target. Version 1.3.2 restored this parity for the OOP regression programs; see the parity guide and 1.3.2 verification matrix.

Documentation and development

Topic	Document
Classes and interfaces	OOP guide
Language syntax, standard library and FFI	Language reference
Incremental builds	Guide
Typed inline assembly	Guide
Native crypto, checksums and CPU features	Native primitives
Compression and platform services	Platform services
Executable packing	Packing guide
Generated std API	MiniDoc output
Changes and releases	Changelog · Releases

Run the Python regression suite from the repository root on a supported host:

python tests/run_tests.py

Both compiler implementations and their documentation were developed with the assistance of generative AI. Licensed under Apache 2.0; see third-party notices for bundled or generated-code components that require attribution.