Usage

Summary

This library works by resolving a few key directories and saving the results to variables, namely:

Data, DATA_HOME and DATA_DIRS
Config, with CONFIG_HOME and CONFIG_DIRS
Executables, with BIN_HOME
State data, with STATE_HOME
Cached data, with CACHE_HOME
Runtime data, with RUNTIME_DIR

While it is possible to use these variables directly, it is recommended that you make use of the accessor functions instead, which all follow this pattern:

accessor() # Give the base directory(ies)
accessor(parts...) # Give the base directory(ies) joined with parts
accessor(proj::Project) # Give the base directory(ies) for proj
acessors(proj::Project, parts...) # proj directory(ies) joined with parts

Where accessor is a stand-in for the particular named directory being resolved. Two boolean keyword arguments are often supported:

create, to create the path when it does not exist. This is different to simply piping the returned path into mkpath in that it: a. Takes care to create the base directory with the appropriate mode (700) b. Creates the directory component of the path with the default mode (usually 755) c. If the path is to a file (i.e. the path does not end with /), touches the file.
existent, to filter the list of provided paths to ones that exist (when applicable)

To give appropriate project-specific directories we can use a BaseDirs.Project:

BaseDirs.Project — Type

A representation of a "Project", namely the essential components of naming information used to produce platform-appropriate project paths.

Project(name::AbstractString;
        org::AbstractString="julia", qualifier::AbstractString="lang")
  -> Project

The information needed, and the platforms that make use of it, are as follows:

name, the name of the project (Linux, MacOS, Windows)
org ("julia"), the organisation the project belongs to (MacOS, Windows)
qualifier ("org"), the nature of the organisation, usually a TLD (MacOS)

The resulting "project path components" take one of the following forms:

Platform	Project path form
Linux	`"$org/$name"`
MacOS	`"$qualifier.$org.$name"`
Windows	`"$org\$name"`

source

The user and system forms of the various accessor functions are split into the User and System modules, with combined accessors in the XDG namespace. This essentially creates a tree of accessor functions:

User
- data
- config
- bin
- state
- cache
- runtime
- fonts
- applications
System
- data
- config
- fonts
- applications
data
config
fonts
applications

The User submodule also provides a number of other "user folder" accessors, namely:

desktop
downloads
documents
music
pictures
videos
templates
public

Example usage

julia> using BaseDirs

julia> BaseDirs.CONFIG_HOME[]
"/home/tec/.config"

julia> BaseDirs.User.config()
"/home/tec/.config"

julia> BaseDirs.User.config("sub", "dir/")
"/home/tec/.config/sub/dir/"

julia> BaseDirs.User.config(BaseDirs.Project("mything"), "config.conf", create=true)
"/home/tec/.config/mything/config.conf"

Variables

Base directories

BaseDirs.DATA_HOME — Constant

DATA_HOME (XDG_DATA_HOME)

The single base directory relative to which user-specific data files should be written.

Default values

Linux	MacOS	Windows
`~/.local/share`	`~/Library/ApplicationSupport`	`RoamingAppData`

source

BaseDirs.DATA_DIRS — Constant

DATA_DIRS (XDG_DATA_DIRS)

The set of preference ordered base directories relative to which data files should be searched.

Default values

Linux	MacOS	Windows
`/usr/local/share`	`/Library/ApplicationSupport`	`ProgramData`
`/usr/share`

source

BaseDirs.CONFIG_HOME — Constant

CONFIG_HOME (XDG_CONFIG_HOME)

The single base directory relative to which user-specific configuration files should be written.

Default values

Linux	MacOS	Windows
`~/.local/config`	`~/Library/ApplicationSupport`	`RoamingAppData`

source

BaseDirs.CONFIG_DIRS — Constant

CONFIG_DIRS (XDG_CONFIG_DIRS)

The set of preference ordered base directories relative to which data files should be searched.

Default values

Linux	MacOS	Windows
`/etc/xdg`	`/Library/ApplicationSupport`	`ProgramData`

source

BaseDirs.BIN_HOME — Constant

BIN_HOME (XDG_BIN_HOME)

The single base directory relative to which user-specific executables should be written.

Default values

Linux	MacOS*	Windows*
`~/.local/bin`	`~/.local/bin`	`\bin`
	`/opt/local/bin`	`RoamingAppData\bin`
	`/usr/local/bin`	`AppData\bin`
		current working dir

* The first of these directories that exists is used.

Warning

This is not yet standardised by the XDG, see https://gitlab.freedesktop.org/xdg/xdg-specs/-/issues/14 for more information.

source

BaseDirs.STATE_HOME — Constant

STATE_HOME (XDG_STATE_HOME)

The single base directory relative to which user-specific state data should be written.

This should contain state data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in DATA_HOME. It may contain:

actions history (logs, history, recently used files, …)
current state of the application that can be reused on a restart (view, layout, open files, undo history, …)

Default values

Linux	MacOS	Windows
`~/.local/state`	`~/Library/ApplicationSupport`	`LocalAppData`

source

BaseDirs.CACHE_HOME — Constant

CACHE_HOME (XDG_CACHE_HOME)

The single base directory relative to which user-specific non-essential (cached) data should be written.

Default values

Linux	MacOS	Windows
`~/.cache`	`~/Library/Caches`	`LocalAppData\cache`

source

BaseDirs.RUNTIME_DIR — Constant

RUNTIME_DIR (XDG_RUNTIME_DIR)

The single base directory relative to which user-specific runtime files and other file objects should be placed. . Applications should use this directory for communication and synchronization purposes and should not place larger files in it.

Default values

Linux	MacOS	Windows
`/run/user/$UID`	`~/Library/ApplicationSupport`	`LocalAppData`

source

User directories

BaseDirs.DESKTOP_DIR — Constant

DESKTOP_DIR (XDG_DESKTOP_DIR)

The user's desktop directory.

source

BaseDirs.DOWNLOAD_DIR — Constant

DOWNLOAD_DIR (XDG_DOWNLOAD_DIR)

The user's downloads directory.

source

BaseDirs.DOCUMENTS_DIR — Constant

DOCUMENTS_DIR (XDG_DOCUMENTS_DIR)

The user's documents directory.

source

BaseDirs.PICTURES_DIR — Constant

PICTURES_DIR (XDG_PICTURES_DIR)

The user's pictures directory.

source

BaseDirs.VIDEOS_DIR — Constant

VIDEOS_DIR (XDG_VIDEOS_DIR)

The user's videos directory.

source

BaseDirs.TEMPLATES_DIR — Constant

TEMPLATES_DIR (XDG_TEMPLATES_DIR)

The user's templates directory.

source

BaseDirs.PUBLICSHARE_DIR — Constant

PUBLICSHARE_DIR (XDG_PUBLICSHARE_DIR)

The user's public directory.

source

Other directories

BaseDirs.APPLICATIONS_DIRS — Constant

APPLICATIONS_DIRS

A list of locations in which application files may be found/placed.

source

BaseDirs.FONTS_DIRS — Constant

FONTS_DIRS

A list of locations in which font files may be found.

source

Functions

User

BaseDirs.User — Module

BaseDirs.User

This module containes accessor functions for user-specific directories.

Base directory acessors

data, config, state, cache, and runtime -> String

User directory accessors

desktop, downloads, music, videos, templates, public -> String

Other acessors

fonts and applications -> Vector{String}

Note

Unlike the System and "combined" (BaseDirs.*) acessors, the Base and User acessors here return a single directory (String).

source

BaseDirs.User.data — Function

data(; create) -> String # the directory
data(parts...; create) # the directory joined with parts
data(proj::Project; create) # the project-specific directory
data(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the user configuration directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user configuration directory as appropriate.

The returned path is based on the variable BaseDirs.DATA_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

source

BaseDirs.User.config — Function

config(; create) -> String # the directory
config(parts...; create) # the directory joined with parts
config(proj::Project; create) # the project-specific directory
config(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the user configuration directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user configuration directory as appropriate.

The returned path is based on the variable BaseDirs.CONFIG_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

source

BaseDirs.User.bin — Function

bin(; create) -> String # the directory
bin(parts...; create) # the directory joined with parts
bin(proj::Project; create) # the project-specific directory
bin(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the executables directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the executables directory as appropriate.

The returned path is based on the variable BaseDirs.BIN_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

Special behaviour

When create is true and the path referrs to a file, chmod is called to ensure that all users who can read the file can execute it.

source

BaseDirs.User.state — Function

state(; create) -> String # the directory
state(parts...; create) # the directory joined with parts
state(proj::Project; create) # the project-specific directory
state(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the state data directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the state data directory as appropriate.

The returned path is based on the variable BaseDirs.STATE_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

source

BaseDirs.User.cache — Function

cache(; create) -> String # the directory
cache(parts...; create) # the directory joined with parts
cache(proj::Project; create) # the project-specific directory
cache(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the cached data directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the cached data directory as appropriate.

The returned path is based on the variable BaseDirs.CACHE_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

source

BaseDirs.User.runtime — Function

state(; create) -> String # the directory
state(parts...; create) # the directory joined with parts
state(proj::Project; create) # the project-specific directory
state(proj::Project, parts...; create) # the project-specific directory joined with parts

Locate the runtime information directory. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the runtime information directory as appropriate.

The returned path is based on the variable BaseDirs.STATE_HOME, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).

source

BaseDirs.User.desktop — Function

desktop(parts...) -> String

Join the desktop directory with zero or more path components (parts).

The desktop directory is based on the variable BaseDirs.DESKTOP_DIR, which see.

source

BaseDirs.User.downloads — Function

downloads(parts...) -> String

Join the downloads directory with zero or more path components (parts).

The downloads directory is based on the variable BaseDirs.DOWNLOADS_DIR, which see.

source

BaseDirs.User.documents — Function

documents(parts...) -> String

Join the documents directory with zero or more path components (parts).

The documents directory is based on the variable BaseDirs.DOCUMENTS_DIR, which see.

source

BaseDirs.User.music — Function

music(parts...) -> String

Join the music directory with zero or more path components (parts).

The music directory is based on the variable BaseDirs.MUSIC_DIR, which see.

source

BaseDirs.User.pictures — Function

pictures(parts...) -> String

Join the pictures directory with zero or more path components (parts).

The pictures directory is based on the variable BaseDirs.PICTURES_DIR, which see.

source

BaseDirs.User.videos — Function

videos(parts...) -> String

Join the videos directory with zero or more path components (parts).

The videos directory is based on the variable BaseDirs.VIDEOS_DIR, which see.

source

BaseDirs.User.templates — Function

templates(parts...) -> String

Join the templates directory with zero or more path components (parts).

The templates directory is based on the variable BaseDirs.TEMPLATES_DIR, which see.

source

BaseDirs.User.public — Function

public(parts...) -> String

Join the public directory with zero or more path components (parts).

The public directory is based on the variable BaseDirs.PUBLIC_DIR, which see.

source

BaseDirs.User.fonts — Function

fonts(; create, existent) -> Vector{String} # all directories
fonts(parts...; create, existent) # all directories joined with parts
fonts(proj::Project; create, existent) # all project-specific directories
fonts(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all user fonts directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user fonts directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.User.applications — Function

applications(; create, existent) -> Vector{String} # all directories
applications(parts...; create, existent) # all directories joined with parts
applications(proj::Project; create, existent) # all project-specific directories
applications(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all user applications directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user applications directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

System

BaseDirs.System — Module

BaseDirs.System

This module contains acessor functions for system directories.

Base directory acessors

data, config -> Vector{String}

Other acessors

fonts and applications -> Vector{String}

source

BaseDirs.System.data — Function

data(; create, existent) -> Vector{String} # all directories
data(parts...; create, existent) # all directories joined with parts
data(proj::Project; create, existent) # all project-specific directories
data(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all system configuration directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the system configuration directories as appropriate.

The returned path is based on the variable BaseDirs.DATA_DIRS, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.System.config — Function

config(; create, existent) -> Vector{String} # all directories
config(parts...; create, existent) # all directories joined with parts
config(proj::Project; create, existent) # all project-specific directories
config(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

The returned path is based on the variable BaseDirs.CONFIG_DIRS, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.System.fonts — Function

fonts(; create, existent) -> Vector{String} # all directories
fonts(parts...; create, existent) # all directories joined with parts
fonts(proj::Project; create, existent) # all project-specific directories
fonts(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all system fonts directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the system fonts directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.System.applications — Function

applications(; create, existent) -> Vector{String} # all directories
applications(parts...; create, existent) # all directories joined with parts
applications(proj::Project; create, existent) # all project-specific directories
applications(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all system applications directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the system applications directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

Combined

BaseDirs.data — Function

data(; create, existent) -> Vector{String} # all directories
data(parts...; create, existent) # all directories joined with parts
data(proj::Project; create, existent) # all project-specific directories
data(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all user and system configuration directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user and system configuration directories as appropriate.

The returned path is based on the variables BaseDirs.DATA_HOME, and BaseDirs.DATA_DIRS, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.config — Function

config(; create, existent) -> Vector{String} # all directories
config(parts...; create, existent) # all directories joined with parts
config(proj::Project; create, existent) # all project-specific directories
config(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

The returned path is based on the variables BaseDirs.CONFIG_HOME, and BaseDirs.CONFIG_DIRS, which see.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.fonts — Function

fonts(; create, existent) -> Vector{String} # all directories
fonts(parts...; create, existent) # all directories joined with parts
fonts(proj::Project; create, existent) # all project-specific directories
fonts(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all user and system fonts directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user and system fonts directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source

BaseDirs.applications — Function

applications(; create, existent) -> Vector{String} # all directories
applications(parts...; create, existent) # all directories joined with parts
applications(proj::Project; create, existent) # all project-specific directories
applications(proj::Project, parts...; create, existent) # all project-specific directories joined with parts

Locate all user and system applications directories. Optionally, a project and/or path components can be provided as arguments, in which case they are joined with the user and system applications directories as appropriate.

Keyword arguments

create::Bool (default false), whether the path should be created if it does not exist. Paths ending in / are interpreted as directories, and all other paths are considered files. This takes care to create the base directories with the appropriate permissions (700).
existent::Bool (default false), filter out paths that do not exist.

source