⏳ Three-minute quickstart guide

Step 1: Install Unison

If you haven't already, please join the #general and #troubleshooting channels on Discord.

We are really hoping that if you are trying out Unison you'll come talk to us, ask questions, and report bugs! We want you to have a welcoming and positive experience when getting started! 😊

brew tap unisonweb/unison
brew install unison-language

curl shttp://debian.unison-lang.org/public.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/unison-computing.gpg
echo 'deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/unison-computing.gpg] https://debian.unison-lang.org/ bookworm main' | sudo tee /etc/apt/sources.list.d/unison-computing.list
sudo apt update
sudo apt install unisonweb
/usr/bin/ucm

sudo apt install apt-transport-https 
curl https://debian.unison-lang.org/public.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/unison-computing.gpg
echo 'deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/unison-computing.gpg] https://debian.unison-lang.org/ bookworm nightly' | sudo tee /etc/apt/sources.list.d/unison-computing.list
sudo apt update
sudo apt install unisonweb
/usr/bin/ucm

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-linux-x64.tar.gz \
	| tar -xz
./ucm

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos-x64.tar.gz \
  | tar -xz
./ucm

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos-arm64.tar.gz \
  | tar -xz
./ucm

Step 2: Create your Unison codebase

Run ucm to initialize a Unison codebase in $HOME/.unison. This is where Unison will store function definitions, types, namespaces, and so on.

Step 3: Create the quickstart project

A Unison codebase is subdivided into many projects. Unison projects represent the various libraries, applications, or programs that you might be working on. From the root of your codebase, represented with ., use the project.create command to make a new quickstart project. It will create a main branch for you to work in.

scratch/main> project.create quickstart

You'll see the UCM download the base standard library into a lib namespace. Namespaces help give structure to Unison code because a Unison codebase isn't saved to the file system. You can think of this as our analog to a directory structure. Namespace segments are separated with the . character. A project's dependencies are located in a special namespace called lib. The code for our quickstart project will be simple, so we only need the base library in scope. Check that the base library has been downloaded by running ls lib.base in the UCM.

quickstart/main> ls lib.base

Run your first program

Head to the text editor of your choosing and create a new file called scratch.u in the directory where you launched ucm (so if you launched ucm from ~/myUnisonCode, you'd create ~/myUnisonCode/scratch.u). Add the following code to the file:

myTerm = List.map (x -> x * 10) [1,2,3,4,5,6]
> myTerm

The first line is defining a Unison term called myTerm. This one multiplies every element in a list by 10, using the jsonschema.lib.base.data.List.map function.

The second, beginning with >, is a watch expression.

The ucm monitors all the unison source files in the current directory for changes and evaluates any watch expressions:

quickstart/main>

  I found and typechecked these definitions in ~/myUnisonCode/scratch.u. If you do an `add` or
  `update`, here's how your codebase would change:

    ⍟ These new definitions are ok to `add`:

      myTerm : [Nat]

  Now evaluating any watch expressions (lines starting with `>`)... Ctrl+C cancels.

    2 | > myTerm
          ⧩
          [10, 20, 30, 40, 50, 60]

Congratulations, you ran your first Unison program!

We want to hear from you!

If you have any trouble with the process, or have ideas about how to improve this document, come talk to us in the #troubleshooting Discord channel!