Libraries of C, Go and Rust
Most of the code a computer runs is C, or is reached through C: the library of the system, zlib, SQLite, OpenSSL, 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. A Zeno program can call any of them, as they are.
import c
let m = c.library("m", ["double cbrt(double x);", "double hypot(double x, double y);"])
print(m.cbrt(27.0), m.hypot(3.0, 4.0))
3.0000000000000004 5.0
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 the third version of using other languages' libraries, after
Python, JavaScript and Java (python.md,
node.md, java.md) and Ruby, PHP, Lua and C#.
Nothing changes for a program that does not say import c. The
decisions behind it are chapter 44 of decisions.md.
What it needs
A C compiler: cc, gcc or clang, the first that is installed, or
the one CC names, as for zeno build. The first time a program runs
a c.library, Zeno writes a small file of C for the functions it
declares and builds it with the library. That takes a moment, 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.
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.
let crc = c.library(["crc.c", "-DCRC_TABLE"], "uint16_t crc16(const uint8_t *data, size_t length);")
let z = c.library("z", ["#include <zlib.h>", "uLong crc32(uLong crc, const Bytef *buf, uInt len);"])
A library that is not there is a FileError, which a program can
catch:
error: uncaught FileError: C has no library `sqlite`. Is it installed, with what
building with it needs (on Debian and Ubuntu, its package that ends in `-dev`)?
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:typedef struct counter counter;. int8_ttouint64_t,size_tandboolcan be used with no#include.- A declaration with no
(is a value: see Values a header names.
When the library and its declarations are written out in the program, as texts, Zeno knows every function before the program runs, and checks each call as it checks a call of a function of Zeno:
error: the 1st parameter of `cbrt` (`double`) should be float, but this is str
error: `abs` takes 1 argument, but 2 were given
error: the library `m` has no `cube` among what is declared for it. Declared: cbrt, abs
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, not at the first call:
error: uncaught Error: the library `m` has no `cube_root`, which was declared
print shows a library by its name, and a function by its
declaration:
print(m, m.cbrt)
<C library m> double cbrt(double x)
Values go across
| C | Zeno |
|---|---|
int, uint8_t, long, size_t... |
int, checked to fit: 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 |
T * 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. A pointer to const is not copied back: the
function promised not to change it.
let m = c.library("m", "double frexp(double x, int *exponent);")
let exponent = [0]
print(m.frexp(8.0, exponent), exponent)
0.5 [4]
A pointer C gives back is kept as it is. It can be given back to
C, compared with ==, and printed, and that is all. This is how a
library that hands out a handle (FILE *, sqlite3 *, a driver's
context) is used:
let counter = mine.counter_new()
mine.counter_add(counter, 5)
print(mine.counter_get(counter))
mine.counter_free(counter)
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:
let sqlite = c.library("sqlite3", [
"#include <sqlite3.h>",
"int sqlite3_open(const char *filename, sqlite3 **db);",
"int sqlite3_close(sqlite3 *db);",
])
let db = [none]
print(sqlite.sqlite3_open(":memory:", db))
sqlite.sqlite3_close(db[0])
0
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.
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 program
that zeno build made prints the bytes as they are.
Values a header names
A declaration with no ( names a value: a constant or a macro of a
header, a constant of an enum, or a variable. It is read by its name,
as C reads it, each time the program reads it:
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)
GPIOA and GPIO_PIN_5 are macros, and GPIO_PIN_SET a constant of an
enum. C cannot declare a macro, so a value is not declared again: the
header has it. 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;".
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 and nothing in between.
The library is built in with the program: a file of C is compiled with
it, a library is linked. That is what firmware needs: the vendor's HAL,
on the board.
zeno build blink.zeno
Every build does it: --firmware, --no-collector, --owned and
--minimal. With --minimal the C is about what a person would write:
#include "stm32f4xx_hal.h"
void HAL_GPIO_WritePin(GPIO_TypeDef *port, uint16_t pin, GPIO_PinState state);
...
HAL_GPIO_WritePin(((GPIO_TypeDef *)(((void *)(GPIOA)))), ((uint16_t)(((int64_t)(GPIO_PIN_5)))), ...);
A program built this way prints what zeno run prints, and a number
that does not fit stops it with the same OverflowError (a --minimal
build does not check, as it checks nothing). A list[u8] is handed to
a function that takes bytes where it is, with no copy, and what C
writes there is what the list holds afterwards. Any other list is
copied in and back, as in zeno run.
One thing can differ in the last digit. A call the C compiler can work
out by itself, such as m.cbrt(27.0) with the number written in the
program, is worked out by GCC or Clang while it builds, rounded
exactly (3.0), where zeno run asks the library as the program runs
(3.0000000000000004 with glibc). Given a number the compiler cannot
see, both ask the library.
For zeno build, 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
(blink.c for blink.zeno): the build says so, and writes nothing.
zeno build --llvm and --target do not take import c yet.
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.
Go: mark each function //export, and build with
-buildmode=c-shared (a .so) or -buildmode=c-archive (a .a):
package main
import "C"
//export Celsius
func Celsius(f float64) float64 { return (f - 32) * 5 / 9 }
func main() {}
go build -buildmode=c-shared -o libtemp.so temp.go
import c
let temp = c.library("libtemp.so", "double Celsius(double f);")
print(temp.Celsius(98.6))
37.0
Go writes libtemp.h beside the library, with the declarations.
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, and
cargo build --release.
#[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
}
rustc -O --crate-type cdylib filter.rs -o libfilter.so
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)))
22.0
Errors
A mistake Zeno can see before the program runs is found then, as above: a wrong argument, a function that is not declared, a declaration Zeno cannot take:
error: `printf` takes any number of arguments (`...`), and Zeno cannot know their types.
Declare it with the ones the program gives, under another name of C, or write a function
of C that calls it
A number that does not fit is found as the program runs, as for
u8(300):
error: uncaught OverflowError: the 1st parameter of `same8` (`int8_t`) holds -128 to 127, and this is 300
A mistake inside C, such as reading memory that is not there, stops C. It runs beside Zeno, so the program stops with an error at the line that called it, and Zeno itself does not crash:
error: C stopped while Zeno was waiting for its answer
A declaration that does not agree with the header is the compiler's error, with its first lines shown.
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; }. zeno build --llvm, and the other languages of--target.- 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. - C++. 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). - Reading the declarations from a header by itself. They are copied by hand for now, and only the ones used are needed.
The example
examples/modbus.zeno makes a request of
Modbus RTU and checks the frames that come back, with the checksum
written in C as a board's firmware already has it
(examples/crc.c):
zeno run examples/modbus.zeno
request: 01 03 00 6B 00 03 74 17
good: true
reply: 01 03 06 02 2B 00 00 00 64 05 7A true
damaged: 01 03 06 02 3B 00 00 00 64 05 7A false
How it is built
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. 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, so it is the compiler that
works out what uLong or size_t is on this machine, and checks the
declarations against the header.
That library is loaded by a small helper written in C
(src/bridge.c), which runs beside the program and
is spoken to as the helpers of the other languages are. A fault in C
stops the helper and not Zeno, and a program that never says
import c never starts it.
Things to try
- Call
crc32of zlib on a file read withfiles.read_bytes. - Open a database with SQLite's
sqlite3_open, keeping thesqlite3 *it gives back. - Write a function in Go that formats a number with
strconv.FormatFloat, and call it from Zeno.
This page is docs/c.md in the language repository.