README.md

The XDG Base Directory Specification implemented in Go.

The XDG Base Directory Specification allows you specify directories where runtime files, configurations, data and caches are kept. The file discovery process is automatic and adheres to the XDG standard.

This package supports most Unix-based operating systems. It should work fine on MacOS. I wrote this package for my personal needs: to deduplicate this kind of functionality from my other programs, but it is very much a self-contained implementation.

See Usage section below for examples. Package documentation is available here: https://pkg.go.dev/github.com/mdm-code/xdg.

Installation

go get github.com/mdm-code/xdg

Default locations

The table shows default values for XDG environmental variables for Unix-like systems:

	Unix-like
XDG_DATA_HOME	$HOME/.local/share
XDG_CONFIG_HOME	$HOME/.config
XDG_STATE_HOME	$HOME/.local/state
XDG_DATA_DIRS	/usr/local/share/:/usr/share/
XDG_CONFIG_DIRS	/etc/xdg
XDG_CACHE_HOME	$HOME/.cache
XDG_RUNTIME_DIR	$TMPDIR

Usage

Here is an example of how to use the public API of the xdg package.

package main

import (
	"fmt"

	"github.com/mdm-code/xdg"
)

func main() {
	// XDG base directory paths.
	dirs := []struct {
		msg string
		pth string
	}{
		{"Home data directory: ", xdg.DataHomeDir()},
		{"Config home directory: ", xdg.CacheHomeDir()},
		{"State home directory: ", xdg.StateHomeDir()},
		{"Data directories: ", xdg.DataDirs()},
		{"Config directories: ", xdg.ConfigDirs()},
		{"Cache home directory: ", xdg.CacheHomeDir()},
		{"Runtime home directory: ", xdg.RuntimeDir()},
	}
	for _, d := range dirs {
		fmt.Println(d.msg, d.pth)
	}

	// Search for file in data XDG directories.
	fpath := "/prog/file"
	if f, ok := xdg.Find(xdg.Data, fpath); ok {
		fmt.Println(f)
	} else {
		fmt.Printf("ERROR: couldn't find %s\n", fpath)
	}
}

Development

Consult Makefile to see how to format, examine code with go vet, run unit test, run code linter with golint get test coverage and check if the package builds all right.

Remember to install golint before you try to run tests and test the build:

go install golang.org/x/lint/golint@latest

License

Copyright (c) 2023 Michał Adamczyk.

This project is licensed under the MIT license. See LICENSE for more details.