feat(cpp): add standard installation layout and native packaging support

.github/workflows/cpp-packaging.yml

@@ -0,0 +1,128 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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
+#
+#     https://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.
+
+name: Cpp-Packaging
+
+on:
+  push:
+    branches:
+      - develop
+      - rc/**
+    paths:
+      - '.github/workflows/cpp-packaging.yml'
+      - 'cpp/**'
+      - 'packaging/**'
+      - 'LICENSE'
+      - 'NOTICE'
+  pull_request:
+    branches:
+      - develop
+      - rc/**
+    paths:
+      - '.github/workflows/cpp-packaging.yml'
+      - 'cpp/**'
+      - 'packaging/**'
+      - 'LICENSE'
+      - 'NOTICE'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deb:
+    name: Debian package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Install packaging tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential cmake ninja-build pkg-config dpkg-dev uuid-dev
+
+      - name: Configure and build
+        run: |
+          cmake -S cpp -B build/deb -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_TEST=OFF \
+            -DBUILD_TOOLS=ON \
+            -DTSFILE_ENABLE_CPACK=ON \
+            -DTSFILE_DEPENDENCY_SOURCE=AUTO \
+            -DTSFILE_ENABLE_NATIVE_ARCH=OFF
+          cmake --build build/deb --parallel
+
+      - name: Build and inspect DEB packages
+        run: |
+          cpack --config build/deb/CPackConfig.cmake -G DEB
+          ls -lh ./*.deb
+          for package in ./*.deb; do
+            dpkg-deb --info "$package"
+            dpkg-deb --contents "$package" | grep -E '(/libtsfile|/tsfile-cli|TsFileConfig|libtsfile.pc)' || true
+          done
+
+      - name: Upload DEB packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: tsfile-deb
+          path: '*.deb'
+          if-no-files-found: error
+
+  rpm:
+    name: Fedora package
+    runs-on: ubuntu-24.04
+    container: fedora:latest
+    timeout-minutes: 30
+    steps:
+      - name: Install build and packaging tools
+        run: |
+          dnf install -y \
+            cmake gcc-c++ make ninja-build pkgconf-pkg-config rpm-build \
+            git curl tar xz unzip gzip libuuid-devel
+
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Configure and build
+        run: |
+          cmake -S cpp -B build/rpm -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_TEST=OFF \
+            -DBUILD_TOOLS=ON \
+            -DTSFILE_ENABLE_CPACK=ON \
+            -DTSFILE_DEPENDENCY_SOURCE=AUTO \
+            -DTSFILE_ENABLE_NATIVE_ARCH=OFF
+          cmake --build build/rpm --parallel
+
+      - name: Build and inspect RPM packages
+        run: |
+          cpack --config build/rpm/CPackConfig.cmake -G RPM
+          ls -lh ./*.rpm
+          for package in ./*.rpm; do
+            rpm -qip "$package"
+            rpm -qlp "$package" | grep -E '(/libtsfile|/tsfile-cli|TsFileConfig|libtsfile.pc)' || true
+          done
+
+      - name: Upload RPM packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: tsfile-rpm
+          path: '*.rpm'
+          if-no-files-found: error

cpp/CMakeLists.txt

@@ -34,6 +34,25 @@ if (POLICY CMP0074)
 endif ()
 set(TsFile_CPP_VERSION 2.3.2.dev)
 
+include(GNUInstallDirs)
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/TsFilePublicHeaders.cmake)
+
+# The package version identifies the source release. Development suffixes are
+# intentionally removed from generated package metadata and never enter the
+# SONAME.
+string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TSFILE_PACKAGE_VERSION
+        "${TsFile_CPP_VERSION}")
+if ("${TSFILE_PACKAGE_VERSION}" STREQUAL "")
+    message(FATAL_ERROR
+            "TsFile_CPP_VERSION must start with a semantic version: "
+            "${TsFile_CPP_VERSION}")
+endif ()
+set(TSFILE_ABI_VERSION "1" CACHE STRING
+        "TsFile shared-library ABI epoch (changes only on ABI breaks)")
+if (NOT TSFILE_ABI_VERSION MATCHES "^[0-9]+$")
+    message(FATAL_ERROR "TSFILE_ABI_VERSION must be a positive integer")
+endif ()
+
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/DependencySource.cmake)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
@@ -64,10 +83,18 @@ endif ()
 message("cmake using: USE_CPP11=${USE_CPP11}")
 # MSVC has no /std:c++11; CMake maps this to the closest supported standard
 # (C++14 default on MSVC), which compiles the C++11 codebase fine.
-set(CMAKE_CXX_STANDARD 11)
+set(TSFILE_CXX_STANDARD "11" CACHE STRING
+        "C++ language standard used to build TsFile (11, 14, or 17)")
+set_property(CACHE TSFILE_CXX_STANDARD PROPERTY STRINGS 11 14 17)
+if (NOT TSFILE_CXX_STANDARD MATCHES "^(11|14|17)$")
+    message(FATAL_ERROR
+            "TSFILE_CXX_STANDARD must be one of 11, 14, or 17")
+endif ()
+set(CMAKE_CXX_STANDARD ${TSFILE_CXX_STANDARD})
 set(CMAKE_CXX_STANDARD_REQUIRED OFF)
 if (NOT MSVC)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+    set(CMAKE_CXX_FLAGS
+            "${CMAKE_CXX_FLAGS} -std=c++${TSFILE_CXX_STANDARD}")
 endif ()
 
 if (DEFINED ENV{CXX})
@@ -333,7 +360,8 @@ if (MSVC)
     # C++17 extensions), so we pin it explicitly for reproducibility.
     set(CMAKE_CXX_FLAGS "$ENV{CXXFLAGS} /W3 /utf-8 /EHsc /bigobj /Zc:__cplusplus /std:c++14")
 else ()
-    set(CMAKE_CXX_FLAGS "$ENV{CXXFLAGS} -Wall -std=c++11")
+    set(CMAKE_CXX_FLAGS
+            "$ENV{CXXFLAGS} -Wall -std=c++${TSFILE_CXX_STANDARD}")
 endif ()
 add_subdirectory(third_party)
 
@@ -406,3 +434,140 @@ endif ()
 unset(_TSFILE_PROJECT_DEPENDENCIES)
 
 add_subdirectory(examples)
+
+# Install the compatibility header closure from the generated staging tree. The
+# staging tree is populated by the existing copy_* targets and contains only
+# headers selected by the reviewed closure manifest. The closure is retained
+# for source compatibility; it is not the final public API boundary.
+foreach (header_dir IN LISTS TSFILE_PUBLIC_HEADER_CLOSURE)
+    install(DIRECTORY "${LIBRARY_INCLUDE_DIR}/${header_dir}/"
+            DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/tsfile/${header_dir}"
+            COMPONENT development
+            FILES_MATCHING PATTERN "*.h")
+endforeach()
+if (ENABLE_SIMD AND TSFILE_SIMDE_INCLUDE_ROOT)
+    install(DIRECTORY "${TSFILE_SIMDE_INCLUDE_ROOT}/simde/"
+            DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/simde"
+            COMPONENT development
+            FILES_MATCHING PATTERN "*.h")
+endif ()
+if (ENABLE_ANTLR4 AND TSFILE_ANTLR4_INCLUDE_ROOT)
+    install(DIRECTORY "${TSFILE_ANTLR4_INCLUDE_ROOT}/"
+            DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+            COMPONENT development
+            FILES_MATCHING PATTERN "*.h")
+endif ()
+if (ENABLE_ANTLR4 AND TSFILE_UTF8CPP_INCLUDE_ROOT)
+    install(DIRECTORY "${TSFILE_UTF8CPP_INCLUDE_ROOT}/"
+            DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+            COMPONENT development
+            FILES_MATCHING PATTERN "*.h")
+endif ()
+
+set(TSFILE_LICENSE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/../LICENSE")
+set(TSFILE_NOTICE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/../NOTICE")
+if (EXISTS "${TSFILE_LICENSE_FILE}")
+    install(FILES "${TSFILE_LICENSE_FILE}"
+            DESTINATION "${CMAKE_INSTALL_DATADIR}/doc/tsfile"
+            COMPONENT runtime)
+endif()
+if (EXISTS "${TSFILE_NOTICE_FILE}")
+    install(FILES "${TSFILE_NOTICE_FILE}"
+            DESTINATION "${CMAKE_INSTALL_DATADIR}/doc/tsfile"
+            COMPONENT runtime)
+endif()
+
+include(CMakePackageConfigHelpers)
+set(TSFILE_CMAKE_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/TsFile")
+configure_package_config_file(
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/TsFileConfig.cmake.in"
+        "${CMAKE_CURRENT_BINARY_DIR}/TsFileConfig.cmake"
+        INSTALL_DESTINATION "${TSFILE_CMAKE_INSTALL_DIR}")
+write_basic_package_version_file(
+        "${CMAKE_CURRENT_BINARY_DIR}/TsFileConfigVersion.cmake"
+        VERSION "${TSFILE_PACKAGE_VERSION}"
+        COMPATIBILITY SameMajorVersion)
+install(FILES
+        "${CMAKE_CURRENT_BINARY_DIR}/TsFileConfig.cmake"
+        "${CMAKE_CURRENT_BINARY_DIR}/TsFileConfigVersion.cmake"
+        DESTINATION "${TSFILE_CMAKE_INSTALL_DIR}"
+        COMPONENT development)
+
+set(TSFILE_PKGCONFIG_CFLAGS "")
+foreach (_TSFILE_PUBLIC_FEATURE
+        ENABLE_ANTLR4
+        ENABLE_MEM_STAT
+        ENABLE_SNAPPY
+        ENABLE_LZ4
+        ENABLE_LZOKAY
+        ENABLE_ZLIB
+        ENABLE_GZIP
+        ENABLE_ZSTD
+        ENABLE_LZMA2
+        ENABLE_THREADS
+        ENABLE_SIMD)
+    if (${_TSFILE_PUBLIC_FEATURE})
+        string(APPEND TSFILE_PKGCONFIG_CFLAGS
+                " -D${_TSFILE_PUBLIC_FEATURE}")
+    endif ()
+endforeach ()
+configure_file(
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/libtsfile.pc.in"
+        "${CMAKE_CURRENT_BINARY_DIR}/libtsfile.pc"
+        @ONLY)
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/libtsfile.pc"
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig"
+        COMPONENT development)
+unset(_TSFILE_PUBLIC_FEATURE)
+
+# CPack is an opt-in local/package-builder integration. Native release jobs
+# can configure the project with TSFILE_DEPENDENCY_SOURCE=SYSTEM when the
+# target image provides every compatible dependency; AUTO remains the
+# reproducible fallback for distribution images with older packages.
+option(TSFILE_ENABLE_CPACK
+        "Enable CPack DEB/RPM package metadata generation" OFF)
+if (TSFILE_ENABLE_CPACK)
+    set(CPACK_PACKAGE_NAME "tsfile")
+    set(CPACK_PACKAGE_VENDOR "Apache Software Foundation")
+    set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Apache TsFile C++ library")
+    set(CPACK_PACKAGE_DESCRIPTION
+            "Columnar storage library and command-line tools for time series data")
+    set(CPACK_PACKAGE_HOMEPAGE_URL "https://tsfile.apache.org/")
+    set(CPACK_PACKAGE_CONTACT "dev@tsfile.apache.org")
+    set(CPACK_RESOURCE_FILE_LICENSE "${TSFILE_LICENSE_FILE}")
+    set(CPACK_PACKAGE_VERSION "${TSFILE_PACKAGE_VERSION}")
+    string(REPLACE "." ";" _TSFILE_PACKAGE_VERSION_PARTS
+            "${TSFILE_PACKAGE_VERSION}")
+    list(GET _TSFILE_PACKAGE_VERSION_PARTS 0 CPACK_PACKAGE_VERSION_MAJOR)
+    list(GET _TSFILE_PACKAGE_VERSION_PARTS 1 CPACK_PACKAGE_VERSION_MINOR)
+    list(GET _TSFILE_PACKAGE_VERSION_PARTS 2 CPACK_PACKAGE_VERSION_PATCH)
+
+    set(CPACK_COMPONENTS_ALL runtime development tools)
+    set(CPACK_COMPONENT_DEVELOPMENT_DEPENDS runtime)
+    set(CPACK_COMPONENT_TOOLS_DEPENDS runtime)
+    set(CPACK_DEB_COMPONENT_INSTALL ON)
+    set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
+    set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+    set(CPACK_DEBIAN_RUNTIME_PACKAGE_NAME "tsfile")
+    set(CPACK_DEBIAN_DEVELOPMENT_PACKAGE_NAME "tsfile-dev")
+    set(CPACK_DEBIAN_TOOLS_PACKAGE_NAME "tsfile-tools")
+    set(CPACK_DEBIAN_DEVELOPMENT_PACKAGE_DEPENDS
+            "tsfile (= ${TSFILE_PACKAGE_VERSION})")
+    set(CPACK_DEBIAN_TOOLS_PACKAGE_DEPENDS
+            "tsfile (= ${TSFILE_PACKAGE_VERSION})")
+
+    set(CPACK_RPM_COMPONENT_INSTALL ON)
+    set(CPACK_RPM_PACKAGE_LICENSE "Apache-2.0")
+    set(CPACK_RPM_PACKAGE_RELEASE "1")
+    set(CPACK_RPM_PACKAGE_AUTOREQPROV ON)
+    set(CPACK_RPM_RUNTIME_PACKAGE_NAME "tsfile")
+    set(CPACK_RPM_DEVELOPMENT_PACKAGE_NAME "tsfile-devel")
+    set(CPACK_RPM_TOOLS_PACKAGE_NAME "tsfile-tools")
+    set(CPACK_RPM_DEVELOPMENT_PACKAGE_REQUIRES
+            "tsfile = ${TSFILE_PACKAGE_VERSION}-1")
+    set(CPACK_RPM_TOOLS_PACKAGE_REQUIRES
+            "tsfile = ${TSFILE_PACKAGE_VERSION}-1")
+
+    include(CPack)
+    unset(_TSFILE_PACKAGE_VERSION_PARTS)
+endif ()

cpp/README.md

@@ -80,6 +80,13 @@ TsFile C++ now supports:
 - **macOS**: Clang
 - **Windows**: MSVC 2017+ and MinGW
 
+### Installation and Packages
+
+The C++ install layout supports CMake consumers, pkg-config, a relocatable
+TGZ archive, native Linux DEB/RPM packages, and Homebrew on macOS. See
+[`packaging/README.md`](../packaging/README.md) for build commands and the
+platform-specific release rules.
+
 All code must compile without errors on all supported platforms before submission.
 
 We welcome any bug reports. You can open an issue with a title starting with [CPP] to describe the bug, like: https://github.com/apache/tsfile/issues/94
@@ -170,7 +177,7 @@ dependencies are resolved:
 
 ANTLR4, Snappy, LZ4, lzokay, SIMDe, zlib, Zstandard, and liblzma are currently
 resolved through this policy. A compatible system ANTLR4 must be version 4.9.3
-or newer and earlier than 5.0.0, and provide an `antlr4_static` or
+or newer and earlier than 4.10.0, and provide an `antlr4_static` or
 `antlr4_shared` target. A compatible system Snappy must be version 1.2.1 or
 newer in the 1.x release series and provide the `Snappy::snappy` CMake target.
 A compatible system LZ4 must be version 1.9.4 or newer in the 1.x release

cpp/cmake/ANTLR4Dependency.cmake

@@ -19,7 +19,11 @@ under the License.
 
 set(TSFILE_ANTLR4_MIN_VERSION "4.9.3")
 set(TSFILE_ANTLR4_BUNDLED_VERSION "4.9.3")
-set(TSFILE_ANTLR4_NEXT_INCOMPATIBLE_VERSION "5.0.0")
+# The generated parser in this repository follows the 4.9 runtime API. ANTLR
+# 4.10 introduced breaking C++ runtime changes (and raised its language floor
+# to C++17), so newer system runtimes must use the verified bundled fallback
+# until the parser is regenerated and reviewed.
+set(TSFILE_ANTLR4_NEXT_INCOMPATIBLE_VERSION "4.10.0")
 set(TSFILE_ANTLR4_SYSTEM_INCLUDE_DIR "")
 set(_TSFILE_SYSTEM_ANTLR4_FOUND FALSE)
 

cpp/cmake/TsFileConfig.cmake.in

@@ -0,0 +1,29 @@
+#[[
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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
+
+    https://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)
+if (@ENABLE_THREADS@)
+    find_dependency(Threads)
+endif()
+
+include("${CMAKE_CURRENT_LIST_DIR}/TsFileTargets.cmake")
+
+check_required_components(TsFile)