morloc README

The project's README from github.com/morloc-project/morloc. As one markdown file: README.md.

github release   license: Apache 2.0   Manual   Discord   Paper   X   BlueSky   Email

Composition

Morloc

Make the function, not the application, the unit of composition

Morloc composes functions across languages under a common type system and transforms modules into rich CLIs, APIs, and MCPs.

Write ordinary code in ordinary languages, source it into a Morloc script, and provide a type. These functions are then first class citizens. They can be used freely within a rich functional language. The Morloc compiler generates the CLI, API, MCP model, and usage statements from the types and declarative docstring instructions.

Install

Morloc runs natively on Linux, macOS (new ARM chips), and Windows WSL.

Run this to install the Morloc Installation Manager (mim):

curl -fsSL https://raw.githubusercontent.com/morloc-project/morloc-manager/main/scripts/install.sh | sh
mim new     # bulid the environment
mim shell   # drop into a shell
mim demo    # pull cool morloc demos

The build is native by default, add the --engine docker flag to build in a container (or podman or apptainer). The environment automatically handles dependencies for Morloc builds via the Pixi package manager. See the manual section Getting Started for more info.

You may freeze Morloc environments into Docker images with mim freeze.

An example

Two functions, in two languages, neither aware of the other. A C++ sum:

// foo.hpp
#pragma once
#include <vector>

double sum(const std::vector<double>& vec) {
    double sum = 0.0;
    for (double value : vec) {
        sum += value;
    }
    return sum;
}

and a parallel map in Python:

# foo.py
import multiprocessing as mp

def pmap(f, xs):
    with mp.Pool() as pool:
        results = pool.map(f, xs)
    return results

Neither file imports anything from Morloc. The Morloc module gives each a type and composes them:

-- sums.loc
module m (sum, sumOfSums)

import root-py
import root-cpp

source Py from "foo.py" ("pmap")
source Cpp from "foo.hpp" ("sum")

pmap :: (a -> b) -> [a] -> [b]

--' Add up a list of numbers
sum :: [Real] -> Real

--' Add up a list of lists, summing each in parallel
sumOfSums :: [[Real]] -> Real
sumOfSums = sum . pmap sum

. is function composition, so sumOfSums reads right to left: pmap sum sums each inner list in parallel, and the outer sum adds the results.

$ morloc make sums.loc
$ ./sums sumOfSums '[[1,2],[3,4,5]]'
15

A Python function called a C++ function across a process boundary, and you wrote no binding, no serializer, and no argument parser.

Free stuff that the compiler generates based on the type

Building the program creats a CLI tool from the given types and docstrings:

$ ./sums -h
Usage: ./sums <nexus_options> <command> <command_options>

Commands:
  sum        Add up a list of numbers
  sumOfSums  Add up a list of lists, summing each in parallel

General Options:
  -h, --help  Print help; -hh adds details and examples, -hhh adds schemas
              (nexus options: -h @)

./sums sum -h goes further and prints the argument types the compiler derived.

It can also serve as an MCP server (./sums --mcp-tools emits JSON Schema tool definitions), an HTTP, TCP, and Unix-socket service, and a module that another Morloc module can import and re-export. None of these are separate builds or a separate descriptions, so none of them can drift from the functions: changing a return type changes all interfaces.

Where the project stands

Morloc has been in development for about ten years and is in beta. I use it for my own work and am currently trying to build a community.

The test suite is massive and growing, but many bugs remain. The core feature is slowly stabilizing, but I still make regular backwards incompatible changes. Play with the cutting edge and you might bleed. Track your blood over here: issue tracker.

Getting involved

The hard part is finished. The ongoing work is the long tail of bug fixes and ecosystem development. That is where I need people. Here's what I'm looking for:

If you are interested in playing with Morloc (or want to drown my in money), feel free to contact me at [email protected].

License

Apache 2.0. See LICENSE.

morloc (morloc-project/morloc)

Searching Database…

219 ·GitHub
Morloc
What is this?Morloc is a strongly-typed, polyglot compiler: it composes functions written in different languages under one common type system and turns each module into a CLI, an API and an MCP server.
Is it a programming language, a compiler, or a framework?It is a compiler for its own small functional scripting language. You write functions in ordinary languages, source them into a Morloc script, give them types, and the compiler builds everything else.
How do I install and build it?Run the install script to get the Morloc Installation Manager (mim), which builds Morloc natively on Linux, macOS on new ARM chips, and Windows WSL. Add the --engine docker flag to build in a container instead.
Do I need to install anything else first?Nothing manual: mim pulls build dependencies automatically via the Pixi package manager. Docker, Podman or Apptainer are only needed for container builds, and mim freeze turns an environment into a Docker image.
Is it stable enough to build on?Not yet: after roughly ten years of development Morloc is still in beta, many bugs remain and the author regularly makes backwards-incompatible changes. Play with the cutting edge and you might bleed.
How does a Python function call a C++ function in Morloc?The compiler generates all the glue for you: the call happens across a process boundary and you write no bindings, no serializers and no argument parsers — you just give both functions types in the Morloc module.
What do I get when I build a Morloc module?One build produces a CLI with derived help text, an MCP server (--mcp-tools emits JSON Schema tool definitions), an HTTP, TCP and Unix-socket service, and an importable module — all generated from the same types, so interfaces cannot drift from the code.
Which languages can my functions be written in?The README demonstrates C++ and Python composing side by side, and Morloc is explicitly polyglot. Language support is still growing — the author invites contributors to bring new languages into the ecosystem.
The author says the hard part is done — what help does he want?Bug reports, typed modules for libraries you already maintain, editor tooling, new languages, and type-system theory. Contact is [email protected].
What are similar projects?swift, unison, crystal, reason, scala, TypeScript, carbon-lang, elixir
Which topics is it in?polyglot, type-system, apis, haskell, interoperability, wsl, language, functional-programming, programming-language, code-generation, compiler, cpp
Creator
morloc-project
Size
22.2 MB
Stars
219
Updated
CommitOct 08Releasev0.109.0Oct 08
Age
9y
Commits · 90 Days