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, astruct, aunionor anenumis given to C as it is too.int8_ttouint64_t,size_tandboolcan be used with no#include.A declaration with no
(is a value: a constant or a macro of a header, a constant of anenum, 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 underzeno 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.cforread.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 asprintf.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.hypotruns underzeno runonly.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
Run the first program of this chapter. Then give
hypota str and runzeno check. Who found the mistake, Zeno or the C compiler?Declare
"double cbrt(double x);"and printm.cbrt(27.0)underzeno 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?Add
uint16_t sensor_peek(const sensor *s);to the driver of this chapter, and call it from Zeno.Give
sensor_reada list of three floats. What does the checker say?Build
read.zenowith--minimaland find the call ofsensor_crcinread.c. Where is the list’s copy?Call
crc32of zlib on a file read withfiles.read_bytes.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?