Miranda Runner

Prerequisites

• Docker installed.
• Docker available from the terminal.

Docker permissions

Docker needs to be available from the terminal used by VS Code.

On Windows, the user may need to belong to the docker-users group in order to run Docker without permission issues.

On Linux, the user may need to belong to the docker group in order to run Docker without using sudo.

On macOS, Docker Desktop must be installed and running.

Objective

Miranda Runner aims to provide an easy way to run Miranda code independently from the host machine configuration by using Docker.

The extension follows a plug-and-play philosophy: the "plug" step is the initial setup, where the extension is installed and Docker is made available; the "play" step is running Miranda code directly from VS Code using the editor's Play button.

When a *.mir file is opened, the extension is activated and adds a Play button to the editor, allowing the user to request the execution of the Miranda source file directly from VS Code.

Demo

Problem Solved

The Miranda compiler source code is written in C and relies on UNIX system calls that are not available or fully compatible on every operating system, such as Windows.

This creates an adoption barrier, because running a Miranda program should be simple, without requiring users to manually compile the compiler or configure a compatible UNIX-like environment.

Miranda Runner solves this problem by using Docker. The extension builds and runs Miranda inside a container, avoiding host-specific compilation issues. When the user runs a Miranda source file from VS Code, the extension sends an execution request to the Docker container, provides the source file, and displays the result in the VS Code Output panel.

Examples

Create the following files in the same directory:

main.mir
numeric_utils.mir
list.mir

Then open main.mir in VS Code and click the Play button in the editor.

main.mir

%include "numeric_utils.mir"
%include "list.mir"

sqrt 4
2 + 2
fact 0
fact (2 + 2)

len [1,2,3,4]

count 1 []
count 1 [3,4,5]
count 1 [1,1,2]
count 1 (append [1,1,2] 1)

numeric_utils.mir

|| Factorial
fact 0 = 1
fact n = n * fact (n-1)

|| Fibonacci
fib 0 = 0
fib 1 = 1
fib n = fib (n - 1) + fib (n - 2)

list.mir

|| List length
len [] = 0
len (x:xs) = 1 + len xs

|| Count occurrences
count n [] = 0
count n (n:xs) = 1 + count n xs
count n (x:xs) = count n xs

|| Append element to end
append [] n = [n]
append (x:xs) n = x : append xs n