ENH: Modernize CMake packaging to match vtkAddon (supersedes #27)

CMake/qRestAPIConfig.cmake.in

@@ -1,14 +1,16 @@
+# qRestAPI package configuration file for use from a build tree.
 
-# Import qRestAPI targets
-if(NOT qRestAPI_EXPORTS_INCLUDED)
-  include("@qRestAPI_BINARY_DIR@/qRestAPIExports.cmake")
-  set(qRestAPI_EXPORTS_INCLUDED 1)
-endif()
+# Re-resolve the Qt dependency first, so the imported target's link interface
+# is satisfied for downstream consumers.
+include(CMakeFindDependencyMacro)
+find_dependency(Qt@qRestAPI_QT_VERSION@ COMPONENTS @qRestAPI_QT_COMPONENTS@)
 
-set(qRestAPI_LIBRARIES "qRestAPI")
+include("@CMAKE_CURRENT_BINARY_DIR@/qRestAPITargets.cmake")
 
-set(qRestAPI_INCLUDE_DIRS "@qRestAPI_INCLUDE_DIRS_CONFIG@")
-set(qRestAPI_LIBRARY_DIRS "@qRestAPI_LIBRARY_DIRS_CONFIG@")
+set(qRestAPI_CMAKE_DIR "@qRestAPI_CMAKE_DIR@")
 
-# The location of the UseqRestAPI.cmake file.
-set(qRestAPI_USE_FILE "@qRestAPI_USE_FILE_CONFIG@")
+# Legacy variables (kept for backward compatibility; prefer the imported
+# qRestAPI target).
+set(qRestAPI_LIBRARIES qRestAPI)
+set(qRestAPI_INCLUDE_DIRS "@qRestAPI_INCLUDE_DIRS@")
+set(qRestAPI_LIBRARY_DIRS "@qRestAPI_LIBRARY_DIRS@")

CMake/qRestAPIInstallConfig.cmake.in

@@ -0,0 +1,23 @@
+# qRestAPI package configuration file for use from an install tree.
+#
+# Generated with configure_package_config_file(): PACKAGE_PREFIX_DIR is computed
+# at load time from the location of this file, so the install tree is
+# relocatable (no absolute paths are baked in).
+@PACKAGE_INIT@
+
+# Re-resolve the Qt dependency first, so the imported target's link interface
+# is satisfied for downstream consumers.
+include(CMakeFindDependencyMacro)
+find_dependency(Qt@qRestAPI_QT_VERSION@ COMPONENTS @qRestAPI_QT_COMPONENTS@)
+
+include("${CMAKE_CURRENT_LIST_DIR}/qRestAPITargets.cmake")
+
+set(qRestAPI_CMAKE_DIR "${CMAKE_CURRENT_LIST_DIR}")
+
+# Legacy variables (kept for backward compatibility; prefer the imported
+# qRestAPI target).
+set(qRestAPI_LIBRARIES qRestAPI)
+set_and_check(qRestAPI_INCLUDE_DIRS "@PACKAGE_qRestAPI_INSTALL_INCLUDE_DIR@")
+set_and_check(qRestAPI_LIBRARY_DIRS "@PACKAGE_qRestAPI_INSTALL_LIB_DIR@")
+
+check_required_components(qRestAPI)

CMakeLists.txt

@@ -1,41 +1,108 @@
-cmake_minimum_required(VERSION 3.5.0)
+cmake_minimum_required(VERSION 3.16.3)
 
 project(qRestAPI)
 
+# --------------------------------------------------------------------------
+# CMake variables
+# --------------------------------------------------------------------------
 set(CMAKE_INCLUDE_CURRENT_DIR 1)
-set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE 1)
 set(CMAKE_POSITION_INDEPENDENT_CODE 1)
 
+# --------------------------------------------------------------------------
+# Directories
+# --------------------------------------------------------------------------
+#
+# CMake: holds the package-config templates (*Config.cmake.in).
+#
+set(${PROJECT_NAME}_CMAKE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/CMake)
+#
+# Include
+#
+set(${PROJECT_NAME}_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
+  CACHE INTERNAL "${PROJECT_NAME} include dirs" FORCE)
+#
+# Library
+#
+set(${PROJECT_NAME}_LIBRARY_DIRS ${CMAKE_CURRENT_BINARY_DIR}
+  CACHE INTERNAL "${PROJECT_NAME} library dirs" FORCE)
+
+# --------------------------------------------------------------------------
+# Options
+# --------------------------------------------------------------------------
 option(BUILD_SHARED_LIBS "Build shared library" ON)
 option(BUILD_TESTING "Test the project" ON)
 
-set(qRestAPI_QT_VERSION "4" CACHE STRING "Expected Qt version")
-mark_as_advanced(qRestAPI_QT_VERSION)
-set_property(CACHE qRestAPI_QT_VERSION PROPERTY STRINGS 4 5 6)
-if(NOT (qRestAPI_QT_VERSION VERSION_EQUAL "4" OR qRestAPI_QT_VERSION VERSION_EQUAL "5" OR qRestAPI_QT_VERSION VERSION_EQUAL "6"))
-  message(FATAL_ERROR "Expected value for qRestAPI_QT_VERSION is either '4', '5' or '6'")
+# --------------------------------------------------------------------------
+# Install directories
+# --------------------------------------------------------------------------
+# These may be set by a parent project (e.g. a superbuild) before this project
+# is added. When not set, sensible standalone defaults are used.
+if(NOT DEFINED ${PROJECT_NAME}_INSTALL_BIN_DIR)
+  set(${PROJECT_NAME}_INSTALL_BIN_DIR bin)
+endif()
+if(NOT DEFINED ${PROJECT_NAME}_INSTALL_LIB_DIR)
+  set(${PROJECT_NAME}_INSTALL_LIB_DIR lib/${PROJECT_NAME})
+endif()
+if(NOT DEFINED ${PROJECT_NAME}_INSTALL_INCLUDE_DIR)
+  set(${PROJECT_NAME}_INSTALL_INCLUDE_DIR include/${PROJECT_NAME})
+endif()
+if(NOT DEFINED ${PROJECT_NAME}_INSTALL_CMAKE_DIR)
+  set(${PROJECT_NAME}_INSTALL_CMAKE_DIR cmake/${PROJECT_NAME})
 endif()
 
-if(qRestAPI_QT_VERSION VERSION_GREATER "4")
-  set(QT${qRestAPI_QT_VERSION}_INSTALL_PREFIX "" CACHE PATH "The install location of Qt${qRestAPI_QT_VERSION}")
-  set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ${QT${qRestAPI_QT_VERSION}_INSTALL_PREFIX})
+# Install the development files (headers, CMake package config, exported
+# targets) in addition to the runtime library. OFF by default so a plain
+# install ships only the runtime; turn ON for packaging / standalone install
+# trees. (CMP0077 is NEW at this cmake_minimum_required, so a parent project may
+# still override this before add_subdirectory().)
+option(${PROJECT_NAME}_INSTALL_DEVELOPMENT
+  "Install ${PROJECT_NAME} development files (headers, CMake package config, exported targets)" OFF)
+
+# Backward compatibility: honor the deprecated, inverted
+# ${PROJECT_NAME}_INSTALL_NO_DEVELOPMENT if a consumer still sets it.
+if(DEFINED ${PROJECT_NAME}_INSTALL_NO_DEVELOPMENT)
+  message(DEPRECATION
+    "${PROJECT_NAME}_INSTALL_NO_DEVELOPMENT is deprecated; use ${PROJECT_NAME}_INSTALL_DEVELOPMENT (inverted value).")
+  if(${PROJECT_NAME}_INSTALL_NO_DEVELOPMENT)
+    set(${PROJECT_NAME}_INSTALL_DEVELOPMENT OFF CACHE BOOL "" FORCE)
+  else()
+    set(${PROJECT_NAME}_INSTALL_DEVELOPMENT ON CACHE BOOL "" FORCE)
+  endif()
 endif()
 
-if(qRestAPI_QT_VERSION VERSION_GREATER "4")
-  set(qRestAPI_QT${qRestAPI_QT_VERSION}_COMPONENTS Core Gui Network Qml Test)
-  find_package(Qt${qRestAPI_QT_VERSION} COMPONENTS ${qRestAPI_QT${qRestAPI_QT_VERSION}_COMPONENTS} REQUIRED)
-else()
-  # HACK: QtXml is required because of "http://www.richelbilderbeek.nl/CppLinkErrorUndefinedReferenceToQListData.htm"
-  find_package(Qt4 4.6.2 COMPONENTS QtCore QtGui QtNetwork QtScript QtXml QtTest REQUIRED)
-  include(${QT_USE_FILE})
+# --------------------------------------------------------------------------
+# Dependencies
+# --------------------------------------------------------------------------
+
+#
+# Qt
+#
+set(${PROJECT_NAME}_QT_VERSION "5" CACHE STRING "Expected Qt version (5 or 6)")
+mark_as_advanced(${PROJECT_NAME}_QT_VERSION)
+set_property(CACHE ${PROJECT_NAME}_QT_VERSION PROPERTY STRINGS 5 6)
+if(NOT (${PROJECT_NAME}_QT_VERSION VERSION_EQUAL "5" OR ${PROJECT_NAME}_QT_VERSION VERSION_EQUAL "6"))
+  message(FATAL_ERROR "Expected value for ${PROJECT_NAME}_QT_VERSION is either '5' or '6'")
 endif()
 
+set(QT${${PROJECT_NAME}_QT_VERSION}_INSTALL_PREFIX "" CACHE PATH "The install location of Qt${${PROJECT_NAME}_QT_VERSION}")
+set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ${QT${${PROJECT_NAME}_QT_VERSION}_INSTALL_PREFIX})
+
+# Qt components used through the public interface of the library. They are
+# recorded here so the generated package config can re-resolve them through
+# find_dependency() for downstream consumers. The Test component is required
+# only when building the tests (see Testing/CMakeLists.txt).
+set(${PROJECT_NAME}_QT_COMPONENTS Gui Network Qml)
+find_package(Qt${${PROJECT_NAME}_QT_VERSION} COMPONENTS Core ${${PROJECT_NAME}_QT_COMPONENTS} REQUIRED)
+
 if(BUILD_SHARED_LIBS)
-  set(qRestAPI_STATIC OFF)
+  set(${PROJECT_NAME}_STATIC OFF)
 else()
-  set(qRestAPI_STATIC ON)
+  set(${PROJECT_NAME}_STATIC ON)
 endif()
 
+# --------------------------------------------------------------------------
+# Configure headers
+# --------------------------------------------------------------------------
 configure_file(
   qRestAPI_Export.h.in
   ${CMAKE_CURRENT_BINARY_DIR}/qRestAPI_Export.h
@@ -61,24 +128,95 @@ set(KIT_MOC_SRCS
   qRestResult.h
   )
 
-if(qRestAPI_QT_VERSION VERSION_GREATER "5")
+if(${PROJECT_NAME}_QT_VERSION VERSION_GREATER "5")
   qt_wrap_cpp(KIT_MOC_OUTPUT ${KIT_MOC_SRCS})
-elseif(qRestAPI_QT_VERSION VERSION_GREATER "4")
-  qt5_wrap_cpp(KIT_MOC_OUTPUT ${KIT_MOC_SRCS})
 else()
-  QT4_WRAP_CPP(KIT_MOC_OUTPUT ${KIT_MOC_SRCS})
+  qt5_wrap_cpp(KIT_MOC_OUTPUT ${KIT_MOC_SRCS})
 endif()
 
+# --------------------------------------------------------------------------
+# Build qRestAPI library
+# --------------------------------------------------------------------------
 add_library(${PROJECT_NAME} ${KIT_SRCS} ${KIT_MOC_OUTPUT})
-if(qRestAPI_QT_VERSION VERSION_GREATER "4")
-  target_link_libraries(${PROJECT_NAME} Qt${qRestAPI_QT_VERSION}::Gui Qt${qRestAPI_QT_VERSION}::Network Qt${qRestAPI_QT_VERSION}::Qml)
-else()
-  target_link_libraries(${PROJECT_NAME} ${QT_LIBRARIES})
+
+# Public usage requirements: consumers get the include directories through the
+# imported target, resolved differently for the build tree and the install tree.
+target_include_directories(${PROJECT_NAME} PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
+  $<INSTALL_INTERFACE:${${PROJECT_NAME}_INSTALL_INCLUDE_DIR}>
+  )
+
+target_link_libraries(${PROJECT_NAME} PUBLIC
+  Qt${${PROJECT_NAME}_QT_VERSION}::Gui
+  Qt${${PROJECT_NAME}_QT_VERSION}::Network
+  Qt${${PROJECT_NAME}_QT_VERSION}::Qml)
+
+# --------------------------------------------------------------------------
+# Export targets for a build tree
+# --------------------------------------------------------------------------
+export(TARGETS ${PROJECT_NAME}
+  FILE ${CMAKE_CURRENT_BINARY_DIR}/qRestAPITargets.cmake)
+
+# --------------------------------------------------------------------------
+# Install library
+# --------------------------------------------------------------------------
+install(TARGETS ${PROJECT_NAME}
+  EXPORT qRestAPITargets
+  RUNTIME DESTINATION ${${PROJECT_NAME}_INSTALL_BIN_DIR} COMPONENT RuntimeLibraries
+  LIBRARY DESTINATION ${${PROJECT_NAME}_INSTALL_LIB_DIR} COMPONENT RuntimeLibraries
+  ARCHIVE DESTINATION ${${PROJECT_NAME}_INSTALL_LIB_DIR} COMPONENT Development
+  )
+
+# --------------------------------------------------------------------------
+# Configure package config file for the build tree
+# --------------------------------------------------------------------------
+configure_file(
+  ${${PROJECT_NAME}_CMAKE_DIR}/qRestAPIConfig.cmake.in
+  ${CMAKE_CURRENT_BINARY_DIR}/qRestAPIConfig.cmake @ONLY)
+
+# --------------------------------------------------------------------------
+# Install development files
+# --------------------------------------------------------------------------
+if(${PROJECT_NAME}_INSTALL_DEVELOPMENT)
+
+  # Public headers (exclude private *_p.h headers)
+  file(GLOB headers "${CMAKE_CURRENT_SOURCE_DIR}/*.h")
+  list(FILTER headers EXCLUDE REGEX "_p\\.h$")
+  install(
+    FILES ${headers}
+    DESTINATION ${${PROJECT_NAME}_INSTALL_INCLUDE_DIR} COMPONENT Development)
+
+  file(GLOB headers "${CMAKE_CURRENT_BINARY_DIR}/*.h")
+  install(
+    FILES ${headers}
+    DESTINATION ${${PROJECT_NAME}_INSTALL_INCLUDE_DIR} COMPONENT Development)
+
+  # Relocatable package config file for the install tree
+  include(CMakePackageConfigHelpers)
+  configure_package_config_file(
+    ${${PROJECT_NAME}_CMAKE_DIR}/qRestAPIInstallConfig.cmake.in
+    ${CMAKE_CURRENT_BINARY_DIR}/install/qRestAPIConfig.cmake
+    INSTALL_DESTINATION ${${PROJECT_NAME}_INSTALL_CMAKE_DIR}
+    PATH_VARS ${PROJECT_NAME}_INSTALL_INCLUDE_DIR ${PROJECT_NAME}_INSTALL_LIB_DIR
+    )
+
+  install(
+    FILES ${CMAKE_CURRENT_BINARY_DIR}/install/qRestAPIConfig.cmake
+    DESTINATION ${${PROJECT_NAME}_INSTALL_CMAKE_DIR} COMPONENT Development)
+
+  # Exported targets for the install tree
+  install(
+    EXPORT qRestAPITargets
+    FILE qRestAPITargets.cmake
+    DESTINATION ${${PROJECT_NAME}_INSTALL_CMAKE_DIR} COMPONENT Development)
+
 endif()
 
-include(CTest)
+# --------------------------------------------------------------------------
+# Testing
+# --------------------------------------------------------------------------
 if(BUILD_TESTING)
+  include(CTest)
   add_subdirectory(Testing)
 endif()
-
-include(CMake/GenerateqRestAPIConfig.cmake)

README.md

@@ -16,17 +16,9 @@ It provides the following interfaces:
 
 ## Prerequisites
 
- * [Qt](https://www.qt.io/) 4.x, 5.x, or 6.x
+ * [Qt](https://www.qt.io/) 5.x or 6.x
  * [CMake](http://www.cmake.org)
 
-## How to build using Qt 4.x
-
-    git clone git://github.com/commontk/qRestAPI.git
-    mkdir qRestAPI-build
-    cd qRestAPI-build
-    cmake -DQT_QMAKE_EXECUTABLE:FILEPATH=/path/to/qmake ../qRestAPI
-    make -j4
-
 ## How to build using Qt 5.x
 
     git clone git://github.com/commontk/qRestAPI.git
@@ -43,6 +35,32 @@ It provides the following interfaces:
     cmake -DQT6_INSTALL_PREFIX:PATH=/path/to/QtX.Y.Z/X.Y.Z/gcc_64 ../qRestAPI
     make -j4
 
+## Installing / packaging
+
+By default only the runtime library is installed. To also install the
+development files (headers, exported CMake targets and the package config
+file) — e.g. when building a package or a standalone install tree — turn on
+`qRestAPI_INSTALL_DEVELOPMENT`:
+
+    cmake -DqRestAPI_INSTALL_DEVELOPMENT=ON -DCMAKE_INSTALL_PREFIX=/path/to/prefix ../qRestAPI
+    make install
+
+The install tree is relocatable. Downstream projects consume it with:
+
+    find_package(qRestAPI REQUIRED)
+    target_link_libraries(MyTarget PRIVATE qRestAPI)
+
+The following variables let a parent project (typically a superbuild) override
+the install layout; each defaults to a standalone-friendly value when unset:
+
+| Variable                       | Default            |
+|--------------------------------|--------------------|
+| `qRestAPI_INSTALL_DEVELOPMENT` | `OFF`              |
+| `qRestAPI_INSTALL_BIN_DIR`     | `bin`              |
+| `qRestAPI_INSTALL_LIB_DIR`     | `lib/qRestAPI`     |
+| `qRestAPI_INSTALL_INCLUDE_DIR` | `include/qRestAPI` |
+| `qRestAPI_INSTALL_CMAKE_DIR`   | `cmake/qRestAPI`   |
+
 ## Testing
 
 To run tests checking that queries can successfully be executed.