~bratishkaerik/zig-libgccjit

#zig-libgccjit — wrapper and bindings for libgccjit.h

#Description

This library contains wrapper (in src/wrapper.zig) and raw bindings (in src/bindings.zig) for "gccjit" library, specifically C API "libgccjit.h".

Raw bindings and wrapper covers ABI versions 0 to 28.

Currently tested with Zig 0.13.0 and 0.14.0-dev.2198+e5f5229fd.

#Adding to your project

#Dependency

First you need to add this project to your build.zig.zon:

zig fetch --save 'git+https://git.sr.ht/~bratishkaerik/zig-libgccjit#main'

Then import dependency in your build.zig:

const dep_zig_libgccjit = b.dependency("zig-libgccjit", .{
    .target = target,
    .optimize = optimize,
});

#Wrapper module

const mod_gccjit_wrapper = dep_zig_libgccjit.module("wrapper");

// ...
// You can replace "gccjit" here with any name that you want to
// use in your "@import" statement.
exe.root_module.addImport("gccjit", mod_gccjit_wrapper);

In your program:

const gccjit = @import("gccjit");
_ = try gccjit.Context.acquire();

#Raw bindings module

const mod_gccjit_raw_bindings = dep_zig_libgccjit.module("raw_bindings");

// ...
exe.root_module.addImport("gccjit_raw", mod_gccjit_raw_bindings);

In your program:

const c = @import("gccjit_raw");
_ = c.gcc_jit_context.acquire();

#Configuring dependency

To change ABI version (LIBGCCJIT_ABI_VERSION from official docs), you can pass abi_version parameter to b.dependency call: (by default it's equal to 0, for maximum compatibility):

const dep_zig_libgccjit = b.dependency("zig-libgccjit", .{
    .target = target,
    .optimize = optimize,
    // Might be a bug in Zig?
    .abi_version = @as(u32, 24),
});

#Examples

For example of usage see subfolders in examples/ folder.

#License

This project is licensed using REUSE standard. See LICENSES/ sub-directory and copyright notices in files.

IANAL. Following text is not a legal advice, it is only my thoughts and understanding of process after asking questions in #gnu channel and browsing links from GNU GPL FAQ links section:

#Commentary

As of 2023-04-15 "zig-libgccjit" is licensed under "GNU GPL version 3 or later", same as "libgccjit.h", because I thought that latter is considered to be derivative work from former.

#My understanding of licensing of programs that uses "libgccjit" library with or without this library

Suppose that you have some compiler that contains two backends: self-hosted and "libgccjit".

Suppose that you have some build option "use-backend" which has following options:

(1) Enable and compile only self-hosted backend (fully omit "libgccjit" backend from final binary).
(2) Enable and compile only "libgccjit" backend (fully omit self-hosted backend from final binary).
(3) Enable and compile both backends.

I think that all options requires your project to be licensed under GPL-compatible license, but see below:

Given the nature of Zig's compilation process (lazy compilation + comptime logic), I think that options (2) and (3) requires your final binary to be distributed not just under GPL-compatible license, but "GNU GPL version 3 or later", since binary will be considered "derivative work" of "libgccjit" (and this library, if you are using this).

BUT if you fully omit "libgccjit" library (and this library, if you are using this) from your program by using option (1), final binary can be distributed under your license, not neccessarily under "GNU GPL version 3 or later", because your binary in this scenario is not a derivative work.

#GNU GPL FAQ links

What does the GPL say about translating some code to a different programming language?

Under copyright law, translation of a work is considered a kind of modification. Therefore, what the GPL says about modified versions applies also to translated versions. The translation is covered by the copyright on the original program.

If the original program carries a free license, that license gives permission to translate it. How you can use and license the translated program is determined by that license. If the original program is licensed under certain versions of the GNU GPL, the translated program must be covered by the same versions of the GNU GPL.

If a library is released under the GPL (not the LGPL), does that mean that any software which uses it has to be under the GPL or a GPL-compatible license?

Yes, because the program actually links to the library. As such, the terms of the GPL apply to the entire combination. The software modules that link with the library may be under various GPL compatible licenses, but the work as a whole must be licensed under the GPL. See also: What does it mean to say a license is “compatible with the GPL”?

When is a program and its plug-ins considered a single combined program?

It depends on how the main program invokes its plug-ins. If the main program uses fork and exec to invoke plug-ins, and they establish intimate communication by sharing complex data structures, or shipping complex data structures back and forth, that can make them one single combined program. A main program that uses simple fork and exec to invoke plug-ins and does not establish intimate communication between them results in the plug-ins being a separate program.

If the main program dynamically links plug-ins, and they make function calls to each other and share data structures, we believe they form a single combined program, which must be treated as an extension of both the main program and the plug-ins. If the main program dynamically links plug-ins, but the communication between them is limited to invoking the ‘main’ function of the plug-in with some options and waiting for it to return, that is a borderline case.

Using shared memory to communicate with complex data structures is pretty much equivalent to dynamic linking.

If I write a plug-in to use with a GPL-covered program, what requirements does that impose on the licenses I can use for distributing my plug-in?

Please see this question for determining when plug-ins and a main program are considered a single combined program and when they are considered separate works.

If the main program and the plugins are a single combined program then this means you must license the plug-in under the GPL or a GPL-compatible free software license and distribute it with source code in a GPL-compliant way. A main program that is separate from its plug-ins makes no requirements for the plug-ins.

refs

clone