cmake: Allow shared libraries to customize the soname using LLVM_ABI_REVISION

[tstellar]

Summary

The LLVM_ABI_REVISION variable is intended to be used for release
candidates which introduce an ABI change to a shared library. This
variable can be specified per library, so there is not one global value
for all of LLVM.

For example, if we LLVM X.0.0-rc2 introduces an ABI change for a library
compared with LLVM X.0.0-rc1, then the LLVM_ABI_REVISION number for
library will be incremented by 1.

In the main branch, LLVM_ABI_REVISION should always be 0, it is only
meant to be used in the release branch.

[dim]

clang/tools/clang-shlib/CMakeLists.txt

5

Is this actually needed? This CMakeLists.txt calls add_clang_library() in clang/cmake/modules/AddClang.cmake, which calls add_llvm_library() in llvm/cmake/modules/AddLLVM.cmake, which calls the confusingly named llvm_add_library() in the same file. That last function is already updated below to set LLVM_ABI_REVISION to 0 is it is unset.

llvm/tools/llvm-shlib/CMakeLists.txt

9

Similar here, this CMakeLists.txt calls add_llvm_library which already sets the LLVM_ABI_REVISION to 0.

78

I think this is also handled via add_llvm_library/llvm_add_library?

[serge-sans-paille]

clang/tools/clang-shlib/CMakeLists.txt

2

This comment is a bit misleading: should it be for each RC *or* for each RC that implies an ABI change? And what about the (very rare) minor version release, like 11.1.0? My understanding is that they implie an SONAME bump, maybe that should be stated somewhere?

I think it would be great to have that ABI policy documented somewhere in the official doc, and not only as a cmake comment, as every project linking with clang or llvm is impacted.

llvm/cmake/modules/AddLLVM.cmake

595

Nit: strange indent.

clang/tools/clang-shlib/CMakeLists.txt

+# In the main branch, LLVM_ABI_REVISION should always be 0.  In the release
+# branches, this should be incremented before each release candidate every
+# time the ABI of libclang-cpp.so changes.
+set(LLVM_ABI_REVISION 0)
+
 # Building libclang-cpp.so fails if LLVM_ENABLE_PIC=Off
 if (NOT LLVM_ENABLE_PIC)
   return()
 endif()
 
 get_property(clang_libs GLOBAL PROPERTY CLANG_STATIC_LIBS)
 
 foreach (lib ${clang_libs})

llvm/cmake/modules/AddLLVM.cmake

if(MSVC)
       set_target_properties(${name} PROPERTIES
         PREFIX ""
         )
     endif()
 
     # Set SOVERSION on shared libraries that lack explicit SONAME
     # specifier, on *nix systems that are not Darwin.
     if(UNIX AND NOT APPLE AND NOT ARG_SONAME)
+      if (NOT LLVM_ABI_REVISION)
+        set(LLVM_ABI_REVISION 0)
+      endif()
       set_target_properties(${name}
         PROPERTIES
         # Since 4.0.0, the ABI version is indicated by the major version
-        SOVERSION ${LLVM_VERSION_MAJOR}${LLVM_VERSION_SUFFIX}
-        VERSION ${LLVM_VERSION_MAJOR}${LLVM_VERSION_SUFFIX})
+  SOVERSION ${LLVM_VERSION_MAJOR}.${LLVM_ABI_REVISION}
+  VERSION ${LLVM_VERSION_MAJOR}.${LLVM_ABI_REVISION})
     endif()
   endif()
 
   if(ARG_MODULE OR ARG_SHARED)
     # Do not add -Dname_EXPORTS to the command-line when building files in this
     # target. Doing so is actively harmful for the modules build because it
     # creates extra module variants, and not useful because we don't use these
     # macros.

llvm/tools/llvm-shlib/CMakeLists.txt

 # This tool creates a shared library from the LLVM libraries. Generating this
 # library is enabled by setting LLVM_BUILD_LLVM_DYLIB=yes on the CMake
 # commandline. By default the shared library only exports the LLVM C API.
 
+# In the main branch, LLVM_ABI_REVISION should always be 0.  In the release
+# branches, this should be incremented before each release candidate every
+# time the ABI of libLLVM.so changes.
+set(LLVM_ABI_REVISION 0)
+
 set(SOURCES
   libllvm.cpp
   )
 
 if(LLVM_LINK_LLVM_DYLIB AND LLVM_DYLIB_EXPORTED_SYMBOL_FILE)
   message(WARNING "Using LLVM_LINK_LLVM_DYLIB with LLVM_DYLIB_EXPORTED_SYMBOL_FILE may not work. Use at your own risk.")
 endif()
 
if(LLVM_BUILD_LLVM_DYLIB)
   endif()
 
   target_link_libraries(LLVM PRIVATE ${LIB_NAMES})
 
   if (APPLE)
     set_property(TARGET LLVM APPEND_STRING PROPERTY
                 LINK_FLAGS
                 " -compatibility_version 1 -current_version ${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}.${LLVM_VERSION_PATCH}")
+  else()
+    set_target_properties(LLVM
+      PROPERTIES
+      SOVERSION ${LLVM_ABI_REVISION})
   endif()
 
   if(TARGET libLLVMExports)
     add_dependencies(LLVM libLLVMExports)
   endif()
 endif()
 
 if(LLVM_BUILD_LLVM_C_DYLIB AND NOT MSVC)