FAQ 788: Principles for Handling ControlDesk Projects in Version Control Systems (VCS) like SVN or GIT

Question

Would you like to check in ControlDesk projects to a VCS?
What do I need to do and how do I see in the dSPACE Log that something went wrong?

Solution

Observe the ControlDesk project file structure and folder hierarchy. The ControlDesk project file set is based on close relationships and certain files depend on each other.

Based on this, it is recommended that you use ControlDesk project backups instead of the complete file set view.

This has the following advantages:

1. ControlDesk project backups are easy to handle.
2. You only work with a single file.
3. This procedure is stable and process-compliant.
4. No temporary files are part of the ControlDesk project backup project.
5. External files that are inside the Project/Experiment tree of ControlDesk will be detected.

You should always make a project backup in ControlDesk itself via ControlDesk -> File -> Save As -> Backup Project

If the one-file policy is not feasible for you and the ControlDesk file structure should be stored file-by-file, consider the following principles.

The next section will focus on ControlDesk. Knowledge of how to operate a VCS correctly is a prerequisite.

The use of a VCS is the responsibility of the user, and we recommend always making a backup before you start to make changes.

File and directory structure

ControlDesk projects use a defined file and directory structure that describes the ControlDesk project as a whole. Therefore, it is key to always save a consistent version of the project.
The contents of the project may be distributed across several files.

Example: Layouts
- The instruments on the layout are saved directly in the layout (.lay).
- The data connections are saved centrally in a single file (.cdc).
- Both files are referenced in the ControlDesk experiment file (.cde).

Files within the ControlDesk project are directly dependent on each other and cannot simply be exchanged (between projects), saved individually, or restored from a backup.

The user must ensure that all relevant changes are transferred to the VCS each time they are stored. This applies in particular to newly created, deleted, and renamed files.

Important

Save and close your ControlDesk project before storing it in your VCS.
Most files in the project structure are binary files and can only be exchanged as single artifacts.
Those that are text-based must be treated the same way because of the dependencies written above (refer to “Example: Layouts”).
This means:
Do not merge any files.
ControlDesk is not designed to fully support all features of a VCS.

Write permissions

You must have write permissions for all files in the project folder.
This means that in a tool such as SVN, you have to “lock” all files to remove the read-only status of the files.
If this is not adhered to, the project might become inconsistent and can no longer be used.

Simultaneous work on ControlDesk projects

Simultaneous work on the same project copy is not supported.
Because of the connection of files in several places of the project structure, it is not possible for more than one person to make changes to a versioned project at a time.
The same applies for simultaneous work on a project that is located in a network. This is also not supported.
There is one exception:
As soon as the export/import function is used in ControlDesk.
For example, in a team, several colleagues create their own layout with instruments that are linked to variables. They use all the same version of the ControlDesk project. These layouts are then imported and combined in the master copy.
 

Hint:

Some parts, e.g., layouts, or all parts of the ControlDesk project could be generated via tool automation.
That would lead to fewer used files which must be versioned.

Error messages that might be related to misuse of a VCS

In ControlDesk, you will find the log messages from all dSPACE products under ControlDesk-> View -> dSPACE Log.
Following examples indicates incorrect usage of a VCS:

Read-only message:

The following files used by project 'my_project' are read-only:
Project.events
my_project.CDP
You might not be able to save your work.

Missing file message:

The following file is missing on disk. D:\my_project\my_experiment\Experiment Layouts\my_layout.lay. The Missing File dialog will be shown.

Access denied message:

The following unexpected exception occurred: Access to the path 'D:\my_project\my_experiment\Events\Project.events' is denied.

Do not exist message:

Some files which belong to the variable description 'SCALEXIO' do not exist.
See details for missing files.
Therefore, the experiment might be corrupt and result in unexpected behavior.
Contact dSPACE Support. You might be able to repair the experiment by copying the missing file to ' D:\my_project\my_experiment\Variable Descriptions\SCALEXIO' directory.

What to do if one of these messages is shown

Try to establish a consistent project status. If that is not possible, use the most recent project backup.