45

I am planning to develop a cross-platform script. On Linux and other operating systems, it will store configuration in XDG_CONFIG_HOME and data files (specifically, downloaded plugins) in XDG_DATA_HOME. On Windows, it will use APPDATA for both (unless someone has a better idea). However, what would be the proper thing to do on Mac OS X?

On my first glance through a handy Macbook's ~/Library directory, I saw Preferences and Application Support folders. I was originally planning to use those, but Preferences seems to just contain plists with reverse domain names like com.apple.foo.bar.baz.plist, and every folder in Application Support corresponds to a bundle in /Applications, so I'm not sure how well the system would react to files that don't match its standards. Storing them directly in ~/Library might be an option, but I don't want to pollute it with a stray myscript.conf file if there's a better place for it.

Where should I store these files? (And please don't say just ~/.myscript. I know it's the Unix tradition, but it annoys me to see random dotfiles in the home directory.)

hippietrail
  • 15,848
  • 18
  • 99
  • 158
LeafStorm
  • 3,057
  • 4
  • 24
  • 28
  • 15
    If it's a command line tool, or otherwise used by developers, *please please please* just use the XDG directories. Or at least use them if they exist, even if you fall back to `~/Library` as a default instead of `~/.config` et al. – OJFord Oct 08 '16 at 21:02
  • 1
    Wouldn’t you want command-line tools and scripts separate from macOS apps (I presume obj-c and swift have their source for getting this information) so rather than ~/Library use ~./config ~/local ~/.cache ? The only thing I haven't worked out is if those tools are shared between multiple user if shared data should be under /usr/local/share. XDG doest seem to distinguish user and system options. – AndrewC Oct 19 '22 at 19:01

4 Answers4

54

Comparing Apple's documentation for the various paths to the XDG Base Directory specifications approximates to the following locations:

  • XDG_CONFIG_HOME ▶︎ ~/Library/Preferences/
  • XDG_DATA_HOME ▶︎ ~/Library/
  • XDG_CACHE_HOME ▶︎ ~/Library/Caches/

Mapping XDG Base Directory Specification locations for "My App" on Mac OS X could look like this:

  • XDG_CONFIG_HOME ▶︎ ~/Library/Preferences/name.often.with.domain.myapp.plist
  • XDG_DATA_HOME ▶︎ ~/Library/My App/
  • XDG_CACHE_HOME ▶︎ ~/Library/Caches/My App/

These mappings seem pretty reasonable but they aren't exact. Some kinds of cache or data may be appropriate for ~/Library/Application Support/My App, and other may be best in the temp locations or the App bundle. All of it is by convention and the same reasons for using the best XDG_ locations apply to using the best locations on the Mac OS X system.

Your annoyance at ~/.myscript is in line with Apple's guidelines: "Don't pollute user space".

References:

fjarlq
  • 2,419
  • 1
  • 16
  • 10
jla
  • 6,904
  • 2
  • 36
  • 34
  • 3
    XDG_*_HOME aren't app-specific — your examples should probably read "XDG_CONFIG_HOME -> ~/Library/Preferences/", "XDG_DATA_HOME -> ~/Library/", & "XDG_CACHE_HOME -> ~/Library/Caches/". (Your post was helpful though! I'm just providing this minor correction for posterity) – Josh Tilles Jul 22 '13 at 14:38
  • The examples were locations for "My App". I've added a generic mapping to the answer that shows the non app-specific locations. Thanks. – jla Jul 26 '13 at 18:16
  • Links seem to be outdated, was it something like this: https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1 – Jan Rüegg May 26 '17 at 12:37
  • 1
    Link update: [Mac OS X Reference Library: Important Java Directories on Mac OS X](https://developer.apple.com/library/content/qa/qa1170/_index.html) – Max Pole Aug 02 '17 at 11:10
  • 1
    I dont think there is really a standard for non-gui under macOS. I would be more inclined to keep command-line and scripts in accordance to UNIX/LINUX ~/.cache ~./config ~local seem to have become favourites. macOS applications have there own specification ~/Library for example Xcode, objective-c and swift. – AndrewC Oct 19 '22 at 19:08
23

I agree with OJFord's comment: if you are writing a script (I think this applies to all CLI-only application), simply follow the XDG Base Directory would be better.

Rationales:

  1. Names in XDG_CONFIG_HOME are typically small-case bare-names like git; the ones in ~/Library/Preferences/ are typically files named with reverse domain name notation like com.apple.AppStore.plist, or directories named in title case like Blackmagic Design.
  2. GUI applications have been following macOS conventions when they are placed in /Applications. You don't place your script in /Applications; you place them in UNIX-specific directorys. Better to be consistent.
  3. ~/Library/Preferences/ is full of .plists. No cross-platform script that I know is using property lists.
  4. Users may want to sync cross-platform configuration and macOS-only one separately.

For example, Git places their config file in XDG_CONFIG_HOME/git/config, not in ~/Library/Preferences/Git/config. Makes sense to me.

note

I made the point only for configuration files ($XDG_CONFIG_HOME) and data files ($XDG_DATA_HOME); for cache files it gets subtle. According to How-To Geek, ~/Library/Caches directory is excluded from Time Machine by default. I don’t care about cache folder since I back up neither directories anyway; but for ones who care, I recommend them to link ~/.cache to somewhere in the default cache folder, such as:

cd ~; mv .cache ~/Library/Caches/XDG-cache; ln -s ~/Library/Caches/XDG-cache .cache
Franklin Yu
  • 8,920
  • 6
  • 43
  • 57
  • 2
    Could not agree more. I hope more scripts and CLI programs adopt XDG across all *nix platforms. – Kansha Oct 15 '18 at 19:16
7

I would use ~/Library/Application Support/script_name/. The subdirectories inside Application Support are used conventionally by various apps, including Apple's own softwares. But it's not enforced by the OS and not tied to apps inside /Applications. So you're perfectly free to create your own directory in it.

For the directory structure of OS X in general, see this Apple document.

Yuji
  • 34,103
  • 3
  • 70
  • 88
  • Okay, cool. Is this suitable for configuration as well, or just data files? – LeafStorm Jul 31 '10 at 17:34
  • Both are fine. I added to the answer an official document as a reference. – Yuji Aug 01 '10 at 17:55
  • 4
    Link seems to be outdated, maybe this one: https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1 – Jan Rüegg May 26 '17 at 12:37
3

Here are the choices made by the os package in golang:

  • XDG_CACHE_HOME → $HOME/Library/Caches

  • XDG_CONFIG_HOME → $HOME/Library/Application Support

Damien L
  • 161
  • 6