An application typically manages a specific set of directories and files. The base directories can be categorized by the following table:

However, not all applications will actually use or require all of these directories.

Mapping to the (User) Filesystem

This section describes strategies to implement the defined base directories.

Application Identity

All platforms need to identify an application in one way or the other. This identification can then be used to derive directory names.

Linux and/or Microsoft Windows may use the plain application name, macOS requires a more sophisticated Bundle ID. This bundle ID consists out of the

• reversed domain, e.g. com.github.bvfnbk and the
• name of the application, e.g. ApplicationName

which is concatenated to

com.github.bvfnbk.ApplicationName

and is used for application-specific directory names and for configuration files (e.g. com.github.bvfnbk.ApplicationName.plist)

Single Directory for All

The idea is to put all application directories into a single directory. This actually is a reasonable strategy on all platforms lacking a specification of standard user directories or for simplification purposes.

Please note: In the most generic use case, this may be any directory in the users home directory. This directory is usually hidden on linux platforms, e.g.

~/.${applicationName}/

For linux, the following table defines one possible strategy to map the application directories

This is a simple example naming strategy, loosely following the filesystem hierarchy standard (very loosely…). The actual directory names like etc/ etc. should be configurable.

Windows

There is no specific directory structure defined for user applications. It may use the Single Directory for All strategy as previously defined. However, there are recommendations on where to put this kind of directory.

Windows defines the AppData directory for each user to contain the user application data. This directory can be found at

C:\Users\${username}\AppData\

By default, there are the following directories to be found here:

C:\Users\${username}\AppData\Local
C:\Users\${username}\AppData\LocalLow
C:\Users\${username}\AppData\Roaming

Please note:

• The Roaming application data directory is for roaming user profiles, i.e. users whose PCs are connected to a domain and their profiles are loaded from the domain controller. This way, important settings could be shared across different computers if all are part of the same domain.
• LocalLow is for access-restricted applications, e.g. for a web browser in protected/safe mode which are not able to access the Local directory.
• Local is the place to put application specific files by default.

Linux (XDG)

The XDG base directory specification defines the following environment variables and directories (amongst others):

Please note: There is a XDG_RUNTIME_DIR which is meant for runtime and other files. The specification puts certain requirements onto this directory, e.g. it must be created when the user logs in and removed when the user logs out etc. which qualifies it for highly volatile files only.

The defined application directories can therefore be mapped to

macOS

The most important directories for an application are

(Left out, but mentioned here for the sake of completeness: Desktop/, Documents/, Downloads/, Movies/, Music/, Pictures/, Public/, Sites/)

The Library/ directory is the main directory of interest, containing

Please note: The Apple File System Programming Guide actually discourages the direct creation of configuration files in the Preferences/ directory.

The proposed application directories can therefore be mapped to

There is no “true” directory for temporary files. One has to classify the type of (temporary) file and eventually put the files into the Cache directory. The $TMPDIR points to a generated directory, e.g. /var/folders/cr/1zh7581j0vxfjqvpskdv1kvc0000gn/T/ which may be wiped after restart (please note that this directory is used by the JVM as well; cf. the system property java.io.tmpdir).

Outlook

An application developer may require more control over the concrete locations of each application directory, e.g. the developer may want to move some directories to a network share but leave others at their local counterparts.

Please note: On Microsoft Windows it may be useful to separate domain-specific (generic) configuration from host-specific configuration and store those files in the AppData/Roaming and/or AppData/Local directory. This is especially true for files which may be too large to be stored on a network drive (e.g. caches etc.).

Resources

• Linux
  • Filesystem Hierarchy Standard https://wiki.linuxfoundation.org/lsb/fhs
  • XDG Base Directory Specification https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• Apple Filesystem Programming Guide
  • https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html
  • https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html

• Microsoft Windows User Directory Structure (URL???)