3.1. Installing Morloc

Morloc is installed and managed by mim, the Morloc installation manager. It fetches the compiler and runtime, resolves each program’s cross-language package dependencies into one coherent world, and runs, serves, and inspects Morloc programs. There is no separate Morloc install step: mim is the whole of it.

Morloc runs on Linux and on Apple Silicon macOS. On Windows, install through the Windows Subsystem for Linux and follow the Linux instructions inside it.

3.1.1. Installing mim

One command, on Linux (x86-64 or ARM) or Apple Silicon macOS:

$ curl -fsSL https://raw.githubusercontent.com/morloc-project/morloc-manager/main/scripts/install.sh | sh

This downloads the prebuilt mim binary for your platform, checks it against the published SHA-256 when that checksum is reachable, and installs it into ~/.local/bin (or $XDG_BIN_HOME, if you set it). No sudo is needed. Two environment variables adjust it:

Variable Effect

MIM_DEST

Directory to install into. Default: $XDG_BIN_HOME, else ~/.local/bin.

MIM_VERSION

Git tag to install (e.g. v0.31.1). Default: the latest release.

The installer never edits your shell startup files. If the destination is already on your PATH — as ~/.local/bin is on most Linux distributions — you are done:

$ mim --version

Otherwise the installer prints the exact command to add it, which on macOS it usually will: macOS builds its default PATH from /etc/paths, which does not include ~/.local/bin. For zsh, the macOS default shell, that command is:

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Open a new shell afterwards, or run the same export in the current one. mim is the only executable you need on your PATH; everything else lives inside the environments mim manages.

What mim needs from your host

mim is a single static binary with no libraries to install, but it does shell out to a few standard tools:

  • curl — required for fetching data

  • tar — required for unpacking archives.

  • a container engine — if you can’t run native or if you like boxes.

  • nix — if you run NixOS

Those last two are explained next.

3.1.2. Choosing a backend

You do not normally have to choose. mim new probes the host, picks a viable backend, and remembers the choice for later environments.

Native is the default wherever it works. Morloc runs directly on your host against a toolchain mim provisions with conda/pixi into a private directory. Nothing is installed system-wide and no container engine is needed. Container is the fallback, taken automatically when the native backend cannot work; Docker and Podman are supported.

To force one:

$ mim new --engine none      # native
$ mim new --engine podman    # or: --engine docker

If more than one container engine is installed and no default has been recorded yet, mim asks you to name one rather than guessing.

Which hosts get which backend

The native backend works on:

  • Linux with glibc and a standard filesystem layout (Debian, Ubuntu, Fedora, RHEL, Arch, and so on), on x86-64 and ARM

  • macOS on Apple Silicon

  • NixOS, provided the nix toolchain is available and unprivileged user namespaces are enabled. Conda binaries expect the dynamic loader at a path NixOS does not have, so mim builds a buildFHSEnv sandbox to supply one.

Everything else falls back to a container: musl distributions such as Alpine, hosts with a non-standard filesystem layout, NixOS without nix or without user namespaces, and Intel macOS, for which no prebuilt Morloc compiler is published.

Podman notes

Unlike Docker, podman runs rootless by default, so no sudo is required, and on Linux it runs with no daemon.

On macOS and Windows (even through WSL) a virtual machine is required, so you will need to initialize podman first:

$ podman machine init
$ podman machine start
Apptainer / Singularity notes

Apptainer (formerly Singularity) is the usual container engine on HPC clusters. It runs rootless, has no daemon, and uses a single-file image format (.sif) that lives on the shared filesystem, which makes it a natural fit for SLURM-style job dispatch. The historical fork SingularityCE is treated as equivalent; either binary is detected automatically.

Warning
Experimental Feature

Apptainer support is in development and is the least tested of the backends. Creating an environment with --engine apptainer is not currently expected to work: the image build emits a Dockerfile, which Apptainer cannot consume. Use the native backend, or Docker/Podman, until this is finished. The SLURM dispatch described in Execution contexts depends on Apptainer and is blocked behind the same work.

3.1.3. Creating an environment

An environment is a named, self-contained Morloc installation: a solved toolchain of compilers and language runtimes, the Morloc compiler and runtime built against it, and a data directory holding installed modules and binaries. On the container backend that toolchain lives in an image; on the native backend it lives in a private directory on your host. Either way, everything Morloc does happens inside an environment, and environments do not interfere with each other or with anything else on your machine.

Create one and name it base:

$ mim new base
...
Solving native toolchain with pixi (this may take a few minutes)...
...
Native environment 'base' is ready.
Set 'base' as the default environment.

Every setting has a default, so that is the whole command. Pass --wizard to be prompted for each one instead; mim new -h lists them all.

The first run is the slow one. mim downloads the Morloc compiler for your platform, solves a conda toolchain, and builds the Morloc runtime from source against it. Budget several minutes. Later environments reuse the downloaded compiler, and re-running new or update with unchanged requirements skips the solve entirely.

It is also the run that fails if your network inspects TLS. If a download stops with a certificate error, pass your organization’s CA with --cert-bundle; see Troubleshooting.

Without a name, an environment is named after the Morloc version it tracks: latest, or v0.105.2 for a pinned --morloc-version. The first environment you create becomes the default — the one every command targets when you do not pass --env — so base is ready to use immediately.

No language toolchain is installed up front. Python, R, C++, and Rust are provisioned on demand the first time you build a program that uses them, so your first morloc make will also pause to solve and install. Use --lang to pin a language into the environment whether or not a program asks for it:

$ mim new polyglot --lang py,cpp

You can keep as many environments as you like and act on any of them with --env:

$ mim ls                                  # list them; the default is marked
$ mim info base                           # detail on one
$ mim modify --env edge --set-default     # change the default
$ mim rm base                             # remove one

mim info <name> reports the environment’s backend, its Morloc version, the languages in its solved world, and the directories it owns. Add --packages to list every package in the solved world at its locked version.

3.1.4. Working inside an environment

Two ways in. mim run executes a single command:

$ mim run -- morloc --version
0.101.0    # you may have a later version

mim shell drops you into an interactive session:

$ mim shell

Inside that shell morloc is on your PATH, so you can drop the mim run -- prefix. The rest of this manual writes commands as if you are in a mim shell; outside one, prefix them with mim run --.

The shell starts in your current working directory, and changes you make there persist. On the container backend that directory is bind-mounted in. The environment’s module directory persists too, so anything installed into it stays installed.

If you want syntax highlighting before you start typing, skip ahead to Editor support and come back.