From 4cdbe559d3901e6966cf43b1ef0e43b5c46974b9 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 31 Jul 2024 17:15:14 +0000 Subject: [PATCH] build based on 26fcc2f --- dev/.documenter-siteinfo.json | 2 +- dev/defaults/index.html | 2 +- dev/index.html | 2 +- dev/others/index.html | 2 +- dev/usage/index.html | 36 +++++++++++++++++------------------ 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index b228d43..84983f3 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-31T16:20:46","documenter_version":"1.0.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-31T17:15:11","documenter_version":"1.0.1"}} \ No newline at end of file diff --git a/dev/defaults/index.html b/dev/defaults/index.html index 699a02a..fc63dc2 100644 --- a/dev/defaults/index.html +++ b/dev/defaults/index.html @@ -1,2 +1,2 @@ -Defaults · BaseDirs.jl

Defaults

From our survey of other simlar packages, we've seen a range of approaches. Trying to take the best of those, these are the defaults that BaseDirs.jl uses.

Base directories

Common NameEnvVarLinuxMacOSWindows (KnownPath)
User dataXDG_DATA_HOME~/.local/share~/Library/Application SupportRoamingAppData
System dataXDG_DATA_DIRS/usr/local/share, /usr/share/Library/Application SupportProgramData
User configXDG_CONFIG_HOME~/.config~/Library/Application SupportRoamingAppData
System configXDG_CONFIG_DIRS/etc/xdg/Library/Application SupportProgramData
StateXDG_STATE_HOME~/.local/state~/Library/Application SupportLocalAppData
User executablesXDG_BIN_HOME [binhome]~/.local/bin~/.local/bin or /opt/local/bin or /usr/local/bin~\bin or RoamingAppData\bin or AppData\bin or pwd()
CacheXDG_CACHE_HOME~/.cache~/Library/Caches/LocalAppData\cache
RuntimeXDG_RUNTIME_DIR/run/user/$UID~/Library/Application SupportLocalAppData

User directories

Common NameEnvVarLinux[xdguserdirs]MacOSWindows (KnownPath)
DesktopXDG_DESKTOP_DIR~/Desktop~/DesktopDesktop
DownloadXDG_DOWNLOAD_DIR~/Downloads~/DownloadsDownloads
DocumentsXDG_DOCUMENTS_DIR~/Documents~/DocumentsDocuments
MusicXDG_MUSIC_DIR~/Music~/MusicMusic
PicturesXDG_PICTURES_DIR~/Pictures~/PicturesPictures
VideosXDG_VIDEOS_DIR~/Videos~/MoviesVideos
TemplatesXDG_TEMPLATES_DIR~/Templates~/TemplatesTemplates
PublicXDG_PUBLICSHARE_DIR~/Public~/PublicPublic

Project directories

Project paths

A project path string (henceforth given by the Project placeholder) is formatted according to the following bits of information:

  • Qualifier (only used on mac), which defaults to org
  • Organisation/Company, which defaults to julia
  • Application/Project name, which must be provided.

The operating system specific project path is composed as follows:

SystemProject path formatExample
Linux$Namecontraption
MacOS$Qualifier.$Organisation.$Namecom.ACME.contraption
Windows$Organisation\$NameACME\contraption

Project directory template

Common NameLinuxMacOSWindows
User data$(User data)/$Project$(User data)/$Project$(User data)\$Project\data
System data$(System data)/$Project$(System data)/$Project$(System data)\$Project\data
User config$(User config)/$Project$(User config)/$Project$(User config)\$Project\config
System config$(System config)/$Project$(System config)/$Project$(System config)\$Project\config
Cache$(Cache)/$Project$(Cache)/$Project$(Cache)\$Project\cache
State$(State)/$Project$(State)/$Project$(State)\$Project\state

Extra directories

Common nameLinuxMacOSWindows
Fonts$(User data)/fonts, ~/.fonts, $(System data)/fonts~/Library/Fonts, /Library/Fonts, /System/Library/Fonts, /Network/Library/FontsFonts
Applications$(User data)/applications, $(System data)/applications/ApplicationsPrograms, CommonPrograms
  • binhomeWhile XDG_BIN_HOME is not yet standard, it seems like the most likely name to be given to ~/.local/bin (see this issue), and I think it is worth having something rather than nothing.
  • xdguserdirsIn accordance with the xdg-user-dirs documentation, the system and user user-dirs.dirs files are checked before using the defaults.
+Defaults · BaseDirs.jl

Defaults

From our survey of other simlar packages, we've seen a range of approaches. Trying to take the best of those, these are the defaults that BaseDirs.jl uses.

Base directories

Common NameEnvVarLinuxMacOSWindows (KnownPath)
User dataXDG_DATA_HOME~/.local/share~/Library/Application SupportRoamingAppData
System dataXDG_DATA_DIRS/usr/local/share, /usr/share/Library/Application SupportProgramData
User configXDG_CONFIG_HOME~/.config~/Library/Application SupportRoamingAppData
System configXDG_CONFIG_DIRS/etc/xdg/Library/Application SupportProgramData
StateXDG_STATE_HOME~/.local/state~/Library/Application SupportLocalAppData
User executablesXDG_BIN_HOME [binhome]~/.local/bin~/.local/bin or /opt/local/bin or /usr/local/bin~\bin or RoamingAppData\bin or AppData\bin or pwd()
CacheXDG_CACHE_HOME~/.cache~/Library/Caches/LocalAppData\cache
RuntimeXDG_RUNTIME_DIR/run/user/$UID~/Library/Application SupportLocalAppData

User directories

Common NameEnvVarLinux[xdguserdirs]MacOSWindows (KnownPath)
DesktopXDG_DESKTOP_DIR~/Desktop~/DesktopDesktop
DownloadXDG_DOWNLOAD_DIR~/Downloads~/DownloadsDownloads
DocumentsXDG_DOCUMENTS_DIR~/Documents~/DocumentsDocuments
MusicXDG_MUSIC_DIR~/Music~/MusicMusic
PicturesXDG_PICTURES_DIR~/Pictures~/PicturesPictures
VideosXDG_VIDEOS_DIR~/Videos~/MoviesVideos
TemplatesXDG_TEMPLATES_DIR~/Templates~/TemplatesTemplates
PublicXDG_PUBLICSHARE_DIR~/Public~/PublicPublic

Project directories

Project paths

A project path string (henceforth given by the Project placeholder) is formatted according to the following bits of information:

  • Qualifier (only used on mac), which defaults to org
  • Organisation/Company, which defaults to julia
  • Application/Project name, which must be provided.

The operating system specific project path is composed as follows:

SystemProject path formatExample
Linux$Namecontraption
MacOS$Qualifier.$Organisation.$Namecom.ACME.contraption
Windows$Organisation\$NameACME\contraption

Project directory template

Common NameLinuxMacOSWindows
User data$(User data)/$Project$(User data)/$Project$(User data)\$Project\data
System data$(System data)/$Project$(System data)/$Project$(System data)\$Project\data
User config$(User config)/$Project$(User config)/$Project$(User config)\$Project\config
System config$(System config)/$Project$(System config)/$Project$(System config)\$Project\config
Cache$(Cache)/$Project$(Cache)/$Project$(Cache)\$Project\cache
State$(State)/$Project$(State)/$Project$(State)\$Project\state

Extra directories

Common nameLinuxMacOSWindows
Fonts$(User data)/fonts, ~/.fonts, $(System data)/fonts~/Library/Fonts, /Library/Fonts, /System/Library/Fonts, /Network/Library/FontsFonts
Applications$(User data)/applications, $(System data)/applications/ApplicationsPrograms, CommonPrograms
  • binhomeWhile XDG_BIN_HOME is not yet standard, it seems like the most likely name to be given to ~/.local/bin (see this issue), and I think it is worth having something rather than nothing.
  • xdguserdirsIn accordance with the xdg-user-dirs documentation, the system and user user-dirs.dirs files are checked before using the defaults.
diff --git a/dev/index.html b/dev/index.html index 7e04c52..091dd52 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Introduction · BaseDirs.jl

BaseDirs

This package exists to help you put and look for files in the appropriate place(s).

It 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:

Why should I care?

It may be easy to treat file paths haphazardly, but for the user in particular abiding by the standards/conventions of the their platform has a number of major benefits, such as:

  • Improved ease of backups, since it is easier to make rules for which folders need to be backed up.
  • Improved configuration portability, since it is easier to identify and share the relevant configuration files.
  • Ease of isolating application state, by containing state to a single directory it is easy to avoid sharing it.
  • Decreased reliance on hard-coded paths, improving flexibility and composability.

It is worth noting that these considerations apply to both graphical and command-line desktop applications.

Choosing the appropriate base directory

image

+Introduction · BaseDirs.jl

BaseDirs

This package exists to help you put and look for files in the appropriate place(s).

It 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:

Why should I care?

It may be easy to treat file paths haphazardly, but for the user in particular abiding by the standards/conventions of the their platform has a number of major benefits, such as:

  • Improved ease of backups, since it is easier to make rules for which folders need to be backed up.
  • Improved configuration portability, since it is easier to identify and share the relevant configuration files.
  • Ease of isolating application state, by containing state to a single directory it is easy to avoid sharing it.
  • Decreased reliance on hard-coded paths, improving flexibility and composability.

It is worth noting that these considerations apply to both graphical and command-line desktop applications.

Choosing the appropriate base directory

image

diff --git a/dev/others/index.html b/dev/others/index.html index 1ac0aa8..2e52830 100644 --- a/dev/others/index.html +++ b/dev/others/index.html @@ -1,2 +1,2 @@ -Prior Art · BaseDirs.jl

A Survey of other XDG-y packages

The entire point of this package is to handle locations in a fairly standardised way. With this in mind, it seems fairly sensible to survey other notable XDG-y packages and see how them behave. Specifically, we will be looking at the following:

Base directories

Linux

Common NameEnvVarXDG specQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOME~/.local/shareXDG specXDG specXDG specXDG spec
System dataXDG_DATA_DIRS/usr/local/share, /usr/shareXDG specXDG spec~/.local/shareXDG spec
User configXDG_CONFIG_HOME~/.configXDG specXDG specXDG specXDG spec
System configXDG_CONFIG_DIRS/etc/xdgXDG specXDG spec-XDG spec
StateXDG_STATE_HOME~/.local/state-XDG specXDG specXDG spec
User executablesXDG_BIN_HOME [binhome]~/.local/bin--XDG spec-
CacheXDG_CACHE_HOME~/.cacheXDG specXDG specXDG specXDG spec
RuntimeXDG_RUNTIME_DIR/run/user/$UIDXDG specXDG spec-XDG spec

MacOS

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOME~/Library/Application SupportQtQtQt
System dataXDG_DATA_DIRS/Library/Application SupportQt~/Library/Application SupportQt
User configXDG_CONFIG_HOME~/Library/Preferences~/Library/Application SupportGo XDGQt
System configXDG_CONFIG_DIRS~/Library/Preferences~/Library/Preferences, /Library/Application Support, /Library/Preferences--
StateXDG_STATE_HOME-~/Library/Application Support-Go XDG
User executablesXDG_BIN_HOME [binhome]----
CacheXDG_CACHE_HOME~/Library/Caches/ , /Library/CachesQtQtQt
RuntimeXDG_RUNTIME_DIR~/Library/Application SupportQt-~/Library/Caches/TemporaryItems

Windows

Here folder names not beginning with ~ or / refer to Known Folders.

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOMELocalAppDataQtQtLocalAppData or RoamingAppData
System dataXDG_DATA_DIRSProgramDataRoamingAppData, ProgramDataRoamingAppDataProgramData
User configXDG_CONFIG_HOMELocalAppDataLocalAppDataRoamingAppDataLocalAppData or RoamingAppData
System configXDG_CONFIG_DIRSProgramDataProgramData, RoamingAppData-ProgramData
StateXDG_STATE_HOME-LocalAppData-LocalAppData
User executablesXDG_BIN_HOME [binhome]---
CacheXDG_CACHE_HOMELocalAppData\cacheLocalAppData\cacheLocalAppDataLocalAppData\Cache
RuntimeXDG_RUNTIME_DIR~LocalAppDataGo XDGLocalAppData\Temp

User directories

Linux

Common NameEnvVarXDG specQStandardPathsGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIR~/DesktopXDG specXDG spec--
DownloadXDG_DOWNLOAD_DIR~/DownloadsXDG specXDG spec--
DocumentsXDG_DOCUMENTS_DIR~/DocumentsXDG specXDG spec-XDG spec
MusicXDG_MUSIC_DIR~/MusicXDG specXDG spec--
PicturesXDG_PICTURES_DIR~/PicturesXDG specXDG spec--
VideosXDG_VIDEOS_DIR~/VideosXDG specXDG spec--
TemplatesXDG_TEMPLATES_DIR~/Templates-XDG spec--
PublicXDG_PUBLICSHARE_DIR~/Public-XDG spec--

MacOS

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIR~/DesktopQtQt-
DownloadXDG_DOWNLOAD_DIR~/DownloadsQtQt-
DocumentsXDG_DOCUMENTS_DIR~/DocumentQtQtQt
MusicXDG_MUSIC_DIR~/MusicQtQt-
PicturesXDG_PICTURES_DIR~/PicturesQtQt-
VideosXDG_VIDEOS_DIR~/MoviesQtQt-
TemplatesXDG_TEMPLATES_DIR-~/TemplateGo XDG-
PublicXDG_PUBLICSHARE_DIR-~/PublicGo XDG-

Windows

Common NameEnvVarGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIRDesktopGo XDG-
DownloadXDG_DOWNLOAD_DIRDownloadsGo XDG-
DocumentsXDG_DOCUMENTS_DIRDocumentsGo XDGGo XDG
MusicXDG_MUSIC_DIRMusicGo XDG-
PicturesXDG_PICTURES_DIRPicturesGo XDG-
VideosXDG_VIDEOS_DIRVideosGo XDG-
TemplatesXDG_TEMPLATES_DIRTemplatesGo XDG-
PublicXDG_PUBLICSHARE_DIRPublicGo XDG-

Project directories

Here $PP will be a stand-in for the project path, according to the conventions of the OS.

Linux

Common NameQStandardPathsRust directories-rs
User data$(User data)/$PP$(User data)/$PP
System data$(System data)/$PP$(User data)/$PP
User config$(User config)/$PP$(User config)/$PP
System config$(System config)/$PP-
Cache$(Cache)/$PP$(Cache)/$PP
State-$(State)/$PP

MacOS

Common NameQStandardPathsRust directories-rs
User data$(User data)/$PP$(User data)/$PP
System data$(System data)/$PP$(User data)/$PP
User config$(User config)/$PP$(User config)/$PP
System config--
Cache$(Cache)/$PP$(Cache)/$PP
State--

Windows

Common NameQStandardPathsRust directories-rs
User data$(User data)\$PP$(User data)\$PP\data
System data$(System data)\$PP$(User data)\$PP\data
User config$(User config)\$PP$(User config)\$PP\config
System config$(System config)\$PP-
Cache$(Cache)\$PP$(Cache)\$PP\cache
State--

Extra directories

Linux

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
Fonts~/.fonts, $(User/System data)/fontsQt~/.local/share/fonts-
Applications$(User/System data)/applicationsQt--

MacOS

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
Fonts/System/Library/Fonts~/Library/Fonts, /Library/Fonts, /System/Library/Fonts, /Network/Library/Fonts~/Library/Fonts-
Applications/ApplicationsQt--

Windows

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
FontsFontsQt--
ApplicationsRoamingAppData, ProgramsPrograms, CommonPrograms--

Discrepancies

Base directories

MacOS

User configuration
The conflict

directories-rs uses ~/Library/Preferences while all the other implementations use ~/Library/Application support.

Resolution

Looking at Table 1.3 of Apple's Standard Directory Guidelines, it says of ~/Library/Preferences that "You should not create files in this directory yourself. Instead, use the NSUserDefaults class or CFPreferences API to get and set preference values for your app." (wnich I interpret as "don't touch directly"), and of ~/Library/Application Support that "Use this directory to store all app data files except those associated with the user’s documents". Given the intended use of this package is to procure the correct locations to read/write files to, ~/Library/Application Support is thus the more appropriate choice.

System configuration
The conflict

Qt uses ~/Library/Preferences, while Go XDG uses ~/Library/Preferences, /Library/Application Support, and /Library/Preferences. The other implementations do not declare a MacOS system configuration directory.

Resolution

For the aforementioned reasons with User configuration on MacOS, the Preferences folder does not seem appropriate, which leaves /Library/Application Support.

User executables
The conflict

MacOS does not have a standard directory for user executables.

Resolution

Look for the common manually specified "local executable folder" paths (~/.local/bin/, /opt/local/bin) on the path, and if none of them are found fall back on the system executable folder /usr/local/bin.

Runtime
The conflict

MacOS simply has no direct equivalent of the XDG runtime directory. Thus, we must choose which aspect of the runtime directory we think is more important: the transient-ness, or the association with the application. Qt and Go XDG pick the lattter, but Python's platform-dirs picks the latter.

Resolution

Since in the XDG spec the runtime directory is a collection of all application's runtime files which is held in-memory, a temporary directory seems to make the most sense in this regard. However, while the runtime directory's contents are transient, then might not be able to be safely deleted on a whim, which is one of the usual assumptions made about the contents of a temporary directory.

There is no clear option here, but I will prioritise avoiding putting fragile files in a temporary directory, and so we will go with ~/Library/Application Support.

Windows

Roaming vs Local app data
The conflict

Across the data and configuration folders, there is general contention around whether RoamingAppData or AppData should be used. The difference seems to relate to DomainController and ActiveDirectory — simply put data in RoamingAppData will follow the user around, while AppData won't. The idea is that "less essential but potentially large" information goes in AppData.

Resolution

I think configuration should follow the user around, and if data can be stored locally because it's not essential, then that's what the cache is for. So, RoamingAppData will be used for everything but State, Cache, and Runtime.

In there is demand in the future, a local::Bool keyword argument could be added to support both modes of operaton.

Executable files
The conflict

Windows doesn't have anywhere that user executable files are supposed to go.

Resolution

Like with MacOS, check for locations that users seem to use for this purpose which are also on the path, namely ~\bin, RoamingAppData\bin, and AppData\bin. If none of these exist, use the current working directory as at least that way the provided path will be callable in the state at the time.

User directories

No conflicts 🎉.

Project directories

Windows AppData project suffixes

The conflict

Some projects just use AppData\$Project for the data, config, and cache folders, however directories-rs adds suffixes after the project.

Resolution

There's no formally specified structure, and conventions in usage are loose, so we may as well decide on a more structured approach, and use suffix directories.

Extra directories

A collection of different directories

The conflict

Some packages only have one or two Application/Font directories, other have many.

Resolution

Since these will primarily be used for searching, it makes sense to include all valid paths.

  • binhomeWhile XDG_BIN_HOME is not yet standard, it seems like the most likely name to be given to ~/.local/bin (see this issue), and I think it is worth having something rather than nothing.
+Prior Art · BaseDirs.jl

A Survey of other XDG-y packages

The entire point of this package is to handle locations in a fairly standardised way. With this in mind, it seems fairly sensible to survey other notable XDG-y packages and see how them behave. Specifically, we will be looking at the following:

Base directories

Linux

Common NameEnvVarXDG specQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOME~/.local/shareXDG specXDG specXDG specXDG spec
System dataXDG_DATA_DIRS/usr/local/share, /usr/shareXDG specXDG spec~/.local/shareXDG spec
User configXDG_CONFIG_HOME~/.configXDG specXDG specXDG specXDG spec
System configXDG_CONFIG_DIRS/etc/xdgXDG specXDG spec-XDG spec
StateXDG_STATE_HOME~/.local/state-XDG specXDG specXDG spec
User executablesXDG_BIN_HOME [binhome]~/.local/bin--XDG spec-
CacheXDG_CACHE_HOME~/.cacheXDG specXDG specXDG specXDG spec
RuntimeXDG_RUNTIME_DIR/run/user/$UIDXDG specXDG spec-XDG spec

MacOS

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOME~/Library/Application SupportQtQtQt
System dataXDG_DATA_DIRS/Library/Application SupportQt~/Library/Application SupportQt
User configXDG_CONFIG_HOME~/Library/Preferences~/Library/Application SupportGo XDGQt
System configXDG_CONFIG_DIRS~/Library/Preferences~/Library/Preferences, /Library/Application Support, /Library/Preferences--
StateXDG_STATE_HOME-~/Library/Application Support-Go XDG
User executablesXDG_BIN_HOME [binhome]----
CacheXDG_CACHE_HOME~/Library/Caches/ , /Library/CachesQtQtQt
RuntimeXDG_RUNTIME_DIR~/Library/Application SupportQt-~/Library/Caches/TemporaryItems

Windows

Here folder names not beginning with ~ or / refer to Known Folders.

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
User dataXDG_DATA_HOMELocalAppDataQtQtLocalAppData or RoamingAppData
System dataXDG_DATA_DIRSProgramDataRoamingAppData, ProgramDataRoamingAppDataProgramData
User configXDG_CONFIG_HOMELocalAppDataLocalAppDataRoamingAppDataLocalAppData or RoamingAppData
System configXDG_CONFIG_DIRSProgramDataProgramData, RoamingAppData-ProgramData
StateXDG_STATE_HOME-LocalAppData-LocalAppData
User executablesXDG_BIN_HOME [binhome]---
CacheXDG_CACHE_HOMELocalAppData\cacheLocalAppData\cacheLocalAppDataLocalAppData\Cache
RuntimeXDG_RUNTIME_DIR~LocalAppDataGo XDGLocalAppData\Temp

User directories

Linux

Common NameEnvVarXDG specQStandardPathsGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIR~/DesktopXDG specXDG spec--
DownloadXDG_DOWNLOAD_DIR~/DownloadsXDG specXDG spec--
DocumentsXDG_DOCUMENTS_DIR~/DocumentsXDG specXDG spec-XDG spec
MusicXDG_MUSIC_DIR~/MusicXDG specXDG spec--
PicturesXDG_PICTURES_DIR~/PicturesXDG specXDG spec--
VideosXDG_VIDEOS_DIR~/VideosXDG specXDG spec--
TemplatesXDG_TEMPLATES_DIR~/Templates-XDG spec--
PublicXDG_PUBLICSHARE_DIR~/Public-XDG spec--

MacOS

Common NameEnvVarQStandardPathsGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIR~/DesktopQtQt-
DownloadXDG_DOWNLOAD_DIR~/DownloadsQtQt-
DocumentsXDG_DOCUMENTS_DIR~/DocumentQtQtQt
MusicXDG_MUSIC_DIR~/MusicQtQt-
PicturesXDG_PICTURES_DIR~/PicturesQtQt-
VideosXDG_VIDEOS_DIR~/MoviesQtQt-
TemplatesXDG_TEMPLATES_DIR-~/TemplateGo XDG-
PublicXDG_PUBLICSHARE_DIR-~/PublicGo XDG-

Windows

Common NameEnvVarGo XDGRust directories-rsPython platform-dirs
DesktopXDG_DESKTOP_DIRDesktopGo XDG-
DownloadXDG_DOWNLOAD_DIRDownloadsGo XDG-
DocumentsXDG_DOCUMENTS_DIRDocumentsGo XDGGo XDG
MusicXDG_MUSIC_DIRMusicGo XDG-
PicturesXDG_PICTURES_DIRPicturesGo XDG-
VideosXDG_VIDEOS_DIRVideosGo XDG-
TemplatesXDG_TEMPLATES_DIRTemplatesGo XDG-
PublicXDG_PUBLICSHARE_DIRPublicGo XDG-

Project directories

Here $PP will be a stand-in for the project path, according to the conventions of the OS.

Linux

Common NameQStandardPathsRust directories-rs
User data$(User data)/$PP$(User data)/$PP
System data$(System data)/$PP$(User data)/$PP
User config$(User config)/$PP$(User config)/$PP
System config$(System config)/$PP-
Cache$(Cache)/$PP$(Cache)/$PP
State-$(State)/$PP

MacOS

Common NameQStandardPathsRust directories-rs
User data$(User data)/$PP$(User data)/$PP
System data$(System data)/$PP$(User data)/$PP
User config$(User config)/$PP$(User config)/$PP
System config--
Cache$(Cache)/$PP$(Cache)/$PP
State--

Windows

Common NameQStandardPathsRust directories-rs
User data$(User data)\$PP$(User data)\$PP\data
System data$(System data)\$PP$(User data)\$PP\data
User config$(User config)\$PP$(User config)\$PP\config
System config$(System config)\$PP-
Cache$(Cache)\$PP$(Cache)\$PP\cache
State--

Extra directories

Linux

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
Fonts~/.fonts, $(User/System data)/fontsQt~/.local/share/fonts-
Applications$(User/System data)/applicationsQt--

MacOS

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
Fonts/System/Library/Fonts~/Library/Fonts, /Library/Fonts, /System/Library/Fonts, /Network/Library/Fonts~/Library/Fonts-
Applications/ApplicationsQt--

Windows

Common NameQStandardPathsGo XDGRust directories-rsPython platform-dirs
FontsFontsQt--
ApplicationsRoamingAppData, ProgramsPrograms, CommonPrograms--

Discrepancies

Base directories

MacOS

User configuration
The conflict

directories-rs uses ~/Library/Preferences while all the other implementations use ~/Library/Application support.

Resolution

Looking at Table 1.3 of Apple's Standard Directory Guidelines, it says of ~/Library/Preferences that "You should not create files in this directory yourself. Instead, use the NSUserDefaults class or CFPreferences API to get and set preference values for your app." (wnich I interpret as "don't touch directly"), and of ~/Library/Application Support that "Use this directory to store all app data files except those associated with the user’s documents". Given the intended use of this package is to procure the correct locations to read/write files to, ~/Library/Application Support is thus the more appropriate choice.

System configuration
The conflict

Qt uses ~/Library/Preferences, while Go XDG uses ~/Library/Preferences, /Library/Application Support, and /Library/Preferences. The other implementations do not declare a MacOS system configuration directory.

Resolution

For the aforementioned reasons with User configuration on MacOS, the Preferences folder does not seem appropriate, which leaves /Library/Application Support.

User executables
The conflict

MacOS does not have a standard directory for user executables.

Resolution

Look for the common manually specified "local executable folder" paths (~/.local/bin/, /opt/local/bin) on the path, and if none of them are found fall back on the system executable folder /usr/local/bin.

Runtime
The conflict

MacOS simply has no direct equivalent of the XDG runtime directory. Thus, we must choose which aspect of the runtime directory we think is more important: the transient-ness, or the association with the application. Qt and Go XDG pick the lattter, but Python's platform-dirs picks the latter.

Resolution

Since in the XDG spec the runtime directory is a collection of all application's runtime files which is held in-memory, a temporary directory seems to make the most sense in this regard. However, while the runtime directory's contents are transient, then might not be able to be safely deleted on a whim, which is one of the usual assumptions made about the contents of a temporary directory.

There is no clear option here, but I will prioritise avoiding putting fragile files in a temporary directory, and so we will go with ~/Library/Application Support.

Windows

Roaming vs Local app data
The conflict

Across the data and configuration folders, there is general contention around whether RoamingAppData or AppData should be used. The difference seems to relate to DomainController and ActiveDirectory — simply put data in RoamingAppData will follow the user around, while AppData won't. The idea is that "less essential but potentially large" information goes in AppData.

Resolution

I think configuration should follow the user around, and if data can be stored locally because it's not essential, then that's what the cache is for. So, RoamingAppData will be used for everything but State, Cache, and Runtime.

In there is demand in the future, a local::Bool keyword argument could be added to support both modes of operaton.

Executable files
The conflict

Windows doesn't have anywhere that user executable files are supposed to go.

Resolution

Like with MacOS, check for locations that users seem to use for this purpose which are also on the path, namely ~\bin, RoamingAppData\bin, and AppData\bin. If none of these exist, use the current working directory as at least that way the provided path will be callable in the state at the time.

User directories

No conflicts 🎉.

Project directories

Windows AppData project suffixes

The conflict

Some projects just use AppData\$Project for the data, config, and cache folders, however directories-rs adds suffixes after the project.

Resolution

There's no formally specified structure, and conventions in usage are loose, so we may as well decide on a more structured approach, and use suffix directories.

Extra directories

A collection of different directories

The conflict

Some packages only have one or two Application/Font directories, other have many.

Resolution

Since these will primarily be used for searching, it makes sense to include all valid paths.

  • binhomeWhile XDG_BIN_HOME is not yet standard, it seems like the most likely name to be given to ~/.local/bin (see this issue), and I think it is worth having something rather than nothing.
diff --git a/dev/usage/index.html b/dev/usage/index.html index 31fac97..fb72044 100644 --- a/dev/usage/index.html +++ b/dev/usage/index.html @@ -4,7 +4,7 @@ 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:

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:

PlatformProject 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:

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

Example usage

julia> using BaseDirs
+  -> Project

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

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

PlatformProject 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:

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

Example usage

julia> using BaseDirs
 
 julia> BaseDirs.CONFIG_HOME[]
 "/home/tec/.config"
@@ -16,52 +16,52 @@
 "/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

LinuxMacOSWindows
~/.local/share~/Library/ApplicationSupportRoamingAppData
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

LinuxMacOSWindows
/usr/local/share/Library/ApplicationSupportProgramData
/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

LinuxMacOSWindows
~/.local/config~/Library/ApplicationSupportRoamingAppData
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

LinuxMacOSWindows
/etc/xdg/Library/ApplicationSupportProgramData
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

LinuxMacOS*Windows*
~/.local/bin~/.local/bin\bin
/opt/local/binRoamingAppData\bin
/usr/local/binAppData\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

LinuxMacOSWindows
~/.local/state~/Library/ApplicationSupportLocalAppData
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

LinuxMacOSWindows
~/.cache~/Library/CachesLocalAppData\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

LinuxMacOSWindows
/run/user/$UID~/Library/ApplicationSupportLocalAppData
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
+"/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

LinuxMacOSWindows
~/.local/share~/Library/ApplicationSupportRoamingAppData
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

LinuxMacOSWindows
/usr/local/share/Library/ApplicationSupportProgramData
/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

LinuxMacOSWindows
~/.local/config~/Library/ApplicationSupportRoamingAppData
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

LinuxMacOSWindows
/etc/xdg/Library/ApplicationSupportProgramData
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

LinuxMacOS*Windows*
~/.local/bin~/.local/bin\bin
/opt/local/binRoamingAppData\bin
/usr/local/binAppData\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

LinuxMacOSWindows
~/.local/state~/Library/ApplicationSupportLocalAppData
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

LinuxMacOSWindows
~/.cache~/Library/CachesLocalAppData\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

LinuxMacOSWindows
/run/user/$UID~/Library/ApplicationSupportLocalAppData
source

User directories

Other directories

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
+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
+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
+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
+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
+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
+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
+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
+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
+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

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 (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
+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 (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
+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
+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
+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

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 (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
+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 (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
+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
+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

source