[CMake] `install-distribution` for LLDB on Darwin

[sgraenitz]

Summary

There's a number of requirements for installing LLDB on macOS that are untypical for LLVM projects: use special install-prefix for LLDB.framework, ship headers and tools as framework resources, patch RPATHs, externalize debug-info to dSYM's and strip binaries with -ST. For some of it we could use llvm_externalize_debuginfo() in the past and just add special cases. However, this complicates the code for all projects and comes with the major drawback, that it adds all these actions at build-time, i.e. dSYM creation and stripping take a lot of time and don't make sense at build-time.

LLVM's distribution mechanism (https://llvm.org/docs/BuildingADistribution.html) appears to be the natural candidate to install LLDB. Based on D64399 (enable in standalone builds), this patch integrates framework installation with the distribution mechanism and adds custom stripping flags and dSYM creation at install-time. Unlike the abandoned D61952, it leaves build-tree binaries untouched, so there's no side-effects on testing. Potential install-order issues must be handled externally.

Please let me know what you think, while I run a few more tests and add remarks+documentation.

[sgraenitz]

Usage example that should work in conjunction with D64397 and D64399:

$ cd path/to/lldb-deps-relwithdebinfo
$ cmake -GNinja -C/path/to/llvm-project/lldb/cmake/caches/Apple-lldb-base.cmake \
                -DLLVM_ENABLE_PROJECTS="clang;libcxx" \
                /path/to/llvm-project/llvm
$ cmake --build .

$ cd lldb-relwithdebinfo
$ cmake -GNinja -C/path/to/llvm-project/lldb/cmake/caches/Apple-lldb-macOS.cmake \
                -DLLVM_DIR=/path/to/lldb-deps-relwithdebinfo/lib/cmake/llvm \
                -DClang_DIR=/path/to/lldb-deps-relwithdebinfo/lib/cmake/clang \
                /path/to/llvm-project/lldb
$ cmake --build . --target distribution
$ DESTDIR=/path/to/install/location cmake --build . --target install-distribution

$ tree /path/to/install/location | grep -v -E "(h|py)$"
/path/to/install/location
├── Applications
│   └── Xcode.app
│       └── Contents
│           ├── Developer
│           │   └── usr
│           │       └── bin
│           │           └── lldb
│           └── SharedFrameworks
│               └── LLDB.framework
│                   ├── Headers -> Versions/Current/Headers
│                   ├── LLDB -> Versions/Current/LLDB
│                   ├── Resources -> Versions/Current/Resources
│                   └── Versions
│                       ├── A
│                       │   ├── Headers
│                       │   ├── LLDB
│                       │   └── Resources
│                       │       ├── Info.plist
│                       │       ├── Python
│                       │       │   ├── lldb
│                       │       │   │   ├── _lldb.so -> ../../../LLDB
│                       │       │   │   ├── diagnose
│                       │       │   │   ├── formatters
│                       │       │   │   │   ├── cpp
│                       │       │   │   ├── macosx
│                       │       │   │   │   ├── heap
│                       │       │   │   │   │   ├── Makefile
│                       │       │   │   │   │   └── heap_find.cpp
│                       │       │   │   ├── runtime
│                       │       │   │   └── utils
│                       │       ├── darwin-debug
│                       │       ├── debugserver
│                       │       └── lldb-argdumper
│                       └── Current -> A
└── debuginfo
    ├── LLDB.framework.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── LLDB
    ├── darwin-debug.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── darwin-debug
    ├── debugserver.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── debugserver
    └── lldb-argdumper.dSYM
        └── Contents
            ├── Info.plist
            └── Resources
                └── DWARF
                    └── lldb-argdumper

41 directories, 114 files

[labath]

I'm not very familiar with the details here, but this approach seems reasonable to me...

[xiaobai]

I like the idea a lot and the implementation looks alright. LGTM

lldb/cmake/caches/Apple-lldb-macOS.cmake

 include(${CMAKE_CURRENT_LIST_DIR}/Apple-lldb-base.cmake)
 
 set(LLDB_BUILD_FRAMEWORK ON CACHE BOOL "")
 set(LLDB_NO_INSTALL_DEFAULT_RPATH ON CACHE BOOL "")
 
 # Set the install prefix to the default install location on the enduser machine.
 # If the location is not writeable on the build machine, specify another prefix
 # in the DESTDIR environment variable, e.g.: DESTDIR=/tmp ninja install
 set(CMAKE_INSTALL_PREFIX /Applications/Xcode.app/Contents/Developer/usr CACHE STRING "")
 
 # Choose the install location for LLDB.framework so that it matches the
 # INSTALL_RPATH of the lldb driver. It's either absolute or relative to
 # CMAKE_INSTALL_PREFIX. In any case, DESTDIR will be an extra prefix.
 set(LLDB_FRAMEWORK_INSTALL_DIR /Applications/Xcode.app/Contents/SharedFrameworks CACHE STRING "")
 
+# DESTDIR will be an extra prefix
+set(LLDB_DEBUGINFO_INSTALL_PREFIX /debuginfo CACHE STRING "")
+
 # Release builds may change these:
 set(CMAKE_OSX_DEPLOYMENT_TARGET 10.11 CACHE STRING "")
 set(LLDB_USE_SYSTEM_DEBUGSERVER ON CACHE BOOL "")
 set(LLVM_EXTERNALIZE_DEBUGINFO OFF CACHE BOOL "")

lldb/cmake/modules/AddLLDB.cmake

 function(add_lldb_library name)
   # only supported parameters to this macro are the optional
   # MODULE;SHARED;STATIC library type and source files
   cmake_parse_arguments(PARAM
     "MODULE;SHARED;STATIC;OBJECT;PLUGIN"
-    "ENTITLEMENTS"
+    "INSTALL_PREFIX;ENTITLEMENTS"
     "EXTRA_CXXFLAGS;DEPENDS;LINK_LIBS;LINK_COMPONENTS"
     ${ARGN})
   llvm_process_sources(srcs ${PARAM_UNPARSED_ARGUMENTS})
   list(APPEND LLVM_LINK_COMPONENTS ${PARAM_LINK_COMPONENTS})
 
   if(PARAM_PLUGIN)
     set_property(GLOBAL APPEND PROPERTY LLDB_PLUGINS ${name})
   endif()
else()
     endif()
 
     llvm_add_library(${name} ${libkind} ${srcs}
       LINK_LIBS ${PARAM_LINK_LIBS}
       DEPENDS ${PARAM_DEPENDS}
       ${pass_ENTITLEMENTS}
       ${pass_NO_INSTALL_RPATH}
     )
+  endif()
 
-    if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ${name} STREQUAL "liblldb")
-      if (PARAM_SHARED)
-        if(${name} STREQUAL "liblldb" AND LLDB_BUILD_FRAMEWORK)
-          if(LLDB_FRAMEWORK_INSTALL_DIR)
-            set(install_dir ${LLDB_FRAMEWORK_INSTALL_DIR})
-          else()
-            set(install_dir ".")
-          endif()
-        else()
-          set(install_dir lib${LLVM_LIBDIR_SUFFIX})
-        endif()
-        install(TARGETS ${name}
-          COMPONENT ${name}
-          RUNTIME DESTINATION bin
-          LIBRARY DESTINATION ${install_dir}
-          ARCHIVE DESTINATION ${install_dir})
-      else()
-        install(TARGETS ${name}
-          COMPONENT ${name}
-          LIBRARY DESTINATION lib${LLVM_LIBDIR_SUFFIX}
-          ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX})
-      endif()
-      if (NOT CMAKE_CONFIGURATION_TYPES)
-        add_llvm_install_targets(install-${name}
-                                 DEPENDS ${name}
-                                 COMPONENT ${name})
-      endif()
-    endif()
-  endif()
-
+  if(PARAM_SHARED)
+    set(install_dest lib${LLVM_LIBDIR_SUFFIX})
+    if(PARAM_INSTALL_PREFIX)
+      set(install_dest ${PARAM_INSTALL_PREFIX})
+    # RUNTIME is relevant for DLL platforms, FRAMEWORK for macOS
+    install(TARGETS ${name} COMPONENT ${name}
+      LIBRARY DESTINATION ${install_dest}
+      ARCHIVE DESTINATION ${install_dest}
+      FRAMEWORK DESTINATION ${install_dest})
 
   # Hack: only some LLDB libraries depend on the clang autogenerated headers,
   # but it is simple enough to make all of LLDB depend on some of those
   # headers without negatively impacting much of anything.
   if(NOT LLDB_BUILT_STANDALONE)
     add_dependencies(${name} clang-tablegen-targets)
   endif()
 
   # Add in any extra C++ compilation flags for this library.
   target_compile_options(${name} PRIVATE ${PARAM_EXTRA_CXXFLAGS})
 
   if(PARAM_PLUGIN)
     set_target_properties(${name} PROPERTIES FOLDER "lldb plugins")
   else()
     set_target_properties(${name} PROPERTIES FOLDER "lldb libraries")
   endif()
 endfunction(add_lldb_library)
 
 function(add_lldb_executable name)
   cmake_parse_arguments(ARG
     "GENERATE_INSTALL"
-    "ENTITLEMENTS"
+    "INSTALL_PREFIX;ENTITLEMENTS"
     "LINK_LIBS;LINK_COMPONENTS"
     ${ARGN}
     )
 
   if(ARG_ENTITLEMENTS)
     set(pass_ENTITLEMENTS ENTITLEMENTS ${ARG_ENTITLEMENTS})
   endif()
 
   if(LLDB_NO_INSTALL_DEFAULT_RPATH)
     set(pass_NO_INSTALL_RPATH NO_INSTALL_RPATH)
   endif()
 
   list(APPEND LLVM_LINK_COMPONENTS ${ARG_LINK_COMPONENTS})
   add_llvm_executable(${name}
     ${pass_ENTITLEMENTS}
     ${pass_NO_INSTALL_RPATH}
     ${ARG_UNPARSED_ARGUMENTS}
   )
 
   target_link_libraries(${name} PRIVATE ${ARG_LINK_LIBS})
   set_target_properties(${name} PROPERTIES FOLDER "lldb executables")
 
   if(ARG_GENERATE_INSTALL)
-    install(TARGETS ${name}
-            COMPONENT ${name}
-            RUNTIME DESTINATION bin)
+    set(install_dest bin)
+    if(ARG_INSTALL_PREFIX)
+      set(install_dest ${ARG_INSTALL_PREFIX})
+    endif()
+    install(TARGETS ${name} COMPONENT ${name}
+            RUNTIME DESTINATION ${install_dest})
     if (NOT CMAKE_CONFIGURATION_TYPES)
       add_llvm_install_targets(install-${name}
                                DEPENDS ${name}
                                COMPONENT ${name})
     endif()
+    if(APPLE AND ARG_INSTALL_PREFIX)
+      lldb_add_post_install_steps_darwin(${name} ${ARG_INSTALL_PREFIX})
+    endif()
   endif()
-endfunction(add_lldb_executable)
+endfunction()
 
 
 macro(add_lldb_tool_subdirectory name)
   add_llvm_subdirectory(LLDB TOOL ${name})
 endmacro()
 
 function(add_lldb_tool name)
-  add_lldb_executable(${name} GENERATE_INSTALL ${ARGN})
+  cmake_parse_arguments(ARG "ADD_TO_FRAMEWORK" "" "" ${ARGN})
+  if(LLDB_BUILD_FRAMEWORK AND ARG_ADD_TO_FRAMEWORK)
+    set(subdir LLDB.framework/Versions/${LLDB_FRAMEWORK_VERSION}/Resources)
+    add_lldb_executable(${name}
+      GENERATE_INSTALL
+      INSTALL_PREFIX ${LLDB_FRAMEWORK_INSTALL_DIR}/${subdir}
+      ${ARG_UNPARSED_ARGUMENTS}
+    )
+    lldb_add_to_buildtree_lldb_framework(${name} ${subdir})
+    return()
+  endif()
+
+  add_lldb_executable(${name} GENERATE_INSTALL ${ARG_UNPARSED_ARGUMENTS})
 endfunction()
 
 # Support appending linker flags to an existing target.
 # This will preserve the existing linker flags on the
 # target, if there are any.
 function(lldb_append_link_flags target_name new_link_flags)
   # Retrieve existing linker flags.
   get_target_property(current_link_flags ${target_name} LINK_FLAGS)
 
   # If we had any linker flags, include them first in the new linker flags.
   if(current_link_flags)
     set(new_link_flags "${current_link_flags} ${new_link_flags}")
   endif()
 
   # Now set them onto the target.
   set_target_properties(${target_name} PROPERTIES LINK_FLAGS ${new_link_flags})
 endfunction()
 
-# Unified handling for executable LLDB.framework resources. Given the name of an
-# executable target, this function adds a post-build step to copy it to the
-# framework bundle in the build-tree.
-function(lldb_add_to_framework name)
-  set(subdir "LLDB.framework/Versions/${LLDB_FRAMEWORK_VERSION}/Resources")
-
+function(lldb_add_to_buildtree_lldb_framework name subdir)
   # Destination for the copy in the build-tree. While the framework target may
   # not exist yet, it will exist when the generator expression gets expanded.
   set(copy_dest "$<TARGET_FILE_DIR:liblldb>/../../../${subdir}")
 
   # Copy into the framework's Resources directory for testing.
   add_custom_command(TARGET ${name} POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:${name}> ${copy_dest}
     COMMENT "Copy ${name} to ${copy_dest}"
   )
 endfunction()
 
+function(lldb_add_post_install_steps_darwin name install_prefix)
+  if(NOT APPLE)
+    message(WARNING "Darwin-specific functionality; not currently available on non-Apple platforms.")
+    return()
+  endif()
+
+  get_target_property(output_name ${name} OUTPUT_NAME)
+  if(NOT output_name)
+    set(output_name ${name})
+  endif()
+
+  get_target_property(is_framework ${name} FRAMEWORK)
+  if(is_framework)
+    get_target_property(buildtree_dir ${name} LIBRARY_OUTPUT_DIRECTORY)
+    if(buildtree_dir)
+      set(bundle_subdir ${output_name}.framework/Versions/${LLDB_FRAMEWORK_VERSION}/)
+    else()
+      message(SEND_ERROR "Framework target ${name} missing property for output directory. Cannot generate post-install steps.")
+      return()
+    endif()
+  else()
+    get_target_property(target_type ${name} TYPE)
+    if(target_type STREQUAL "EXECUTABLE")
+      set(buildtree_dir ${LLVM_RUNTIME_OUTPUT_INTDIR})
+    else()
+      # Only ever install shared libraries.
+      set(output_name "lib${output_name}.dylib")
+      set(buildtree_dir ${LLVM_LIBRARY_OUTPUT_INTDIR})
+    endif()
+  endif()
+
+  # Generate dSYM in symroot
+  set(dsym_name ${output_name}.dSYM)
+  if(is_framework)
+    set(dsym_name ${output_name}.framework.dSYM)
+  endif()
+  if(LLDB_DEBUGINFO_INSTALL_PREFIX)
+    # This makes the path absolute, so we must respect DESTDIR.
+    set(dsym_name "\$ENV\{DESTDIR\}${LLDB_DEBUGINFO_INSTALL_PREFIX}/${dsym_name}")
+  endif()
+
+  set(buildtree_name ${buildtree_dir}/${bundle_subdir}${output_name})
+  install(CODE "message(STATUS \"Externalize debuginfo: ${dsym_name}\")" COMPONENT ${name})
+  install(CODE "execute_process(COMMAND xcrun dsymutil -o=${dsym_name} ${buildtree_name})"
+          COMPONENT ${name})
+
+  # Strip distribution binary with -ST (removing debug symbol table entries and
+  # Swift symbols). Avoid CMAKE_INSTALL_DO_STRIP and llvm_externalize_debuginfo()
+  # as they can't be configured sufficiently.
+  set(installtree_name "\$ENV\{DESTDIR\}${install_prefix}/${bundle_subdir}${output_name}")
+  install(CODE "message(STATUS \"Stripping: ${installtree_name}\")" COMPONENT ${name})
+  install(CODE "execute_process(COMMAND xcrun strip -ST ${installtree_name})"
+          COMPONENT ${name})
+endfunction()
+
 # CMake's set_target_properties() doesn't allow to pass lists for RPATH
 # properties directly (error: "called with incorrect number of arguments").
 # Instead of defining two list variables each time, use this helper function.
 function(lldb_setup_rpaths name)
   cmake_parse_arguments(LIST "" "" "BUILD_RPATH;INSTALL_RPATH" ${ARGN})
   set_target_properties(${name} PROPERTIES
     BUILD_WITH_INSTALL_RPATH OFF
     BUILD_RPATH "${LIST_BUILD_RPATH}"
     INSTALL_RPATH "${LIST_INSTALL_RPATH}"
   )
 endfunction()
 No newline at end of file

lldb/cmake/modules/LLDBConfig.cmake

if(LLDB_BUILD_FRAMEWORK)
   if(CMAKE_VERSION VERSION_LESS 3.8)
     message(FATAL_ERROR "LLDB_BUILD_FRAMEWORK is not supported on CMake < 3.8")
   endif()
 
   set(LLDB_FRAMEWORK_VERSION A CACHE STRING "LLDB.framework version (default is A)")
   set(LLDB_FRAMEWORK_BUILD_DIR bin CACHE STRING "Output directory for LLDB.framework")
   set(LLDB_FRAMEWORK_INSTALL_DIR Library/Frameworks CACHE STRING "Install directory for LLDB.framework")
 
-  # Set designated directory for all dSYMs. Essentially, this emits the
-  # framework's dSYM outside of the framework directory.
-  if(LLVM_EXTERNALIZE_DEBUGINFO)
-    set(LLVM_EXTERNALIZE_DEBUGINFO_OUTPUT_DIR ${CMAKE_BINARY_DIR}/${CMAKE_CFG_INTDIR}/bin CACHE STRING
-        "Directory to emit dSYM files stripped from executables and libraries (Darwin Only)")
-  endif()
-endif()
+  # Essentially, emit the framework's dSYM outside of the framework directory.
+  set(LLDB_DEBUGINFO_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/${CMAKE_CFG_INTDIR}/bin CACHE STRING
 
 if (NOT CMAKE_SYSTEM_NAME MATCHES "Windows")
   set(LLDB_EXPORT_ALL_SYMBOLS 0 CACHE BOOL
     "Causes lldb to export all symbols when building liblldb.")
 else()
   # Windows doesn't support toggling this, so don't bother making it a
   # cache variable.
   set(LLDB_EXPORT_ALL_SYMBOLS 0)

lldb/cmake/modules/LLDBFramework.cmake

 
 # Used in llvm_add_library() to set default output directories for multi-config
 # generators. Overwrite to account for special framework output directory.
 set_output_directory(liblldb
   BINARY_DIR ${framework_target_dir}
   LIBRARY_DIR ${framework_target_dir}
 )
 
+lldb_add_post_install_steps_darwin(liblldb ${LLDB_FRAMEWORK_INSTALL_DIR})
+
 # Affects the layout of the framework bundle (default is macOS layout).
 if(IOS)
   set_target_properties(liblldb PROPERTIES
     XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET "${IPHONEOS_DEPLOYMENT_TARGET}")
 else()
   set_target_properties(liblldb PROPERTIES
     XCODE_ATTRIBUTE_MACOSX_DEPLOYMENT_TARGET "${MACOSX_DEPLOYMENT_TARGET}")
 endif()

lldb/source/API/CMakeLists.txt

 if ( CMAKE_SYSTEM_NAME MATCHES "Windows" )
   add_definitions( -DEXPORT_LIBLLDB )
 endif()
 
 get_property(LLDB_ALL_PLUGINS GLOBAL PROPERTY LLDB_PLUGINS)
 
 if(NOT LLDB_DISABLE_PYTHON)
   get_target_property(lldb_scripts_dir swig_wrapper BINARY_DIR)
   set(lldb_python_wrapper ${lldb_scripts_dir}/LLDBWrapPython.cpp)
 endif()
 
-if(LLDB_BUILD_FRAMEWORK AND LLVM_EXTERNALIZE_DEBUGINFO)
-  set(LLVM_EXTERNALIZE_DEBUGINFO_EXTENSION framework.dSYM)
+if(LLDB_BUILD_FRAMEWORK)
+  set(option_install_prefix INSTALL_PREFIX ${LLDB_FRAMEWORK_INSTALL_DIR})
 endif()
 
 add_lldb_library(liblldb SHARED
   SBAddress.cpp
   SBAttachInfo.cpp
   SBBlock.cpp
   SBBreakpoint.cpp
   SBBreakpointLocation.cpp
LINK_LIBS
     lldbInitialization
     lldbInterpreter
     lldbSymbol
     lldbTarget
     lldbUtility
     ${LLDB_ALL_PLUGINS}
   LINK_COMPONENTS
     Support
-  )
+
+  ${option_install_prefix}
 
 if (MSVC)
   set_source_files_properties(SBReproducer.cpp PROPERTIES COMPILE_FLAGS /bigobj)
 endif()
 
 if(lldb_python_wrapper)
   add_dependencies(liblldb swig_wrapper)
 

lldb/tools/argdumper/CMakeLists.txt

-add_lldb_tool(lldb-argdumper
+add_lldb_tool(lldb-argdumper ADD_TO_FRAMEWORK
   argdumper.cpp
 
   LINK_LIBS
     lldbUtility
-  )
-
-if(LLDB_BUILD_FRAMEWORK)
-  lldb_add_to_framework(lldb-argdumper)
-endif()

lldb/tools/darwin-debug/CMakeLists.txt

-add_lldb_tool(darwin-debug
+add_lldb_tool(darwin-debug ADD_TO_FRAMEWORK
   darwin-debug.cpp
-  )
-
-if(LLDB_BUILD_FRAMEWORK)
-  lldb_add_to_framework(darwin-debug)
-endif()

lldb/tools/debugserver/source/CMakeLists.txt

target_link_libraries(lldbDebugserverCommon
                         lldbDebugserverArchSupport
                         lldbDebugserverDarwin_DarwinLog
                         ${LIBCOMPRESSION})
   if(HAVE_LIBCOMPRESSION)
     set_property(TARGET lldbDebugserverCommon APPEND PROPERTY
                  COMPILE_DEFINITIONS HAVE_LIBCOMPRESSION)
   endif()
   set(LLVM_OPTIONAL_SOURCES ${lldbDebugserverCommonSources})
-  add_lldb_tool(debugserver
+  add_lldb_tool(debugserver ADD_TO_FRAMEWORK
     debugserver.cpp
-
-    LINK_LIBS
-      lldbDebugserverCommon
-
-    ENTITLEMENTS
-      ${entitlements}
-    )
+    LINK_LIBS lldbDebugserverCommon
+    ENTITLEMENTS ${entitlements}
 
   set_target_properties(debugserver PROPERTIES FOLDER "lldb libraries/debugserver")
 
-  if(LLDB_BUILD_FRAMEWORK)
-    lldb_add_to_framework(debugserver)
-  endif()
-
   if(IOS)
     set_property(TARGET lldbDebugserverCommon APPEND PROPERTY COMPILE_DEFINITIONS
       WITH_LOCKDOWN
       WITH_FBS
       WITH_BKS
       )
     set_property(TARGET debugserver APPEND PROPERTY COMPILE_DEFINITIONS
       WITH_LOCKDOWN