lensfun: How database files are found and loaded

lensfun 0.3.95.0

How database files are found and loaded

The database files could be loaded in two ways:

1. Call lfDatabase::Load(const char *) to load single files. If the given path points to a folder instead of a file, all included XML files will be parsed. If the same object is defined in multiple files, or lfDatabase::Load(const char *) is called several times for different paths, later definitions override earlier definitions.
2. Call lfDatabase::Load() with no parameters. This will try to load the database from several standardized locations. It also detects updated database versions which where downloaded with the lensfun-update-data tool. A user can override system-wide lens profiles by placing appropriately formatted XML files in its home directory. This method should be preferred if Lensfun is installed system-wide (typically only for Linux distributions with package managers).

# Pre-defined database locations

Lensfun has four pre-defined database locations which are available from the following static class members:

1. lfDatabase::SystemUpdatesLocation
2. lfDatabase::SystemLocation
3. lfDatabase::UserUpdatesLocation
4. lfDatabase::UserLocation

When lfDatabase::Load() is called without arguments, it first searches in lfDatabase::SystemLocation, lfDatabase::SystemUpdatesLocation and lfDatabase::UserUpdatesLocation. Only the folder with the newest database will be loaded, finally. The age of the database is determined based on the `timestamp.txt` file found in the database folder. It contains the UNIX time stamp of the last Git commit, hence a higher number identifies a more recent database.

Afterwards, lfDatabase::UserLocation is loaded without considering a `timestamp.txt`. This means that profiles in lfDatabase::UserLocation will always have the highest priority and will overwrite previously loaded profiles with the same name.

## Linux, UNIX and Mac OS X

The system-wide database folders can be configured at compile time and are preset by the `GNUInstallDirs` CMake Module.

lfDatabase::SystemLocation defaults to `${CMAKE_INSTALL_DATAROOTDIR}/lensfun/version_x`, where x denotes the database format version (Database format versions).
On Linux this is typically `/usr/share/lensfun/version_1` or similar.

lfDatabase::SystemUpdatesLocation defaults to `${CMAKE_INSTALL_LOCALSTATEDIR}/lib/lensfun-updates/version_x`, where x denotes the database format version (Database format versions).
On Linux this is typically `/var/lib/lensfun-updated/version_1` or similar.

The user folders are set at run time based on the current user name and home directory.

lfDatabase::UserLocation is at `~/.local/share/lensfun/updates/version_x`, where x denotes the database format version (Database format versions).

lfDatabase::UserLocation is at `~/.local/share/lensfun`.

## Windows

As `GNUInstallDirs` CMake Module does not create any meaningful output on Windows systems, `${CMAKE_INSTALL_DATAROOTDIR}` will be preset by the `%ALLUSERSPROFILE%` environment variable.

lfDatabase::SystemLocation defaults to `${CMAKE_INSTALL_DATAROOTDIR}/Lensfun/version_x`, where x denotes the database format version (Database format versions).
This is typically `C:/ProgramData/lensfun/version_1` or similar.

lfDatabase::SystemUpdatesLocation defaults to `${CMAKE_INSTALL_DATAROOTDIR}/Lensfun-updates/version_x`, where x denotes the database format version (Database format versions).
This is typically `C:/ProgramData/lensfun-updates/version_1` or similar.

The user folders are set at run time based on the current user name and home directory.

lfDatabase::UserLocation is at `%USERSPROFILE%/AppData/Local/lensfun/updates/version_x`, where x denotes the database format version (Database format versions).

lfDatabase::UserLocation is at `%USERSPROFILE%/AppData/Local/lensfun`.