[CMake] make SONAME of libLLVM configurable

[axw]

Summary

Make the SONAME of the monolithic libLLVM
configurable. This is part of enabling the creation
of libraries with consistent names between old
autotools-based builds, and new CMake builds.
This diff does not change the current naming
scheme, but it would be trivial to do so later.

This is in response to
https://llvm.org/bugs/show_bug.cgi?id=25059, and
also to enable Debian's LLVM packaging to move to
CMake.

llvm_add_library now has SOVERSION and VERSION
options, which, if non-empty and not equal to "cmake-default",
will be set as properties on shared library targets.
The "cmake-default" special case is due to empty string
arguments not resulting in variables defined. This allows us
to have:
(a) defaults if SOVERSION/VERSION are unspecified (i.e. existing MAJOR.MINOR for SOVERSION, etc.)
(b) a means of using the CMake-default SOVERSION/VERSION (i.e. by passing "cmake-default")

There are two new user-configurable options:

LLVM_DYLIB_SOVERSION (defaults to $MAJOR.$MINOR)
LLVM_DYLIB_VERSION (defaults to $PACKAGE_VERSION)

A follow-up will introduce configuration for the name of
the libLLVM shared library.

[axw]

Fix whitespace

[• tstellarAMD]

I think we should make the shared object name available via an llvm-config option.

[sylvestre.ledru]

Not sure I like the "." idea... This is not obvious. What is wrong with unset ?

By the way, I think we also update the documentation.

[axw]

Not sure I like the "." idea... This is not obvious. What is wrong with unset ?

I agree it's not very obvious, but it remains that we need some way of preventing SOVERSION from being set.

Can you please explain what you mean by "unset"? Are you suggesting "unset" as an alternative string to compare against, or are you referring to the CMake unset() command? If you mean the command, I'm not sure it would help.

By the way, I think we also update the documentation.

Sure, I'll take a pass over the docs to see what needs updating.

[axw]

I think we should make the shared object name available via an llvm-config option.

Sounds good, will do.

[beanz]

Can you separate out LLVM_DYLIB_NAME into a separate patch? Since that will also require support for llvm-config it might be nice to not have it attached to this patch.

Thanks,
-Chris

[axw]

• Drop LLVM_DYLIB_NAME changes
• Use "cmake-default" as the magic string to not set any SOVERSION/VERSION property

[beanz]

I have no objection to this patch, but what is the motivation?

As far as I can tell this doesn't actually address the problems from PR25059, and it doesn't support making the name match autoconf.

Are there specific name transformations that you need that this supports?

[beanz]

According to Tom my other patch addresses his problem (see D13841). Can you please take a look at that patch and see if it addresses what you need as well?

[axw]

In D14040#279163, @beanz wrote:

I have no objection to this patch, but what is the motivation?

As far as I can tell this doesn't actually address the problems from PR25059, and it doesn't support making the name match autoconf.

Not directly. My intention was to leave switching the defaults to a follow-up.

Are there specific name transformations that you need that this supports?

Yes, Debian uses a slightly different SONAME in its builds (e.g. for LLVM 3.8.0, SONAME is libLLVM-3.8.so.1), and would also like to maintain compatibility. I was hoping to cut down on the number of patches that Debian makes on top of LLVM, but perhaps it's not a good argument for adding this complexity to the LLVM project.

[beanz]

@axw, your patches are way less complex than mine, but I'm not sure it is possible to match the autoconf system without overriding the output name and more or less replacing the symlink creation code.

Perhaps the right approach is to land my changes and rebase yours on top to add the customization you need. Does that sound reasonable to you?

[axw]

I don't think this is necessary now. Debian will just need to patch to set the SOVERSION, but that's a Debian-specific thing that doesn't belong in the LLVM tree.

CMakeLists.txt

 option (LLVM_BUILD_DOCS "Build the llvm documentation." OFF)
 option (LLVM_INCLUDE_DOCS "Generate build targets for llvm documentation." ON)
 option (LLVM_ENABLE_DOXYGEN "Use doxygen to generate llvm API documentation." OFF)
 option (LLVM_ENABLE_SPHINX "Use Sphinx to generate llvm documentation." OFF)
 
 option (LLVM_BUILD_EXTERNAL_COMPILER_RT
   "Build compiler-rt as an external project." OFF)
 
+set(LLVM_DYLIB_SOVERSION "${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}" CACHE STRING
+  "Specify the SOVERSION for libLLVM (specify \"cmake-default\" to use the CMake default)")
+set(LLVM_DYLIB_VERSION "${PACKAGE_VERSION}" CACHE STRING
+  "Specify the VERSION for libLLVM (specify \"cmake-default\" to use the CMake default)")
+
 # You can configure which libraries from LLVM you want to include in the
 # shared library by setting LLVM_DYLIB_COMPONENTS to a semi-colon delimited
 # list of LLVM components. All component names handled by llvm-config are valid.
 if(NOT DEFINED LLVM_DYLIB_COMPONENTS)
   set(LLVM_DYLIB_COMPONENTS "all" CACHE STRING
     "Semicolon-separated list of components to include in libLLVM, or \"all\".")
 endif()
 option(LLVM_LINK_LLVM_DYLIB "Link tools against the libllvm dynamic library" OFF)

cmake/modules/AddLLVM.cmake

 #   LINK_LIBS lib_targets...
 #     Same semantics as target_link_libraries().
 #   ADDITIONAL_HEADERS
 #     May specify header files for IDE generators.
 #   )
 function(llvm_add_library name)
   cmake_parse_arguments(ARG
     "MODULE;SHARED;STATIC;DISABLE_LLVM_LINK_LLVM_DYLIB"
-    "OUTPUT_NAME"
+    "OUTPUT_NAME;SOVERSION;VERSION"
     "ADDITIONAL_HEADERS;DEPENDS;LINK_COMPONENTS;LINK_LIBS;OBJLIBS"
     ${ARGN})
   list(APPEND LLVM_COMMON_DEPENDS ${ARG_DEPENDS})
   if(ARG_ADDITIONAL_HEADERS)
     # Pass through ADDITIONAL_HEADERS.
     set(ARG_ADDITIONAL_HEADERS ADDITIONAL_HEADERS ${ARG_ADDITIONAL_HEADERS})
   endif()
   if(ARG_OBJLIBS)
function(llvm_add_library name)
 
   if(ARG_SHARED)
     if(WIN32)
       set_target_properties(${name} PROPERTIES
         PREFIX ""
         )
     endif()
 
-    set_target_properties(${name}
-      PROPERTIES
-      SOVERSION ${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}
-      VERSION ${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}.${LLVM_VERSION_PATCH}${LLVM_VERSION_SUFFIX})
+    # Set SOVERSION iff it is unspecified in arguments;
+    # we take a value of "cmake-default" to mean don't
+    # set the property.
+    set(soversion ${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR})
+    if(ARG_SOVERSION)
+      set(soversion ${ARG_SOVERSION})
+    endif()
+    if(NOT "${soversion}" STREQUAL "cmake-default")
+      set_target_properties(${name} PROPERTIES SOVERSION ${soversion})
+    endif()
+
+    # As above, but for VERSION.
+    set(version ${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}.${LLVM_VERSION_PATCH}${LLVM_VERSION_SUFFIX})
+    if(ARG_VERSION)
+      set(version ${ARG_VERSION})
+    endif()
+    if(NOT "${version}" STREQUAL "cmake-default")
+      set_target_properties(${name} PROPERTIES VERSION ${version})
+    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.
     set_target_properties( ${name} PROPERTIES DEFINE_SYMBOL "" )

tools/llvm-shlib/CMakeLists.txt

add_custom_command(OUTPUT ${LLVM_EXPORTED_SYMBOL_FILE}
       COMMENT "Generating combined export list...")
     add_custom_target(libLLVMExports DEPENDS ${LLVM_EXPORTED_SYMBOL_FILE})
   endif()
 else()
   set(LLVM_EXPORTED_SYMBOL_FILE ${LLVM_DYLIB_EXPORTED_SYMBOL_FILE})
   add_custom_target(libLLVMExports DEPENDS ${LLVM_EXPORTED_SYMBOL_FILE})
 endif()
 
-add_llvm_library(LLVM SHARED DISABLE_LLVM_LINK_LLVM_DYLIB ${SOURCES})
+add_llvm_library(LLVM ${SOURCES}
+    SHARED
+    SOVERSION ${LLVM_DYLIB_SOVERSION}
+    VERSION ${LLVM_DYLIB_VERSION}
+    DISABLE_LLVM_LINK_LLVM_DYLIB)
 
 list(REMOVE_DUPLICATES LIB_NAMES)
 if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux") # FIXME: It should be "GNU ld for elf"
   # GNU ld doesn't resolve symbols in the version script.
   set(LIB_NAMES -Wl,--whole-archive ${LIB_NAMES} -Wl,--no-whole-archive)
 elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
   set(LIB_NAMES -Wl,-all_load ${LIB_NAMES})
 endif()