Package 'rappdirs'

Title: Application Directories: Determine Where to Save Data, Caches, and Logs
Description: An easy way to determine which directories on the users computer you should use to save data, caches and logs. A port of Python's 'Appdirs' (<https://github.com/ActiveState/appdirs>) to R.
Authors: Hadley Wickham [trl, cre, cph], Sridhar Ratnakumar [aut], Trent Mick [aut], ActiveState [cph] (R/appdir.r, R/cache.r, R/data.r, R/log.r translated from appdirs), Eddy Petrisor [ctb], Trevor Davis [trl, aut], Gabor Csardi [ctb], Gregory Jefferis [ctb], Posit Software, PBC [cph, fnd]
Maintainer: Hadley Wickham <[email protected]>
License: MIT + file LICENSE
Version: 0.3.3.9000
Built: 2024-05-21 09:24:41 UTC
Source: https://github.com/r-lib/rappdirs

Help Index


Path to shared data/config directories

Description

site_data_dir returns full path to the user-shared data dir for this application. site_config_dir returns full path to the user-specific configuration directory for this application which returns the same path as site data directory in Windows and Mac but a different one for Unix. Typical user-shared data directories are:

Usage

site_data_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  multipath = FALSE,
  expand = TRUE,
  os = NULL
)

site_config_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  multipath = FALSE,
  expand = TRUE,
  os = NULL
)

Arguments

appname

is the name of application. If NULL, just the system directory is returned.

appauthor

(only required and used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname.

version

is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be "<major>.<minor>". Only applied when appname is not NULL.

multipath

is an optional parameter only applicable to *nix which indicates that the entire list of data dirs should be returned By default, the first directory is returned

expand

If TRUE (the default) will expand the R_LIBS specifiers with their equivalents. See R_LIBS() for list of all possibly specifiers.

os

Operating system whose conventions are used to construct the requested directory. Possible values are "win", "mac", "unix". If NULL (the default) then the current OS will be used.

Details

  • Mac OS X: ⁠/Library/Application Support/<AppName>⁠

  • Unix: ⁠/usr/local/share:/usr/share/⁠

  • Win XP: ⁠C:\\Documents and Settings\\All Users\\Application Data\\<AppAuthor>\\<AppName>⁠

  • Vista: (Fail! ⁠C:\\ProgramData⁠ is a hidden system directory on Vista.)

  • Win 7: ⁠C:\\ProgramData\\<AppAuthor>\\<AppName>⁠. Hidden, but writeable on Win 7.

Unix also specifies a separate location for user-shared configuration data in $XDG_CONFIG_DIRS.

  • Unix: ⁠/etc/xdg/<AppName>⁠, in $XDG_CONFIG_HOME if defined

For Unix, this returns the first default. Set the multipath=TRUE to guarantee returning all directories.

Warning

Do not use this on Windows. See the note above for why.


Path to user cache directory

Description

This functions uses R_USER_CACHE_DIR if set. Otherwise, they follow platform conventions. Typical user cache directories are:

  • Mac OS X: ⁠~/Library/Caches/<AppName>⁠

  • Linux: ⁠~/.cache/<AppName>⁠

  • Win XP: ⁠C:\\Documents and Settings\\<username>\\Local Settings\\Application Data\\<AppAuthor>\\<AppName>\\Cache⁠

  • Vista: ⁠C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>\\Cache⁠

Usage

user_cache_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  opinion = TRUE,
  expand = TRUE,
  os = NULL
)

Arguments

appname

is the name of application. If NULL, just the system directory is returned.

appauthor

(only required and used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname.

version

is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be "<major>.<minor>". Only applied when appname is not NULL.

opinion

(logical) Use FALSE to disable the appending of Cache on Windows. See discussion below.

expand

If TRUE (the default) will expand the R_LIBS specifiers with their equivalents. See R_LIBS() for list of all possibly specifiers.

os

Operating system whose conventions are used to construct the requested directory. Possible values are "win", "mac", "unix". If NULL (the default) then the current OS will be used.

Opinion

On Windows the only suggestion in the MSDN docs is that local settings go in the CSIDL_LOCAL_APPDATA directory. This is identical to the non-roaming app data dir (i.e. user_data_dir()). But apps typically put cache data somewhere under this directory so user_cache_dir() appends Cache to the CSIDL_LOCAL_APPDATA value, unless opinion = FALSE.

See Also

tempdir() for a non-persistent temporary directory.

Examples

user_cache_dir("rappdirs")

Path to user config/data directories

Description

user_data_dir() returns path to the user-specific data directory and user_config_dir() returns full path to the user-specific configuration directory. These are the same on Windows and Mac but different on Linux.

These functions first use R_USER_DATA_DIR and R_USER_CONFIG_DIR if set. Otherwise, they follow platform conventions. Typical user config and data directories are:

  • Mac OS X: ⁠~/Library/Application Support/<AppName>⁠

  • Win XP (not roaming): ⁠C:\\Documents and Settings\\<username>\\Data\\<AppAuthor>\\<AppName>⁠

  • Win XP (roaming): ⁠C:\\Documents and Settings\\<username>\\Local Settings\\Data\\<AppAuthor>\\<AppName>⁠

  • Win 7 (not roaming): ⁠C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>⁠

  • Win 7 (roaming): ⁠C:\\Users\\<username>\\AppData\\Roaming\\<AppAuthor>\\<AppName>⁠

Only Linux makes the distinction between config and data:

  • Data: ⁠~/.local/share/<AppName>⁠

  • Config: ⁠~/.config/<AppName>⁠

Usage

user_data_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  roaming = FALSE,
  expand = TRUE,
  os = NULL
)

user_config_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  roaming = TRUE,
  expand = TRUE,
  os = NULL
)

Arguments

appname

is the name of application. If NULL, just the system directory is returned.

appauthor

(only required and used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname.

version

is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be "<major>.<minor>". Only applied when appname is not NULL.

roaming

(logical, default FALSE) can be set TRUE to use the Windows roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be sync'd on login. See <https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-vista/cc766489(v=ws.10). for a discussion of issues.

expand

If TRUE (the default) will expand the R_LIBS specifiers with their equivalents. See R_LIBS() for list of all possibly specifiers.

os

Operating system whose conventions are used to construct the requested directory. Possible values are "win", "mac", "unix". If NULL (the default) then the current OS will be used.

Examples

user_data_dir("rappdirs")

user_config_dir("rappdirs", roaming = TRUE, os = "win")
user_config_dir("rappdirs", roaming = FALSE, os = "win")
user_config_dir("rappdirs", os = "unix")
user_config_dir("rappdirs", os = "mac")
user_config_dir("rappdirs", version = "%p-platform/%v")

Path to user log directory

Description

Typical user cache directories are:

Usage

user_log_dir(
  appname = NULL,
  appauthor = appname,
  version = NULL,
  opinion = TRUE,
  expand = TRUE,
  os = NULL
)

Arguments

appname

is the name of application. If NULL, just the system directory is returned.

appauthor

(only required and used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname.

version

is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be "<major>.<minor>". Only applied when appname is not NULL.

opinion

(logical) can be FALSE to disable the appending of ‘Logs’ to the base app data dir for Windows, and ‘log’ to the base cache dir for Unix. See discussion below.

expand

If TRUE (the default) will expand the R_LIBS specifiers with their equivalents. See R_LIBS() for list of all possibly specifiers.

os

Operating system whose conventions are used to construct the requested directory. Possible values are "win", "mac", "unix". If NULL (the default) then the current OS will be used.

Details

  • Mac OS X: ‘~/Library/Logs/<AppName>

  • Unix: ‘~/.cache/<AppName>/log’, or under \env$XDG_CACHE_HOME if defined

  • Win XP: ‘C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Logs

  • Vista: ‘C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs

On Windows the only suggestion in the MSDN docs is that local settings go in the CSIDL_LOCAL_APPDATA directory.

Opinion

This function appends ‘Logs’ to the CSIDL_LOCAL_APPDATA value for Windows and appends ‘log’ to the user cache dir for Unix. This can be disabled with the opinion = FALSE option.

Examples

user_log_dir()