From 4ba0bbe6199c7528aeb32e9c6c3699dfc41341e9 Mon Sep 17 00:00:00 2001 From: Gordon Messmer Date: Feb 05 2026 17:33:45 +0000 Subject: [PATCH 1/3] DRAFT: expand policy doc regarding versioned symbols --- diff --git a/guidelines/modules/ROOT/pages/C_and_C++.adoc b/guidelines/modules/ROOT/pages/C_and_C++.adoc index c9605a0..fb03420 100644 --- a/guidelines/modules/ROOT/pages/C_and_C++.adoc +++ b/guidelines/modules/ROOT/pages/C_and_C++.adoc @@ -70,10 +70,53 @@ but with a different implementation. Having two `libfoo.so` each with a different API is bad practice and makes it harder to package and distribute those packages. -Libraries should version all of their symbols using a version script. -Versioning allows the library to avoid changing the SONAME when the API changes -and instead compatibility functions can be written -to provide backwards compatibility for older applications. +== Versioned Symbols + +Without versioned symbols, RPM will generate a dependency expression +naming the library but without a version, effectively setting +"$Major.0.0" as the minimum version. Versioned symbols provide the +information required to ensure that libraries are actually new enough +to run the software that links to them. + +Package maintainers are encouraged to work with upstream projects to +add versioned symbols to libraries that do not include them yet. + +Adding symbol versions is simple for the majority of libraries, +initially requiring only a symbol map and one additional argument to +the linker during the build process. + +``` +generate_initial_map.sh: +#!/bin/sh +echo "$2 {" +echo " global:" +objdump -T $1 | \ + grep -F .text | \ + awk '{print $7;}' | \ + c++filt | \ + awk '/[() ]/ {print " \"" $0 "\";";} \ + !/[() ]/ {print " " $0 ";";}' | \ + sort +echo "}" +``` + +Run `generate_initial_map.sh /path/to/library.so.1 _` to +generate a map file. + +=== Adding version-script to Autoconf + +The version script might be added to `configure.ac` + +``` +AS_IF([test "$GCC" = yes], +- [AX_APPEND_LINK_FLAGS([-Wstrict-aliasing=3],[AM_LDFLAGS])]) ++ [AX_APPEND_LINK_FLAGS([-Wstrict-aliasing=3],[AM_LDFLAGS]) ++ AX_APPEND_LINK_FLAGS([-Wl,--version-script=${top_srcdir}/lib/libFoo.map],[AM_LDFLAGS])]) +``` + +=== Adding version-script to CMake + +=== Adding version-script to Meson == Applications diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc index fa6c8f5..cce194c 100644 --- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc @@ -241,6 +241,11 @@ The items listed fall into two categories: The package should compile and build into binary rpms on all supported architectures. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support]. +* [[symbols-are-versioned]] *SHOULD*: + Shared libraries should provide versioned symbols (as in "libc.so.6(*GLIBC_2.41*)(64bit)". + Maintainers are encouraged to work with upstream projects that do not yet provide + versioned symbols to add them. + See xref:C_and_C++.adoc[Versioned Symbols] * [[functions-as-described]] *SHOULD*: The reviewer should test that the package functions as described. A package should not segfault instead of running, for example. From 69f425bbad9f7ee9c74db4846f1f0ad4cb57a225 Mon Sep 17 00:00:00 2001 From: Gordon Messmer Date: Feb 05 2026 17:33:45 +0000 Subject: [PATCH 2/3] Add a note explaining how to look for versioned symbols. --- diff --git a/guidelines/modules/ROOT/pages/C_and_C++.adoc b/guidelines/modules/ROOT/pages/C_and_C++.adoc index fb03420..a85bdbe 100644 --- a/guidelines/modules/ROOT/pages/C_and_C++.adoc +++ b/guidelines/modules/ROOT/pages/C_and_C++.adoc @@ -78,6 +78,12 @@ naming the library but without a version, effectively setting information required to ensure that libraries are actually new enough to run the software that links to them. +Examine the capabilities provided by the binary rpm: +`rpm -qp --provides `. A package with shared libraries will +list the library as `libc.so.6()(64bit)` and if the library provides +versioned symbols it will also list the library with versions as +`libm.so.6(GLIBC_2.41)(64bit)`. + Package maintainers are encouraged to work with upstream projects to add versioned symbols to libraries that do not include them yet. @@ -88,6 +94,9 @@ the linker during the build process. ``` generate_initial_map.sh: #!/bin/sh +echo "# Avoid modifying a symbol set after it has been released" +echo "# When adding features in a new release, add a new set" +echo "# Removing features is a breaking change" echo "$2 {" echo " global:" objdump -T $1 | \ @@ -105,13 +114,12 @@ generate a map file. === Adding version-script to Autoconf -The version script might be added to `configure.ac` +The version script might be added to `configure.ac`. AX_APPEND_LINK_FLAGS +will test the linker to ensure it supports the --version-script option, +and add the flag to AM_LDFLAGS if the test succeeds. ``` -AS_IF([test "$GCC" = yes], -- [AX_APPEND_LINK_FLAGS([-Wstrict-aliasing=3],[AM_LDFLAGS])]) -+ [AX_APPEND_LINK_FLAGS([-Wstrict-aliasing=3],[AM_LDFLAGS]) -+ AX_APPEND_LINK_FLAGS([-Wl,--version-script=${top_srcdir}/lib/libFoo.map],[AM_LDFLAGS])]) +AX_APPEND_LINK_FLAGS([-Wl,--version-script=${top_srcdir}/lib/libFoo.map],[AM_LDFLAGS]) ``` === Adding version-script to CMake From e9e4e1aafabcc61715052d5cf5a7adb4e0d7ef53 Mon Sep 17 00:00:00 2001 From: Gordon Messmer Date: Feb 05 2026 17:33:45 +0000 Subject: [PATCH 3/3] Add more build script examples --- diff --git a/guidelines/modules/ROOT/pages/C_and_C++.adoc b/guidelines/modules/ROOT/pages/C_and_C++.adoc index a85bdbe..8af3669 100644 --- a/guidelines/modules/ROOT/pages/C_and_C++.adoc +++ b/guidelines/modules/ROOT/pages/C_and_C++.adoc @@ -112,20 +112,69 @@ echo "}" Run `generate_initial_map.sh /path/to/library.so.1 _` to generate a map file. -=== Adding version-script to Autoconf +=== Adding version-script to Automake -The version script might be added to `configure.ac`. AX_APPEND_LINK_FLAGS -will test the linker to ensure it supports the --version-script option, -and add the flag to AM_LDFLAGS if the test succeeds. +The GNU Portability Library link:https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html[manual] +includes examples of using version-script in automake. In Makefile.am: ``` -AX_APPEND_LINK_FLAGS([-Wl,--version-script=${top_srcdir}/lib/libFoo.map],[AM_LDFLAGS]) +if HAVE_LD_VERSION_SCRIPT +libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map +endif ``` === Adding version-script to CMake +The BSD-3-Clause licensed link:https://github.com/protocolbuffers/protobuf[protobuf] +project includes examples of using version-script in CMake. + +In CMakeLists.txt, check the linker for support: + +``` +file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/cmaketest.map +"{ + global: + main; + local: + *; +};") +# CheckLinkerFlag module available in CMake >=3.18. +if(${CMAKE_VERSION} VERSION_GREATER_EQUAL 3.18) + include(CheckLinkerFlag) + check_linker_flag(CXX -Wl,--version-script=${CMAKE_CURRENT_BINARY_DIR}/cmaketest.map project_HAVE_LD_VERSION_SCRIPT) +endif() +file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/cmaketest.map) +``` + +And, where the library is defined: + +``` +if(project_HAVE_LD_VERSION_SCRIPT) + target_link_options(libfoo PRIVATE -Wl,--version-script=${protobuf_source_dir}/src/libfoo.map) + set_target_properties(libfoo PROPERTIES + LINK_DEPENDS ${project_source_dir}/src/libfoo.map) +endif() +``` + === Adding version-script to Meson +Meson's link:https://github.com/mesonbuild/meson/blob/master/test%20cases/linuxlike/3%20linker%20script/meson.build[test cases] +include examples of using version-script. + +``` +# Solaris 11.4 ld supports --version-script only when you also specify +# -z gnu-version-script-compat +if meson.get_compiler('c').get_linker_id() == 'ld.solaris' + add_project_link_arguments('-Wl,-z,gnu-version-script-compat', language: 'C') +endif + +# Static map file +mapfile = 'bob.map' +vflag = '-Wl,--version-script,@0@/@1@'.format(meson.current_source_dir(), mapfile) + +l = shared_library('bob', 'bob.c', link_args : vflag, link_depends : mapfile) +``` + == Applications No additional suggestions are provided for applications at this time.