The Zeno Book Zeno 0.8 zeno-lang.org

24 Libraries of C

Most of the code a computer runs is C, or is reached through C: the library of the system, zlib, SQLite, a vendor’s driver, and the code a board’s firmware already has. Go and Rust can both make a library that C can call. Since 0.6 a Zeno program can call any of them, as they are:

maths.zeno

import c

let m = c.library("m", ["double hypot(double x, double y);", "double frexp(double x, int *exponent);"])
let exponent = [0]
print(m.hypot(3.0, 4.0), m.frexp(8.0, exponent), exponent)
5.0 0.5 [4]

c.library takes two things: the library, and the functions of it that the program uses, declared as C declares them. The declarations are the lines a header has, copied as they are. From there, each function is called as a function of Zeno is.

This is not the bridge of the last chapter. A value of Python stays in Python, and Zeno asks for each field of it. C has no such values: a function of C takes numbers, text and pointers, and gives one back. So the checker reads the declarations and checks every call before the program runs, and zeno build calls the function directly, with nothing in between. That is what firmware needs.

Nothing changes for a program that does not say import c. What C needs is started by the first c.library that runs, and a program that imports c and never calls it starts nothing.

24.1 What it needs

A C compiler: cc, gcc or clang, the first that is installed, or the one CC names, as for zeno build. Under zeno run, the first time a program reaches a c.library Zeno writes a small file of C for the functions it declares and builds it with the library. That takes about half a second, and is kept: the next run starts at once. It is built again when the declarations change, or a file of the library does.

The library itself has to be there with what building with it needs. On Debian and Ubuntu that is the package whose name ends in -dev: zlib1g-dev for zlib, libsqlite3-dev for SQLite.

24.2 Naming the library

The first thing given is one text, or a list of them:

Given What it is
"z" a library of the system, by its name: -lz, as C is built with it
"crc.c" a file of C, built with the rest
"libtemp.so" a library that was built already: .so, .a, .o, .dylib, .dll
"-DSTEP=3" anything that starts with - goes to the compiler as it is
none nothing more: for the C library every program has (strlen, abs)

A file is found from the folder of the program, wherever the program is started from, and so is a header it includes.

libc.zeno

import c

let libc = c.library(none, [
    "size_t strlen(const char *text);",
    "int abs(int n);",
    "char *getenv(const char *name);",
])
print(libc.strlen("zeno"), libc.abs(-7), libc.getenv("NO_SUCH_NAME"))
4 7 none

A library that is not there is a FileError, which a program can catch. The message asks if it is installed, with what building with it needs.

24.3 Declaring the functions

The second thing given is the declarations: one text, or a list of texts, each declaration ending with ;. They are C, and only the functions the program uses are needed.

  • A line that starts with #, such as #include <zlib.h>, is given to C as it is. With the header included, the compiler checks each declaration against it, and a type the header names (uLong, Bytef) is known.

  • A typedef, a struct, a union or an enum is given to C as it is too.

  • int8_t to uint64_t, size_t and bool can be used with no #include.

  • A declaration with no ( is a value: a constant or a macro of a header, a constant of an enum, or a variable. It has a section below.

When the library and its declarations are written out in the program as texts, which is nearly always, Zeno knows every function before the program runs, and checks each call as it checks a call of a function of Zeno:

wrong.zeno

import c

let m = c.library("m", ["double hypot(double x, double y);"])
print(m.hypot("3", 4.0))
print(m.cube(3.0))
$ zeno check wrong.zeno
error: the 1st parameter of `hypot` (`double`) should be float, but this is str
 --> wrong.zeno:4:15
  |
4 | print(m.hypot("3", 4.0))
  |               ^

error: the library `m` has no `cube` among what is declared for it. Declared: hypot
 --> wrong.zeno:5:7
  |
5 | print(m.cube(3.0))
  |       ^

2 errors found. Nothing was run.

A type that only a header names (uLong, HAL_StatusTypeDef) is taken to be a whole number, as nearly all such names are, unless it is one of the names headers give floats (float32_t). The C compiler sees the real type, and says so if the two disagree. A declaration that names a function the library does not have is an error when c.library is called, and not at the first call.

C has no way to ask a library what its functions take: a library knows the names of its functions and nothing of their types. That is why the program declares them. And Zeno does not read a header by itself, because a header is written for a C compiler: it is full of macros, and means something different on each machine. So the declarations are handed to the C compiler, which is there already wherever zeno build is used, and it works out what uLong or size_t is on this machine. (Decisions 44.1 and 44.3.)

24.4 Values go across

C Zeno
int, uint8_t, long, size_t and their like int, checked to fit: an OverflowError if it does not
uint64_t above the top of int u64
float, double float
bool, _Bool bool
const char * given a str, lent for the call, with the \0 C expects
char * given back a str or none, copied
a pointer to numbers, given a list, lent for the call: copied in, and back after
any other pointer given back a C pointer or none: given back to C, never looked inside
NULL none
void none

A list for a pointer is lent. Its items are copied into memory of the type the pointer is to, the function is called, and the items are copied back into the list afterwards, so a function that fills a buffer fills the list. That is how frexp gave its exponent in the first program. A pointer to const is not copied back: the function promised not to change it.

A pointer that C gives back is kept as it is. It can be given back to C, compared with ==, tested for none and printed, and that is all. This is how a library that hands out a handle (FILE *, sqlite3 *, a driver’s context) is used. A function that gives a handle back through a pointer to a pointer (sqlite3 **db) is given a list of one none, and finds the handle in it afterwards.

Zeno never frees memory that C gave it. A library that says the caller frees what it returns has a function to do it, and the program calls that, as it would in C.

24.5 A library of your own

Here is a small driver as a board’s firmware might have it: a header and a file of C. Both lie beside the program.

sensor.h

#include <stddef.h>
#include <stdint.h>

#define SENSOR_CHANNELS 4

typedef enum { SENSOR_OK, SENSOR_BUSY } sensor_status;
typedef struct sensor sensor;

sensor *sensor_open(uint8_t channel);
sensor_status sensor_read(sensor *s, uint16_t *samples, size_t count);
uint16_t sensor_crc(const uint8_t *data, size_t length);
void sensor_close(sensor *s);

sensor.c

#include "sensor.h"
#include <stdlib.h>

struct sensor { uint8_t channel; uint16_t next; };

sensor *sensor_open(uint8_t channel) {
    if (channel >= SENSOR_CHANNELS) return NULL;
    sensor *s = malloc(sizeof *s);
    s->channel = channel;
    s->next = 0;
    return s;
}

sensor_status sensor_read(sensor *s, uint16_t *samples, size_t count) {
    for (size_t i = 0; i < count; i++) {
        samples[i] = (uint16_t)(s->channel * 100 + s->next++);
    }
    return SENSOR_OK;
}

uint16_t sensor_crc(const uint8_t *data, size_t length) {
    uint16_t crc = 0xFFFF;
    for (size_t i = 0; i < length; i++) {
        crc ^= data[i];
        for (int bit = 0; bit < 8; bit++) {
            crc = (crc & 1) ? (uint16_t)((crc >> 1) ^ 0xA001) : (uint16_t)(crc >> 1);
        }
    }
    return crc;
}

void sensor_close(sensor *s) { free(s); }

read.zeno

import c

let sensor = c.library("sensor.c", [
    "#include \"sensor.h\"",
    "sensor *sensor_open(uint8_t channel);",
    "sensor_status sensor_read(sensor *s, uint16_t *samples, size_t count);",
    "uint16_t sensor_crc(const uint8_t *data, size_t length);",
    "void sensor_close(sensor *s);",
    "int SENSOR_CHANNELS;",
    "sensor_status SENSOR_OK;",
])

print(sensor.SENSOR_CHANNELS, sensor.sensor_open(9))
let s = sensor.sensor_open(2)
let samples = [0] * 4
if sensor.sensor_read(s, samples, len(samples)) == sensor.SENSOR_OK {
    print(samples)
}
sensor.sensor_close(s)

let frame: list[u8] = [1, 3, 0, 107, 0, 3]
print(sensor.sensor_crc(frame, len(frame)))
4 none
[200, 201, 202, 203]
6004

sensor_open(9) gave NULL, which is none. s is the handle: Zeno never looks inside it, and hands it back. samples was lent and filled. frame is a list[u8] (Sized Numbers), which is what bytes are in Zeno.

24.6 Values a header names

The last two declarations of that program have no (, and each names a value. SENSOR_CHANNELS is a macro, and SENSOR_OK a constant of an enum. Each is read by its name, as C reads it, every time the program reads it. C cannot declare a macro, so the value is not declared again: the header has it, and the declaration only tells Zeno its type.

That is how the names of a vendor’s HAL are used:

let hal = c.library("hal.c", [
    "#include \"stm32f4xx_hal.h\"",
    "void HAL_GPIO_WritePin(GPIO_TypeDef *port, uint16_t pin, GPIO_PinState state);",
    "GPIO_TypeDef *GPIOA;",
    "uint16_t GPIO_PIN_5;",
    "GPIO_PinState GPIO_PIN_SET;",
])
hal.HAL_GPIO_WritePin(hal.GPIOA, hal.GPIO_PIN_5, hal.GPIO_PIN_SET)

A variable that only the library’s own file of C has, with no header, is declared with extern, as C would declare it: "extern uint32_t uptime_ms;".

24.7 zeno build: C calls C

zeno build writes C, so a function of a library is called there as C calls it, with no helper beside the program. The library is built in with the program: a file of C is compiled with it, and a library is linked.

$ zeno build read.zeno
Wrote read.c
Built read. Run it with ./read
$ ./read
4 none
[200, 201, 202, 203]
6004
$ zeno build --no-collector --minimal read.zeno
Wrote read.c
Built read. Run it with ./read
$ ./read
4 none
[200, 201, 202, 203]
6004
$ grep -c "" read.c
466
$ grep "sensor_close(" read.c
void sensor_close(sensor *s);
    sensor_close(((sensor *)(z_s)));

Every build does it: a plain one, --firmware, --no-collector, --owned and --minimal (Compiling). The last lines above are the whole of the minimal build’s C counted, and the two lines of it that have sensor_close: the declaration, as the program gave it, and the call.

A built program prints what zeno run prints, and a number that does not fit stops it with the same OverflowError:

channel.zeno

import c

let sensor = c.library("sensor.c", ["#include \"sensor.h\"", "sensor *sensor_open(uint8_t channel);"])
for channel in [2, 300] {
    print(sensor.sensor_open(channel) is none)
}
$ zeno run channel.zeno
false
error: uncaught OverflowError: the 1st parameter of `sensor_open` (`uint8_t`) holds 0 to 255, and this is 300
 --> channel.zeno:5:11
  |
5 |     print(sensor.sensor_open(channel) is none)
  |           ^
$ zeno build channel.zeno
Wrote channel.c
Built channel. Run it with ./channel
$ ./channel
false
error: uncaught OverflowError: the 1st parameter of `sensor_open` (`uint8_t`) holds 0 to 255, and this is 300
 --> channel.zeno:5:11

A --minimal build does not check this, as it checks nothing.

Three things to know about a build:

  • A list[u8] is handed over where it is, with no copy, to a function that takes bytes, and what C writes there is what the list holds afterwards. Any other list is copied in and back, as under zeno run.

  • The library and its declarations must be written out in the program as texts, so that they are known while it builds.

  • A file of C cannot have the name the build gives the program’s own C: read.c for read.zeno. The build says so, and writes nothing.

zeno build --llvm and --target do not take import c yet.

This was used on Linux x86-64: the system’s maths library, zlib, SQLite, a file of C beside the program, and libraries of Go and Rust. The tests also run it on Windows (MinGW gcc) and on macOS (Apple clang), with a file of C and the maths library. It has not been run with a cross-compiler or on a board.

24.8 Libraries of Go and Rust

Go and Rust each build a library that C can call, and c.library takes that library. The build is done by their own tools.

Rust: mark each function #[no_mangle] pub extern "C", and build it as a cdylib (a .so) or a staticlib (a .a). With Cargo, that is crate-type = ["cdylib"] under [lib] in Cargo.toml.

filter.rs

#[no_mangle]
pub extern "C" fn average(values: *const f64, count: usize) -> f64 {
    let values = unsafe { std::slice::from_raw_parts(values, count) };
    values.iter().sum::<f64>() / count as f64
}

average.zeno

import c

let filter = c.library("libfilter.so", "double average(const double *values, size_t count);")
let readings = [20.0, 22.0, 21.0, 25.0]
print(filter.average(readings, len(readings)))
$ rustc -O --crate-type cdylib filter.rs -o libfilter.so
$ zeno run average.zeno
22.0

Go: mark each function //export, and build with the mode c-shared (a .so) or c-archive (a .a). Go writes libtemp.h beside the library, with the declarations.

temp.go

package main

import "C"

//export Celsius
func Celsius(f float64) float64 { return (f - 32) * 5 / 9 }

func main() {}

temp.zeno

import c

let temp = c.library("libtemp.so", "double Celsius(double f);")
print(temp.Celsius(98.6))
$ go build -buildmode=c-shared -o libtemp.so temp.go
$ zeno run temp.zeno
37.0

There is no import cpp. A library of C++ is used through C, as Go and Rust are: one with extern "C" functions is a library of C (decision 44.12).

24.9 When C goes wrong

A mistake Zeno can see before the program runs is found then: a wrong argument, a function that is not declared, a declaration Zeno cannot take, such as a function with .... A number that does not fit is found as the program runs.

A mistake inside C, such as reading memory that is not there, is another matter. Under zeno run C runs beside Zeno, so the program stops with an error at the line that called it, and Zeno itself does not crash; try cannot catch it. In a built program C is the program, and it stops as a program of C does.

Text that C gives back is bytes. A byte there that is not part of a character of UTF-8 is shown as \u{fffd} by zeno run; a built program prints the bytes as they are.

24.10 What is not there yet

  • The address of a variable (&huart2, a handle of a HAL that the vendor’s code defines). Write a function of C that gives it:
    UART_HandleTypeDef *uart2(void) { return &huart2; }

  • A function of Zeno given to C, as a callback.

  • A struct given or given back whole, not through a pointer.

  • A function that takes ..., such as printf.

  • Reading the declarations from a header by itself. They are copied by hand for now, and only the ones used are needed.

  • A function of a library kept as a value is refused by a build: let f = m.hypot runs under zeno run only.

  • zeno build –llvm, and the other languages of --target.

24.11 How it is built

Under zeno run, Zeno reads the declarations and writes a small file of C with a function for each, which takes its arguments from a table of numbers and calls the real one. The C compiler builds that with the library. The result is loaded by a small helper written in C, which runs beside the program and is spoken to as the helpers of the other languages are (Libraries of Other Languages). A fault in C stops the helper and not Zeno.

Under zeno build there is no helper. The declarations go into the program’s C as they were written, each call is a call, and a number is checked to fit before it is given. The example examples/modbus.zeno makes a request of Modbus RTU with the checksum written in C (examples/crc.c), and it is built for both of the emulated boards with the rest of the examples (The Board). The reasons are chapter 44 of docs/decisions.md.

24.12 Things to try

  1. Run the first program of this chapter. Then give hypot a str and run zeno check. Who found the mistake, Zeno or the C compiler?

  2. Declare "double cbrt(double x);" and print m.cbrt(27.0) under zeno run, and then built. The two can differ in the last digit. Which one did the C compiler work out by itself, before the program ran?

  3. Add uint16_t sensor_peek(const sensor *s); to the driver of this chapter, and call it from Zeno.

  4. Give sensor_read a list of three floats. What does the checker say?

  5. Build read.zeno with --minimal and find the call of sensor_crc in read.c. Where is the list’s copy?

  6. Call crc32 of zlib on a file read with files.read_bytes.

  7. Write a function in Go that formats a number with strconv.FormatFloat, and call it from Zeno. What does Go give back, and who frees it?