appdirs

README

Appdirs for Go

This is my implementation of ActiveState's appdirs for Go.

Installation

Use go get to retrieve the module and add it to your GOPATH workspace, or project's Go module dependencies:

go get github.com/daemotron/appdirs

To update the SDK, use go get -U to retrieve the latest version of the module:

go get -U github.com/daemotron/appdirs

This module has been tested with Go 1.18 and 1.22.

Documentation

Usage Example

package main

import (
    "log"
    "github.com/daemotron/appdirs"
)

func main() {
    // create application context
    app := appdirs.AppConf{Name: "my-app"}

    // get the user-specific configuration directory and print it
    userDir, err := app.UserConfigDir()
    if err != nil {
        log.Fatalln(err)
    }
    log.Println(userDir)
}

API Reference

Full documentation for this package is available via the Go Package Index

Documentation

Overview

Package appdirs helps to determine appropriate platform-specific system directories. This includes directories where to place cache files, user data, configuration, etc.

Currently, this package supports the following operating systems:

• Linux
• Windows
• macOS

Please Note: While most unix systems should work with the present implementation, OS specific flavours (such as FreeBSD's /usr/local/etc directory) have not been implemented (yet).

This package is inspired by ActiveState's now deprecated appdirs Python package.

Index

• Variables
• type AppConf
  • func (conf AppConf) GlobalCacheDir() (string, error)
  • func (conf AppConf) GlobalConfigDir() (string, error)
  • func (conf AppConf) GlobalDataDir() (string, error)
  • func (conf AppConf) SiteConfigDir() (string, error)
  • func (conf AppConf) SiteDataDir() (string, error)
  • func (conf AppConf) UserCacheDir() (string, error)
  • func (conf AppConf) UserConfigDir() (string, error)
  • func (conf AppConf) UserDataDir() (string, error)
  • func (conf AppConf) UserLogDir() (string, error)
  • func (conf AppConf) UserStateDir() (string, error)

Variables

var (
	ErrAllUsersProfileNotDefined = errors.New("ALLUSERSPROFILE environment not defined") // %ALLUSERSPROFILE% environment not defined (Windows only)
)

Custom errors

Types

type AppConf

type AppConf struct {
	Name    string
	Author  string
	Version string
	Roaming bool
	Multi   bool
}

An AppConf instance represents an application. The fields in the struct can be filled in before calling any of its application-specific directory methods.

• Name indicates the application name and is mandatory
• Author indicates the application author or publisher and is optional
• Version is a version string and is optional
• Roaming is a flag indicating whether to use the roaming or local variant (Windows only)
• Multi is a flag indicating whether to return only one, or all possible paths separated by the OS specific separator

func (AppConf) GlobalCacheDir

func (conf AppConf) GlobalCacheDir() (string, error)

GlobalCacheDir returns the full path to the global cache dir for this application.

Typical global cache directories are:

macOS:      /Library/Caches/<AppName>
Unix:       /var/cache/<AppName>
Windows:    same as [UserCacheDir]

This method is mostly geared towards Unix; on Windows it is identical to [SiteDataDir].

func (AppConf) GlobalConfigDir

func (conf AppConf) GlobalConfigDir() (string, error)

GlobalConfigDir returns the full path to the global config dir for this application.

Typical global config directories are:

macOS:      same as [SiteConfigDir]
Unix:       /etc/<AppName>
Windows:    same as [SiteConfigDir]

This method is mostly geared towards Unix; on Windows it is identical to [SiteDataDir].

func (AppConf) GlobalDataDir

func (conf AppConf) GlobalDataDir() (string, error)

GlobalDataDir returns the full path to the global data dir for this application.

Typical site data directories are:

macOS:      /Library/Application Support/<AppName>
Unix:       /var/lib/<AppName>
Windows:    C:\ProgramData\<AppAuthor>\<AppName>   # Hidden, but writeable on Win 7.

This method is mostly geared towards Unix; on Windows it is identical to [SiteDataDir].

func (AppConf) SiteConfigDir

func (conf AppConf) SiteConfigDir() (string, error)

SiteConfigDir returns the full path to the user-shared config dir for this application.

Typical site config directories are:

macOS:      /Library/Preferences/<AppName>
Unix:       /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName> for each value in $XDG_CONFIG_DIRS
Windows:    same as [SiteDataDir]

For Unix, this is using the $XDG_CONFIG_DIRS[0] default, if conf.Multi = False

func (AppConf) SiteDataDir

func (conf AppConf) SiteDataDir() (string, error)

SiteDataDir returns the full path to the user-shared data dir for this application.

Typical site data directories are:

macOS:      /Library/Application Support/<AppName>
Unix:       /usr/local/share/<AppName> or /usr/share/<AppName>
Windows:    C:\ProgramData\<AppAuthor>\<AppName>   # Hidden, but writeable on Win 7.

For Unix, this is using the $XDG_DATA_DIRS[0] default.

func (AppConf) UserCacheDir

func (conf AppConf) UserCacheDir() (string, error)

UserCacheDir returns the full path to the user-specific cache dir for this application.

Typical user cache directories are:

macOS:      ~/Library/Caches/<AppName>
Unix:       ~/.cache/<AppName> (XDG default)
Windows:    C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Cache

For Unix, we follow the XDG spec and support $XDG_CACHE_HOME. That means, by default "~/.cache/<AppName>"

func (AppConf) UserConfigDir

func (conf AppConf) UserConfigDir() (string, error)

UserConfigDir returns the full path to the user-specific config dir for this application.

Typical user config directories are:

macOS:      ~/Library/Preferences/<AppName>
Unix:       ~/.config/<AppName>     # or in $XDG_CONFIG_HOME, if defined
Windows:    same as user_data_dir

For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default "~/.config/<AppName>".

func (AppConf) UserDataDir

func (conf AppConf) UserDataDir() (string, error)

UserDataDir returns the full path to the user-specific directory for this application

Typical user data directories are:

macOS:                  ~/Library/Application Support/<AppName>
Unix:                   ~/.local/share/<AppName>    # or in $XDG_DATA_HOME, if defined
Windows (not roaming):  C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>
Windows (roaming):      C:\Users\<username>\AppData\Roaming\<AppAuthor>\<AppName>

For Unix, we follow the XDG spec and support $XDG_DATA_HOME. That means, by default "~/.local/share/<AppName>".

func (AppConf) UserLogDir

func (conf AppConf) UserLogDir() (string, error)

UserLogDir returns the full path to the user-specific log dir for this application.

Typical user log directories are:

macOS:      ~/Library/Logs/<AppName>
Unix:       ~/.cache/<AppName>/log  # or under $XDG_CACHE_HOME if defined
Windows:    C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs

func (AppConf) UserStateDir

func (conf AppConf) UserStateDir() (string, error)

UserStateDir returns the full path to the user-specific state dir for this application.

Typical user state directories are:

macOS:     same as [UserDataDir]
Unix:      ~/.local/state/<AppName>   # or in $XDG_STATE_HOME, if defined
Windows:   same as [UserDataDir]

For Unix, we follow this Debian proposal <https://wiki.debian.org/XDGBaseDirectorySpecification#state> to extend the XDG spec and support $XDG_STATE_HOME. That means, by default "~/.local/state/<AppName>".