Home / Learn / 1 Hello, Una

Release v0.4.0Edition 0.2

1.1 Your first program: hello world

Page 2 of 11

1.1.1 What a program is

A program is a list of instructions for a computer, such as "write this line on the screen". Think of a recipe: it names what it needs, then gives the steps in order, and anyone who follows it gets the same dish. A computer follows a program the same way, one step after another, exactly as written.

You write a program as text, in a file, in a programming language: a small language with strict rules, so that each line has one meaning. That text is the source code, or just the code. This book teaches the language Una.

A few more words come up on every page:

1.1.2 What you need: a terminal and una

Una runs on macOS, on Macs with Apple silicon, and on Linux, on 64-bit ARM computers whose system has glibc 2.39 or later, such as Ubuntu 24.04 (not systems built on musl, such as Alpine): those are the systems this release of una is built for. It does not run on Linux on x86-64 computers, nor on Windows; the install steps give the details.

You work with una in a terminal: the program that shows the console on your screen. To open one:

In the terminal you type a command, a line that names a program and what it should do, and press Enter; the program runs and prints its answer under the command.

Next, install una. Built into it is Z3, a program that una asks to prove facts about your code: to show, before the program runs, that a rule of the code holds in every case. The programs of this chapter need no proof, but from chapter 2 on, una check proves facts with Z3. There is no separate Z3 to install. The install steps install una and say how to set up your terminal so that typing una runs it from any directory.

1.1.3 Checking the install: una --version

To see that the install worked, type una --version and press Enter. It prints the version of una, the editions it supports, which are the versions of the Una language it can read (Making the package says more), and the version of Z3 built into it.

If una --version answers with this line instead, followed by a short note on how to use una, the una that ran is a release older than 0.3, which did not know --version yet:

error: unexpected argument '--version' found

Run the installer again, as the install steps say, to get the current release.

1.1.3.1 When an old una comes first

When you type una, the terminal looks for a program of that name in a list of directories, in order, and runs the first one it finds. That list is your PATH. The installer puts una in ~/.una/bin, where ~ stands for your home directory, but it does not change your PATH for you: when that directory is not on it, the installer prints the line to add. So if una --version still gives the old answer, or the terminal says it cannot find una, put ~/.una/bin at the front of your PATH, once:

  1. Open your shell's profile in your text editor: a file of settings that a terminal reads each time it starts. On macOS it is ~/.zshrc; on most Linux systems it is ~/.bashrc. If the file does not exist yet, create it. Its name starts with a dot, which hides it: in the open dialog of macOS, Cmd+Shift+. shows hidden files.
  2. Add this line at the end of the file, and save it: export PATH="$HOME/.una/bin:$PATH". It puts ~/.una/bin in front of the directories already on your PATH.
  3. Close the terminal and open a new one, so that it reads the profile again.
  4. Type which -a una. It prints the path of every copy of una the terminal can find, the one it runs first at the top. The top line must end in .una/bin/una. Then type una --version again.

An old copy may still be listed under the new one. It does no harm there, since the terminal runs the first copy it finds. If you no longer need it, you can remove it, gently: if your profile has an older line that adds the old copy's directory to PATH, delete that line; then delete the old copy's folder, if it is one you made yourself, such as an unpacked download. Leave a copy that another tool installed, such as a package manager, to that tool, which can remove it.

1.1.4 Hello, world: the whole program

This is a whole Una program. It prints one line, Hello, world, the line that first programs have printed in many languages for decades:

src/hello.unacheckrununa
module hello

--- Greets the world.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("Hello, world")

Each line is explained in this chapter, and you can read most of it already:

To run it, you put it in a package, then ask una to check and run it.

1.1.5 Making the package

Una keeps a program's files together in a package: a directory (a folder) with a manifest, una.toml, a lock file, verification.lock, and the code under a directory named src/. Every program in this book is a package, so it is worth making the first one by hand.

A new terminal starts in your home directory: the directory that holds your own files and directories, such as Documents. The terminal is always "in" one directory, and commands work there. Two commands move you around:

Make the directory hello in your home directory, move into it, and make src inside it:

sh
mkdir hello
cd hello
mkdir src

A path names a file or a directory by the directories that lead to it, separated by /: hello/src is the directory src inside hello, and src/hello.una is the file hello.una inside src. A path without a leading / starts from the directory you are in.

The manifest is a short file of settings that una reads before it reads any code. You write it with a text editor: a program that saves exactly the characters you type, with no fonts or formatting. Any code editor works. On macOS, TextEdit works too, once you choose Format > Make Plain Text before you type, and turn off Edit > Substitutions > Smart Quotes: otherwise TextEdit turns each " you type into a curly quote, “ or ”, which Una does not read as a quote, and una check reports U0001 at it. On Linux, the text editor that comes with your system works. Create a new file, write these lines, and save it in the hello directory with the name una.toml exactly. If the editor offers to add .txt to the name, refuse it: una.toml.txt is a different file, and una does not read it.

una.tomltoml
[package]
name = "hello"
version = "0.1.0"
edition = "0.2"

[run]
entry = "hello"
grants = ["console"]

It has two tables, each a heading in brackets followed by key = value lines:

The second file, verification.lock, tells una which version of Z3 to use and how much work a proof may take, so that a check that passes on your computer passes on every other one. You do not need to understand its lines yet: copy them as they are. The file is the same in every package of this book. Create it with your editor, and save it in hello with the name verification.lock:

Output
encoding_version = "una-smt-1"
solver           = "z3"
solver_version   = "5.1.0"
logic            = "QF_UFLIA"
step_budget      = 5000000
random_seed      = 0

una explain U7004 prints these lines too, under "Fixed example", so you can copy the lock from your terminal at any time. Take that one: the lock it shows first, under "Failing example", is the broken one. Chapter 11 explains both files in full.

Last, save the program itself as src/hello.una: the file hello.una in the directory src.

1.1.6 Checking and running it

In the hello directory, check the package, then run it:

sh
una check .
una run .

The . names the current directory, the package's. una check . prints nothing when the package is right. una run . checks again, then runs main, and the console shows what it prints:

Output
Hello, world

That is your first program. Every program in this book is made the same way: a directory with una.toml, verification.lock and a module under src/, then una check . and una run . in that directory.

1.1.7 If una check finds a mistake

A mistake in a program is normal: everyone makes them while writing code. Una finds as many as it can before the program runs. Here is the program with one letter left out of print:

diff
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,4 @@
 pub main() -> Unit
   uses @console: Console[print]
 =
-  @console.print("Hello, world")
+  @console.prnt("Hello, world")

una check . reports a diagnostic, a report of one problem:

Diagnostic
[U1001] Error: capability `Console` has no operation `prnt`
   ╭─[ src/hello.una:7:12 ]
   │
 7 │   @console.prnt("Hello, world")
   │            ──┬─
   │              ╰─── capability `Console` has no operation `prnt`
   │
   │ Help: repair 1: write `print`; edit src/hello.una:7:12..7:16 to "print"
   │
   │ Note: run `una explain U1001` for an explanation
───╯
1 of 1 diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)

Read it in three steps:

  1. The first line says what is wrong. U1001 is the diagnostic's code, the name of this kind of problem, and the message says that the console has no operation, no action, named prnt.
  2. The box shows where. src/hello.una:7:12 is the file, the line 7 and the column 12, the 12th character of the line. The line is shown under it, and the marks point at the word.
  3. Help suggests a repair. Here: write print. The last line says that una fix ., a command that makes such repairs for you, can make this one.

una run . checks first, so it refuses to run a program with a mistake like this one, and prints the same diagnostic. Fix the word, and una check . prints nothing again. Section 18.2 reads diagnostics in depth.

1.1.8 How a package is laid out

The pieces fit together by name, and una checks each link:

The package's name in una.toml, hello, need not match its directory's name, though here it does.

1.1.9 Check yourself: a first program

You change the doc comment and the text to print, so that main reads:

src/hello.unauna
--- Greets the language you are learning.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("Hello, Una")

What does una run . print now? And what does una check . print?

Show the answer
Output
Hello, Una

una run . prints the new text, exactly as it stands between the double quotes. una check . prints nothing, since the package is still right. The doc comment changed too, but it is a note for people: it prints nothing.

Next:1.2 Modules