You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tsfile.apache.org by co...@apache.org on 2026/09/17 06:31:03 UTC
(tsfile) 20/24: docs: document native package artifact workflow
This is an automated email from the ASF dual-hosted git repository.
ColinLeeo pushed a commit to branch feat/native-package-artifacts
in repository https://gitbox.apache.org/repos/asf/tsfile.git
commit 89fb5a8b56066a75274fc3280e7fd8742b301089
Author: ColinLee <sh...@163.com>
AuthorDate: Thu Sep 10 21:12:34 2026 +0800
docs: document native package artifact workflow
---
.github/workflows/cpp-packaging.yml | 128 ---------------------
cpp/README.md | 2 +-
.../plans/2026-09-10-native-package-artifacts.md | 2 +-
.../2026-09-10-native-package-artifacts-design.md | 17 +--
packaging/README.md | 30 ++++-
5 files changed, 35 insertions(+), 144 deletions(-)
diff --git a/.github/workflows/cpp-packaging.yml b/.github/workflows/cpp-packaging.yml
deleted file mode 100644
index 54fa92211..000000000
--- a/.github/workflows/cpp-packaging.yml
+++ /dev/null
@@ -1,128 +0,0 @@
-#
-# 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
diff --git a/cpp/README.md b/cpp/README.md
index d14cf6ad6..c092cf54f 100644
--- a/cpp/README.md
+++ b/cpp/README.md
@@ -177,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 4.10.0, and provide an `antlr4_static` or
+or newer and earlier than 4.13.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
diff --git a/docs/superpowers/plans/2026-09-10-native-package-artifacts.md b/docs/superpowers/plans/2026-09-10-native-package-artifacts.md
index a3c9b292c..29436e629 100644
--- a/docs/superpowers/plans/2026-09-10-native-package-artifacts.md
+++ b/docs/superpowers/plans/2026-09-10-native-package-artifacts.md
@@ -53,7 +53,7 @@
- Modify through cherry-pick: `cpp/tools/CMakeLists.txt`
- Create through cherry-pick: `cpp/cmake/TsFileConfig.cmake.in`
- Create through cherry-pick: `cpp/cmake/TsFilePublicHeaders.cmake`
-- Create through cherry-pick: `cpp/cmake/tsfile.pc.in`
+- Create through cherry-pick: `cpp/cmake/libtsfile.pc.in`
- Create through cherry-pick: `packaging/README.md`
- Create through cherry-pick: `packaging/homebrew/tsfile.rb`
- Create through cherry-pick: `.github/workflows/cpp-packaging.yml`
diff --git a/docs/superpowers/specs/2026-09-10-native-package-artifacts-design.md b/docs/superpowers/specs/2026-09-10-native-package-artifacts-design.md
index 49f922f55..ac04ec68b 100644
--- a/docs/superpowers/specs/2026-09-10-native-package-artifacts-design.md
+++ b/docs/superpowers/specs/2026-09-10-native-package-artifacts-design.md
@@ -77,11 +77,11 @@ The caller does not enter a version. A `prepare` job reads
For a base version of `2.5.0`, an example identity is:
```text
-logical: 2.5.0.dev0+20260910.123.1.gabcdef
-deb: 2.5.0~dev0+20260910.123.1.gabcdef-1
-rpm: Version 2.5.0, Release 0.dev0.20260910.123.1.gabcdef.el9
-archive: 2.5.0-dev0.20260910.123.1.gabcdef
-homebrew: 2.5.0.dev0.20260910.123.1.gabcdef
+logical: 2.5.0.dev0+20260910.123.1.gabcdef1
+deb: 2.5.0~dev0+20260910.123.1.gabcdef1-1
+rpm: Version 2.5.0, Release 0.dev0.20260910.123.1.gabcdef1.el9
+archive: 2.5.0-dev0.20260910.123.1.gabcdef1
+homebrew: 2.5.0.dev0.20260910.123.1.gabcdef1
```
The workflow fails before building if the source version cannot be parsed.
@@ -188,8 +188,9 @@ successful. It downloads the intermediate artifacts, arranges them by package
family and platform, generates `SHA256SUMS`, and writes `manifest.json` with the
source commit, generated versions, platforms, filenames, sizes, and checksums.
-It uploads one final GitHub Actions artifact named from the logical build
-identity, with a retention period of 14 days.
+It uploads one final GitHub Actions artifact named
+`tsfile-native-packages-<archive-version>`, with a retention period of 14 days.
+The local assembly directory uses the logical version of the same build identity.
The manifest also records the intended JFrog repository, immutable target path,
and Debian coordinates for each file. This does not publish anything, but it
@@ -230,7 +231,7 @@ tsfile-native-packages-<logical-version>/
│ ├── Formula/tsfile-dev.rb
│ └── bottles/
└── windows/
- └── apache-tsfile-cpp-<archive-version>-windows-x86_64.zip
+ └── tsfile-<archive-version>-windows-x86_64.zip
```
## Failure and Safety Behavior
diff --git a/packaging/README.md b/packaging/README.md
index c693cd1f6..910026236 100644
--- a/packaging/README.md
+++ b/packaging/README.md
@@ -29,9 +29,29 @@ The header closure mirrors the include relationships used by the current C++
implementation. It is intentionally broader than the long-term stable public
API; a separate API cleanup will narrow it in a future version.
+## Manual artifact workflow
+
+`Build native package artifacts` (`.github/workflows/native-packages.yml`) is
+the authoritative native packaging workflow. In the fork's GitHub Actions tab,
+select this workflow, choose **Run workflow**, select the branch containing the
+commit to build, and dispatch it manually. It runs only on `workflow_dispatch`,
+with read-only repository permissions; pushes and pull requests do not trigger
+native packaging.
+
+A successful run produces Ubuntu DEBs, AlmaLinux RPMs, an ARM64 and Intel
+Homebrew development bottle with a merged Formula, and a Windows x86_64 SDK/CLI
+ZIP. It combines these into `tsfile-native-packages-<archive-version>` with
+`manifest.json` and `SHA256SUMS`. Download this final artifact from the workflow
+run; both intermediate and final artifacts are retained for 14 days.
+
+Publishing is a separate, manual step. This workflow only builds, tests, and
+uploads GitHub Actions artifacts. It has no publishing credentials and does
+not upload to JFrog, sign packages, update `latest`, create tags or releases, or
+implement RC/final release behavior.
+
## Portable archive
-Build a relocatable source archive on any host with CMake and CPack:
+Build a relocatable binary archive on any host with CMake and CPack:
```bash
cmake -S cpp -B cpp/build/package \
@@ -41,7 +61,6 @@ cmake -S cpp -B cpp/build/package \
-DTSFILE_ENABLE_CPACK=ON \
-DTSFILE_DEPENDENCY_SOURCE=AUTO
cmake --build cpp/build/package --parallel
-cmake --install cpp/build/package
cpack --config cpp/build/package/CPackConfig.cmake -G TGZ
```
@@ -63,15 +82,14 @@ cmake -S cpp -B cpp/build/package \
-DTSFILE_ENABLE_CPACK=ON \
-DTSFILE_DEPENDENCY_SOURCE=AUTO
cmake --build cpp/build/package --parallel
-cmake --install cpp/build/package
cpack --config cpp/build/package/CPackConfig.cmake -G DEB
# or: cpack --config cpp/build/package/CPackConfig.cmake -G RPM
```
`SYSTEM` can be used instead of `AUTO` when the build image provides every
-compatible dependency, including ANTLR4 4.9.x. `AUTO` is the reproducible
-release default and uses the verified source fallback for unavailable or
-incompatible distro versions.
+compatible dependency, including ANTLR4 >=4.9.3 and <4.13.0. `AUTO` is the
+reproducible release default and uses the verified source fallback for
+unavailable or incompatible distro versions.
The manual `Build native package artifacts` workflow is the authoritative
native package build. Its Linux jobs create `tsfile`, `tsfile-dev`, and