[cmake] rework LLVM_LINK_LLVM_DYLIB option handling

[axw]

Summary

This diff attempts to address the concerns raised in
http://reviews.llvm.org/D12488.

We introduce a new USE_SHARED option to llvm_config,
which, if set, causes the target to be linked against
libLLVM.

add_llvm_utility now uniformly disables linking against
libLLVM. These utilities are not intended for distribution,
and this keeps the option handling more centralised.

llvm-shlib is now processes before any other "tools"
subdirectories, ensuring the libLLVM target is defined
before its dependents.

One main difference from what was requested: llvm_config
does not prune LLVM_DYLIB_COMPONENTS from the components
passed into explicit_llvm_config. This is because the "all"
component does something special, adding additional
libraries (namely libLTO). Adding the component libraries
after libLLVM should not be a problem, as symbols will be
resolved in libLLVM first.

Finally, I'm not really happy with the
DISABLE_LLVM_LINK_LLVM option, but I'm not sure of a
better way to get the following:

• link all tools and shared libraries to libLLVM if LLVM_LINK_LLVM_DYLIB is set
• some way of explicitly *not* doing so for utilities and libLLVM itself

Suggestions for improvement here are particularly welcome.

[beanz]

Thank you for doing this. LGTM. A few comments below.

cmake/modules/LLVM-Config.cmake

45

I do think we should strip out the components based on LLVM_DYLIB_COMPONENTS to make it more explicit, but this is fine, we can do that later.

tools/CMakeLists.txt

35

You were correct that this isn't actually needed. Feel free to strip this out.

[axw]

Thanks for the review.

cmake/modules/LLVM-Config.cmake

45

I've added a TODO. The main complication is in handling the case of LLVM_DYLIB_COMPONETS=all. I think it just means ~replicating what's done in llvm-shlib: convert all to libnames and only retain the shared library ones, which won't be included in libLLVM.

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)
 
+# 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)
 option(LLVM_BUILD_LLVM_DYLIB "Build libllvm dynamic library" ${LLVM_LINK_LLVM_DYLIB})
 option(LLVM_DYLIB_EXPORT_ALL "Export all symbols from libLLVM.dylib (default is C API only" ${LLVM_LINK_LLVM_DYLIB})
 set(LLVM_DISABLE_LLVM_DYLIB_ATEXIT_DEFAULT ON)
 if (LLVM_LINK_LLVM_DYLIB)
   set(LLVM_DISABLE_LLVM_DYLIB_ATEXIT_DEFAULT OFF)
 endif()
 option(LLVM_DISABLE_LLVM_DYLIB_ATEXIT "Disable llvm-shlib's atexit destructors." ${LLVM_DISABLE_LLVM_DYLIB_ATEXIT_DEFAULT})

cmake/modules/AddLLVM.cmake

macro(add_llvm_executable name)
   # creates extra module variants, and not useful because we don't use these
   # macros.
   set_target_properties( ${name} PROPERTIES DEFINE_SYMBOL "" )
 
   if (LLVM_EXPORTED_SYMBOL_FILE)
     add_llvm_symbol_exports( ${name} ${LLVM_EXPORTED_SYMBOL_FILE} )
   endif(LLVM_EXPORTED_SYMBOL_FILE)
 
-  set(EXCLUDE_FROM_ALL OFF)
-  set_output_directory(${name} ${LLVM_RUNTIME_OUTPUT_INTDIR} ${LLVM_LIBRARY_OUTPUT_INTDIR})
   if (LLVM_LINK_LLVM_DYLIB AND NOT ARG_DISABLE_LLVM_LINK_LLVM_DYLIB)
-    target_link_libraries(${name} LLVM)
-  else()
-    llvm_config( ${name} ${LLVM_LINK_COMPONENTS} )
+    set(USE_SHARED USE_SHARED)
   endif()
+
+  set(EXCLUDE_FROM_ALL OFF)
+  set_output_directory(${name} ${LLVM_RUNTIME_OUTPUT_INTDIR} ${LLVM_LIBRARY_OUTPUT_INTDIR})
+  llvm_config( ${name} ${USE_SHARED} ${LLVM_LINK_COMPONENTS} )
   if( LLVM_COMMON_DEPENDS )
     add_dependencies( ${name} ${LLVM_COMMON_DEPENDS} )
   endif( LLVM_COMMON_DEPENDS )
 endmacro(add_llvm_executable name)
 
 function(export_executable_symbols target)
   if (NOT MSVC) # MSVC's linker doesn't support exporting all symbols.
     set_target_properties(${target} PROPERTIES ENABLE_EXPORTS 1)
macro(add_llvm_example name)
   if( LLVM_BUILD_EXAMPLES )
     install(TARGETS ${name} RUNTIME DESTINATION examples)
   endif()
   set_target_properties(${name} PROPERTIES FOLDER "Examples")
 endmacro(add_llvm_example name)
 
 
 macro(add_llvm_utility name)
-  add_llvm_executable(${name} ${ARGN})
+  add_llvm_executable(${name} DISABLE_LLVM_LINK_LLVM_DYLIB ${ARGN})
   set_target_properties(${name} PROPERTIES FOLDER "Utils")
   if( LLVM_INSTALL_UTILS )
     install (TARGETS ${name}
       RUNTIME DESTINATION bin
       COMPONENT ${name})
     if (NOT CMAKE_CONFIGURATION_TYPES)
       add_custom_target(install-${name}
                         DEPENDS ${name}

cmake/modules/LLVM-Config.cmake

if( capitalized_lib STREQUAL t OR
       set(${return_var} ON PARENT_SCOPE)
       break()
     endif()
   endforeach()
 endfunction(is_llvm_target_library)
 
 
 macro(llvm_config executable)
-  explicit_llvm_config(${executable} ${ARGN})
+  cmake_parse_arguments(ARG "USE_SHARED" "" "" ${ARGN})
+  set(link_components ${ARG_UNPARSED_ARGUMENTS})
+
+  if(USE_SHARED)
+    # If USE_SHARED is specified, then we link against libLLVM,
+    # but also against the component libraries below. This is
+    # done in case libLLVM does not contain all of the components
+    # the target requires.
+    target_link_libraries(${executable} LLVM)
+  endif()
+
+  explicit_llvm_config(${executable} ${link_components})
 endmacro(llvm_config)
 
 
 function(explicit_llvm_config executable)
   set( link_components ${ARGN} )
 
   llvm_map_components_to_libnames(LIBRARIES ${link_components})
   get_target_property(t ${executable} TYPE)

cmake/modules/TableGen.cmake

 
 macro(add_tablegen target project)
   set(${target}_OLD_LLVM_LINK_COMPONENTS ${LLVM_LINK_COMPONENTS})
   set(LLVM_LINK_COMPONENTS ${LLVM_LINK_COMPONENTS} TableGen)
 
   # FIXME: It leaks to user, callee of add_tablegen.
   set(LLVM_ENABLE_OBJLIB ON)
 
-  add_llvm_utility(
-    ${target} ${ARGN}
-    # libLLVM does not include the TableGen
-    # components, so we cannot link any tblgen
-    # utilities against it.
-    DISABLE_LLVM_LINK_LLVM_DYLIB)
-
+  add_llvm_utility(${target} ${ARGN})
   set(LLVM_LINK_COMPONENTS ${${target}_OLD_LLVM_LINK_COMPONENTS})
 
   set(${project}_TABLEGEN "${target}" CACHE
       STRING "Native TableGen executable. Saves building one when cross-compiling.")
 
   # Upgrade existing LLVM_TABLEGEN setting.
   if(${project} STREQUAL LLVM)
     if(${LLVM_TABLEGEN} STREQUAL tblgen)

tools/CMakeLists.txt

if(NOT LLVM_USE_INTEL_JITEVENTS )
   set(LLVM_TOOL_LLVM_JITLISTENER_BUILD Off)
 endif()
 
 if(CYGWIN OR NOT LLVM_ENABLE_PIC)
   set(LLVM_TOOL_LTO_BUILD Off)
   set(LLVM_TOOL_LLVM_LTO_BUILD Off)
 endif()
 
+# Process llvm-shlib before other projects, to ensure the libLLVM
+# target is properly defined for tools that will link against it.
+add_llvm_tool_subdirectory(llvm-shlib)
+
 # Projects supported via LLVM_EXTERNAL_*_SOURCE_DIR need to be explicitly
 # specified.
 add_llvm_external_project(clang)
 add_llvm_external_project(llgo)
 add_llvm_external_project(lld)
 add_llvm_external_project(lldb)
 
 # Automatically add remaining sub-directories containing a 'CMakeLists.txt'
 # file as external projects.
 add_llvm_implicit_projects()
 
 set(LLVM_COMMON_DEPENDS ${LLVM_COMMON_DEPENDS} PARENT_SCOPE)

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.
 
-if(LLVM_LINK_LLVM_DYLIB)
-  if(DEFINED LLVM_DYLIB_COMPONENTS)
-    # To avoid inscrutable link errors, just disallow setting
-    # LLVM_DYLIB_COMPONENTS when we're intending to link tools
-    # and shared libraries with the dylib.
-    message(FATAL_ERROR "LLVM_DYLIB_COMPONENTS must not be set when LLVM_LINK_LLVM_DYLIB is ON")
-  endif()
-  if(NOT LLVM_DYLIB_EXPORT_ALL)
-    message(FATAL_ERROR "LLVM_DYLIB_EXPORT_ALL must be ON when LLVM_LINK_LLVM_DYLIB is ON")
-  endif()
-  set(LLVM_DYLIB_COMPONENTS all)
-endif()
-
-# If LLVM_LINK_LLVM_DYLIB is not OFF, 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
-    ${LLVM_TARGETS_TO_BUILD}
-    Analysis
-    BitReader
-    BitWriter
-    CodeGen
-    Core
-    DebugInfoDWARF
-    DebugInfoPDB
-    ExecutionEngine
-    IPO
-    IRReader
-    InstCombine
-    Instrumentation
-    Interpreter
-    Linker
-    MCDisassembler
-    MCJIT
-    ObjCARCOpts
-    Object
-    ScalarOpts
-    Support
-    Target
-    TransformUtils
-    Vectorize
-    native
-    )
-endif()
-
 add_definitions( -DLLVM_VERSION_INFO=\"${PACKAGE_VERSION}\" )
 
 set(SOURCES
   libllvm.cpp
   )
 
 llvm_map_components_to_libnames(LIB_NAMES ${LLVM_DYLIB_COMPONENTS})
 
 if(LLVM_LINK_LLVM_DYLIB)
+  if(NOT LLVM_DYLIB_EXPORT_ALL)
+    message(FATAL_ERROR "LLVM_DYLIB_EXPORT_ALL must be ON when LLVM_LINK_LLVM_DYLIB is ON")
+  endif()
+
   # libLLVM.so should not have any dependencies on any other LLVM
   # shared libraries. When using the "all" pseudo-component,
   # LLVM_AVAILABLE_LIBS is added to the dependencies, which may
   # contain shared libraries (e.g. libLTO).
   #
   # Also exclude libLLVMTableGen for the following reasons:
   #  - it is only used by internal *-tblgen utilities;
   #  - it pollutes the global options space.