---
title: "1.1 Your first program: hello world"
url: https://una-lang.org/en/learn/hello/your-first-program-hello-world/
release: v0.4.0
edition: "0.2"
---

# 1.1 Your first program: hello world

## 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:

- **Running** a program means having the computer follow its instructions.
- The **console** is the window of text where you type commands and where a program writes its lines. [Section 1.5](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-5) covers it.
- `una` is the tool that reads Una code. It **checks** the code, which means it looks for mistakes without running it, and it **runs** the code when the check passes.

## 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](https://una-lang.org/en/docs/get-started/#1-install) give the details.

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

- on macOS, open the Terminal app, in Applications > Utilities, or find it by typing "Terminal" in Spotlight, which [[Cmd]]+[[Space]] opens;
- on Linux, open the Terminal app from your applications menu; on many systems [[Ctrl]]+[[Alt]]+[[T]] opens 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](https://una-lang.org/en/learn/numbers/) on, `una check` proves facts with Z3. There is no separate Z3 to install. The [install steps](https://una-lang.org/en/docs/get-started/#1-install) 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](#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](https://una-lang.org/en/docs/get-started/#1-install) 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:

```una include="steps/01-hello/src/hello.una" title="src/hello.una" verified="check, run"
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:

- `module hello` names this file of code. [Section 1.2](https://una-lang.org/en/learn/hello/modules/#s1-2) covers modules.
- `--- Greets the world.` is a note for people, which the computer does not run.
- `pub main() -> Unit` and the lines under it are the function `main`, where the program starts. [Section 1.3](https://una-lang.org/en/learn/hello/the-main-function/#s1-3) covers `main`.
- `uses @console: Console[print]` says that this function may print on the console. [Section 1.5](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-5) covers printing, and [chapter 12](https://una-lang.org/en/learn/capabilities/) covers what `uses` can say in full.
- `@console.print("Hello, world")` prints the text between the double quotes.

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:

- `mkdir hello` makes a directory named `hello` in the directory you are in;
- `cd hello` moves the terminal into `hello`, so that the next commands work there.

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.

```toml include="steps/01-hello/una.toml" title="una.toml"
[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:

- `[package]` names the package, gives its version, and names its **edition**: the version of the Una language its code is written in. This book uses edition `0.2`. A package keeps the rules of its edition even when `una` gets newer.
- `[run]` says how `una run` starts the program. `entry` names the module that holds `main`, and `grants` lists what the program may use outside itself when it runs: here, the console. [Section 1.5](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-5) explains grants.

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`:

```text include="steps/01-hello/expected/commands/explain-u7004.txt#L32-L37"
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](https://una-lang.org/en/learn/packages/the-manifest-and-the-lock/#s11-3) 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:

```text include="steps/01-hello/expected/output.txt"
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 include="steps/01-hello..steps/02-typo:src/hello.una"
--- 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:

```text include="steps/02-typo/expected/rendered.txt"
[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](https://una-lang.org/en/learn/tools/reading-a-diagnostic/#s18-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 directory holds `una.toml`, `verification.lock` and `src/`.
- Each file `src/<name>.una` holds the module `<name>`, and its first line says `module <name>`.
- `entry` in `una.toml` names one of those modules, and that module has `pub main() -> Unit`.
- `una check .` reads every file of the package; `una run .` checks, then runs `main`.

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:

```una include="steps/03-hello-una/src/hello.una#main" title="src/hello.una"
--- 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?

:::answer Show the answer
```text include="steps/03-hello-una/expected/output.txt"
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.
:::
