---
title: "11.1 Packages and modules"
url: https://una-lang.org/en/learn/packages/packages-and-modules/
release: v0.4.0
edition: "0.2"
---

# 11.1 Packages and modules

## 11.1.1 What a package and a module are

Think of a store's binder of procedures. The binder holds everything the staff need, and tabbed sections divide it: one for the till, one for deliveries, one for returns. A clerk looking for the refund rules opens one section, not the whole binder.

A **package** is the binder: one program, kept in one directory with everything `una` needs to check and run it. A **module** is one section: a single file of Una code under the package's `src/` directory. [Chapter 1](https://una-lang.org/en/learn/hello/modules/#s1-2) made packages of one module each. A program grows by adding modules, and each module holds the code about one subject.

A few words name the parts, and the rest of the chapter uses them:

- A **path** is where a file sits, written as the directories that lead to it: `src/store/money.una` is the file `money.una` in the directory `store`, inside `src`.
- A **module path** is a module's name, built from its file's path: drop `src/` and `.una`, and write `.` for each `/`. So `src/store/money.una` holds the module `store.money`. Each part between dots is a **segment**. In chapter 1, every module path had one segment, such as `morning`.
- A **declaration** is a top-level item of a module: a function, a kind, a predicate and the like, each starting at the left edge of the file.
- The **entry** is the module that `una run` starts, the one with `pub main`.

Each example of this chapter is a package of its own, a step, made as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains; the chapter's download, `11-packages.tar.gz`, holds every one of them.

## 11.1.2 Why a program is split into modules

Every module has its own set of names, so one module cannot declare two things with the same name. Here is a store's program kept in one module. It formats an amount of money, and it also formats a tax rate, and both functions are called `format`:

```una include="steps/01-one-file/src/store.una" title="steps/01-one-file/src/store.una"
module store

--- An amount in cents as a person reads it: 1990 is "19.90".
format(cents: Int) -> Text
=
  let rest = cents mod 100
  if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"

--- A tax rate as a person reads it: 8 is "8%".
format(percent: Int) -> Text = "{percent}%"

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("a lamp costs {format(1990)}, with tax at {format(8)}")
```

`una check .` reports:

```text include="steps/01-one-file/expected/rendered.txt"
[U1002] Error: `format` is defined twice in this module, both times as a function
    ╭─[ src/store.una:10:1 ]
    │
  4 │ format(cents: Int) -> Text
    │ ───┬──
    │    ╰──── first defined here
    │
 10 │ format(percent: Int) -> Text = "{percent}%"
    │ ───┬──
    │    ╰──── `format` is defined twice in this module, both times as a function
    │
    │ Note: run `una explain U1002` for an explanation
────╯
```

The first line names the problem: `format` is defined twice. The two marks point at both declarations, so you see which one came first. Inside one module, a name means one thing, and the checker refuses to guess which `format` a call means.

In one file, every new function has to find a name that no other function of the whole program uses, and every function can call every other. As the file grows, so do both problems: names get longer to stay apart, and a change to any helper can affect any line of the program. Modules solve both. Each module has its own names, so the money module and the tax module can each have a `format` of their own. And each module decides which of its declarations other modules may use, which [section 11.2](https://una-lang.org/en/learn/packages/pub-and-import/#s11-2) covers.

## 11.1.3 How to write a module

The next step splits a store's program into two modules. `store.money` formats an amount, and `store.app` prints with it:

```una include="steps/02-modules/src/store/money.una" title="steps/02-modules/src/store/money.una" verified="check"
module store.money

--- An amount in cents as a person reads it: 1990 is "19.90".
pub format(cents: Int) -> Text
=
  let rest = cents mod 100
  if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"
```

```una include="steps/02-modules/src/store/app.una" title="steps/02-modules/src/store/app.una" verified="check, run"
module store.app

import store.money (format)

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("a lamp costs {format(1990)}, a desk {format(24905)}")
```

`una run .` prints:

```text include="steps/02-modules/expected/output.txt"
a lamp costs 19.90, a desk 249.05
```

A module file has three parts, always in this order:

:::steps
1. **The `module` line.** The first line of the file names the module: `module store.money`. It must be the module path of the file's own path.
2. **The imports.** Zero or more `import` lines, each naming a module of the package and the declarations it takes: `import store.money (format)`. [Section 11.2](https://una-lang.org/en/learn/packages/pub-and-import/#s11-2) covers imports.
3. **The declarations.** The functions, kinds and other declarations of the module, in any order, separated by blank lines. All of them see each other: a function can call one declared further down.
:::

Two smaller things in this step. `pub` before `format`, the word [section 6.3](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-3) introduced, is what lets the module `store.app` call it; [section 11.2](https://una-lang.org/en/learn/packages/pub-and-import/#s11-2) shows how one module takes a function from another. `cents mod 100` is the remainder of dividing `cents` by 100, as `/` is the quotient: 1990 divided by 100 is 19, remainder 90 ([section 2.2](https://una-lang.org/en/learn/numbers/whole-numbers-int/#s2-2) covers both).

### 11.1.3.1 The entry module in `una.toml`

`una check .` checks every module, but `una run .` must know where to start. The manifest, `una.toml`, says so: `[run] entry` is a module path, here `store.app`, and that module has the `pub main`.

```toml include="steps/02-modules/una.toml" title="steps/02-modules/una.toml"
[package]
name = "store"
version = "0.1.0"
edition = "0.2"

[run]
entry = "store.app"
grants = ["console"]
```

[Section 11.3](https://una-lang.org/en/learn/packages/the-manifest-and-the-lock/#s11-3) explains every line of this file.

## 11.1.4 Modules at every depth

A module path has as many segments as its file has directories under `src/`, plus one for the file. This step has three modules at three depths:

| File | Module |
| --- | --- |
| `src/app.una` | `app` |
| `src/store/money.una` | `store.money` |
| `src/store/tax/rates.una` | `store.tax.rates` |

The tax module knows the store's sales tax, and has a `format` of its own, for percentages:

```una include="steps/03-paths/src/store/tax/rates.una" title="steps/03-paths/src/store/tax/rates.una" verified="check"
module store.tax.rates

--- The store's sales tax, in percent.
pub rate() -> Int = 8

--- The tax on an amount, in cents, rounded down.
pub tax_cents(cents: Int) -> Int = cents * rate() / 100

--- The rate as a person reads it: 8 is "8%".
pub rate_text() -> Text = format(rate())

--- A percentage as a person reads it.
format(percent: Int) -> Text = "{percent}%"
```

The entry is `app`, a module of one segment, directly under `src/`:

```una include="steps/03-paths/src/app.una" title="steps/03-paths/src/app.una" verified="check, run"
module app

import store.money (format)
import store.tax.rates (rate_text, tax_cents)

pub main() -> Unit
  uses @console: Console[print]
=
  let cents = 1990
  @console.print("a lamp costs {format(cents)}, and tax at {rate_text()} adds {format(tax_cents(cents))}")
```

```toml include="steps/03-paths/una.toml" title="steps/03-paths/una.toml"
[package]
name = "store"
version = "0.1.0"
edition = "0.2"

[run]
entry = "app"
grants = ["console"]
```

`una run .` prints:

```text include="steps/03-paths/expected/output.txt"
a lamp costs 19.90, and tax at 8% adds 1.59
```

Two functions called `format` now live in one package without a clash: `store.money` has one, and `store.tax.rates` has another. `app` imports only the money one, and calls the tax module's `rate_text`, which uses its own `format` inside.

## 11.1.5 How una finds and checks the modules

### 11.1.5.1 Every file under `src/` is a module

There is no list of modules to keep up to date. `una check .` reads every `.una` file under `src/`, checks all of them together, and reports each diagnostic with its file. A new file is part of the package as soon as it exists, and a deleted file is gone from it. Hidden entries, whose names start with a dot, are skipped.

A directory under `src/` only groups modules: it is not a module itself, and it needs no file of its own. `src/store/` holds `store.money`, but there is no module `store`.

### 11.1.5.2 The `module` line must match the path

A file whose `module` line does not match its path is U1008, at that line, with a repair that writes the right path. [A module header that does not match its path](https://una-lang.org/en/learn/packages/common-mistakes/#a-module-header-that-does-not-match-its-path-u1008) shows one.

### 11.1.5.3 The rules for a module path

Each segment is a lower-case name, as a function's name is: a lower-case letter, then lower-case letters, digits and underscores, such as `store`, `tax_rates` or `v2`. It may not contain `__` or end with `_` (U1005), and it may not be a keyword.

Paths that start with `std` or `prelude` belong to the standard library. Add a file `src/std/money.una` to the package of the last step, and `una check .` reports:

```text include="steps/04-reserved/expected/rendered.txt"
[U1009] Error: module `std.money` starts with `std`, a segment that only the standard library may use
   ╭─[ src/std/money.una:1:1 ]
   │
 1 │ module std.money
   │ ────────┬───────
   │         ╰───────── module `std.money` starts with `std`, a segment that only the standard library may use
   │
   │ Note: run `una explain U1009` for an explanation
───╯
```

The standard library has its own modules there, such as `std.host`, so a package may not add any. Choose another first segment, such as `store`.

### 11.1.5.4 Where checking and running start

`una check .` and `una test .` take every module. `una run .` starts at `main` in the entry module, and runs only what `main` calls. A module that nothing calls is still checked, and its examples still run under `una test .`.

## 11.1.6 Grouping and moving modules

Group modules by what they are about, not by what kind of declaration they hold: `store.money` keeps the type of an amount, its formatting and its tests together. A reader who wants to know how amounts are printed then opens one file.

A module path follows the file system, so moving a file renames its module. The checker then reports the header that no longer matches, and every import of the old name, so nothing is left pointing at a module that is gone.

:::decide
**Which to use:**

| You have… | Use |
| --- | --- |
| A small program, a few functions about one subject | One module, such as `src/app.una` |
| Code about two subjects, such as money and the catalog | One module per subject |
| Several modules about one area | A directory for the area: `src/store/money.una`, `src/store/catalog.una` |
| A helper that two modules need | Its own module, or the module that owns its subject, imported by both |
:::

## 11.1.7 Check yourself: module paths

The file `src/store/tax/rates.una` of [Modules at every depth](#modules-at-every-depth) now starts with a shorter line:

```diff include="steps/03-paths..steps/05-tax-header:src/store/tax/rates.una" context="0" title="src/store/tax/rates.una"
--- a/src/store/tax/rates.una
+++ b/src/store/tax/rates.una
@@ -1 +1 @@
-module store.tax.rates
+module tax.rates
```

The rest of the package is unchanged, and `app` still imports `store.tax.rates`. What does `una check .` report? Count the diagnostics before you open the answer.

:::answer Show the answer
Four diagnostics, three of them in `app`:

```text include="steps/05-tax-header/expected/diagnostics.txt"
error U1001 at src/app.una:4:8: module `store.tax.rates` is not a module of this package; the standard modules that can be imported are `std.host` and `std.testing`
error U1001 at src/app.una:10:61: cannot find name `rate_text` in this module, its imports or the prelude
error U1001 at src/app.una:10:87: cannot find name `tax_cents` in this module, its imports or the prelude
error U1008 at src/store/tax/rates.una:1:8: module `tax.rates` is in `src/store/tax/rates.una`, which must hold module `store.tax.rates`
```

The file still sits at `src/store/tax/rates.una`, so its module must be `store.tax.rates` (U1008, with a repair that writes it). And since no file now holds `store.tax.rates`, the import in `app` names a module that does not exist (U1001), and the two names it imported cannot be found. Fix the `module` line, and all four go away: when several diagnostics appear at once, look first for the one the others follow from.
:::
