puregotk

Puregotk

NOTE: This library is still experimental and should be validated against real applications, but the generated APIs and bundled examples are tested in this repository.

Autogenerated GTK4, Libadwaita, WebKitGTK, Layer Shell, and Session Lock bindings for Go leveraging github.com/bnema/purego.

This branch and release line are based on the upstream puregotk project on Codeberg, with additional compatibility, generator, and downstream integration work layered on top.

Motivation

I created this library because I found that alternative libraries using Cgo had much too slow compilation speed. For my laptop around 15 minutes to build a simple example (without build cache) for gotk3 and also gotk4. Whilst this is maybe not a big problem for development, I found it annoying for CI and package building where you would not want to rely on a cache. Additionally, having Cgo involved means harder cross compilation.

This is not a fault of those libraries; cgo compilation is just inherently slow in Go. In this project I wanted to explore a different approach by leveraging purego to load shared libraries with dlopen without needing cgo.

Compilation speed currently is around 40 seconds for me on basic examples.

Available libraries

Bindings for the following GObject-introspectable libraries are currently generated from the GNOME Flatpak SDK:

• Adw-1
• cairo-1.0
• Gdk-4.0
• GdkPixbuf-2.0
• Gio-2.0
• GLib-2.0
• GModule-2.0
• GObject-2.0
• Graphene-1.0
• Gsk-4.0
• Gtk-4.0
• JavaScriptCore-6.0
• Pango-1.0
• PangoCairo-1.0
• Soup-3.0
• WebKit-6.0
• Gtk4LayerShell-1.0
• Gtk4SessionLock-1.0

If you want to add bindings for another GObject-introspectable library to puregotk, you can either add the GIR file to internal/gir/spec in this repository or generate the bindings in your own external repository (see examples/mylib-gtk-meson-go).

Advantages

No Cgo needed, thus:

• Easy cross compilation
• No C toolchain needed
• Much faster compile times than alternatives like gotk3 & gotk4

Disadvantages

Limitations of this library as compared to the alternatives using cgo:

• Some APIs involving complex by-value structs, unions, or other hard-to-map ABI cases may still be exposed conservatively. Common by-value struct arguments are supported by the bundled purego fork on Linux/macOS amd64/arm64, but exact C layout compatibility is still required.

Planned features

In order of priority:

• General code cleanup
• Support for OS other than Linux (I only test on Linux currently)
• GTK 3 support
• Architectures other than AMD64/ARM64

Basic example

You can find more examples for advanced features, such as GObject subclassing for custom widgets, writing GObject GTK libraries in Go, generating bindings from external GIR files, using Meson and Flatpak, Blueprint files and more in examples

package main

import (
	"os"

	"github.com/bnema/puregotk/v4/gio"
	"github.com/bnema/puregotk/v4/gtk"
)

func main() {
	appID := "page.codeberg.puregotk.Gtk4Hello"
	app := gtk.NewApplication(&appID, gio.GApplicationDefaultFlagsValue)
	defer app.Unref()

	actcb := func(_ gio.Application) {
		activate(app)
	}
	app.ConnectActivate(&actcb)

	if code := app.Run(len(os.Args), os.Args); code > 0 {
		os.Exit(code)
	}
}

func activate(app *gtk.Application) {
	window := gtk.NewApplicationWindow(app)
	defer window.Unref()

	title := "puregotk"
	window.SetTitle(&title)

	labelText := "Hello, World!"
	label := gtk.NewLabel(&labelText)
	defer label.Unref()

	window.SetChild(&label.Widget)
	window.SetDefaultSize(500, 500)
	window.Present()
}

Save this to a main.go and then build & run with

go run main.go

NOTE: You can also use CGO_ENABLED=0 to build without cgo!

Library loading

Because the GTK libs are loading at runtime (in init), we have to know where your libs are located. The default configuration is a "just works" configuration, we hardcode some paths that are common.

However, for systems such as NixOS or distros that use other paths the following environment variables might help:

• PUREGOTK_LIB_FOLDER, set this to the root folder where all libs are stored e.g. /some/path/
• PUREGOTK_LIBNAME_PATH where LIBNAME is the name of the library, e.g. PUREGOTK_GTK_PATH for the file path to GTK e.g. /some/path/libgtk-4.so. You have to do this for all deps, e.g. cairo, pango, etc

See https://github.com/bnema/puregotk/blob/main/internal/core/core.go for exact implementation details.

Additionally we also have a fallback to pkg-config, but I would say only rely on this as a last effort due to the increased startup time. When packaging code, always make sure that correct paths are used by e.g. using the aforementioned environment variables.

Generating the library

This library is automatically generated by reading GIR files.

To generate the library, run:

./gen.sh

In the root of the project. This needs:

• Go >= 1.24

License

MIT

Acknowledgements

• puregotk on Codeberg for the upstream project structure, GNOME 50 direction, and binding base this branch builds on
• purego and the upstream ebitengine project for the runtime foundation that makes this possible
• gotk4 for some GIR type definitions
• gtk of course