xdgbasedir

README

go-xdgbasedir

Package xdgbasedir implements a freedesktop XDG Base Directory Specification for Go.

linux / darwin	windows	coverage
godoc.org	Release

freedesktop.org XDG Base Directory Specification reference:

• https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.8.html
• https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Current specification version:

• 0.8

Specification

func	linux, darwin (Mode: Unix)	darwin (Mode: Native)	windows
DataHome()	~/.local/share	~/Library/Application Support	C:\Users\%USER%\AppData\Local
ConfigHome()	~/.config	~/Library/Preferences	C:\Users\%USER%\AppData\Local
DataDirs()	/usr/local/share:/usr/share	~/Library/Application Support	C:\Users\%USER%\AppData\Local
ConfigDirs()	/etc/xdg	~/Library/Preferences	C:\Users\%USER%\AppData\Local
CacheHome()	~/.cache	~/Library/Caches	C:\Users\%USER%\AppData\Local\cache
RuntimeDir()	/run/user/$(id -u)	~/Library/Application Support	C:\Users\%USER%

Note

XDG Base Directory Specification is mainly for GNU/Linux. It does not mention which directory to use with macOS(darwin) or windows.
So, We referred to the qt standard paths document for the corresponding directory.

We prepared a Mode for users using macOS like Unix. It's darwin GOOS specific.
If it is set to Unix, it refers to the same path as linux. If it is set to Native, it refers to the Specification path.
By default, Unix.

Unix:

// +build darwin

package main

import (
	"fmt"

	"github.com/zchee/go-xdgbasedir"
)

func main() {
	xdgbasedir.Mode = xdgbasedir.Unix // optional, default is Unix
	fmt.Println(xdgbasedir.DataHome())

	// Output:
	// "/Users/foo/.local/share"
}

Native:

// +build darwin

package main

import (
	"fmt"

	"github.com/zchee/go-xdgbasedir"
)

func main() {
	xdgbasedir.Mode = xdgbasedir.Native
	fmt.Println(xdgbasedir.DataHome())

	// Output:
	// "/Users/foo/Library/Application Support"
}

Badge

powered by shields.io.

markdown:

[![XDGBaseDirSpecVersion](https://img.shields.io/badge/%20XDG%20Base%20Dir%20-%200.8-blue.svg?style=flat-square)](https://specifications.freedesktop.org/basedir-spec/0.8/)

Documentation

Overview

Package xdgbasedir implements a freedesktop.org XDG Base Directory Specification.

https://specifications.freedesktop.org/basedir-spec/latest/

The XDG Base Directory Specification is based on the following concepts:

- There is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME.

- There is a single base directory relative to which user-specific configuration files should be written. This directory is defined by the environment variable $XDG_CONFIG_HOME.

- There is a set of preference ordered base directories relative to which data files should be searched. This set of directories is defined by the environment variable $XDG_DATA_DIRS.

- There is a set of preference ordered base directories relative to which configuration files should be searched. This set of directories is defined by the environment variable $XDG_CONFIG_DIRS.

- There is a single base directory relative to which user-specific non-essential (cached) data should be written. This directory is defined by the environment variable $XDG_CACHE_HOME.

Index

• Constants
• Variables
• func CacheHome() string
• func ConfigDirs() string
• func ConfigHome() string
• func DataDirs() string
• func DataHome() string
• func RuntimeDir() string

Constants

const (
	// Unix unix mode directory structure.
	Unix mode = iota
	// Native native mode directory structure.
	Native
)

Variables

var Mode = Unix

Mode mode of directory structure. This config only available darwin.

If it is set to `Unix`, it refers to the same path as linux. If it is set to `Native`, it refers to the Apple FileSystemProgrammingGuide path. By default, `Unix`.

Functions

func CacheHome

func CacheHome() string

CacheHome return the XDG_CACHE_HOME based directory path.

$XDG_CACHE_HOME defines the base directory relative to which user specific non-essential data files should be stored. If $XDG_CACHE_HOME is either not set or empty, a default equal to $HOME/.cache should be used.

func ConfigDirs

func ConfigDirs() string

ConfigDirs return the XDG_CONFIG_DIRS based directory path.

$XDG_CONFIG_DIRS defines the preference-ordered set of base directories to search for configuration files in addition to the $XDG_CONFIG_HOME base directory. The directories in $XDG_CONFIG_DIRS should be seperated with a colon ':'. If $XDG_CONFIG_DIRS is either not set or empty, a value equal to /etc/xdg should be used.

func ConfigHome

func ConfigHome() string

ConfigHome return the XDG_CONFIG_HOME based directory path.

$XDG_CONFIG_HOME defines the base directory relative to which user specific configuration files should be stored. If $XDG_CONFIG_HOME is either not set or empty, a default equal to $HOME/.config should be used.

func DataDirs

func DataDirs() string

DataDirs return the XDG_DATA_DIRS based directory path.

$XDG_DATA_DIRS defines the preference-ordered set of base directories to search for data files in addition to the $XDG_DATA_HOME base directory. The directories in $XDG_DATA_DIRS should be seperated with a colon ':'. If $XDG_DATA_DIRS is either not set or empty, a value equal to /usr/local/share/:/usr/share/ should be used.

func DataHome

func DataHome() string

DataHome return the XDG_DATA_HOME based directory path.

$XDG_DATA_HOME defines the base directory relative to which user specific data files should be stored. If $XDG_DATA_HOME is either not set or empty, a default equal to $HOME/.local/share should be used.

func RuntimeDir

func RuntimeDir() string

RuntimeDir return the XDG_RUNTIME_DIR based directory path.

$XDG_RUNTIME_DIR defines the base directory relative to which user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...) should be stored. The directory MUST be owned by the user, and he MUST be the only one having read and write access to it. Its Unix access mode MUST be 0700.

TODO(zchee): XDG_RUNTIME_DIR seems to change depending on the each distro or init system such as systemd. Also In macOS, normal user haven't permission for write to this directory. xref:

http://serverfault.com/questions/388840/good-default-for-xdg-runtime-dir/727994#727994