go-freedesktop

The freedesktop.org desktop-integration layer, in pure Go. No cgo, no D-Bus C library, no external tools.

CGO_ENABLED=0 6 specs XDG-native 100% coverage BSD-3-Clause

go-freedesktop is a family of small, independent Go modules that implement the freedesktop.org specifications a launcher, file manager or desktop shell relies on — enumerating installed applications, resolving icons, classifying files by MIME type, choosing which application opens a type, building the category menu, and serving desktop notifications.

Every module is pure Go, CGO_ENABLED=0, reuses standard XDG base-directory resolution instead of reinventing it, and cross-compiles to a static binary. Each spec is one small module, so a caller pulls in only what it needs. They are the desktop-integration layer beneath go-widgets launchers and shells.

Why go-freedesktop

Talking to a Linux desktop from Go usually means shelling out to gio, xdg-mime or notify-send, or binding GLib/GIO through cgo. go-freedesktop implements the underlying freedesktop.org specifications directly — parsing the same on-disk files and speaking the same D-Bus interface — in pure Go with cgo disabled. One small module per spec, reusing standard XDG base-directory resolution, so a launcher, file manager or shell pulls in only the layer it needs and cross-compiles to a static binary.

Modules

lib

desktopentry

Implements the Desktop Entry spec: enumerate the installed applications and expand their Exec= launch commands (field codes, TryExec, actions) — what a dock or app menu needs.

lib

icontheme

Implements the Icon Theme spec: resolve an icon name to a file path at a target size and scale, following theme inheritance and the hicolor fallback.

lib

mime

Implements the Shared MIME-info Database: resolve a canonical MIME type from a file's name, its content (magic), or both, against the on-disk database.

lib

mimeapps

Implements the MIME Applications Associations spec (mimeapps.list): the default application and the ordered candidate list for a type, with round-trippable edits — the engine behind “Open With…”.

lib

notifications

Implements the Desktop Notifications spec: the org.freedesktop.Notifications D-Bus service side — decode Notify calls and render them as go-widgets Toasts.

core

x11

The foundation every X11 client needs before it can say anything of its own: the wire codec, the .Xauthority parser, the connection-setup exchange, the shared-memory segment MIT-SHM attaches, and the unix transport that hands the server a descriptor over SCM_RIGHTS. No Xlib, no XCB — the bytes, and deliberately nothing above them. Shared by screencast and go-widgets/window, so one protocol parser cannot drift into two.

lib

screencast

Capture the pixels of displays and windows on Linux: MIT-SHM 1.2 with descriptor passing, the core GetImage fallback, RANDR 1.5 and XINERAMA monitor enumeration, XFIXES cursor. No shelling out to xwd, import or grim. Wayland is not implemented and says so: Diagnose reports when a session can only be captured through the portal's PipeWire stream, rather than failing obscurely.

lib

secretservice

Client for the Secret Service API (org.freedesktop.Secret.Service) over D-Bus: GNOME Keyring and KWallet secret storage, the Linux side of go-keyring.

docs

Versioned documentation site (MkDocs Material + mike): one page per module with the API surface and usage. Source →

brand

Logos and icons for the organization, in SVG / PNG / JPG / ICO / ICNS across colour, white and black variants.

Quality bar

Pure Go. CGO_ENABLED=0 across the org — no D-Bus C library, no GLib, no external tools.
Reuse, don't reinvent. XDG base-directory resolution comes from a shared library; later waves build on the earlier ones (mimeapps and menu stand on desktopentry).
100% test coverage is the bar, error branches included, on native amd64/arm64 plus emulated 64-bit targets.
Spec-faithful. Parses the same on-disk files and speaks the same D-Bus interface as the reference tools, so it interoperates with the rest of the desktop.
BSD-3-Clause on every source file.