From b8ba6d39bb316c9b38d66fd3007c0a48cb74e6bb Mon Sep 17 00:00:00 2001
From: Ihor Dutchak <ihor.youw@gmail.com>
Date: Sun, 12 Mar 2023 16:46:46 +0200
Subject: [PATCH] doc: Shared+Static build for CMake

Document the recommended way to build both Shared and Static libraries of HIDAPI using CMake.

Closes: #424
---
 BUILD.cmake.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/BUILD.cmake.md b/BUILD.cmake.md
index 743a95f19..cc8e23ece 100644
--- a/BUILD.cmake.md
+++ b/BUILD.cmake.md
@@ -233,3 +233,45 @@ Advanced:
       target_compile_definitions(hidapi_libusb PRIVATE NO_ICONV)
     endif()
     ```
+
+## Both Shared and Static build
+
+If you're a former (or present) user of Autotools build scripts for HIDAPI, or you're a package manager maintainer and you're often working with those - you're likely asking how to build HIDAPI with CMake and get both Shared and Static libraries (as would be done by Autotools: `./configure --enable-static --enable-shared ...`).
+
+CMake doesn't have such option of-the-box and it is decided not to introduce any manual CMake-level workarounds for HIDAPI on this matter
+
+If you want to mimic the Autotools behavior, it is possible by building/installing first the static version of the library and then shared version of the library. The installation folder (`CMAKE_INSTALL_PREFIX`) should point to the same directory for both variants, that way:
+- both static and shared library binaries will be available and usable;
+- a single header file(s) for both of them;
+- Autotools/pkg-config (`.pc`) files will be generated and usable as if generated by Autotools natively and build configured with both `-enable-static --enable-shared` options;
+- CMake package scripts will be generated and fully usable, but _only the last build installed_, i.e. if the last was installed Shared version of the binary - CMake targets found by `find_package(hidapi)` would point to a Shared binaries.
+
+There is a historical discussion, why such solution is simplest/preferable: https://github.com/libusb/hidapi/issues/424
+
+#### TL;DR/Sample
+
+```sh
+# First - configure/build
+
+# Static libraries
+cmake -S <HIDAPI source dir> -B "<build dir>/static" -DCMAKE_INSTALL_PREFIX=<where you need to install HIDAPI> -DBUILD_SHARED_LIBS=FALSE
+cmake --build "<build dir>/static"
+# Shared libraries
+cmake -S <HIDAPI source dir> -B "<build dir>/static" -DCMAKE_INSTALL_PREFIX=<where you need to install HIDAPI> -DBUILD_SHARED_LIBS=TRUE
+cmake --build "<build dir>/shared"
+
+# (Optionally) change the installation destination
+# NOTE1: this is supported by CMake only on some platforms
+# NOTE2: this is *not required*, if the `$pkgdir` already passed as `CMAKE_INSTALL_PREFIX` above
+export DESTDIR="$pkgdir"
+
+#
+# Install the libraries
+# NOTE: order of installation matters - install Shared variant the last
+
+# Static libraries
+cmake --install "<build dir>/static"
+# Shared libraries
+cmake --install "<build dir>/shared"
+
+```