Fix CMake export for external LZ4; doc vcpkg overlays

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.15)
 cmake_policy(SET CMP0091 NEW) # enable new "MSVC runtime library selection" (https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)
 
 project(libCZI 
-      VERSION 0.69.0
+      VERSION 0.69.1
       HOMEPAGE_URL "https://github.com/ZEISS/libczi"
       DESCRIPTION "libCZI is an Open Source Cross-Platform C++ library to read and write CZI")
 

cmake/libCZIConfig.cmake.in

@@ -14,6 +14,12 @@
 # Flags baked in at install time:
 set(LIBCZI_BUILD_AZURESDK_BASED_STREAM @LIBCZI_BUILD_AZURESDK_BASED_STREAM@)
 set(LIBCZI_BUILD_CURL_BASED_STREAM     @LIBCZI_BUILD_CURL_BASED_STREAM@)
+# Keep the experimental chunked-compression and LZ4 dependency state available
+# to consumers of the installed CMake package. When libCZI exports a target that
+# links to an external LZ4 target, downstream find_package(libCZI) must also load
+# the lz4 package before libCZITargets.cmake is included.
+set(LIBCZI_BUILD_EXPERIMENTAL_CHUNKED_COMPRESSION @LIBCZI_BUILD_EXPERIMENTAL_CHUNKED_COMPRESSION@)
+set(LIBCZI_BUILD_PREFER_EXTERNALPACKAGE_LZ4 @LIBCZI_BUILD_PREFER_EXTERNALPACKAGE_LZ4@)
 
 include(CMakeFindDependencyMacro)
 
@@ -22,6 +28,10 @@ include(CMakeFindDependencyMacro)
 find_dependency(zstd CONFIG REQUIRED)
 find_dependency(Eigen3 CONFIG REQUIRED)
 
+if(LIBCZI_BUILD_EXPERIMENTAL_CHUNKED_COMPRESSION AND LIBCZI_BUILD_PREFER_EXTERNALPACKAGE_LZ4)
+  find_dependency(lz4 CONFIG REQUIRED)
+endif()
+
 if(LIBCZI_BUILD_AZURESDK_BASED_STREAM)
   find_dependency(azure-core-cpp CONFIG)
   find_dependency(azure-identity-cpp CONFIG)

docs/source/pages/building.rst

@@ -152,13 +152,71 @@ For building with a downloaded libcurl, the following packages is needed:
 
     sudo apt-get install libssl-dev
 
-Alternatively, the cross-platform package-manager `vcpkg <https://vcpkg.io/en/>`_ can be used to manage the dependencies. For building on Windows,
-the following command brings in the necessary dependencies:
+Using vcpkg
+-----------
+
+Alternatively, the cross-platform package-manager `vcpkg <https://vcpkg.io/en/>`_
+can be used to build and install libCZI. For example:
+
+.. code:: bash
+
+    vcpkg install libczi
+
+Optional vcpkg features can be selected with the usual feature syntax:
+
+.. code:: bash
+
+    vcpkg install "libczi[curl]"
+
+For building libCZI itself on Windows, vcpkg can also be used to bring in
+dependencies such as RapidJSON and curl:
 
 .. code:: bash
 
     vcpkg install rapidjson 'curl[ssl]'
 
+Experimental functionality and overlay ports
+--------------------------------------------
+
+The vcpkg registry port for libCZI is intended to provide stable, generally
+supported build configurations. Experimental libCZI features may be unsuitable
+for the registry port while their API, ABI, file format, or dependencies are
+still subject to change.
+
+If you want to consume an experimental feature through vcpkg, use an overlay
+port. An overlay port is a local copy of a vcpkg port that takes precedence over
+the registry version for a single vcpkg invocation. This lets a project opt in to
+experimental libCZI build switches without requiring those switches to be part of
+the public vcpkg registry.
+
+A typical workflow is:
+
+.. code:: bash
+
+    mkdir -p vcpkg-overlays/ports
+    cp -r <vcpkg-root>/ports/libczi vcpkg-overlays/ports/libczi
+
+Then edit the copied ``vcpkg-overlays/ports/libczi`` port to expose the desired
+feature and map it to the corresponding libCZI CMake options. For experimental
+chunked compression, the relevant options are:
+
+.. code:: cmake
+
+    LIBCZI_BUILD_ENABLE_EXPERIMENTAL_FUNCTIONALITY
+    LIBCZI_BUILD_EXPERIMENTAL_CHUNKED_COMPRESSION
+    LIBCZI_BUILD_PREFER_EXTERNALPACKAGE_LZ4
+
+The overlay port should also declare the additional dependency on ``lz4``. It
+can then be used with:
+
+.. code:: bash
+
+    vcpkg install "libczi[experimental-chunked-compression]" \
+        --overlay-ports=./vcpkg-overlays/ports
+
+Projects using overlay ports should treat the resulting binaries and CZI files
+as experimental and keep the overlay definition under their own version control.
+
 
 Building the documentation
 --------------------------

docs/source/pages/version_history.md

@@ -56,4 +56,5 @@ Version history
  0.67.5             | [168](https://github.com/ZEISS/libczi/pull/168)      | fix bug with zstd1-decoding in case of pixeltype BGR48
  0.67.6             | [169](https://github.com/ZEISS/libczi/pull/169)      | fix CI/CD build
  0.68.0             | [171](https://github.com/ZEISS/libczi/pull/171)      | add bitmap creation from compressed subblock data and attachment statistics APIs; improve test integration and CI workflow
- 0.69.0             | [172](https://github.com/ZEISS/libczi/pull/172)      | add EXPERIMENTAL chunked-compression
+ 0.69.0             | [172](https://github.com/ZEISS/libczi/pull/172)      | add EXPERIMENTAL chunked-compression
+ 0.69.1             | [174](https://github.com/ZEISS/libczi/pull/174)      | fix CMake package export for external LZ4 and document vcpkg overlay ports