Installation

Osmol v0.1 ships as a reference interpreter: one Python file, osmol.py, published on PyPI as the osmol package. Installing takes about one minute, and at the end of this page you will have run the toolchain and downloaded the two canonical example programs.

Requirements

Python 3.9 or newer. The interpreter uses only the standard library: no dependencies, no build step, no compiler.
Also a terminal. That is the whole list.

The entire v0.1 implementation is a single file. If you are here to implement Osmol in another language, that file is also your most compact executable reading of the semantics. See The Reference Interpreter and The v0.1 Pragmas.

Install from PyPI

pip install osmol

If you prefer isolated tool installs, pipx works too:

pipx install osmol

Both install version 0.1.0, the current release.

Windows note

On Windows, Python from the Microsoft Store does not put installed console scripts on your PATH, so a bare osmol command may not be found even though the package installed correctly. For that reason, the canonical invocation everywhere in this book is:

python3 -m osmol

This form works on every platform and every Python install, so this is what we standardize on. On macOS and Linux (and on Windows installs where the scripts directory is on PATH), you may use osmol directly and substitute it in your head throughout.

Verify

Run the interpreter's help:

python3 -m osmol --help

You should see:

usage: osmol.py [-h] [--resolve twin:fact=value] file

Osmol v0.1 reference interpreter

positional arguments:
  file

options:
  -h, --help            show this help message and exit
  --resolve twin:fact=value
                        inject a human judgment for a pending decide

That is the entire command-line surface of v0.1: a file to settle, and --resolve for injecting human judgments into pending decide declarations. (Why judgments must be injected rather than computed is a load-bearing design decision, see Resolving Decides.)

Get the example programs

Two programs ship with the language and anchor its conformance story:

dinner.osmol: the two-twin mesh from spec §8 (maya and raj coordinating dinner), which settles to equilibrium in three flows. You will spend the next two chapters inside it.
spam.osmol: a one-line program that dies at parse time with error[O-000], demonstrating that in Osmol, spam is a syntax error.

Download them from the official repository:

curl -O https://raw.githubusercontent.com/osmol-lang/osmol/main/dinner.osmol
curl -O https://raw.githubusercontent.com/osmol-lang/osmol/main/spam.osmol

(curl is built into Windows 10 and later, macOS, and most Linux distributions. You can also download the files by hand from github.com/osmol-lang/osmol.)

A quick taste of what you just fetched. This is spam.osmol in its entirety:

twin spammer {
  send offer(crypto) to everyone
}

Try running it. The interpreter will refuse, loudly, before any semantics happen. That refusal is the founding gesture of the language: there is no send.

You're done when

python3 -m osmol --help prints the usage text above, and dinner.osmol and spam.osmol sit in your working directory. Then continue to Your First Twin.

The Book of Osmol