Skip to content

Getting started

Three ways to use it, in increasing order of effort.

1. In your browser

Open the playground. Nothing to install, nothing to sign up for.

Pick a programme from the dropdown, or type your own, and press Ctrl or ⌘ + Enter. The five tabs on the right show what it prints, the types it inferred, the scopes, the Python it compiles to, and your source printed back.

Everything runs inside the page. Your code is not uploaded anywhere, and after the first load it works offline. The Copy link button puts your programme in the URL, so you can send it to somebody.

2. On your own machine

You need Python 3.11 or later and uv, which is one command to install:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then:

git clone https://github.com/abilian/astero
cd astero/examples/ocaml
uv run python -m ocaml corpus/fact.ml

That should print 120 three times: corpus/fact.ml computes a factorial three different ways.

uv run builds the environment the first time and reuses it afterwards. There is nothing else to set up, because the compiler is pure Python with no dependencies at all.

The five views, from the command line

Each of the playground's tabs is a flag:

python -m ocaml programme.ml              # run it
python -m ocaml --types programme.ml      # the types it inferred
python -m ocaml --names programme.ml      # the scopes
python -m ocaml --python programme.ml     # the Python it emits
python -m ocaml --printed programme.ml    # your source, printed back

Try one on a programme you know:

$ python -m ocaml --types corpus/tree.ml
val insert : 'a -> 'a tree -> 'a tree
val height : 'a tree -> int
val min_elt : 'a tree -> 'a
val to_list : 'a tree -> 'a list
val summarise : int list -> stats

Nothing in corpus/tree.ml says what type anything has. All of that was worked out.

Your own playground

To run the browser playground from your own copy:

make -C .. web-serve

Then open http://localhost:8000/. That builds the bundle and starts a small web server; press Ctrl+C to stop it.

3. From Python

The compiler is an ordinary package, so you can call the parts directly:

from ocaml.front.parser import parse
from ocaml.middle.infer import signature
from ocaml.back.interpret import run_source
from ocaml.back.compile import compile_source

source = "let rec fact n = if n <= 1 then 1 else n * fact (n - 1)"

signature(parse(source))     # ['val fact : int -> int']
compile_source(source)       # the Python it emits, as a string
run_source(source)           # runs it, and gives back the top-level scope

ocaml.pipeline.analyse(source) runs every stage at once and hands back what each produced. Both the command line and the playground are built on it, so anything you can see in either you can get at from Python.

The example programmes

corpus/ holds eighteen programmes, and reading a few before writing your own will save you time. Eight of them are one per chapter of a typical course:
sorting.ml sorting: insertion, selection, merge, quicksort
stacks.ml stacks and queues, the queue amortised over two stacks
divide.ml divide and conquer: Euclid, fast exponentiation, binary search
dynamic.ml dynamic programming: memoisation, maximum subarray, longest common subsequence
assoc.ml dictionaries, as association lists
polynomes.ml polynomials: Horner, sum, product, derivative
combinatoire.ml Hanoi, subsets, permutations, Gray code
graphes.ml graphs: depth-first and breadth-first traversal

Each has a .expected file, which is exactly what it prints, and a .signature file, which is the types it gets. Those are not decoration: they are what the test suite compares against on every change.

Next