Unverified Commit ab52c549 authored by Kip's avatar Kip Committed by GitHub

Shared-library soname is now generated correctly (#809)

* Add support for interface versioning so applications don't break...

* {CMakeLists.txt,src/CMakeLists.txt}: Shared-library soname is now generated correctly...
version.txt: Added SONAME major and minor fields...
README.md: Add versioning notes. In particular, when to update interface version...
debian/changelog: Fixed lintian complaining about a malformed changelog for non-native package...
parent a345fcc6
...@@ -67,7 +67,7 @@ if (PISTACHE_USE_SSL) ...@@ -67,7 +67,7 @@ if (PISTACHE_USE_SSL)
find_package(OpenSSL REQUIRED COMPONENTS SSL Crypto) find_package(OpenSSL REQUIRED COMPONENTS SSL Crypto)
endif () endif ()
# Set version... # Set release version...
# Retrieve from external file... # Retrieve from external file...
file(READ "version.txt" VERSION_FILE) file(READ "version.txt" VERSION_FILE)
...@@ -107,7 +107,19 @@ endif () ...@@ -107,7 +107,19 @@ endif ()
) )
endif() endif()
# Set libraries... # Set public interface version...
# Major should be incremented every time a non-backward compatible change
# occurs in the ABI...
string(REGEX MATCH "SONAME_VERSION_MAJOR *([0-9]*)" _ ${VERSION_FILE})
set(SONAME_VERSION_MAJOR ${CMAKE_MATCH_1})
# Minor should be incremented every time a backward compatible change occurs
# in the ABI...
string(REGEX MATCH "SONAME_VERSION_MINOR *([0-9]+)" _ ${VERSION_FILE})
set(SONAME_VERSION_MINOR ${CMAKE_MATCH_1})
# Set libraries that we need to link against...
# Minimum... # Minimum...
set(LIBS "-lpistache -lpthread") set(LIBS "-lpistache -lpthread")
......
...@@ -30,6 +30,29 @@ For those that prefer IRC over Slack, the rag-tag crew of maintainers idle in `# ...@@ -30,6 +30,29 @@ For those that prefer IRC over Slack, the rag-tag crew of maintainers idle in `#
The [Launchpad Team](https://launchpad.net/~pistache+team) administers the daily and stable Ubuntu pre-compiled packages. The [Launchpad Team](https://launchpad.net/~pistache+team) administers the daily and stable Ubuntu pre-compiled packages.
## Release Versioning
Please update `version.txt` accordingly with each unstable or stable release.
## Interface Versioning
The version of the library's public interface (ABI) is not the same as the release version. The interface version is primarily associated with the _external_ interface of the library. Different platforms handle this differently, such as AIX, GNU/Linux, and Solaris.
GNU Libtool abstracts each platform's idiosyncrasies away because it is more portable than using `ar(1)` or `ranlib(1)` directly. However, it is a pain to integrate with CMake so we made do without it by setting the SONAME directly.
When Pistache is installed it will normally ship:
- `libpistache-<release>.so.X.Y`: This is the actual shared-library binary file. The _X_ and _Y_ values are the major and minor interface versions respectively.
- `libpistache-<release>.so.X`: This is the _soname_ soft link that points to the binary file. It is what other programs and other libraries reference internally. You should never need to directly reference this file in your build environment.
- `libpistache-<release>.so`: This is the _linker name_ entry. This is also a soft link that refers to the soname with the highest major interface version. This linker name is what is referred to on the linker command line. This file is created by the installation process.
- `libpistache-<release>.a`: This is the _static archive_ form of the library. Since when using a static library all of its symbols are normally resolved before runtime, an interface version in the filename is unnecessary.
If your contribution has modified the interface, you may need to update the major or minor interface versions. Otherwise user applications and build environments will eventually break. This is because they will attempt to link against an incorrect version of the library -- or worse, link correctly but with undefined runtime behaviour.
The major version should be incremented every time a non-backward compatible change occured in the ABI. The minor version should be incremented every time a backward compatible change occurs. This can be done by modifying `version.txt` accordingly.
# Precompiled Packages # Precompiled Packages
If you have no need to modify the Pistache source, you are strongly recommended to use precompiled packages for your distribution. This will save you time. If you have no need to modify the Pistache source, you are strongly recommended to use precompiled packages for your distribution. This will save you time.
......
pistache (0.0.002) eoan; urgency=medium pistache (0.0.002-pistache1) focal; urgency=medium
* Latest upstream. * Latest upstream.
-- Kip Warner <kip@thevertigo.com> Fri, 17 Jan 2020 14:29:59 -0800 -- Kip Warner <kip@thevertigo.com> Sun, 02 Aug 2020 18:26:47 -0700
...@@ -47,9 +47,8 @@ endif () ...@@ -47,9 +47,8 @@ endif ()
set(Pistache_OUTPUT_NAME "pistache") set(Pistache_OUTPUT_NAME "pistache")
set_target_properties(pistache_shared PROPERTIES set_target_properties(pistache_shared PROPERTIES
OUTPUT_NAME ${Pistache_OUTPUT_NAME} OUTPUT_NAME ${Pistache_OUTPUT_NAME}-${version}
VERSION ${version} SOVERSION ${SONAME_VERSION_MAJOR}.${SONAME_VERSION_MINOR}
SOVERSION ${VERSION_MAJOR}
) )
set_target_properties(pistache_static PROPERTIES set_target_properties(pistache_static PROPERTIES
......
VERSION_MAJOR 0 VERSION_MAJOR 0
VERSION_MINOR 0 VERSION_MINOR 0
VERSION_PATCH 002 VERSION_PATCH 002
VERSION_GIT_DATE 20200708 VERSION_GIT_DATE 20200802
SONAME_VERSION_MAJOR 0
SONAME_VERSION_MINOR 0
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment