lin-epics-modules/sinqMotor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added further info on versioning to README.md

Browse Source
This commit is contained in:
mathis_s
2025-04-24 09:17:05 +02:00
parent bfda809257
commit 3ec83b115e
1 changed files with 41 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -17,9 +17,48 @@ The full inheritance chain for two different motor drivers "a" and "b" looks lik
`asynController -> sinqController -> bController`
`asynAxis -> sinqAxis -> bAxis`
Those inheritance chains are created at runtime by loading shared libraries. Therefore, it is important to load compatible versions. At SINQ, the versioning numbers follow the SemVer standard (https://semver.org/lang/de/). For example, if driver "a" depends on version 2.1.0 of "sinqMotor", then it is safe to use "sinqMotor" 2.5.3 since 2.5.3 is backwards compatible to 2.1.0. However, it is not allowed to use e.g. version 1.9.0 or 2.0.0 or 3.0.1 instead. For more details on SemVer, please refer to the official documentation.
Those inheritance chains are created at runtime by loading shared libraries. These libraries must be compatible to each other (see next section).
To find out which version of sinqMotor is needed by driver "a", refer to its Makefile (line `sinqMotor_VERSION=x.x.x`, where x.x.x is the minimum required version).
### Versioning
In order to make sure the shared libraries are compatible to each other, we use the "require" framework extension for EPICS (https://github.com/paulscherrerinstitute/require). If a shared library has another library as a dependency, it is checked whether the latter is already loaded. If yes, the loaded version is considered compatible if:
1) no specific version was required by the former library
2) the already loaded version matches the required version exactly
3) major and minor numbers are the same and already loaded patch number is equal to the required one or higher
4) major numbers are the same and already loaded minor number is higher than the required one
5) the already loaded version is a test version and the required version is not a test version
These rules are in complicance with the SemVer standard (https://semver.org/lang/de/)
If the dependency hasn't been loaded yet, it is loaded now. In case no specific version is required, the latest numbered version is used.
Because these rules are checked sequentially for each required dependency and no unloading is performed, it is important to consider the order of required libraries. Consider the following example:
```
require "libDriverA" # sinqMotor 1.2 is specified as a dependency
require "libDriverB" # sinqMotor 1.0 is specified as a dependency
```
`require` first checks the dependencies of `libDriverA` and sees that `sinqMotor 1.2` is required. It therefore load `sinqMotor 1.2` and then `libDriverA`. Now the next `require` starts analyzing the dependencies of `libDriverB` and sees that `sinqMotor 1.0` is required. Since `sinqMotor 1.2` is already loaded, rule 4) is applied and `libDriverB` is assumed to be compatible with `sinqMotor 1.2` as well (which it should be according to SemVer).
When the order is inverted, the following happens:
```
require "libDriverB" # sinqMotor 1.0 is specified as a dependency
require "libDriverA" # sinqMotor 1.2 is specified as a dependency
```
`require` first checks the dependencies of `libDriverB` and sees that `sinqMotor 1.0` is required. It therefore load `sinqMotor 1.0` and then `libDriverB`. Now the next `require` starts analyzing the dependencies of `libDriverA` and sees that `sinqMotor 1.2` is required. Since `sinqMotor 1.0` is already loaded, `require` cannot load `sinqMotor 1.2`. Therefore the IOC startup is aborted with an error message.
In order to make the setup script more robust, it is therefore recommended to explicitly add a dependency version which is compatible to all required libraries:
```
require "sinqMotor", "1.2"
require "libDriverB" # sinqMotor 1.0 is specified as a dependency
require "libDriverA" # sinqMotor 1.2 is specified as a dependency
```
The IOC startup now succeeds because we made sure the higher version is loaded first.
Please see the README.md of https://github.com/paulscherrerinstitute/require for more details.
To find out which version of sinqMotor is needed by a driver, refer to its Makefile (line `sinqMotor_VERSION=x.x.x`, where x.x.x is the minimum required version).
### IOC startup script