BaseDirs.System
— ModuleBaseDirs.System
This module contains acessor functions for system directories.
Base directory acessors
data
, config
-> Vector{String}
Other acessors
fonts
and applications
-> Vector{String}
BaseDirs.User
— ModuleBaseDirs.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}
Unlike the System
and "combined" (BaseDirs.*) acessors, the Base and User acessors here return a single directory (String
).
BaseDirs.BaseDirs
— ModuleBaseDirs
This module provides utilities to identify the appropriate locations for files.
The User
and System
submodules provide a number of accessor functions, which see.
There are also four combined accessor functions defined, namely: data
, config
, fonts
, and applications
. These provide a list of all relevant user and system directories.
This is essentially an implementation of the XDG (Cross-Desktop Group) directory specifications, with analogues for Windows and MacOS for cross-platform. More specifically, this is a hybrid of:
- The XDG base directory and the XDG user directory specifications on Linux
- The Known Folder API on Windows
- The Standard Directories guidelines on macOS
BaseDirs.APPLICATIONS_DIRS
— ConstantAPPLICATIONS_DIRS
A list of locations in which application files may be found/placed.
BaseDirs.BIN_HOME
— ConstantBIN_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.
This is not yet standardised by the XDG, see https://gitlab.freedesktop.org/xdg/xdg-specs/-/issues/14 for more information.
BaseDirs.CACHE_HOME
— ConstantCACHE_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 |
BaseDirs.CONFIG_DIRS
— ConstantCONFIG_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 |
BaseDirs.CONFIG_HOME
— ConstantCONFIG_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 |
BaseDirs.DATA_DIRS
— ConstantDATA_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 |
BaseDirs.DATA_HOME
— ConstantDATA_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 |
BaseDirs.DESKTOP_DIR
— ConstantDESKTOP_DIR (XDG_DESKTOP_DIR
)
The user's desktop directory.
BaseDirs.DOCUMENTS_DIR
— ConstantDOCUMENTS_DIR (XDG_DOCUMENTS_DIR
)
The user's documents directory.
BaseDirs.DOWNLOAD_DIR
— ConstantDOWNLOAD_DIR (XDG_DOWNLOAD_DIR
)
The user's downloads directory.
BaseDirs.FONTS_DIRS
— ConstantFONTS_DIRS
A list of locations in which font files may be found.
BaseDirs.MUSIC_DIR
— ConstantMUSIC_DIR (XDG_MUSIC_DIR
)
The user's music directory.
BaseDirs.PICTURES_DIR
— ConstantPICTURES_DIR (XDG_PICTURES_DIR
)
The user's pictures directory.
BaseDirs.PUBLICSHARE_DIR
— ConstantPUBLICSHARE_DIR (XDG_PUBLICSHARE_DIR
)
The user's public directory.
BaseDirs.RUNTIME_DIR
— ConstantRUNTIME_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 |
BaseDirs.STATE_HOME
— ConstantSTATE_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 |
BaseDirs.TEMPLATES_DIR
— ConstantTEMPLATES_DIR (XDG_TEMPLATES_DIR
)
The user's templates directory.
BaseDirs.VIDEOS_DIR
— ConstantVIDEOS_DIR (XDG_VIDEOS_DIR
)
The user's videos directory.
BaseDirs.Project
— TypeA 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" |
BaseDirs.System.applications
— Functionapplications(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.System.config
— Functionconfig(; 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
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.CONFIG_DIRS
, which see.
Keyword arguments
create::Bool
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.System.data
— Functiondata(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.System.fonts
— Functionfonts(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.User.applications
— Functionapplications(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.User.bin
— Functionbin(; 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
(defaultfalse
), 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).
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.
BaseDirs.User.cache
— Functioncache(; 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
(defaultfalse
), 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).
BaseDirs.User.config
— Functionconfig(; 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
(defaultfalse
), 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).
BaseDirs.User.data
— Functiondata(; 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
(defaultfalse
), 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).
BaseDirs.User.desktop
— Functiondesktop(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.
BaseDirs.User.documents
— Functiondocuments(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.
BaseDirs.User.downloads
— Functiondownloads(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.
BaseDirs.User.fonts
— Functionfonts(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.User.music
— Functionmusic(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.
BaseDirs.User.pictures
— Functionpictures(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.
BaseDirs.User.public
— Functionpublic(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.
BaseDirs.User.runtime
— Functionstate(; 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
(defaultfalse
), 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).
BaseDirs.User.state
— Functionstate(; 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
(defaultfalse
), 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).
BaseDirs.User.templates
— Functiontemplates(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.
BaseDirs.User.videos
— Functionvideos(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.
BaseDirs.applications
— Functionapplications(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.config
— Functionconfig(; 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
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.CONFIG_HOME
, and BaseDirs.CONFIG_DIRS
, which see.
Keyword arguments
create::Bool
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.data
— Functiondata(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.fonts
— Functionfonts(; 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
(defaultfalse
), 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
(defaultfalse
), filter out paths that do not exist.
BaseDirs.parseuserdirs
— Methodparseuserdirs(configdir::String)
Parse the user-dirs.dirs
file that lies under configdir
. Returns a NamedTuple
with all relevant entries.
This is not part of the BaseDirs API.
BaseDirs.Internals.ensureexecutable
— Methodensureexecutable(path::String)
Make path
executable by everybody who can read it. Returns path
.
BaseDirs.Internals.ensurepath
— Methodensurepath(path::String)
Ensure that path
exists. Should path
end with /
it is interpreted as a directory. The directory-suffix /
is used on all filesystems for consistency of the API, regardless of the native path seperator of the host filesystem.