File-Based Storage
In CODESYS 3, a project is stored in a single binary file. The contents of this file cannot be read or created outside of the development environment. A comparison of two project versions shows no discernible differences, and two editors already come into conflict when they modify different objects.
After installing the CODESYS File-Based Storage add-on in CODESYS 3, a file-based storage format is provided which is compatible with the storage format in CODESYS 4. It allows for the conversion of the file-based format in CODESYS 4 into the binary format in CODESYS 3 and back.
In CODESYS 4, a project is managed in an open, file-based format. Every object is stored in its own text file, and the project structure is the folder structure in the file system. There is no object manager.
The following advantages result from this.
An object can be read with any text editor and edited if necessary.
The comparison of two project states shows the content changes in plain text.
Changes to different objects do not conflict with each other.
A project is managed in a version control system such as Git, SVN, or Mercurial. The project archive from CODESYS 3 is unnecessary because of this.
The usual processes of a version control system – such as merge request, pull request, and code review – can be used because the changes can also be viewed in the web portal of the version control system.
For more information, see the following: Workspaces and File Types
Source code and generated files
Not everything in the project folder belongs to the source text. In addition to object files, CODESYS 4 also stores temporary results, resolved libraries, and user-specific settings. These files are regenerated as needed.
Folder | Location | Contents |
|---|---|---|
| In the | Compile and reference contexts |
| In the | Temporary files created for diagnostic purposes |
| In the | Generated offline boot application if no path is specified |
| Top level in | Resolved compiled libraries |
| Top level in the project | Project settings and user preferences The directory is created only when a custom project setting is saved for the first time. |
| Parallel to the workspace file | Workspace settings and user preferences |
The cache of device descriptions, on the other hand, belongs to the project. The device descriptions are available as text files and are also version-controlled.
Character set, line breaks, and indentation
To make sure that a comparison between two project versions shows content changes and not format changes, all files are written according to fixed rules in CODESYS 4.
Property | Rule |
|---|---|
Character set for IEC source code and JSON files | UTF-8 without BOM (Byte Order Mark) Files initially omit any information about the character encoding used |
Character set for XML files | UTF-8 preferred Inventory files such as device descriptions are read according to their meta declaration. |
Line break while writing | LF (Line Feed) |
Line break while reading | LF and CRLF (Carriage Return Line Feed) |
Indentation in JSON and XML files | 1 tab per level |
Order of entries in JSON objects | Deterministic |
Files are always saved with the LF line ending format (0x0A). Both LF and CRLF (0x0D, 0x0A) are supported during import. This makes sure that files remain readable even when they have been modified outside of CODESYS 4 with an editor which uses the CRLF line ending format.
Projects in version control systems
The deterministic order in JSON objects and the indentation with tabs have the same purpose: a modified object only creates a difference where the contents have changed.
Object files
Project configuration files such as
Libraries.jsonandProjectInfo.jsonLibraries.lock.jsonlockfileWorkspace file
Folders and files generated from the source code are not part of version control. They contain temporary data, binary files, or user-specific settings. Other development environments handle this in the same way – for example a C# project has the bin and obj folders.
For the following folders, exclusion is a default setting, not a requirement. If binary files are not a problem in your version control system, then you can include the folders in the version control system.
Files excluded from version control:
.library-cache.user<workspace name>.fbsws.user
Configure the version control system so that files are converted to LF format (Line Feed) when checked in, and fetched unchanged when checked out. In Git, you can configure this with the following settings.
core.eol = lf core.autocrlf = false
Save the exclusions for each project folder in a separate file with the .gitignore extension, and the settings for line breaks in a separate file with the .gitattributes extension. Both files should be version-controlled, otherwise the rules will not work.
Editing files outside of CODESYS 4
The object files of a project are in plain text. If necessary, you can edit the files outside of CODESYS 4, for example when resolving a merge conflict or when making a change that affects many objects in the same way.
Here you need to comply with the following conditions:
The declaration remains syntactically valid. The declaration is used to separate it from the implementation.
The character set remains UTF-8 without BOM.
The folder structure remains unchanged because it is the project structure.
Whenever you resolve a merge conflict outside of CODESYS 4, you should check the result afterwards in the CODESYS 4 IDE. A merge may create relationships between objects which are not permitted in a project. An example of this is a POU which is subordinate to another POU.
Files of the version control system such as .gitignore are located in the project folder and therefore also appear in the workspace navigator.