Three-minute quickstart guide

This short guide will have you downloading and installing Unison and running your first program (a toy distributed mergesort implementation). There isn't much exposition here and the focus is on getting you up and running as quickly as possible. 🏎

More in-depth guides follow this one.

If you have any trouble with the process, or have ideas about how to improve this document, come talk to us in the #alphatesting Slack channel! This document is also on GitHub.

Step 1: Install Unison

If you haven't already, please join the #alphatesting channel on Slack. Once you're logged in, this Slack post gives the (very brief and simple) install instructions.

When Unison is further along and ready for more general availability we'll just include those instructions here. For now, given the many rough edges that exist, we are really hoping that if you are trying out Unison you'll come talk to us, ask questions, and report bugs!

Step 2: Create your Unison codebase

Create a new directory, unisoncode (or any name you choose), then run the ucm binary from within that directory. You'll see a note about "No codebase exists here so I'm initializing one..." and a welcome screen.

Step 3: Fetch and run a distributed mergesort example

Prerequisites for this step: you'll need to have Git installed and on your path.

At the Unison .> prompt, before doing anything else, do:

.> pull https://github.com/unisonweb/quickstart quickstart

to fetch a base library with the first example. You'll see some output from git in the background, and once that's done you'll see a big list of definitions that the pull added. Press q to exit the list of definitions.

First, we'll unpack the new code we just got, to help configure your codebase to match the other examples on the documentation site. 😄

.> move.namespace quickstart.base .base

Next:

.> edit quickstart.dsort

to add the dsort distributed mergesort function to the top of a newly created scratch file, scratch.u:

Open that file and add the following watch expression (a line starting with >) to the top, then save the file:

> runLocal '(quickstart.dsort (<) [8,2,3,1,4,5,6,7])

You should see your watch expression evaluate to a sorted list. You are now up and running!

Disclaimer: This example is a toy that simulates execution locally and does no error handling. It's just meant to be suggestive of the general idea of being able to test Unison distributed programs locally (perhaps with simulated latency and failures injected) and then run them unchanged atop an actual elastic source of distributed compute. This will be something you'll be able to do in Unison in not too long (see the roadmap)).

What next?

Quickstart