File Structure

Basically, a workspace contains following entries:

workspace-root/
    ├── .librepcb-workspace
    ├── projects/
    └── data/
        ├── .librepcb-data
        ├── settings.lp
        └── libraries/
            ├── local/
            └── remote/

.librepcb-workspace

This file indicates that the directory is a LibrePCB workspace and also contains the file format version. See File Format Versioning for more information about LibrePCB's file format versioning system. Because the workspace is intended to be forward compatible (i.e. should be usable with all future LibrePCB releases), the workspace file format should always stay at version 0.1.

projects/

This is the default location where all newly created projects are stored. The user can organize his projects in an arbitrary, hierarchical system inside that directory. But of course it's also possible to store projects outside this directory.

Each project is represented by a directory, see its file structure documentation for details.

data/

All the settings and libraries of the workspace are stored within this directory.

Important: There can exist several data directories with exactly the same purpose and the same organization, just with different names. If a directory with the name v followed by the application's file format version number (e.g. v0.1) exists, this directory will be used instead of the data directory. See Upgrade workspace to newer application version and Downgrade workspace to older application version for details.

data/.librepcb-data

Contains the file format of the data directory, to determine whether the contained files are compatible with the application version. If this version is older, the contained files need to be upgraded to the latest file format. If it is newer, the data directory will not be accessed because it's not compatible.

Note: This file didn't exist in file format 0.1, so the absence of that file is considered as file format 0.1.

data/settings.lp

This file contains workspace settings (selected language/locale, measurement unit, ...). See librepcb::WorkspaceSettings.

data/libraries/

Here are all libraries located, split up into two subdirectories. By the way, all of these libraries together are sometimes referred as the workspace library.

data/libraries/local/

In this directory are all regular, writable libraries located. For example if the user creates a new library, it will be stored here. Each library is represented by one subdirectory. The contained file structure is documented here.

The basename of the directories is freely choosable by the user, and the suffix must be .lplib.

data/libraries/remote/

This directory contains also libraries, but only those which are managed by LibrePCB itself. So all libraries which are downloaded through the LibrePCB Server API using the library manager. Because they are updated by LibrePCB, the user cannot modify them (i.e. they are read-only). To modify them anyway, the user can copy them as local libraries and make changes there.

The libraries UUID is used as directory basenames (with .lplib suffix) to avoid name conflicts.

Example

This is an example how a workspace could look like:

MyAwesomeWorkspace/
    ├── .librepcb-workspace
    ├── projects/
    │   ├── Project_A/
    │   ├── Project_B/
    │   └── Project_C/
    ├── data/
    │   ├── .librepcb-data
    │   ├── settings.lp
    │   └── libraries/
    │       ├── local/
    │       │   ├── Library_A.lplib/
    │       │   ├── Library_B.lplib/
    │       │   └── Library_C.lplib/
    │       └── remote/
    │           ├── 5d9abd1b-cf0b-4cf7-8666-20a1add9971e.lplib/
    │           ├── 193ef70d-8dab-4a6c-a672-274c5bf09b68.lplib/
    │           └── c2c427a9-17c6-4400-981c-6ece1c9735c3.lplib/
    ├── v0.1/
    │   ├── settings.lp
    │   └── libraries/
    │       ├── local/
    │       │   ├── Library_A.lplib/
    │       │   ├── Library_B.lplib/
    │       │   └── Library_C.lplib/
    │       └── remote/
    │           ├── 5d9abd1b-cf0b-4cf7-8666-20a1add9971e.lplib/
    │           ├── 193ef70d-8dab-4a6c-a672-274c5bf09b68.lplib/
    │           └── c2c427a9-17c6-4400-981c-6ece1c9735c3.lplib/
    └── v0.2/
        ├── .librepcb-data
        └── settings.lp

Upgrade workspace to newer application version

When the user opens the workspace with a specific application's major version the first time – let's say after updating LibrePCB from v1.x to v2.x – LibrePCB realizes that the data directory contains an outdated file format. Then a dialog is shown to create a backup first, by recursively copying the data directory to v1. Afterwards, the data directory is upgraded to file format v2.

There's one special case: File format v0.1 didn't use the data directory yet, it used the directory v0.1 instead. When opening that workspace with a newer LibrePCB version, a wizard is shown to suggest copying the v0.1 directory to data, i.e. the "backup" mechanism works the other way around.

Downgrade workspace to older application version

As the data directory backups are not removed automatically, a downgrade is not required at all. The application simply uses the backup directory (e.g. v0.1) instead of the data directory, so all settings and libraries of the older application version are still there and compatible. The workspace can thus smoothly be used with different application versions at the same time.

If a data directory backup is no longer required for sure, the user can just remove it by himself (to reduce disk usage).

Library Index (SQLite Database)

For better performance of the workspace library (searching in the filesystem can be quite slow), an SQLite database is used for caching/indexing (see librepcb::WorkspaceLibraryDb). From time to time this database is filled/updated with metadata of all libraries and their elements. Searching for elements is then done with SELECT statements in the database, which is very fast.

The database is stored within the data directory directory of the workspace.

Here is the current structure of the database:

Database ERM

Table of Contents