The Zeno Book Zeno 0.1 zeno-lang.org

22 Packages

Modules put one program into several files. A package lets a program use files that are not its own: a folder of modules that lives somewhere else, beside the program or in somebody else’s git repository.

22.1 Starting a program with zeno new

zeno new makes a folder with a small program in it, laid out the way a program that grows will want:

$ zeno new weather
Made the program `weather` in weather/
  zeno.package   the name of the program, and the packages it needs
  main.zeno      the program
  greeting.zeno  a module, with a test
Run it with `zeno run weather/main.zeno`, and its tests with `zeno test weather`.
$ zeno run weather/main.zeno
Hello, world, from weather.
$ zeno test weather
weather/greeting.zeno
  ok      hello says who it greets

1 test: 1 passed, 0 failed.

zeno new --package name makes a package instead: a folder of modules for other programs to use, with no main.zeno.

22.2 The project file

A folder is a package when it holds a file called zeno.package. The one zeno new made is comments, which say what can be written, and then one line:

weather/zeno.package

package weather

There are two kinds of line, and that is all the file can say:

Line Means
package weather the name of this package
needs filters in "../filters" it needs the package in that folder, counted from this file’s folder. Nothing is copied
needs units from "address" at "v1.2.0" it needs the package in that git repository, at that tag, branch or commit

A comment starts with #, as in a program. A program with no zeno.package is still a program; the file is needed from the day the program needs a package.

22.3 A package beside the program

Here is a package of filters for noisy readings, in a folder of its own:

filters/zeno.package

package filters

filters/filters.zeno

function mean(values: list[float]) -> float {
    return sum(values) / float(len(values))
}

function clamp(x: float, low: float, high: float) -> float {
    if x < low {
        return low
    }
    if x > high {
        return high
    }
    return x
}

filters/lowpass.zeno

from filters import clamp

class Lowpass {
    weight: float
    value: float

    function add(self, reading: float) -> float {
        self.value += self.weight * (reading - self.value)
        return self.value
    }
}

function start(weight: float, first: float) -> Lowpass {
    return Lowpass(clamp(weight, 0.0, 1.0), first)
}

And a program, in the folder beside it, that needs the package:

thermostat/zeno.package

package thermostat

needs filters in "../filters"

thermostat/main.zeno

import filters
import filters.lowpass

let readings = [18.2, 18.9, 19.6, 21.0, 22.4, 23.1]
let smooth = filters.lowpass.start(0.5, readings[0])
for r in readings {
    print(f"read {r:5.1f}  smoothed {smooth.add(r):5.1f}")
}
print(f"mean {filters.mean(readings):.2f}")
$ zeno run thermostat/main.zeno
read  18.2  smoothed  18.2
read  18.9  smoothed  18.5
read  19.6  smoothed  19.1
read  21.0  smoothed  20.0
read  22.4  smoothed  21.2
read  23.1  smoothed  22.2
mean 20.53

Which file an import names

The rule for imports has one step more than in the last chapter:

  1. If the first word of the import is a package that this file’s zeno.package needs, the rest is a file in that package’s folder. import filters.lowpass is lowpass.zeno there, and import filters alone is the file with the package’s own name, filters.zeno.

  2. Otherwise it is a file of the package the importing file is in.

Inside the package the same rule holds from the package’s own side: lowpass.zeno writes from filters import clamp to get its neighbour. A package sees its own files and the packages its own zeno.package needs, and nothing of the program that uses it, so the same package works in every program, and can be run and tested on its own.

22.4 Other people’s packages: zeno fetch

A package that somebody else keeps is named by its git repository and by one exact version of it:

package logger

needs units from "https://github.com/someone/zeno-units" at "v1.2.0"

at is a tag, a branch or a commit. There are no ranges such as ^1.2: the version written is the version used. Then, in the program’s folder:

$ zeno run main.zeno
error: the package `units` has not been fetched: there is no file
`packages/units/zeno.package`. Run `zeno fetch` in the folder of the program

$ zeno fetch
Fetched units v1.2.0 (1c4e326) into packages/units
Fetched prefix main (d4461d9) into packages/prefix
Wrote zeno.lock

$ zeno run main.zeno
42.0

Three things happened.

  • Running never fetches. zeno run, check and build read files and nothing else. Only zeno fetch uses the network, with the git that is on the machine.

  • What a package needs comes too. units needs prefix, so that was fetched as well. All of them go into one folder, packages/, beside the program’s zeno.package, and a program has one package of each name.

  • zeno.lock was written. It holds the exact commit each package was at. A branch moves, but the next zeno fetch, here or on another machine, gets the commit in the lock. zeno fetch --update looks every version up again and writes the lock afresh.

Keep zeno.package and zeno.lock with the program. The folder packages/ can be made again from them at any time.

A range such as ^1.2 means the program built today and the program built next month may hold different code, chosen by somebody else’s release. Firmware that passed its tests on the bench must build the same a year later. One exact version and a lock file give that, and there is no solver to understand. Fetching only when asked means a build never depends on the network, which a factory build machine may not have. (Decisions 8.4, 8.9 and 8.10.)

22.5 What can go wrong

Each mistake in a zeno.package is shown with its file and line, as a mistake in a program is. A few of the messages:

error: this does not say which version of `units` is needed. Add `at` and a tag,
a branch or a commit of that repository, as in `needs units from "..." at "v1.0.0"`

error: the package in `lib` is called `filters`, not `filter`. Write `needs filters ...`

error: two packages called `b` are needed: the one in `a/b` and the one in `b`.
A program has one package of each name. Make the `needs` lines agree

zeno new starts a program, zeno new --package a package. zeno.package names a package and lists what it needs: a folder with in, or a git repository and one exact version with from and at. An import whose first word is a needed package reads that package’s folder. zeno fetch gets git packages into packages/ and pins them in zeno.lock; nothing else touches the network.

  1. Make a package units_extra with a function that turns a temperature in degC into Fahrenheit as a float, and use it from a program beside it.

  2. Misspell the package’s name in the program’s needs line, and read the message.

  3. Add a test to filters.zeno and run zeno test in the package’s folder (Testing).

  4. Put a package of yours in a git repository, tag it, and need it from a program with from and at.