fix: install library and CMake package files, not just headers

Author: hsluoyz

CMakeLists.txt

@@ -23,10 +23,6 @@ if(APPLE AND NOT DEFINED CMAKE_OSX_DEPLOYMENT_TARGET)
     set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13" CACHE STRING "Minimum OS X deployment version")
 endif()
 
-if(WIN32)
-    add_compile_options("/bigobj")
-endif()
-
 ###############################################################################
 # Project definition.
 
@@ -43,6 +39,15 @@ set(CMAKE_MODULE_PATH
     ${PROJECT_SOURCE_DIR}/cmake/modules
 )
 
+# Some translation units exceed the default COFF section limit. This has to come
+# after project(), which is what defines WIN32 and the compiler id.
+if(MSVC)
+    add_compile_options("/bigobj")
+elseif(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+    # MinGW spells the same thing differently, and rejects /bigobj outright.
+    add_compile_options("-Wa,-mbig-obj")
+endif()
+
 ###############################################################################
 # Forbid in-source build.
 
@@ -78,6 +83,10 @@ endif()
 # Setting to C++ standard to C++17
 set(CMAKE_CXX_STANDARD 17)
 
+# Standard bin/lib/include/share layout, needed by the install rules below and
+# by the INSTALL_INTERFACE of the casbin target.
+include(GNUInstallDirs)
+
 ###############################################################################
 # Install external dependencies
 # Some required targets may be created by third-party CMake configs, which 
@@ -170,22 +179,66 @@ endif()
 # Install casbin
 
 if(CASBIN_INSTALL)
-    message(CHECK_START "[casbin]: Installing casbin ...")
-    export(
+    message(CHECK_START "[casbin]: Configuring the casbin installation ...")
+
+    include(CMakePackageConfigHelpers)
+
+    set(CASBIN_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/casbin"
+        CACHE STRING "Path to the installed casbin CMake package files")
+
+    # Installing headers
+    install(
+        DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/casbin
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    )
+
+    # Installing the library itself. Without this the installed tree only ever
+    # contained headers, so downstream projects had nothing to link against.
+    install(
         TARGETS casbin
+        EXPORT casbinTargets
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    )
+
+    # Installing the CMake package files so that find_package(casbin) works
+    # against the install prefix (and hence for package managers such as vcpkg)
+    # instead of only against the CMake User Package Registry.
+    install(
+        EXPORT casbinTargets
+        FILE casbinTargets.cmake
         NAMESPACE casbin::
-        FILE casbinConfig.cmake
+        DESTINATION ${CASBIN_INSTALL_CMAKEDIR}
+    )
+
+    configure_package_config_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/cmake/casbinConfig.cmake.in
+        ${CMAKE_CURRENT_BINARY_DIR}/casbinConfig.cmake
+        INSTALL_DESTINATION ${CASBIN_INSTALL_CMAKEDIR}
+    )
+
+    write_basic_package_version_file(
+        ${CMAKE_CURRENT_BINARY_DIR}/casbinConfigVersion.cmake
+        VERSION ${PROJECT_VERSION}
+        COMPATIBILITY SameMajorVersion
     )
 
-    # Installing headers
     install(
-        DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/casbin
-        DESTINATION include
+        FILES
+            ${CMAKE_CURRENT_BINARY_DIR}/casbinConfig.cmake
+            ${CMAKE_CURRENT_BINARY_DIR}/casbinConfigVersion.cmake
+        DESTINATION ${CASBIN_INSTALL_CMAKEDIR}
     )
 
-    set(CMAKE_EXPORT_PACKAGE_REGISTRY ON)
-    export(PACKAGE casbin)
+    # Also export the targets for the build tree, so that a project using
+    # FetchContent/add_subdirectory can consume casbin:: without installing.
+    export(
+        EXPORT casbinTargets
+        NAMESPACE casbin::
+        FILE ${CMAKE_CURRENT_BINARY_DIR}/casbinTargets.cmake
+    )
 
-    message(CHECK_PASS " The targets can now be imported with find_package(casbin)")
-    message(STATUS "[casbin]: Build the \"install\" target and add \"${CMAKE_INSTALL_PREFIX}/include\" to you PATH for casbin to work")
+    message(CHECK_PASS " done")
+    message(STATUS "[casbin]: Build the \"install\" target, then use find_package(casbin) and link against casbin::casbin")
 endif()

README.md

@@ -157,13 +157,11 @@ your may link your own targets against casbin's likewise:
 ```cmake
 add_executable(myexec main.cpp)
 
-target_link_libraries(myexec PRIVATE casbin)
-
-set(myexec_INCLUDE_DIR ${casbin_SOURCE_DIR}/include)
-target_include_directories(myexec PRIVATE ${myexec_INCLUDE_DIR})
+target_link_libraries(myexec PRIVATE casbin::casbin)
 ```
 
-Do remember to include `casbin_SOURCE_DIR/include` directory wherever casbin's functions are utilised.
+The `casbin::casbin` target carries its own include directories, so you don't need to
+add `casbin_SOURCE_DIR/include` yourself.
 
 ### With local installation
 
@@ -183,13 +181,8 @@ You may integrate casbin into your CMake project through `find_package`.
     cmake ..
     ```
 
-    **Note:** Look up for the logs of this step. And add the path indicated by the log into your PATH/project include directory.
-    The log message you're looking for should be something like this:
-    ```bash
-    [casbin]: Installing casbin ...
-    [casbin]: Installing casbin ... -  The targets can now be imported with find_package(casbin)
-    [casbin]: Build the "install" target and add "/usr/local/include" to you PATH for casbin to work
-    ```
+    Use `-DCMAKE_INSTALL_PREFIX=<path>` if you don't want to install into the default
+    location (`C:/Program Files/casbin` on Windows, `/usr/local` on Linux/macOS).
 
 3. After the project is configured successfully, build it:
     ```bash
@@ -209,12 +202,13 @@ You may integrate casbin into your CMake project through `find_package`.
     ```
     This will import all the targets exported by casbin to your project
 
-6. Link against casbin (Refer to Step 2's **Note** to get the value of `MY_INCLUDE_DIR` for your system):
+6. Link against casbin:
     ```cmake
-    set(MY_INCLUDE_DIR "/usr/local/include")
-    target_include_directories(MyTargetName PRIVATE ${MY_INCLUDE_DIR})
     target_link_libraries(MyTargetName PRIVATE casbin::casbin)
     ```
+    The include directories come with the target, so there is no need to set them by hand.
+    If you installed into a non-default prefix, point CMake at it with
+    `-DCMAKE_PREFIX_PATH=<path>`.
 
 ## Installation and Set-Up
 
@@ -249,13 +243,14 @@ You may integrate casbin into your CMake project through `find_package`.
     cmake --build . --target install
     ```
 
-    - For **Windows**, this will install `casbin.lib` to `<custom-path>/casbin-cpp/build/casbin`
-    and the headers to `C:/Program Files/casbin/include`.
-    - For Unix based OS i.e. **Linux and macOS**, this will install `casbin.a` to `<custom-path>/casbin-cpp/build/casbin` 
-    and the headers to `usr/local/include`.
+    This installs everything under `CMAKE_INSTALL_PREFIX` (`C:/Program Files/casbin` on Windows,
+    `/usr/local` on Linux/macOS by default):
+
+    - the library into `lib/` (`casbin.lib` on Windows, `libcasbin.a` on Linux/macOS),
+    - the headers into `include/casbin/`,
+    - the CMake package files into `lib/cmake/casbin/`, so that `find_package(casbin)` finds it.
 
-    You can add the respective include and lib paths
-    to the PATH environment variable to use casbin.
+    Pass `-DCMAKE_INSTALL_PREFIX=<path>` at configure time to install somewhere else.
 
 5. (OPTIONAL) To run the tests, issue the following command from `/build`:
 

casbin/CMakeLists.txt

@@ -74,21 +74,29 @@ set(CASBIN_SOURCE_FILES
 set(CMAKE_CXX_STANDARD 17)
 
 add_library(casbin STATIC ${CASBIN_SOURCE_FILES})
+# So that add_subdirectory()/FetchContent consumers can use the same name as
+# find_package() consumers.
+add_library(casbin::casbin ALIAS casbin)
 
 target_precompile_headers(casbin PRIVATE ${CASBIN_INCLUDE_DIR}/casbin/pch.h)
-target_include_directories(casbin PRIVATE ${CASBIN_INCLUDE_DIR})
+
+# Consumers must see the headers too, both from the build tree and from an
+# installed prefix, otherwise find_package(casbin) hands out a target that
+# cannot be compiled against.
+target_include_directories(casbin
+    PUBLIC
+        $<BUILD_INTERFACE:${CASBIN_INCLUDE_DIR}>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
 target_link_libraries(casbin PUBLIC nlohmann_json::nlohmann_json)
 
-set_target_properties(casbin PROPERTIES 
-    PREFIX ""
+# Keep the platform default naming (libcasbin.a / casbin.lib) so that the
+# installed library looks like every other system library and can be picked up
+# with a plain -lcasbin.
+set_target_properties(casbin PROPERTIES
     VERSION ${PROJECT_VERSION}
 )
 
-if(WIN32 OR MSVC)
-    set_target_properties(casbin PROPERTIES SUFFIX ".lib")
-elseif(UNIX)
-    set_target_properties(casbin PROPERTIES 
-        SUFFIX ".a"
-        POSITION_INDEPENDENT_CODE ON
-    )
+if(UNIX)
+    set_target_properties(casbin PROPERTIES POSITION_INDEPENDENT_CODE ON)
 endif()

cmake/casbinConfig.cmake.in

@@ -0,0 +1,24 @@
+#  Copyright 2023 The casbin Authors. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+
+# casbin::casbin links nlohmann_json publicly, so consumers need it as well.
+find_dependency(nlohmann_json 3.10.1)
+
+include("${CMAKE_CURRENT_LIST_DIR}/casbinTargets.cmake")
+
+check_required_components(casbin)

cmake/modules/Findjson.cmake

@@ -14,13 +14,26 @@
 #  limitations under the License.
 include(FetchContent)
 
-set(JSON_Install ON)
+# Prefer a nlohmann_json that is already available on the system (this is what
+# package managers such as vcpkg or Conan provide); only download a copy when
+# there is none, so that packaged builds don't vendor their own.
+option(CASBIN_FETCH_JSON "Always download nlohmann_json instead of using the system one" OFF)
 
-FetchContent_Declare(
-  json
-  GIT_REPOSITORY https://github.com/nlohmann/json.git
-  GIT_TAG v3.11.2
-  DOWNLOAD_EXTRACT_TIMESTAMP FALSE
-)
+if(NOT CASBIN_FETCH_JSON)
+    find_package(nlohmann_json 3.10.1 CONFIG QUIET)
+endif()
 
-FetchContent_MakeAvailable(json)
+if(NOT nlohmann_json_FOUND)
+    set(JSON_Install ON)
+
+    FetchContent_Declare(
+      json
+      GIT_REPOSITORY https://github.com/nlohmann/json.git
+      GIT_TAG v3.11.2
+      DOWNLOAD_EXTRACT_TIMESTAMP FALSE
+    )
+
+    FetchContent_MakeAvailable(json)
+endif()
+
+set(json_FOUND TRUE)