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
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
.> edit quickstart.dsort
to add the
dsort distributed mergesort function to the top of a newly created scratch file,
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)).