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 weatherThere 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 filtersfilters/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:
If the first word of the import is a package that this file’s
zeno.packageneeds, the rest is a file in that package’s folder.import filters.lowpassislowpass.zenothere, andimport filtersalone is the file with the package’s own name,filters.zeno.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,checkandbuildread files and nothing else. Onlyzeno fetchuses the network, with thegitthat is on the machine.What a package needs comes too.
unitsneedsprefix, so that was fetched as well. All of them go into one folder,packages/, beside the program’szeno.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 --updatelooks 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.
Make a package
units_extrawith a function that turns a temperature indegCinto Fahrenheit as a float, and use it from a program beside it.Misspell the package’s name in the program’s
needsline, and read the message.Add a test to
filters.zenoand runzeno testin the package’s folder (Testing).Put a package of yours in a git repository, tag it, and need it from a program with
fromandat.