Running Unison Programs

📑

What's in this document?

Running a main function

Use the run command in the UCM to execute the entry point to a Unison program.

scratch/main> run main
🧠
Runnable main functions have this signature: main : '{IO, Exception} someTypeHere, but the entry point can be called anything, not just main.

The run command expects a delayed computation returning any type. It provides a handler for the IO and Exception abilities, so programs which perform IO and bubble up top-level failures can be executed by the UCM.

Arguments to main functions

To accept arguments to a main function, use the getArgs function:

getArgs : '{IO, Exception} [Text]

getArgs returns a list of Text representing the arguments of the program in a thunk. Remember to force the thunk with () when you actually want the arguments to work with.

runningPrograms.myMain : '{IO, Exception} ()
runningPrograms.myMain : '{IO, Exception} ()
runningPrograms.myMain _ =
  use Text ++
  args : [Text]
  args = getArgs()
  printLine ("Hello " ++ Text.join " " args)
✨
It might be tempting to represent the fact that your main function accepts a list of arguments in its type signature, like main : [Text] -> {IO, Exception} (), but getArgs effectfully reads command line arguments, which is why it's expressed in IO.

In the UCM, you'd call run with arguments like

project/main> run myMain a b c

Hello a b c

()

Stand-alone binaries

The UCM can produce standalone binary executables for when you want to run a Unison program without the CLI. These binary executables contain all the Unison code for the program in question AND its essential dependencies in a single, lightweight bytecode file.

To produce the binary file run the compile command from within the UCM:

scratch/main> compile myMain myRadExecutable

The first argument is the entry point to your Unison program, and the second argument is the name of the file that the UCM should produce.

Unison executables have the suffix .uc so the above command will write a file called myRadExecutable.uc in the folder where the codebase lives.

To run the binary executable, issue the run.compiled command from the terminal of your choice:

$ ucm run.compiled myRadExecutable.uc

You can supply arguments to the executable in a space-separated list.

🌻 Your Unison program is now up and running.