@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/tpc-cpp-check/references/HPKBUILD_GUIDE.md

@@ -0,0 +1,235 @@
+# HPKBUILD 详细检查指南
+
+本指南为 TpcCheckSkill 提供 HPKBUILD 文件的详细检查规范和模板。
+
+---
+
+## 1. pkgver 版本号规范
+
+### 1.1 与上游 tag 一致
+
+pkgver 必须与上游社区 tag 名称保持一致，包括 `v` 前缀。
+
+| 上游 tag | 正确 pkgver | 错误 pkgver |
+|----------|-------------|-------------|
+| `v2.0.0` | `pkgver=v2.0.0` | `pkgver=2.0.0` |
+| `9.0.0` | `pkgver=9.0.0` | `pkgver=v9.0.0` |
+
+### 1.2 不能使用 `master`
+
+pkgver 不能使用 `master` 分支名。
+
+| 场景 | 正确示例 | 错误示例 |
+|------|----------|----------|
+| 无合适 release tag | `pkgver=e9fe7fbecae47a2287e761080f8b1133cc22e8fa` | `pkgver=master` |
+| 短 hash | `pkgver=c0031cf` | `pkgver=master` |
+
+### 1.3 commit hash 作为 pkgver 时
+
+不应使用额外的 `commitid` 变量，应直接在 prepare() 中使用 `git clone` + `git reset --hard $pkgver`。
+
+**正确示例**：
+```bash
+pkgver=1fd04917cff50fac72ae23e45f82ca6fd9130bd8
+builddir=$pkgname-${pkgver}
+
+# prepare() 中:
+git clone -b master $source $builddir
+cd $builddir
+git reset --hard $pkgver
+```
+
+**错误示例（旧的 master+commitid 模式）**：
+```bash
+pkgver=master
+commitid=bc09d8f8b4681aaeaa82b9d9a078e7eae4838424
+builddir=$pkgname-${commitid}
+```
+
+### 1.4 pkgver 与 builddir 的关系
+
+| pkgver 格式 | builddir |
+|-------------|----------|
+| 不带 `v` 前缀（如 `9.0.0`） | `builddir=$pkgname-${pkgver}` |
+| 带 `v` 前缀（如 `v0.41.0`） | `builddir=$pkgname-${pkgver:1}` |
+| commit hash | `builddir=$pkgname-${pkgver}` |
+
+---
+
+## 2. 构建类型规范
+
+### 2.1 cmake 类型
+
+**buildtools 值**：`cmake`（或不写，默认 cmake）
+
+**无需 `source envset.sh`**
+
+**build() 函数模板**：
+```bash
+build() {
+    cd $builddir
+    PKG_CONFIG_LIBDIR="${pkgconfigpath}" \
+    ${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" \
+    -DCMAKE_BUILD_TYPE=Release -DOHOS_ARCH=$ARCH -B$ARCH-build -S./ -L > $buildlog 2>&1
+    $MAKE -C $ARCH-build >> $buildlog 2>&1
+    ret=$?
+    cd $OLDPWD
+    return $ret
+}
+```
+
+**关键检查项**：
+- 必须使用 `${OHOS_SDK}/native/build-tools/cmake/bin/cmake`（不能用系统 cmake）
+- 必须包含 `-DOHOS_ARCH=$ARCH`
+- 必须包含 `-B$ARCH-build -S./`
+- 输出重定向到 `$buildlog`
+- 必须 `cd $OLDPWD` 并 `return $ret`
+
+### 2.2 configure 类型
+
+**buildtools 值**：`configure`
+
+**必须有 `source envset.sh`**
+
+**build() 函数模板**：
+```bash
+build() {
+    cd $builddir
+    ./configure --host=${host} "$@" > $buildlog 2>&1
+    $MAKE -j4 >> $buildlog 2>&1
+    ret=$?
+    cd $OLDPWD
+    return $ret
+}
+```
+
+**关键检查项**：
+- 必须在 prepare() 中根据 `$ARCH` 设置 `host` 变量和调用 `setXXXENV`
+- 必须在 package() 中调用对应的 `unsetXXXENV`
+- 必须有 `source envset.sh` 行
+
+### 2.3 automake 类型
+
+**buildtools 值**：`automake`
+
+**必须有 `source envset.sh`**
+
+**build() 函数模板**：
+```bash
+build() {
+    cd $builddir
+    ./configure --host=${host} "$@" > $buildlog 2>&1
+    $MAKE -j4 >> $buildlog 2>&1
+    ret=$?
+    cd $OLDPWD
+    return $ret
+}
+```
+
+**关键检查项**：
+- 与 configure 类型相同
+- 必须在 prepare() 中根据 `$ARCH` 设置 `host` 变量和调用 `setXXXENV`
+- 必须在 package() 中调用对应的 `unsetXXXENV`
+
+### 2.4 make 类型
+
+**buildtools 值**：`make`
+
+**必须有 `source envset.sh`**
+
+**build() 函数模板**：
+```bash
+build() {
+    cd $builddir-$ARCH-build
+    $MAKE CC=$CC CFLAGS="..." LDFLAGS="..." > $buildlog 2>&1
+    ret=$?
+    cd $OLDPWD
+    return $ret
+}
+```
+
+**关键检查项**：
+- 必须使用 `$CC` 和正确的交叉编译标志
+
+### 2.5 meson 类型
+
+**buildtools 值**：`meson`
+
+**必须有 `source envset.sh`**
+
+**build() 函数模板**：
+```bash
+build() {
+    cd $builddir
+    meson setup $ARCH-build --cross-file $ARCH-cross-file.txt "$@" > $buildlog 2>&1
+    ninja -C $ARCH-build >> $buildlog 2>&1
+    ret=$?
+    cd $OLDPWD
+    return $ret
+}
+```
+
+**关键检查项**：
+- 必须提供交叉编译配置文件（如 `$ARCH-cross-file.txt`）
+- meson setup 必须指定 `--cross-file` 和构建目录 `$ARCH-build`
+- 使用 `ninja -C $ARCH-build` 编译
+- 输出重定向到 `$buildlog`
+- 必须 `cd $OLDPWD` 并 `return $ret`
+
+---
+
+## 3. 必需函数规范
+
+### 3.1 prepare()
+
+- 创建构建目录 `$builddir/$ARCH-build`
+- 如有 patch 需在此应用
+
+### 3.2 build()
+
+- 必须正确 `cd $builddir` 和 `cd $OLDPWD`
+- 必须捕获退出码 `ret=$?` 并 `return $ret`
+
+### 3.3 package()
+
+- 安装到 `$LYCIUM_ROOT/usr/$pkgname/$ARCH` 目录结构下
+
+### 3.4 check()
+
+- 至少包含 `echo "The test must be on an OpenHarmony device!"`
+
+### 3.5 cleanbuild()
+
+- 清理 `$builddir` 相关目录
+
+---
+
+## 4. 头部规范
+
+必须包含 Apache 2.0 许可证头部和 Contributor/Maintainer 信息：
+
+```bash
+# Copyright (c) 2025 Huawei Device Co., Ltd.
+# 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.
+
+# Contributor: 姓名 <邮箱>
+# Maintainer: 姓名 <邮箱>
+```
+
+---
+
+## 5. Patch 规范
+
+- 命名格式：`<libname>_oh_pkg.patch`（构建适配）、`<libname>_oh_test.patch`（测试适配）
+- 必须在 prepare() 中应用 patch，使用 `patchflag=true` 控制只应用一次
+- SHA512SUM 中必须包含 patch 文件的校验值

package/vendor/Server/Skills/tpc-cpp-check/references/REPORT_TEMPLATE.md

@@ -0,0 +1,250 @@
+# tpc_c_cplusplus 适配库检视报告模板
+
+本模板用于生成 tpc_c_cplusplus 适配库检视报告，输出至 `{outputDir}/check-report.md`。
+
+**数据来源说明**：本检视基于 GitCode API 按需获取 PR 变更文件内容，不克隆整个仓库。检视范围仅限于 PR 中实际变更的文件（增量模式）或所有必需文件（全量模式）。
+
+---
+
+```markdown
+# 适配库规范性检视报告：{libName}
+
+**检视时间**: {YYYY-MM-DD HH:mm:ss}
+**检视路径**: `{libPath}`
+**库类型**: {thirdparty / community}
+**构建类型**: {cmake / configure / automake / make / meson}
+**检视模式**: {增量检视 / 全量检视}
+
+---
+
+## 概要信息
+
+| 字段 | 内容 |
+|------|------|
+| **库名** | {libName} |
+| **库类型** | {thirdparty / community} |
+| **路径** | {libPath} |
+| **构建类型** | {cmake / configure / automake / make / meson} |
+| **检视模式** | {增量检视 / 全量检视} |
+
+---
+
+## 问题统计
+
+| 严重程度 | 数量 |
+|----------|------|
+| 严重 (Critical) | N 个 |
+| 重要 (Major) | N 个 |
+| 一般 (Minor) | N 个 |
+| 表面 (Cosmetic) | N 个 |
+| **合计** | N 个 |
+
+> **⚠️ 合入阻断提醒：严重 (Critical) 和重要 (Major) 问题必须在合入前全部修复，否则不予批准合入！当前共有 X 个严重 + Y 个重要 = Z 项阻断性问题待解决。**
+
+---
+
+## 检视范围
+
+**本次检视模式**：{增量检视 / 全量检视}
+
+**增量检视说明**：仅检查 PR 中变更的文件，不对未修改的文件进行合规性检查。预存问题不在增量检视范围内。
+
+**全量检视说明**：对所有必需文件和可选文件进行完整合规性检查。
+
+**实际检查文件清单**：
+
+| 文件 | 是否检查 | 说明 |
+|------|----------|------|
+| HPKBUILD | ✅ / — | {说明} |
+| SHA512SUM | ✅ / — | {说明} |
+| README.OpenSource | ✅ / — | {说明} |
+| README_zh.md | ✅ / — | {说明} |
+| docs/hap_integrate.md | ✅ / — | {说明} |
+| HPKCHECK | ✅ / — | {说明} |
+| OAT.xml | ✅ / — | {说明} |
+
+---
+
+## 变更文件检查
+
+> 增量模式下仅检查变更文件，全量模式下检查所有必需文件。
+
+### HPKBUILD 检查
+
+> 若 HPKBUILD 为变更文件（增量）或全量检视模式，进行详细检查。
+
+#### 字段完整性
+
+| 字段 | 状态 | 说明 |
+|------|------|------|
+| pkgname | ✅ / ❌ | {值} / {问题描述} |
+| pkgver | ✅ / ❌ | {值} / {问题描述} |
+| pkgrel | ✅ / ❌ | {值} / {问题描述} |
+| pkgdesc | ✅ / ❌ | {值} / {问题描述} |
+| url | ✅ / ❌ | {值} / {问题描述} |
+| archs | ✅ / ❌ | {值} / {问题描述} |
+| license | ✅ / ❌ | {值} / {问题描述} |
+| depends | ✅ / ❌ | {值} / {问题描述} |
+| makedepends | ✅ / ❌ | {值} / {问题描述} |
+| source | ✅ / ❌ | {值} / {问题描述} |
+| downloadpackage | ✅ / ❌ | {值} / {问题描述} |
+| autounpack | ✅ / ❌ | {值} / {问题描述} |
+| builddir | ✅ / ❌ | {值} / {问题描述} |
+| packagename | ✅ / ❌ | {值} / {问题描述} |
+
+#### 函数完整性
+
+| 函数 | 状态 | 说明 |
+|------|------|------|
+| prepare() | ✅ / ❌ | {说明} |
+| build() | ✅ / ❌ | {说明} |
+| package() | ✅ / ❌ | {说明} |
+| check() | ✅ / ❌ | {说明} |
+| cleanbuild() | ✅ / ❌ | {说明} |
+
+#### 构建类型检查
+
+**构建类型**：{cmake / configure / automake / make / meson}
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| {检查项} | ✅ / ❌ | {说明} |
+
+#### 头部检查
+
+| 检查项 | 状态 |
+|--------|------|
+| Apache 2.0 许可证头部 | ✅ / ❌ |
+| Contributor 信息 | ✅ / ❌ |
+| Maintainer 信息 | ✅ / ❌ |
+
+### SHA512SUM 检查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| 文件非空 | ✅ / ❌ | {说明} |
+| 格式正确 | ✅ / ❌ | {说明} |
+| 包含源码校验值 | ✅ / ❌ | {说明} |
+
+### README.OpenSource 检查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| JSON 格式合法 | ✅ / ❌ | {说明} |
+| 必需字段完整 | ✅ / ❌ | {说明} |
+
+### README_zh.md 检查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| 标题格式 | ✅ / ❌ | {说明} |
+| 功能简介章节 | ✅ / ❌ | {说明} |
+| 三方库版本章节 | ✅ / ❌ | {说明} |
+| 已适配功能章节 | ✅ / ❌ | {说明} |
+| 使用约束章节 | ✅ / ❌ | {说明} |
+| 集成方式章节 | ✅ / ❌ | {说明} |
+| 链接路径正确 | ✅ / ❌ | {说明} |
+
+### docs/hap_integrate.md 检查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| 标题格式 | ✅ / ❌ | {说明} |
+| 必需章节完整 | ✅ / ❌ | {说明} |
+| 开发环境链接 | ✅ / ❌ | {说明} |
+| 截图引用 | ✅ / ❌ | {说明} |
+
+### 可选文件检查
+
+| 文件 | 状态 | 说明 |
+|------|------|------|
+| HPKCHECK | ✅ / ❌ / — | {说明} |
+| OAT.xml | ✅ / ❌ / — | {说明} |
+
+---
+
+## 问题清单
+
+### ⛔ 严重 (Critical) — N 项 【必须修复后方可合入】
+
+| 编号 | 类别 | 文件 | 问题描述 | 修复建议 |
+|------|------|------|----------|----------|
+| C1 | {类别} | {文件路径} | {问题描述} | {修复建议} |
+
+> 若无 Critical 问题，填写：**无**
+
+### 🚫 重要 (Major) — N 项 【必须修复后方可合入】
+
+| 编号 | 类别 | 文件 | 问题描述 | 修复建议 |
+|------|------|------|----------|----------|
+| M1 | {类别} | {文件路径} | {问题描述} | {修复建议} |
+
+> 若无 Major 问题，填写：**无**
+
+### 💡 一般 (Minor) — N 项
+
+| 编号 | 类别 | 文件 | 问题描述 | 修复建议 |
+|------|------|------|----------|----------|
+| N1 | {类别} | {文件路径} | {问题描述} | {修复建议} |
+
+> 若无 Minor 问题，填写：**无**
+
+### 📝 表面 (Cosmetic) — N 项
+
+| 编号 | 类别 | 文件 | 问题描述 | 修复建议 |
+|------|------|------|----------|----------|
+| S1 | {类别} | {文件路径} | {问题描述} | {修复建议} |
+
+> 若无 Cosmetic 问题，填写：**无**
+
+---
+
+> **🔴 合入阻断提醒：以上 C1~CX（严重）和 M1~MY（重要）共 Z 项问题为合入前置条件，必须在 PR 合入前全部修复。一般和表面级别问题可在后续迭代中改善。**
+
+---
+
+*本报告由 TpcCheckSkill 自动生成，仅供参考，最终合入决策由人工评审确认。*
+```
+
+---
+
+## result.txt 文件生成规范
+
+检视完成后，生成 `{outputDir}/result.txt` 文件供前端展示和数据库存储。
+
+```txt
+=== 合入建议分级报告 ===
+PR 地址：{prUrl}
+仓库：{owner}/{repo}
+PR 编号：#{prNumber}
+生成时间：{YYYY-MM-DD HH:mm:ss}
+
+【合入建议】：{等级标识}
+
+【问题统计】
+- Critical 级别：{criticalCount} 个
+- Major 级别：{majorCount} 个
+- Minor 级别：{minorCount} 个
+- Cosmetic 级别：{cosmeticCount} 个
+
+【分级理由】
+{分级理由详细说明}
+
+【详细分析】
+━━━ Critical 级别问题 ━━━
+{列出所有 Critical 问题，每个占一行}
+
+━━━ Major 级别问题 ━━━
+{列出所有 Major 问题，每个占一行}
+
+━━━ Minor 级别问题 ━━━
+{列出所有 Minor 问题，每个占一行}
+
+━━━ Cosmetic 级别问题 ━━━
+{列出所有 Cosmetic 问题，每个占一行}
+
+━━━ 合入建议 ━━━
+{最终合入建议和条件说明}
+
+=== 分级结束 ===
+```