XCSoar data directory

XCSoar stores user data (profiles, waypoints, logs, downloaded weather, and similar files) in a data root directory. The application refers to this location as %LOCAL_PATH% in profile settings.

This chapter describes where that directory lives on each platform and how files are organised inside it. The layout is implemented by Repository/FileType.cpp (GetFileTypeDefaultDir()) and DataFileLayout.cpp.

Typed layout (XCSoar 7.45+)

Starting with XCSoar 7.45, the typed subdirectory layout described below is the standard for all new and upgraded installations. Earlier versions stored most files directly in the data root (a “flat” layout).

Automatic migration: when you upgrade from an older release, XCSoar moves recognised files from the data root into the matching subdirectories on the first startup after the upgrade. Profile paths that pointed at the old locations are updated automatically. No manual file shuffling is required.

Migration marker: after migration completes (or when there is nothing to move), XCSoar creates an empty marker file .xcsoar-subdir-layout-v1 in the data root (DataLayoutMigration.cpp). While this file exists, the migration is not run again. If every planned move fails (for example because a file with the same name already exists in the destination subdirectory), the marker is not written and XCSoar will retry on the next startup.

Legacy flat files that were not moved are still found through the ResolveTypedDataFilePath() fallback (see Profile paths below).

Data root location

XCSoar may use more than one data root (for example a removable SD card plus internal storage). The primary data root is the first entry in the search list and is where new files are written.

Platform

Typical path

Notes

Linux / Unix

~/.xcsoar/

Hidden directory in the user’s home folder

Windows

%LOCALAPPDATA%\XCSoarData\

Also checks XCSoarData next to XCSoar.exe and under My Documents

macOS (desktop)

~/XCSoarData/

Visible folder in the home directory

iOS

~/Documents/XCSoarData/

Accessible via iTunes / Files when file sharing is enabled

Android

App-specific external storage, or legacy /sdcard/XCSoarData/

Upgrades keep the old location when xcsoar.log is found there

Kobo

/mnt/onboard/XCSoarData/

On-board user partition

System-wide (Linux)

/etc/xcsoar/

Optional global configuration, read after the user directory

Rebranded builds use the product name from build/product.mk instead of XCSoar / XCSoarData; see Rebranding XCSoar.

Directory layout overview

Since XCSoar 7.45, most user files live in typed subdirectories under the data root (see Typed layout (XCSoar 7.45+)). Repository downloads, the file manager, and profile path resolution all use the FileType API (Repository/FileType.hpp).

<data-root>/
├── airspace/              OpenAir, TNP, SUA files
├── cache/                 Repository index, NOTAM cache, weather tiles, …
│   ├── pc_met/            Flugwetter (PCMet) overlay images
│   ├── cupx/              Temporary CUPX extraction
│   └── weather/
│       ├── edl/mbtiles/   EDL forecast MBTiles cache
│       ├── rasp/          RASP forecast files (*-rasp*.dat)
│       └── xctherm/<model>/  XCTherm GeoJSON slice cache
├── checklists/            Checklist files (*.xcc, xcsoar-checklist.txt)
├── flarm/                 FLARMNet database and FLARM message data
├── input/                 Custom input event files (*.xci)
├── logs/                  IGC and NMEA flight logs
├── lua/                   Lua scripts (*.lua); lua/lib/ for libraries
├── maps/                  Terrain files (*.xcm, *.lkm)
├── profiles/              Profile files (*.prf)
│   └── planes/            Plane polar files (*.xcp)
├── tasks/                 Saved task files
├── waypoints/             Waypoint files (*.cup, *.dat, …)
│   └── details/           Waypoint detail text files
├── weather/
│   └── overlay/           User-supplied GeoTIFF overlays (*.tif)
├── kobo/                  Kobo-specific helper files (Kobo only)
├── xcsoar.log             Application log (data root)
├── xcsoar-old.log         Rotated log
├── xcsoar-startup.log     Early startup log (Android)
├── xcsoar-marks.txt       User map markers
└── .xcsoar-subdir-layout-v1
                           Migration marker (created after layout upgrade)

Typed subdirectories

The following table lists each managed subdirectory, the FileType value that selects it, and the filename patterns recognised by GetFileTypePatterns().

Subdirectory

FileType

Filename patterns

airspace/

AIRSPACE

*.openair, *.txt, *.air, *.sua

waypoints/

WAYPOINT

*.dat, *.xcw, *.cup, *.cupx, *.wpz, *.wpt

waypoints/details/

WAYPOINTDETAILS

*.txt (content sniffing distinguishes waypoint details from airspace)

maps/

MAP

*.xcm, *.lkm

flarm/

FLARMNET, FLARMDB

*.fln, xcsoar-flarm.txt, flarm-msg-data.csv

tasks/

TASK

*.tsk, *.cup, *.igc

checklists/

CHECKLIST

*.xcc, xcsoar-checklist.txt

logs/

IGC, NMEA

*.igc, *.nmea

profiles/

PROFILE

*.prf (including default.prf)

profiles/planes/

PLANE

*.xcp

input/

XCI

*.xci

lua/

LUA

*.lua; put libraries in lua/lib/ for require

cache/

(by filename)

repository, user_repository_*, notams.json

Ambiguous *.txt files in the data root are classified by reading their contents (DataFileLayout.cpp). OpenAir and TNP airspace files go to airspace/; waypoint detail files with attachment sections go to waypoints/details/.

Cache directory

cache/ holds data that XCSoar downloads or regenerates and that should not be edited manually. The whole cache/ tree is excluded from data backups (Dialogs/DataManagement/BackupRestorePanel.cpp).

  • repository — main file repository index

  • user_repository_<name> — additional user-defined repository files

  • notams.json — cached NOTAM data

  • pc_met/ — downloaded Flugwetter (PCMet) overlay images

  • cupx/ — temporary files while opening CUPX waypoints

  • weather/rasp/ — RASP forecast files (*-rasp*.dat, for example xcsoar-rasp.dat)

  • weather/edl/mbtiles/ — downloaded EDL forecast MBTiles tiles

  • weather/xctherm/<model>/ — XCTherm GeoJSON slice cache files

Downloaded weather data (RASP, EDL, XCTherm) is stored here rather than under the top-level weather/ directory, so it is excluded from backups together with other cache data. Earlier 7.45 development builds used weather/rasp/, weather/edl/, and weather/xctherm/ directly in the data root; those paths may still be read for backwards compatibility until the cache move is complete.

Legacy copies of repository and notams.json in the data root or in a top-level repository/ folder are still resolved for backwards compatibility (DataFilePath.cpp).

Weather data

The top-level weather/ directory is for user-provided overlay images only:

  • GeoTIFF overlays — weather/overlay/ (*.tif, *.tiff), listed in the Weather dialog (Dialogs/Weather/MapOverlayWidget.cpp).

Repository downloads and other fetched forecast data live under cache/weather/ (see cache-directory):

  • RASP — cache/weather/rasp/ (Weather/Rasp/). The default filename is xcsoar-rasp.dat.

  • EDL — cache/weather/edl/mbtiles/ (Weather/EDL/TileStore.cpp). Filenames encode forecast time and isobar level.

  • XCTherm — cache/weather/xctherm/<model>/ (Weather/xctherm/XCThermAPI.cpp). Each file is named <parameter>_<utc>.xctcache.

Files in the data root

Some paths intentionally remain at the top level of the data root:

  • Log files — xcsoar.log, xcsoar-old.log, xcsoar-startup.log, xcsoar-persist.log (LogFile.cpp)

  • Markers — xcsoar-marks.txt (Markers/Markers.cpp)

  • Migration marker — .xcsoar-subdir-layout-v1 — empty file written after the 7.45 layout migration; see Typed layout (XCSoar 7.45+)

Kobo builds additionally use kobo/ for power-off text, Wi-Fi auto-on flags, OTG host state, and user scripts.

Profile paths

Profile settings store file references as %LOCAL_PATH%\<relative-path> (LocalPath.cpp). After migration, paths point at the typed subdirectories (for example %LOCAL_PATH%\waypoints\waypoints.cup).

ResolveTypedDataFilePath() and ResolveLocalDataFile() (DataFilePath.cpp) look up files in the typed subdirectory first, then fall back to the data root for legacy flat layouts.

Upgrading from a flat layout

This section summarises the automatic migration introduced in 7.45; see Typed layout (XCSoar 7.45+) for the marker file and when migration runs.

On first start after upgrading to the typed layout, XCSoar scans the data root and moves recognised files into the matching subdirectories (DataLayoutMigration.cpp). A file is moved only when:

  • its type can be determined from the filename (or content, for ambiguous *.txt files), and

  • no file with the same name already exists at the destination.

After at least one successful move, XCSoar writes .xcsoar-subdir-layout-v1 and updates profile references to the new paths. If there was nothing to migrate, the marker is still created so the scan is not repeated on every startup. Files that cannot be classified (or would overwrite an existing destination file) are left in the data root.

The file manager and data-management tools understand the typed layout: downloads are stored in the correct subdirectory, and files can be transferred between storage volumes with paths rewritten automatically.