<type>documentation</type>
<domain>intro</domain>
<id>user-settings-dir</id>
<title>Settings Directory</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

The first time you run Wing, it will create your ``Settings Directory``
automatically. This directory is used to store your license, preferences,
default project, history, and other files used internally by Wing.  It
also contains any user-defined snippets, scripts, display theme color palettes, syntax colors,
file sets, and shared perspectives.

Wing cannot run without this directory. If it cannot be created, Wing will exit.

The settings directory is created in a location appropriate to your
operating system.  That location is listed as your ``Settings Directory``
in the `About Box <script:about_application>`__ accessible from the ``Help`` menu.

On Windows the settings directory is called ``~~WINDOWS_USER_DIR~~`` and is placed
within the per-user application data directory.  For Windows running on ``c:`` 
with an English localization the location is::

  c:\Users\${username}\AppData\Roaming\~~WINDOWS_USER_DIR~~
  
~~~if WEBSITE:
In Wing Personal the settings directory is instead named ``Wing Personal ~~MAJOR_VERSION~~``
and in Wing 101 it is called ``Wing 101 ~~MAJOR_VERSION~~``.
~~~

On Linux and macOS the settings directory is a sub-directory of your
home directory::
  
  ~~POSIX_USER_DIR~~ 
  
~~~if WEBSITE:
In Wing Personal this directory is instead called ``.wing-personal6`` and in
Wing 101 it is called ``.wing-101-6``.
~~~

**Cache Directory**

Wing also creates a Cache Directory that contains the source analysis caches,
auto-save directory, and a few other things.  This directory is also listed
in Wing's `About box <script:about_application>`__, accessed from the ``Help``
menu.

On Windows, the cache directory is located in the ``AppData\Local`` area.  
On Linux, it is ``~/.cache/~~POSIX_CACHE_DIR~~`` and on macOS, it can be found 
with the symbolic link ``~~POSIX_USER_DIR~~/cache-dir-symlink``.

~~~if WEBSITE:
In Wing Personal, this directory is instead called ``wingpersonal6`` and in
Wing 101 it is called ``wing101-6``.
~~~

**Overriding Settings and Cache Directories**

The default location of the settings directory can be changed by passing
``--settings=fullpath`` on the command line, where ``fullpath`` is the 
full path of the directory to use.  If the directory does not exist
it will be created only if its parent directory exists.  Otherwise, Wing
falls back to using the default location for the settings directory.

Similarly, the default location of the cache directory can be changed with
``--cache=fullpath``.

**Shared Settings Directory**

Another way to override the default settings directory is to create a
directory named ``user-settings`` inside of the Wing installation directory.
When this is present, Wing will use it instead of the default location.

Creating this directory allows settings to move with Wing if your installation
is on a portable drive, or to be shared among multiple users that 
log into the same machine.  Permissions on the directory need to allow read 
and write for all users that will be using Wing.

This is not recommended if multiple users log into the same machine concurrently 
because settings changed by one user will be overwritten by another user without
any notice, and the default project file will be locked if opened by multiple users.
