[Oorexx-devel] Fwd: Question ad CMakeLists.txt (ooRexx 5 version numbers in the library name on Unix (Linux and MacOS) breaks long established Rexx convention)

[Rony G. Flatscher]

Sorry, sent this reply to Rick instead of the list by mistake!

---rony



 Forwarded Message 
Subject:Re: [Oorexx-devel] Question ad CMakeLists.txt (ooRexx 5 version 
numbers in the library
name on Unix (Linux and MacOS) breaks long established Rexx convention)
Date:   Sun, 26 Jul 2020 17:48:58 +0200
From:   Rony G. Flatscher 
To: Rick McGuire 



Thank you for your follow-up information!

Following your suggestion I defined a new API identifier "ORX_API_LEVEL" in 
"SYM_LINK_CREATE_TO ",
adjusted 'set_target_properities' accordingly and 'SYM_LINK_CREATE_TO' in the 
enclosed diff/patch file.

Tested on 64-bit Ubuntu.

If there are no objections I would check-in those changes.

---rony



On 26.07.2020 16:34, Rick McGuire wrote:
> I just checked, the only new entry points in rexx.dll are internal use only 
> ones required by
> different interpreter components. There are no new "official" APIs 
> introduced. The version can
> reasonable left at the 4 level. 
>
> Rick
>
> On Sun, Jul 26, 2020 at 10:31 AM Rick McGuire  > wrote:
>
> I guess the real problem is that we are inappropriately tying the uses of 
> the library version
> to the release version. The purpose here is to allow linking to a version 
> that contains the
> entry points required by your program. The links to the older versions 
> are created because the
> new version is upward compatible to the old version, so, for example, a 
> version 5 library will
> work with programs linked to version 4 of the same library. A new release 
> of the interpreter
> does not warrant automatically bumping the library version, unless the 
> library also contains
> new entry points that implement new APIs. I had a similar problem with 
> the context APIs. The
> API version is not tied to the interpreter release number, but is only 
> incremented when a new
> API is added to a given context vector. The different context APIs 
> (thread, method, routine,
> etc.) each carries its own version identifier. 
>
> So what is needed here is an API level identifier. The past version was 
> not necessarily
> broken, because I'm not sure any new entry points were introduced between 
> 4.0 and 4.2. I'd
> have to go double check, but I'm not sure that any new ones are being 
> introduced in 5.0.0,
> which would argue that it should be left a the 4 level. 
>
> Rick 
>
> On Sun, Jul 26, 2020 at 9:48 AM Rony G. Flatscher  > wrote:
>
> On 26.07.2020 14:11, Rick McGuire wrote:
> > The only reservation I have is that new APIs can get introduced in 
> minor releases as
> well as major
> > releases. As such, wouldn't it be better if "5.0" were used? A 
> library for a 5.1 release
> might
> > contain APIs that a 5.0 release does not. The old convention was 
> probably an error.
>
> It seems that you foresee situations with ooRexx that warrant at 
> least ORX_MINOR to be
> used, even
> worse, you view the old convention to be in error!
>
> In that case it would not make sense to simplify the so version 
> number for ooRexx 5.0 to
> only use
> ORX_MAJOR then and the question is whether it makes sense to change 
> the current setting of
> ORX_VERSION at all then!
> :)
>
> ---rony
>

Index: CMakeLists.txt
===
--- CMakeLists.txt  (revision 12100)
+++ CMakeLists.txt  (working copy)
@@ -64,6 +64,7 @@
 
#/**/
 project (ooRexx)
 # The version of ooRexx to make
+set (ORX_API_LEVEL 4)
 set (ORX_MAJOR 5)
 set (ORX_MINOR 0)
 set (ORX_MOD_LVL 0)
@@ -87,7 +88,7 @@
 
 # Unix: used in macro create_install_symlink()
 set(SYM_LINK_CREATE_FROM 3)# define lower bound
-math(EXPR SYM_LINK_CREATE_TO "${ORX_MAJOR}-1") # define upper bound is 
dependent on ${ORX_MAJOR}
+math(EXPR SYM_LINK_CREATE_TO "${ORX_API_LEVEL}-1") # define upper bound is 
dependent on ${ORX_MAJOR}
 
 
 # OOREXX_SHEBANG_PROGRAM default:
@@ -668,7 +669,7 @@
 install(TARGETS rexxapi RUNTIME DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
 LIBRARY DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
 ARCHIVE DESTINATION ${INSTALL_INCLUDE_DIR} COMPONENT 
DevLib)
-set_target_properties(rexxapi PROPERTIES VERSION ${ORX_VERSION})
+set_target_properties(rexxapi PROPERTIES SOVERSION ${ORX_API_LEVEL})
 create_install_symlink(rexxapi)
 
  librexx.so ##
@@ -953,7 +954,7 @@
 install(TARGETS rexx RUNTIME DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
  LIBRARY DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
  ARCHIVE DESTINATION ${INSTALL_INCLUDE_DIR} COMPONENT 
DevLib)
-set_target_properties(rexx 

Re: [Oorexx-devel] Question ad CMakeLists.txt (ooRexx 5 version numbers in the library name on Unix (Linux and MacOS) breaks long established Rexx convention)

[Rick McGuire]

I just checked, the only new entry points in rexx.dll are internal use only
ones required by different interpreter components. There are no new
"official" APIs introduced. The version can reasonable left at the 4 level.

Rick

On Sun, Jul 26, 2020 at 10:31 AM Rick McGuire  wrote:

> I guess the real problem is that we are inappropriately tying the uses of
> the library version to the release version. The purpose here is to allow
> linking to a version that contains the entry points required by your
> program. The links to the older versions are created because the new
> version is upward compatible to the old version, so, for example, a version
> 5 library will work with programs linked to version 4 of the same library.
> A new release of the interpreter does not warrant automatically bumping the
> library version, unless the library also contains new entry points that
> implement new APIs. I had a similar problem with the context APIs. The API
> version is not tied to the interpreter release number, but is only
> incremented when a new API is added to a given context vector. The
> different context APIs (thread, method, routine, etc.) each carries its own
> version identifier.
>
> So what is needed here is an API level identifier. The past version was
> not necessarily broken, because I'm not sure any new entry points were
> introduced between 4.0 and 4.2. I'd have to go double check, but I'm not
> sure that any new ones are being introduced in 5.0.0, which would argue
> that it should be left a the 4 level.
>
> Rick
>
> On Sun, Jul 26, 2020 at 9:48 AM Rony G. Flatscher 
> wrote:
>
>> On 26.07.2020 14:11, Rick McGuire wrote:
>> > The only reservation I have is that new APIs can get introduced in
>> minor releases as well as major
>> > releases. As such, wouldn't it be better if "5.0" were used? A library
>> for a 5.1 release might
>> > contain APIs that a 5.0 release does not. The old convention was
>> probably an error.
>>
>> It seems that you foresee situations with ooRexx that warrant at least
>> ORX_MINOR to be used, even
>> worse, you view the old convention to be in error!
>>
>> In that case it would not make sense to simplify the so version number
>> for ooRexx 5.0 to only use
>> ORX_MAJOR then and the question is whether it makes sense to change the
>> current setting of
>> ORX_VERSION at all then!
>> :)
>>
>> ---rony
>>
>>
>>
>> ___
>> Oorexx-devel mailing list
>> Oorexx-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
>>
>
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Question ad CMakeLists.txt (ooRexx 5 version numbers in the library name on Unix (Linux and MacOS) breaks long established Rexx convention)

[Rony G. Flatscher]

On 26.07.2020 14:11, Rick McGuire wrote:
> The only reservation I have is that new APIs can get introduced in minor 
> releases as well as major
> releases. As such, wouldn't it be better if "5.0" were used? A library for a 
> 5.1 release might
> contain APIs that a 5.0 release does not. The old convention was probably an 
> error.

It seems that you foresee situations with ooRexx that warrant at least 
ORX_MINOR to be used, even
worse, you view the old convention to be in error!

In that case it would not make sense to simplify the so version number for 
ooRexx 5.0 to only use
ORX_MAJOR then and the question is whether it makes sense to change the current 
setting of
ORX_VERSION at all then!
:)

---rony



___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Question ad CMakeLists.txt (ooRexx 5 version numbers in the library name on Unix (Linux and MacOS) breaks long established Rexx convention)

[Rick McGuire]

The only reservation I have is that new APIs can get introduced in minor
releases as well as major releases. As such, wouldn't it be better if "5.0"
were used? A library for a 5.1 release might contain APIs that a 5.0
release does not. The old convention was probably an error.

Note that "new APIs" in this sense only applies to new entry points added
to the libraries. APIs added to the context vectors are a different
mechanism and shouldn't cause problems.

Rick

On Sun, Jul 26, 2020 at 7:50 AM Rony G. Flatscher 
wrote:

> On 25.07.2020 20:10, Rony G. Flatscher wrote:
>
> On 25.07.2020 18:57, Rony G. Flatscher wrote:
>
> The library names of the Unix (Linux and Mac) versions of ooRexx added
> links to support earlier ooRexx versions in the form
>
>- Linux
>   - "lib" name ".so.${ORX_MAJOR}", e.g.
>  - librexx.so -> librexx.so.3
>  librexx.so -> librexx.so.4
>  
>  - librexxapi.so -> librexxapi.so.3
>  librexxapi.so -> librexxapi.so.4
>  ...
>
>  - MacOS
>   - "lib" name ".${ORX_MAJOR}.dylib", e.g.
>  - librexx.dylib -> librexx.3.dylib
>  librexx.dylib -> librexx.4.dylib
>  ...
>  - librexxapi.dylib -> librexxapi.3.dylib
>  librexxapi.dylib -> librexxapi.4.dylib
>  ...
>
> The version number in the current ooRexx 5.0 beta on Unix (Linux, MacOS)
> use in addition to ${ORX_MAJOR} the subnumbers ${ORX_MINOR}.${ORX_MOD_LVL,
> thereby unnecessarily breaking the naming system, e.g.:
>
>- Linux
>   - "lib" name ".so.${ORX_MAJOR}", e.g.
>  - librexx.so -> librexx.so.3
>  librexx.so -> librexx.so.4
>  librexx.so -> librexx.so.5.0.0
>  
>  - librexxapi.so -> librexxapi.so.3
>  librexxapi.so -> librexxapi.so.4
>  librexxapi.so -> librexxapi.so.5.0.0
>  ...
>
>  - MacOS
>   - "lib" name ".${ORX_MAJOR}.dylib", e.g.
>  - librexx.dylib -> librexx.3.dylib
>  librexx.dylib -> librexx.4.dylib
>  librexx.dylib -> librexx.5.0.0.dylib
>  ...
>  - librexxapi.dylib -> librexxapi.3.dylib
>  librexxapi.dylib -> librexxapi.4.dylib
>  librexxapi.dylib -> librexxapi.5.0.0.dylib
>  ...
>
> Suggesting to changing the versioned library names of ooRexx 5 to match
> the established convention (using only ${ORX_MAJOR}).
>
> Are there any objections to such a change?
>
> ---
>
> If not, where does "CMAKE_SHARED_LIBRARY_PREFIX" get set (which gets used
> for setting "ORX_SHARED_LIBRARY_EXT")?
>
> It seems that the above two variables play no role in the version string
> for the link file names. Rather the usage of "set_target_properties(libname
> PROPERTIES VERSION ${ORX_VERSION})" for each "libname" defines the version
> string to use [1]. So probably using "${ORX_MAJOR}" instead of
> "${ORX_VERSION}" would make the version string in the link names to consist
> of "5" only.
>
> ---rony
>
> [1] Search for "VERSION" in:
> 
>  to
> yield:
>
> "... For shared libraries VERSION and SOVERSION can be used to specify the
> build version and API version respectively. When building or installing
> appropriate symlinks are created if the platform supports symlinks and the
> linker supports so-names. If only one of both is specified the missing is
> assumed to have the same version number. For executables VERSION can be
> used to specify the build version. When building or installing appropriate
> symlinks are created if the platform supports symlinks. For shared
> libraries and executables on Windows the VERSION attribute is parsed to
> extract a “major.minor” version number. These numbers are used as the image
> version of the binary. ...".
>
> What the enclosed patch does to "CMakeLists.txt" (tested on Ubuntu):
>
>- changes the variable name in "set_target_properties" for library
>version from "VERSION" to "SOVERSION", which will self-document the purpose
>of that property (cf. [1] above),
>- changes the value from "${ORX_VERSION}" (i.e. "5.0.0") to
>"${ORX_MAJOR}" (i.e. "5")
>
> If there are  no objections I will check-in that patch.
>
> ---rony
>
>
> ___
> Oorexx-devel mailing list
> Oorexx-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
>
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Question ad CMakeLists.txt (ooRexx 5 version numbers in the library name on Unix (Linux and MacOS) breaks long established Rexx convention)

[Rony G. Flatscher]

On 25.07.2020 20:10, Rony G. Flatscher wrote:
> On 25.07.2020 18:57, Rony G. Flatscher wrote:
>>
>> The library names of the Unix (Linux and Mac) versions of ooRexx added links 
>> to support earlier
>> ooRexx versions in the form
>>
>>   * Linux
>>   o "lib" name ".so.${ORX_MAJOR}", e.g.
>>   + librexx.so -> librexx.so.3
>> librexx.so -> librexx.so.4
>> 
>>   + librexxapi.so -> librexxapi.so.3
>> librexxapi.so -> librexxapi.so.4
>> ...
>>
>>   * MacOS
>>   o "lib" name ".${ORX_MAJOR}.dylib", e.g.
>>   + librexx.dylib -> librexx.3.dylib
>> librexx.dylib -> librexx.4.dylib
>> ...
>>   + librexxapi.dylib -> librexxapi.3.dylib
>> librexxapi.dylib -> librexxapi.4.dylib
>> ...
>>
>> The version number in the current ooRexx 5.0 beta on Unix (Linux, MacOS) use 
>> in addition to
>> ${ORX_MAJOR} the subnumbers ${ORX_MINOR}.${ORX_MOD_LVL, thereby 
>> unnecessarily breaking the naming
>> system, e.g.:
>>
>>   * Linux
>>   o "lib" name ".so.${ORX_MAJOR}", e.g.
>>   + librexx.so -> librexx.so.3
>> librexx.so -> librexx.so.4
>> librexx.so -> librexx.so.5.0.0
>> 
>>   + librexxapi.so -> librexxapi.so.3
>> librexxapi.so -> librexxapi.so.4
>> librexxapi.so -> librexxapi.so.5.0.0
>> ...
>>
>>   * MacOS
>>   o "lib" name ".${ORX_MAJOR}.dylib", e.g.
>>   + librexx.dylib -> librexx.3.dylib
>> librexx.dylib -> librexx.4.dylib
>> librexx.dylib -> librexx.5.0.0.dylib
>> ...
>>   + librexxapi.dylib -> librexxapi.3.dylib
>> librexxapi.dylib -> librexxapi.4.dylib
>> librexxapi.dylib -> librexxapi.5.0.0.dylib
>> ...
>>
>> Suggesting to changing the versioned library names of ooRexx 5 to match the 
>> established
>> convention (using only ${ORX_MAJOR}).
>>
>> Are there any objections to such a change?
>>
>> ---
>>
>> If not, where does "CMAKE_SHARED_LIBRARY_PREFIX" get set (which gets used 
>> for setting
>> "ORX_SHARED_LIBRARY_EXT")?
>>
> It seems that the above two variables play no role in the version string for 
> the link file names.
> Rather the usage of "set_target_properties(libname PROPERTIES VERSION 
> ${ORX_VERSION})" for each
> "libname" defines the version string to use [1]. So probably using 
> "${ORX_MAJOR}" instead of
> "${ORX_VERSION}" would make the version string in the link names to consist 
> of "5" only.
>
> ---rony
>
> [1] Search for "VERSION" in:
>  to 
> yield:
>
> "... For shared libraries VERSION and SOVERSION can be used to specify 
> the build version and
> API version respectively. When building or installing appropriate 
> symlinks are created if the
> platform supports symlinks and the linker supports so-names. If only one 
> of both is specified
> the missing is assumed to have the same version number. For executables 
> VERSION can be used to
> specify the build version. When building or installing appropriate 
> symlinks are created if the
> platform supports symlinks. For shared libraries and executables on 
> Windows the VERSION
> attribute is parsed to extract a “major.minor” version number. These 
> numbers are used as the
> image version of the binary. ...".
>
What the enclosed patch does to "CMakeLists.txt" (tested on Ubuntu):

  * changes the variable name in "set_target_properties" for library version 
from "VERSION" to
"SOVERSION", which will self-document the purpose of that property (cf. [1] 
above),
  * changes the value from "${ORX_VERSION}" (i.e. "5.0.0") to "${ORX_MAJOR}" 
(i.e. "5")

If there are  no objections I will check-in that patch.

---rony


Index: CMakeLists.txt
===
--- CMakeLists.txt  (revision 12100)
+++ CMakeLists.txt  (working copy)
@@ -668,7 +668,7 @@
 install(TARGETS rexxapi RUNTIME DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
 LIBRARY DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
 ARCHIVE DESTINATION ${INSTALL_INCLUDE_DIR} COMPONENT 
DevLib)
-set_target_properties(rexxapi PROPERTIES VERSION ${ORX_VERSION})
+set_target_properties(rexxapi PROPERTIES SOVERSION ${ORX_MAJOR})
 create_install_symlink(rexxapi)
 
  librexx.so ##
@@ -953,7 +953,7 @@
 install(TARGETS rexx RUNTIME DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
  LIBRARY DESTINATION ${INSTALL_LIB_DIR} COMPONENT Core
  ARCHIVE DESTINATION ${INSTALL_INCLUDE_DIR} COMPONENT 
DevLib)
-set_target_properties(rexx PROPERTIES VERSION ${ORX_VERSION})
+set_target_properties(rexx PROPERTIES SOVERSION ${ORX_MAJOR})
 create_install_symlink(rexx)
 
  orexx (executable)