README
¶
ConfigDir for Go
This library provides a cross platform means of detecting the system's configuration directories so that your Go app can store config files in a standard location. For Linux and other Unixes (BSD, etc.) this means using the Freedesktop.org XDG Base Directory Specification (0.8), and for Windows and macOS it uses their standard directories.
This is a simple no-nonsense module that just gives you the path names to do with as you please. You can either get the bare root config path, or get a path with any number of names suffixed onto it for vendor- or application-specific namespacing.
For the impatient, the directories this library can return tend to be like the following:
System-wide Configuration | |
---|---|
Windows | %PROGRAMDATA% or C:\ProgramData |
Linux | $XDG_CONFIG_DIRS or /etc/xdg |
macOS | /Library/Application Support |
User-level Configuration | |
Windows | %APPDATA% or C:\Users\%USER%\AppData\Roaming |
Linux | $XDG_CONFIG_HOME or $HOME/.config |
macOS | $HOME/Library/Application Support |
User-level Cache Folder | |
Windows | %LOCALAPPDATA% or C:\Users\%USER%\AppData\Local |
Linux | $XDG_CACHE_HOME or $HOME/.cache |
macOS | $HOME/Library/Caches |
Quick Start
// A common use case is to get a private config folder for your app to
// place its settings files into, that are specific to the local user.
configPath := configdir.LocalConfig("my-app")
err := configdir.MakePath(configPath) // Ensure it exists.
if err != nil {
panic(err)
}
// Deal with a JSON configuration file in that folder.
configFile := filepath.Join(configPath, "settings.json")
type AppSettings struct {
Username string `json:"username"`
Password string `json:"password"`
}
var settings AppSettings
// Does the file not exist?
if _, err = os.Stat(configFile); os.IsNotExist(err) {
// Create the new config file.
settings = AppSettings{"MyUser", "MyPassword"}
fh, err := os.Create(configFile)
if err != nil {
panic(err)
}
defer fh.Close()
encoder := json.NewEncoder(fh)
encoder.Encode(&settings)
} else {
// Load the existing file.
fh, err := os.Open(configFile)
if err != nil {
panic(err)
}
defer fh.Close()
decoder := json.NewDecoder(fh)
decoder.Decode(&settings)
}
Documentation
Package documentation is available at https://godoc.org/github.com/kirsle/configdir
Author
Noah Petherbridge, @kirsle
License
MIT
Documentation
¶
Overview ¶
Package configdir provides a cross platform means of detecting the system's configuration directories.
This makes it easy to program your Go app to store its configuration files in a standard location relevant to the host operating system. For Linux and some other Unixes (like BSD) this means following the Freedesktop.org XDG Base Directory Specification 0.8, and for Windows and macOS it uses their standard directories.
This is a simple no-nonsense module that just gives you the paths, with optional components tacked on the end for vendor- or app-specific namespacing. It also provides a convenience function to call `os.MkdirAll()` on the paths to ensure they exist and are ready for you to read and write files in.
Standard Global Configuration Paths
- Linux: $XDG_CONFIG_DIRS or "/etc/xdg"
- Windows: %PROGRAMDATA% or "C:\\ProgramData"
- macOS: /Library/Application Support
Standard User-Specific Configuration Paths
- Linux: $XDG_CONFIG_HOME or "$HOME/.config"
- Windows: %APPDATA% or "C:\\Users\\%USER%\\AppData\\Roaming"
- macOS: $HOME/Library/Application Support
Standard User-Specific Cache Paths
- Linux: $XDG_CACHE_HOME or "$HOME/.cache"
- Windows: %LOCALAPPDATA% or "C:\\Users\\%USER%\\AppData\\Local"
- macOS: $HOME/Library/Caches
Index ¶
Examples ¶
Constants ¶
const VERSION = "0.1.0"
VERSION is the semantic version number of the configdir library.
Variables ¶
var DefaultFileMode = os.FileMode(0755)
DefaultFileMode controls the default permissions on any paths created by using MakePath.
Functions ¶
func LocalCache ¶
LocalCache returns the local user cache folder, with optional path components added to the end for vendor/application-specific settings.
func LocalConfig ¶
LocalConfig returns the local user configuration path, with optional path components added to the end for vendor/application-specific settings.
func MakePath ¶
MakePath ensures that the full path you wanted, including vendor or application-specific components, exists. You can give this the output of any of the config path functions (SystemConfig, LocalConfig or LocalCache).
In the event that the path function gives multiple answers, e.g. for SystemConfig, MakePath() will only attempt to create the sub-folders on the *first* path found. If this isn't what you want, you may want to just use the os.MkdirAll() functionality directly.
func Refresh ¶
func Refresh()
Refresh will rediscover the config paths, checking current environment variables again.
This function is automatically called when the program initializes. If you change the environment variables at run-time, though, you may call the Refresh() function to reevaluate the config paths.
func SystemConfig ¶
SystemConfig returns the system-wide configuration paths, with optional path components added to the end for vendor/application-specific settings.
Types ¶
This section is empty.