Using static libraries

Explain
,
1

Hi, i tried to learn how static libraries work.

First, i am using zig version 0.13.0.

Now after running zig init i get 2 files main.zig and root.zig.
I understand that the way it is setup is that the main.zig will become a executable and the root.zig will become a library (static by default) and that is just a convenience and they have nothing to do with each other except for the fact they are in the same project.

Now if i want to write my library in the root.zig file and use it in main.zig i can link it

exe.linkLibrary(lib);

and i then need to:

extern fn add(a: i32, b: i32) i32;

in the main.zig to use it.

Now my questions are:

  • if i build raylib for example as a static library, do i have to manually add those extern definitions into my main.zig file and do i have to do this with any library i might use? (seen this in Not-Nik/raylib-zig).
  • do i only need to add those functions that i want to call or also helper functions that are only use within those functions i need?
  • what if i create a library some c dev would like to use do they have to do that them self.

I know i can just put all of raylib into my program exe.addCSourceFiles() and co. i just want to know how in general these kinds of stuff works.

2

Zig can produce and consume C ABI libraries (static or dynamic).
C ABI functions for libraries are commonly declared in a header file (with .h extension).

You can add the extern definitions manually, but you don’t have to do it.
A header file can be generated by zig with the static library. The header file can be used to generate automatically the zig extern definitions.

You only need to add those functions that you want to call.
You might also need to add enum, struct and union declarations if these are used as parameters or return values.

They can include the produced header file, using #include "library.h" and get all the C functions, struct, enum and union declarations needed to call the zig exported functions.

To generate a C header file use the -femit-h flag in your build command.
e.g. zig build-lib -femit-h ...

To generate a .zig file with extern from C header files, there are two methods.

  • Using the zig translate-c command. See: C Translation CLI

  • Include the C header in your zig file using @cImport and @cInclude:

const c = @cImport(
    @cInclude("stdio.h");
);

pub fn main() void {
    c.puts("Hello World");
}

see: Import from C Header File

1 Like
3

Hi @dimdin thank you for the quick reply.

According to some threads i found on discord and github issues, it seems that emitting header files is currently broken.
I tried:

zig build-lib ./src/root.zig -femit-h="./root.h"

but there is no output.

But good to know that there was/will be a way to do emit those things.

So just to clarify:

I always need to give the compiled lib plus the function definitions to my “customers/users” otherwise they have a bad time using my library.
So i either create a *.h file or a *.zig file with the function definitions?

1 Like
4

It is true (How to enable build.zig also emit header file? - #6 by castholm)
But I successfully generate headers (use -femit-h without path)

Yes, having a .h file makes it easy to use the library from almost any language (directly from C,C++, using bindgen from Rust, using cgo from Go,…)

Having a zig file helps zig users, but it is better to export the library also as a zig module by adding it as a module in build.zig and build.zig.zon (How to package a zig source module and how to use it).

2 Likes