Running Unison Programs

📑

What's in this document?

Running a main function

Unison programs can be executed within the UCM with the run command. This command is used to execute the "main" entry point to your Unison code.

🧠
Runnable main functions have this signature: main : '{IO, Exception} someTypeHere.

The run command expects a delayed computation returning any type. The run command 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 the entry point of your Unison program, you can use the getArgs function: getArgs : '{IO, Exception} [Text].

getArgs returns a list of Text representing the arguments of the program in a thunk or delayed computation. Remember to force the thunk with the ! when you actually want the arguments to work with.

✨
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.

The following function will print out the given main function arguments:

runningPrograms.myMain : '{IO, Exception} ()
runningPrograms.myMain : '{IO, Exception} ()
runningPrograms.myMain _ =
  use Text ++
  args : [Text]
  args = getArgs()
  printLine ("Hello " ++ Text.join " " args)

In the UCM, you can call it with run like

project/main> run myMain a b c

And it will return the following to the console:

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 entering into 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 (the "main" method described above), and the second argument is the name of the executable file that the UCM should produce.

Unison executable files 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, you can then issue the following command from the terminal of your choice:

$ ucm run.compiled myRadExecutable.uc

You can supply arguments to the executable in a space-separated list. They'll be accessible in your Unison program via the getArgs function.

🌻 Your Unison program is now up and running!