storage: RFC

From FreeCAD Documentation
Jump to navigation Jump to search
  1. FreeCAD should honour the XDG Base Directory Specification
    1. $XDG_CONFIG_HOME for configuration files, i.e. most of .FreeCAD
      1. $XDG_CACHE_HOME for any data that can be deleted and regenerated offline, and caches of things which normally require network access at the moment when they are browsed, so most likely .FreeCAD/webdatacache/ and ~/.FreeCAD/AddonManager/Images/
    2. $XDG_DATA_HOME for fonts, icons etc. which are usable by multiple applications. It is the equivalent of /usr/local/share ($XDG_DATA_HOME is ~/.local/share by default). FreeCAD already stores some things related to the Qt online help browser in ~/.local/share/freecad/freecad/freecad.qhc
      1. There are some recommendations about other directories namely …/lib/ (portable libraries) …/lib/<some-arch-id> (arch-specific libraries) and …/bin/ (executable libraries) A few tools (1, 2) use the directories other than share.
      2. $XDG_DATA_DIRS defaults to /usr/local/share:/usr/share
      3. It is unclear what the difference between share and lib is:
        1. This page on says that plug-ins live in /usr/lib/,
        2. this page on says that "The "share" word is used because what is under /usr/share is platform independent, and can be shared among several machines across a network filesystem",
        3. this page at says that ~/.local/lib is for "Static, private vendor data that is compatible with all architectures" and that ~/.local/share is for "Resources shared between multiple packages, such as fonts or artwork.".
      4. The directories other than share are not customisable using env vars.
      5. Macros and mods (currently in ~/.FreeCAD/Macro and ~/.FreeCAD/Mod), when they are installed by the Addon manager, should be in $XDG_DATA_HOME/share or in $XDG_DATA_HOME/lib.
      6. Which one to pick depends on whether we consider these "plug-ins" usable by other tools or whether they are private (which could likely be understood as "FreeCAD-specific"). Branded versions of FreeCAD can share installed macros and mods; and external applications could invoke FreeCAD macros directly (see e.g. how the XternalApps Workbench invokes Inkscape extensions from within FreeCAD, the reverse would also make sense). Also, since ~/.local/share is not customisable, it seems less useful to move things there (maybe it is a recent $XDG_RUNTIME_DIR)
    3. $XDG_DATA_DIRS defaults to /usr/share and is a list of places where fonts, icons etc. are stored. /usr/share/freecad/mod shouldn't be hard-coded based on the prefix (assuming that's the case), instead (or probably in addition to that) a lookup should be done in all the directories listed in this colon-separated variable.
    4. $XDG_DOCUMENTS_DIR as the default location when opening/saving files on a fresh installation (probably already the case, I didn't pay attention; the $PWD is probably an okay choice especially when started from the command-line)
    5. "State" as described on the Debian wiki and in this mailing list message is the kind of small values that an application remembers (window position, size of the Tree View, recently used files) which can usually change often (so it is not a good candidate for storing alongside the configuration in a VCS, or at least not for storing in the same repository), and tends to be created without the user making conscious choices or without realising that these are "settings" (as opposed to actual configuration, which happens e.g. in the preferences editor and involved clicking on checkboxes and making actual choices). There is no standard location for state, and no XDG variable to customise that location; however it seems like a good idea to keep that information in a separate sub-directory of the FreeCAD configuration directory. Currently some of these details are stored in separate files (e.g. cookies in .FreeCAD/cookies, the window size in .config/FreeCAD/FreeCAD.conf instead of .FreeCAD/…
  2. FreeCAD should honour the $HOME variable
  3. When FreeCAD is started for the first time, it should not create any directories or files in the user's home folder, unless some customisation or state change actually happens. Rationale: if the user is just trying FreeCAD and simply creates a new document, then exits without saving, they do not expect this to cause any change in the "settings" or "configuration" of their machine. Since FreeCAD has a start page, any "first run" wizard or tip can be integrated in the start page and be displayed every time. This has the advantage that the software operates in a more stateless way: instead of switching between different states, unbeknownst to the user, the software looks and feels like it was started from the first time every time, unless the user actively configures something (e.g. through a start page customisation dialog). State (like the window size or toolbar positions or browser history) can be saved, but only if the user does an action that changes the default state (toggles maximisation of the main window, moves a toolbar, or visits a browser page other than the start page).

Python macros and mods can use some of these paths via the following API, which might need to be extended:

  • App.getHelpDir()
  • App.getResourceDir()
  • App.getUserAppDataDir()
  • App.getUserMacroDir()