From b5553cd640cf46e78685d56340c6e7735d507a06 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 18:52:33 +0800 Subject: [PATCH 01/38] docs: add plan 5 (upstream sync and release) --- docs/plans/2026-11-18-plan5-release.md | 279 +++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 docs/plans/2026-11-18-plan5-release.md diff --git a/docs/plans/2026-11-18-plan5-release.md b/docs/plans/2026-11-18-plan5-release.md new file mode 100644 index 0000000..dcedd14 --- /dev/null +++ b/docs/plans/2026-11-18-plan5-release.md @@ -0,0 +1,279 @@ +# Plan 5:上游同步与发布 Implementation Plan + +**Goal:** 让仓库自动跟踪 openslide.org/builds 上的 openslide-bin 正式版与 nightly。上游更新时按以下顺序处理: + +1. 重新生成绑定; +2. 在四平台上测试; +3. 提交到 master; +4. 按规格 §7.2 计算版本号; +5. 把 5 个 NuGet 包推送到 nuget.org(维护者设置 `NUGET_API_KEY` 之后才会推送,未设置时只做演练); +6. 创建 GitHub Release,附上 nupkg、查看器的三平台构建和 openslide-bin 源码包。 + +同时清掉计划 1–4 遗留的所有“发布前必须处理”事项。 + +**Architecture:** +- 发布逻辑分为三层: + - `eng/` 中的 PowerShell 脚本:版本计算、上游检测、清单更新、打包,每个脚本都带 `-SelfTest`; + - 三个 workflow:`ci.yml` 改为可复用;新增 `release.yml`、`upstream-sync.yml`; + - 仓库文档。 +- 发布必须先跑完 CI 的四平台矩阵(复用 `ci.yml`),通过后才执行。 +- 没有 `NUGET_API_KEY` 时整个发布降级为演练:只构建、打包并上传 workflow artifact,不打 tag、不建 Release、不推送。 + +**Tech Stack:** GitHub Actions(action 主版本与现有 ci.yml 一致)、PowerShell 7、.NET 10 SDK、nuget.org v3 API、GitHub REST API(`gh`)。 + +**Spec:** `docs/design/2026-11-17-openslidesharp-v4-refactor-design.md`(§3、§7、§9)。遗留事项:`docs/notes/2026-11-17-plan1-carryover.md` 至 `docs/notes/2026-11-18-plan4-carryover.md` 中 “发布前必须处理” 各节。 + +## Global Constraints + +- **版本号**(§7.2)。所有包共用同一版本号: + + | 情况 | NuGet 版本 | + |---|---| + | 正式版 openslide-bin `X.Y.Z.B` | `X.Y.Z.B` | + | nightly `X.Y.Z.B+YYYYMMDD.nightly`,openslide 版本 `…-g` | `X.Y.Z.(B+1)-nightly.YYYYMMDD.g` | + | 上游未变、只改 C# 的第 N 次发布 | 上面的版本后加 `.N`(N 从 1 开始,按已有 tag 计算) | + | 清单为正式版时只改 C# | 按 nightly 规则编号:日期取该正式版的发布日期,hash 取该 tag 对应的 openslide commit | + +- **单调不变式:** 推送前查询 nuget.org 上 `OpenSlideSharp` 的全部版本(含预发布)。计算出的版本按 NuGet 的排序规则不高于已有最高版本时,拒绝发布。当前 nuget.org 上的最高版本是 `1.1.2`。 +- **同步规则**(§7.2): + - 只接受高于清单当前版本、也高于已发布最高版本的正式版;旧系列的维护版跳过。 + - nightly 算出的版本必须高于已发布最高版本,否则跳过。 + - 同一次同步按 NuGet 版本从低到高处理,正式版优先。 + - 清单永不降级。 +- **程序集元数据:** `InformationalVersion` = `+openslide.`,例如 `4.0.1.3-nightly.20261102.g174630bf+openslide.v4.0.1-49-g174630bf`。Release notes 中写明 openslide-bin 版本、openslide 版本和 commit。 +- **提交身份:** workflow 中的自动提交和 tag 一律使用 `IOL0ol1 <1353839731@qq.com>`。 +- **推送凭据:** 用 `secrets.NUGET_API_KEY`,`dotnet nuget push … --skip-duplicate`。secret 不存在或为空时进入演练模式,日志用 `::notice::` 说明。workflow 在任何情况下都不得打印 secret。 +- **发布前置:** release 必须在同一 ref 上复用 `ci.yml` 并全部通过后才执行(反目标:不得发布未经四平台测试的包)。 +- **GitHub Release 内容:** + - 5 个 nupkg(不含 snupkg); + - 查看器 3 个归档:`OpenSlideSharp.Viewer--win-x64.zip`、`-linux-x64.tar.gz`、`-osx-arm64.tar.gz`。每个归档 = 发布目录(可执行文件 + `licenses/`); + - openslide-bin 源码包:`openslide-bin-.tar.gz`,原样转存,满足 LGPL 的源码提供义务; + - nightly 版本标为 prerelease。 +- **Action 版本:** 沿用 `actions/checkout@v7`、`actions/setup-dotnet@v6`、`actions/cache@v6`、`actions/upload-artifact@v7`、`actions/download-artifact@v8`。每个 job 写 `timeout-minutes`,权限按 job 最小化。 +- **脚本:** PowerShell 7(`#requires -Version 7`)。所有网络响应都要校验 HTTP 状态和 sha256。 + +## Review Focus + +1. **NuGet 版本排序。** `4.0.1.3-nightly.20261102.g174630bf` 必须低于 `4.0.1.3`、高于 `4.0.1.2`,带 `.N` 的版本按数字比较(`.10` 高于 `.9`),四段与三段混排时也要正确。版本比较出错会导致发布出 nuget.org 上收不回的错序版本。→ Task 3 的 `-SelfTest` 用例。 +2. **演练模式不留痕。** 没有 key 时不得打 tag、不得建 Release、不得推送任何东西,workflow 仍为绿色并输出 notice。→ Task 4 的演练检查;合并后用 `workflow_dispatch` 实跑一次。 +3. **上游有更新但新版本测试失败。** 不提交、不发布;按上游版本开 issue,同一版本不重复开;临时分支要清理。→ Task 5 的 `-SelfTest`(模拟),合并后再用 `workflow_dispatch` 做一次演练。 +4. **工具输出目录为符号链接时误删链接目标的内容**(计划 3 遗留)。→ Task 2 `OutputSafetyTests` 新用例。 +5. **供应链:** nuget.exe 和上游资源都要固定并校验哈希,清单中的 sha256 还要与 GitHub 资源的 `digest` 交叉校验。→ Task 1。 + +--- + +### Task 1: 上游清单、原生库与打包脚本的发布前加固 + +**Files:** +- Modify: + - `eng/Update-OpenSlideManifest.ps1` + - `eng/Get-OpenSlide.ps1` + - `eng/Test-Packages.ps1` + - `eng/openslide.json`(重新生成,包含 source 资源) + - `src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj` + - `src/OpenSlideSharp.runtime/README.md` + +**Interfaces:** +- **清单**新增 `"source": { "url": "…/openslide-bin-.tar.gz", "sha256": "…" }`。 + - `Update-OpenSlideManifest.ps1` 记录每个资源时,都要与 GitHub release API 中该资源的 `digest`(形如 `sha256:`)比对,不一致时报错退出。 + - 源码包同样需要校验。 +- **`Get-OpenSlide.ps1`:** + - licenses 改为按平台分目录:`artifacts/native/licenses//…`,每个平台目录里各有一份 `VERSIONS.md`,根目录不再放 `VERSIONS.md` 和 `versions.json`。这样即使只取某一平台,内容也是确定的。 + - 写出 `artifacts/native/openslide-bin.json`,内容为清单的 `channel`、`binVersion`、`openslideVersion`、`openslideCommit`、`date`、`source`。 + - 新增 `-Verify` 开关:检查 `.stamp` 中各平台的 sha 与清单一致、预期文件都存在,不一致则报错退出。打包前(Test-Packages 的 pack 分支,以及 release)必须调用。 +- **runtime 包:** + - `licenses//**` 与 `openslide-bin.json` 打进包内; + - 许可改用 `PackageLicenseFile` 指向包内的 `LICENSE.txt`(新建 `src/OpenSlideSharp.runtime/LICENSE.txt`),说明包内原生库来自 openslide-bin,按 LGPL-2.1 授权,各平台静态链接的组件及其许可见 `licenses//`,源码见 `openslide-bin.json` 中的 `source`; + - README 同步更新。 +- **`Test-Packages.ps1`:** + - nuget.exe 固定为一个明确版本,从 `https://dist.nuget.org/win-x86-commandline/v<版本>/nuget.exe` 下载。脚本里写死 sha256,下载后校验,不一致即失败。实现时下载一次,记录版本和 sha256。 + - 依赖组断言改为精确断言:TFM 名称集合完全相等,依赖集合完全相等,不再用 `-lt 3`。 + - runtime 包断言新的 licenses 布局、`openslide-bin.json` 和 `LICENSE.txt`,并断言 nuspec 中为 `LICENSE.txt`。 + - pack 分支开始前调用 `Get-OpenSlide.ps1 -Platform all -Verify`。 + +- [ ] **Step 1:实现,然后重新生成清单**(仍为当前最新 nightly),在本机运行 `pwsh eng/Get-OpenSlide.ps1 -Platform all -Force` 与 `pwsh eng/Test-Packages.ps1`。 + +Expected:`All package smoke tests passed.` + +- [ ] **Step 2:用 `dotnet test OpenSlideSharp.slnx -c Release` 跑全部测试后提交** + +提交信息:`build: verify upstream assets against GitHub digests, ship per-platform notices and pin nuget.exe` + +--- + +### Task 2: 包元数据、许可声明与发布前的 API 修整 + +**Files:** +- Modify: + - `src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj` + - `src/OpenSlideSharp.Tool/Export/ExportSupport.cs` + - `test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs` + - `samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj` + - `samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt` + - `src/OpenSlideSharp/DeepZoomGenerator.cs` + - `src/OpenSlideSharp/OpenSlide.cs`(GetThumbnail) + - `src/OpenSlideSharp.SkiaSharp/SkiaColorTransform.cs`(文档) + - `Directory.Build.props` + - 相应测试 +- Create: `src/OpenSlideSharp.Tool/LICENSE.txt` +- Delete: `samples/OpenSlideSharp.Viewer/SOURCE.md`(改为发布时生成) + +**Interfaces:** +- **工具包:** + - 改用 `PackageLicenseFile`(`LICENSE.txt`):工具代码为 MIT;随包分发的 openslide-bin 为 LGPL-2.1,其组件许可见 `licenses/openslide-bin//`;SkiaSharp 与 HarfBuzzSharp 见 `licenses/skiasharp/`;查看器资源见 `licenses/viewer/`。 + - openslide-bin 的许可证目录按 Task 1 的新布局复制。 +- **工具输出安全**(计划 3 遗留):`EnsureReplaceableDirectory` 遇到输出根本身是符号链接或 junction(`LinkTarget != null`)时,直接以退出码 1 拒绝,提示 “is a link”,不删除任何内容。 + - 新用例 `Output_IsSymlinkToMarkedDirectory_IsRefused`:链接目标里放一个 marker 和一个文件,运行后目标内容完好。没有创建链接的权限时用 `Assert.Skip` 跳过,Linux 和 macOS 上一定会运行。 +- **查看器 licenses:** + - `THIRD-PARTY-NOTICES.txt` 为 MicroCom.Runtime 和 Tmds.DBus.Protocol 补上 MIT 许可全文; + - 发布时由 `openslide-bin.json`(来自 runtime 包或 `artifacts/native`)生成 `licenses/SOURCE.md`,写入确切的 openslide-bin 版本、源码包 URL 与 sha256,以及用 `OPENSLIDE_LIBRARY_PATH` 替换原生库的说明; + - `Test-Packages` 中查看器发布的断言同步改为检查 SOURCE.md 含 `binVersion`。 +- **InformationalVersion:** + - `Directory.Build.props` 新增可选属性 `OpenSlideUpstreamVersion`(由发布流程传入)。设置后令 `InformationalVersion = $(Version)+openslide.$(OpenSlideUpstreamVersion)`,并关闭 SDK 自动追加 git hash(`IncludeSourceRevisionInInformationalVersion=false`)。 + - 未设置时行为不变。 + - 测试:构建时传入该属性,`OpenSlideLibrary` 所在程序集的 `AssemblyInformationalVersionAttribute` 应符合预期。写成 `test/OpenSlideSharp.Tests/AssemblyVersionTests.cs`,读取的是测试运行时的程序集,所以这里只断言不为空,且 `+` 前面等于 `Version`;端到端的值由 Task 4 发布流程的日志检查。 +- **API 修整**(计划 2 遗留): + - `DeepZoomGenerator`:去掉 `tileSize + 2*overlap ≤ int.MaxValue/4` 的构造期限制,改为在 `GetTile` 中用 `CheckedPixelBytes` 检查(`ParamName` 为 `level`),从而接受 Python 能接受的参数; + - `OpenSlide.GetThumbnail`:先检查所选层级的读取大小,再分配输出;超限时 `ParamName` 为 `maxWidth`/`maxHeight`(取超限的那一维); + - `SkiaColorTransform` 的文档注明缓存以 ICC 数组引用为键,调用方不得在之后修改该数组。 + - 以上各项都配测试。 + +- [ ] **Step 1:写失败的测试**(符号链接、DeepZoom 大 tileSize、GetThumbnail 参数名、InformationalVersion 格式) +- [ ] **Step 2:实现** +- [ ] **Step 3:运行全部测试和 `pwsh eng/Test-Packages.ps1`** +- [ ] **Step 4:提交**(可以分成几个 fix/build/docs 提交) + +--- + +### Task 3: 版本计算与上游检测脚本 + +**Files:** +- Create: + - `eng/Get-ReleaseVersion.ps1` + - `eng/Find-UpstreamUpdate.ps1` + - `eng/NuGetVersion.psm1`(NuGet 版本解析与比较,供两个脚本共用) +- Modify: `.github/workflows/ci.yml`(新增 `scripts` job,在 ubuntu-latest 上运行两个脚本的 `-SelfTest`) + +**Interfaces:** +- `NuGetVersion.psm1`: + - `ConvertTo-NuGetVersion [string]`:解析 1–4 段数字加可选的 `-prerelease` 和 `+metadata`; + - `Compare-NuGetVersion a b`:返回 -1、0 或 1,按 NuGet 规则比较: + 1. 数字段逐段比较,缺省视为 0; + 2. 有预发布标签的版本低于没有的; + 3. 预发布标签按 `.` 分段:纯数字段按数值比较,其余段按字符串忽略大小写比较;数字段低于字母段;段数少者较低; + 4. `+` 后的元数据不参与比较。 +- `Get-ReleaseVersion.ps1 [-Manifest eng/openslide.json] [-PublishedVersions ] [-ExistingTags ] [-SelfTest]`: + - 输出 JSON:`version`、`prerelease`(bool)、`informationalVersion`、`tag`(`v`)、`releaseName`、`notes`(Markdown,含 openslide-bin 版本、openslide 版本和 commit、源码包链接); + - 版本按 §7.2 计算; + - 基础版本对应的 tag 已存在时,N 取已有 `.N` 的最大值 + 1,没有则为 1; + - 违反单调不变式时以非零退出,并说明原因; + - 省略 `-PublishedVersions` 时从 `https://api.nuget.org/v3-flatcontainer/openslidesharp/index.json` 获取(404 视为空);省略 `-ExistingTags` 时用 `git tag --list 'v*'`。 +- `Find-UpstreamUpdate.ps1 [-Manifest …] [-PublishedVersions …] [-SelfTest]`: + - 查询 openslide-bin 最新正式版(`repos/openslide/openslide-bin/releases/latest`)和 openslide/builds 最新的 nightly prerelease; + - 按同步规则输出要处理的候选列表(JSON 数组,按 NuGet 版本从低到高,正式版优先),每项含 `channel` 和 `tag`; + - 没有更新时输出空数组。 + - GitHub API 用 `GITHUB_TOKEN`(若有)认证。 +- 两个脚本的 `-SelfTest` 都用内置的模拟数据,不访问网络,至少覆盖以下用例: + +| 用例 | 期望 | +|---|---| +| `Compare 4.0.1.3-nightly.20261102.g174630bf < 4.0.1.3` | -1 | +| `Compare 4.0.1.3-nightly.20261102.g174630bf > 4.0.1.2` | 1 | +| `Compare …g174630bf.10 > …g174630bf.9` | 1 | +| `Compare 1.1.2 < 4.0.1.2` | -1 | +| `Compare 4.0.1 == 4.0.1.0` | 0 | +| `Compare 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta` | 有序 | +| nightly 清单 `4.0.1.2+20261102.nightly`、`v4.0.1-49-g174630bf`,无 tag,已发布 `1.1.2` | `4.0.1.3-nightly.20261102.g174630bf` | +| 同上,已有 tag `v4.0.1.3-nightly.20261102.g174630bf` | `4.0.1.3-nightly.20261102.g174630bf.1` | +| 同上,已有 `.1`、`.2` | `.3` | +| 正式版清单 `4.0.1.2`(date `2026-06-20`,commit `fe79a971`),无 tag | `4.0.1.2` | +| 同上,已有 tag `v4.0.1.2` | `4.0.1.3-nightly.20260620.gfe79a971.1` | +| 已发布 `4.0.1.3`、清单 nightly 基线 `4.0.1.2` | 拒绝(单调) | +| 上游正式版 `4.0.0.14`、清单 `4.0.1.2` | 跳过(旧系列) | +| 上游有新正式版 `4.0.2.0` 和新 nightly `4.0.2.0+…` | 先正式版,再 nightly | + +- [ ] **Step 1:先写 `-SelfTest` 用例并运行,确认失败** +- [ ] **Step 2:实现** +- [ ] **Step 3:自测通过;用真实网络各运行一次,记录输出**(当前清单、nuget.org 与上游) +- [ ] **Step 4:加入 CI 的 `scripts` job,提交** + +--- + +### Task 4: `release.yml` + +**Files:** +- Create: `.github/workflows/release.yml` +- Modify: + - `.github/workflows/ci.yml`:增加 `workflow_call`(输入 `ref`),被调用时各 job checkout 该 ref; + - `eng/Test-Packages.ps1`(如需要):新增 `-PackOnly` 开关,供发布时只打包、不跑冒烟。 + +**Interfaces:** +- **触发:** + - `push` 到 master,且 `src/**`、`eng/openslide.json`、`Directory.*.props` 有变更; + - `workflow_dispatch`,输入 `dry_run`(bool,默认 false); + - `workflow_call`,输入 `ref`,供同步流程调用。 +- **并发:** `concurrency: release`,不取消进行中的运行。 +- **jobs:** + 1. `ci`:`uses: ./.github/workflows/ci.yml`,传入 ref。 + 2. `version`:needs ci,在 ubuntu 上运行。 + - checkout 时 `fetch-depth: 0`,并获取 tags; + - 运行 `Get-ReleaseVersion.ps1`,输出 version、tag、prerelease 等; + - 判定演练模式:输入 `dry_run`,或 `secrets.NUGET_API_KEY` 为空(通过 `env` 传给 step 再判断,不得打印)。 + 3. `pack`:needs version,在 windows-latest 上运行。 + - `Get-OpenSlide -Platform all -Force -Verify`; + - 用 `-Version ` 和 `-p:OpenSlideUpstreamVersion=` 打出 5 个包:可以运行 `Test-Packages.ps1 -PackOnly`,也可以直接按其顺序执行 `dotnet pack`; + - 上传 artifact `nupkgs`。 + 4. `viewer`:needs version,matrix 为 win-x64、linux-x64、osx-arm64,均在 ubuntu-latest 上交叉发布。 + - 用本地 feed 中的 runtime 包(下载 `nupkgs` artifact),`-p:UseOpenSlideRuntimePackage=true`; + - win-x64 打 zip,其余打 tar.gz; + - 上传 artifact。 + 5. `publish`:needs pack、viewer,**非演练**时才执行,`permissions: contents: write`。 + - 下载 artifacts 和 openslide-bin 源码包,按清单 sha256 校验; + - `dotnet nuget push *.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate`; + - 以 `IOL0ol1 <1353839731@qq.com>` 身份为发布的 ref 打 annotated tag `v` 并 push; + - 用 `gh release create` 创建 Release:notes 用 `Get-ReleaseVersion` 输出的 notes,nightly 加 `--prerelease`,附件按 Global Constraints。 + 6. `dry-run-summary`:演练时执行,把版本、包列表和附件列表写入 `$GITHUB_STEP_SUMMARY`。 +- **安全:** + - 只有 `publish` job 能接触 key; + - `pull_request` 事件不会触发 release; + - 工作流文件中不得有 `echo` 输出 secret。 + +- [ ] **Step 1:编写 workflow**,用 `actionlint` 检查(如果本机不可用,在 CI 中加一个 actionlint step:`rhysd/actionlint` 的官方 docker 用法,或下载固定版本的二进制并校验 sha256)。 +- [ ] **Step 2:在本机模拟 pack 与 viewer 步骤**(运行对应的 PowerShell 命令),确认产物齐全:5 个 nupkg 和 3 个归档,归档内有 licenses 和 SOURCE.md。 +- [ ] **Step 3:提交。** `workflow_dispatch` 只能运行默认分支上的 workflow,所以要在合并后验证:在 master 上以 `dry_run=true` 运行一次,确认绿色、没有 tag、没有 Release。 + +--- + +### Task 5: `upstream-sync.yml` 与文档 + +**Files:** +- Create: `.github/workflows/upstream-sync.yml` +- Modify: + - `README.md`:Versioning 一节说明自动发布;新增 “Old packages” 一节,列出需要弃用的旧包; + - `src/OpenSlideSharp.runtime/README.md`:注明 VS 2026 18.7+ 的原生 `PackageReference` 用法未经测试; + - `samples/OpenSlideSharp.Viewer/README.md`:Release 下载说明,以及 macOS 上 `xattr -d com.apple.quarantine` 的处理方法。 + +**Interfaces:** +- **触发:** `schedule`(每天 03:17 UTC)和 `workflow_dispatch`(输入 `dry_run`)。 +- **并发:** `concurrency: upstream-sync`。 +- **jobs:** + 1. `detect`:运行 `Find-UpstreamUpdate.ps1`,输出候选列表;为空时结束。 + 2. `update`:只处理第一个候选,一次同步只推进一个版本,下一个留给下次运行。 + - 新建分支 `sync/`; + - `Update-OpenSlideManifest.ps1 -Channel -Tag `; + - `Get-OpenSlide -Platform current`; + - `Generate-Bindings.ps1`(在 windows-latest 上运行,与 ci 的 bindings job 一致); + - 以 IOL0ol1 身份提交,提交信息为 `build: track openslide-bin `,推送分支(`permissions: contents: write`)。 + 3. `ci`:`uses: ./.github/workflows/ci.yml`,输入 `ref: sync/`。 + 4. `merge`:needs ci,成功且非演练时执行。 + - 把 master 快进到 sync 分支;无法快进时(master 已前进)改为开 PR,交给维护者处理; + - 删除 sync 分支。 + 5. `release`:needs merge,`uses: ./.github/workflows/release.yml`,输入 `ref: master`,并通过 `secrets: inherit` 传入 secret。 + 6. `report-failure`:在 `if: failure()` 时执行。 + - 按标题 `Upstream sync failed: openslide-bin ` 查找处于 open 状态的 issue,不存在才新建(`permissions: issues: write`); + - 正文附上运行链接; + - 删除 sync 分支。 +- **演练:** 只执行 detect 和 update。update 不推送,只把生成的 diff 写进 step summary。 + +- [ ] **Step 1:编写 workflow 和文档**,用 actionlint 检查。 +- [ ] **Step 2:提交。** 合并后在 master 上以 `dry_run=true` 运行一次同步。当前清单已是最新的 nightly 时,预期为 detect 输出空列表,运行结束。 From 7be0f014b32abf73f587bacf47c90805151fec3e Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:17:21 +0800 Subject: [PATCH 02/38] build: verify upstream assets against GitHub digests, ship per-platform notices and pin nuget.exe - Update-OpenSlideManifest.ps1 checks every archive, and the openslide-bin source tarball it now records as "source", against the sha256 digest of the GitHub release asset, and refuses to write the manifest otherwise. - Get-OpenSlide.ps1 keeps each archive's licenses and VERSIONS.md in licenses// instead of one archive's copy at the root, writes openslide-bin.json (build, versions and source tarball), and gains -Verify, which packing now runs first. - OpenSlideSharp.runtime packs the per-platform licenses and openslide-bin.json, and states its terms in LICENSE.txt (PackageLicenseFile) instead of the LGPL-2.1-only expression. - Test-Packages.ps1 pins nuget.exe 8.0.0 by version and sha256, asserts dependency groups exactly, and checks the new runtime, tool and viewer license layouts. --- README.md | 2 +- eng/Get-OpenSlide.ps1 | 133 ++++++++++++--- eng/Test-Packages.ps1 | 158 +++++++++++++----- eng/Update-OpenSlideManifest.ps1 | 61 +++++-- eng/openslide.json | 4 + .../OpenSlideSharp.Viewer.csproj | 11 +- samples/OpenSlideSharp.Viewer/README.md | 2 +- samples/OpenSlideSharp.Viewer/SOURCE.md | 3 +- .../THIRD-PARTY-NOTICES.txt | 7 +- .../OpenSlideSharp.Tool.csproj | 11 +- src/OpenSlideSharp.Tool/README.md | 2 +- src/OpenSlideSharp.runtime/LICENSE.txt | 21 +++ .../OpenSlideSharp.runtime.csproj | 27 ++- src/OpenSlideSharp.runtime/README.md | 2 +- 14 files changed, 336 insertions(+), 108 deletions(-) create mode 100644 src/OpenSlideSharp.runtime/LICENSE.txt diff --git a/README.md b/README.md index 980a583..357ebc1 100644 --- a/README.md +++ b/README.md @@ -156,4 +156,4 @@ dotnet test OpenSlideSharp.slnx ## License -The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide and its dependencies under LGPL-2.1-only. +The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. diff --git a/eng/Get-OpenSlide.ps1 b/eng/Get-OpenSlide.ps1 index 7afcd47..2758a32 100644 --- a/eng/Get-OpenSlide.ps1 +++ b/eng/Get-OpenSlide.ps1 @@ -6,18 +6,30 @@ .DESCRIPTION Archives are cached in artifacts/downloads. Output layout (default artifacts/native): win-x64/libopenslide-1.dll, linux-x64|linux-arm64/libopenslide-1.so, - osx-arm64|osx-x64/libopenslide-1.dylib, msvc/x64/libopenslide.lib, - include/, licenses/, VERSIONS.md, versions.json, CHANGELOG.md, .stamp + osx-arm64|osx-x64/libopenslide-1.dylib, msvc/x64/libopenslide.lib, include/openslide/*.h, + licenses// the archive's licenses/ (one folder per component) and its VERSIONS.md, + openslide-bin.json channel, versions, date and source tarball (url, sha256) from the manifest, + .stamp the sha256 of each extracted archive + Each archive links its own set of components, so each keeps its own licenses// folder: the output + for one platform is the same whichever other platforms were extracted before. .PARAMETER Platform current (default), all, or one or more manifest asset keys (windows-x64, linux-x86_64, linux-aarch64, macos-arm64-x86_64). +.PARAMETER Force + Download (if not cached) and extract the chosen archives again even if .stamp says they are up to date. +.PARAMETER Verify + Check that the output holds what the manifest pins for the chosen platforms, and fail if it does not: .stamp has + each archive's manifest sha256, every expected file exists, licenses/ has only archive folders, and + openslide-bin.json matches the manifest. Without -Force nothing is downloaded or extracted; with -Force the chosen + archives are extracted again first. Packing runs this (-Platform all -Verify) first. #> [CmdletBinding()] param( [string[]]$Platform = @('current'), [string]$Manifest, [string]$Destination, - [switch]$Force + [switch]$Force, + [switch]$Verify ) $ErrorActionPreference = 'Stop' $ProgressPreference = 'SilentlyContinue' @@ -29,6 +41,9 @@ $downloads = Join-Path $repoRoot 'artifacts/downloads' $m = Get-Content $Manifest -Raw | ConvertFrom-Json $allKeys = @($m.assets.PSObject.Properties.Name) +if (-not $m.source -or -not $m.source.url -or -not $m.source.sha256) { + throw "$Manifest has no source tarball (source.url and source.sha256). Run eng/Update-OpenSlideManifest.ps1 to regenerate it." +} # --- choose archives ------------------------------------------------------- $keys = foreach ($p in $Platform) { @@ -50,15 +65,33 @@ $keys = foreach ($p in $Platform) { } $keys = @($keys | Select-Object -Unique) +# openslide-bin.json: which openslide-bin build the binaries are, and its source tarball. +$binInfo = [ordered]@{ + channel = "$($m.channel)" + binVersion = "$($m.binVersion)" + openslideVersion = "$($m.openslideVersion)" + openslideCommit = "$($m.openslideCommit)" + date = if ($m.date -is [datetime]) { $m.date.ToString('yyyy-MM-dd') } else { "$($m.date)" } + source = [ordered]@{ url = "$($m.source.url)"; sha256 = "$($m.source.sha256)".ToLowerInvariant() } +} +$binInfoJson = (($binInfo | ConvertTo-Json -Depth 5) -replace "`r`n", "`n") + "`n" +$binInfoPath = Join-Path $Destination 'openslide-bin.json' + # --- stamp ----------------------------------------------------------------- -New-Item -ItemType Directory -Force $Destination | Out-Null $stampPath = Join-Path $Destination '.stamp' -$stamp = [ordered]@{} -if (Test-Path $stampPath) { - foreach ($line in Get-Content $stampPath) { - $parts = $line -split '\s+', 2 - if ($parts.Count -eq 2) { $stamp[$parts[0]] = $parts[1] } +function Read-Stamp { + $s = [ordered]@{} + if (Test-Path $stampPath) { + foreach ($line in Get-Content $stampPath) { + $parts = $line -split '\s+', 2 + if ($parts.Count -eq 2) { $s[$parts[0]] = $parts[1] } + } } + $s +} +function Save-Stamp($Stamp) { + [string[]]$lines = @($Stamp.GetEnumerator() | ForEach-Object { "$($_.Key) $($_.Value)" }) + Set-Content -Path $stampPath -Value $lines -Encoding utf8NoBOM } # --- helpers --------------------------------------------------------------- @@ -116,14 +149,16 @@ function Expand-OpenSlideArchive([string]$Archive, [string]$To) { } finally { Pop-Location } } -# Files that must exist for a key to count as extracted (guards against a stale .stamp). +# Files that must exist for a key to count as extracted (guards against a stale .stamp or an older layout). function Get-ExpectedOutputs([string]$Key) { switch ($Key) { - 'windows-x64' { 'win-x64/libopenslide-1.dll', 'msvc/x64/libopenslide.lib', 'include/openslide/openslide.h' } + 'windows-x64' { 'win-x64/libopenslide-1.dll', 'msvc/x64/libopenslide.lib', 'include/openslide/openslide.h', 'include/openslide/openslide-features.h' } 'linux-x86_64' { 'linux-x64/libopenslide-1.so' } 'linux-aarch64' { 'linux-arm64/libopenslide-1.so' } 'macos-arm64-x86_64' { 'osx-arm64/libopenslide-1.dylib', 'osx-x64/libopenslide-1.dylib' } } + "licenses/$Key/VERSIONS.md" + "licenses/$Key/OpenSlide/COPYING.LESSER" } function Copy-Native([string]$From, [string]$ToRelative) { @@ -138,7 +173,43 @@ function Find-Single([string]$Dir, [scriptblock]$Filter, [string]$What) { $hits[0].FullName } +function Test-Staged { + $stamp = Read-Stamp + $problems = [Collections.Generic.List[string]]::new() + foreach ($key in $keys) { + $sha = $m.assets.$key.sha256.ToLowerInvariant() + if ($stamp[$key] -ne $sha) { $problems.Add("${key}: .stamp has '$($stamp[$key])', the manifest pins $sha") } + foreach ($rel in Get-ExpectedOutputs $key) { + if (-not (Test-Path -PathType Leaf (Join-Path $Destination $rel))) { $problems.Add("${key}: $rel is missing") } + } + } + foreach ($entry in @(Get-ChildItem (Join-Path $Destination 'licenses') -Force -ErrorAction SilentlyContinue)) { + if (-not $entry.PSIsContainer -or $entry.Name -notin $allKeys) { $problems.Add("licenses/$($entry.Name) is not the licenses folder of an archive in the manifest") } + } + if (-not (Test-Path -PathType Leaf $binInfoPath)) { $problems.Add('openslide-bin.json is missing') } + elseif (((Get-Content $binInfoPath -Raw) -replace "`r`n", "`n") -cne $binInfoJson) { $problems.Add('openslide-bin.json does not match the manifest') } + if ($problems.Count -gt 0) { + throw "$Destination does not hold what $Manifest pins:`n - $($problems -join "`n - ")`nRun eng/Get-OpenSlide.ps1 -Platform $($Platform -join ',') -Force." + } + Write-Host "Verified $Destination against $Manifest ($($keys -join ', '))." +} + +# --- verify only ------------------------------------------------------------- +if ($Verify -and -not $Force) { + Test-Staged + return +} + # --- process --------------------------------------------------------------- +New-Item -ItemType Directory -Force $Destination | Out-Null +# Earlier versions put the licenses/, VERSIONS.md, versions.json and CHANGELOG.md of whichever archive came last at +# the root; remove them so that only the per-archive folders remain. +foreach ($file in 'VERSIONS.md', 'versions.json', 'CHANGELOG.md') { Remove-Item (Join-Path $Destination $file) -Force -ErrorAction SilentlyContinue } +Get-ChildItem (Join-Path $Destination 'licenses') -Force -ErrorAction SilentlyContinue | + Where-Object { -not $_.PSIsContainer -or $_.Name -notin $allKeys } | + Remove-Item -Recurse -Force + +$stamp = Read-Stamp foreach ($key in $keys) { $sha = $m.assets.$key.sha256.ToLowerInvariant() $missing = @(Get-ExpectedOutputs $key | Where-Object { -not (Test-Path (Join-Path $Destination $_)) }) @@ -148,6 +219,10 @@ foreach ($key in $keys) { } $archive = Get-Archive $key + # Until this archive is fully extracted, .stamp must not claim it. + $stamp.Remove($key) + Save-Stamp $stamp + $tmp = Join-Path ([IO.Path]::GetTempPath()) ('osl-' + [guid]::NewGuid().ToString('N')) New-Item -ItemType Directory $tmp | Out-Null try { @@ -173,23 +248,35 @@ foreach ($key in $keys) { } } - # Shared, platform-independent files (identical across archives; last one wins). - foreach ($dir in 'include', 'licenses') { - $src = Join-Path $root $dir - if (Test-Path $src) { - New-Item -ItemType Directory -Force (Join-Path $Destination $dir) | Out-Null - Copy-Item (Join-Path $src '*') (Join-Path $Destination $dir) -Recurse -Force - } - } - foreach ($file in 'VERSIONS.md', 'versions.json', 'CHANGELOG.md') { - $src = Join-Path $root $file - if (Test-Path $src) { Copy-Item $src (Join-Path $Destination $file) -Force } + # The public headers are the same in every archive. + $include = Join-Path $root 'include' + if (Test-Path $include) { + New-Item -ItemType Directory -Force (Join-Path $Destination 'include') | Out-Null + Copy-Item (Join-Path $include '*') (Join-Path $Destination 'include') -Recurse -Force } + + # This archive's licenses and component versions, replacing any earlier copy. + $licenses = Join-Path $root 'licenses' + $versionsMd = Join-Path $root 'VERSIONS.md' + if (-not (Test-Path -PathType Container $licenses)) { throw "$archive has no licenses/ folder." } + if (-not (Test-Path -PathType Leaf $versionsMd)) { throw "$archive has no VERSIONS.md." } + $licenseDir = Join-Path $Destination "licenses/$key" + if (Test-Path $licenseDir) { Remove-Item $licenseDir -Recurse -Force } + New-Item -ItemType Directory -Force $licenseDir | Out-Null + Copy-Item (Join-Path $licenses '*') $licenseDir -Recurse -Force + Copy-Item $versionsMd $licenseDir -Force } finally { Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue } $stamp[$key] = $sha - $stamp.GetEnumerator() | ForEach-Object { "$($_.Key) $($_.Value)" } | Set-Content $stampPath -Encoding utf8NoBOM + Save-Stamp $stamp Write-Host "Extracted $key" } + +if (-not (Test-Path -PathType Leaf $binInfoPath) -or (Get-Content $binInfoPath -Raw) -cne $binInfoJson) { + Set-Content -Path $binInfoPath -Value $binInfoJson -NoNewline -Encoding utf8NoBOM + Write-Host "Wrote $binInfoPath" +} + +if ($Verify) { Test-Staged } diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index fd19200..563cec7 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -6,6 +6,9 @@ an ASP.NET Core app, net48 x64 and AnyCPU, no-runtime, the installed tool, the d self-contained as one executable with its licenses for this machine's RID, and a Visual Studio C++ project), plus the 32-bit build warning. +Packing first checks, with eng/Get-OpenSlide.ps1 -Platform all -Verify, that artifacts/native holds exactly the +binaries and notices eng/openslide.json pins. + -SkipPack reuses the nupkgs already in artifacts/smoke-feed (CI downloads them there) instead of packing; everything else, including the nupkg content assertions, still runs. net48 and the C++ stage only run on Windows. @@ -46,6 +49,9 @@ if ($SkipPack) { } } else { + # Pack only what eng/openslide.json pins: every platform's binaries, licenses and openslide-bin.json. + & (Join-Path $PSScriptRoot 'Get-OpenSlide.ps1') -Platform all -Verify + foreach ($proj in 'src/OpenSlideSharp/OpenSlideSharp.csproj', 'src/OpenSlideSharp.SkiaSharp/OpenSlideSharp.SkiaSharp.csproj', 'src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj', 'src/OpenSlideSharp.AspNetCore/OpenSlideSharp.AspNetCore.csproj') { Invoke-Native dotnet @('pack', (Join-Path $root $proj), '-c', 'Release', '-o', $feed, "-p:Version=$Version") } @@ -66,6 +72,21 @@ function Get-NupkgEntries([string]$Path) { finally { $zip.Dispose() } } +function Get-NupkgText([string]$Path, [string]$Name) { + $zip = [IO.Compression.ZipFile]::OpenRead($Path) + try { + $e = $zip.GetEntry($Name) + if (-not $e) { throw "$Path has no '$Name'" } + $sr = New-Object IO.StreamReader($e.Open()) + try { return $sr.ReadToEnd() } finally { $sr.Dispose() } + } + finally { $zip.Dispose() } +} + +# The openslide-bin build the packages carry, and its archives (asset keys), each with its own licenses//. +$manifest = Get-Content (Join-Path $root 'eng/openslide.json') -Raw | ConvertFrom-Json +$binKeys = @($manifest.assets.PSObject.Properties.Name) + $runtimeNupkg = Join-Path $feed "OpenSlideSharp.runtime.$Version.nupkg" $entries = Get-NupkgEntries $runtimeNupkg $entries | ForEach-Object { " runtime: $_" } @@ -82,15 +103,32 @@ $required = @( 'build/native/lib/x64/libopenslide.lib', 'lib/netstandard2.0/_._', 'buildTransitive/net462/OpenSlideSharp.runtime.targets', - 'VERSIONS.md', 'versions.json', 'README.md', 'openslide_logo.png' + 'LICENSE.txt', 'openslide-bin.json', 'README.md', 'openslide_logo.png' ) +# Each archive's notices: licenses// with VERSIONS.md and openslide-bin's licenses// layout. +foreach ($key in $binKeys) { $required += "licenses/$key/VERSIONS.md", "licenses/$key/OpenSlide/COPYING.LESSER" } foreach ($r in $required) { if ($entries -notcontains $r) { throw "runtime nupkg is missing '$r'" } } -if (-not ($entries | Where-Object { $_ -like 'licenses/*' })) { throw "runtime nupkg has no licenses/**" } -# openslide-bin's layout, licenses//, without the project directory doubled. -if ($entries -notcontains 'licenses/OpenSlide/COPYING.LESSER') { throw "runtime nupkg is missing 'licenses/OpenSlide/COPYING.LESSER'" } -if ($entries | Where-Object { $_ -match '^licenses/([^/]+)/\1/' }) { throw 'runtime nupkg has doubled directories under licenses/' } +$licenseRoots = @($entries | Where-Object { $_ -like 'licenses/*' } | ForEach-Object { ($_ -split '/')[1] } | Sort-Object -Unique) +if (($licenseRoots -join ', ') -cne (($binKeys | Sort-Object) -join ', ')) { + throw "runtime nupkg has licenses/{$($licenseRoots -join ', ')}, expected one folder per openslide-bin archive: $(($binKeys | Sort-Object) -join ', ')" +} +if ($entries | Where-Object { $_ -match '^licenses/[^/]+/([^/]+)/\1/' }) { throw 'runtime nupkg has doubled directories under licenses//' } +# The old layout's single VERSIONS.md and versions.json, of whichever archive was extracted last, are gone. +foreach ($stale in 'VERSIONS.md', 'versions.json') { + if ($entries -contains $stale) { throw "runtime nupkg still has '$stale' at its root" } +} +# openslide-bin.json describes exactly the build in eng/openslide.json, with its source tarball. +$binJson = Get-NupkgText $runtimeNupkg 'openslide-bin.json' | ConvertFrom-Json +$binFields = @($binJson.PSObject.Properties.Name) +if (($binFields -join ', ') -cne 'channel, binVersion, openslideVersion, openslideCommit, date, source') { throw "runtime openslide-bin.json has the fields '$($binFields -join ', ')'" } +foreach ($f in 'channel', 'binVersion', 'openslideVersion', 'openslideCommit', 'date') { + if ("$($binJson.$f)" -cne "$($manifest.$f)") { throw "runtime openslide-bin.json: $f is '$($binJson.$f)', eng/openslide.json has '$($manifest.$f)'" } +} +if ("$($binJson.source.url)" -cne "$($manifest.source.url)" -or "$($binJson.source.sha256)" -cne "$($manifest.source.sha256)") { + throw "runtime openslide-bin.json: source is '$($binJson.source.url)' ($($binJson.source.sha256)), eng/openslide.json has '$($manifest.source.url)' ($($manifest.source.sha256))" +} if ($entries | Where-Object { $_ -match '\.debug$' }) { throw "runtime nupkg contains .debug files" } if ($entries | Where-Object { $_ -match '\.dSYM(/|$)' }) { throw "runtime nupkg contains .dSYM entries" } if ($entries | Where-Object { $_ -match '(^|/)slidetool' }) { throw "runtime nupkg contains slidetool" } @@ -109,42 +147,59 @@ function Get-NuspecXml([string]$Path) { $rtMeta = (Get-NuspecXml $runtimeNupkg).package.metadata $rtDeps = @($rtMeta.dependencies.group | Where-Object { $_ -and $_.HasChildNodes }) if ($rtMeta.dependencies -and ($rtMeta.dependencies.dependency -or $rtDeps.Count -gt 0)) { throw "runtime nuspec declares dependencies" } -if ($rtMeta.license.InnerText -ne 'LGPL-2.1-only') { throw "runtime nuspec license is '$($rtMeta.license.InnerText)', expected LGPL-2.1-only" } +if ($rtMeta.license.type -ne 'file' -or $rtMeta.license.InnerText -ne 'LICENSE.txt') { + throw "runtime nuspec license is '$($rtMeta.license.InnerText)' ($($rtMeta.license.type)), expected LICENSE.txt" +} if (($rtMeta.tags -split '\s+') -notcontains 'native') { throw "runtime nuspec tags lack 'native': $($rtMeta.tags)" } +# Asserts a nuspec's dependency groups exactly: the same target frameworks as $Expected's keys, and in each group the +# same package ids as that key's table, with those minimum versions. +function Assert-DependencyGroups([string]$Name, $Meta, [hashtable]$Expected) { + $groups = @($Meta.dependencies.group | Where-Object { $_ }) + $tfms = ($groups | ForEach-Object { $_.targetFramework } | Sort-Object) -join ', ' + $wantTfms = ($Expected.Keys | Sort-Object) -join ', ' + if ($tfms -cne $wantTfms) { throw "$Name nuspec has dependency groups for '$tfms', expected exactly '$wantTfms'" } + foreach ($g in $groups) { + $want = $Expected[$g.targetFramework] + $deps = @{} + foreach ($d in @($g.dependency | Where-Object { $_ })) { $deps[$d.id] = $d.version } + $ids = ($deps.Keys | Sort-Object) -join ', ' + $wantIds = ($want.Keys | Sort-Object) -join ', ' + if ($ids -cne $wantIds) { throw "$Name nuspec group '$($g.targetFramework)' depends on '$ids', expected exactly '$wantIds'" } + foreach ($id in $want.Keys) { + # NuGet writes a minimum version as '[x, )' or 'x' depending on the packer; accept both. + if ($deps[$id] -notmatch ('^\[?' + [regex]::Escape($want[$id]) + '(, \))?\]?$')) { + throw "$Name nuspec group '$($g.targetFramework)': $id version is '$($deps[$id])', expected $($want[$id])" + } + } + } +} + +# The versions the packages were built against, from central package management. +$central = @{} +foreach ($pv in ([xml](Get-Content (Join-Path $root 'Directory.Packages.props') -Raw)).SelectNodes('//PackageVersion')) { $central[$pv.Include] = $pv.Version } + +# The core and Skia packages never depend on the runtime package: the native library is the app's choice. $coreMeta = (Get-NuspecXml (Join-Path $feed "OpenSlideSharp.$Version.nupkg")).package.metadata -if ($coreMeta.SelectNodes("//*[local-name()='dependency'][@id='OpenSlideSharp.runtime']").Count -gt 0) { throw "core nuspec depends on OpenSlideSharp.runtime" } +Assert-DependencyGroups 'core' $coreMeta @{ + 'net10.0' = @{} + '.NETStandard2.0' = @{ 'System.Memory' = $central['System.Memory'] } + '.NETStandard2.1' = @{} +} $skiaMeta = (Get-NuspecXml (Join-Path $feed "OpenSlideSharp.SkiaSharp.$Version.nupkg")).package.metadata -if ($skiaMeta.SelectNodes("//*[local-name()='dependency'][@id='OpenSlideSharp.runtime']").Count -gt 0) { throw "Skia nuspec depends on OpenSlideSharp.runtime" } if ($skiaMeta.license.InnerText -ne 'MIT') { throw "Skia nuspec license is '$($skiaMeta.license.InnerText)', expected MIT" } -$skiaGroups = @($skiaMeta.dependencies.group) -if ($skiaGroups.Count -lt 3) { throw "Skia nuspec has $($skiaGroups.Count) dependency groups, expected one per target framework (3)" } -foreach ($g in $skiaGroups) { - $deps = @{} - foreach ($d in @($g.dependency)) { $deps[$d.id] = $d.version } - $expect = @{ 'OpenSlideSharp' = $Version; 'SkiaSharp' = '3.119.4'; 'SkiaSharp.NativeAssets.Linux.NoDependencies' = '3.119.4' } - foreach ($id in $expect.Keys) { - if (-not $deps.ContainsKey($id)) { throw "Skia nuspec group '$($g.targetFramework)' lacks a dependency on $id" } - # NuGet writes a minimum version as '[x, )' or 'x' depending on the packer; accept both. - if ($deps[$id] -notmatch ('^\[?' + [regex]::Escape($expect[$id]) + '(, \))?\]?$')) { throw "Skia nuspec group '$($g.targetFramework)': $id version is '$($deps[$id])', expected $($expect[$id])" } - } +$skiaDeps = @{ + 'OpenSlideSharp' = $Version + 'SkiaSharp' = $central['SkiaSharp'] + 'SkiaSharp.NativeAssets.Linux.NoDependencies' = $central['SkiaSharp.NativeAssets.Linux.NoDependencies'] } +Assert-DependencyGroups 'Skia' $skiaMeta @{ 'net10.0' = $skiaDeps; '.NETStandard2.0' = $skiaDeps; '.NETStandard2.1' = $skiaDeps } # OpenSlideSharp.AspNetCore: net10.0 only, on the core and Skia packages of the same version and the ASP.NET Core # shared framework. The native library is the app's choice, so no runtime package. $aspMeta = (Get-NuspecXml (Join-Path $feed "OpenSlideSharp.AspNetCore.$Version.nupkg")).package.metadata -$aspGroups = @($aspMeta.dependencies.group) -if ($aspGroups.Count -ne 1 -or $aspGroups[0].targetFramework -ne 'net10.0') { - throw "AspNetCore nuspec dependency groups are '$(($aspGroups | ForEach-Object { $_.targetFramework }) -join ', ')', expected only net10.0" -} -$aspDeps = @{} -foreach ($d in @($aspGroups[0].dependency)) { $aspDeps[$d.id] = $d.version } -$aspIds = ($aspDeps.Keys | Sort-Object) -join ', ' -if ($aspIds -ne 'OpenSlideSharp, OpenSlideSharp.SkiaSharp') { throw "AspNetCore nuspec depends on '$aspIds', expected exactly OpenSlideSharp and OpenSlideSharp.SkiaSharp" } -foreach ($id in $aspDeps.Keys) { - if ($aspDeps[$id] -notmatch ('^\[?' + [regex]::Escape($Version) + '(, \))?\]?$')) { throw "AspNetCore nuspec: $id version is '$($aspDeps[$id])', expected $Version" } -} +Assert-DependencyGroups 'AspNetCore' $aspMeta @{ 'net10.0' = @{ 'OpenSlideSharp' = $Version; 'OpenSlideSharp.SkiaSharp' = $Version } } if ($aspMeta.SelectNodes("//*[local-name()='frameworkReference'][@name='Microsoft.AspNetCore.App']").Count -ne 1) { throw 'AspNetCore nuspec lacks frameworkReference Microsoft.AspNetCore.App' } @@ -181,15 +236,15 @@ if ($extraRids.Count -gt 0) { throw "tool nupkg has native assets for unsupporte # The tool redistributes LGPL-2.1 OpenSlide (with openslide-bin's statically linked libraries), SkiaSharp and Skia, # and the OpenSeadragon viewer files: their licenses must travel with it, and the license expression must name them. $toolEntries | Where-Object { $_ -like 'licenses/*' } | ForEach-Object { " tool: $_" } -if ($toolEntries -notcontains 'licenses/openslide-bin/VERSIONS.md') { throw "tool nupkg is missing 'licenses/openslide-bin/VERSIONS.md'" } -if ($toolEntries -notcontains 'licenses/openslide-bin/OpenSlide/COPYING.LESSER') { throw "tool nupkg is missing OpenSlide's license, 'licenses/openslide-bin/OpenSlide/COPYING.LESSER'" } -if ($toolEntries | Where-Object { $_ -match '^licenses/openslide-bin/([^/]+)/\1/' }) { throw 'tool nupkg has doubled directories under licenses/openslide-bin/' } -$openslideBinLicenses = @($toolEntries | Where-Object { $_ -match '^licenses/openslide-bin/[^/]+/.' }) -$runtimeLicenses = @($entries | Where-Object { $_ -match '^licenses/[^/]+/.' }) -if ($openslideBinLicenses.Count -ne $runtimeLicenses.Count) { - throw "tool nupkg has $($openslideBinLicenses.Count) files under licenses/openslide-bin/, the runtime nupkg $($runtimeLicenses.Count) under licenses/" -} -if (-not ($openslideBinLicenses | Where-Object { $_ -match '/(COPYING|LICENSE)[^/]*$' })) { throw 'tool nupkg has no COPYING or LICENSE file under licenses/openslide-bin/' } +foreach ($r in @('licenses/openslide-bin/openslide-bin.json') + @($binKeys | ForEach-Object { "licenses/openslide-bin/$_/VERSIONS.md", "licenses/openslide-bin/$_/OpenSlide/COPYING.LESSER" })) { + if ($toolEntries -notcontains $r) { throw "tool nupkg is missing '$r'" } +} +# Exactly the runtime package's licenses// trees, under licenses/openslide-bin/. +$openslideBinLicenses = @($toolEntries | Where-Object { $_ -like 'licenses/openslide-bin/*/*' } | ForEach-Object { $_.Substring('licenses/openslide-bin/'.Length) } | Sort-Object) +$runtimeLicenses = @($entries | Where-Object { $_ -like 'licenses/*/*' } | ForEach-Object { $_.Substring('licenses/'.Length) } | Sort-Object) +if (($openslideBinLicenses -join "`n") -cne ($runtimeLicenses -join "`n")) { + throw "tool nupkg has $($openslideBinLicenses.Count) files under licenses/openslide-bin//, not the runtime nupkg's $($runtimeLicenses.Count) under licenses//" +} foreach ($r in 'licenses/viewer/LICENSE.openseadragon', 'licenses/viewer/LICENSE.openseadragon-scalebar', 'licenses/skiasharp/LICENSE.txt', 'licenses/skiasharp/THIRD-PARTY-NOTICES.txt') { if ($toolEntries -notcontains $r) { throw "tool nupkg is missing '$r'" } } @@ -331,11 +386,13 @@ $unexpected = @($paths | Where-Object { $_ -ne $viewerName -and -not $_.StartsWi if ($paths -notcontains $viewerName -or $unexpected.Count -gt 0) { throw "[viewer] expected $viewerName and licenses/ in $viewerPublish, found: $($paths -join ', ')" } -foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', 'licenses/openslide-bin/VERSIONS.md') { +# The license texts of OpenSlide and of the libraries linked into it, from the runtime package: at least those of the +# openslide-bin archive this RID's library comes from. +$viewerBinKey = @{ 'win-x64' = 'windows-x64'; 'linux-x64' = 'linux-x86_64'; 'linux-arm64' = 'linux-aarch64'; 'osx-arm64' = 'macos-arm64-x86_64'; 'osx-x64' = 'macos-arm64-x86_64' }[$viewerRid] +foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', 'licenses/openslide-bin/openslide-bin.json', + "licenses/openslide-bin/$viewerBinKey/VERSIONS.md", "licenses/openslide-bin/$viewerBinKey/OpenSlide/COPYING.LESSER") { if ($paths -notcontains $required) { throw "[viewer] $required is not in $viewerPublish" } } -# The license texts of OpenSlide and of the libraries linked into it, from the runtime package. -if (-not ($paths | Where-Object { $_ -like 'licenses/openslide-bin/OpenSlide/*' })) { throw "[viewer] OpenSlide's license is not in licenses/openslide-bin/" } $binLicenses = @($paths | Where-Object { $_ -like 'licenses/openslide-bin/*/*' }) Write-Host "licenses/openslide-bin: $($binLicenses.Count) license files" # The bundle extracts its native libraries when it starts; a fresh extraction directory shows they came from it. @@ -364,10 +421,25 @@ Write-Host "PASS: viewer ($viewerRid)" # 7. Native C++ consumer (Visual Studio vcxproj via packages.config), Windows only. if ($IsWindows) { $cppProj = Join-Path $root 'test/NativeCppSmoke' + # nuget.exe is pinned to one release (see https://dist.nuget.org/tools.json) and used only with this sha256. + $nugetVersion = '8.0.0' + $nugetSha256 = 'd4ddb222cb8fca8200b59e82286c0cba9c29b4fce6f9835fdfa54e67c9483d07' $nuget = Join-Path $artifacts 'tools/nuget.exe' + if ((Test-Path $nuget) -and (Get-FileHash $nuget -Algorithm SHA256).Hash -ne $nugetSha256) { + Write-Host "Cached $nuget is not nuget.exe $nugetVersion; downloading again." + Remove-Item $nuget -Force + } if (-not (Test-Path $nuget)) { New-Item -ItemType Directory -Force (Split-Path $nuget) | Out-Null - Invoke-WebRequest 'https://dist.nuget.org/win-x86-commandline/latest/nuget.exe' -OutFile $nuget + $part = "$nuget.part" + try { Invoke-WebRequest "https://dist.nuget.org/win-x86-commandline/v$nugetVersion/nuget.exe" -OutFile $part } + catch { Remove-Item $part -Force -ErrorAction SilentlyContinue; throw } + $actual = (Get-FileHash $part -Algorithm SHA256).Hash.ToLowerInvariant() + if ($actual -ne $nugetSha256) { + Remove-Item $part -Force + throw "nuget.exe $nugetVersion has sha256 $actual, expected $nugetSha256. The download was deleted." + } + Move-Item $part $nuget -Force } Write-Host '== smoke: native C++ (x64)' diff --git a/eng/Update-OpenSlideManifest.ps1 b/eng/Update-OpenSlideManifest.ps1 index ac7a299..528e9f0 100644 --- a/eng/Update-OpenSlideManifest.ps1 +++ b/eng/Update-OpenSlideManifest.ps1 @@ -6,7 +6,8 @@ .DESCRIPTION nightly: latest prerelease with assets in openslide/builds. stable : latest non-prerelease in openslide/openslide-bin. - Downloads the four archives into artifacts/downloads and records their sha256. + Downloads the four binary archives and the openslide-bin source tarball into artifacts/downloads and records their + sha256. Every file must hash to the sha256 digest GitHub publishes for that release asset, or nothing is written. Honours $env:GITHUB_TOKEN for authenticated GitHub API calls. #> [CmdletBinding()] @@ -35,6 +36,8 @@ function Invoke-GitHubApi([string]$Path) { Invoke-RestMethod -Uri "https://api.github.com/$Path" -Headers $headers } +function Get-Sha256([string]$Path) { (Get-FileHash $Path -Algorithm SHA256).Hash.ToLowerInvariant() } + $repo = if ($Channel -eq 'nightly') { 'openslide/builds' } else { 'openslide/openslide-bin' } $release = $null @@ -53,30 +56,53 @@ $tagName = $release.tag_name $binVersion = $tagName -replace '^v', '' Write-Host "Release: $repo $tagName" -New-Item -ItemType Directory -Force $downloads | Out-Null -$assets = [ordered]@{} -foreach ($key in $assetSuffixes.Keys) { - $asset = $release.assets | Where-Object { $_.name -like "openslide-bin-*$($assetSuffixes[$key])" } | Select-Object -First 1 - if (-not $asset) { throw "Release $tagName has no asset matching *$($assetSuffixes[$key])." } - $path = Join-Path $downloads $asset.name - # A cached file of the wrong size is a leftover from an interrupted download. - if ((Test-Path $path) -and (Get-Item $path).Length -ne $asset.size) { Remove-Item $path -Force } +# Downloads a release asset into artifacts/downloads (reusing a cached copy only if it hashes right) and checks it +# against the sha256 digest the GitHub release API reports for it. Returns the manifest entry: url and sha256. +function Get-VerifiedAsset($Asset) { + if ("$($Asset.digest)" -notmatch '^sha256:([0-9a-fA-F]{64})$') { + throw "Release $tagName reports no sha256 digest for $($Asset.name) (digest: '$($Asset.digest)'), so it cannot be verified." + } + $expected = $Matches[1].ToLowerInvariant() + $url = $Asset.browser_download_url + if (-not "$url".StartsWith("https://github.com/$repo/releases/download/", [StringComparison]::Ordinal)) { + throw "Asset $($Asset.name) has an unexpected download URL: $url" + } + $path = Join-Path $downloads $Asset.name + if ((Test-Path $path) -and (Get-Sha256 $path) -ne $expected) { + Write-Host "Cached $($Asset.name) does not match the release digest; downloading again." + Remove-Item $path -Force + } if (-not (Test-Path $path)) { - Write-Host "Downloading $($asset.name)" - # Download to .part and rename only on success, so a failed download is never cached or hashed. + Write-Host "Downloading $($Asset.name)" + # Download to .part and rename only after the hash checks out, so a failed download is never cached. $part = "$path.part" Remove-Item $part -Force -ErrorAction SilentlyContinue - try { Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $part } + try { Invoke-WebRequest -Uri $url -OutFile $part } catch { Remove-Item $part -Force -ErrorAction SilentlyContinue; throw } - if ((Get-Item $part).Length -ne $asset.size) { Remove-Item $part -Force; throw "Downloaded $($asset.name) has the wrong size." } + $actual = Get-Sha256 $part + if ($actual -ne $expected) { + Remove-Item $part -Force + throw "SHA256 mismatch for $($Asset.name): the release digest is $expected, the download hashes to $actual. The downloaded file was deleted." + } Move-Item $part $path } - $assets[$key] = [ordered]@{ - url = $asset.browser_download_url - sha256 = (Get-FileHash $path -Algorithm SHA256).Hash.ToLowerInvariant() - } + [ordered]@{ url = $url; sha256 = $expected } } +New-Item -ItemType Directory -Force $downloads | Out-Null +$assets = [ordered]@{} +foreach ($key in $assetSuffixes.Keys) { + $asset = $release.assets | Where-Object { $_.name -like "openslide-bin-*$($assetSuffixes[$key])" } | Select-Object -First 1 + if (-not $asset) { throw "Release $tagName has no asset matching *$($assetSuffixes[$key])." } + $assets[$key] = Get-VerifiedAsset $asset +} + +# The corresponding source of every binary archive: openslide-bin's source tarball of the same version. +$sourceName = "openslide-bin-$binVersion.tar.gz" +$sourceAsset = $release.assets | Where-Object { $_.name -eq $sourceName } | Select-Object -First 1 +if (-not $sourceAsset) { throw "Release $tagName has no source tarball $sourceName." } +$source = Get-VerifiedAsset $sourceAsset + # Read versions.json straight out of the windows zip. $zipName = ($release.assets | Where-Object { $_.name -like "openslide-bin-*$($assetSuffixes['windows-x64'])" } | Select-Object -First 1).name $zip = Join-Path $downloads $zipName @@ -115,6 +141,7 @@ $manifest = [ordered]@{ openslideCommit = $commit date = $date releaseUrl = "https://github.com/$repo/releases/tag/$([uri]::EscapeDataString($tagName))" + source = $source assets = $assets } New-Item -ItemType Directory -Force (Split-Path -Parent $OutFile) | Out-Null diff --git a/eng/openslide.json b/eng/openslide.json index ce0ccb5..8a86100 100644 --- a/eng/openslide.json +++ b/eng/openslide.json @@ -5,6 +5,10 @@ "openslideCommit": "174630bf", "date": "2026-11-02", "releaseUrl": "https://github.com/openslide/builds/releases/tag/v4.0.1.2%2B20261102.nightly", + "source": { + "url": "https://github.com/openslide/builds/releases/download/v4.0.1.2%2B20261102.nightly/openslide-bin-4.0.1.2%2B20261102.nightly.tar.gz", + "sha256": "6d3e485ae85566edaad8b69c0dd606bccd7b7b16aa6354c1258e66f4337708c1" + }, "assets": { "windows-x64": { "url": "https://github.com/openslide/builds/releases/download/v4.0.1.2%2B20261102.nightly/openslide-bin-4.0.1.2%2B20261102.nightly-windows-x64.zip", diff --git a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj index e356642..90667a6 100644 --- a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj +++ b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj @@ -52,8 +52,9 @@ <_ViewerPackageFile Include="@(ResolvedFileToPublish)" Condition="'%(ResolvedFileToPublish.NuGetPackageId)' != ''" @@ -79,7 +80,7 @@ <_ViewerLicense Include="@(_OpenSlideBinLicense)" RelativePath="licenses/openslide-bin/%(_OpenSlideBinLicense.RecursiveDir)%(_OpenSlideBinLicense.Filename)%(_OpenSlideBinLicense.Extension)" /> - <_ViewerLicense Include="$(_OpenSlideBinDir)/VERSIONS.md" RelativePath="licenses/openslide-bin/VERSIONS.md" /> + <_ViewerLicense Include="$(_OpenSlideBinDir)/openslide-bin.json" RelativePath="licenses/openslide-bin/openslide-bin.json" /> <_ViewerLicense Include="@(_ViewerPackageLicense)" RelativePath="licenses/%(_ViewerPackageLicense.PackageId)/%(_ViewerPackageLicense.Filename)%(_ViewerPackageLicense.Extension)" /> <_ViewerLicense Include="$(MSBuildThisFileDirectory)..\..\LICENSE" RelativePath="licenses/OpenSlideSharp/LICENSE" /> diff --git a/samples/OpenSlideSharp.Viewer/README.md b/samples/OpenSlideSharp.Viewer/README.md index 95d011d..bb18793 100644 --- a/samples/OpenSlideSharp.Viewer/README.md +++ b/samples/OpenSlideSharp.Viewer/README.md @@ -54,7 +54,7 @@ The native libraries are inside the executable. It extracts them on first start ## Licenses -`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, with their versions in `VERSIONS.md`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them, and `SOURCE.md` says where OpenSlide's source code is and how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The planned GitHub release builds will ship this publish folder, executable and `licenses/`, as one archive per platform. +`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, with their versions in each platform's `VERSIONS.md` under `openslide-bin/`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them, and `SOURCE.md` says where OpenSlide's source code is and how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The planned GitHub release builds will ship this publish folder, executable and `licenses/`, as one archive per platform. ## Known issue on Windows diff --git a/samples/OpenSlideSharp.Viewer/SOURCE.md b/samples/OpenSlideSharp.Viewer/SOURCE.md index a09795a..3515dee 100644 --- a/samples/OpenSlideSharp.Viewer/SOURCE.md +++ b/samples/OpenSlideSharp.Viewer/SOURCE.md @@ -4,7 +4,8 @@ The viewer contains a build of [OpenSlide](https://openslide.org/) from [openslide-bin](https://github.com/openslide/openslide-bin): `libopenslide-1.dll` on Windows, `libopenslide-1.so` on Linux and `libopenslide-1.dylib` on macOS, which the executable extracts when it first starts. OpenSlide is licensed under the GNU Lesser General Public License 2.1, and the libraries linked into it under their own licenses: see -`openslide-bin/`, and `openslide-bin/VERSIONS.md` for their versions. +`openslide-bin//`, and `openslide-bin//VERSIONS.md` for their versions. +`openslide-bin/openslide-bin.json` names the openslide-bin build and its source tarball. ## Source code diff --git a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt index fd5d3ce..17848bc 100644 --- a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt +++ b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt @@ -13,11 +13,12 @@ file. 1. OpenSlide and the libraries linked into it (openslide-bin) License: OpenSlide: LGPL-2.1-only. The libraries statically linked into it (cairo, glib, libdicom, libffi, libjpeg-turbo, libpng, libtiff, libxml2, OpenJPEG, pixman, proxy-libintl, SQLite, uthash, zlib-ng, - Zstandard, as listed in VERSIONS.md) are each under their own license. + Zstandard, as listed in each platform's VERSIONS.md) are each under their own license. Upstream: https://openslide.org/ https://github.com/openslide/openslide-bin - Files: openslide-bin/VERSIONS.md (the components and their versions) - openslide-bin// (their license texts) + Files: openslide-bin//VERSIONS.md (the components and their versions) + openslide-bin/// (their license texts) + openslide-bin/openslide-bin.json (the openslide-bin build and its source tarball) Source code, and how to use another OpenSlide build instead: SOURCE.md. 2. SkiaSharp and Skia diff --git a/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj b/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj index 7608f95..d073636 100644 --- a/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj +++ b/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj @@ -38,9 +38,10 @@ @@ -48,9 +49,9 @@ - + - + diff --git a/src/OpenSlideSharp.Tool/README.md b/src/OpenSlideSharp.Tool/README.md index 23d7293..df0b1c7 100644 --- a/src/OpenSlideSharp.Tool/README.md +++ b/src/OpenSlideSharp.Tool/README.md @@ -65,7 +65,7 @@ Each worker holds one tile or chunk at a time, and OpenSlide keeps a tile cache The tool's own code is under the MIT license. The package also contains, each under its own license, which are in the package's `licenses/` folder: -- OpenSlide 4.x from [openslide-bin](https://github.com/openslide/openslide-bin), LGPL-2.1, with the libraries built into it (`licenses/openslide-bin/`, and `VERSIONS.md` listing their versions). The source is the openslide-bin source tarball of the same version. +- OpenSlide 4.x from [openslide-bin](https://github.com/openslide/openslide-bin), LGPL-2.1, with the libraries built into it (`licenses/openslide-bin//`, each with a `VERSIONS.md` listing their versions). The source is the openslide-bin source tarball named in `licenses/openslide-bin/openslide-bin.json`. - [SkiaSharp](https://github.com/mono/SkiaSharp), MIT, with Skia (BSD-3-Clause) and the libraries in its native build (`licenses/skiasharp/`). - [OpenSeadragon](https://openseadragon.github.io/), BSD-3-Clause, and its [scale bar plugin](https://github.com/usnistgov/OpenSeadragonScalebar), in the public domain (NIST), written with `-r` (`licenses/viewer/`). diff --git a/src/OpenSlideSharp.runtime/LICENSE.txt b/src/OpenSlideSharp.runtime/LICENSE.txt new file mode 100644 index 0000000..3b1fc36 --- /dev/null +++ b/src/OpenSlideSharp.runtime/LICENSE.txt @@ -0,0 +1,21 @@ +OpenSlideSharp.runtime: license information + +The native libraries in this package are builds of OpenSlide from openslide-bin +(https://github.com/openslide/openslide-bin). OpenSlide is licensed under the GNU Lesser General Public License, +version 2.1 (LGPL-2.1-only). The library of each platform statically links further components, each under its own +license. The full license texts of OpenSlide and of these components, and VERSIONS.md with their versions, are in +the licenses folder of that platform: + + licenses/windows-x64/ runtimes/win-x64/native/ and build/native/ (headers and import library) + licenses/linux-x86_64/ runtimes/linux-x64/native/ + licenses/linux-aarch64/ runtimes/linux-arm64/native/ + licenses/macos-arm64-x86_64/ runtimes/osx-arm64/native/ and runtimes/osx-x64/native/ + +OpenSlide's license text is licenses//OpenSlide/COPYING.LESSER. + +Source code: openslide-bin.json in this package names the openslide-bin build (binVersion) and its source tarball +(source.url, with its sha256 in source.sha256). The tarball holds the source code of OpenSlide and of every +component listed above, and the scripts that build these libraries from it. + +The MSBuild files under build/ and buildTransitive/ are part of OpenSlideSharp +(https://github.com/IOL0ol1/OpenSlideSharp) and are licensed under the MIT license. diff --git a/src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj b/src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj index ca2b533..ff2da4f 100644 --- a/src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj +++ b/src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj @@ -6,9 +6,14 @@ true $(NoWarn);NU5128 OpenSlideSharp.runtime - LGPL-2.1-only + + + LICENSE.txt openslide wsi native - Native OpenSlide 4.x libraries from openslide-bin (https://github.com/openslide/openslide-bin); source: openslide-bin source tarball of the same version. + Native OpenSlide 4.x libraries from openslide-bin (https://github.com/openslide/openslide-bin), LGPL-2.1, with the licenses of the components linked into each platform's library in licenses/; source: the openslide-bin source tarball named in openslide-bin.json. $([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)../../artifacts/native')) @@ -18,6 +23,8 @@ + + @@ -38,10 +45,14 @@ - + - - + + + @@ -50,8 +61,10 @@ Text="Missing native binary '$(OpenSlideNativeRoot)/%(OpenSlideNativeFile.Identity)'. Run 'pwsh eng/Get-OpenSlide.ps1 -Platform all' first." /> - + + diff --git a/src/OpenSlideSharp.runtime/README.md b/src/OpenSlideSharp.runtime/README.md index 7a29a19..ab36d01 100644 --- a/src/OpenSlideSharp.runtime/README.md +++ b/src/OpenSlideSharp.runtime/README.md @@ -12,7 +12,7 @@ OpenSlide ships Windows binaries for x64 only, so a .NET Framework app must run ## Licensing -This package is licensed under LGPL-2.1-only because it redistributes OpenSlide and its dependencies, each under its own license. See `licenses/` and `VERSIONS.md` inside the package for the exact components and versions. The corresponding source is the openslide-bin source tarball of the same version. +The native libraries are builds of OpenSlide (LGPL-2.1) from openslide-bin. Each platform's library statically links further components, each under its own license. `LICENSE.txt` in the package states the terms. `licenses//` (`windows-x64`, `linux-x86_64`, `linux-aarch64`, `macos-arm64-x86_64`) holds the full license texts of that platform's components and `VERSIONS.md` with their versions. `openslide-bin.json` names the openslide-bin build and its source tarball (URL and sha256), which is the corresponding source. ## Known issues From 22ac774ba58991ede1f331cf56271d5928cfb2ac Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:40:49 +0800 Subject: [PATCH 03/38] fix: refuse a tool output directory that is a symbolic link or junction Replacing an output moves it aside and deletes it. When the output root was a link to a directory holding the marker, the link was moved and the files of the directory it points to were deleted through it. EnsureReplaceableDirectory now refuses any output root that is a link (exit code 1, "is a link") before anything is changed. --- .../Export/ExportSupport.cs | 16 +++- src/OpenSlideSharp.Tool/README.md | 2 +- .../OutputSafetyTests.cs | 76 +++++++++++++++++++ 3 files changed, 91 insertions(+), 3 deletions(-) diff --git a/src/OpenSlideSharp.Tool/Export/ExportSupport.cs b/src/OpenSlideSharp.Tool/Export/ExportSupport.cs index a730b2f..161495c 100644 --- a/src/OpenSlideSharp.Tool/Export/ExportSupport.cs +++ b/src/OpenSlideSharp.Tool/Export/ExportSupport.cs @@ -68,6 +68,17 @@ public static void EnsureReplaceableFile(string path, string slide) public static void EnsureReplaceableDirectory(string path, string slide) { string full = Path.TrimEndingDirectorySeparator(Path.GetFullPath(path)); + + // A symbolic link or junction (to a directory, a file or nothing): replacing it would move the link aside + // and then delete, through it, the contents of whatever it points to. + FileSystemInfo entry = Directory.Exists(full) ? new DirectoryInfo(full) : new FileInfo(full); + if (entry.LinkTarget is { } linkTarget) + { + throw new IOException( + $"Refusing to write the output directory '{full}': it is a link (to '{linkTarget}'). " + + "Remove the link or choose another output."); + } + if (File.Exists(full)) { // For example the slide itself: -r names its directory after the slide without its extension. @@ -111,8 +122,9 @@ public static void EnsureReplaceableDirectory(string path, string slide) /// /// /// An existing directory is replaced only if it holds the marker (an earlier output, complete or not) or is empty. - /// Nothing is deleted if a file has that name (such as the slide), or if the directory has no marker, is a root - /// directory, holds the current directory or the slide, or holds a MIRAX slide's data directory. + /// Nothing is deleted if the path is a symbolic link or junction, if a file has that name (such as the slide), or + /// if the directory has no marker, is a root directory, holds the current directory or the slide, or holds a + /// MIRAX slide's data directory. /// /// The output directory. /// The slide being exported. diff --git a/src/OpenSlideSharp.Tool/README.md b/src/OpenSlideSharp.Tool/README.md index df0b1c7..5b08ca6 100644 --- a/src/OpenSlideSharp.Tool/README.md +++ b/src/OpenSlideSharp.Tool/README.md @@ -46,7 +46,7 @@ Every key of the store is written as a file, with `/` in the key as directories. ## Behavior - Outputs are relative to the current directory unless a path is given. -- Every output directory (`_files/`, the `-r` directory `/`, each `.zarr` store, the `_associated` directory) gets an empty `.openslide-sharp-output` marker file before anything else. Existing output is replaced, but an existing output directory only if it holds that marker or is empty. Any other existing directory, or a file where an output directory would go (such as an extensionless slide with `-r`), stops the export with exit code 1 and nothing is deleted. Root directories, the current directory and its ancestors, directories holding the slide, and a MIRAX slide's data directory (`name/` next to `name.mrxs`) are never deleted. +- Every output directory (`_files/`, the `-r` directory `/`, each `.zarr` store, the `_associated` directory) gets an empty `.openslide-sharp-output` marker file before anything else. Existing output is replaced, but an existing output directory only if it holds that marker or is empty. Any other existing directory, a symbolic link or junction where an output directory would go (even one to a directory with the marker), or a file there (such as an extensionless slide with `-r`), stops the export with exit code 1 and nothing is deleted. Root directories, the current directory and its ancestors, directories holding the slide, and a MIRAX slide's data directory (`name/` next to `name.mrxs`) are never deleted. - An output directory being replaced is first renamed to `..openslide-sharp-old-` next to it, in one step; then the old `.dzi` is deleted, before any new file is written, and the renamed directory is deleted. If the rename fails (on Windows, while a program has a file in it open), the export stops with exit code 1 and nothing has changed. If only the delete fails, a warning names what is left and the export goes on; the next export to the same output deletes it (only while it still holds the marker, which is deleted last). - Every file is written to `..tmp` next to it and then moved into place, so no file is ever partially written. The `.dzi` is written after the tiles, and the OME-Zarr root metadata (`zarr.json`, or `.zgroup` and `.zattrs`) after every chunk and level, so an interrupted export is not mistaken for a complete one. - Progress goes to stderr, at most once a second: `Tiling : / tiles`. Warnings (see [Color](#color)) and errors go to stderr too, prefixed with `openslide-sharp:`. diff --git a/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs b/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs index 9e20a33..29103bf 100644 --- a/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs +++ b/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Diagnostics; using System.IO; using System.Linq; using System.Runtime.Versioning; @@ -79,6 +80,42 @@ public async Task OmeZarr_OutputIsAssociatedDirectory_IsRefused() } } + [Theory] + [InlineData("omezarr")] + [InlineData("deepzoom")] + [InlineData("deepzoom -r")] + public async Task Output_IsSymlinkToMarkedDirectory_IsRefused(string command) + { + // Replacing the output moves it aside and deletes it: through a link, that would delete the files of the + // directory it points to, even though the marker there says the tool wrote them. + using var temp = new TempDirectory(); + string target = temp.Combine("target"); + Directory.CreateDirectory(target); + File.WriteAllText(Path.Combine(target, Marker), string.Empty); + File.WriteAllText(Path.Combine(target, "keep.txt"), "not the tool's"); + string slide = TestFiles.Get("boxes.tiff"); + string output = temp.Combine("boxes"); + string link = command switch + { + "omezarr" => temp.Combine("boxes.zarr"), + "deepzoom" => output + "_files", + _ => output, + }; + CreateDirectoryLinkOrSkip(link, target); + string[] before = Snapshot(target); + var stderr = new StringWriter(); + + int code = command == "omezarr" + ? await OmeZarrCommand.RunAsync(new OmeZarrArguments(slide) { Output = link }, stderr, Token) + : await DeepZoomCommand.RunAsync(new DeepZoomArguments(slide) { Output = output, Viewer = command == "deepzoom -r" }, stderr, Token); + + Assert.Equal(1, code); + Assert.Contains("is a link", stderr.ToString(), StringComparison.Ordinal); + Assert.Equal(before, Snapshot(target)); + Assert.NotNull(new DirectoryInfo(link).LinkTarget); + Assert.Equal(new[] { link, target }.Order(StringComparer.Ordinal), Directory.GetFileSystemEntries(temp.Path).Order(StringComparer.Ordinal)); + } + [Fact] public async Task DeepZoom_OldDzi_IsDeletedBeforeAnyTile() { @@ -184,6 +221,45 @@ private static string[] Snapshot(string directory) => private static string[] Leftovers(string directory) => Directory.GetDirectories(directory, "*.openslide-sharp-old-*"); + // A symbolic link to a directory; on Windows without the right to create one (Developer Mode or an elevated + // process), a directory junction, which the tool must treat the same way. Skips only if neither can be made. + private static void CreateDirectoryLinkOrSkip(string link, string target) + { + try + { + Directory.CreateSymbolicLink(link, target); + } + catch (Exception e) when (e is IOException or UnauthorizedAccessException) + { + if (OperatingSystem.IsWindows() && TryCreateJunction(link, target)) + { + return; + } + + Assert.Skip($"Cannot create a symbolic link here: {e.Message}"); + } + } + + private static bool TryCreateJunction(string link, string target) + { + var info = new ProcessStartInfo("cmd.exe") + { + UseShellExecute = false, + RedirectStandardOutput = true, + RedirectStandardError = true, + }; + info.ArgumentList.Add("/c"); + info.ArgumentList.Add("mklink"); + info.ArgumentList.Add("/J"); + info.ArgumentList.Add(link); + info.ArgumentList.Add(target); + using Process process = Process.Start(info)!; + process.StandardOutput.ReadToEnd(); + process.StandardError.ReadToEnd(); + process.WaitForExit(); + return process.ExitCode == 0 && Directory.Exists(link); + } + // Keeps a level directory from being deleted: a tile held open on Windows, or no write permission elsewhere // (which root ignores; the test then sees a plain success). private static IDisposable Lock(string level) => From ddaba11ad405db4c86fe6b1a343891ca7e0318db Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:43:35 +0800 Subject: [PATCH 04/38] fix: accept any DeepZoom tile size and overlap, as openslide-python does The constructor refused tileSize + 2 * overlap above int.MaxValue / 4 (reported for overlap), although such a generator works wherever the tiles stay small, for example a tile size larger than every level. GetTile now checks the tile and the slide region it reads before allocating anything, and reports a size too large for a .NET array for the level parameter. Tile sizes are kept as long, so GetTileDimensions and GetTileCoordinates report wide overlaps without overflowing. --- .../OpenSlideServerOptionsValidator.cs | 4 +- src/OpenSlideSharp/DeepZoomGenerator.cs | 36 ++++++----- src/OpenSlideSharp/OpenSlide.cs | 12 +++- test/OpenSlideSharp.Tests/DeepZoomTests.cs | 60 +++++++++++++++++++ 4 files changed, 94 insertions(+), 18 deletions(-) diff --git a/src/OpenSlideSharp.AspNetCore/Internal/OpenSlideServerOptionsValidator.cs b/src/OpenSlideSharp.AspNetCore/Internal/OpenSlideServerOptionsValidator.cs index f85f437..8fc3680 100644 --- a/src/OpenSlideSharp.AspNetCore/Internal/OpenSlideServerOptionsValidator.cs +++ b/src/OpenSlideSharp.AspNetCore/Internal/OpenSlideServerOptionsValidator.cs @@ -50,7 +50,9 @@ public ValidateOptionsResult Validate(string? name, OpenSlideServerOptions optio failures.Add($"DeepZoom.Overlap must not be negative, but is {deepZoom.Overlap}."); } - // DeepZoomGenerator's own limit on the tile edge with overlap. + // DeepZoomGenerator accepts any tile size and overlap, as openslide-python does, and only GetTile fails for a + // tile too large for an array. A server has no use for tile edges this long: fail at startup instead of on + // requests. if (deepZoom.TileSize >= 1 && deepZoom.Overlap >= 0 && deepZoom.TileSize + (2L * deepZoom.Overlap) > int.MaxValue / 4) { failures.Add("DeepZoom.TileSize plus twice DeepZoom.Overlap is too large."); diff --git a/src/OpenSlideSharp/DeepZoomGenerator.cs b/src/OpenSlideSharp/DeepZoomGenerator.cs index d950e0a..d308c8b 100644 --- a/src/OpenSlideSharp/DeepZoomGenerator.cs +++ b/src/OpenSlideSharp/DeepZoomGenerator.cs @@ -26,12 +26,15 @@ public sealed class DeepZoomGenerator /// Creates a generator for a slide. /// The slide. - /// Width and height of a tile; tileSize + 2 * overlap should be a power of two for best viewer performance. + /// + /// Width and height of a tile; tileSize + 2 * overlap should be a power of two for best viewer performance. + /// Any size is accepted, as in openslide-python; rejects a tile too large to render. + /// /// Extra pixels added to each interior edge of a tile. /// to render only the non-empty slide region. /// Converts tiles to sRGB; if given, tiles carry no ICC profile. /// is . - /// is less than 1, or is negative or too large. + /// is less than 1, or is negative. /// The slide has been disposed. /// The slide is in the error state. public DeepZoomGenerator(OpenSlide slide, int tileSize = 254, int overlap = 1, bool limitBounds = false, IColorTransform? colorTransform = null) @@ -45,7 +48,7 @@ public DeepZoomGenerator(OpenSlide slide, int tileSize = 254, int overlap = 1, b /// Extra pixels added to each interior edge of a tile. /// Converts tiles to sRGB; if given, tiles carry no ICC profile. /// is . - /// is less than 1, or is negative or too large. + /// is less than 1, or is negative. /// The slide has been disposed. /// The slide is in the error state. public DeepZoomGenerator(AssociatedImage image, int tileSize = 254, int overlap = 1, IColorTransform? colorTransform = null) @@ -76,11 +79,6 @@ private DeepZoomGenerator( throw new ArgumentOutOfRangeException(nameof(overlap), overlap, "The overlap must not be negative."); } - if ((long)tileSize + (2L * overlap) > int.MaxValue / 4) - { - throw new ArgumentOutOfRangeException(nameof(overlap), overlap, "The tile size plus twice the overlap is too large."); - } - _source = source; _ensureUsable = ensureUsable; TileSize = tileSize; @@ -138,8 +136,8 @@ private DeepZoomGenerator( /// The tile row within the level. /// The tile. /// - /// The level, column or row is out of range, or the tile, or the slide region it is rendered from, needs more - /// bytes than a .NET array can hold. + /// The level, column or row is out of range; or, reported for , the tile, or the slide + /// region it is rendered from, needs more bytes than a .NET array can hold (a large tile size or overlap). /// /// The slide has been disposed. /// The slide is in the error state, or reading failed. @@ -147,9 +145,16 @@ public PixelImage GetTile(int level, long column, long row) { _ensureUsable?.Invoke(); TileInfo info = GetTileInfo(level, column, row); - var data = new byte[OpenSlide.CheckedPixelBytes(info.Width, info.Height, "tile")]; - _renderer.Render(info.Exponent, info.X, info.Y, info.Width, info.Height, data); - return new PixelImage(info.Width, info.Height, PixelFormat.Bgra32Opaque, data, _iccProfile); + + // Both are checked before anything is allocated or read. A tile that fits has at most Array.MaxLength / 4 + // pixels and is at least 1 x 1, so each side fits in an int. + long length = OpenSlide.CheckedPixelBytes(info.Width, info.Height, "tile", nameof(level)); + OpenSlide.CheckedPixelBytes(Math.Max(info.Region.Width, 0), Math.Max(info.Region.Height, 0), "slide region", nameof(level)); + int width = (int)info.Width; + int height = (int)info.Height; + var data = new byte[length]; + _renderer.Render(info.Exponent, info.X, info.Y, width, height, data); + return new PixelImage(width, height, PixelFormat.Bgra32Opaque, data, _iccProfile); } /// Returns the OpenSlide.ReadRegion arguments for a tile. @@ -244,8 +249,9 @@ private TileInfo GetTileInfo(int level, long column, long row) long y = ((long)TileSize * row) - overlapTop; SourceRegion region = _geometry.Map(exponent, x, y, width, height); return new TileInfo( - new TileRegion(region.X, region.Y, region.Level, region.Width, region.Height), (int)width, (int)height, exponent, x, y); + new TileRegion(region.X, region.Y, region.Level, region.Width, region.Height), width, height, exponent, x, y); } - private readonly record struct TileInfo(TileRegion Region, int Width, int Height, int Exponent, long X, long Y); + // Width and Height are long: the tile size plus twice the overlap can exceed int.MaxValue. + private readonly record struct TileInfo(TileRegion Region, long Width, long Height, int Exponent, long X, long Y); } diff --git a/src/OpenSlideSharp/OpenSlide.cs b/src/OpenSlideSharp/OpenSlide.cs index de0b909..71cab16 100644 --- a/src/OpenSlideSharp/OpenSlide.cs +++ b/src/OpenSlideSharp/OpenSlide.cs @@ -408,7 +408,15 @@ public void SetCache(OpenSlideCache cache) /// Returns width * height * 4 after rejecting negative sizes and sizes that do not fit in a .NET array. /// Computed in , so large associated image dimensions cannot overflow. /// - internal static long CheckedPixelBytes(long width, long height, string what) + internal static long CheckedPixelBytes(long width, long height, string what) => + CheckedPixelBytes(width, height, what, nameof(width)); + + /// + /// Like , but a size too large for a .NET array is reported + /// as an for : the public parameter that + /// led to it. + /// + internal static long CheckedPixelBytes(long width, long height, string what, string paramName) { if (width < 0) { @@ -429,7 +437,7 @@ internal static long CheckedPixelBytes(long width, long height, string what) if (width != 0 && height > maxLength / 4 / width) { throw new ArgumentOutOfRangeException( - nameof(width), $"A {width} x {height} {what} needs more bytes than a .NET array can hold."); + paramName, $"A {width} x {height} {what} needs more bytes than a .NET array can hold."); } return width * height * 4; diff --git a/test/OpenSlideSharp.Tests/DeepZoomTests.cs b/test/OpenSlideSharp.Tests/DeepZoomTests.cs index 78a6cb4..a9edf38 100644 --- a/test/OpenSlideSharp.Tests/DeepZoomTests.cs +++ b/test/OpenSlideSharp.Tests/DeepZoomTests.cs @@ -251,6 +251,66 @@ public void LevelLists_CannotBeChangedThroughACast() Assert.Throws(() => ((IList)dz.LevelDimensions)[0] = new SlideSize(9, 9)); } + [Fact] + public void Constructor_HugeTileSizeAndOverlap_AreAccepted() + { + // openslide-python accepts any tile size and overlap. Here every level is one tile, which has no interior + // edge, so the overlap adds nothing and each tile is the whole level. + using var osr = OpenSlide.Open(TestFiles.Get("boxes.tiff")); + var whole = new DeepZoomGenerator(osr, tileSize: int.MaxValue, overlap: int.MaxValue); + var standard = new DeepZoomGenerator(osr); + + Assert.All(whole.LevelTiles, t => Assert.Equal(new TileGridSize(1, 1), t)); + Assert.Equal(whole.LevelCount, whole.TileCount); + Assert.Contains($"TileSize=\"{int.MaxValue}\" Overlap=\"{int.MaxValue}\"", whole.GetDzi("png")); + int top = whole.LevelCount - 1; + PixelImage level = whole.GetTile(top, 0, 0); + Assert.Equal(whole.LevelDimensions[top], new SlideSize(level.Width, level.Height)); + Assert.Equal(new TileRegion(0, 0, 0, 300, 250), whole.GetTileCoordinates(top, 0, 0)); + + // A level that is one tile with the default size too gives the same pixels. + Assert.Equal(new TileGridSize(1, 1), standard.LevelTiles[top - 1]); + Assert.Equal(standard.GetTile(top - 1, 0, 0).Data, whole.GetTile(top - 1, 0, 0).Data); + } + + [Fact] + public void GetTile_TooLargeForAnArray_ThrowsForLevelBeforeReading() + { + // 40000 x 40000 pixels need 6.4 GB, more than a .NET array holds. + var source = FakeRenderSource.SingleLevel(100_000, 100_000); + var dz = new DeepZoomGenerator(source, 40_000, 0, false, null); + int top = dz.LevelCount - 1; + + var ex = Assert.Throws(() => dz.GetTile(top, 0, 0)); + + Assert.Equal("level", ex.ParamName); + Assert.Contains("40000 x 40000", ex.Message, StringComparison.Ordinal); + Assert.Equal(0, source.ReadCount); + Assert.Equal(new SlideSize(40_000, 40_000), dz.GetTileDimensions(top, 0, 0)); + } + + [Fact] + public void GetTile_HugeOverlap_ReportsTheSizeAndThrowsForLevel() + { + // An interior tile is the tile size plus twice the overlap: more than int.MaxValue pixels wide here, which + // GetTileDimensions and GetTileCoordinates report as is, like openslide-python. + const int overlap = int.MaxValue / 2; + var source = FakeRenderSource.SingleLevel(1000, 1000); + var dz = new DeepZoomGenerator(source, 254, overlap, false, null); + int top = dz.LevelCount - 1; + long edge = 254 + (2L * overlap); + + Assert.Equal(new SlideSize(edge, edge), dz.GetTileDimensions(top, 1, 1)); + Assert.Equal(new TileRegion(254 - overlap, 254 - overlap, 0, 1000 - 254 + overlap, 1000 - 254 + overlap), dz.GetTileCoordinates(top, 1, 1)); + Assert.Equal("level", Assert.Throws(() => dz.GetTile(top, 1, 1)).ParamName); + Assert.Equal(0, source.ReadCount); + + // The tiles of a level with one tile have no overlap, so they render. + Assert.Equal(new TileGridSize(1, 1), dz.LevelTiles[top - 2]); + PixelImage small = dz.GetTile(top - 2, 0, 0); + Assert.Equal(dz.LevelDimensions[top - 2], new SlideSize(small.Width, small.Height)); + } + [Fact] public void Constructor_InvalidParameters_Throw() { From 4adfe62b96b7917003dc7e66717136793929fed1 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:45:49 +0800 Subject: [PATCH 05/38] fix: check the thumbnail's level before allocating, and name the maximum to lower GetThumbnail allocated the output first and only then found that the level it reads whole does not fit in a .NET array, reported for 'width'. It now checks the level first and reports it for maxWidth or maxHeight, whichever ratio chose the level. The body moves to an internal RenderThumbnail over any render source, so a test can use a level larger than any fixture. --- src/OpenSlideSharp/OpenSlide.cs | 35 +++++++++++++------ .../Rendering/ThumbnailTests.cs | 19 ++++++++++ 2 files changed, 44 insertions(+), 10 deletions(-) diff --git a/src/OpenSlideSharp/OpenSlide.cs b/src/OpenSlideSharp/OpenSlide.cs index 71cab16..1792913 100644 --- a/src/OpenSlideSharp/OpenSlide.cs +++ b/src/OpenSlideSharp/OpenSlide.cs @@ -337,8 +337,8 @@ public unsafe void ReadRegion(long x, long y, int level, int width, int height, /// A image whose is . /// /// - /// or is less than 1, or the level to read would not fit - /// in a .NET array. + /// or is less than 1; or the level to read would not fit + /// in a .NET array, reported for the maximum whose ratio chose that level (checked before anything is allocated). /// /// The slide has been disposed. /// The slide is in the error state, or reading failed. @@ -354,25 +354,40 @@ public PixelImage GetThumbnail(int maxWidth, int maxHeight) throw new ArgumentOutOfRangeException(nameof(maxHeight), maxHeight, "The maximum height must be at least 1."); } - SlideSize dimensions = Dimensions; - double downsample = Math.Max((double)dimensions.Width / maxWidth, (double)dimensions.Height / maxHeight); - int level = GetBestLevelForDownsample(downsample); - SlideSize levelSize = _levelDimensions[level]; + return RenderThumbnail(new SlideRenderSource(this), maxWidth, maxHeight); + } - // An empty level, or one that already fits, is not scaled. Otherwise the size is at most the maximum. + /// The body of , for any render source, after its arguments are checked. + internal static PixelImage RenderThumbnail(IRenderSource source, int maxWidth, int maxHeight) + { + SlideSize dimensions = source.LevelDimensions[0]; + double downsample = Math.Max((double)dimensions.Width / maxWidth, (double)dimensions.Height / maxHeight); + int level = source.GetBestLevelForDownsample(downsample); + SlideSize levelSize = source.LevelDimensions[level]; + + // The whole level is read, so it must fit in a .NET array: checked before anything is allocated. Reported for + // the maximum whose ratio chose the level, the one to lower for a smaller level (if the slide has one). + string limiting = (double)dimensions.Width / maxWidth >= (double)dimensions.Height / maxHeight + ? nameof(maxWidth) + : nameof(maxHeight); + CheckedPixelBytes(levelSize.Width, levelSize.Height, "level, which the thumbnail is made from,", limiting); + + // An empty level, or one that already fits, is not scaled. Otherwise the size is at most the maximum. So the + // output is never larger than the level, and fits in an array too; only an empty level can have a side too + // long for a PixelImage. (long Width, long Height) size = ThumbnailSize.Compute(levelSize.Width, levelSize.Height, maxWidth, maxHeight) ?? (levelSize.Width, levelSize.Height); if (size.Width > int.MaxValue / 4 || size.Height > int.MaxValue) { throw new ArgumentOutOfRangeException( - nameof(maxWidth), $"A {size.Width} x {size.Height} thumbnail is too large for a PixelImage."); + size.Width > int.MaxValue / 4 ? nameof(maxWidth) : nameof(maxHeight), + $"A {size.Width} x {size.Height} thumbnail is too large for a PixelImage."); } int width = (int)size.Width; int height = (int)size.Height; var data = new byte[CheckedPixelBytes(width, height, "thumbnail")]; - var source = new SlideRenderSource(this); Compositor.TryParseBackground( source.GetProperty(OpenSlideProperties.BackgroundColor), out byte red, out byte green, out byte blue); RegionRenderer.RenderRegion( @@ -383,7 +398,7 @@ public PixelImage GetThumbnail(int maxWidth, int maxHeight) width, height, data); - return new PixelImage(width, height, PixelFormat.Bgra32Opaque, data, ColorProfile); + return new PixelImage(width, height, PixelFormat.Bgra32Opaque, data, source.ColorProfile); } /// diff --git a/test/OpenSlideSharp.Tests/Rendering/ThumbnailTests.cs b/test/OpenSlideSharp.Tests/Rendering/ThumbnailTests.cs index 3021e03..8c50a95 100644 --- a/test/OpenSlideSharp.Tests/Rendering/ThumbnailTests.cs +++ b/test/OpenSlideSharp.Tests/Rendering/ThumbnailTests.cs @@ -49,6 +49,25 @@ public void GetThumbnail_MatchesPython(string source, int maxWidth, int maxHeigh } } + [Theory] + [InlineData(100_000, 50_000, "maxWidth")] + [InlineData(50_000, 100_000, "maxHeight")] + public void GetThumbnail_LevelTooLargeToRead_NamesTheLimitingMaximumBeforeAllocating(long width, long height, string param) + { + // A slide with one level of 5e9 pixels: any thumbnail reads that level whole, which needs more bytes than a + // .NET array holds. The maximum whose ratio picks the level is the one to lower. Nothing may be allocated + // first: the 4000 x 2000 output would be 32 MB. + var source = FakeRenderSource.SingleLevel(width, height); + long before = GC.GetAllocatedBytesForCurrentThread(); + + var ex = Assert.Throws(() => OpenSlide.RenderThumbnail(source, 4000, 4000)); + + Assert.True(GC.GetAllocatedBytesForCurrentThread() - before < 1_000_000, "the output was allocated before the check"); + Assert.Equal(param, ex.ParamName); + Assert.Contains($"{width} x {height}", ex.Message, StringComparison.Ordinal); + Assert.Equal(0, source.ReadCount); + } + [Fact] public void GetThumbnail_InvalidSize_Throws() { From 03c1f021f150c2e25730b7313a2272b352dc5520 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:48:00 +0800 Subject: [PATCH 06/38] docs: state that the Skia transform cache is keyed by the ICC profile array Encode with ColorMode.Default caches the transform per array that holds the image's ICC profile, by reference, so a caller that changes that array afterwards keeps getting the transform made for the old bytes. Say so on SkiaColorTransform, GetCached and Encode, and pin the behaviour in a test. --- .../PixelImageExtensions.cs | 5 ++++ .../SkiaColorTransform.cs | 13 ++++++++++ .../Skia/ColorTransformTests.cs | 24 +++++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/src/OpenSlideSharp.SkiaSharp/PixelImageExtensions.cs b/src/OpenSlideSharp.SkiaSharp/PixelImageExtensions.cs index f740a37..2951ea1 100644 --- a/src/OpenSlideSharp.SkiaSharp/PixelImageExtensions.cs +++ b/src/OpenSlideSharp.SkiaSharp/PixelImageExtensions.cs @@ -65,6 +65,11 @@ public static SKImage ToSKImage(this PixelImage image) } /// Encodes the image as JPEG or PNG. + /// + /// With , the transform made for a profile is cached, keyed by the array that holds + /// (by reference): do not change that array once an image with it has been + /// encoded. + /// /// The image to encode. /// The output format. /// Quality from 0 to 100; ignored for PNG. diff --git a/src/OpenSlideSharp.SkiaSharp/SkiaColorTransform.cs b/src/OpenSlideSharp.SkiaSharp/SkiaColorTransform.cs index a2b199b..7748a73 100644 --- a/src/OpenSlideSharp.SkiaSharp/SkiaColorTransform.cs +++ b/src/OpenSlideSharp.SkiaSharp/SkiaColorTransform.cs @@ -7,6 +7,13 @@ namespace OpenSlideSharp.SkiaSharp; /// Creates instances that convert ICC profiles to sRGB with SkiaSharp. +/// +/// copies the profile. +/// with +/// instead caches the transform it makes for a profile, keyed by the array that holds +/// (by reference, not by content): do not change that array after passing it to a +/// , or later encodes keep applying the transform made for the old bytes. +/// public static class SkiaColorTransform { // One decision per slide: the core hands every tile the same backing array of the profile. @@ -52,6 +59,12 @@ public static class SkiaColorTransform } /// Like , but remembers the result per backing array of the profile. + /// + /// The key is the array itself, compared by reference and held weakly, and only a profile that spans its whole + /// array is cached (any other is converted every time). The bytes are not copied, so a caller must not change the + /// array afterwards: the cached transform would still be the one made for the old bytes. The profiles OpenSlide + /// returns are never changed; a caller's own profile given to a must not be either. + /// internal static IColorTransform? GetCached(ReadOnlyMemory iccProfile) { if (iccProfile.IsEmpty) diff --git a/test/OpenSlideSharp.Tests/Skia/ColorTransformTests.cs b/test/OpenSlideSharp.Tests/Skia/ColorTransformTests.cs index 073e248..a3b335c 100644 --- a/test/OpenSlideSharp.Tests/Skia/ColorTransformTests.cs +++ b/test/OpenSlideSharp.Tests/Skia/ColorTransformTests.cs @@ -254,6 +254,30 @@ public void Create_GarbageOrEmpty_ReturnsNull() Assert.Null(SkiaColorTransform.Create(ReadOnlyMemory.Empty)); } + [Fact] + public void GetCached_IsKeyedByTheProfileArrayReference() + { + byte[] profile = File.ReadAllBytes(TestFiles.Get("icc/swap-rb-matrix.icc")); + IColorTransform? first = SkiaColorTransform.GetCached(profile); + Assert.NotNull(first); + + // The same array gives the same transform; an equal copy is another key. + Assert.Same(first, SkiaColorTransform.GetCached(profile)); + Assert.NotSame(first, SkiaColorTransform.GetCached((byte[])profile.Clone())); + + // A profile that is only part of its array is not cached. + var padded = new byte[profile.Length + 1]; + profile.CopyTo(padded, 1); + var part = new ReadOnlyMemory(padded, 1, profile.Length); + Assert.NotSame(SkiaColorTransform.GetCached(part), SkiaColorTransform.GetCached(part)); + + // The bytes are not looked at again: an array changed after the first call keeps the old transform, which is + // why callers must not change it. + Array.Clear(profile); + Assert.Null(SkiaColorTransform.Create(profile)); + Assert.Same(first, SkiaColorTransform.GetCached(profile)); + } + [Fact] public void Apply_ConcurrentCalls_AreConsistent() { From fbb667fe99085cfea95486fe548208a377daf4ee Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 19:49:49 +0800 Subject: [PATCH 07/38] build: put the upstream OpenSlide version in InformationalVersion when given With OpenSlideUpstreamVersion set (the release build passes the openslide version of the bundled openslide-bin build), InformationalVersion is +openslide., without the git commit hash the SDK appends. Without it nothing changes. The test checks the core assembly built with the same properties. --- Directory.Build.props | 11 ++++++ .../AssemblyVersionTests.cs | 35 +++++++++++++++++++ .../OpenSlideSharp.Tests.csproj | 6 ++++ 3 files changed, 52 insertions(+) create mode 100644 test/OpenSlideSharp.Tests/AssemblyVersionTests.cs diff --git a/Directory.Build.props b/Directory.Build.props index b049f82..076afad 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -8,6 +8,17 @@ 0.0.0-local + + + $(Version)+openslide.$(OpenSlideUpstreamVersion) + false + + IOL0ol1 Copyright (c) IOL0ol1 diff --git a/test/OpenSlideSharp.Tests/AssemblyVersionTests.cs b/test/OpenSlideSharp.Tests/AssemblyVersionTests.cs new file mode 100644 index 0000000..7a9cc2c --- /dev/null +++ b/test/OpenSlideSharp.Tests/AssemblyVersionTests.cs @@ -0,0 +1,35 @@ +using System.Linq; +using System.Reflection; +using Xunit; + +namespace OpenSlideSharp.Tests; + +/// +/// The informational version of the assemblies (Directory.Build.props): the package version, and with +/// OpenSlideUpstreamVersion set (as the release build does) <version>+openslide.<upstream version>. +/// +public class AssemblyVersionTests +{ + // The properties this test assembly, and the core assembly with it, were built with (see the project file). + private static string BuildProperty(string name) => + typeof(AssemblyVersionTests).Assembly.GetCustomAttributes() + .Single(a => a.Key == "Build." + name).Value ?? string.Empty; + + [Fact] + public void InformationalVersion_IsTheVersion_WithTheUpstreamVersionWhenGiven() + { + string? informational = typeof(OpenSlideLibrary).Assembly + .GetCustomAttribute()?.InformationalVersion; + string version = BuildProperty("Version"); + string upstream = BuildProperty("OpenSlideUpstreamVersion"); + + Assert.False(string.IsNullOrEmpty(informational)); + Assert.False(string.IsNullOrEmpty(version)); + Assert.Equal(version, informational!.Split('+')[0]); + if (upstream.Length > 0) + { + // Not followed by the SDK's git commit hash. + Assert.Equal($"{version}+openslide.{upstream}", informational); + } + } +} diff --git a/test/OpenSlideSharp.Tests/OpenSlideSharp.Tests.csproj b/test/OpenSlideSharp.Tests/OpenSlideSharp.Tests.csproj index 1ed50d8..17b1a57 100644 --- a/test/OpenSlideSharp.Tests/OpenSlideSharp.Tests.csproj +++ b/test/OpenSlideSharp.Tests/OpenSlideSharp.Tests.csproj @@ -19,6 +19,12 @@ + + + + + + From 4172569ffa9995e0088307f11e14622622220692 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 20:02:54 +0800 Subject: [PATCH 08/38] build: ship the tool's terms in LICENSE.txt and name the release copy of the OpenSlide source The tool package now uses PackageLicenseFile like the runtime package: LICENSE.txt holds the MIT license of its own code and states the terms of what it redistributes (OpenSlide with each platform's linked libraries, SkiaSharp and Skia, OpenSeadragon and its scale bar plugin, and System.CommandLine, whose MIT text it reproduces), pointing to their texts in licenses/. Nightly source tarballs on openslide/builds expire, so the runtime and tool license files and READMEs also name the copy of openslide-bin-.tar.gz attached to the OpenSlideSharp GitHub release of the same version, checked against source.sha256 in openslide-bin.json. Test-Packages asserts the tool's license file and that both license files point to the source. --- README.md | 2 +- eng/Test-Packages.ps1 | 20 +++- src/OpenSlideSharp.Tool/LICENSE.txt | 107 ++++++++++++++++++ .../OpenSlideSharp.Tool.csproj | 23 ++-- src/OpenSlideSharp.Tool/README.md | 7 +- src/OpenSlideSharp.runtime/LICENSE.txt | 9 +- src/OpenSlideSharp.runtime/README.md | 2 +- 7 files changed, 149 insertions(+), 21 deletions(-) create mode 100644 src/OpenSlideSharp.Tool/LICENSE.txt diff --git a/README.md b/README.md index 357ebc1..98b590c 100644 --- a/README.md +++ b/README.md @@ -156,4 +156,4 @@ dotnet test OpenSlideSharp.slnx ## License -The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. +The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. The corresponding source is the openslide-bin source tarball named in the package's `openslide-bin.json`; each [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) attaches a copy for its version. `OpenSlideSharp.Tool` states its terms in its own `LICENSE.txt`, and the viewer in `licenses/` next to its executable. diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index 563cec7..aba488a 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -234,9 +234,10 @@ $extraRids = @($toolRids | Where-Object { $_ -notin 'win-x64', 'linux-x64', 'lin if ($extraRids.Count -gt 0) { throw "tool nupkg has native assets for unsupported RIDs: $($extraRids -join ', ')" } # The tool redistributes LGPL-2.1 OpenSlide (with openslide-bin's statically linked libraries), SkiaSharp and Skia, -# and the OpenSeadragon viewer files: their licenses must travel with it, and the license expression must name them. +# System.CommandLine and the OpenSeadragon viewer files: their licenses must travel with it, and its LICENSE.txt must +# state them. $toolEntries | Where-Object { $_ -like 'licenses/*' } | ForEach-Object { " tool: $_" } -foreach ($r in @('licenses/openslide-bin/openslide-bin.json') + @($binKeys | ForEach-Object { "licenses/openslide-bin/$_/VERSIONS.md", "licenses/openslide-bin/$_/OpenSlide/COPYING.LESSER" })) { +foreach ($r in @('LICENSE.txt', 'licenses/openslide-bin/openslide-bin.json') + @($binKeys | ForEach-Object { "licenses/openslide-bin/$_/VERSIONS.md", "licenses/openslide-bin/$_/OpenSlide/COPYING.LESSER" })) { if ($toolEntries -notcontains $r) { throw "tool nupkg is missing '$r'" } } # Exactly the runtime package's licenses// trees, under licenses/openslide-bin/. @@ -249,11 +250,20 @@ foreach ($r in 'licenses/viewer/LICENSE.openseadragon', 'licenses/viewer/LICENSE if ($toolEntries -notcontains $r) { throw "tool nupkg is missing '$r'" } } $toolMeta = (Get-NuspecXml $toolNupkg).package.metadata -$toolLicense = 'MIT AND LGPL-2.1-only AND BSD-3-Clause' -if ($toolMeta.license.type -ne 'expression' -or $toolMeta.license.InnerText -ne $toolLicense) { - throw "tool nuspec license is '$($toolMeta.license.InnerText)' ($($toolMeta.license.type)), expected the expression '$toolLicense'" +if ($toolMeta.license.type -ne 'file' -or $toolMeta.license.InnerText -ne 'LICENSE.txt') { + throw "tool nuspec license is '$($toolMeta.license.InnerText)' ($($toolMeta.license.type)), expected LICENSE.txt" } if ($toolMeta.description -notmatch 'openslide-bin source tarball') { throw "tool nuspec description does not name the OpenSlide source: $($toolMeta.description)" } +# Both license files point to the OpenSlide source: the tarball openslide-bin.json names, and its copy on the +# OpenSlideSharp GitHub release (nightly openslide-bin builds are removed after a while). +foreach ($license in @(@{ Name = 'runtime'; Text = Get-NupkgText $runtimeNupkg 'LICENSE.txt' }, @{ Name = 'tool'; Text = Get-NupkgText $toolNupkg 'LICENSE.txt' })) { + foreach ($phrase in 'source.sha256', 'openslide-bin-.tar.gz', 'https://github.com/IOL0ol1/OpenSlideSharp/releases') { + if (-not $license.Text.Contains($phrase)) { throw "$($license.Name) LICENSE.txt does not mention '$phrase'" } + } +} +foreach ($phrase in 'LGPL-2.1-only', 'licenses/openslide-bin//OpenSlide/COPYING.LESSER', 'licenses/skiasharp/', 'licenses/viewer/', 'System.CommandLine') { + if (-not (Get-NupkgText $toolNupkg 'LICENSE.txt').Contains($phrase)) { throw "tool LICENSE.txt does not mention '$phrase'" } +} $toolSize = (Get-Item $toolNupkg).Length Write-Host ("tool nupkg size: {0:N1} MB ({1} bytes)" -f ($toolSize / 1MB), $toolSize) diff --git a/src/OpenSlideSharp.Tool/LICENSE.txt b/src/OpenSlideSharp.Tool/LICENSE.txt new file mode 100644 index 0000000..3a8f388 --- /dev/null +++ b/src/OpenSlideSharp.Tool/LICENSE.txt @@ -0,0 +1,107 @@ +OpenSlideSharp.Tool: license information + +The tool (openslide-sharp) is part of OpenSlideSharp (https://github.com/IOL0ol1/OpenSlideSharp). Its own code is +licensed under the MIT license below. The package also redistributes the components listed after it, each under its +own license; their license texts are in the package's licenses/ folder, or at the end of this file. + +------------------------------------------------------------------------------- +OpenSlideSharp license +------------------------------------------------------------------------------- + +The MIT License (MIT) + +Copyright (c) 2026 IOL0ol1 + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +------------------------------------------------------------------------------- +Redistributed components +------------------------------------------------------------------------------- + +1. OpenSlide and the libraries linked into it (openslide-bin) + + The native libraries tools/net10.0/any/runtimes//native/libopenslide-1.* are builds of OpenSlide + (https://openslide.org/) from openslide-bin (https://github.com/openslide/openslide-bin). OpenSlide is licensed + under the GNU Lesser General Public License, version 2.1 (LGPL-2.1-only). The library of each platform statically + links further components, each under its own license. The full license texts of OpenSlide and of these + components, and VERSIONS.md with their versions, are in the licenses folder of that platform: + + licenses/openslide-bin/windows-x64/ runtimes/win-x64/native/ + licenses/openslide-bin/linux-x86_64/ runtimes/linux-x64/native/ + licenses/openslide-bin/linux-aarch64/ runtimes/linux-arm64/native/ + licenses/openslide-bin/macos-arm64-x86_64/ runtimes/osx-arm64/native/ and runtimes/osx-x64/native/ + + OpenSlide's license text is licenses/openslide-bin//OpenSlide/COPYING.LESSER. + + Source code: licenses/openslide-bin/openslide-bin.json names the openslide-bin build (binVersion) and its source + tarball, openslide-bin-.tar.gz (source.url, with its sha256 in source.sha256). The tarball holds the + source code of OpenSlide and of every component listed above, and the scripts that build these libraries from it. + The same tarball is also attached to the OpenSlideSharp GitHub release of this package's version, tag + v on https://github.com/IOL0ol1/OpenSlideSharp/releases, which keeps it after openslide-bin's + nightly builds (https://github.com/openslide/builds) are removed. Check either copy by its file name and against + source.sha256. + + The tool loads the library at run time. To use another build of OpenSlide 4.x, for example one built from that + source, set the OPENSLIDE_LIBRARY_PATH environment variable to its full path. + +2. SkiaSharp and Skia + + SkiaSharp (https://github.com/mono/SkiaSharp) is licensed under the MIT license, and the native libraries + tools/net10.0/any/runtimes//native/libSkiaSharp.* contain Skia (https://skia.org/), BSD-3-Clause, and further + third-party code. See licenses/skiasharp/LICENSE.txt (SkiaSharp's license) and + licenses/skiasharp/THIRD-PARTY-NOTICES.txt (the notices of the code in SkiaSharp's and HarfBuzzSharp's native + builds). + +3. OpenSeadragon and its scale bar plugin + + Written by openslide-sharp deepzoom -r for its HTML viewer. OpenSeadragon (https://openseadragon.github.io/) is + licensed under BSD-3-Clause: licenses/viewer/LICENSE.openseadragon. The scale bar plugin + (https://github.com/usnistgov/OpenSeadragonScalebar) is in the public domain (NIST): + licenses/viewer/LICENSE.openseadragon-scalebar. + +4. System.CommandLine + + System.CommandLine (https://github.com/dotnet/command-line-api) is licensed under the MIT license below. + +------------------------------------------------------------------------------- +System.CommandLine license +------------------------------------------------------------------------------- + +The MIT License (MIT) + +Copyright © .NET Foundation and Contributors + +All rights reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj b/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj index d073636..4b0d253 100644 --- a/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj +++ b/src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj @@ -7,9 +7,14 @@ openslide-sharp OpenSlideSharp.Tool openslide wsi pathology deepzoom ome-zarr dotnet-tool - Command-line tool that exports OpenSlide slides as Deep Zoom (like deepzoom_tile.py) or OME-Zarr. Bundles native OpenSlide from openslide-bin (LGPL-2.1); source: the openslide-bin source tarball of the same version. Also bundles SkiaSharp (MIT) with Skia (BSD-3-Clause), and OpenSeadragon (BSD-3-Clause) with its public-domain scale bar plugin for the -r viewer. See licenses/. - - MIT AND LGPL-2.1-only AND BSD-3-Clause + Command-line tool that exports OpenSlide slides as Deep Zoom (like deepzoom_tile.py) or OME-Zarr. Bundles native OpenSlide from openslide-bin (LGPL-2.1); source: the openslide-bin source tarball named in licenses/openslide-bin/openslide-bin.json, also attached to the OpenSlideSharp GitHub release of the same version. Also bundles SkiaSharp (MIT) with Skia (BSD-3-Clause), System.CommandLine (MIT), and OpenSeadragon (BSD-3-Clause) with its public-domain scale bar plugin for the -r viewer. See LICENSE.txt and licenses/. + + + LICENSE.txt @@ -38,11 +43,12 @@ @@ -59,6 +65,7 @@ + diff --git a/src/OpenSlideSharp.Tool/README.md b/src/OpenSlideSharp.Tool/README.md index 5b08ca6..c757152 100644 --- a/src/OpenSlideSharp.Tool/README.md +++ b/src/OpenSlideSharp.Tool/README.md @@ -63,13 +63,14 @@ Each worker holds one tile or chunk at a time, and OpenSlide keeps a tile cache ## Licenses -The tool's own code is under the MIT license. The package also contains, each under its own license, which are in the package's `licenses/` folder: +The tool's own code is under the MIT license. The package also contains, each under its own license, which are in the package's `licenses/` folder or in `LICENSE.txt`: -- OpenSlide 4.x from [openslide-bin](https://github.com/openslide/openslide-bin), LGPL-2.1, with the libraries built into it (`licenses/openslide-bin//`, each with a `VERSIONS.md` listing their versions). The source is the openslide-bin source tarball named in `licenses/openslide-bin/openslide-bin.json`. +- OpenSlide 4.x from [openslide-bin](https://github.com/openslide/openslide-bin), LGPL-2.1, with the libraries built into it (`licenses/openslide-bin//`, each with a `VERSIONS.md` listing their versions). The source is the openslide-bin source tarball named in `licenses/openslide-bin/openslide-bin.json` (URL and sha256). The same file, `openslide-bin-.tar.gz`, is attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the package's version (tag `v`), which keeps it after a nightly openslide-bin build is removed; check it against that sha256. - [SkiaSharp](https://github.com/mono/SkiaSharp), MIT, with Skia (BSD-3-Clause) and the libraries in its native build (`licenses/skiasharp/`). - [OpenSeadragon](https://openseadragon.github.io/), BSD-3-Clause, and its [scale bar plugin](https://github.com/usnistgov/OpenSeadragonScalebar), in the public domain (NIST), written with `-r` (`licenses/viewer/`). +- [System.CommandLine](https://github.com/dotnet/command-line-api), MIT. -The package license expression is `MIT AND LGPL-2.1-only AND BSD-3-Clause`. +The package license is `LICENSE.txt`, which states these terms and where each license text is. ## Color diff --git a/src/OpenSlideSharp.runtime/LICENSE.txt b/src/OpenSlideSharp.runtime/LICENSE.txt index 3b1fc36..92ec12e 100644 --- a/src/OpenSlideSharp.runtime/LICENSE.txt +++ b/src/OpenSlideSharp.runtime/LICENSE.txt @@ -13,9 +13,12 @@ the licenses folder of that platform: OpenSlide's license text is licenses//OpenSlide/COPYING.LESSER. -Source code: openslide-bin.json in this package names the openslide-bin build (binVersion) and its source tarball -(source.url, with its sha256 in source.sha256). The tarball holds the source code of OpenSlide and of every -component listed above, and the scripts that build these libraries from it. +Source code: openslide-bin.json in this package names the openslide-bin build (binVersion) and its source tarball, +openslide-bin-.tar.gz (source.url, with its sha256 in source.sha256). The tarball holds the source code +of OpenSlide and of every component listed above, and the scripts that build these libraries from it. The same +tarball is also attached to the OpenSlideSharp GitHub release of this package's version, tag v on +https://github.com/IOL0ol1/OpenSlideSharp/releases, which keeps it after openslide-bin's nightly builds +(https://github.com/openslide/builds) are removed. Check either copy by its file name and against source.sha256. The MSBuild files under build/ and buildTransitive/ are part of OpenSlideSharp (https://github.com/IOL0ol1/OpenSlideSharp) and are licensed under the MIT license. diff --git a/src/OpenSlideSharp.runtime/README.md b/src/OpenSlideSharp.runtime/README.md index ab36d01..e0a7238 100644 --- a/src/OpenSlideSharp.runtime/README.md +++ b/src/OpenSlideSharp.runtime/README.md @@ -12,7 +12,7 @@ OpenSlide ships Windows binaries for x64 only, so a .NET Framework app must run ## Licensing -The native libraries are builds of OpenSlide (LGPL-2.1) from openslide-bin. Each platform's library statically links further components, each under its own license. `LICENSE.txt` in the package states the terms. `licenses//` (`windows-x64`, `linux-x86_64`, `linux-aarch64`, `macos-arm64-x86_64`) holds the full license texts of that platform's components and `VERSIONS.md` with their versions. `openslide-bin.json` names the openslide-bin build and its source tarball (URL and sha256), which is the corresponding source. +The native libraries are builds of OpenSlide (LGPL-2.1) from openslide-bin. Each platform's library statically links further components, each under its own license. `LICENSE.txt` in the package states the terms. `licenses//` (`windows-x64`, `linux-x86_64`, `linux-aarch64`, `macos-arm64-x86_64`) holds the full license texts of that platform's components and `VERSIONS.md` with their versions. `openslide-bin.json` names the openslide-bin build and its source tarball (URL and sha256), which is the corresponding source. The same file, `openslide-bin-.tar.gz`, is attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the package's version (tag `v`), which keeps it after a nightly openslide-bin build is removed; check it against that sha256. ## Known issues From efdd604db676b0b25dabd565dd5b7b0f13f90ee4 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 20:03:04 +0800 Subject: [PATCH 09/38] build: write the viewer's SOURCE.md at publish and ship only its platform's openslide-bin notices licenses/SOURCE.md is no longer a fixed file that gives only URL patterns. PublishLicenses writes it from openslide-bin.json (runtime package or artifacts/native): the exact openslide-bin build and OpenSlide version, the source tarball's file name, sha256 and URL, the copy attached to the OpenSlideSharp GitHub release of the viewer's version, and how to load another OpenSlide build with OPENSLIDE_LIBRARY_PATH. A publish now carries the openslide-bin notices of its RID's archive only (win-x64: windows-x64, linux-x64: linux-x86_64, linux-arm64: linux-aarch64, osx-*: macos-arm64-x86_64; all four for a publish without a RID), and fails for a RID openslide-bin does not build. THIRD-PARTY-NOTICES.txt now reproduces the MIT texts of MicroCom.Runtime and Tmds.DBus.Protocol. Test-Packages checks that the viewer's openslide-bin notices are exactly the runtime package's for its platform and that SOURCE.md names the build. --- eng/Test-Packages.ps1 | 18 ++- .../OpenSlideSharp.Viewer.csproj | 146 +++++++++++++++++- samples/OpenSlideSharp.Viewer/README.md | 2 +- samples/OpenSlideSharp.Viewer/SOURCE.md | 36 ----- .../THIRD-PARTY-NOTICES.txt | 62 +++++++- 5 files changed, 212 insertions(+), 52 deletions(-) delete mode 100644 samples/OpenSlideSharp.Viewer/SOURCE.md diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index aba488a..5f86735 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -396,15 +396,25 @@ $unexpected = @($paths | Where-Object { $_ -ne $viewerName -and -not $_.StartsWi if ($paths -notcontains $viewerName -or $unexpected.Count -gt 0) { throw "[viewer] expected $viewerName and licenses/ in $viewerPublish, found: $($paths -join ', ')" } -# The license texts of OpenSlide and of the libraries linked into it, from the runtime package: at least those of the -# openslide-bin archive this RID's library comes from. +# The license texts of OpenSlide and of the libraries linked into it, from the runtime package: exactly those of the +# openslide-bin archive this RID's library comes from, and no other platform's. $viewerBinKey = @{ 'win-x64' = 'windows-x64'; 'linux-x64' = 'linux-x86_64'; 'linux-arm64' = 'linux-aarch64'; 'osx-arm64' = 'macos-arm64-x86_64'; 'osx-x64' = 'macos-arm64-x86_64' }[$viewerRid] foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', 'licenses/openslide-bin/openslide-bin.json', "licenses/openslide-bin/$viewerBinKey/VERSIONS.md", "licenses/openslide-bin/$viewerBinKey/OpenSlide/COPYING.LESSER") { if ($paths -notcontains $required) { throw "[viewer] $required is not in $viewerPublish" } } -$binLicenses = @($paths | Where-Object { $_ -like 'licenses/openslide-bin/*/*' }) -Write-Host "licenses/openslide-bin: $($binLicenses.Count) license files" +$binLicenses = @($paths | Where-Object { $_ -like 'licenses/openslide-bin/*/*' } | ForEach-Object { $_.Substring('licenses/openslide-bin/'.Length) } | Sort-Object) +$wantBinLicenses = @($runtimeLicenses | Where-Object { $_ -like "$viewerBinKey/*" }) +if (($binLicenses -join "`n") -cne ($wantBinLicenses -join "`n")) { + throw "[viewer] licenses/openslide-bin/ has $($binLicenses.Count) files ($((@($binLicenses | ForEach-Object { ($_ -split '/')[0] } | Sort-Object -Unique)) -join ', ')), expected the runtime nupkg's $($wantBinLicenses.Count) under licenses/$viewerBinKey/ only" +} +Write-Host "licenses/openslide-bin/$viewerBinKey`: $($binLicenses.Count) license files" +# SOURCE.md is written at publish from openslide-bin.json: the exact build, its source tarball and the release copy. +$sourceMd = Get-Content (Join-Path $viewerPublish 'licenses/SOURCE.md') -Raw +foreach ($phrase in $manifest.binVersion, "openslide-bin-$($manifest.binVersion).tar.gz", $manifest.source.sha256, $manifest.source.url, + $manifest.openslideVersion, "https://github.com/IOL0ol1/OpenSlideSharp/releases/tag/v$Version", "openslide-bin/$viewerBinKey/", 'OPENSLIDE_LIBRARY_PATH') { + if (-not $sourceMd.Contains("$phrase")) { throw "[viewer] licenses/SOURCE.md does not contain '$phrase'" } +} # The bundle extracts its native libraries when it starts; a fresh extraction directory shows they came from it. $viewerExtract = Join-Path $viewerOut 'extract' $env:DOTNET_BUNDLE_EXTRACT_BASE_DIR = $viewerExtract diff --git a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj index 90667a6..f8d824b 100644 --- a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj +++ b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj @@ -52,23 +52,50 @@ <_OpenSlideBinDir Condition="'$(UseOpenSlideRuntimePackage)' == 'true'">$(PkgOpenSlideSharp_runtime) <_OpenSlideBinDir Condition="'$(UseOpenSlideRuntimePackage)' != 'true'">$(MSBuildThisFileDirectory)..\..\artifacts\native + + <_OpenSlideBinRid Condition="'$(UseOpenSlideRuntimePackage)' == 'true'">$(RuntimeIdentifier) + <_OpenSlideBinRid Condition="'$(UseOpenSlideRuntimePackage)' != 'true'">$(OpenSlideNativeRid) + <_OpenSlideBinKey Condition="'$(_OpenSlideBinRid)' == 'win-x64'">windows-x64 + <_OpenSlideBinKey Condition="'$(_OpenSlideBinRid)' == 'linux-x64'">linux-x86_64 + <_OpenSlideBinKey Condition="'$(_OpenSlideBinRid)' == 'linux-arm64'">linux-aarch64 + <_OpenSlideBinKey Condition="$(_OpenSlideBinRid.StartsWith('osx-'))">macos-arm64-x86_64 + + <_OpenSlideBinLicenseDir Condition="'$(_OpenSlideBinKey)' != ''">$(_OpenSlideBinKey)/ + <_ViewerSourceNotice>$([MSBuild]::NormalizePath('$(MSBuildProjectDirectory)', '$(IntermediateOutputPath)', 'licenses', 'SOURCE.md')) + + + + + + + <_ViewerPackageFile Include="@(ResolvedFileToPublish)" Condition="'%(ResolvedFileToPublish.NuGetPackageId)' != ''" PackageDir="$([System.Text.RegularExpressions.Regex]::Match('%(ResolvedFileToPublish.FullPath)', '(?i)^.*[\\/]%(ResolvedFileToPublish.NuGetPackageId)[\\/]%(ResolvedFileToPublish.NuGetPackageVersion)[\\/]').Value)" /> @@ -76,20 +103,123 @@ <_ViewerPackageLicense Include="%(_ViewerPackage.Identity)LICENSE*;%(_ViewerPackage.Identity)THIRD-PARTY-NOTICES*" PackageId="%(_ViewerPackage.NuGetPackageId)" /> - <_OpenSlideBinLicense Include="$(_OpenSlideBinDir)/licenses/**" /> + <_OpenSlideBinLicense Include="$(_OpenSlideBinDir)/licenses/$(_OpenSlideBinLicenseDir)**" /> <_ViewerLicense Include="@(_OpenSlideBinLicense)" - RelativePath="licenses/openslide-bin/%(_OpenSlideBinLicense.RecursiveDir)%(_OpenSlideBinLicense.Filename)%(_OpenSlideBinLicense.Extension)" /> + RelativePath="licenses/openslide-bin/$(_OpenSlideBinLicenseDir)%(_OpenSlideBinLicense.RecursiveDir)%(_OpenSlideBinLicense.Filename)%(_OpenSlideBinLicense.Extension)" /> <_ViewerLicense Include="$(_OpenSlideBinDir)/openslide-bin.json" RelativePath="licenses/openslide-bin/openslide-bin.json" /> <_ViewerLicense Include="@(_ViewerPackageLicense)" RelativePath="licenses/%(_ViewerPackageLicense.PackageId)/%(_ViewerPackageLicense.Filename)%(_ViewerPackageLicense.Extension)" /> <_ViewerLicense Include="$(MSBuildThisFileDirectory)..\..\LICENSE" RelativePath="licenses/OpenSlideSharp/LICENSE" /> <_ViewerLicense Include="$(MSBuildThisFileDirectory)THIRD-PARTY-NOTICES.txt" RelativePath="licenses/THIRD-PARTY-NOTICES.txt" /> - <_ViewerLicense Include="$(MSBuildThisFileDirectory)SOURCE.md" RelativePath="licenses/SOURCE.md" /> + <_ViewerLicense Include="$(_ViewerSourceNotice)" RelativePath="licenses/SOURCE.md" /> + + + + + + + + + + + (); + var missing = new List(); + foreach (string name in new[] { "channel", "binVersion", "openslideVersion", "openslideCommit", "date", "url", "sha256" }) + { + Match match = Regex.Match(json, "\"" + name + "\"\\s*:\\s*\"([^\"\\\\]+)\""); + if (match.Success) + { + values[name] = match.Groups[1].Value; + } + else + { + missing.Add(name); + } + } + + if (missing.Count > 0) + { + Log.LogError("{0} has no plain string value for {1}.", BinInfo, string.Join(", ", missing)); + } + else if (!Regex.IsMatch(values["sha256"], "^[0-9a-f]{64}$")) + { + Log.LogError("{0}: source.sha256 '{1}' is not a lowercase sha256.", BinInfo, values["sha256"]); + } + else + { + string folder = "openslide-bin/" + (string.IsNullOrEmpty(Platform) ? "" : Platform) + "/"; + string releases = "https://github.com/IOL0ol1/OpenSlideSharp/releases"; + string kept = values["channel"] == "nightly" ? " (nightly builds are kept there for a limited time)" : ""; + string[] lines = + { + "# OpenSlide: source code and replacing the library", + "", + "The viewer contains a build of [OpenSlide](https://openslide.org/) from", + "[openslide-bin](https://github.com/openslide/openslide-bin): `libopenslide-1.dll` on Windows, `libopenslide-1.so` on", + "Linux and `libopenslide-1.dylib` on macOS, which the executable extracts when it first starts.", + "", + "- openslide-bin build: `" + values["binVersion"] + "` (" + values["channel"] + ", " + values["date"] + ")", + "- OpenSlide: `" + values["openslideVersion"] + "` (commit `" + values["openslideCommit"] + "`)", + "", + "OpenSlide is licensed under the GNU Lesser General Public License 2.1, and the libraries linked into it under", + "their own licenses: see `" + folder + "`, and `" + folder + "VERSIONS.md` for their versions.", + "`openslide-bin/openslide-bin.json` records this build and its source archive.", + "", + "## Source code", + "", + "The corresponding source code is the openslide-bin source archive of this build. It holds the source code of", + "OpenSlide and of every library linked into it, and the scripts that build them.", + "", + "- File: `openslide-bin-" + values["binVersion"] + ".tar.gz`", + "- sha256: `" + values["sha256"] + "`", + "- From openslide-bin: <" + values["url"] + ">" + kept, + "- From OpenSlideSharp: attached to the GitHub release of version `" + PackageVersion + "`,", + " <" + releases + "/tag/v" + PackageVersion + ">, which keeps it (all releases: <" + releases + ">)", + "", + "Check a download by its file name and against the sha256 above (`source.sha256` in", + "`openslide-bin/openslide-bin.json`).", + "", + "## Using another OpenSlide build", + "", + "Set the `OPENSLIDE_LIBRARY_PATH` environment variable to the full path of another build of the OpenSlide 4.x library,", + "for example one built from the source above, changed or not. The viewer then loads that library instead of the one it", + "contains:", + "", + "```sh", + "OPENSLIDE_LIBRARY_PATH=/path/to/libopenslide.so.1 ./OpenSlideSharp.Viewer slide.svs", + "```", + "", + "```powershell", + "$env:OPENSLIDE_LIBRARY_PATH = 'C:\\path\\to\\libopenslide-1.dll'", + ".\\OpenSlideSharp.Viewer.exe slide.svs", + "```", + "", + "`OpenSlideSharp.Viewer --check slide.svs` prints the version of the library it loaded (`openslide=...`).", + }; + string text = string.Join("\n", lines) + "\n"; + if (!File.Exists(OutputFile) || File.ReadAllText(OutputFile) != text) + { + Directory.CreateDirectory(Path.GetDirectoryName(OutputFile)); + File.WriteAllText(OutputFile, text); + } + } + ]]> + + + diff --git a/samples/OpenSlideSharp.Viewer/README.md b/samples/OpenSlideSharp.Viewer/README.md index bb18793..96ed651 100644 --- a/samples/OpenSlideSharp.Viewer/README.md +++ b/samples/OpenSlideSharp.Viewer/README.md @@ -54,7 +54,7 @@ The native libraries are inside the executable. It extracts them on first start ## Licenses -`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, with their versions in each platform's `VERSIONS.md` under `openslide-bin/`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them, and `SOURCE.md` says where OpenSlide's source code is and how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The planned GitHub release builds will ship this publish folder, executable and `licenses/`, as one archive per platform. +`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, under `openslide-bin//` for the openslide-bin build of the publish's platform, with their versions in its `VERSIONS.md`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them. `SOURCE.md`, written at publish time from `openslide-bin/openslide-bin.json`, names the exact openslide-bin build and its source tarball (file name, sha256, the openslide-bin download URL, and the copy attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the same version), and says how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The planned GitHub release builds will ship this publish folder, executable and `licenses/`, as one archive per platform. ## Known issue on Windows diff --git a/samples/OpenSlideSharp.Viewer/SOURCE.md b/samples/OpenSlideSharp.Viewer/SOURCE.md deleted file mode 100644 index 3515dee..0000000 --- a/samples/OpenSlideSharp.Viewer/SOURCE.md +++ /dev/null @@ -1,36 +0,0 @@ -# OpenSlide: source code and replacing the library - -The viewer contains a build of [OpenSlide](https://openslide.org/) from -[openslide-bin](https://github.com/openslide/openslide-bin): `libopenslide-1.dll` on Windows, `libopenslide-1.so` on -Linux and `libopenslide-1.dylib` on macOS, which the executable extracts when it first starts. OpenSlide is licensed -under the GNU Lesser General Public License 2.1, and the libraries linked into it under their own licenses: see -`openslide-bin//`, and `openslide-bin//VERSIONS.md` for their versions. -`openslide-bin/openslide-bin.json` names the openslide-bin build and its source tarball. - -## Source code - -The corresponding source code is the openslide-bin source archive of the same build, `openslide-bin-.tar.gz`, -published with its binaries: - -- a release: `https://github.com/openslide/openslide-bin/releases/download/v/openslide-bin-.tar.gz` -- a nightly build: the release `v` on (nightly builds are kept - for a limited time) - -The viewer has the version of the OpenSlideSharp packages it was built with, and the table under "Versioning" in - gives the openslide-bin build of each version. - -## Using another OpenSlide build - -Set the `OPENSLIDE_LIBRARY_PATH` environment variable to the full path of another build of the OpenSlide 4.x library, -for example one built from the source above, changed or not. The viewer then loads that library instead of the one it -contains: - -```sh -OPENSLIDE_LIBRARY_PATH=/path/to/libopenslide.so.1 ./OpenSlideSharp.Viewer slide.svs -``` - -```powershell -$env:OPENSLIDE_LIBRARY_PATH = 'C:\path\to\libopenslide-1.dll'; .\OpenSlideSharp.Viewer.exe slide.svs -``` - -`OpenSlideSharp.Viewer --check slide.svs` prints the version of the library it loaded (`openslide=...`). diff --git a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt index 17848bc..75dfe98 100644 --- a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt +++ b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt @@ -19,7 +19,10 @@ file. Files: openslide-bin//VERSIONS.md (the components and their versions) openslide-bin/// (their license texts) openslide-bin/openslide-bin.json (the openslide-bin build and its source tarball) - Source code, and how to use another OpenSlide build instead: SOURCE.md. + is the openslide-bin build of the executable's platform: windows-x64, + linux-x86_64, linux-aarch64 or macos-arm64-x86_64. + Source code (the exact build, its source tarball with its sha256, and where to download it), and + how to use another OpenSlide build instead: SOURCE.md. 2. SkiaSharp and Skia License: SkiaSharp: MIT. Skia: BSD-3-Clause, and the licenses of the code it includes. @@ -45,11 +48,11 @@ file. Upstream: https://github.com/AvaloniaUI/Avalonia 6. MicroCom.Runtime - License: MIT. Copyright 2021 Nikita Tsukanov. + License: MIT; the text is below. Upstream: https://github.com/kekekeks/MicroCom 7. Tmds.DBus.Protocol (Linux) - License: MIT. Copyright Tom Deseyn. + License: MIT; the text is below. Upstream: https://github.com/tmds/Tmds.DBus 8. .NET runtime @@ -89,6 +92,59 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +------------------------------------------------------------------------------- +MicroCom.Runtime license (https://github.com/kekekeks/MicroCom/blob/master/LICENSE) +------------------------------------------------------------------------------- + +MIT License + +Copyright (c) 2021 Nikita Tsukanov + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +------------------------------------------------------------------------------- +Tmds.DBus.Protocol license (https://github.com/tmds/Tmds.DBus/blob/main/COPYING) +------------------------------------------------------------------------------- + +Copyright 2006 Alp Toker +Copyright 2010 Other Contributors +Copyright 2016 Tom Deseyn + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + ------------------------------------------------------------------------------- Inter license (https://github.com/rsms/inter/blob/master/LICENSE.txt) ------------------------------------------------------------------------------- From 9e357f972c25f972122b1ecdf4d31774a92c8fe3 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 20:32:30 +0800 Subject: [PATCH 10/38] build: compute the NuGet release version and detect upstream openslide-bin updates NuGetVersion.psm1 orders versions by NuGet rules. Get-ReleaseVersion.ps1 applies the version table and refuses a version that is not above the highest one on nuget.org. Find-UpstreamUpdate.ps1 lists the stable and nightly upstream releases worth syncing, lowest version first. Both have a network-free -SelfTest. --- eng/Find-UpstreamUpdate.ps1 | 166 ++++++++++++++++++++++++++++++++++++ eng/Get-ReleaseVersion.ps1 | 166 ++++++++++++++++++++++++++++++++++++ eng/NuGetVersion.psm1 | 80 +++++++++++++++++ 3 files changed, 412 insertions(+) create mode 100644 eng/Find-UpstreamUpdate.ps1 create mode 100644 eng/Get-ReleaseVersion.ps1 create mode 100644 eng/NuGetVersion.psm1 diff --git a/eng/Find-UpstreamUpdate.ps1 b/eng/Find-UpstreamUpdate.ps1 new file mode 100644 index 0000000..1e07f45 --- /dev/null +++ b/eng/Find-UpstreamUpdate.ps1 @@ -0,0 +1,166 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Lists the upstream openslide-bin releases that should be synced into eng/openslide.json, as a JSON array. +.DESCRIPTION + Looks at the latest stable openslide-bin release and the latest nightly in openslide/builds. A release is a + candidate only when its NuGet version (version table in Get-ReleaseVersion.ps1) is strictly higher than the manifest's + and than the highest version published on nuget.org. Old-series maintenance releases are therefore skipped, and the + manifest never goes down. Output order is ascending by NuGet version, stable first. No update prints []. + Each item: channel, tag, binVersion, version. A GitHub API failure exits non-zero; it never prints []. + Honours $env:GITHUB_TOKEN. -SelfTest runs built-in cases against mock data (no network) and exits 1 if one fails. +#> +[CmdletBinding()] +param( + [string]$Manifest, + [string[]]$PublishedVersions, + [switch]$SelfTest +) +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +Import-Module (Join-Path $PSScriptRoot 'NuGetVersion.psm1') -Force + +function Get-UpstreamNuGetVersion([string]$BinVersion, [string]$OpenSlideVersion, [string]$Date8, [bool]$Nightly) { + # Version table: stable X.Y.Z.B -> X.Y.Z.B; nightly X.Y.Z.B+YYYYMMDD.nightly -> X.Y.Z.(B+1)-nightly.YYYYMMDD.g. + $core = ($BinVersion -split '\+')[0] + if ($core -notmatch '^\d+(\.\d+){2,3}$') { throw "Unsupported openslide-bin version '$BinVersion'." } + if (-not $Nightly) { return $core } + if ($OpenSlideVersion -notmatch '-g([0-9a-f]{8,})$') { throw "Cannot extract the OpenSlide commit from '$OpenSlideVersion'." } + $n = [int[]]@($core -split '\.') + while ($n.Count -lt 4) { $n += 0 } + '{0}.{1}.{2}.{3}-nightly.{4}.g{5}' -f $n[0], $n[1], $n[2], ($n[3] + 1), $Date8, $Matches[1].Substring(0, 8) +} + +function Get-NightlyReleaseInfo($Release) { + $tag = [string]$Release.tag_name + if ($tag -notmatch '^v(\d+(?:\.\d+){2,3}\+(\d{8})\.nightly)$') { throw "Unexpected nightly tag '$tag'." } + $bin = $Matches[1]; $date8 = $Matches[2] + if ([string]$Release.body -notmatch '\*\*OpenSlide\*\*\s*\|\s*\*\*([^*\s|]+)\*\*') { + throw "Release $tag lists no OpenSlide version in its notes, so its NuGet version cannot be computed." + } + $osv = $Matches[1] + [pscustomobject]@{ Tag = $tag; BinVersion = $bin; OpenSlideVersion = $osv; Version = (Get-UpstreamNuGetVersion $bin $osv $date8 $true) } +} + +function Get-UpstreamCandidates { + param([Parameter(Mandatory)]$Manifest, $StableRelease, $NightlyRelease, [string[]]$PublishedVersions) + $isNightlyManifest = $Manifest.channel -eq 'nightly' + $manifestVersion = Get-UpstreamNuGetVersion ([string]$Manifest.binVersion) ([string]$Manifest.openslideVersion) ([string]$Manifest.date -replace '-', '') $isNightlyManifest + $manifestTag = "v$($Manifest.binVersion)" + $published = Get-MaxNuGetVersion $PublishedVersions + # Strictly above both the manifest and the highest published version, and never the manifest's own tag. + $isNew = { + param($Tag, $Version) + $Tag -ne $manifestTag -and (Compare-NuGetVersion $Version $manifestVersion) -gt 0 -and + ($null -eq $published -or (Compare-NuGetVersion $Version $published) -gt 0) + } + $candidates = [System.Collections.Generic.List[object]]::new() + if ($StableRelease) { + $tag = [string]$StableRelease.tag_name + $bin = $tag -replace '^v', '' + $version = Get-UpstreamNuGetVersion $bin '' '' $false + if (& $isNew $tag $version) { + $candidates.Add([ordered]@{ channel = 'stable'; tag = $tag; binVersion = $bin; version = $version }) + } + } + if ($NightlyRelease) { + $n = Get-NightlyReleaseInfo $NightlyRelease + # After a stable candidate the manifest sits on that version, so the nightly has to beat it as well. + $floor = if ($candidates.Count -gt 0) { $candidates[0].version } else { $null } + if ((& $isNew $n.Tag $n.Version) -and ($null -eq $floor -or (Compare-NuGetVersion $n.Version $floor) -gt 0)) { + $candidates.Add([ordered]@{ channel = 'nightly'; tag = $n.Tag; binVersion = $n.BinVersion; version = $n.Version }) + } + } + $candidates.ToArray() +} + +function Invoke-GitHubApi([string]$Path) { + $headers = @{ Accept = 'application/vnd.github+json'; 'User-Agent' = 'OpenSlideSharp-upstream-sync' } + if ($env:GITHUB_TOKEN) { $headers.Authorization = "Bearer $($env:GITHUB_TOKEN)" } + $url = "https://api.github.com/$Path" + $r = Invoke-WebRequest -Uri $url -Headers $headers -SkipHttpErrorCheck + if ($r.StatusCode -ne 200) { throw "GET $url returned HTTP $($r.StatusCode)." } + $r.Content | ConvertFrom-Json -NoEnumerate +} + +if ($SelfTest) { + $results = [System.Collections.Generic.List[object]]::new() + function Test-Case([string]$Name, [scriptblock]$Body) { + try { $ok = [bool](& $Body) } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } + $results.Add([pscustomobject]@{ Name = $Name; Ok = $ok }) + } + function New-Manifest($Channel, $Bin, $OsVersion, $Commit, $Date) { + [pscustomobject]@{ channel = $Channel; binVersion = $Bin; openslideVersion = $OsVersion; openslideCommit = $Commit; date = $Date } + } + function New-Stable($Tag) { [pscustomobject]@{ tag_name = $Tag; prerelease = $false; draft = $false; body = '## Changes' } } + function New-Nightly($Tag, $OsVersion) { + [pscustomobject]@{ tag_name = $Tag; prerelease = $true; draft = $false + body = "See the build index.`n`n| Software | Version |`n| -------- | ------- |`n| **OpenSlide** | **$OsVersion** |`n| cairo | 1.18.4-2 |" } + } + function Find($Manifest, $Stable, $Nightly, $Published = @('1.1.2')) { + ,@(Get-UpstreamCandidates -Manifest $Manifest -StableRelease $Stable -NightlyRelease $Nightly -PublishedVersions $Published) + } + $nightlyManifest = New-Manifest 'nightly' '4.0.1.2+20261102.nightly' 'v4.0.1-49-g174630bf' '174630bf' '2026-11-02' + $stableManifest = New-Manifest 'stable' '4.0.1.2' 'v4.0.1' 'fe79a971' '2026-06-20' + + Test-Case 'nightly manifest equal to upstream: no candidates' { + (Find $nightlyManifest (New-Stable 'v4.0.1.2') (New-Nightly 'v4.0.1.2+20261102.nightly' 'v4.0.1-49-g174630bf')).Count -eq 0 } + Test-Case 'old-series stable 4.0.0.14 vs manifest 4.0.1.2: skipped' { + (Find $stableManifest (New-Stable 'v4.0.0.14') $null).Count -eq 0 } + Test-Case 'stable 4.0.2.0 and nightly 4.0.2.0+...: stable first, then nightly' { + $c = Find $stableManifest (New-Stable 'v4.0.2.0') (New-Nightly 'v4.0.2.0+20261201.nightly' 'v4.0.2-3-gabcdef0123') + $c.Count -eq 2 -and $c[0].channel -eq 'stable' -and $c[0].tag -eq 'v4.0.2.0' -and $c[0].version -eq '4.0.2.0' -and $c[0].binVersion -eq '4.0.2.0' -and + $c[1].channel -eq 'nightly' -and $c[1].tag -eq 'v4.0.2.0+20261201.nightly' -and $c[1].version -eq '4.0.2.1-nightly.20261201.gabcdef01' -and + $c[1].binVersion -eq '4.0.2.0+20261201.nightly' } + Test-Case 'newer nightly only, manifest nightly: one nightly candidate' { + $c = Find $nightlyManifest (New-Stable 'v4.0.1.2') (New-Nightly 'v4.0.1.2+20261110.nightly' 'v4.0.1-52-g11112222') + $c.Count -eq 1 -and $c[0].channel -eq 'nightly' -and $c[0].version -eq '4.0.1.3-nightly.20261110.g11112222' } + Test-Case 'older nightly than the manifest: skipped (never downgrade)' { + (Find $nightlyManifest $null (New-Nightly 'v4.0.1.2+20261101.nightly' 'v4.0.1-47-g377f40b1')).Count -eq 0 } + Test-Case 'nightly not above the highest published version: skipped' { + (Find $nightlyManifest $null (New-Nightly 'v4.0.1.2+20261110.nightly' 'v4.0.1-52-g11112222') @('1.1.2', '4.0.1.3')).Count -eq 0 } + Test-Case 'stable manifest 4.0.1.2, stable upstream 4.0.1.2: not a candidate (manifest tag)' { + (Find $stableManifest (New-Stable 'v4.0.1.2') $null).Count -eq 0 } + Test-Case 'stable not above the highest published version: skipped' { + (Find $stableManifest (New-Stable 'v4.0.2.0') $null @('4.0.2.0')).Count -eq 0 } + Test-Case 'nightly based on an older series than a new stable: only the stable is kept' { + $c = Find $stableManifest (New-Stable 'v4.0.2.0') (New-Nightly 'v4.0.1.9+20261201.nightly' 'v4.0.1-60-g99998888') + $c.Count -eq 1 -and $c[0].channel -eq 'stable' } + Test-Case 'only stable exists upstream' { + $c = Find $nightlyManifest (New-Stable 'v4.1.0.0') $null + $c.Count -eq 1 -and $c[0].version -eq '4.1.0.0' } + Test-Case 'only nightly exists upstream' { + $c = Find $stableManifest $null (New-Nightly 'v4.0.1.2+20261110.nightly' 'v4.0.1-52-g11112222') + $c.Count -eq 1 -and $c[0].version -eq '4.0.1.3-nightly.20261110.g11112222' } + Test-Case 'nothing exists upstream' { (Find $stableManifest $null $null).Count -eq 0 } + Test-Case 'empty published list is accepted' { (Find $stableManifest (New-Stable 'v4.0.2.0') $null @()).Count -eq 1 } + Test-Case 'nightly release without an OpenSlide row in the notes is an error' { + try { Find $stableManifest $null ([pscustomobject]@{ tag_name = 'v4.0.1.3+20261110.nightly'; body = 'nothing' }); $false } catch { $_.Exception.Message -match 'OpenSlide' } } + Test-Case 'Compare 4.0.1.3-nightly.20261102.g174630bf < 4.0.1.3' { + (Compare-NuGetVersion '4.0.1.3-nightly.20261102.g174630bf' '4.0.1.3') -eq -1 } + Test-Case 'Compare 1.1.2 < 4.0.1.2' { (Compare-NuGetVersion '1.1.2' '4.0.1.2') -eq -1 } + + foreach ($r in $results) { Write-Host ("{0} {1}" -f ($r.Ok ? 'PASS' : 'FAIL'), $r.Name) } + $failed = @($results | Where-Object { -not $_.Ok }).Count + Write-Host "$($results.Count - $failed) passed, $failed failed" + exit ($failed -gt 0 ? 1 : 0) +} + +$repoRoot = Split-Path -Parent $PSScriptRoot +try { + if (-not $Manifest) { $Manifest = Join-Path $repoRoot 'eng/openslide.json' } + $manifestObject = Get-Content -Raw -Path $Manifest | ConvertFrom-Json + if ($null -eq $PSBoundParameters['PublishedVersions']) { $PublishedVersions = Get-PublishedNuGetVersions } + + $stable = Invoke-GitHubApi 'repos/openslide/openslide-bin/releases/latest' + $nightly = $null + foreach ($r in (Invoke-GitHubApi 'repos/openslide/builds/releases?per_page=30')) { + if ($r.prerelease -and -not $r.draft -and $r.assets.Count -gt 0) { $nightly = $r; break } + } + $found = @(Get-UpstreamCandidates -Manifest $manifestObject -StableRelease $stable -NightlyRelease $nightly -PublishedVersions $PublishedVersions) + if ($found.Count -eq 0) { '[]' } else { $found | ConvertTo-Json -AsArray -Depth 3 } +} catch { + [Console]::Error.WriteLine("Find-UpstreamUpdate: $($_.Exception.Message)") + exit 1 +} diff --git a/eng/Get-ReleaseVersion.ps1 b/eng/Get-ReleaseVersion.ps1 new file mode 100644 index 0000000..a1379b7 --- /dev/null +++ b/eng/Get-ReleaseVersion.ps1 @@ -0,0 +1,166 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Computes the NuGet release version for the current eng/openslide.json and prints it, with the release metadata, as JSON. +.DESCRIPTION + Version table: + stable manifest X.Y.Z.B -> X.Y.Z.B + nightly manifest X.Y.Z.B+YYYYMMDD.nightly -> X.Y.Z.(B+1)-nightly.YYYYMMDD.g + C#-only release of an unchanged upstream (the tag of the base version exists) -> base version + ".N", N from 1 + stable manifest with a C#-only release -> numbered like a nightly: the stable release's date and commit. + The version must be higher than every version published on nuget.org, or the script fails. + -PublishedVersions defaults to the nuget.org flat container, -ExistingTags to `git tag --list 'v*'`. + -SelfTest runs built-in cases against mock data (no network, no git) and exits 1 if one fails. +#> +[CmdletBinding()] +param( + [string]$Manifest, + [string[]]$PublishedVersions, + [string[]]$ExistingTags, + [switch]$SelfTest +) +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +Import-Module (Join-Path $PSScriptRoot 'NuGetVersion.psm1') -Force + +function Get-NextSuffix([string]$Base, [string[]]$Tags) { + # Highest N among the tags v (counts as 0) and v.N, plus 1; $null when none of them exists. + $max = -1 + $pattern = '^v' + [regex]::Escape($Base) + '(?:\.(\d+))?$' + foreach ($t in @($Tags)) { + if ($t -match $pattern) { # -match is case-insensitive + $n = if ($Matches[1]) { [int]$Matches[1] } else { 0 } + if ($n -gt $max) { $max = $n } + } + } + if ($max -lt 0) { $null } else { $max + 1 } +} + +function Get-ReleaseVersionInfo { + param([Parameter(Mandatory)]$Manifest, [string[]]$PublishedVersions, [string[]]$ExistingTags) + $bin = [string]$Manifest.binVersion + $core = ($bin -split '\+')[0] + if ($core -notmatch '^\d+(\.\d+){2,3}$') { throw "Unsupported binVersion '$bin'." } + $nums = [int[]]@($core -split '\.') + while ($nums.Count -lt 4) { $nums += 0 } + $nightlyBase = '{0}.{1}.{2}.{3}-nightly.{4}.g{5}' -f $nums[0], $nums[1], $nums[2], ($nums[3] + 1), + ([string]$Manifest.date -replace '-', ''), ([string]$Manifest.openslideCommit).Substring(0, 8) + if ($Manifest.channel -eq 'nightly') { + $suffix = Get-NextSuffix $nightlyBase $ExistingTags + $version = if ($null -eq $suffix) { $nightlyBase } else { "$nightlyBase.$suffix" } + } elseif ($Manifest.channel -eq 'stable') { + if ($null -eq (Get-NextSuffix $core $ExistingTags)) { + $version = $core + } else { + $suffix = Get-NextSuffix $nightlyBase $ExistingTags + $version = "$nightlyBase.$([Math]::Max(1, [int]$suffix))" + } + } else { + throw "Unknown manifest channel '$($Manifest.channel)'." + } + + $max = Get-MaxNuGetVersion $PublishedVersions + if ($null -ne $max -and (Compare-NuGetVersion $version $max) -le 0) { + throw "Version $version is not higher than the highest version published on nuget.org ($max); refusing to release an out-of-order version." + } + + $tarball = "openslide-bin-$bin.tar.gz" + $notes = @( + "OpenSlideSharp $version, built against OpenSlide binaries from openslide-bin ``$bin``.", + '', + "- openslide-bin: ``$bin`` ($($Manifest.releaseUrl))", + "- OpenSlide: ``$($Manifest.openslideVersion)`` (commit ``$($Manifest.openslideCommit)``)", + "- Upstream source tarball: $($Manifest.source.url)", + "- This release attaches ``$tarball`` (sha256 ``$($Manifest.source.sha256)``), a copy of that tarball. The upstream nightly URL expires, so this copy is the permanent source for the bundled binaries." + ) -join "`n" + [ordered]@{ + version = $version + prerelease = $version.Contains('-') + informationalVersion = "$version+openslide.$($Manifest.openslideVersion)" + tag = "v$version" + releaseName = "OpenSlideSharp $version" + notes = $notes + } +} + +if ($SelfTest) { + $results = [System.Collections.Generic.List[object]]::new() + function Test-Case([string]$Name, [scriptblock]$Body) { + try { $ok = [bool](& $Body) } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } + $results.Add([pscustomobject]@{ Name = $Name; Ok = $ok }) + } + function New-Manifest($Channel, $Bin, $OsVersion, $Commit, $Date) { + [pscustomobject]@{ channel = $Channel; binVersion = $Bin; openslideVersion = $OsVersion; openslideCommit = $Commit; date = $Date + source = [pscustomobject]@{ url = 'https://example.invalid/src.tar.gz'; sha256 = ('ab' * 32) } } + } + function Get-Version($Manifest, $Published = @('1.1.2'), $Tags = @()) { + (Get-ReleaseVersionInfo -Manifest $Manifest -PublishedVersions $Published -ExistingTags $Tags).version + } + $nightly = New-Manifest 'nightly' '4.0.1.2+20261102.nightly' 'v4.0.1-49-g174630bf' '174630bf' '2026-11-02' + $stable = New-Manifest 'stable' '4.0.1.2' 'v4.0.1' 'fe79a971' '2026-06-20' + $nb = '4.0.1.3-nightly.20261102.g174630bf' + + Test-Case "Compare $nb < 4.0.1.3" { (Compare-NuGetVersion $nb '4.0.1.3') -eq -1 } + Test-Case "Compare $nb > 4.0.1.2" { (Compare-NuGetVersion $nb '4.0.1.2') -eq 1 } + Test-Case 'Compare ...g174630bf.10 > ...g174630bf.9' { (Compare-NuGetVersion "$nb.10" "$nb.9") -eq 1 } + Test-Case 'Compare ...g174630bf.1 > ...g174630bf' { (Compare-NuGetVersion "$nb.1" $nb) -eq 1 } + Test-Case 'Compare 1.1.2 < 4.0.1.2' { (Compare-NuGetVersion '1.1.2' '4.0.1.2') -eq -1 } + Test-Case 'Compare 4.0.1 == 4.0.1.0' { (Compare-NuGetVersion '4.0.1' '4.0.1.0') -eq 0 } + Test-Case 'Compare 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta' { + (Compare-NuGetVersion '1.0.0-alpha' '1.0.0-alpha.1') -eq -1 -and (Compare-NuGetVersion '1.0.0-alpha.1' '1.0.0-beta') -eq -1 -and + (Compare-NuGetVersion '1.0.0-beta' '1.0.0-alpha') -eq 1 } + Test-Case 'Compare ignores case in labels and metadata' { + (Compare-NuGetVersion '1.0.0-Beta+abc' '1.0.0-beta+xyz') -eq 0 } + Test-Case 'Compare numeric label segment < alphanumeric segment' { (Compare-NuGetVersion '1.0.0-1' '1.0.0-a') -eq -1 } + Test-Case 'Compare 4.0.1.3 > 1.1.2-beta' { (Compare-NuGetVersion '4.0.1.3' '1.1.2-beta') -eq 1 } + + Test-Case 'nightly manifest, no tag, published 1.1.2' { (Get-Version $nightly) -eq $nb } + Test-Case 'nightly manifest, base tag exists -> .1' { (Get-Version $nightly -Tags "v$nb") -eq "$nb.1" } + Test-Case 'nightly manifest, tags .1 and .2 -> .3' { (Get-Version $nightly -Tags "v$nb.1", "v$nb.2") -eq "$nb.3" } + Test-Case 'nightly manifest, .9 and .10 -> .11 (numeric max)' { (Get-Version $nightly -Tags "v$nb", "v$nb.9", "v$nb.10") -eq "$nb.11" } + Test-Case 'unrelated tags are ignored' { (Get-Version $nightly -Tags 'v1.1.1', 'v4.0.1.3', "v$nb-x") -eq $nb } + Test-Case 'stable manifest, no tag -> 4.0.1.2' { (Get-Version $stable) -eq '4.0.1.2' } + Test-Case 'stable manifest, tag v4.0.1.2 exists -> nightly-numbered .1' { + (Get-Version $stable -Tags 'v4.0.1.2') -eq '4.0.1.3-nightly.20260620.gfe79a971.1' } + Test-Case 'stable manifest, v4.0.1.2 and .1 exist -> .2' { + (Get-Version $stable -Tags 'v4.0.1.2', 'v4.0.1.3-nightly.20260620.gfe79a971.1') -eq '4.0.1.3-nightly.20260620.gfe79a971.2' } + Test-Case 'monotonic: published 4.0.1.3 rejects nightly 4.0.1.3-nightly...' { + try { Get-Version $nightly -Published '1.1.2', '4.0.1.3'; $false } catch { $_.Exception.Message -match 'not higher' } } + Test-Case 'monotonic: published version equal to the computed one is rejected' { + try { Get-Version $stable -Published '4.0.1.2'; $false } catch { $_.Exception.Message -match 'not higher' } } + Test-Case 'published versions are lower-case and compared case-insensitively' { + try { Get-Version $nightly -Published $nb.ToLowerInvariant(); $false } catch { $_.Exception.Message -match 'not higher' } } + Test-Case 'empty published list is accepted' { (Get-Version $nightly -Published @()) -eq $nb } + + $info = Get-ReleaseVersionInfo -Manifest $nightly -PublishedVersions @('1.1.2') -ExistingTags @() + Test-Case 'nightly is a prerelease; stable is not' { + $info.prerelease -eq $true -and (Get-ReleaseVersionInfo -Manifest $stable -PublishedVersions @() -ExistingTags @()).prerelease -eq $false } + Test-Case 'informationalVersion = version+openslide.' { + $info.informationalVersion -eq "$nb+openslide.v4.0.1-49-g174630bf" } + Test-Case 'tag and releaseName' { $info.tag -eq "v$nb" -and $info.releaseName -eq "OpenSlideSharp $nb" } + Test-Case 'notes name versions, commit, source URL and the attached tarball with its sha256' { + $info.notes -match [regex]::Escape('4.0.1.2+20261102.nightly') -and $info.notes -match 'v4\.0\.1-49-g174630bf' -and + $info.notes -match '174630bf' -and $info.notes -match 'example\.invalid/src\.tar\.gz' -and + $info.notes -match [regex]::Escape('openslide-bin-4.0.1.2+20261102.nightly.tar.gz') -and $info.notes -match ('ab' * 32) } + + foreach ($r in $results) { Write-Host ("{0} {1}" -f ($r.Ok ? 'PASS' : 'FAIL'), $r.Name) } + $failed = @($results | Where-Object { -not $_.Ok }).Count + Write-Host "$($results.Count - $failed) passed, $failed failed" + exit ($failed -gt 0 ? 1 : 0) +} + +$repoRoot = Split-Path -Parent $PSScriptRoot +try { + if (-not $Manifest) { $Manifest = Join-Path $repoRoot 'eng/openslide.json' } + $manifestObject = Get-Content -Raw -Path $Manifest | ConvertFrom-Json + if ($null -eq $PSBoundParameters['PublishedVersions']) { $PublishedVersions = Get-PublishedNuGetVersions } + if ($null -eq $PSBoundParameters['ExistingTags']) { + $ExistingTags = @(git -C $repoRoot tag --list 'v*') + if ($LASTEXITCODE -ne 0) { throw "git tag --list failed with exit code $LASTEXITCODE." } + } + Get-ReleaseVersionInfo -Manifest $manifestObject -PublishedVersions $PublishedVersions -ExistingTags $ExistingTags | ConvertTo-Json -Depth 3 +} catch { + [Console]::Error.WriteLine("Get-ReleaseVersion: $($_.Exception.Message)") + exit 1 +} diff --git a/eng/NuGetVersion.psm1 b/eng/NuGetVersion.psm1 new file mode 100644 index 0000000..3430fe2 --- /dev/null +++ b/eng/NuGetVersion.psm1 @@ -0,0 +1,80 @@ +#requires -Version 7 +# NuGet version parsing and ordering, shared by Get-ReleaseVersion.ps1 and Find-UpstreamUpdate.ps1. +Set-StrictMode -Version Latest + +function ConvertTo-NuGetVersion { + <# Parses 1-4 numeric segments with an optional -prerelease and +metadata. Missing segments count as 0. #> + [CmdletBinding()] + param([Parameter(Mandatory, Position = 0)][string]$Version) + if ($Version -notmatch '^(\d+(?:\.\d+){0,3})(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$') { + throw "Not a NuGet version: '$Version'." + } + $numbers = [bigint[]]@($Matches[1] -split '\.') + while ($numbers.Count -lt 4) { $numbers += [bigint]0 } + $pre = if ($Matches.ContainsKey(2)) { $Matches[2] } else { '' } + $meta = if ($Matches.ContainsKey(3)) { $Matches[3] } else { '' } + $labels = [string[]]@() + if ($pre) { $labels = [string[]]($pre -split '\.') } + [pscustomobject]@{ + Numbers = $numbers + Prerelease = $pre + Labels = $labels + Metadata = $meta + Original = $Version + } +} + +function Compare-NuGetVersion { + <# Returns -1, 0 or 1. Metadata after '+' is ignored; prerelease labels compare per NuGet/SemVer 2. #> + [CmdletBinding()] + param([Parameter(Mandatory, Position = 0)][string]$A, [Parameter(Mandatory, Position = 1)][string]$B) + $x = ConvertTo-NuGetVersion $A + $y = ConvertTo-NuGetVersion $B + for ($i = 0; $i -lt 4; $i++) { + $c = $x.Numbers[$i].CompareTo($y.Numbers[$i]) + if ($c -ne 0) { return [Math]::Sign($c) } + } + $xHas = $x.Labels.Count -gt 0 + $yHas = $y.Labels.Count -gt 0 + if (-not $xHas -and -not $yHas) { return 0 } + if (-not $xHas) { return 1 } # a release is higher than its prereleases + if (-not $yHas) { return -1 } + $n = [Math]::Min($x.Labels.Count, $y.Labels.Count) + for ($i = 0; $i -lt $n; $i++) { + $p = $x.Labels[$i]; $q = $y.Labels[$i] + $pNum = $p -match '^\d+$'; $qNum = $q -match '^\d+$' + if ($pNum -and $qNum) { $c = ([bigint]$p).CompareTo([bigint]$q) } + elseif ($pNum) { $c = -1 } # numeric segments are lower than alphanumeric ones + elseif ($qNum) { $c = 1 } + else { $c = [string]::Compare($p, $q, [StringComparison]::OrdinalIgnoreCase) } + if ($c -ne 0) { return [Math]::Sign($c) } + } + [Math]::Sign($x.Labels.Count - $y.Labels.Count) # fewer segments is lower +} + +function Get-MaxNuGetVersion { + <# The highest of the given versions, or $null for an empty list. #> + [CmdletBinding()] + param([string[]]$Versions) + $max = $null + foreach ($v in @($Versions)) { + if ([string]::IsNullOrWhiteSpace($v)) { continue } + if ($null -eq $max -or (Compare-NuGetVersion $v $max) -gt 0) { $max = $v } + } + $max +} + +function Get-PublishedNuGetVersions { + <# All versions of a package on nuget.org (flat container, lower-case ids and versions). 404 means none. #> + [CmdletBinding()] + param([string]$PackageId = 'openslidesharp') + $url = "https://api.nuget.org/v3-flatcontainer/$($PackageId.ToLowerInvariant())/index.json" + $r = Invoke-WebRequest -Uri $url -SkipHttpErrorCheck -Headers @{ 'User-Agent' = 'OpenSlideSharp-release' } + if ($r.StatusCode -eq 404) { return @() } + if ($r.StatusCode -ne 200) { throw "GET $url returned HTTP $($r.StatusCode)." } + $json = $r.Content | ConvertFrom-Json + if ($null -eq $json -or -not ($json.PSObject.Properties.Name -contains 'versions')) { throw "GET $url returned no 'versions' list." } + [string[]]@($json.versions) +} + +Export-ModuleMember -Function ConvertTo-NuGetVersion, Compare-NuGetVersion, Get-MaxNuGetVersion, Get-PublishedNuGetVersions From 8fb6189378c3ac9dd7ab9aa7fef1fa806c16a125 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 20:32:30 +0800 Subject: [PATCH 11/38] ci: self-test the release version and upstream update scripts --- .github/workflows/ci.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 472e98d..762d9ed 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -181,3 +181,17 @@ jobs: - name: Smoke-test the packed packages shell: pwsh run: ./eng/Test-Packages.ps1 -SkipPack -Version 0.0.0-ci.${{ github.run_number }} + + scripts: + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + - name: Self-test the release version script + shell: pwsh + run: ./eng/Get-ReleaseVersion.ps1 -SelfTest + - name: Self-test the upstream update script + shell: pwsh + run: ./eng/Find-UpstreamUpdate.ps1 -SelfTest From 72fa58d5b7ccef0ae22b2453425a8ee1f7b411f1 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 20:49:36 +0800 Subject: [PATCH 12/38] build: make the version script's self-tests able to fail, and harden numbering and upstream detection Self-test cases must yield exactly one boolean. Published versions count toward the .N numbering, an empty nuget.org list is an error, the stable release is the highest one in the list rather than releases/latest, and the stable commit hash is carried into the upstream version string. --- eng/Find-UpstreamUpdate.ps1 | 31 +++++++++++++++++++++++++++---- eng/Get-ReleaseVersion.ps1 | 36 +++++++++++++++++++++++++++--------- eng/NuGetVersion.psm1 | 17 +++++++++++++---- 3 files changed, 67 insertions(+), 17 deletions(-) diff --git a/eng/Find-UpstreamUpdate.ps1 b/eng/Find-UpstreamUpdate.ps1 index 1e07f45..4dbd3af 100644 --- a/eng/Find-UpstreamUpdate.ps1 +++ b/eng/Find-UpstreamUpdate.ps1 @@ -4,7 +4,7 @@ .SYNOPSIS Lists the upstream openslide-bin releases that should be synced into eng/openslide.json, as a JSON array. .DESCRIPTION - Looks at the latest stable openslide-bin release and the latest nightly in openslide/builds. A release is a + Looks at the highest stable openslide-bin release (from the release list, not releases/latest) and the latest nightly in openslide/builds. A release is a candidate only when its NuGet version (version table in Get-ReleaseVersion.ps1) is strictly higher than the manifest's and than the highest version published on nuget.org. Old-series maintenance releases are therefore skipped, and the manifest never goes down. Output order is ascending by NuGet version, stable first. No update prints []. @@ -75,6 +75,16 @@ function Get-UpstreamCandidates { $candidates.ToArray() } +function Select-LatestStableRelease($Releases) { + # The highest stable release by NuGet order. releases/latest is creation-ordered and can point at an old-series maintenance release. + $best = $null + foreach ($r in @($Releases)) { + if ($r.prerelease -or $r.draft -or [string]$r.tag_name -notmatch '^v\d+(\.\d+){2,3}$') { continue } + if ($null -eq $best -or (Compare-NuGetVersion ([string]$r.tag_name -replace '^v', '') ([string]$best.tag_name -replace '^v', '')) -gt 0) { $best = $r } + } + $best +} + function Invoke-GitHubApi([string]$Path) { $headers = @{ Accept = 'application/vnd.github+json'; 'User-Agent' = 'OpenSlideSharp-upstream-sync' } if ($env:GITHUB_TOKEN) { $headers.Authorization = "Bearer $($env:GITHUB_TOKEN)" } @@ -87,7 +97,11 @@ function Invoke-GitHubApi([string]$Path) { if ($SelfTest) { $results = [System.Collections.Generic.List[object]]::new() function Test-Case([string]$Name, [scriptblock]$Body) { - try { $ok = [bool](& $Body) } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } + try { + # A case must produce exactly one boolean; stray output (e.g. a negative case that did not throw) is a failure. + $out = @(& $Body) + $ok = $out.Count -eq 1 -and $out[0] -is [bool] -and $out[0] + } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } $results.Add([pscustomobject]@{ Name = $Name; Ok = $ok }) } function New-Manifest($Channel, $Bin, $OsVersion, $Commit, $Date) { @@ -136,7 +150,16 @@ if ($SelfTest) { Test-Case 'nothing exists upstream' { (Find $stableManifest $null $null).Count -eq 0 } Test-Case 'empty published list is accepted' { (Find $stableManifest (New-Stable 'v4.0.2.0') $null @()).Count -eq 1 } Test-Case 'nightly release without an OpenSlide row in the notes is an error' { - try { Find $stableManifest $null ([pscustomobject]@{ tag_name = 'v4.0.1.3+20261110.nightly'; body = 'nothing' }); $false } catch { $_.Exception.Message -match 'OpenSlide' } } + try { $null = Find $stableManifest $null ([pscustomobject]@{ tag_name = 'v4.0.1.3+20261110.nightly'; body = 'nothing' }); $false } catch { $_.Exception.Message -match 'lists no OpenSlide version' } } + Test-Case 'latest stable is the highest, not the newest created (old-series maintenance release listed first)' { + $rel = @((New-Stable 'v4.0.0.14'), (New-Stable 'v4.0.1.2'), (New-Stable 'v4.0.1.1'), [pscustomobject]@{ tag_name = 'v9.9.9.9'; prerelease = $true; draft = $false }) + (Select-LatestStableRelease $rel).tag_name -eq 'v4.0.1.2' -and + (Select-LatestStableRelease @((New-Stable 'v4.0.0.14'), (New-Stable 'v4.0.2.0'), (New-Stable 'v4.0.1.9'))).tag_name -eq 'v4.0.2.0' } + Test-Case 'a newer-created old-series stable does not hide the new stable' { + $latest = Select-LatestStableRelease @((New-Stable 'v4.0.0.14'), (New-Stable 'v4.0.2.0')) + $c = Find $stableManifest $latest $null + $c.Count -eq 1 -and $c[0].tag -eq 'v4.0.2.0' } + Test-Case 'no stable releases at all gives $null' { $null -eq (Select-LatestStableRelease @()) } Test-Case 'Compare 4.0.1.3-nightly.20261102.g174630bf < 4.0.1.3' { (Compare-NuGetVersion '4.0.1.3-nightly.20261102.g174630bf' '4.0.1.3') -eq -1 } Test-Case 'Compare 1.1.2 < 4.0.1.2' { (Compare-NuGetVersion '1.1.2' '4.0.1.2') -eq -1 } @@ -153,7 +176,7 @@ try { $manifestObject = Get-Content -Raw -Path $Manifest | ConvertFrom-Json if ($null -eq $PSBoundParameters['PublishedVersions']) { $PublishedVersions = Get-PublishedNuGetVersions } - $stable = Invoke-GitHubApi 'repos/openslide/openslide-bin/releases/latest' + $stable = Select-LatestStableRelease (Invoke-GitHubApi 'repos/openslide/openslide-bin/releases?per_page=100') $nightly = $null foreach ($r in (Invoke-GitHubApi 'repos/openslide/builds/releases?per_page=30')) { if ($r.prerelease -and -not $r.draft -and $r.assets.Count -gt 0) { $nightly = $r; break } diff --git a/eng/Get-ReleaseVersion.ps1 b/eng/Get-ReleaseVersion.ps1 index a1379b7..6b8565a 100644 --- a/eng/Get-ReleaseVersion.ps1 +++ b/eng/Get-ReleaseVersion.ps1 @@ -40,6 +40,8 @@ function Get-NextSuffix([string]$Base, [string[]]$Tags) { function Get-ReleaseVersionInfo { param([Parameter(Mandatory)]$Manifest, [string[]]$PublishedVersions, [string[]]$ExistingTags) $bin = [string]$Manifest.binVersion + # Existing tags and published versions both occupy a number (published versions are written as tags: v). + $ExistingTags = @($ExistingTags) + @(@($PublishedVersions) | Where-Object { $_ } | ForEach-Object { "v$_" }) $core = ($bin -split '\+')[0] if ($core -notmatch '^\d+(\.\d+){2,3}$') { throw "Unsupported binVersion '$bin'." } $nums = [int[]]@($core -split '\.') @@ -65,6 +67,8 @@ function Get-ReleaseVersionInfo { throw "Version $version is not higher than the highest version published on nuget.org ($max); refusing to release an out-of-order version." } + $osv = [string]$Manifest.openslideVersion + $upstreamVersion = if ($osv -match '-g[0-9a-fA-F]+$') { $osv } else { "$osv.g$($Manifest.openslideCommit)" } $tarball = "openslide-bin-$bin.tar.gz" $notes = @( "OpenSlideSharp $version, built against OpenSlide binaries from openslide-bin ``$bin``.", @@ -77,7 +81,8 @@ function Get-ReleaseVersionInfo { [ordered]@{ version = $version prerelease = $version.Contains('-') - informationalVersion = "$version+openslide.$($Manifest.openslideVersion)" + openslideUpstreamVersion = $upstreamVersion + informationalVersion = "$version+openslide.$upstreamVersion" tag = "v$version" releaseName = "OpenSlideSharp $version" notes = $notes @@ -87,7 +92,11 @@ function Get-ReleaseVersionInfo { if ($SelfTest) { $results = [System.Collections.Generic.List[object]]::new() function Test-Case([string]$Name, [scriptblock]$Body) { - try { $ok = [bool](& $Body) } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } + try { + # A case must produce exactly one boolean; stray output (e.g. a negative case that did not throw) is a failure. + $out = @(& $Body) + $ok = $out.Count -eq 1 -and $out[0] -is [bool] -and $out[0] + } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } $results.Add([pscustomobject]@{ Name = $Name; Ok = $ok }) } function New-Manifest($Channel, $Bin, $OsVersion, $Commit, $Date) { @@ -126,18 +135,27 @@ if ($SelfTest) { Test-Case 'stable manifest, v4.0.1.2 and .1 exist -> .2' { (Get-Version $stable -Tags 'v4.0.1.2', 'v4.0.1.3-nightly.20260620.gfe79a971.1') -eq '4.0.1.3-nightly.20260620.gfe79a971.2' } Test-Case 'monotonic: published 4.0.1.3 rejects nightly 4.0.1.3-nightly...' { - try { Get-Version $nightly -Published '1.1.2', '4.0.1.3'; $false } catch { $_.Exception.Message -match 'not higher' } } - Test-Case 'monotonic: published version equal to the computed one is rejected' { - try { Get-Version $stable -Published '4.0.1.2'; $false } catch { $_.Exception.Message -match 'not higher' } } - Test-Case 'published versions are lower-case and compared case-insensitively' { - try { Get-Version $nightly -Published $nb.ToLowerInvariant(); $false } catch { $_.Exception.Message -match 'not higher' } } + try { $null = Get-Version $nightly -Published '1.1.2', '4.0.1.3'; $false } catch { $_.Exception.Message -match 'not higher' } } + Test-Case 'monotonic: published 4.0.1.4 rejects stable 4.0.1.2' { + try { $null = Get-Version $stable -Published '4.0.1.4'; $false } catch { $_.Exception.Message -match 'not higher' } } + Test-Case 'base already published, no tag -> .1' { (Get-Version $nightly -Published '1.1.2', $nb) -eq "$nb.1" } + Test-Case 'published lower-case version counts case-insensitively -> .1' { + (Get-Version $nightly -Published $nb.ToLowerInvariant()) -eq "$nb.1" } + Test-Case 'published .2 and tag .1 -> .3' { (Get-Version $nightly -Published '1.1.2', "$nb.2" -Tags "v$nb.1") -eq "$nb.3" } + Test-Case 'published .1 and tags base, .2 -> .3' { (Get-Version $nightly -Published "$nb.1" -Tags "v$nb", "v$nb.2") -eq "$nb.3" } + Test-Case 'empty fetched published list is refused' { + try { $null = Assert-PublishedNuGetVersions @(); $false } catch { $_.Exception.Message -match 'no published versions' } } + Test-Case 'non-empty fetched published list is accepted' { @(Assert-PublishedNuGetVersions @('1.1.2')).Count -eq 1 } Test-Case 'empty published list is accepted' { (Get-Version $nightly -Published @()) -eq $nb } $info = Get-ReleaseVersionInfo -Manifest $nightly -PublishedVersions @('1.1.2') -ExistingTags @() Test-Case 'nightly is a prerelease; stable is not' { $info.prerelease -eq $true -and (Get-ReleaseVersionInfo -Manifest $stable -PublishedVersions @() -ExistingTags @()).prerelease -eq $false } - Test-Case 'informationalVersion = version+openslide.' { - $info.informationalVersion -eq "$nb+openslide.v4.0.1-49-g174630bf" } + Test-Case 'informationalVersion = version+openslide.' { + $info.informationalVersion -eq "$nb+openslide.v4.0.1-49-g174630bf" -and $info.openslideUpstreamVersion -eq 'v4.0.1-49-g174630bf' } + Test-Case 'stable: openslideUpstreamVersion gets the commit appended' { + $s = Get-ReleaseVersionInfo -Manifest $stable -PublishedVersions @('1.1.2') -ExistingTags @() + $s.openslideUpstreamVersion -eq 'v4.0.1.gfe79a971' -and $s.informationalVersion -eq '4.0.1.2+openslide.v4.0.1.gfe79a971' } Test-Case 'tag and releaseName' { $info.tag -eq "v$nb" -and $info.releaseName -eq "OpenSlideSharp $nb" } Test-Case 'notes name versions, commit, source URL and the attached tarball with its sha256' { $info.notes -match [regex]::Escape('4.0.1.2+20261102.nightly') -and $info.notes -match 'v4\.0\.1-49-g174630bf' -and diff --git a/eng/NuGetVersion.psm1 b/eng/NuGetVersion.psm1 index 3430fe2..a8fedff 100644 --- a/eng/NuGetVersion.psm1 +++ b/eng/NuGetVersion.psm1 @@ -65,16 +65,25 @@ function Get-MaxNuGetVersion { } function Get-PublishedNuGetVersions { - <# All versions of a package on nuget.org (flat container, lower-case ids and versions). 404 means none. #> + <# All versions of a package on nuget.org (flat container, lower-case ids and versions). 404, any other non-200 status and an empty list are errors. #> [CmdletBinding()] param([string]$PackageId = 'openslidesharp') $url = "https://api.nuget.org/v3-flatcontainer/$($PackageId.ToLowerInvariant())/index.json" $r = Invoke-WebRequest -Uri $url -SkipHttpErrorCheck -Headers @{ 'User-Agent' = 'OpenSlideSharp-release' } - if ($r.StatusCode -eq 404) { return @() } if ($r.StatusCode -ne 200) { throw "GET $url returned HTTP $($r.StatusCode)." } $json = $r.Content | ConvertFrom-Json if ($null -eq $json -or -not ($json.PSObject.Properties.Name -contains 'versions')) { throw "GET $url returned no 'versions' list." } - [string[]]@($json.versions) + Assert-PublishedNuGetVersions ([string[]]@($json.versions)) $PackageId } -Export-ModuleMember -Function ConvertTo-NuGetVersion, Compare-NuGetVersion, Get-MaxNuGetVersion, Get-PublishedNuGetVersions +function Assert-PublishedNuGetVersions { + <# The package is known to exist on nuget.org, so an empty list means a broken fetch, not "nothing published". #> + [CmdletBinding()] + param([string[]]$Versions, [string]$PackageId = 'openslidesharp') + if (@($Versions | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }).Count -eq 0) { + throw "nuget.org returned no published versions for $PackageId, which is known to exist; refusing to continue without the monotonic check." + } + [string[]]@($Versions) +} + +Export-ModuleMember -Function ConvertTo-NuGetVersion, Compare-NuGetVersion, Get-MaxNuGetVersion, Get-PublishedNuGetVersions, Assert-PublishedNuGetVersions From 723ee870b5a560795af28662a73c173559571ef6 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 21:27:55 +0800 Subject: [PATCH 13/38] build: pack only, with the upstream OpenSlide version, for releases Test-Packages.ps1 -PackOnly packs the five packages the usual way and checks their contents, without the smoke tests, leaving them in artifacts/smoke-feed. -OpenSlideUpstreamVersion goes to every pack, and every OpenSlideSharp assembly in the packages must then have the InformationalVersion +openslide.. --- eng/Test-Packages.ps1 | 50 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 5 deletions(-) diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index 5f86735..c4be9af 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -12,14 +12,24 @@ binaries and notices eng/openslide.json pins. -SkipPack reuses the nupkgs already in artifacts/smoke-feed (CI downloads them there) instead of packing; everything else, including the nupkg content assertions, still runs. net48 and the C++ stage only run on Windows. + +-PackOnly packs and checks the nupkg contents, as the release does, and runs no +smoke test: the five nupkgs are left in artifacts/smoke-feed. + +-OpenSlideUpstreamVersion is passed to every pack (see Directory.Build.props), +and every OpenSlideSharp assembly in the nupkgs must then have the +InformationalVersion +openslide.. #> [CmdletBinding()] param( [string]$Version = "0.0.0-smoke.$([DateTime]::UtcNow.ToString('yyyyMMddHHmmss'))", - [switch]$SkipPack + [switch]$SkipPack, + [switch]$PackOnly, + [string]$OpenSlideUpstreamVersion ) $ErrorActionPreference = 'Stop' +if ($SkipPack -and $PackOnly) { throw '-SkipPack and -PackOnly cannot be used together.' } Add-Type -AssemblyName System.IO.Compression.FileSystem $root = Split-Path -Parent $PSScriptRoot @@ -52,17 +62,19 @@ else { # Pack only what eng/openslide.json pins: every platform's binaries, licenses and openslide-bin.json. & (Join-Path $PSScriptRoot 'Get-OpenSlide.ps1') -Platform all -Verify + $versionProps = @("-p:Version=$Version") + if ($OpenSlideUpstreamVersion) { $versionProps += "-p:OpenSlideUpstreamVersion=$OpenSlideUpstreamVersion" } foreach ($proj in 'src/OpenSlideSharp/OpenSlideSharp.csproj', 'src/OpenSlideSharp.SkiaSharp/OpenSlideSharp.SkiaSharp.csproj', 'src/OpenSlideSharp.runtime/OpenSlideSharp.runtime.csproj', 'src/OpenSlideSharp.AspNetCore/OpenSlideSharp.AspNetCore.csproj') { - Invoke-Native dotnet @('pack', (Join-Path $root $proj), '-c', 'Release', '-o', $feed, "-p:Version=$Version") + Invoke-Native dotnet (@('pack', (Join-Path $root $proj), '-c', 'Release', '-o', $feed) + $versionProps) } # The tool carries the native library of every RID through OpenSlideSharp.runtime, restored from the feed just # packed. It restores into the isolated cache, so smoke versions never reach the user's NuGet cache, and builds # into its own artifacts folder, so the regular build output keeps its own restore. $env:NUGET_PACKAGES = $packages - Invoke-Native dotnet @('pack', (Join-Path $root 'src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj'), '-c', 'Release', '-o', $feed, - "-p:Version=$Version", '-p:UseOpenSlideRuntimePackage=true', "-p:RestoreAdditionalProjectSources=$feed", - '--artifacts-path', (Join-Path $artifacts 'smoke/pack-tool')) + Invoke-Native dotnet (@('pack', (Join-Path $root 'src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj'), '-c', 'Release', '-o', $feed) + + $versionProps + @('-p:UseOpenSlideRuntimePackage=true', "-p:RestoreAdditionalProjectSources=$feed", + '--artifacts-path', (Join-Path $artifacts 'smoke/pack-tool'))) } # 2. Assert nupkg contents. @@ -267,6 +279,34 @@ foreach ($phrase in 'LGPL-2.1-only', 'licenses/openslide-bin//OpenSlid $toolSize = (Get-Item $toolNupkg).Length Write-Host ("tool nupkg size: {0:N1} MB ({1} bytes)" -f ($toolSize / 1MB), $toolSize) +# With -OpenSlideUpstreamVersion every OpenSlideSharp assembly in the packages names the OpenSlide it was released with. +if ($OpenSlideUpstreamVersion) { + $wantInfo = "$Version+openslide.$OpenSlideUpstreamVersion" + $infoDir = Join-Path $artifacts 'smoke/informational-version' + New-Item -ItemType Directory -Force $infoDir | Out-Null + foreach ($id in 'OpenSlideSharp', 'OpenSlideSharp.SkiaSharp', 'OpenSlideSharp.AspNetCore', 'OpenSlideSharp.Tool') { + $zip = [IO.Compression.ZipFile]::OpenRead((Join-Path $feed "$id.$Version.nupkg")) + try { + $dlls = @($zip.Entries | Where-Object { $_.FullName -match '(^|/)OpenSlideSharp[^/]*\.dll$' }) + if ($dlls.Count -eq 0) { throw "$id nupkg has no OpenSlideSharp assembly" } + foreach ($dll in $dlls) { + $file = Join-Path $infoDir "$([Guid]::NewGuid().ToString('N')).dll" + [IO.Compression.ZipFileExtensions]::ExtractToFile($dll, $file) + # ProductVersion is the InformationalVersion (from the version resource on Windows, the metadata elsewhere). + $info = [Diagnostics.FileVersionInfo]::GetVersionInfo($file).ProductVersion + if ($info -cne $wantInfo) { throw "$id nupkg: $($dll.FullName) has InformationalVersion '$info', expected '$wantInfo'" } + } + Write-Host "$id nupkg: $($dlls.Count) assemblies with InformationalVersion $wantInfo" + } + finally { $zip.Dispose() } + } +} + +if ($PackOnly) { + Write-Host "Packed and checked the packages in $feed (-PackOnly: no smoke tests)." + exit 0 +} + # 3. Consume the packages from an isolated global cache. $env:NUGET_PACKAGES = $packages From 1e243e0099f3703e4997979aa9be5e2119d41d2b Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 21:28:13 +0800 Subject: [PATCH 14/38] build: publish the viewer from one script, and archive it for releases eng/Publish-Viewer.ps1 holds the viewer publish and its checks from Test-Packages.ps1, now for any RID: self-contained single file with the OpenSlide library from the runtime package in a feed, only the executable and licenses/ in the folder, the RID's openslide-bin notices, and SOURCE.md naming the release v. On the machine's own RID it also runs --check. -ArchiveDirectory writes the release download, OpenSlideSharp.Viewer--.zip for Windows and .tar.gz otherwise, entry by entry so that the executable has mode 755 whatever the host. Test-Packages.ps1 runs the script for its viewer smoke test. --- eng/Publish-Viewer.ps1 | 220 +++++++++++++++++++++++++++++++++++++++++ eng/Test-Packages.ps1 | 74 +------------- 2 files changed, 225 insertions(+), 69 deletions(-) create mode 100644 eng/Publish-Viewer.ps1 diff --git a/eng/Publish-Viewer.ps1 b/eng/Publish-Viewer.ps1 new file mode 100644 index 0000000..49e7f12 --- /dev/null +++ b/eng/Publish-Viewer.ps1 @@ -0,0 +1,220 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Publishes the desktop viewer the way its releases ship it: self-contained, one executable and its licenses/, with + the native OpenSlide library from the OpenSlideSharp.runtime package in a local feed. +.DESCRIPTION + Then checks the publish folder: only the executable and licenses/, with exactly the notices of the openslide-bin + archive the RID's library comes from (as the runtime package has them), and a licenses/SOURCE.md that names the + openslide-bin build of eng/openslide.json, its source tarball and the OpenSlideSharp release v. + When -Rid is this machine's, also runs the executable with --check on test/OpenSlideSharp.Tests/Fixtures/small.svs + (it reads the slide without a window) and checks that the native libraries came out of the bundle. + Cross-publishing works from any host: for osx-* the SDK signs the bundle ad hoc itself. +.PARAMETER Rid + win-x64, linux-x64, linux-arm64, osx-arm64 or osx-x64. Default: this machine's. +.PARAMETER Feed + A folder with OpenSlideSharp.runtime..nupkg. +.PARAMETER OpenSlideUpstreamVersion + Passed to the build, which then sets InformationalVersion (see Directory.Build.props). +.PARAMETER ArtifactsPath + The build's --artifacts-path. Default: artifacts/viewer/. +.PARAMETER ArchiveDirectory + Also archive the publish folder there, as the release download: OpenSlideSharp.Viewer--.zip for + Windows, .tar.gz (the executable with mode 755) otherwise. The executable and licenses/ are at the archive's root. +#> +[CmdletBinding()] +param( + [string]$Rid, + [Parameter(Mandatory)][string]$Version, + [Parameter(Mandatory)][string]$Feed, + [string]$OpenSlideUpstreamVersion, + [string]$ArtifactsPath, + [string]$ArchiveDirectory +) + +$ErrorActionPreference = 'Stop' +Add-Type -AssemblyName System.IO.Compression.FileSystem + +$root = Split-Path -Parent $PSScriptRoot +$fixture = Join-Path $root 'test/OpenSlideSharp.Tests/Fixtures/small.svs' +$manifest = Get-Content (Join-Path $root 'eng/openslide.json') -Raw | ConvertFrom-Json + +function Invoke-Native { + param([string]$Exe, [string[]]$Arguments) + & $Exe @Arguments + if ($LASTEXITCODE -ne 0) { throw "$Exe $($Arguments -join ' ') failed with exit code $LASTEXITCODE" } +} + +# A path relative to the current location, as PowerShell (not the process) sees it. +function Get-FullPath([string]$Path) { $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path) } + +$hostArch = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture +# Picked the way eng/Get-OpenSlide.ps1 picks this machine's binaries. +$hostRid = if ($IsWindows -and $hostArch -eq 'X64') { 'win-x64' } +elseif ($IsLinux -and $hostArch -eq 'X64') { 'linux-x64' } +elseif ($IsLinux -and $hostArch -eq 'Arm64') { 'linux-arm64' } +elseif ($IsMacOS -and $hostArch -eq 'Arm64') { 'osx-arm64' } +elseif ($IsMacOS -and $hostArch -eq 'X64') { 'osx-x64' } +if (-not $Rid) { + if (-not $hostRid) { throw "OpenSlide publishes no binaries for this platform ($hostArch); pass -Rid." } + $Rid = $hostRid +} +# The openslide-bin archive the RID's library comes from. +$binKey = @{ 'win-x64' = 'windows-x64'; 'linux-x64' = 'linux-x86_64'; 'linux-arm64' = 'linux-aarch64'; 'osx-arm64' = 'macos-arm64-x86_64'; 'osx-x64' = 'macos-arm64-x86_64' }[$Rid] +if (-not $binKey) { throw "openslide-bin has no build for '$Rid'. Use win-x64, linux-x64, linux-arm64, osx-arm64 or osx-x64." } + +# Restore resolves a relative source against the project folder, so pass it in full. +$Feed = Get-FullPath $Feed +$runtimeNupkg = Join-Path $Feed "OpenSlideSharp.runtime.$Version.nupkg" +if (-not (Test-Path -PathType Leaf $runtimeNupkg)) { throw "$runtimeNupkg not found: the viewer takes the native OpenSlide library from it." } +$ArtifactsPath = Get-FullPath ($ArtifactsPath ? $ArtifactsPath : (Join-Path $root "artifacts/viewer/$Rid")) +$publish = Join-Path $ArtifactsPath "publish/OpenSlideSharp.Viewer/release_$Rid" +# The folder must hold this publish's files only. +Remove-Item $publish -Recurse -Force -ErrorAction SilentlyContinue + +Write-Host "== viewer: publish $Rid ($Version)" +$publishArgs = @('publish', (Join-Path $root 'samples/OpenSlideSharp.Viewer'), '-c', 'Release', '-r', $Rid, '--self-contained', + '-p:PublishSingleFile=true', '-p:UseOpenSlideRuntimePackage=true', "-p:Version=$Version", "-p:OpenSlideSharpVersion=$Version", + "-p:RestoreAdditionalProjectSources=$Feed", '--artifacts-path', $ArtifactsPath) +if ($OpenSlideUpstreamVersion) { $publishArgs += "-p:OpenSlideUpstreamVersion=$OpenSlideUpstreamVersion" } +Invoke-Native dotnet $publishArgs + +# The publish folder is exactly what a release archives: the executable, with the native libraries inside it, and +# licenses/ with the notices of what it contains. +$exeName = $Rid.StartsWith('win-') ? 'OpenSlideSharp.Viewer.exe' : 'OpenSlideSharp.Viewer' +$published = @(Get-ChildItem $publish -Recurse -File | ForEach-Object { + [pscustomobject]@{ Path = [IO.Path]::GetRelativePath($publish, $_.FullName) -replace '\\', '/'; Length = $_.Length } + }) +$published | ForEach-Object { Write-Host ("published: {0} ({1:N1} KB)" -f $_.Path, ($_.Length / 1KB)) } +$paths = @($published | ForEach-Object Path) +$unexpected = @($paths | Where-Object { $_ -ne $exeName -and -not $_.StartsWith('licenses/') }) +if ($paths -notcontains $exeName -or $unexpected.Count -gt 0) { + throw "[viewer] expected $exeName and licenses/ in $publish, found: $($paths -join ', ')" +} +# The license texts of OpenSlide and of the libraries linked into it, from the runtime package: exactly those of the +# openslide-bin archive this RID's library comes from, and no other platform's. +foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', 'licenses/openslide-bin/openslide-bin.json', + "licenses/openslide-bin/$binKey/VERSIONS.md", "licenses/openslide-bin/$binKey/OpenSlide/COPYING.LESSER") { + if ($paths -notcontains $required) { throw "[viewer] $required is not in $publish" } +} +$zip = [IO.Compression.ZipFile]::OpenRead($runtimeNupkg) +try { $runtimeEntries = @($zip.Entries | ForEach-Object { [Uri]::UnescapeDataString($_.FullName) }) } +finally { $zip.Dispose() } +$wantBinLicenses = @($runtimeEntries | Where-Object { $_ -like "licenses/$binKey/*" } | ForEach-Object { $_.Substring('licenses/'.Length) } | Sort-Object) +$binLicenses = @($paths | Where-Object { $_ -like 'licenses/openslide-bin/*/*' } | ForEach-Object { $_.Substring('licenses/openslide-bin/'.Length) } | Sort-Object) +if (($binLicenses -join "`n") -cne ($wantBinLicenses -join "`n")) { + throw "[viewer] licenses/openslide-bin/ has $($binLicenses.Count) files ($((@($binLicenses | ForEach-Object { ($_ -split '/')[0] } | Sort-Object -Unique)) -join ', ')), expected the runtime nupkg's $($wantBinLicenses.Count) under licenses/$binKey/ only" +} +Write-Host "licenses/openslide-bin/$binKey`: $($binLicenses.Count) license files" +# SOURCE.md is written at publish from openslide-bin.json: the exact build, its source tarball and the release copy. +$sourceMd = Get-Content (Join-Path $publish 'licenses/SOURCE.md') -Raw +foreach ($phrase in $manifest.binVersion, "openslide-bin-$($manifest.binVersion).tar.gz", $manifest.source.sha256, $manifest.source.url, + $manifest.openslideVersion, "https://github.com/IOL0ol1/OpenSlideSharp/releases/tag/v$Version", "openslide-bin/$binKey/", 'OPENSLIDE_LIBRARY_PATH') { + if (-not $sourceMd.Contains("$phrase")) { throw "[viewer] licenses/SOURCE.md does not contain '$phrase'" } +} + +if ($Rid -eq $hostRid) { + # The bundle extracts its native libraries when it starts; a fresh extraction directory shows they came from it. + $extract = Join-Path $ArtifactsPath 'extract' + Remove-Item $extract -Recurse -Force -ErrorAction SilentlyContinue + $env:DOTNET_BUNDLE_EXTRACT_BASE_DIR = $extract + try { + # Piped, so that PowerShell waits for the viewer, a GUI program on Windows, and captures what it prints. + $output = & (Join-Path $publish $exeName) --check $fixture 2>&1 | Out-String + $code = $LASTEXITCODE + } + finally { + Remove-Item Env:DOTNET_BUNDLE_EXTRACT_BASE_DIR -ErrorAction SilentlyContinue + } + Write-Host $output + if ($code -ne 0) { throw "[viewer] --check exited with code $code, expected 0" } + foreach ($line in 'openslide=4.', 'slide=16x16') { + if ($output -notmatch [regex]::Escape($line)) { throw "[viewer] --check output does not contain '$line'" } + } + $extracted = @(Get-ChildItem $extract -Recurse -File | ForEach-Object { $_.Name }) + $extracted | ForEach-Object { Write-Host "extracted: $_" } + foreach ($lib in 'libopenslide-1', 'libSkiaSharp', 'libHarfBuzzSharp') { + if (-not ($extracted | Where-Object { [IO.Path]::GetFileNameWithoutExtension($_) -eq $lib })) { throw "[viewer] $lib is not in the bundle" } + } +} +else { + Write-Host "Not running --check: $Rid is not this machine's runtime identifier ($hostRid)." +} + +if ($ArchiveDirectory) { + $ArchiveDirectory = Get-FullPath $ArchiveDirectory + New-Item -ItemType Directory -Force $ArchiveDirectory | Out-Null + $files = @(Get-ChildItem $publish -Recurse -File | Sort-Object FullName) + $dirs = @(Get-ChildItem $publish -Recurse -Directory | Sort-Object FullName) + function Get-EntryName($Item) { [IO.Path]::GetRelativePath($publish, $Item.FullName) -replace '\\', '/' } + if ($Rid.StartsWith('win-')) { + $archive = Join-Path $ArchiveDirectory "OpenSlideSharp.Viewer-$Version-$Rid.zip" + Remove-Item $archive -Force -ErrorAction SilentlyContinue + $zip = [IO.Compression.ZipFile]::Open($archive, [IO.Compression.ZipArchiveMode]::Create) + try { + foreach ($f in $files) { + $null = [IO.Compression.ZipFileExtensions]::CreateEntryFromFile($zip, $f.FullName, (Get-EntryName $f), [IO.Compression.CompressionLevel]::Optimal) + } + } + finally { $zip.Dispose() } + $zip = [IO.Compression.ZipFile]::OpenRead($archive) + try { $entries = @($zip.Entries | ForEach-Object FullName) } finally { $zip.Dispose() } + } + else { + # Written entry by entry, so the modes are the same from any host: 755 for the executable and the folders, + # 644 for the notices, owned by root. + Add-Type -AssemblyName System.Formats.Tar + $archive = Join-Path $ArchiveDirectory "OpenSlideSharp.Viewer-$Version-$Rid.tar.gz" + $exec = [IO.UnixFileMode]0x1ED # 0755 + $plain = [IO.UnixFileMode]0x1A4 # 0644 + $stream = [IO.File]::Create($archive) + try { + $gzip = [IO.Compression.GZipStream]::new($stream, [IO.Compression.CompressionLevel]::Optimal) + try { + $tar = [Formats.Tar.TarWriter]::new($gzip, [Formats.Tar.TarEntryFormat]::Pax, $false) + try { + foreach ($d in $dirs) { + $entry = [Formats.Tar.PaxTarEntry]::new([Formats.Tar.TarEntryType]::Directory, "$(Get-EntryName $d)/") + $entry.Mode = $exec + $entry.ModificationTime = $d.LastWriteTimeUtc + $tar.WriteEntry($entry) + } + foreach ($f in $files) { + $name = Get-EntryName $f + $entry = [Formats.Tar.PaxTarEntry]::new([Formats.Tar.TarEntryType]::RegularFile, $name) + $entry.Mode = ($name -eq $exeName) ? $exec : $plain + $entry.ModificationTime = $f.LastWriteTimeUtc + $data = [IO.File]::OpenRead($f.FullName) + try { $entry.DataStream = $data; $tar.WriteEntry($entry) } finally { $data.Dispose() } + } + } + finally { $tar.Dispose() } + } + finally { $gzip.Dispose() } + } + finally { $stream.Dispose() } + + # Read it back: the same files, and the executable can be run. + $entries = [Collections.Generic.List[string]]::new() + $stream = [IO.File]::OpenRead($archive) + try { + $gzip = [IO.Compression.GZipStream]::new($stream, [IO.Compression.CompressionMode]::Decompress) + $reader = [Formats.Tar.TarReader]::new($gzip) + try { + while ($null -ne ($entry = $reader.GetNextEntry())) { + if ($entry.EntryType -ne [Formats.Tar.TarEntryType]::RegularFile) { continue } + $entries.Add($entry.Name) + if ($entry.Name -eq $exeName -and -not $entry.Mode.HasFlag([IO.UnixFileMode]::UserExecute)) { throw "[viewer] $exeName has mode $($entry.Mode) in $archive" } + } + } + finally { $reader.Dispose(); $gzip.Dispose() } + } + finally { $stream.Dispose() } + } + $want = @($files | ForEach-Object { Get-EntryName $_ } | Sort-Object) + if ((@($entries | Sort-Object) -join "`n") -cne ($want -join "`n")) { throw "[viewer] $archive does not hold exactly the $($want.Count) files of $publish" } + Write-Host ("archive: {0} ({1:N1} MB, {2} files)" -f $archive, ((Get-Item $archive).Length / 1MB), $entries.Count) +} + +Write-Host "PASS: viewer ($Rid)" diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index c4be9af..b5e974d 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -407,76 +407,12 @@ finally { Remove-Item $toolTemp -Recurse -Force -ErrorAction SilentlyContinue } -# 6. The desktop viewer, published the way its releases will be: self-contained, one executable and its licenses, for -# this machine's RID, with the native OpenSlide library from the runtime package in the feed. --check reads the slide -# without a window. +# 6. The desktop viewer, published the way its releases are (eng/Publish-Viewer.ps1): self-contained, one executable +# and its licenses, for this machine's RID, with the native OpenSlide library from the runtime package in the feed, +# and run with --check, which reads the slide without a window. Write-Host '== smoke: viewer (self-contained single file)' -$hostArch = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture -# Picked the way eng/Get-OpenSlide.ps1 picks this machine's binaries. -$viewerRid = if ($IsWindows -and $hostArch -eq 'X64') { 'win-x64' } -elseif ($IsLinux -and $hostArch -eq 'X64') { 'linux-x64' } -elseif ($IsLinux -and $hostArch -eq 'Arm64') { 'linux-arm64' } -elseif ($IsMacOS -and $hostArch -eq 'Arm64') { 'osx-arm64' } -elseif ($IsMacOS -and $hostArch -eq 'X64') { 'osx-x64' } -else { throw "[viewer] OpenSlide publishes no binaries for this platform ($hostArch)" } -$viewerOut = Join-Path $artifacts 'smoke/viewer' -Invoke-Native dotnet @('publish', (Join-Path $root 'samples/OpenSlideSharp.Viewer'), '-c', 'Release', '-r', $viewerRid, '--self-contained', - '-p:PublishSingleFile=true', '-p:UseOpenSlideRuntimePackage=true', "-p:OpenSlideSharpVersion=$Version", - "-p:RestoreAdditionalProjectSources=$feed", '--artifacts-path', $viewerOut) -$viewerPublish = Join-Path $viewerOut "publish/OpenSlideSharp.Viewer/release_$viewerRid" -$viewerName = $IsWindows ? 'OpenSlideSharp.Viewer.exe' : 'OpenSlideSharp.Viewer' -# The publish folder is exactly what a release archives: the executable, with the native libraries inside it, and -# licenses/ with the notices of what it contains. -$published = @(Get-ChildItem $viewerPublish -Recurse -File | ForEach-Object { - [pscustomobject]@{ Path = [IO.Path]::GetRelativePath($viewerPublish, $_.FullName) -replace '\\', '/'; Length = $_.Length } - }) -$published | ForEach-Object { Write-Host ("published: {0} ({1:N1} KB)" -f $_.Path, ($_.Length / 1KB)) } -$paths = @($published | ForEach-Object Path) -$unexpected = @($paths | Where-Object { $_ -ne $viewerName -and -not $_.StartsWith('licenses/') }) -if ($paths -notcontains $viewerName -or $unexpected.Count -gt 0) { - throw "[viewer] expected $viewerName and licenses/ in $viewerPublish, found: $($paths -join ', ')" -} -# The license texts of OpenSlide and of the libraries linked into it, from the runtime package: exactly those of the -# openslide-bin archive this RID's library comes from, and no other platform's. -$viewerBinKey = @{ 'win-x64' = 'windows-x64'; 'linux-x64' = 'linux-x86_64'; 'linux-arm64' = 'linux-aarch64'; 'osx-arm64' = 'macos-arm64-x86_64'; 'osx-x64' = 'macos-arm64-x86_64' }[$viewerRid] -foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', 'licenses/openslide-bin/openslide-bin.json', - "licenses/openslide-bin/$viewerBinKey/VERSIONS.md", "licenses/openslide-bin/$viewerBinKey/OpenSlide/COPYING.LESSER") { - if ($paths -notcontains $required) { throw "[viewer] $required is not in $viewerPublish" } -} -$binLicenses = @($paths | Where-Object { $_ -like 'licenses/openslide-bin/*/*' } | ForEach-Object { $_.Substring('licenses/openslide-bin/'.Length) } | Sort-Object) -$wantBinLicenses = @($runtimeLicenses | Where-Object { $_ -like "$viewerBinKey/*" }) -if (($binLicenses -join "`n") -cne ($wantBinLicenses -join "`n")) { - throw "[viewer] licenses/openslide-bin/ has $($binLicenses.Count) files ($((@($binLicenses | ForEach-Object { ($_ -split '/')[0] } | Sort-Object -Unique)) -join ', ')), expected the runtime nupkg's $($wantBinLicenses.Count) under licenses/$viewerBinKey/ only" -} -Write-Host "licenses/openslide-bin/$viewerBinKey`: $($binLicenses.Count) license files" -# SOURCE.md is written at publish from openslide-bin.json: the exact build, its source tarball and the release copy. -$sourceMd = Get-Content (Join-Path $viewerPublish 'licenses/SOURCE.md') -Raw -foreach ($phrase in $manifest.binVersion, "openslide-bin-$($manifest.binVersion).tar.gz", $manifest.source.sha256, $manifest.source.url, - $manifest.openslideVersion, "https://github.com/IOL0ol1/OpenSlideSharp/releases/tag/v$Version", "openslide-bin/$viewerBinKey/", 'OPENSLIDE_LIBRARY_PATH') { - if (-not $sourceMd.Contains("$phrase")) { throw "[viewer] licenses/SOURCE.md does not contain '$phrase'" } -} -# The bundle extracts its native libraries when it starts; a fresh extraction directory shows they came from it. -$viewerExtract = Join-Path $viewerOut 'extract' -$env:DOTNET_BUNDLE_EXTRACT_BASE_DIR = $viewerExtract -try { - # Piped, so that PowerShell waits for the viewer, a GUI program on Windows, and captures what it prints. - $output = & (Join-Path $viewerPublish $viewerName) --check $fixture 2>&1 | Out-String - $code = $LASTEXITCODE -} -finally { - Remove-Item Env:DOTNET_BUNDLE_EXTRACT_BASE_DIR -ErrorAction SilentlyContinue -} -Write-Host $output -if ($code -ne 0) { throw "[viewer] --check exited with code $code, expected 0" } -foreach ($line in 'openslide=4.', 'slide=16x16') { - if ($output -notmatch [regex]::Escape($line)) { throw "[viewer] --check output does not contain '$line'" } -} -$extracted = @(Get-ChildItem $viewerExtract -Recurse -File | ForEach-Object { $_.Name }) -$extracted | ForEach-Object { Write-Host "extracted: $_" } -foreach ($lib in 'libopenslide-1', 'libSkiaSharp', 'libHarfBuzzSharp') { - if (-not ($extracted | Where-Object { [IO.Path]::GetFileNameWithoutExtension($_) -eq $lib })) { throw "[viewer] $lib is not in the bundle" } -} -Write-Host "PASS: viewer ($viewerRid)" +& (Join-Path $PSScriptRoot 'Publish-Viewer.ps1') -Version $Version -Feed $feed -OpenSlideUpstreamVersion $OpenSlideUpstreamVersion ` + -ArtifactsPath (Join-Path $artifacts 'smoke/viewer') # 7. Native C++ consumer (Visual Studio vcxproj via packages.config), Windows only. if ($IsWindows) { From 45afb5238ac7e572a2dc0040f535cfea55fe0cf5 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 21:28:50 +0800 Subject: [PATCH 15/38] build: gather a release's files with the openslide-bin source tarball eng/Get-ReleaseFiles.ps1 adds the source tarball of eng/openslide.json to a folder of release files, as openslide-bin-.tar.gz once its sha256 matches the manifest, then fails unless the folder holds exactly the five nupkgs, the three viewer archives and the tarball of the version. It lists them, with sizes and sha256, in the run summary. --- eng/Get-ReleaseFiles.ps1 | 64 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 eng/Get-ReleaseFiles.ps1 diff --git a/eng/Get-ReleaseFiles.ps1 b/eng/Get-ReleaseFiles.ps1 new file mode 100644 index 0000000..7a23666 --- /dev/null +++ b/eng/Get-ReleaseFiles.ps1 @@ -0,0 +1,64 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Completes and checks the files of an OpenSlideSharp GitHub release, gathered in one folder. +.DESCRIPTION + -Path holds the release's nupkgs and viewer archives. This script adds the openslide-bin source tarball of + eng/openslide.json: source.url, saved as openslide-bin-.tar.gz (the name openslide-bin gives it) once + its sha256 is source.sha256. Then -Path must hold exactly the release's files, or the script fails: + OpenSlideSharp, OpenSlideSharp.SkiaSharp, OpenSlideSharp.runtime, OpenSlideSharp.AspNetCore and + OpenSlideSharp.Tool ..nupkg; + OpenSlideSharp.Viewer--win-x64.zip, -linux-x64.tar.gz and -osx-arm64.tar.gz; + openslide-bin-.tar.gz. + Prints a Markdown table of the files with their sizes and sha256, and appends it to $GITHUB_STEP_SUMMARY when set. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][string]$Path, + [Parameter(Mandatory)][string]$Version, + [string]$Manifest +) +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' + +$root = Split-Path -Parent $PSScriptRoot +if (-not $Manifest) { $Manifest = Join-Path $root 'eng/openslide.json' } +$m = Get-Content $Manifest -Raw | ConvertFrom-Json +$Path = (Resolve-Path $Path).Path +function Get-Sha256([string]$File) { (Get-FileHash $File -Algorithm SHA256).Hash.ToLowerInvariant() } + +# The source of the bundled OpenSlide binaries, kept with the release: the openslide-bin URL of a nightly expires. +$sourceName = "openslide-bin-$($m.binVersion).tar.gz" +$sourceSha = "$($m.source.sha256)".ToLowerInvariant() +$source = Join-Path $Path $sourceName +$part = "$source.part" +Remove-Item $source, $part -Force -ErrorAction SilentlyContinue +try { + Write-Host "Downloading $($m.source.url)" + $response = Invoke-WebRequest -Uri $m.source.url -OutFile $part -SkipHttpErrorCheck -PassThru + if ($response.StatusCode -ne 200) { throw "GET $($m.source.url) returned HTTP $($response.StatusCode)." } + $actual = Get-Sha256 $part + if ($actual -ne $sourceSha) { throw "$sourceName has sha256 $actual, but $Manifest pins $sourceSha." } + Move-Item $part $source +} +finally { + Remove-Item $part -Force -ErrorAction SilentlyContinue +} + +$expected = @( + foreach ($id in 'OpenSlideSharp', 'OpenSlideSharp.SkiaSharp', 'OpenSlideSharp.runtime', 'OpenSlideSharp.AspNetCore', 'OpenSlideSharp.Tool') { "$id.$Version.nupkg" } + foreach ($archive in 'win-x64.zip', 'linux-x64.tar.gz', 'osx-arm64.tar.gz') { "OpenSlideSharp.Viewer-$Version-$archive" } + $sourceName +) +$present = @(Get-ChildItem $Path -Force | ForEach-Object Name) +$problems = @($expected | Where-Object { $_ -cnotin $present } | ForEach-Object { "missing: $_" }) + + @($present | Where-Object { $_ -cnotin $expected } | ForEach-Object { "unexpected: $_" }) +if ($problems.Count -gt 0) { throw "$Path does not hold exactly the files of release ${Version}:`n $($problems -join "`n ")" } + +$table = @('| File | Size | sha256 |', '|---|--:|---|') + @($expected | ForEach-Object { + $file = Get-Item -LiteralPath (Join-Path $Path $_) + '| `{0}` | {1:N1} MB | `{2}` |' -f $_, ($file.Length / 1MB), (Get-Sha256 $file.FullName) + }) +$table | ForEach-Object { Write-Host $_ } +if ($env:GITHUB_STEP_SUMMARY) { Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $table -Encoding utf8 } From daad188535d2136ac55290d475aeffe09a51015a Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 21:28:50 +0800 Subject: [PATCH 16/38] ci: test a given ref when called, and lint the workflows ci.yml can be called by another workflow with the ref to test; every job checks that ref out. A new actionlint job lints the workflows with actionlint 1.7.12, downloaded from its release and checked against the sha256 in the release's checksums file. --- .github/workflows/ci.yml | 43 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 762d9ed..a8dc549 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,14 @@ on: branches: [master] pull_request: workflow_dispatch: + # The release and upstream sync workflows test the commit they are about to release or merge. + workflow_call: + inputs: + ref: + description: Branch, tag or commit to test. Empty tests the commit of the calling workflow's event. + type: string + required: false + default: '' permissions: contents: read @@ -24,6 +32,8 @@ jobs: os: [windows-latest, ubuntu-latest, ubuntu-24.04-arm, macos-latest] steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - uses: actions/setup-dotnet@v6 with: global-json-file: global.json @@ -43,6 +53,8 @@ jobs: needs: test steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - uses: actions/setup-dotnet@v6 with: global-json-file: global.json @@ -111,6 +123,8 @@ jobs: timeout-minutes: 30 steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - uses: actions/setup-dotnet@v6 with: global-json-file: global.json @@ -141,6 +155,8 @@ jobs: needs: test steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - uses: actions/setup-dotnet@v6 with: global-json-file: global.json @@ -171,6 +187,8 @@ jobs: os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest] steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - uses: actions/setup-dotnet@v6 with: global-json-file: global.json @@ -189,9 +207,34 @@ jobs: contents: read steps: - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} - name: Self-test the release version script shell: pwsh run: ./eng/Get-ReleaseVersion.ps1 -SelfTest - name: Self-test the upstream update script shell: pwsh run: ./eng/Find-UpstreamUpdate.ps1 -SelfTest + + actionlint: + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref }} + persist-credentials: false + - name: Lint the workflows + env: + ACTIONLINT_VERSION: 1.7.12 + # The sha256 of actionlint_1.7.12_linux_amd64.tar.gz in that release's actionlint_1.7.12_checksums.txt. + ACTIONLINT_SHA256: 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8 + run: | + # actionlint also runs shellcheck, which the runner has, on the bash run: scripts. + archive="actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" + curl -fsSL --retry 3 -o "$RUNNER_TEMP/$archive" "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/$archive" + echo "$ACTIONLINT_SHA256 $RUNNER_TEMP/$archive" | sha256sum --check --strict - + tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" actionlint + "$RUNNER_TEMP/actionlint" -color From dbf9fc0faf3d23a04cee1c3e480672020888a8d9 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 21:28:50 +0800 Subject: [PATCH 17/38] ci: release a commit after CI passes on it release.yml runs on pushes to master that change src/, eng/openslide.json or Directory.*.props, by hand, and from another workflow with a ref. It computes the version of the commit, runs ci.yml on that commit, packs the five packages and publishes the viewer for win-x64, linux-x64 and osx-arm64. With the NUGET_API_KEY secret it then pushes the packages to nuget.org, tags the commit v and creates the GitHub release with the packages, the viewer archives and the openslide-bin source tarball; nightly versions are prereleases. Without the key, with dry_run, or for a commit that is not on master it pushes nothing and lists the release in the run summary. Only the publish job can write to the repository. Running it again is safe: the push skips packages already on nuget.org, and an existing tag or release of the same commit is kept. --- .github/workflows/release.yml | 338 ++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..db15c10 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,338 @@ +name: Release + +# Releases one commit after CI passed on it: the five NuGet packages go to nuget.org, the commit is tagged v +# and a GitHub release gets the packages, the desktop viewer archives and the openslide-bin source tarball. +# Without the NUGET_API_KEY secret, with dry_run, or for a commit that is not on master, it is a dry run: it tests and +# builds everything, pushes nothing (no package, tag or release) and lists what it would release in the run summary. + +on: + push: + branches: [master] + paths: + - 'src/**' + - 'eng/openslide.json' + - 'Directory.*.props' + workflow_dispatch: + inputs: + dry_run: + description: Dry run (build everything, push no package, tag or release) + type: boolean + default: false + workflow_call: + inputs: + ref: + description: Branch, tag or commit to release + type: string + required: true + dry_run: + description: Dry run (build everything, push no package, tag or release) + type: boolean + default: false + secrets: + NUGET_API_KEY: + required: false + +permissions: + contents: read + +concurrency: + group: release + cancel-in-progress: false + +jobs: + version: + runs-on: ubuntu-latest + timeout-minutes: 10 + outputs: + sha: ${{ steps.version.outputs.sha }} + version: ${{ steps.version.outputs.version }} + tag: ${{ steps.version.outputs.tag }} + prerelease: ${{ steps.version.outputs.prerelease }} + informational-version: ${{ steps.version.outputs.informational-version }} + upstream-version: ${{ steps.version.outputs.upstream-version }} + release-name: ${{ steps.version.outputs.release-name }} + notes: ${{ steps.version.outputs.notes }} + dry-run: ${{ steps.mode.outputs.dry-run }} + dry-run-reason: ${{ steps.mode.outputs.reason }} + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ inputs.ref || github.sha }} + # Every branch and tag: the version counts the v* tags, and only commits on master are released. + fetch-depth: 0 + fetch-tags: true + persist-credentials: false + - name: Compute the version + id: version + shell: pwsh + run: | + # Every later job builds, tests and tags this commit, even if the branch moves meanwhile. + $sha = git rev-parse HEAD + if ($LASTEXITCODE -ne 0) { exit 1 } + # Fails if the version is not higher than every version on nuget.org. + $json = pwsh -NoProfile -File ./eng/Get-ReleaseVersion.ps1 + if ($LASTEXITCODE -ne 0) { exit 1 } + $info = ($json -join "`n") | ConvertFrom-Json + if ($info.informationalVersion -cne "$($info.version)+openslide.$($info.openslideUpstreamVersion)") { + throw "informationalVersion '$($info.informationalVersion)' is not the one the build writes for $($info.version) and $($info.openslideUpstreamVersion)." + } + $eof = "EOF_$([Guid]::NewGuid().ToString('N'))" + @( + "sha=$sha" + "version=$($info.version)" + "tag=$($info.tag)" + "prerelease=$($info.prerelease ? 'true' : 'false')" + "informational-version=$($info.informationalVersion)" + "upstream-version=$($info.openslideUpstreamVersion)" + "release-name=$($info.releaseName)" + "notes<<$eof" + $info.notes + $eof + ) | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + Write-Host "OpenSlideSharp $($info.version) ($($info.informationalVersion)) from $sha" + - name: Choose between release and dry run + id: mode + shell: pwsh + env: + # Only checked for being empty, never printed. + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + DRY_RUN: ${{ inputs.dry_run }} + SHA: ${{ steps.version.outputs.sha }} + run: | + $reasons = @() + if ($env:DRY_RUN -eq 'true') { $reasons += 'a dry run was asked for' } + if ([string]::IsNullOrEmpty($env:NUGET_API_KEY)) { $reasons += 'the NUGET_API_KEY secret is not set' } + git merge-base --is-ancestor $env:SHA refs/remotes/origin/master + if ($LASTEXITCODE -eq 1) { $reasons += "commit $env:SHA is not on master" } + elseif ($LASTEXITCODE -ne 0) { throw "git merge-base failed with exit code $LASTEXITCODE." } + if ($reasons.Count -gt 0) { + $reason = $reasons -join '; ' + Write-Host "::notice title=Dry run::Nothing will be pushed to nuget.org, tagged or released: $reason." + "dry-run=true", "reason=$reason" | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + } + else { + Write-Host 'Release: the packages go to nuget.org, the commit is tagged and the GitHub release is created.' + 'dry-run=false' | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + } + exit 0 + + ci: + needs: version + uses: ./.github/workflows/ci.yml + permissions: + contents: read + with: + ref: ${{ needs.version.outputs.sha }} + + pack: + needs: [version, ci] + runs-on: windows-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.version.outputs.sha }} + persist-credentials: false + - uses: actions/setup-dotnet@v6 + with: + global-json-file: global.json + - name: Download and verify the native OpenSlide of every platform + shell: pwsh + run: ./eng/Get-OpenSlide.ps1 -Platform all -Force -Verify + - name: Pack + shell: pwsh + env: + VERSION: ${{ needs.version.outputs.version }} + UPSTREAM_VERSION: ${{ needs.version.outputs.upstream-version }} + run: ./eng/Test-Packages.ps1 -PackOnly -Version $env:VERSION -OpenSlideUpstreamVersion $env:UPSTREAM_VERSION + - uses: actions/upload-artifact@v7 + with: + name: nupkgs + path: artifacts/smoke-feed/*.nupkg + if-no-files-found: error + + viewer: + name: viewer (${{ matrix.rid }}) + needs: [version, pack] + # Cross-published: the SDK signs the macOS executable ad hoc on any host. + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + matrix: + rid: [win-x64, linux-x64, osx-arm64] + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.version.outputs.sha }} + persist-credentials: false + - uses: actions/setup-dotnet@v6 + with: + global-json-file: global.json + - uses: actions/download-artifact@v8 + with: + name: nupkgs + path: artifacts/release-feed + - name: Publish and archive the viewer + shell: pwsh + env: + RID: ${{ matrix.rid }} + VERSION: ${{ needs.version.outputs.version }} + UPSTREAM_VERSION: ${{ needs.version.outputs.upstream-version }} + run: >- + ./eng/Publish-Viewer.ps1 -Rid $env:RID -Version $env:VERSION -OpenSlideUpstreamVersion $env:UPSTREAM_VERSION + -Feed artifacts/release-feed -ArchiveDirectory artifacts/release + - uses: actions/upload-artifact@v7 + with: + name: viewer-${{ matrix.rid }} + path: artifacts/release/OpenSlideSharp.Viewer-* + if-no-files-found: error + + publish: + needs: [version, pack, viewer] + if: needs.version.outputs.dry-run == 'false' + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: write + env: + SHA: ${{ needs.version.outputs.sha }} + VERSION: ${{ needs.version.outputs.version }} + TAG: ${{ needs.version.outputs.tag }} + RELEASE_NAME: ${{ needs.version.outputs.release-name }} + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.version.outputs.sha }} + - uses: actions/setup-dotnet@v6 + with: + global-json-file: global.json + - uses: actions/download-artifact@v8 + with: + name: nupkgs + path: artifacts/release + - uses: actions/download-artifact@v8 + with: + pattern: viewer-* + merge-multiple: true + path: artifacts/release + - name: Add the openslide-bin source tarball and check the release files + shell: pwsh + run: | + '## Release files' | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + ./eng/Get-ReleaseFiles.ps1 -Path artifacts/release -Version $env:VERSION + - name: Check that no higher version was published meanwhile + shell: pwsh + run: | + Import-Module ./eng/NuGetVersion.psm1 + $highest = Get-MaxNuGetVersion (Get-PublishedNuGetVersions) + $order = Compare-NuGetVersion $env:VERSION $highest + if ($order -lt 0) { throw "nuget.org has OpenSlideSharp $highest, higher than $env:VERSION. Run the release again for a new version." } + if ($order -eq 0) { Write-Host "OpenSlideSharp $env:VERSION is on nuget.org already (an earlier attempt pushed it); the push skips what is there." } + else { Write-Host "Highest version on nuget.org: $highest" } + - name: Push the packages to nuget.org + shell: pwsh + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + foreach ($id in 'OpenSlideSharp', 'OpenSlideSharp.SkiaSharp', 'OpenSlideSharp.runtime', 'OpenSlideSharp.AspNetCore', 'OpenSlideSharp.Tool') { + dotnet nuget push "artifacts/release/$id.$env:VERSION.nupkg" --api-key $env:NUGET_API_KEY --source https://api.nuget.org/v3/index.json --skip-duplicate + if ($LASTEXITCODE -ne 0) { throw "Pushing $id $env:VERSION failed with exit code $LASTEXITCODE." } + } + - name: Tag the commit + run: | + set -euo pipefail + # The commit the tag points at, if it exists: the last line is the commit an annotated tag peels to. + existing=$(git ls-remote origin "refs/tags/$TAG" "refs/tags/$TAG^{}" | tail -n 1 | cut -f 1) + if [ -z "$existing" ]; then + git -c user.name=IOL0ol1 -c user.email=1353839731@qq.com tag -a "$TAG" -m "$RELEASE_NAME" "$SHA" + git push origin "refs/tags/$TAG" + elif [ "$existing" = "$SHA" ]; then + echo "$TAG points at $SHA already (an earlier attempt pushed it)." + else + echo "::error::$TAG exists already and points at $existing, not at $SHA." + exit 1 + fi + - name: Create the GitHub release + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + PRERELEASE: ${{ needs.version.outputs.prerelease }} + NOTES: ${{ needs.version.outputs.notes }} + run: | + set -euo pipefail + files=(artifacts/release/*) + if gh release view "$TAG" --json isDraft,assets > "$RUNNER_TEMP/release.json" 2> /dev/null; then + if [ "$(jq -r .isDraft "$RUNNER_TEMP/release.json")" = true ]; then + echo "::error::A draft release of $TAG exists. Delete or publish it, then run this job again." + exit 1 + fi + # An earlier attempt created the release: add the files it lacks. + missing=() + for file in "${files[@]}"; do + if ! jq -e --arg name "$(basename "$file")" 'any(.assets[]; .name == $name)' "$RUNNER_TEMP/release.json" > /dev/null; then + missing+=("$file") + fi + done + if [ ${#missing[@]} -gt 0 ]; then + gh release upload "$TAG" "${missing[@]}" + fi + echo "The release $TAG exists already; uploaded ${#missing[@]} missing file(s)." + else + printf '%s\n' "$NOTES" > "$RUNNER_TEMP/release-notes.md" + prerelease=() + if [ "$PRERELEASE" = true ]; then prerelease=(--prerelease); fi + gh release create "$TAG" "${files[@]}" --verify-tag --target "$SHA" --title "$RELEASE_NAME" \ + --notes-file "$RUNNER_TEMP/release-notes.md" "${prerelease[@]}" + fi + { + echo "## Released $RELEASE_NAME" + echo + echo "- Commit: \`$SHA\`, tagged \`$TAG\`" + echo "- GitHub release: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$TAG" + echo "- nuget.org: https://www.nuget.org/packages/OpenSlideSharp/$VERSION" + } >> "$GITHUB_STEP_SUMMARY" + + dry-run-summary: + needs: [version, pack, viewer] + if: needs.version.outputs.dry-run == 'true' + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.version.outputs.sha }} + persist-credentials: false + - uses: actions/download-artifact@v8 + with: + name: nupkgs + path: artifacts/release + - uses: actions/download-artifact@v8 + with: + pattern: viewer-* + merge-multiple: true + path: artifacts/release + - name: Check the release files and list what the release would be + shell: pwsh + env: + SHA: ${{ needs.version.outputs.sha }} + VERSION: ${{ needs.version.outputs.version }} + TAG: ${{ needs.version.outputs.tag }} + PRERELEASE: ${{ needs.version.outputs.prerelease }} + INFORMATIONAL_VERSION: ${{ needs.version.outputs.informational-version }} + REASON: ${{ needs.version.outputs.dry-run-reason }} + NOTES: ${{ needs.version.outputs.notes }} + run: | + @( + "## Dry run: OpenSlideSharp $env:VERSION" + '' + "Nothing was pushed to nuget.org, tagged or released: $env:REASON." + '' + "- Commit: ``$env:SHA``" + "- Tag: ``$env:TAG``$($env:PRERELEASE -eq 'true' ? ', a prerelease' : '')" + "- InformationalVersion: ``$env:INFORMATIONAL_VERSION``" + '' + '### Release files' + '' + ) | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + ./eng/Get-ReleaseFiles.ps1 -Path artifacts/release -Version $env:VERSION + @('', '### Release notes', '', $env:NOTES) | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 From 69549439c3287bada832f92fb76924cd2f3c8a60 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:10:32 +0800 Subject: [PATCH 18/38] build: take OpenSlideSharp packages only from the local feed when consuming them The tool pack and the viewer publish restored OpenSlideSharp.runtime from the local feed and nuget.org alike, and the OpenSlideSharp* ids are not reserved there, so a package of the same id and version on nuget.org could have put another native library into the tool and the viewer archive. eng/LocalFeed.psm1 writes a NuGet.config that maps OpenSlideSharp* to the local feed only and everything else to nuget.org; the tool pack and the viewer publish restore with it. The smoke project's NuGet.config maps OpenSlideSharp* the same way, and the smoke tool install uses the feed as its only source. After each of these restores, every OpenSlideSharp package it resolved must have the sha512 of the feed's nupkg, or the build fails. --- eng/LocalFeed.psm1 | 72 ++++++++++++++++++++++++++++++++++ eng/Publish-Viewer.ps1 | 10 +++-- eng/Test-Packages.ps1 | 28 +++++++++---- test/PackageSmoke/NuGet.config | 6 +-- 4 files changed, 102 insertions(+), 14 deletions(-) create mode 100644 eng/LocalFeed.psm1 diff --git a/eng/LocalFeed.psm1 b/eng/LocalFeed.psm1 new file mode 100644 index 0000000..8b52b46 --- /dev/null +++ b/eng/LocalFeed.psm1 @@ -0,0 +1,72 @@ +#requires -Version 7 +# Restores that consume OpenSlideSharp packages from a local feed (the tool pack, the viewer publish, the package smoke +# tests) must take them from that feed only. The OpenSlideSharp* ids are not reserved on nuget.org, and NuGet does not say +# which source wins when two have the same id and version, so a package there must never be picked instead. +Set-StrictMode -Version Latest + +function New-LocalFeedConfig { + <# Writes a NuGet.config with the local feed and nuget.org as the only sources, OpenSlideSharp* mapped to the feed + only and everything else to nuget.org. Returns its full path, for -p:RestoreConfigFile. #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$Feed, [Parameter(Mandatory)][string]$Path) + $Feed = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Feed) + $Path = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path) + New-Item -ItemType Directory -Force (Split-Path -Parent $Path) | Out-Null + $text = @" + + + + + + + + + + + + + + + + + + +"@ + Set-Content -Path $Path -Value $text -Encoding utf8NoBOM + $Path +} + +function Get-NupkgSha512 { + <# The base64 SHA-512 of a file, as NuGet records a package's hash in project.assets.json. #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$Path) + $stream = [IO.File]::OpenRead($Path) + try { [Convert]::ToBase64String([Security.Cryptography.SHA512]::HashData($stream)) } finally { $stream.Dispose() } +} + +function Assert-RestoredFromFeed { + <# Fails unless every OpenSlideSharp* package a restore resolved (project.assets.json) is byte for byte the nupkg of the + same id and version in the feed, and the -Require ids are among them. #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$AssetsFile, [Parameter(Mandatory)][string]$Feed, [string[]]$Require = @()) + $assets = Get-Content -Raw $AssetsFile | ConvertFrom-Json -AsHashtable + $checked = @() + foreach ($key in @($assets['libraries'].Keys)) { + $library = $assets['libraries'][$key] + $id, $version = $key -split '/', 2 + if ($library['type'] -ne 'package' -or -not $id.StartsWith('OpenSlideSharp', [StringComparison]::OrdinalIgnoreCase)) { continue } + $nupkg = @(Get-ChildItem -LiteralPath $Feed -File | Where-Object { $_.Name -ieq "$id.$version.nupkg" }) + if ($nupkg.Count -ne 1) { throw "$AssetsFile resolved $id $version, which is not in $Feed." } + $want = Get-NupkgSha512 $nupkg[0].FullName + if ($library['sha512'] -cne $want) { + throw "$AssetsFile resolved $id $version with sha512 $($library['sha512']), but $($nupkg[0].FullName) has ${want}: the package did not come from the local feed." + } + $checked += $id + } + foreach ($id in $Require) { + if ($checked -notcontains $id) { throw "$AssetsFile has no package ${id}: expected it from $Feed." } + } + Write-Host "Restored from $Feed`: $($checked -join ', ')" +} + +Export-ModuleMember -Function New-LocalFeedConfig, Get-NupkgSha512, Assert-RestoredFromFeed diff --git a/eng/Publish-Viewer.ps1 b/eng/Publish-Viewer.ps1 index 49e7f12..b70c7ae 100644 --- a/eng/Publish-Viewer.ps1 +++ b/eng/Publish-Viewer.ps1 @@ -14,7 +14,8 @@ .PARAMETER Rid win-x64, linux-x64, linux-arm64, osx-arm64 or osx-x64. Default: this machine's. .PARAMETER Feed - A folder with OpenSlideSharp.runtime..nupkg. + A folder with OpenSlideSharp.runtime..nupkg. The restore takes OpenSlideSharp* packages from it only, never + from nuget.org, and the publish fails unless the resolved runtime package is that nupkg. .PARAMETER OpenSlideUpstreamVersion Passed to the build, which then sets InformationalVersion (see Directory.Build.props). .PARAMETER ArtifactsPath @@ -35,6 +36,7 @@ param( $ErrorActionPreference = 'Stop' Add-Type -AssemblyName System.IO.Compression.FileSystem +Import-Module (Join-Path $PSScriptRoot 'LocalFeed.psm1') -Force $root = Split-Path -Parent $PSScriptRoot $fixture = Join-Path $root 'test/OpenSlideSharp.Tests/Fixtures/small.svs' @@ -64,7 +66,6 @@ if (-not $Rid) { $binKey = @{ 'win-x64' = 'windows-x64'; 'linux-x64' = 'linux-x86_64'; 'linux-arm64' = 'linux-aarch64'; 'osx-arm64' = 'macos-arm64-x86_64'; 'osx-x64' = 'macos-arm64-x86_64' }[$Rid] if (-not $binKey) { throw "openslide-bin has no build for '$Rid'. Use win-x64, linux-x64, linux-arm64, osx-arm64 or osx-x64." } -# Restore resolves a relative source against the project folder, so pass it in full. $Feed = Get-FullPath $Feed $runtimeNupkg = Join-Path $Feed "OpenSlideSharp.runtime.$Version.nupkg" if (-not (Test-Path -PathType Leaf $runtimeNupkg)) { throw "$runtimeNupkg not found: the viewer takes the native OpenSlide library from it." } @@ -72,13 +73,16 @@ $ArtifactsPath = Get-FullPath ($ArtifactsPath ? $ArtifactsPath : (Join-Path $roo $publish = Join-Path $ArtifactsPath "publish/OpenSlideSharp.Viewer/release_$Rid" # The folder must hold this publish's files only. Remove-Item $publish -Recurse -Force -ErrorAction SilentlyContinue +# OpenSlideSharp.runtime from the feed only, never from nuget.org (see eng/LocalFeed.psm1). +$nugetConfig = New-LocalFeedConfig -Feed $Feed -Path (Join-Path $ArtifactsPath 'NuGet.config') Write-Host "== viewer: publish $Rid ($Version)" $publishArgs = @('publish', (Join-Path $root 'samples/OpenSlideSharp.Viewer'), '-c', 'Release', '-r', $Rid, '--self-contained', '-p:PublishSingleFile=true', '-p:UseOpenSlideRuntimePackage=true', "-p:Version=$Version", "-p:OpenSlideSharpVersion=$Version", - "-p:RestoreAdditionalProjectSources=$Feed", '--artifacts-path', $ArtifactsPath) + "-p:RestoreConfigFile=$nugetConfig", '--artifacts-path', $ArtifactsPath) if ($OpenSlideUpstreamVersion) { $publishArgs += "-p:OpenSlideUpstreamVersion=$OpenSlideUpstreamVersion" } Invoke-Native dotnet $publishArgs +Assert-RestoredFromFeed -AssetsFile (Join-Path $ArtifactsPath 'obj/OpenSlideSharp.Viewer/project.assets.json') -Feed $Feed -Require 'OpenSlideSharp.runtime' # The publish folder is exactly what a release archives: the executable, with the native libraries inside it, and # licenses/ with the notices of what it contains. diff --git a/eng/Test-Packages.ps1 b/eng/Test-Packages.ps1 index b5e974d..337b1bf 100644 --- a/eng/Test-Packages.ps1 +++ b/eng/Test-Packages.ps1 @@ -7,7 +7,9 @@ self-contained as one executable with its licenses for this machine's RID, and a the 32-bit build warning. Packing first checks, with eng/Get-OpenSlide.ps1 -Platform all -Verify, that artifacts/native holds exactly the -binaries and notices eng/openslide.json pins. +binaries and notices eng/openslide.json pins. Every restore of an OpenSlideSharp package (the tool pack, the smoke +builds, the tool install, the viewer) takes it from artifacts/smoke-feed only, never from nuget.org, and is checked to +have got the feed's nupkg. -SkipPack reuses the nupkgs already in artifacts/smoke-feed (CI downloads them there) instead of packing; everything else, including the nupkg content @@ -31,6 +33,7 @@ param( $ErrorActionPreference = 'Stop' if ($SkipPack -and $PackOnly) { throw '-SkipPack and -PackOnly cannot be used together.' } Add-Type -AssemblyName System.IO.Compression.FileSystem +Import-Module (Join-Path $PSScriptRoot 'LocalFeed.psm1') -Force $root = Split-Path -Parent $PSScriptRoot $artifacts = Join-Path $root 'artifacts' @@ -69,12 +72,15 @@ else { } # The tool carries the native library of every RID through OpenSlideSharp.runtime, restored from the feed just - # packed. It restores into the isolated cache, so smoke versions never reach the user's NuGet cache, and builds - # into its own artifacts folder, so the regular build output keeps its own restore. + # packed, and from nowhere else (see eng/LocalFeed.psm1). It restores into the isolated cache, so smoke versions + # never reach the user's NuGet cache, and builds into its own artifacts folder, so the regular build output keeps + # its own restore. $env:NUGET_PACKAGES = $packages + $toolArtifacts = Join-Path $artifacts 'smoke/pack-tool' + $nugetConfig = New-LocalFeedConfig -Feed $feed -Path (Join-Path $toolArtifacts 'NuGet.config') Invoke-Native dotnet (@('pack', (Join-Path $root 'src/OpenSlideSharp.Tool/OpenSlideSharp.Tool.csproj'), '-c', 'Release', '-o', $feed) + - $versionProps + @('-p:UseOpenSlideRuntimePackage=true', "-p:RestoreAdditionalProjectSources=$feed", - '--artifacts-path', (Join-Path $artifacts 'smoke/pack-tool'))) + $versionProps + @('-p:UseOpenSlideRuntimePackage=true', "-p:RestoreConfigFile=$nugetConfig", '--artifacts-path', $toolArtifacts)) + Assert-RestoredFromFeed -AssetsFile (Join-Path $toolArtifacts 'obj/OpenSlideSharp.Tool/project.assets.json') -Feed $feed -Require 'OpenSlideSharp.runtime' } # 2. Assert nupkg contents. @@ -310,7 +316,8 @@ if ($PackOnly) { # 3. Consume the packages from an isolated global cache. $env:NUGET_PACKAGES = $packages -# Builds the smoke project; returns the output folder and the captured build log. +# Builds the smoke project; returns the output folder and the captured build log. Its NuGet.config maps OpenSlideSharp* +# to the feed only; the packages it restored must be the feed's. function Build-Smoke { param([string]$Name, [string]$Tfm, [string[]]$Extra) $out = Join-Path $artifacts "smoke/$Name" @@ -318,6 +325,7 @@ function Build-Smoke { $code = $LASTEXITCODE Write-Host $log if ($code -ne 0) { throw "[$Name] dotnet build failed with exit code $code" } + Assert-RestoredFromFeed -AssetsFile (Join-Path $out 'obj/PackageSmoke/project.assets.json') -Feed $feed -Require 'OpenSlideSharp' return [pscustomobject]@{ Bin = (Join-Path $out "bin/PackageSmoke/release_$Tfm"); Log = $log } } @@ -394,7 +402,13 @@ Write-Host '== smoke: openslide-sharp tool' $toolTemp = Join-Path ($env:RUNNER_TEMP ? $env:RUNNER_TEMP : [IO.Path]::GetTempPath()) ('oss-' + [Guid]::NewGuid().ToString('N').Substring(0, 8)) try { $toolPath = Join-Path $toolTemp 'bin' - Invoke-Native dotnet @('tool', 'install', 'OpenSlideSharp.Tool', '--tool-path', $toolPath, '--add-source', $feed, '--version', $Version) + # From the feed only: a tool package has no dependencies, so the feed is its only source. + Invoke-Native dotnet @('tool', 'install', 'OpenSlideSharp.Tool', '--tool-path', $toolPath, '--source', $feed, '--version', $Version) + $lower = "openslidesharp.tool/$($Version.ToLowerInvariant())" + $installed = Join-Path $toolPath ".store/$lower/$lower/openslidesharp.tool.$($Version.ToLowerInvariant()).nupkg" + if ((Get-NupkgSha512 $installed) -cne (Get-NupkgSha512 (Join-Path $feed "OpenSlideSharp.Tool.$Version.nupkg"))) { + throw "[tool] the installed $installed is not the feed's OpenSlideSharp.Tool.$Version.nupkg" + } $toolExe = Join-Path $toolPath $(if ($IsWindows) { 'openslide-sharp.exe' } else { 'openslide-sharp' }) $toolOut = Join-Path $toolTemp 'small' Invoke-Native $toolExe @('deepzoom', $fixture, '-o', $toolOut) diff --git a/test/PackageSmoke/NuGet.config b/test/PackageSmoke/NuGet.config index 0bb5788..515e0ef 100644 --- a/test/PackageSmoke/NuGet.config +++ b/test/PackageSmoke/NuGet.config @@ -6,12 +6,10 @@ + - - - - + From 18ea4400ac4791e83564a52c90227bde6a89deb0 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:10:33 +0800 Subject: [PATCH 19/38] ci: let ci.yml run twice in one workflow run A called ci.yml uploads its packages artifact into the caller's run, and the upstream sync calls it twice (for the sync branch, then through release.yml), so the second upload failed on the existing name. The calls run one after the other, so the second now replaces the first's packages. --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a8dc549..c7c906f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -175,6 +175,10 @@ jobs: name: packages path: artifacts/smoke-feed/*.nupkg if-no-files-found: error + # A called ci.yml uploads into the caller's run, and the upstream sync calls it twice in one run (for the sync + # branch, then through release.yml). The two calls run one after the other, so the second replaces the first's + # packages before its package-unix jobs download them. + overwrite: true package-unix: name: package-unix (${{ matrix.os }}) From 0cee9bcef67c65b52324c0c550d76299231963d2 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:10:33 +0800 Subject: [PATCH 20/38] ci: refuse to release an old or already released commit Being on master was not enough: re-running an old run with "Re-run all jobs", or running the workflow on a tag or a merged branch, released an older commit under a higher version, and a version already on nuget.org was taken for this release's own earlier attempt. eng/Test-ReleaseCommit.ps1 now fails the version job for a commit that carries a release tag or does not contain the latest one, and, before the publish job pushes anything, for a tag v on another commit or a package of the version on nuget.org, or in the release files, built from another commit (the commit in its nuspec). The workflow's header says to use "Re-run failed jobs" after a failure. --- .github/workflows/release.yml | 19 +++--- eng/Test-ReleaseCommit.ps1 | 124 ++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+), 8 deletions(-) create mode 100644 eng/Test-ReleaseCommit.ps1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index db15c10..bce4549 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,6 +4,10 @@ name: Release # and a GitHub release gets the packages, the desktop viewer archives and the openslide-bin source tarball. # Without the NUGET_API_KEY secret, with dry_run, or for a commit that is not on master, it is a dry run: it tests and # builds everything, pushes nothing (no package, tag or release) and lists what it would release in the run summary. +# It fails for a commit that is released already or older than the latest release (eng/Test-ReleaseCommit.ps1). +# After a failure, use "Re-run failed jobs": it finishes the same release, skipping packages already on nuget.org and +# keeping a tag or release of the same commit. "Re-run all jobs" starts a new release, which fails once the commit is +# tagged and, before that, would give it a new version. on: push: @@ -62,6 +66,9 @@ jobs: fetch-depth: 0 fetch-tags: true persist-credentials: false + - name: Check that the commit is not released and comes after the latest release + shell: pwsh + run: ./eng/Test-ReleaseCommit.ps1 -Sha HEAD - name: Compute the version id: version shell: pwsh @@ -220,15 +227,11 @@ jobs: run: | '## Release files' | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 ./eng/Get-ReleaseFiles.ps1 -Path artifacts/release -Version $env:VERSION - - name: Check that no higher version was published meanwhile + - name: Check that the commit can still be released as this version + # Before anything is pushed: no higher version on nuget.org, and the tag and the packages already there (from + # an earlier attempt of this release) are of this commit. shell: pwsh - run: | - Import-Module ./eng/NuGetVersion.psm1 - $highest = Get-MaxNuGetVersion (Get-PublishedNuGetVersions) - $order = Compare-NuGetVersion $env:VERSION $highest - if ($order -lt 0) { throw "nuget.org has OpenSlideSharp $highest, higher than $env:VERSION. Run the release again for a new version." } - if ($order -eq 0) { Write-Host "OpenSlideSharp $env:VERSION is on nuget.org already (an earlier attempt pushed it); the push skips what is there." } - else { Write-Host "Highest version on nuget.org: $highest" } + run: ./eng/Test-ReleaseCommit.ps1 -Sha $env:SHA -Version $env:VERSION -Path artifacts/release - name: Push the packages to nuget.org shell: pwsh env: diff --git a/eng/Test-ReleaseCommit.ps1 b/eng/Test-ReleaseCommit.ps1 new file mode 100644 index 0000000..1dc3fc1 --- /dev/null +++ b/eng/Test-ReleaseCommit.ps1 @@ -0,0 +1,124 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Checks that a commit may be released, so that nuget.org never gets older code under a newer version, nor one version + built from two commits. Fails with the reason. +.DESCRIPTION + Before building (the release workflow's version job), against the repository's v* tags: + - the commit carries no v* tag: it is released already. A release that stopped half way is finished with "Re-run + failed jobs" on its own run, which does not run this check again. + - the commit of the highest v* tag (in NuGet order) is the commit or one of its ancestors: an older commit would be + released under a higher version than newer code. + With -Version and -Path, before pushing (the publish job), against nuget.org and the origin remote: + - nuget.org has no OpenSlideSharp version above -Version; + - the tag v, if origin has it, points at the commit; + - every package of -Version already on nuget.org, and every nupkg in -Path, was built from the commit (the commit + attribute of the nuspec's repository element), so an earlier attempt of the same release is the only one it joins. +.PARAMETER Sha + The commit: any revision git resolves. +.PARAMETER Repository + The git repository, default this one. Its v* tags must be fetched. +#> +[CmdletBinding(DefaultParameterSetName = 'Build')] +param( + [Parameter(Mandatory)][string]$Sha, + [Parameter(Mandatory, ParameterSetName = 'Publish')][string]$Version, + [Parameter(Mandatory, ParameterSetName = 'Publish')][string]$Path, + [string]$Repository +) +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +Import-Module (Join-Path $PSScriptRoot 'NuGetVersion.psm1') -Force +Add-Type -AssemblyName System.IO.Compression.FileSystem +if (-not $Repository) { $Repository = Split-Path -Parent $PSScriptRoot } + +# The lines git prints (none when it prints nothing). +function Invoke-Git { + $out = & git -C $Repository @args + if ($LASTEXITCODE -ne 0) { throw "git $($args -join ' ') failed with exit code $LASTEXITCODE." } + foreach ($line in @($out)) { if ($null -ne $line) { $line } } +} + +# The commit attribute of a nuspec's element. +function Get-NuspecCommit([string]$Xml, [string]$Where) { + $commitId = ([xml]$Xml.TrimStart([char]0xFEFF)).package.metadata.repository.commit + if (-not $commitId) { throw "$Where has no repository commit in its nuspec." } + $commitId +} + +$commit = Invoke-Git rev-parse --verify "$Sha^{commit}" + +if ($PSCmdlet.ParameterSetName -eq 'Build') { + # Release tags: v. Other v* tags are no releases. + function Select-ReleaseTag { + foreach ($tag in @($input)) { + try { $null = ConvertTo-NuGetVersion $tag.Substring(1); $tag } catch { } + } + } + $own = @(Invoke-Git tag --list 'v*' --points-at $commit | Select-ReleaseTag) + if ($own.Count -gt 0) { + throw "Commit $commit is released already, as $($own -join ', '). To finish a release that stopped half way, use `"Re-run failed jobs`" on its run (`"Re-run all jobs`" starts a new release); a new release needs a new commit." + } + $latest = $null + foreach ($tag in @(Invoke-Git tag --list 'v*' | Select-ReleaseTag)) { + if ($null -eq $latest -or (Compare-NuGetVersion $tag.Substring(1) $latest.Substring(1)) -gt 0) { $latest = $tag } + } + if ($null -eq $latest) { + Write-Host "No release tag yet; commit $commit is not released." + } + else { + $latestCommit = Invoke-Git rev-parse --verify "refs/tags/$latest^{commit}" + & git -C $Repository merge-base --is-ancestor $latestCommit $commit + if ($LASTEXITCODE -eq 1) { + throw "Commit $commit does not contain the latest release, $latest ($latestCommit): releasing it would put older code under a higher version. Release a later commit, such as the head of master." + } + if ($LASTEXITCODE -ne 0) { throw "git merge-base failed with exit code $LASTEXITCODE." } + Write-Host "Commit $commit comes after the latest release, $latest ($latestCommit), and is not released yet." + } +} +else { + $ids = 'OpenSlideSharp', 'OpenSlideSharp.SkiaSharp', 'OpenSlideSharp.runtime', 'OpenSlideSharp.AspNetCore', 'OpenSlideSharp.Tool' + + $highest = Get-MaxNuGetVersion (Get-PublishedNuGetVersions) + if ((Compare-NuGetVersion $Version $highest) -lt 0) { + throw "nuget.org has OpenSlideSharp $highest, higher than $Version. Run the release again for a new version." + } + Write-Host "Highest OpenSlideSharp on nuget.org: $highest" + + $tag = "v$Version" + # The last line is the commit an annotated tag peels to. + $remote = @(Invoke-Git ls-remote origin "refs/tags/$tag" "refs/tags/$tag^{}") + if ($remote.Count -gt 0) { + $target = ($remote[-1] -split "`t")[0] + if ($target -ne $commit) { throw "The tag $tag exists already and points at $target, not at $commit." } + Write-Host "The tag $tag points at $commit already: an earlier attempt of this release pushed it." + } + + foreach ($id in $ids) { + $lowerId = $id.ToLowerInvariant() + $url = "https://api.nuget.org/v3-flatcontainer/$lowerId/$($Version.ToLowerInvariant())/$lowerId.nuspec" + $response = Invoke-WebRequest -Uri $url -SkipHttpErrorCheck -Headers @{ 'User-Agent' = 'OpenSlideSharp-release' } + if ($response.StatusCode -eq 404) { Write-Host "$id $Version is not on nuget.org."; continue } + if ($response.StatusCode -ne 200) { throw "GET $url returned HTTP $($response.StatusCode)." } + $content = $response.Content -is [byte[]] ? [Text.Encoding]::UTF8.GetString($response.Content) : $response.Content + $built = Get-NuspecCommit $content "$id $Version on nuget.org" + if ($built -ne $commit) { + throw "$id $Version is on nuget.org already, built from commit $built, not ${commit}: this commit's packages must not join that version." + } + Write-Host "$id $Version is on nuget.org already, built from ${commit}: an earlier attempt of this release pushed it." + } + + foreach ($id in $ids) { + $nupkg = Join-Path $Path "$id.$Version.nupkg" + $zip = [IO.Compression.ZipFile]::OpenRead($nupkg) + try { + $entry = @($zip.Entries | Where-Object { $_.FullName -notmatch '/' -and $_.FullName -like '*.nuspec' })[0] + $reader = [IO.StreamReader]::new($entry.Open()) + try { $built = Get-NuspecCommit $reader.ReadToEnd() $nupkg } finally { $reader.Dispose() } + } + finally { $zip.Dispose() } + if ($built -ne $commit) { throw "$nupkg was built from commit $built, not $commit." } + } + Write-Host "The five nupkgs in $Path were built from $commit, which may be released as $Version." +} From d35d89b5da22ef8c3a9c71e4bff73ae102dde80b Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:50:44 +0800 Subject: [PATCH 21/38] build: report a failed upstream sync in one issue per openslide-bin build eng/Report-SyncFailure.ps1 opens "Upstream sync failed: openslide-bin " (or "... update check" when the run failed before finding a build), or comments on the open issue of that title, with the run link and each job's result, then deletes the run's sync/ branch. -SelfTest runs it against a mocked GitHub API. --- eng/Report-SyncFailure.ps1 | 312 +++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 eng/Report-SyncFailure.ps1 diff --git a/eng/Report-SyncFailure.ps1 b/eng/Report-SyncFailure.ps1 new file mode 100644 index 0000000..e56d120 --- /dev/null +++ b/eng/Report-SyncFailure.ps1 @@ -0,0 +1,312 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Reports a failed upstream sync: one open issue per openslide-bin build, then deletes the run's sync branch. +.DESCRIPTION + The issue is titled "Upstream sync failed: openslide-bin ", or "Upstream sync failed: openslide-bin update + check" when the run failed before it knew which build to take. If an open issue (not a pull request) has exactly that + title, the failure is added to it as a comment, so a build never gets a second open issue; otherwise a new issue is + opened. Both link the run and list the result of each job. Then, with -Branch, the branch is deleted; a branch that + is gone already is fine, and only sync/* branches are accepted. + Uses the GitHub REST API with $env:GITHUB_TOKEN (issues: write, and contents: write to delete the branch). + -SelfTest runs built-in cases against a mocked API (no network) and exits 1 if one fails. +.PARAMETER Repository + owner/name. +.PARAMETER RunUrl + The workflow run to link. +.PARAMETER Tag + The openslide-bin release tag the run synced; empty if it failed before finding one. +.PARAMETER Jobs + The workflow's needs context as JSON (toJSON(needs)). Each job's result goes into the report, and the merge job's + outputs say whether master was fast-forwarded before the failure. +.PARAMETER Branch + The sync branch this run pushed, to delete, e.g. sync/v4.0.1.2+20261110.nightly. Empty: nothing to delete. +#> +[CmdletBinding()] +param( + [string]$Repository, + [string]$RunUrl, + [string]$Tag, + [string]$Jobs, + [string]$Branch, + [switch]$SelfTest +) +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' + +function Get-SyncFailureTitle([string]$Tag) { + if ($Tag) { "Upstream sync failed: openslide-bin $Tag" } else { 'Upstream sync failed: openslide-bin update check' } +} + +# The report text: what failed, the run, each job's result, and whether master changed. +function Get-SyncFailureBody([string]$Tag, [string]$RunUrl, [string]$Jobs, [bool]$Again) { + $lines = [System.Collections.Generic.List[string]]::new() + if ($Again) { $lines.Add("Failed again: $RunUrl") } + elseif ($Tag) { $lines.Add("The upstream sync of openslide-bin ``$Tag`` failed: $RunUrl") } + else { $lines.Add("The upstream sync failed while looking for a newer openslide-bin build: $RunUrl") } + $needs = $null + if ($Jobs) { try { $needs = $Jobs | ConvertFrom-Json } catch { $needs = $null } } + if ($needs) { + $lines.Add('') + $lines.Add('| Job | Result |') + $lines.Add('|---|---|') + foreach ($p in $needs.PSObject.Properties) { $lines.Add("| $($p.Name) | $($p.Value.result) |") } + } + $lines.Add('') + $merge = if ($needs) { $needs.PSObject.Properties['merge'] } else { $null } + if ($merge -and $merge.Value.outputs -and $merge.Value.outputs.merged -eq 'true') { + $lines.Add("master was fast-forwarded to ``$($merge.Value.outputs.sha)`` before the failure, so the release of that commit did not finish. Use ""Re-run failed jobs"" on the run to finish it.") + } else { + $lines.Add('master is unchanged and nothing was released.') + } + if (-not $Again) { + $lines.Add('') + $lines.Add('Later failures of the same build are added here as comments. The sync tries the build again on its next runs while it is the newest one; close this issue when it passes or a newer build replaces it.') + } + $lines -join "`n" +} + +# The GitHub REST API. Every call returns Status (the HTTP status), Content (the parsed JSON, or $null) and Next (the +# path of the next page from the Link header, or $null). +function New-GitHubApi { + { + param([string]$Method, [string]$Path, $Body) + $headers = @{ Accept = 'application/vnd.github+json'; 'User-Agent' = 'OpenSlideSharp-upstream-sync'; 'X-GitHub-Api-Version' = '2022-11-28' } + if ($env:GITHUB_TOKEN) { $headers.Authorization = "Bearer $($env:GITHUB_TOKEN)" } + $request = @{ Uri = "https://api.github.com/$Path"; Method = $Method; Headers = $headers; SkipHttpErrorCheck = $true } + if ($null -ne $Body) { $request.Body = $Body | ConvertTo-Json -Depth 5; $request.ContentType = 'application/json; charset=utf-8' } + $r = Invoke-WebRequest @request + $next = $null + if ("$($r.Headers['Link'])" -match ']+)>;\s*rel="next"') { $next = $Matches[1] } + $content = if ("$($r.Content)".Trim()) { "$($r.Content)" | ConvertFrom-Json -NoEnumerate } else { $null } + [pscustomobject]@{ Status = [int]$r.StatusCode; Content = $content; Next = $next } + } +} + +function Get-ApiError($Response) { + $message = if ($Response.Content -and $Response.Content.PSObject.Properties['message']) { ": $($Response.Content.message)" } else { '' } + "HTTP $($Response.Status)$message" +} + +# The number of the open issue (not pull request) titled exactly $Title, or $null. Reads every page. +function Find-OpenIssue([scriptblock]$Api, [string]$Repository, [string]$Title) { + $path = "repos/$Repository/issues?state=open&per_page=100" + while ($path) { + $r = & $Api 'GET' $path $null + if ($r.Status -ne 200) { throw "Listing the open issues failed with $(Get-ApiError $r)." } + foreach ($issue in @($r.Content)) { + if ($issue.PSObject.Properties['pull_request'] -and $null -ne $issue.pull_request) { continue } + if ([string]$issue.state -ne 'open') { continue } + if ([string]$issue.title -ceq $Title) { return [int]$issue.number } + } + $path = $r.Next + } + $null +} + +function Invoke-SyncFailureReport { + param([Parameter(Mandatory)][scriptblock]$Api, [Parameter(Mandatory)][string]$Repository, [Parameter(Mandatory)][string]$RunUrl, + [string]$Tag, [string]$Jobs, [string]$Branch) + # Checked before any call, so a bad argument changes nothing. + if ($Repository -notmatch '^[\w.-]+/[\w.-]+$') { throw "Unexpected repository '$Repository'." } + if ($RunUrl -notmatch '^https://\S+$') { throw "Unexpected run URL '$RunUrl'." } + if ($Tag -and $Tag -notmatch '^v[0-9A-Za-z.+-]+$') { throw "Unexpected tag '$Tag'." } + if ($Branch -and $Branch -notmatch '^sync/v[0-9A-Za-z.+-]+$') { throw "Refusing to delete '$Branch': only sync/ branches are deleted." } + + $title = Get-SyncFailureTitle $Tag + $number = Find-OpenIssue $Api $Repository $title + $created = $null -eq $number + if ($created) { + $r = & $Api 'POST' "repos/$Repository/issues" @{ title = $title; body = (Get-SyncFailureBody $Tag $RunUrl $Jobs $false) } + if ($r.Status -ne 201) { throw "Opening the issue '$title' failed with $(Get-ApiError $r)." } + $number = [int]$r.Content.number + $url = [string]$r.Content.html_url + Write-Host "Opened issue #${number}: $title" + } else { + $r = & $Api 'POST' "repos/$Repository/issues/$number/comments" @{ body = (Get-SyncFailureBody $Tag $RunUrl $Jobs $true) } + if ($r.Status -ne 201) { throw "Commenting on issue #$number failed with $(Get-ApiError $r)." } + $url = [string]$r.Content.html_url + Write-Host "Issue #$number is open already for this build; added the run as a comment." + } + + $deleted = $false + if ($Branch) { + $ref = ($Branch -split '/' | ForEach-Object { [uri]::EscapeDataString($_) }) -join '/' + $r = & $Api 'DELETE' "repos/$Repository/git/refs/heads/$ref" $null + if ($r.Status -eq 204) { $deleted = $true; Write-Host "Deleted the branch $Branch." } + elseif ($r.Status -in 404, 422) { Write-Host "The branch $Branch does not exist (anymore)." } + else { throw "Deleting the branch $Branch failed with $(Get-ApiError $r)." } + } + [pscustomobject]@{ Title = $title; Issue = $number; Url = $url; Created = $created; BranchDeleted = $deleted } +} + +if ($SelfTest) { + $results = [System.Collections.Generic.List[object]]::new() + function Test-Case([string]$Name, [scriptblock]$Body) { + try { + # A case must produce exactly one boolean; stray output (e.g. a negative case that did not throw) is a failure. + $out = @(& $Body) + $ok = $out.Count -eq 1 -and $out[0] -is [bool] -and $out[0] + } catch { $ok = $false; $Name += " (threw: $($_.Exception.Message))" } + $results.Add([pscustomobject]@{ Name = $Name; Ok = $ok }) + } + # A fake GitHub API over a list of issues (open and closed) that records every call. Like the real one, it lists + # only open issues when asked for state=open, pages by per_page, and fails with the given statuses. + function New-MockApi { + param([object[]]$Issues = @(), [int]$PageSize = 100, [int]$ListStatus = 200, [int]$CreateStatus = 201, + [int]$CommentStatus = 201, [int]$DeleteStatus = 204) + $calls = [System.Collections.Generic.List[object]]::new() + $api = { + param([string]$Method, [string]$Path, $Body) + $calls.Add([pscustomobject]@{ Method = $Method; Path = $Path; Body = $Body }) + $failure = [pscustomobject]@{ message = 'mock failure' } + if ($Method -eq 'GET' -and $Path -match '^(repos/o/r|repositories/1)/issues\?') { + if ($ListStatus -ne 200) { return [pscustomobject]@{ Status = $ListStatus; Content = $failure; Next = $null } } + $all = @($Issues | Where-Object { $Path -notmatch '(^|[?&])state=open(&|$)' -or $_.state -eq 'open' }) + $page = if ($Path -match '[?&]page=(\d+)') { [int]$Matches[1] } else { 1 } + $items = @($all | Select-Object -Skip (($page - 1) * $PageSize) -First $PageSize) + $next = if ($page * $PageSize -lt $all.Count) { "repositories/1/issues?state=open&per_page=100&page=$($page + 1)" } else { $null } + return [pscustomobject]@{ Status = 200; Content = $items; Next = $next } + } + if ($Method -eq 'POST' -and $Path -eq 'repos/o/r/issues') { + $content = if ($CreateStatus -eq 201) { [pscustomobject]@{ number = 42; html_url = 'https://github.com/o/r/issues/42' } } else { $failure } + return [pscustomobject]@{ Status = $CreateStatus; Content = $content; Next = $null } + } + if ($Method -eq 'POST' -and $Path -match '^repos/o/r/issues/(\d+)/comments$') { + $content = if ($CommentStatus -eq 201) { [pscustomobject]@{ html_url = "https://github.com/o/r/issues/$($Matches[1])#issuecomment-1" } } else { $failure } + return [pscustomobject]@{ Status = $CommentStatus; Content = $content; Next = $null } + } + if ($Method -eq 'DELETE' -and $Path -match '^repos/o/r/git/refs/heads/') { + return [pscustomobject]@{ Status = $DeleteStatus; Content = ($DeleteStatus -eq 204 ? $null : $failure); Next = $null } + } + throw "Unexpected API call $Method $Path" + }.GetNewClosure() + [pscustomobject]@{ Api = $api; Calls = $calls } + } + function New-Issue([int]$Number, [string]$Title, [string]$State = 'open', [switch]$PullRequest) { + $i = [pscustomobject]@{ number = $Number; title = $Title; state = $State } + if ($PullRequest) { $i | Add-Member pull_request ([pscustomobject]@{ url = 'https://api.github.com/repos/o/r/pulls/1' }) } + $i + } + function Report($Mock, [string]$Tag = $tag, [string]$Branch = $branch, [string]$Jobs = $ciFailed) { + Invoke-SyncFailureReport -Api $Mock.Api -Repository 'o/r' -RunUrl $run -Tag $Tag -Jobs $Jobs -Branch $Branch 6> $null + } + function Get-Calls($Mock, [string]$Method, [string]$Pattern) { @($Mock.Calls | Where-Object { $_.Method -eq $Method -and $_.Path -match $Pattern }) } + + $tag = 'v4.0.1.2+20261110.nightly' + $title = "Upstream sync failed: openslide-bin $tag" + $branch = "sync/$tag" + $run = 'https://github.com/o/r/actions/runs/123' + $ciFailed = '{"detect":{"result":"success","outputs":{"tag":"v4.0.1.2+20261110.nightly"}},"update":{"result":"success","outputs":{}},"ci":{"result":"failure","outputs":{}},"merge":{"result":"skipped","outputs":{}},"release":{"result":"skipped","outputs":{}}}' + $releaseFailed = '{"detect":{"result":"success","outputs":{}},"update":{"result":"success","outputs":{}},"ci":{"result":"success","outputs":{}},"merge":{"result":"success","outputs":{"merged":"true","sha":"0123456789abcdef0123456789abcdef01234567"}},"release":{"result":"failure","outputs":{}}}' + + Test-Case 'title names the upstream tag' { (Get-SyncFailureTitle $tag) -ceq 'Upstream sync failed: openslide-bin v4.0.1.2+20261110.nightly' } + Test-Case 'title when the check failed before finding a tag' { (Get-SyncFailureTitle '') -ceq 'Upstream sync failed: openslide-bin update check' } + Test-Case 'no open issue: opens one with the title, the run link and the job results' { + $m = New-MockApi + $r = Report $m + $create = Get-Calls $m 'POST' '^repos/o/r/issues$' + $list = Get-Calls $m 'GET' 'issues\?' + $r.Created -and $r.Issue -eq 42 -and $create.Count -eq 1 -and $create[0].Body.title -ceq $title -and + $create[0].Body.body.Contains($run) -and $create[0].Body.body.Contains('| ci | failure |') -and + $create[0].Body.body.Contains('master is unchanged and nothing was released.') -and + (Get-Calls $m 'POST' 'comments$').Count -eq 0 -and $list.Count -eq 1 -and $list[0].Path -match '[?&]state=open(&|$)' } + Test-Case 'open issue with the same title: comments on it with the run link, opens none' { + $m = New-MockApi -Issues @((New-Issue 3 'Something else'), (New-Issue 7 $title)) + $r = Report $m + $comment = Get-Calls $m 'POST' '^repos/o/r/issues/7/comments$' + -not $r.Created -and $r.Issue -eq 7 -and $comment.Count -eq 1 -and $comment[0].Body.body.Contains($run) -and + $comment[0].Body.body.Contains('| ci | failure |') -and (Get-Calls $m 'POST' '^repos/o/r/issues$').Count -eq 0 } + Test-Case 'a pull request with the same title is not the issue' { + $m = New-MockApi -Issues @(New-Issue 5 $title -PullRequest) + $r = Report $m + $r.Created -and (Get-Calls $m 'POST' 'comments$').Count -eq 0 } + Test-Case 'a closed issue with the same title is not reused' { + $m = New-MockApi -Issues @(New-Issue 4 $title -State closed) + (Report $m).Created } + Test-Case "another build's issue, or a longer title, is not reused" { + $m = New-MockApi -Issues @((New-Issue 8 'Upstream sync failed: openslide-bin v4.0.1.2+20261102.nightly'), + (New-Issue 9 "$title (retry)"), (New-Issue 10 $title.ToUpperInvariant())) + (Report $m).Created } + Test-Case 'finds the issue on a later page, so it is not opened twice' { + $issues = @(1..5 | ForEach-Object { New-Issue $_ "Other $_" }) + @(New-Issue 11 $title) + $m = New-MockApi -Issues $issues -PageSize 2 + $r = Report $m + -not $r.Created -and $r.Issue -eq 11 -and (Get-Calls $m 'GET' 'issues\?').Count -eq 3 -and (Get-Calls $m 'POST' '^repos/o/r/issues$').Count -eq 0 } + Test-Case 'listing fails: throws, opens nothing and keeps the branch' { + $m = New-MockApi -ListStatus 500 + try { $null = Report $m; $false } catch { $_.Exception.Message -match 'HTTP 500' -and (Get-Calls $m 'POST' '.').Count -eq 0 -and (Get-Calls $m 'DELETE' '.').Count -eq 0 } } + Test-Case 'opening the issue fails: throws' { + $m = New-MockApi -CreateStatus 403 + try { $null = Report $m; $false } catch { $_.Exception.Message -match 'HTTP 403' } } + Test-Case 'commenting fails: throws' { + $m = New-MockApi -Issues @(New-Issue 7 $title) -CommentStatus 500 + try { $null = Report $m; $false } catch { $_.Exception.Message -match 'HTTP 500' } } + Test-Case 'deletes the sync branch after reporting, with + escaped in the ref' { + $m = New-MockApi + $r = Report $m + $delete = Get-Calls $m 'DELETE' '.' + $r.BranchDeleted -and $delete.Count -eq 1 -and $delete[0].Path -ceq 'repos/o/r/git/refs/heads/sync/v4.0.1.2%2B20261110.nightly' -and + $m.Calls[$m.Calls.Count - 1].Method -eq 'DELETE' } + Test-Case 'a branch that is gone already is fine' { + $r404 = Report (New-MockApi -DeleteStatus 404) + $r422 = Report (New-MockApi -DeleteStatus 422) + $r404.Created -and -not $r404.BranchDeleted -and $r422.Created -and -not $r422.BranchDeleted } + Test-Case 'deleting the branch fails otherwise: throws after the issue is opened' { + $m = New-MockApi -DeleteStatus 500 + try { $null = Report $m; $false } catch { $_.Exception.Message -match 'HTTP 500' -and (Get-Calls $m 'POST' '^repos/o/r/issues$').Count -eq 1 } } + Test-Case 'no branch given: nothing is deleted' { + $m = New-MockApi + $r = Report $m -Branch '' + $r.Created -and -not $r.BranchDeleted -and (Get-Calls $m 'DELETE' '.').Count -eq 0 } + Test-Case 'refuses to delete a branch outside sync/, before any call' { + $outcomes = foreach ($b in 'master', 'refs/heads/master', 'sync/../master', 'feature/sync/v1.0.0.0') { + $m = New-MockApi + try { $null = Report $m -Branch $b; $false } catch { $_.Exception.Message -match 'Refusing' -and $m.Calls.Count -eq 0 } + } + @($outcomes | Where-Object { $_ -ne $true }).Count -eq 0 } + Test-Case 'the check failed before finding a tag: fixed title, says so, deletes nothing' { + $m = New-MockApi + $r = Report $m -Tag '' -Branch '' -Jobs '{"detect":{"result":"failure","outputs":{}},"update":{"result":"skipped","outputs":{}}}' + $create = Get-Calls $m 'POST' '^repos/o/r/issues$' + $r.Created -and $create[0].Body.title -ceq 'Upstream sync failed: openslide-bin update check' -and + $create[0].Body.body.Contains('while looking for a newer openslide-bin build') -and $create[0].Body.body.Contains('| detect | failure |') -and + (Get-Calls $m 'DELETE' '.').Count -eq 0 } + Test-Case 'the same title is found again when the check fails twice' { + $m = New-MockApi -Issues @(New-Issue 12 'Upstream sync failed: openslide-bin update check') + $r = Report $m -Tag '' -Branch '' + -not $r.Created -and $r.Issue -eq 12 } + Test-Case 'release failed after the fast-forward: the report says master moved to the commit' { + $m = New-MockApi + $null = Report $m -Jobs $releaseFailed + $body = (Get-Calls $m 'POST' '^repos/o/r/issues$')[0].Body.body + $body.Contains('fast-forwarded to `0123456789abcdef0123456789abcdef01234567`') -and $body.Contains('| release | failure |') -and + -not $body.Contains('nothing was released') } + Test-Case 'unreadable job results still give a report' { + $m = New-MockApi + $r = Report $m -Jobs 'not json' + $r.Created -and (Get-Calls $m 'POST' '^repos/o/r/issues$')[0].Body.body.Contains($run) } + Test-Case 'rejects an unexpected tag, before any call' { + $m = New-MockApi + try { $null = Report $m -Tag 'v1; rm -rf /'; $false } catch { $_.Exception.Message -match 'Unexpected tag' -and $m.Calls.Count -eq 0 } } + + foreach ($r in $results) { Write-Host ("{0} {1}" -f ($r.Ok ? 'PASS' : 'FAIL'), $r.Name) } + $failed = @($results | Where-Object { -not $_.Ok }).Count + Write-Host "$($results.Count - $failed) passed, $failed failed" + exit ($failed -gt 0 ? 1 : 0) +} + +try { + if (-not $env:GITHUB_TOKEN) { throw 'GITHUB_TOKEN is not set.' } + $report = Invoke-SyncFailureReport -Api (New-GitHubApi) -Repository $Repository -RunUrl $RunUrl -Tag $Tag -Jobs $Jobs -Branch $Branch + if ($env:GITHUB_STEP_SUMMARY) { + $issueLine = $report.Created ? "Opened [#$($report.Issue)]($($report.Url)): $($report.Title)" : "Added this run to the open issue [#$($report.Issue)]($($report.Url)): $($report.Title)" + $lines = @('## Upstream sync failed', '', $issueLine) + if ($Branch) { $lines += '', ($report.BranchDeleted ? "Deleted the branch ``$Branch``." : "The branch ``$Branch`` did not exist.") } + $lines | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + } +} catch { + [Console]::Error.WriteLine("Report-SyncFailure: $($_.Exception.Message)") + exit 1 +} From f31a6a9f666579790422af408c990ed359268677 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:50:44 +0800 Subject: [PATCH 22/38] ci: self-test the upstream sync failure report --- .github/workflows/ci.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c7c906f..2b96670 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -219,6 +219,9 @@ jobs: - name: Self-test the upstream update script shell: pwsh run: ./eng/Find-UpstreamUpdate.ps1 -SelfTest + - name: Self-test the upstream sync failure report + shell: pwsh + run: ./eng/Report-SyncFailure.ps1 -SelfTest actionlint: runs-on: ubuntu-latest From 2c8402ea728a25a3a9b44d497825bbf3a38f4a89 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:50:45 +0800 Subject: [PATCH 23/38] ci: sync newer openslide-bin builds daily upstream-sync.yml takes the next newer openslide-bin build: it commits the manifest and the regenerated bindings on sync/, tests the commit with ci.yml, fast-forwards master to it (or opens a pull request when master moved) and releases it with release.yml. A failure changes nothing on master and is reported once per build. A dry run commits in the runner only and shows the diff in the run summary. --- .github/workflows/upstream-sync.yml | 328 ++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 .github/workflows/upstream-sync.yml diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml new file mode 100644 index 0000000..c7a8727 --- /dev/null +++ b/.github/workflows/upstream-sync.yml @@ -0,0 +1,328 @@ +name: Upstream sync + +# Once a day, takes the next newer openslide-bin build (eng/Find-UpstreamUpdate.ps1): one build per run, a release +# before a nightly; any further one waits for the next run. +# detect lists the newer builds. None: the run ends here. +# update commits eng/openslide.json and the regenerated bindings on sync/ and pushes the branch, +# replacing one an earlier run left. +# ci tests that commit (ci.yml). +# merge fast-forwards master to it and deletes the branch. If master moved meanwhile, or cannot be +# updated, it opens a pull request from the branch instead, keeps the branch and nothing is released. +# release releases the merged commit (release.yml: a dry run while the NUGET_API_KEY secret is not set). +# report-failure after a failure: opens one issue per build, or comments on the open one, and deletes the branch +# (eng/Report-SyncFailure.ps1). Nothing reaches master before ci passed on the commit. +# Pushes made with the workflow token start no other workflow, which is why this one calls ci.yml and release.yml. +# A dry run (the dry_run input, or a run on a branch other than master) runs detect and update only: update commits +# locally, pushes nothing and shows the diff in the run summary. + +on: + schedule: + - cron: '17 3 * * *' + workflow_dispatch: + inputs: + dry_run: + description: Dry run (find and commit the update, push nothing) + type: boolean + default: false + +permissions: + contents: read + +# A fixed group. ci.yml's group, ${{ github.workflow }}-${{ github.ref }}, takes this workflow's name and ref when it is +# called from here; a group equal to it would make the call wait for this run to end. +concurrency: upstream-sync + +jobs: + detect: + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + outputs: + dry-run: ${{ steps.mode.outputs.dry-run }} + channel: ${{ steps.find.outputs.channel }} + tag: ${{ steps.find.outputs.tag }} + bin-version: ${{ steps.find.outputs.bin-version }} + version: ${{ steps.find.outputs.version }} + branch: ${{ steps.find.outputs.branch }} + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - name: Choose between sync and dry run + id: mode + shell: pwsh + env: + DRY_RUN: ${{ inputs.dry_run }} + run: | + $reasons = @() + if ($env:DRY_RUN -eq 'true') { $reasons += 'a dry run was asked for' } + if ($env:GITHUB_REF -ne 'refs/heads/master') { $reasons += "the run is on $env:GITHUB_REF, not on master" } + if ($reasons.Count -gt 0) { + Write-Host "::notice title=Dry run::The update is committed in the runner only; nothing is pushed, merged or released: $($reasons -join '; ')." + 'dry-run=true' | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + } + else { + 'dry-run=false' | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + } + - name: Look for a newer openslide-bin build + id: find + shell: pwsh + env: + GITHUB_TOKEN: ${{ github.token }} + run: | + # Lowest NuGet version first, [] when there is none. Fails when GitHub or nuget.org cannot be read. + $json = pwsh -NoProfile -File ./eng/Find-UpstreamUpdate.ps1 + if ($LASTEXITCODE -ne 0) { exit 1 } + $candidates = @(($json -join "`n") | ConvertFrom-Json) + $pinned = (Get-Content -Raw eng/openslide.json | ConvertFrom-Json).binVersion + if ($candidates.Count -eq 0) { + Write-Host "No newer openslide-bin build: eng/openslide.json pins $pinned." + "No newer openslide-bin build: ``eng/openslide.json`` pins ``$pinned``." | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + exit 0 + } + $c = $candidates[0] + # The tag names a branch and an issue: only the forms eng/Find-UpstreamUpdate.ps1 produces are accepted. + $known = ($c.channel -ceq 'stable' -and $c.tag -cmatch '^v\d+(\.\d+){2,3}$') -or + ($c.channel -ceq 'nightly' -and $c.tag -cmatch '^v\d+(\.\d+){2,3}\+\d{8}\.nightly$') + if (-not $known -or $c.binVersion -cne $c.tag.Substring(1) -or $c.version -cnotmatch '^\d+(\.\d+){2,3}(-[0-9A-Za-z.]+)?$') { + throw "Unexpected candidate: $($c | ConvertTo-Json -Compress)" + } + @( + "channel=$($c.channel)" + "tag=$($c.tag)" + "bin-version=$($c.binVersion)" + "version=$($c.version)" + "branch=sync/$($c.tag)" + ) | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + Write-Host "Syncing openslide-bin $($c.tag) ($($c.channel)), NuGet version $($c.version); eng/openslide.json pins $pinned." + @( + "## Newer openslide-bin builds" + '' + "``eng/openslide.json`` pins ``$pinned``. One build is synced per run, in this order:" + '' + '| Channel | Tag | NuGet version |' + '|---|---|---|' + ($candidates | ForEach-Object { "| $($_.channel) | ``$($_.tag)`` | ``$($_.version)`` |" }) + '' + "This run syncs ``$($c.tag)``." + ) | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + + update: + needs: detect + if: needs.detect.outputs.tag != '' + # Windows, like ci.yml's bindings job, which checks the generated bindings. + runs-on: windows-latest + timeout-minutes: 30 + permissions: + contents: write + outputs: + sha: ${{ steps.commit.outputs.sha }} + base: ${{ steps.commit.outputs.base }} + env: + CHANNEL: ${{ needs.detect.outputs.channel }} + TAG: ${{ needs.detect.outputs.tag }} + BIN_VERSION: ${{ needs.detect.outputs.bin-version }} + BRANCH: ${{ needs.detect.outputs.branch }} + steps: + - uses: actions/checkout@v7 + with: + # Only the push step gets the token; the steps before it run downloaded tools. + persist-credentials: false + - uses: actions/setup-dotnet@v6 + with: + global-json-file: global.json + - name: Pin the upstream build in eng/openslide.json + shell: pwsh + env: + GITHUB_TOKEN: ${{ github.token }} + run: ./eng/Update-OpenSlideManifest.ps1 -Channel $env:CHANNEL -Tag $env:TAG + - name: Stage native OpenSlide + shell: pwsh + run: ./eng/Get-OpenSlide.ps1 -Platform current + - name: Generate bindings + shell: pwsh + run: ./eng/Generate-Bindings.ps1 + - name: Commit the update on the sync branch + id: commit + shell: pwsh + env: + DRY_RUN: ${{ needs.detect.outputs.dry-run }} + run: | + function Invoke-Git { + $out = & git @args + if ($LASTEXITCODE -ne 0) { throw "git $($args -join ' ') failed with exit code $LASTEXITCODE." } + $out + } + $manifest = Get-Content -Raw eng/openslide.json | ConvertFrom-Json + if ($manifest.channel -cne $env:CHANNEL -or $manifest.binVersion -cne $env:BIN_VERSION) { + throw "eng/openslide.json pins $($manifest.channel) $($manifest.binVersion), not $env:CHANNEL $env:BIN_VERSION." + } + # Only the manifest and the generated bindings may change. git diff compares content, so a file that only + # got other line endings on this CRLF checkout does not count. + $changed = @(Invoke-Git diff --name-only) + @(Invoke-Git ls-files --others --exclude-standard) + $unexpected = @($changed | Where-Object { $_ -cne 'eng/openslide.json' -and -not $_.StartsWith('src/OpenSlideSharp/Native/', [StringComparison]::Ordinal) }) + if ($unexpected.Count -gt 0) { throw "The update changed more than the manifest and the bindings: $($unexpected -join ', ')" } + if ('eng/openslide.json' -cnotin $changed) { throw 'eng/openslide.json did not change.' } + $base = Invoke-Git rev-parse HEAD + Invoke-Git switch --quiet --create $env:BRANCH + Invoke-Git add -- eng/openslide.json src/OpenSlideSharp/Native + Invoke-Git -c user.name=IOL0ol1 -c user.email=1353839731@qq.com commit --quiet -m "build: track openslide-bin $env:BIN_VERSION" + $sha = Invoke-Git rev-parse HEAD + "base=$base", "sha=$sha" | Add-Content -Path $env:GITHUB_OUTPUT -Encoding utf8 + $bindings = @(Invoke-Git --no-pager diff --stat HEAD~1 HEAD -- src/OpenSlideSharp/Native) + @( + "## openslide-bin $env:BIN_VERSION" + '' + "Committed ``$sha`` (build: track openslide-bin $env:BIN_VERSION) on ``$env:BRANCH``, on top of ``$base``$($env:DRY_RUN -eq 'true' ? '. Dry run: not pushed.' : '.')" + '' + '### eng/openslide.json' + '' + '```diff' + (Invoke-Git --no-pager diff HEAD~1 HEAD -- eng/openslide.json) + '```' + '' + '### Generated bindings' + '' + ($bindings.Count -gt 0 ? @('```text', $bindings, '```') : 'Unchanged.') + ) | Add-Content -Path $env:GITHUB_STEP_SUMMARY -Encoding utf8 + Write-Host "Committed $sha on $env:BRANCH." + - name: Push the sync branch + if: needs.detect.outputs.dry-run == 'false' + shell: pwsh + env: + GITHUB_TOKEN: ${{ github.token }} + run: | + $auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("x-access-token:$env:GITHUB_TOKEN")) + Write-Host "::add-mask::$auth" + # --force replaces a sync/ that an earlier run left. + git -c "http.$env:GITHUB_SERVER_URL/.extraheader=AUTHORIZATION: basic $auth" push --force origin "HEAD:refs/heads/$env:BRANCH" + if ($LASTEXITCODE -ne 0) { throw "Pushing $env:BRANCH failed with exit code $LASTEXITCODE." } + + ci: + needs: [detect, update] + if: needs.detect.outputs.dry-run == 'false' + uses: ./.github/workflows/ci.yml + permissions: + contents: read + with: + # The commit update pushed to sync/: merge fast-forwards master to exactly this commit. + ref: ${{ needs.update.outputs.sha }} + + merge: + needs: [detect, update, ci] + if: needs.detect.outputs.dry-run == 'false' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + pull-requests: write + outputs: + merged: ${{ steps.merge.outputs.merged }} + sha: ${{ steps.merge.outputs.sha }} + pr-url: ${{ steps.merge.outputs.pr-url }} + steps: + - name: Fast-forward master to the sync commit, or open a pull request + id: merge + env: + GH_TOKEN: ${{ github.token }} + SHA: ${{ needs.update.outputs.sha }} + BASE: ${{ needs.update.outputs.base }} + BRANCH: ${{ needs.detect.outputs.branch }} + TAG: ${{ needs.detect.outputs.tag }} + BIN_VERSION: ${{ needs.detect.outputs.bin-version }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + set -euo pipefail + repo="repos/$GITHUB_REPOSITORY" + master=$(gh api "$repo/git/ref/heads/master" --jq .object.sha) + # Only while master is still the commit the sync started from. With force=false the API also refuses any + # update that is not a fast-forward, so a master that moved after this check stays as it is. + if [ "$master" = "$BASE" ] && gh api --method PATCH "$repo/git/refs/heads/master" -f sha="$SHA" -F force=false --silent; then + { + echo "merged=true" + echo "sha=$SHA" + } >> "$GITHUB_OUTPUT" + echo "master is now $SHA (openslide-bin $BIN_VERSION)." + # master has the commit: a failure to delete the branch must not hold back the release. + if gh api --method DELETE "$repo/git/refs/heads/${BRANCH//+/%2B}" --silent; then + deleted="\`$BRANCH\` is deleted." + else + echo "::warning title=Sync branch kept::Deleting $BRANCH failed; delete it by hand." + deleted="Deleting \`$BRANCH\` failed; delete it by hand." + fi + { + echo "## Merged openslide-bin $BIN_VERSION" + echo + echo "master was fast-forwarded to \`$SHA\`. $deleted" + } >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + if [ "$master" != "$BASE" ]; then + reason="master moved from $BASE to $master while the sync ran" + else + reason="master could not be fast-forwarded (see the log of $RUN_URL)" + fi + # A pull request from the branch, unless one is open already (from an earlier run of the same build). + url=$(gh api --method GET "$repo/pulls" -f state=open -f base=master -f head="$GITHUB_REPOSITORY_OWNER:$BRANCH" --jq '.[0].html_url // empty') + if [ -z "$url" ]; then + body=$(printf '%s\n' \ + "openslide-bin \`$TAG\` passed CI on $SHA in $RUN_URL, but $reason, so it was not merged and nothing was released." \ + "" \ + "Merging this pull request starts the Release workflow, which tests the merged commit again before it publishes.") + url=$(gh api --method POST "$repo/pulls" -f base=master -f head="$BRANCH" -f title="build: track openslide-bin $BIN_VERSION" -f body="$body" --jq .html_url) + fi + { + echo "merged=false" + echo "pr-url=$url" + } >> "$GITHUB_OUTPUT" + echo "::notice title=Pull request instead of a fast-forward::$reason. openslide-bin $BIN_VERSION waits in $url; nothing is released." + { + echo "## openslide-bin $BIN_VERSION waits in a pull request" + echo + echo "Not merged: $reason. The update waits in $url, and nothing was released." + } >> "$GITHUB_STEP_SUMMARY" + + release: + needs: merge + if: needs.merge.outputs.merged == 'true' + uses: ./.github/workflows/release.yml + # release.yml's publish job asks for contents: write (tag and release). GitHub checks a called workflow's + # permissions when the run starts, whether that job runs or not, so this is needed for its dry runs too. + # release.yml runs in the "release" concurrency group, where only one run waits: if another release is queued + # while this call waits, GitHub cancels this call. It then ends "cancelled", which is no failure, so report-failure + # does not run. master has the commit, so a later release includes it; run the Release workflow on master to + # release it at once. + permissions: + contents: write + with: + ref: ${{ needs.merge.outputs.sha }} + secrets: inherit + + report-failure: + needs: [detect, update, ci, merge, release] + # The same choice as detect's dry-run output, made without it so that a failed detect is reported too. A + # cancelled run is no failure and reports nothing; a sync/ branch it leaves is replaced by the next run. + if: failure() && !inputs.dry_run && github.ref == 'refs/heads/master' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + # contents: delete the sync branch. + contents: write + issues: write + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - name: Open or update the issue of this build, and delete the sync branch + shell: pwsh + env: + GITHUB_TOKEN: ${{ github.token }} + TAG: ${{ needs.detect.outputs.tag }} + NEEDS: ${{ toJSON(needs) }} + # The branch this run pushed, unless the merge job opened a pull request from it. + BRANCH: ${{ needs.update.result == 'success' && !needs.merge.outputs.pr-url && needs.detect.outputs.branch || '' }} + run: >- + ./eng/Report-SyncFailure.ps1 -Repository $env:GITHUB_REPOSITORY + -RunUrl "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID" + -Tag $env:TAG -Jobs $env:NEEDS -Branch $env:BRANCH From e2f441c2e7ff0fd0a54e531477bc2dc07e2d8653 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:50:45 +0800 Subject: [PATCH 24/38] docs: describe the automatic releases and list the old packages --- README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 98b590c..1ad7eab 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,15 @@ Package versions map to the openslide-bin builds listed on `. If `master` moved during the run, the update comes as a pull request instead. +- A push to `master` that changes `src/**`, `eng/openslide.json` or `Directory.*.props` releases that commit. +- Other changes, such as to the viewer sample or the `eng/` scripts, are released by running the Release workflow by hand. + +A release tests the commit on all platforms, pushes the five packages to nuget.org, tags the commit `v` and creates a GitHub release with the packages, the viewer archives and the openslide-bin source tarball. Without the `NUGET_API_KEY` secret it is a dry run: it builds and checks everything, publishes nothing and lists what it would release in the run summary. ## Install @@ -154,6 +162,21 @@ pwsh eng/Get-OpenSlide.ps1 # download the native OpenSlide pinned in eng/open dotnet test OpenSlideSharp.slnx ``` +## Old packages + +These 1.x packages end at the version shown and are not updated anymore. Use the replacement instead. + +| Package | Last version | Replacement | +|---|---|---| +| `OpenSlideSharp.Interop` | 1.0.445.17 | `OpenSlideSharp`; the generated bindings are in its `OpenSlideSharp.Native` namespace | +| `OpenSlideSharp.Windows` | 1.1.2 | `OpenSlideSharp` and `OpenSlideSharp.runtime` | +| `OpenSlideSharp.runtime.win` | 1.1.2 | `OpenSlideSharp.runtime` | +| `OpenSlideSharp.BitmapExtensions` | 1.1.2 | `OpenSlideSharp.SkiaSharp` | +| `OpenSlideSharp.OpenCVExtensions` | 1.1.2 | None; `PixelImage.Data` holds the BGRA pixels | +| `OpenSlideSharp.BruTile` | 1.1.2 | None | + +`OpenSlideSharp` itself goes on from 1.1.2 to 4.x, with a new API. + ## License The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. The corresponding source is the openslide-bin source tarball named in the package's `openslide-bin.json`; each [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) attaches a copy for its version. `OpenSlideSharp.Tool` states its terms in its own `LICENSE.txt`, and the viewer in `licenses/` next to its executable. From 235bfd75e80301f398404f0e6481c791d9e00518 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 22:50:46 +0800 Subject: [PATCH 25/38] docs: say how to run the released viewer, and that native PackageReference is untested --- samples/OpenSlideSharp.Viewer/README.md | 21 ++++++++++++++++++++- src/OpenSlideSharp.runtime/README.md | 4 ++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/samples/OpenSlideSharp.Viewer/README.md b/samples/OpenSlideSharp.Viewer/README.md index 96ed651..16a19a7 100644 --- a/samples/OpenSlideSharp.Viewer/README.md +++ b/samples/OpenSlideSharp.Viewer/README.md @@ -9,6 +9,25 @@ dotnet run -c Release --project samples/OpenSlideSharp.Viewer -- /path/to/slide. Open a slide from the command line, with File → Open, or by dropping it on the window. A file that cannot be opened is reported in the status bar, and the slide shown stays. +## Download + +Each [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) has the viewer for three platforms: + +| Platform | Archive | +|---|---| +| Windows x64 | `OpenSlideSharp.Viewer--win-x64.zip` | +| Linux x64 | `OpenSlideSharp.Viewer--linux-x64.tar.gz` | +| macOS on Apple silicon | `OpenSlideSharp.Viewer--osx-arm64.tar.gz` | + +An archive holds the self-contained executable (`OpenSlideSharp.Viewer.exe` on Windows, `OpenSlideSharp.Viewer` on Linux and macOS), which runs without .NET installed, and `licenses/`, at its root. Extract it into a folder of its own and start the executable. + +The macOS executable is signed ad hoc only: it has no Developer ID signature and is not notarized. If macOS blocks a downloaded copy, remove its quarantine attribute and start it again: + +```sh +xattr -d com.apple.quarantine OpenSlideSharp.Viewer +./OpenSlideSharp.Viewer +``` + ## Features - Pan and zoom; tiles are read in the background, and coarser levels show until the finer ones arrive. @@ -54,7 +73,7 @@ The native libraries are inside the executable. It extracts them on first start ## Licenses -`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, under `openslide-bin//` for the openslide-bin build of the publish's platform, with their versions in its `VERSIONS.md`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them. `SOURCE.md`, written at publish time from `openslide-bin/openslide-bin.json`, names the exact openslide-bin build and its source tarball (file name, sha256, the openslide-bin download URL, and the copy attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the same version), and says how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The planned GitHub release builds will ship this publish folder, executable and `licenses/`, as one archive per platform. +`licenses/` holds the license and notice files of what the executable contains: OpenSlide and the libraries linked into it (LGPL-2.1 and others, under `openslide-bin//` for the openslide-bin build of the publish's platform, with their versions in its `VERSIONS.md`), SkiaSharp, HarfBuzzSharp, ANGLE, Avalonia, the .NET runtime and the Inter font. `THIRD-PARTY-NOTICES.txt` lists them. `SOURCE.md`, written at publish time from `openslide-bin/openslide-bin.json`, names the exact openslide-bin build and its source tarball (file name, sha256, the openslide-bin download URL, and the copy attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the same version), and says how to run the viewer with another OpenSlide build (`OPENSLIDE_LIBRARY_PATH`). Keep the folder with the executable. The release archives (see [Download](#download)) are this publish folder: the executable and `licenses/`. ## Known issue on Windows diff --git a/src/OpenSlideSharp.runtime/README.md b/src/OpenSlideSharp.runtime/README.md index e0a7238..e841dc7 100644 --- a/src/OpenSlideSharp.runtime/README.md +++ b/src/OpenSlideSharp.runtime/README.md @@ -10,6 +10,10 @@ Reference this package next to `OpenSlideSharp`; the native library is then copi OpenSlide ships Windows binaries for x64 only, so a .NET Framework app must run as a 64-bit process. Use `PlatformTarget` `x64`, or `AnyCPU` without `Prefer32Bit` (the SDK-style project default). An exe built as `x86`, or as `AnyCPU` with `Prefer32Bit` set to `true`, gets build warning `OPENSLIDE001` and cannot load the library at run time. +## Visual Studio C++ + +A C++ project (`vcxproj`) that installs the package with `packages.config` imports `build/native/OpenSlideSharp.runtime.targets`. For the `x64` platform it adds the OpenSlide headers and the `libopenslide.lib` import library, and copies `libopenslide-1.dll` to the output directory; other platforms fail the build with an error, as OpenSlide ships Windows binaries for x64 only. Native `PackageReference` in C++ projects (Visual Studio 2026 18.7 and later) is untested. + ## Licensing The native libraries are builds of OpenSlide (LGPL-2.1) from openslide-bin. Each platform's library statically links further components, each under its own license. `LICENSE.txt` in the package states the terms. `licenses//` (`windows-x64`, `linux-x86_64`, `linux-aarch64`, `macos-arm64-x86_64`) holds the full license texts of that platform's components and `VERSIONS.md` with their versions. `openslide-bin.json` names the openslide-bin build and its source tarball (URL and sha256), which is the corresponding source. The same file, `openslide-bin-.tar.gz`, is attached to the [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) of the package's version (tag `v`), which keeps it after a nightly openslide-bin build is removed; check it against that sha256. From 7b22d9a5c6533152369f3772cfa6bc48e1e48966 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:37:17 +0800 Subject: [PATCH 26/38] fix: refuse deepzoom tiles too large for an array before touching the old output With -s/-e large enough that a tile, or the slide region read for it, needs more bytes than a .NET array can hold, GetTile failed only after the old output had been moved aside and deleted, naming a 'level' parameter the user never gave. Check the largest tiles of every image first and exit with 2, naming -s and -e. A tile size larger than a small slide still works. --- src/OpenSlideSharp.Tool/DeepZoomCommand.cs | 64 ++++++++++ src/OpenSlideSharp.Tool/README.md | 1 + .../OutputSafetyTests.cs | 114 ++++++++++++++++++ 3 files changed, 179 insertions(+) diff --git a/src/OpenSlideSharp.Tool/DeepZoomCommand.cs b/src/OpenSlideSharp.Tool/DeepZoomCommand.cs index 130ba79..0d48590 100644 --- a/src/OpenSlideSharp.Tool/DeepZoomCommand.cs +++ b/src/OpenSlideSharp.Tool/DeepZoomCommand.cs @@ -69,6 +69,12 @@ internal static async Task RunAsync(DeepZoomArguments args, TextWriter stde { try { + if (CheckTileSizes(slide, args) is { } tooLarge) + { + stderr.WriteLine($"openslide-sharp: {tooLarge}"); + return ExportSupport.InvalidArguments; + } + await ExportAsync(slide, args, stderr, ct).ConfigureAwait(false); return ExportSupport.Success; } @@ -105,6 +111,64 @@ internal static async Task RunAsync(DeepZoomArguments args, TextWriter stde return null; } + // DeepZoomGenerator accepts any tile size and overlap and lets GetTile reject a tile, or the slide region read + // for it, that needs more bytes than a .NET array can hold. Here that would happen after the old output was + // moved aside and deleted, so every image the export writes is checked first, with the same rule. Large values + // alone are fine: a tile never extends past its level, so a small slide with a large -s has small tiles. A + // tile's width and its region's width depend only on its column: all interior columns are TileSize + 2 * + // Overlap wide, and their regions only shrink to the right (they are clipped to the level), so the widest are + // in column 0, 1 or the last one. Likewise for rows. + private static string? CheckTileSizes(OpenSlide slide, DeepZoomArguments args) + { + var images = new List<(DeepZoomGenerator Generator, string Name)> + { + (new DeepZoomGenerator(slide, args.TileSize, args.Overlap, args.LimitBounds), ExportSupport.Describe(args.Slide, null)), + }; + if (args.Viewer) + { + foreach (KeyValuePair image in slide.AssociatedImages) + { + images.Add((new DeepZoomGenerator(image.Value, args.TileSize, args.Overlap), ExportSupport.Describe(args.Slide, image.Key))); + } + } + + foreach ((DeepZoomGenerator generator, string name) in images) + { + for (int level = 0; level < generator.LevelCount; level++) + { + TileGridSize grid = generator.LevelTiles[level]; + foreach (long column in Widest(grid.Columns)) + { + foreach (long row in Widest(grid.Rows)) + { + SlideSize tile = generator.GetTileDimensions(level, column, row); + TileRegion region = generator.GetTileCoordinates(level, column, row); + string? what = TooLarge(tile.Width, tile.Height) ? $"a {tile.Width} x {tile.Height} tile at level {level} of {name}" + : TooLarge(region.Width, region.Height) ? $"a tile at level {level} of {name} read from a {region.Width} x {region.Height} slide region" + : null; + if (what is not null) + { + return $"--size {args.TileSize} and --overlap {args.Overlap} make {what}, which needs more bytes than " + + "a .NET array can hold. Choose a smaller -s/--size or -e/--overlap."; + } + } + } + } + } + + return null; + + static IEnumerable Widest(long count) => new[] { 0L, 1L, count - 1 }.Where(i => i >= 0 && i < count).Distinct(); + + // OpenSlide.CheckedPixelBytes, which GetTile uses: width * height * 4 bytes must fit in an array. + static bool TooLarge(long width, long height) + { + width = Math.Max(width, 0); + height = Math.Max(height, 0); + return width != 0 && height > Array.MaxLength / 4 / width; + } + } + private static async Task ExportAsync(OpenSlide slide, DeepZoomArguments args, TextWriter stderr, CancellationToken ct) { string name = Path.TrimEndingDirectorySeparator(args.Output ?? Path.GetFileNameWithoutExtension(args.Slide)); diff --git a/src/OpenSlideSharp.Tool/README.md b/src/OpenSlideSharp.Tool/README.md index c757152..90e4a55 100644 --- a/src/OpenSlideSharp.Tool/README.md +++ b/src/OpenSlideSharp.Tool/README.md @@ -51,6 +51,7 @@ Every key of the store is written as a file, with `/` in the key as directories. - Every file is written to `..tmp` next to it and then moved into place, so no file is ever partially written. The `.dzi` is written after the tiles, and the OME-Zarr root metadata (`zarr.json`, or `.zgroup` and `.zattrs`) after every chunk and level, so an interrupted export is not mistaken for a complete one. - Progress goes to stderr, at most once a second: `Tiling : / tiles`. Warnings (see [Color](#color)) and errors go to stderr too, prefixed with `openslide-sharp:`. - Ctrl+C stops the export once the files being written are complete. +- Before anything is written, `deepzoom` checks that each tile, and the slide region read for it, fits in a .NET array (`width × height × 4` bytes, just under 2 GiB); with an `-s` or `-e` too large for that it stops with exit code 2. A tile never extends past its level, so a tile size larger than the slide is fine. - Exit codes: 0 on success, 1 if the slide cannot be opened or the export fails, 2 for invalid arguments, 130 when canceled. - `-j` above 4 × the processor count is lowered to that, with a note on stderr. diff --git a/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs b/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs index 29103bf..f84161b 100644 --- a/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs +++ b/test/OpenSlideSharp.Tool.Tests/OutputSafetyTests.cs @@ -211,6 +211,120 @@ public async Task Leftovers_AreCleanedUpOnlyWithMarker() Assert.True(File.Exists(Path.Combine(other, "0", "c", "0"))); // another output's } + [Theory] + [InlineData(false, 30_000, 1)] + [InlineData(true, 30_000, 1)] + [InlineData(false, 254, 600_000_000)] + [InlineData(true, 254, 600_000_000)] + public async Task DeepZoom_TileTooLarge_IsRefusedBeforeTouchingOutput(bool viewer, int tileSize, int overlap) + { + // A tile that needs more bytes than a .NET array can hold: a 30000-pixel tile of a 40000 x 40000 slide, or + // the boxes slide with a huge overlap. The old output is replaced only after every image's tiles are known to fit. + using var temp = new TempDirectory(); + string output = temp.Combine("out"); + Assert.Equal(0, await DeepZoomCommand.RunAsync( + new DeepZoomArguments(TestFiles.Get("boxes.tiff")) { Output = output, Viewer = viewer }, new StringWriter(), Token)); + string slide = TestFiles.Get("boxes.tiff"); + if (tileSize > 254) + { + slide = temp.Combine("large.tiff"); + WriteBlankTiledTiff(slide, 40_000, 40_000); + } + + string[] before = Snapshot(temp.Path); + var stderr = new StringWriter(); + + int code = await DeepZoomCommand.RunAsync( + new DeepZoomArguments(slide) { Output = output, Viewer = viewer, TileSize = tileSize, Overlap = overlap }, stderr, Token); + + Assert.Equal(2, code); + Assert.Contains($"--size {tileSize} and --overlap {overlap} make a ", stderr.ToString(), StringComparison.Ordinal); + Assert.Contains("Choose a smaller -s/--size or -e/--overlap.", stderr.ToString(), StringComparison.Ordinal); + Assert.DoesNotContain("Parameter", stderr.ToString(), StringComparison.Ordinal); + Assert.Equal(before, Snapshot(temp.Path)); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task DeepZoom_SmallSlideLargeTileSize_Works(bool viewer) + { + // Tiles never extend past their level: with a tile size larger than the slide each level is one small tile. + using var temp = new TempDirectory(); + string output = temp.Combine("boxes"); + var stderr = new StringWriter(); + + int code = await DeepZoomCommand.RunAsync( + new DeepZoomArguments(TestFiles.Get("boxes.tiff")) { Output = output, Viewer = viewer, TileSize = 600_000_000 }, stderr, Token); + + Assert.True(code == 0, stderr.ToString()); + string files = viewer ? Path.Combine(output, "slide_files") : output + "_files"; + Assert.Equal(10, Directory.GetFiles(files, "*.jpeg", SearchOption.AllDirectories).Length); + Assert.Contains("TileSize=\"600000000\"", File.ReadAllText(viewer ? Path.Combine(output, "slide.dzi") : output + ".dzi"), StringComparison.Ordinal); + } + + // An uncompressed tiled RGB TIFF whose 256 x 256 tiles all share one blank tile's bytes: a large slide in a small + // file, which OpenSlide opens as a generic TIFF. + private static void WriteBlankTiledTiff(string path, int width, int height) + { + const int Tile = 256; + int tiles = checked(((width + Tile - 1) / Tile) * ((height + Tile - 1) / Tile)); + const int TileBytes = Tile * Tile * 3; + (ushort Tag, ushort Type, int Count, int Value)[] entries = + [ + (256, 4, 1, width), // ImageWidth + (257, 4, 1, height), // ImageLength + (258, 3, 3, 0), // BitsPerSample 8,8,8 (at bitsAt) + (259, 3, 1, 1), // Compression: none + (262, 3, 1, 2), // PhotometricInterpretation: RGB + (277, 3, 1, 3), // SamplesPerPixel + (284, 3, 1, 1), // PlanarConfiguration: contiguous + (322, 3, 1, Tile), // TileWidth + (323, 3, 1, Tile), // TileLength + (324, 4, tiles, 0), // TileOffsets (at offsetsAt) + (325, 4, tiles, 0), // TileByteCounts (at countsAt) + ]; + int bitsAt = 8 + 2 + (entries.Length * 12) + 4; + int tileAt = bitsAt + 6; + int offsetsAt = tileAt + TileBytes; + int countsAt = offsetsAt + (tiles * 4); + + using var file = new BinaryWriter(File.Create(path)); + file.Write("II"u8); + file.Write((ushort)42); + file.Write(8); + file.Write((ushort)entries.Length); + foreach ((ushort tag, ushort type, int count, int value) in entries) + { + file.Write(tag); + file.Write(type); + file.Write(count); + int field = tag switch { 258 => bitsAt, 324 => offsetsAt, 325 => countsAt, _ => value }; + if (type == 3 && count == 1) + { + file.Write((ushort)field); + file.Write((ushort)0); + } + else + { + file.Write(field); + } + } + + file.Write(0); // no next IFD + file.Write(new ushort[] { 8, 8, 8 }.SelectMany(BitConverter.GetBytes).ToArray()); + file.Write(new byte[TileBytes]); + for (int i = 0; i < tiles; i++) + { + file.Write(tileAt); + } + + for (int i = 0; i < tiles; i++) + { + file.Write(TileBytes); + } + } + // Every entry below the directory, with a hash of each file's content. private static string[] Snapshot(string directory) => Directory.GetFileSystemEntries(directory, "*", SearchOption.AllDirectories) From 7f837e56d74295459756b073ab3c9da2847f9e47 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:39:24 +0800 Subject: [PATCH 27/38] docs: say what the upstream sync changes when the release fails or no key is set --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1ad7eab..7cde857 100644 --- a/README.md +++ b/README.md @@ -30,11 +30,11 @@ A nightly version increments the fourth number, then carries the build date and Releases are made by GitHub Actions: -- Every day, the Upstream sync workflow looks for a newer openslide-bin release or nightly build. It pins the next one in `eng/openslide.json`, regenerates the bindings, runs CI, fast-forwards `master` and releases that commit. It takes one build per run, a release before a nightly. A build that fails changes nothing, and gets one issue titled `Upstream sync failed: openslide-bin `. If `master` moved during the run, the update comes as a pull request instead. +- Every day, the Upstream sync workflow looks for a newer openslide-bin release or nightly build. It pins the next one in `eng/openslide.json`, regenerates the bindings, runs CI, fast-forwards `master` and releases that commit. It takes one build per run, a release before a nightly. A build that fails before the fast-forward, in CI for example, changes nothing. A failure at any step gets one issue titled `Upstream sync failed: openslide-bin `, which says whether `master` was fast-forwarded already; if it was, only the release is left, and "Re-run failed jobs" on the run finishes it. If `master` moved during the run, the update comes as a pull request instead. - A push to `master` that changes `src/**`, `eng/openslide.json` or `Directory.*.props` releases that commit. - Other changes, such as to the viewer sample or the `eng/` scripts, are released by running the Release workflow by hand. -A release tests the commit on all platforms, pushes the five packages to nuget.org, tags the commit `v` and creates a GitHub release with the packages, the viewer archives and the openslide-bin source tarball. Without the `NUGET_API_KEY` secret it is a dry run: it builds and checks everything, publishes nothing and lists what it would release in the run summary. +A release tests the commit on all platforms, pushes the five packages to nuget.org, tags the commit `v` and creates a GitHub release with the packages, the viewer archives and the openslide-bin source tarball. Without the `NUGET_API_KEY` secret it is a dry run: it builds and checks everything, publishes nothing and lists what it would release in the run summary. Only the release is a dry run then: the daily sync still commits each newer build (as IOL0ol1) and fast-forwards `master` to it. ## Install From 58954f9523c8cd5adba7fad2e6cf867122da2469 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:39:37 +0800 Subject: [PATCH 28/38] docs: publish the viewer with a local runtime package through Publish-Viewer, and name the 4.x releases --- README.md | 2 +- samples/OpenSlideSharp.Viewer/README.md | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7cde857..0dacb4f 100644 --- a/README.md +++ b/README.md @@ -179,4 +179,4 @@ These 1.x packages end at the version shown and are not updated anymore. Use the ## License -The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. The corresponding source is the openslide-bin source tarball named in the package's `openslide-bin.json`; each [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) attaches a copy for its version. `OpenSlideSharp.Tool` states its terms in its own `LICENSE.txt`, and the viewer in `licenses/` next to its executable. +The managed code is MIT licensed; see [LICENSE](LICENSE). `OpenSlideSharp.runtime` redistributes OpenSlide (LGPL-2.1) built by openslide-bin, with the components linked into each platform's library under their own licenses; its `LICENSE.txt` explains the terms, and `licenses//` holds the license texts. The corresponding source is the openslide-bin source tarball named in the package's `openslide-bin.json`; each 4.x [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) attaches a copy for its version. `OpenSlideSharp.Tool` states its terms in its own `LICENSE.txt`, and the viewer in `licenses/` next to its executable. diff --git a/samples/OpenSlideSharp.Viewer/README.md b/samples/OpenSlideSharp.Viewer/README.md index 16a19a7..10f67ad 100644 --- a/samples/OpenSlideSharp.Viewer/README.md +++ b/samples/OpenSlideSharp.Viewer/README.md @@ -11,7 +11,7 @@ Open a slide from the command line, with File → Open, or by dropping it on the ## Download -Each [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) has the viewer for three platforms: +Each 4.x [GitHub release](https://github.com/IOL0ol1/OpenSlideSharp/releases) has the viewer for three platforms: | Platform | Archive | |---|---| @@ -67,7 +67,15 @@ dotnet publish samples/OpenSlideSharp.Viewer -c Release -r win-x64 --self-contai -p:UseOpenSlideRuntimePackage=true -p:OpenSlideSharpVersion= ``` -`artifacts/publish/OpenSlideSharp.Viewer/release_win-x64/` then holds `OpenSlideSharp.Viewer.exe`, which runs without .NET installed, and `licenses/`. The other runtime identifiers are `linux-x64`, `linux-arm64`, `osx-arm64` and `osx-x64`. OpenSlide comes from the `OpenSlideSharp.runtime` package of that version, restored from nuget.org or from a folder given with `-p:RestoreAdditionalProjectSources=`, as `eng/Test-Packages.ps1` does. +`artifacts/publish/OpenSlideSharp.Viewer/release_win-x64/` then holds `OpenSlideSharp.Viewer.exe`, which runs without .NET installed, and `licenses/`. The other runtime identifiers are `linux-x64`, `linux-arm64`, `osx-arm64` and `osx-x64`. OpenSlide comes from the `OpenSlideSharp.runtime` package of that version, restored from nuget.org. + +To publish with an `OpenSlideSharp.runtime` package in a local folder instead, such as the one `pwsh eng/Test-Packages.ps1 -PackOnly -Version ` packs into `artifacts/smoke-feed` (after `pwsh eng/Get-OpenSlide.ps1 -Platform all`), use the script the releases use: + +```sh +pwsh eng/Publish-Viewer.ps1 -Rid win-x64 -Version -Feed artifacts/smoke-feed +``` + +It restores `OpenSlideSharp*` packages from that folder only, checks that the runtime package came from it, checks the publish folder (under `artifacts/viewer//`) and, for this machine's runtime identifier, runs `--check`. Do not add the folder to `dotnet publish` as a second package source (for example with `-p:RestoreAdditionalProjectSources`): with the same package and version in two sources, NuGet may take either one. The native libraries are inside the executable. It extracts them on first start to `%TEMP%\.net` on Windows and `~/.net` on Linux and macOS (or to `DOTNET_BUNDLE_EXTRACT_BASE_DIR`), and reuses them after that. The folders that older versions of the viewer extracted there can be deleted. From 81929f730169fe30d71d198eceb92fea9ca8a36b Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:42:05 +0800 Subject: [PATCH 29/38] build: leave the runtime package's LICENSE.txt out of the viewer's licenses It describes the nupkg's layout (licenses//, runtimes/), which the viewer's licenses/ folder does not have; THIRD-PARTY-NOTICES.txt and SOURCE.md say the same for the viewer. Publish-Viewer checks that it is gone. --- eng/Publish-Viewer.ps1 | 6 +++++- samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj | 6 ++++++ samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt | 3 ++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/eng/Publish-Viewer.ps1 b/eng/Publish-Viewer.ps1 index b70c7ae..bb160da 100644 --- a/eng/Publish-Viewer.ps1 +++ b/eng/Publish-Viewer.ps1 @@ -6,7 +6,8 @@ the native OpenSlide library from the OpenSlideSharp.runtime package in a local feed. .DESCRIPTION Then checks the publish folder: only the executable and licenses/, with exactly the notices of the openslide-bin - archive the RID's library comes from (as the runtime package has them), and a licenses/SOURCE.md that names the + archive the RID's library comes from (as the runtime package has them), without the runtime package's own + LICENSE.txt (it describes the nupkg's layout), and a licenses/SOURCE.md that names the openslide-bin build of eng/openslide.json, its source tarball and the OpenSlideSharp release v. When -Rid is this machine's, also runs the executable with --check on test/OpenSlideSharp.Tests/Fixtures/small.svs (it reads the slide without a window) and checks that the native libraries came out of the bundle. @@ -102,6 +103,9 @@ foreach ($required in 'licenses/THIRD-PARTY-NOTICES.txt', 'licenses/SOURCE.md', "licenses/openslide-bin/$binKey/VERSIONS.md", "licenses/openslide-bin/$binKey/OpenSlide/COPYING.LESSER") { if ($paths -notcontains $required) { throw "[viewer] $required is not in $publish" } } +# The runtime package's own LICENSE.txt describes the nupkg's layout, which this folder does not have. +$runtimeLicense = @($paths | Where-Object { $_ -like 'licenses/OpenSlideSharp.runtime/*' }) +if ($runtimeLicense.Count -gt 0) { throw "[viewer] $($runtimeLicense -join ', ') must not be in $publish" } $zip = [IO.Compression.ZipFile]::OpenRead($runtimeNupkg) try { $runtimeEntries = @($zip.Entries | ForEach-Object { [Uri]::UnescapeDataString($_.FullName) }) } finally { $zip.Dispose() } diff --git a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj index f8d824b..630ca5a 100644 --- a/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj +++ b/samples/OpenSlideSharp.Viewer/OpenSlideSharp.Viewer.csproj @@ -102,6 +102,12 @@ <_ViewerPackage Include="@(_ViewerPackageFile->'%(PackageDir)'->Distinct())" Condition="'%(_ViewerPackageFile.PackageDir)' != ''" /> <_ViewerPackageLicense Include="%(_ViewerPackage.Identity)LICENSE*;%(_ViewerPackage.Identity)THIRD-PARTY-NOTICES*" PackageId="%(_ViewerPackage.NuGetPackageId)" /> + + <_ViewerPackageLicense Remove="@(_ViewerPackageLicense)" Condition="'%(_ViewerPackageLicense.PackageId)' == 'OpenSlideSharp.runtime'" /> <_OpenSlideBinLicense Include="$(_OpenSlideBinDir)/licenses/$(_OpenSlideBinLicenseDir)**" /> diff --git a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt index 75dfe98..443438e 100644 --- a/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt +++ b/samples/OpenSlideSharp.Viewer/THIRD-PARTY-NOTICES.txt @@ -7,7 +7,8 @@ below, each under its own license. Where a component's NuGet package ships license or notice files, the publish copies them into a folder named after the package, next to this file. The licenses of the other components are reproduced at the end of this -file. +file. OpenSlideSharp.runtime's LICENSE.txt is left out: it describes the layout of that package, and item 1 and +SOURCE.md say the same for this folder. 1. OpenSlide and the libraries linked into it (openslide-bin) From 1f44dbe59f3d885d300b486742d5c8ccafd8c668 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:47:04 +0800 Subject: [PATCH 30/38] build: word the release notes per channel, and note a stable release after a nightly A stable release's notes said that the upstream nightly URL expires. When the release before a stable one was built on a nightly, the notes now also say that functions only that nightly had may be gone from OpenSlideSharp.Native (design 7.2, rule 5). The previous release is the highest lower v* tag or published version; its channel comes from its tagged eng/openslide.json, or from its version's form when that is not available. --- eng/Get-ReleaseVersion.ps1 | 84 +++++++++++++++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 5 deletions(-) diff --git a/eng/Get-ReleaseVersion.ps1 b/eng/Get-ReleaseVersion.ps1 index 6b8565a..bf65488 100644 --- a/eng/Get-ReleaseVersion.ps1 +++ b/eng/Get-ReleaseVersion.ps1 @@ -11,6 +11,10 @@ stable manifest with a C#-only release -> numbered like a nightly: the stable release's date and commit. The version must be higher than every version published on nuget.org, or the script fails. -PublishedVersions defaults to the nuget.org flat container, -ExistingTags to `git tag --list 'v*'`. + The release notes name the openslide-bin build, the OpenSlide version and commit, and the attached source tarball. + For a stable manifest whose previous release (the highest lower v* tag or published version) was built on a nightly, + as its tagged eng/openslide.json says (or, without one, its version's form), they also say that functions only the + nightly had may be gone from OpenSlideSharp.Native. -SelfTest runs built-in cases against mock data (no network, no git) and exits 1 if one fails. #> [CmdletBinding()] @@ -37,8 +41,29 @@ function Get-NextSuffix([string]$Base, [string[]]$Tags) { if ($max -lt 0) { $null } else { $max + 1 } } +function Get-PreviousRelease([string]$Version, [string[]]$Tags, [scriptblock]$ChannelOfTag) { + # The highest v tag below $Version (published versions are among the tags as v), and the channel + # of the openslide-bin build it was made from: from its eng/openslide.json via $ChannelOfTag when that knows it, + # else from the version's form (only nightly-numbered versions have a -nightly label). $null without one. + $previous = $null + $previousTag = $null + foreach ($t in @($Tags)) { + if ("$t" -notmatch '^v(.+)$') { continue } + $v = $Matches[1] + try { $lower = (Compare-NuGetVersion $v $Version) -lt 0 } catch { continue } # a tag that is no version + if ($lower -and ($null -eq $previous -or (Compare-NuGetVersion $v $previous) -gt 0)) { $previous = $v; $previousTag = $t } + } + if ($null -eq $previous) { return $null } + $channel = if ($ChannelOfTag) { & $ChannelOfTag $previousTag } else { $null } + if ($channel -notin 'nightly', 'stable') { + $labels = (ConvertTo-NuGetVersion $previous).Labels + $channel = ($labels.Count -gt 0 -and $labels[0] -eq 'nightly') ? 'nightly' : 'stable' + } + [pscustomobject]@{ Version = $previous; Channel = $channel } +} + function Get-ReleaseVersionInfo { - param([Parameter(Mandatory)]$Manifest, [string[]]$PublishedVersions, [string[]]$ExistingTags) + param([Parameter(Mandatory)]$Manifest, [string[]]$PublishedVersions, [string[]]$ExistingTags, [scriptblock]$ChannelOfTag) $bin = [string]$Manifest.binVersion # Existing tags and published versions both occupy a number (published versions are written as tags: v). $ExistingTags = @($ExistingTags) + @(@($PublishedVersions) | Where-Object { $_ } | ForEach-Object { "v$_" }) @@ -70,14 +95,27 @@ function Get-ReleaseVersionInfo { $osv = [string]$Manifest.openslideVersion $upstreamVersion = if ($osv -match '-g[0-9a-fA-F]+$') { $osv } else { "$osv.g$($Manifest.openslideCommit)" } $tarball = "openslide-bin-$bin.tar.gz" - $notes = @( + $copy = if ($Manifest.channel -eq 'nightly') { + 'a copy of that tarball. The upstream nightly URL expires, so this copy is the permanent source for the bundled binaries.' + } else { + 'a copy of that tarball, the source for the bundled binaries.' + } + $lines = @( "OpenSlideSharp $version, built against OpenSlide binaries from openslide-bin ``$bin``.", '', "- openslide-bin: ``$bin`` ($($Manifest.releaseUrl))", "- OpenSlide: ``$($Manifest.openslideVersion)`` (commit ``$($Manifest.openslideCommit)``)", "- Upstream source tarball: $($Manifest.source.url)", - "- This release attaches ``$tarball`` (sha256 ``$($Manifest.source.sha256)``), a copy of that tarball. The upstream nightly URL expires, so this copy is the permanent source for the bundled binaries." - ) -join "`n" + "- This release attaches ``$tarball`` (sha256 ``$($Manifest.source.sha256)``), $copy" + ) + # Design §7.2, rule 5: the generated Native layer follows the headers of the build, and a nightly may have API that + # the next release does not; the rest of OpenSlideSharp wraps only API of OpenSlide releases. + $previous = Get-PreviousRelease $version $ExistingTags $ChannelOfTag + if ($Manifest.channel -eq 'stable' -and $previous -and $previous.Channel -eq 'nightly') { + $lines += '' + $lines += "The previous release, ``$($previous.Version)``, was built on an openslide-bin nightly. ``OpenSlideSharp.Native`` is generated from the headers of the OpenSlide build, so functions that only that nightly had may be gone from it in this release: API that only a nightly has is not stable. The rest of OpenSlideSharp uses only functions that OpenSlide releases have." + } + $notes = $lines -join "`n" [ordered]@{ version = $version prerelease = $version.Contains('-') @@ -162,6 +200,34 @@ if ($SelfTest) { $info.notes -match '174630bf' -and $info.notes -match 'example\.invalid/src\.tar\.gz' -and $info.notes -match [regex]::Escape('openslide-bin-4.0.1.2+20261102.nightly.tar.gz') -and $info.notes -match ('ab' * 32) } + function Get-Notes($Manifest, $Published = @('1.1.2'), $Tags = @(), $ChannelOfTag = $null) { + (Get-ReleaseVersionInfo -Manifest $Manifest -PublishedVersions $Published -ExistingTags $Tags -ChannelOfTag $ChannelOfTag).notes + } + $earlyNightly = '4.0.1.2-nightly.20260601.g0123abcd' # a nightly on openslide-bin 4.0.1.1, below stable 4.0.1.2 + $stableNext = New-Manifest 'stable' '4.0.1.3' 'v4.0.2' '0a1b2c3d' '2026-12-01' + $stableBasedRelease = '4.0.1.3-nightly.20260620.gfe79a971.1' # a C#-only release on the stable 4.0.1.2 manifest + Test-Case 'nightly notes say the upstream nightly URL expires' { $info.notes -match 'nightly URL expires' } + Test-Case 'stable notes attach the tarball and do not mention an expiring nightly URL' { + $n = Get-Notes $stable + $n -notmatch 'nightly' -and $n -match [regex]::Escape('openslide-bin-4.0.1.2.tar.gz') -and $n -match ('ab' * 32) } + Test-Case 'stable after a nightly release: the notes say nightly-only Native functions may be gone' { + $n = Get-Notes $stable -Tags 'v1.1.1', "v$earlyNightly" + $n -match 'OpenSlideSharp\.Native' -and $n -match [regex]::Escape("previous release, ``$earlyNightly``") } + Test-Case 'stable after a stable release: no such note' { (Get-Notes $stableNext -Tags 'v1.1.1', 'v4.0.1.2') -notmatch 'OpenSlideSharp\.Native' } + Test-Case 'first release, after 1.x only: no such note' { (Get-Notes $stable -Tags 'v1.0.1.3', 'v1.1.0', 'v1.1.1') -notmatch 'OpenSlideSharp\.Native' } + Test-Case 'nightly manifest: no such note' { (Get-Notes $nightly -Tags "v$earlyNightly") -notmatch 'OpenSlideSharp\.Native' } + Test-Case 'a published nightly without a tag counts as the previous release' { + (Get-Notes $stable -Published '1.1.2', $earlyNightly -ChannelOfTag { $null }) -match [regex]::Escape("previous release, ``$earlyNightly``") } + Test-Case 'higher and unparsable tags are not the previous release' { + (Get-Notes $stable -Tags "v$earlyNightly", 'v4.0.1.3', 'v4.0.1.4-nightly.20261201.gaaaaaaaa', 'vnext', 'v1.x') -match [regex]::Escape("previous release, ``$earlyNightly``") } + Test-Case "the previous release's tagged manifest decides its channel over the version's form" { + $tags = 'v4.0.1.2', "v$stableBasedRelease" + $byManifest = Get-Notes $stableNext -Tags $tags -ChannelOfTag { param($Tag) if ($Tag -eq "v$stableBasedRelease") { 'stable' } } + $byForm = Get-Notes $stableNext -Tags $tags -ChannelOfTag { param($Tag) $null } + $nightlyByManifest = Get-Notes $stableNext -Tags 'v4.0.1.2', 'v4.0.1.3-nightly.20261102.g174630bf' -ChannelOfTag { param($Tag) 'nightly' } + $byManifest -notmatch 'OpenSlideSharp\.Native' -and $byForm -match [regex]::Escape("previous release, ``$stableBasedRelease``") -and + $nightlyByManifest -match 'OpenSlideSharp\.Native' } + foreach ($r in $results) { Write-Host ("{0} {1}" -f ($r.Ok ? 'PASS' : 'FAIL'), $r.Name) } $failed = @($results | Where-Object { -not $_.Ok }).Count Write-Host "$($results.Count - $failed) passed, $failed failed" @@ -177,7 +243,15 @@ try { $ExistingTags = @(git -C $repoRoot tag --list 'v*') if ($LASTEXITCODE -ne 0) { throw "git tag --list failed with exit code $LASTEXITCODE." } } - Get-ReleaseVersionInfo -Manifest $manifestObject -PublishedVersions $PublishedVersions -ExistingTags $ExistingTags | ConvertTo-Json -Depth 3 + # The channel in eng/openslide.json of a tagged commit; $null for a tag that is not here or has no manifest (1.x). + $channelOfTag = { + param([string]$Tag) + $json = git -C $repoRoot show "refs/tags/${Tag}:eng/openslide.json" 2> $null + if ($LASTEXITCODE -ne 0) { return $null } + try { [string](($json -join "`n") | ConvertFrom-Json).channel } catch { $null } + } + Get-ReleaseVersionInfo -Manifest $manifestObject -PublishedVersions $PublishedVersions -ExistingTags $ExistingTags -ChannelOfTag $channelOfTag | + ConvertTo-Json -Depth 3 } catch { [Console]::Error.WriteLine("Get-ReleaseVersion: $($_.Exception.Message)") exit 1 From df690f112be173eb671f5eeb8505ebe716b9c33a Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:56:53 +0800 Subject: [PATCH 31/38] ci: run each viewer archive on its own platform before releasing it The release publishes all three viewer archives on Linux, and only linux-x64 was ever run. A new job extracts each archive on windows-latest, ubuntu-latest or macos-latest and runs it with --check (eng/Test-ViewerArchive.ps1); on Windows it also checks the version resource, application manifest and GUI subsystem that the SDK writes into the executable. publish and the dry run summary wait for it. --- .github/workflows/release.yml | 43 +++++++++- eng/Test-ViewerArchive.ps1 | 157 ++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 3 deletions(-) create mode 100644 eng/Test-ViewerArchive.ps1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bce4549..4cdcb89 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -161,7 +161,8 @@ jobs: viewer: name: viewer (${{ matrix.rid }}) needs: [version, pack] - # Cross-published: the SDK signs the macOS executable ad hoc on any host. + # Cross-published: on any host the SDK signs the macOS executable ad hoc and, since .NET 8, writes the Windows + # executable's resources itself (no NETSDK1074). viewer-check runs each archive on its own platform. runs-on: ubuntu-latest timeout-minutes: 30 strategy: @@ -194,8 +195,44 @@ jobs: path: artifacts/release/OpenSlideSharp.Viewer-* if-no-files-found: error + viewer-check: + name: viewer check (${{ matrix.rid }}) + needs: [version, viewer] + # Each archive, published on Linux above, is extracted and run with --check on its own platform before anything + # is released. On Windows this also checks the version resource, application manifest and GUI subsystem that the + # SDK copies into the executable (an SDK that cannot do that on a Linux host warns NETSDK1074 and leaves them out). + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + strategy: + matrix: + include: + - rid: win-x64 + os: windows-latest + - rid: linux-x64 + os: ubuntu-latest + - rid: osx-arm64 + os: macos-latest + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.version.outputs.sha }} + persist-credentials: false + - uses: actions/download-artifact@v8 + with: + name: viewer-${{ matrix.rid }} + path: artifacts/release + - name: Run the viewer from its archive + shell: pwsh + env: + RID: ${{ matrix.rid }} + VERSION: ${{ needs.version.outputs.version }} + INFORMATIONAL_VERSION: ${{ needs.version.outputs.informational-version }} + run: >- + ./eng/Test-ViewerArchive.ps1 -Path artifacts/release -Rid $env:RID -Version $env:VERSION + -InformationalVersion $env:INFORMATIONAL_VERSION + publish: - needs: [version, pack, viewer] + needs: [version, pack, viewer, viewer-check] if: needs.version.outputs.dry-run == 'false' runs-on: ubuntu-latest timeout-minutes: 20 @@ -296,7 +333,7 @@ jobs: } >> "$GITHUB_STEP_SUMMARY" dry-run-summary: - needs: [version, pack, viewer] + needs: [version, pack, viewer, viewer-check] if: needs.version.outputs.dry-run == 'true' runs-on: ubuntu-latest timeout-minutes: 10 diff --git a/eng/Test-ViewerArchive.ps1 b/eng/Test-ViewerArchive.ps1 new file mode 100644 index 0000000..691e3d7 --- /dev/null +++ b/eng/Test-ViewerArchive.ps1 @@ -0,0 +1,157 @@ +#!/usr/bin/env pwsh +#requires -Version 7 +<# +.SYNOPSIS + Runs a release archive of the desktop viewer on its own platform, as a user would after downloading it. +.DESCRIPTION + The release publishes the viewer for every RID on Linux, and eng/Publish-Viewer.ps1 can run only the host's RID. This + extracts OpenSlideSharp.Viewer--.zip (Windows) or .tar.gz into a new folder, checks that it holds the + executable (with mode 755 outside Windows) and licenses/ only, and runs the executable with --check on + test/OpenSlideSharp.Tests/Fixtures/small.svs: it must start, load the native libraries from its bundle and read the + slide. On Windows it also checks what the SDK copies into the executable from the viewer's assembly: the version + resource (ProductVersion = -InformationalVersion), the application manifest from app.manifest and the GUI subsystem. + Must run on a machine of -Rid. +.PARAMETER Path + The folder with the archive. +.PARAMETER Rid + win-x64, linux-x64, linux-arm64, osx-arm64 or osx-x64: this machine's. +.PARAMETER Version + The release version in the archive name. +.PARAMETER InformationalVersion + The executable's expected ProductVersion on Windows. Default: , optionally followed by +. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][string]$Path, + [Parameter(Mandatory)][string]$Rid, + [Parameter(Mandatory)][string]$Version, + [string]$InformationalVersion +) + +$ErrorActionPreference = 'Stop' +Add-Type -AssemblyName System.IO.Compression.FileSystem + +$root = Split-Path -Parent $PSScriptRoot +$fixture = Join-Path $root 'test/OpenSlideSharp.Tests/Fixtures/small.svs' + +$hostArch = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture +$hostRid = if ($IsWindows -and $hostArch -eq 'X64') { 'win-x64' } +elseif ($IsLinux -and $hostArch -eq 'X64') { 'linux-x64' } +elseif ($IsLinux -and $hostArch -eq 'Arm64') { 'linux-arm64' } +elseif ($IsMacOS -and $hostArch -eq 'Arm64') { 'osx-arm64' } +elseif ($IsMacOS -and $hostArch -eq 'X64') { 'osx-x64' } +if ($Rid -ne $hostRid) { throw "The $Rid archive must be run on a $Rid machine; this one is $($hostRid ?? $hostArch)." } + +# The subsystem and the RT_MANIFEST (type 24) texts of a PE file's Win32 resources. +function Get-PeResourceInfo([string]$File) { + $stream = [IO.File]::OpenRead($File) + try { + $pe = [Reflection.PortableExecutable.PEReader]::new($stream) + $header = $pe.PEHeaders.PEHeader + $manifests = [Collections.Generic.List[string]]::new() + $directory = $header.ResourceTableDirectory + if ($directory.Size -gt 0) { + $base = $directory.RelativeVirtualAddress + $rsrc = [Linq.Enumerable]::ToArray($pe.GetSectionData($base).GetContent()) + # The entries of the resource directory at $Offset: an id (or $null for a name), and the offset of the + # subdirectory or data entry it points to. + function Get-Entries([int]$Offset) { + $count = [BitConverter]::ToUInt16($rsrc, $Offset + 12) + [BitConverter]::ToUInt16($rsrc, $Offset + 14) + for ($i = 0; $i -lt $count; $i++) { + $name = [BitConverter]::ToUInt32($rsrc, $Offset + 16 + 8 * $i) + $target = [BitConverter]::ToUInt32($rsrc, $Offset + 20 + 8 * $i) + [pscustomobject]@{ + Id = ($name -band 0x80000000) -eq 0 ? [int]$name : $null + IsDirectory = ($target -band 0x80000000) -ne 0 + Offset = [int]($target -band 0x7FFFFFFF) + } + } + } + function Get-Leaves([int]$Offset) { + foreach ($e in Get-Entries $Offset) { if ($e.IsDirectory) { Get-Leaves $e.Offset } else { $e.Offset } } + } + foreach ($type in Get-Entries 0) { + if ($type.Id -ne 24 -or -not $type.IsDirectory) { continue } + foreach ($leaf in Get-Leaves $type.Offset) { + $start = [BitConverter]::ToInt32($rsrc, $leaf) - $base + $size = [BitConverter]::ToInt32($rsrc, $leaf + 4) + if ($start -lt 0 -or $start + $size -gt $rsrc.Length) { throw "A manifest resource of $File lies outside its resource section." } + $manifests.Add([Text.Encoding]::UTF8.GetString($rsrc, $start, $size)) + } + } + } + [pscustomobject]@{ Subsystem = $header.Subsystem; Manifests = $manifests.ToArray() } + } + finally { $stream.Dispose() } +} + +$isWindowsRid = $Rid.StartsWith('win-') +$archive = Join-Path $Path "OpenSlideSharp.Viewer-$Version-$Rid$($isWindowsRid ? '.zip' : '.tar.gz')" +if (-not (Test-Path -PathType Leaf $archive)) { throw "$archive not found." } +$work = Join-Path ([IO.Path]::GetTempPath()) "viewer-archive-$([Guid]::NewGuid().ToString('N'))" +$extracted = Join-Path $work 'viewer' +New-Item -ItemType Directory -Force $extracted | Out-Null +try { + Write-Host "== viewer archive: $archive" + if ($isWindowsRid) { + [IO.Compression.ZipFile]::ExtractToDirectory($archive, $extracted) + } + else { + tar -xzf $archive -C $extracted + if ($LASTEXITCODE -ne 0) { throw "tar -xzf $archive failed with exit code $LASTEXITCODE." } + } + + $exeName = $isWindowsRid ? 'OpenSlideSharp.Viewer.exe' : 'OpenSlideSharp.Viewer' + $exe = Join-Path $extracted $exeName + $top = (@(Get-ChildItem $extracted -Force | ForEach-Object Name) | Sort-Object) -join ',' + $expected = (@($exeName, 'licenses') | Sort-Object) -join ',' + if ($top -cne $expected) { + throw "The archive's root holds $top, expected $exeName and licenses/." + } + if (-not $isWindowsRid -and ((Get-Item $exe).UnixFileMode -band [IO.UnixFileMode]::UserExecute) -eq 0) { + throw "$exeName is not executable after extraction (mode $((Get-Item $exe).UnixFileMode))." + } + + if ($isWindowsRid) { + # Copied from the managed assembly into the apphost; an SDK that cannot do that on the publishing host leaves + # the apphost's own resources (NETSDK1074). + $info = (Get-Item $exe).VersionInfo + Write-Host "ProductVersion: $($info.ProductVersion), FileVersion: $($info.FileVersion)" + $versionOk = $InformationalVersion ? $info.ProductVersion -ceq $InformationalVersion : ($info.ProductVersion -ceq $Version -or $info.ProductVersion.StartsWith("$Version+", [StringComparison]::Ordinal)) + if (-not $versionOk) { + throw "$exeName has ProductVersion '$($info.ProductVersion)', expected '$($InformationalVersion ? $InformationalVersion : $Version)'." + } + $pe = Get-PeResourceInfo $exe + Write-Host "Subsystem: $($pe.Subsystem), manifests: $($pe.Manifests.Count)" + if ($pe.Subsystem -ne [Reflection.PortableExecutable.Subsystem]::WindowsGui) { throw "$exeName has the $($pe.Subsystem) subsystem, expected WindowsGui." } + if (-not ($pe.Manifests | Where-Object { $_.Contains('OpenSlideSharp.Viewer.Desktop') })) { + throw "$exeName does not have the application manifest of samples/OpenSlideSharp.Viewer/app.manifest." + } + } + + # The bundle extracts its native libraries when it starts; a fresh extraction directory shows they came from it. + $bundleExtract = Join-Path $work 'extract' + $env:DOTNET_BUNDLE_EXTRACT_BASE_DIR = $bundleExtract + try { + # Piped, so that PowerShell waits for the viewer, a GUI program on Windows, and captures what it prints. + $output = & $exe --check $fixture 2>&1 | Out-String + $code = $LASTEXITCODE + } + finally { + Remove-Item Env:DOTNET_BUNDLE_EXTRACT_BASE_DIR -ErrorAction SilentlyContinue + } + Write-Host $output + if ($code -ne 0) { throw "$exeName --check exited with code $code, expected 0." } + foreach ($line in 'openslide=4.', 'slide=16x16') { + if ($output -notmatch [regex]::Escape($line)) { throw "$exeName --check did not print '$line'." } + } + $libraries = @(Get-ChildItem $bundleExtract -Recurse -File | ForEach-Object Name) + $libraries | ForEach-Object { Write-Host "extracted: $_" } + foreach ($lib in 'libopenslide-1', 'libSkiaSharp', 'libHarfBuzzSharp') { + if (-not ($libraries | Where-Object { [IO.Path]::GetFileNameWithoutExtension($_) -eq $lib })) { throw "$lib is not in the bundle." } + } + Write-Host "The $Rid archive runs." +} +finally { + Remove-Item $work -Recurse -Force -ErrorAction SilentlyContinue +} From 5417158fb3094dc42fc0c3193d478dc20699114c Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Wed, 18 Nov 2026 23:59:28 +0800 Subject: [PATCH 32/38] ci: give each ref its own release concurrency group A dry run dispatched on a branch shared the single release group with the releases of master, and a newer pending run cancels the older one. The group is now publish-: the upstream sync's calls and pushes to master still share one. It is not release-, which, as group names are case insensitive, equals the group of the ci.yml call inside the run. --- .github/workflows/release.yml | 7 ++++++- .github/workflows/upstream-sync.yml | 8 ++++---- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4cdcb89..9b810a5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -39,8 +39,13 @@ on: permissions: contents: read +# One group per ref: a dry run dispatched on a branch must not take the queue slot of a release of master (GitHub keeps +# one running and one pending run per group, and a newer pending run cancels the older). When called, github.ref is the +# caller's, so the upstream sync's calls and pushes to master share publish-refs/heads/master and run one at a time. +# Not release-${{ github.ref }}: group names are case insensitive, and ci.yml, called below, takes the group +# ${{ github.workflow }}-${{ github.ref }}, which is Release-refs/heads/... here; the call would wait for this run. concurrency: - group: release + group: publish-${{ github.ref }} cancel-in-progress: false jobs: diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index c7a8727..73b6136 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -289,10 +289,10 @@ jobs: uses: ./.github/workflows/release.yml # release.yml's publish job asks for contents: write (tag and release). GitHub checks a called workflow's # permissions when the run starts, whether that job runs or not, so this is needed for its dry runs too. - # release.yml runs in the "release" concurrency group, where only one run waits: if another release is queued - # while this call waits, GitHub cancels this call. It then ends "cancelled", which is no failure, so report-failure - # does not run. master has the commit, so a later release includes it; run the Release workflow on master to - # release it at once. + # release.yml runs in the concurrency group publish-, here publish-refs/heads/master, shared with the releases + # of pushes to master; only one run waits in it: if another release of master is queued while this call waits, + # GitHub cancels this call. It then ends "cancelled", which is no failure, so report-failure does not run. master + # has the commit, so a later release includes it; run the Release workflow on master to release it at once. permissions: contents: write with: From b9a1d1313ef6b86133c3ecf339c9b994a4bf41b2 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:00:02 +0800 Subject: [PATCH 33/38] ci: describe what keeping the sync token out of .git/config does and does not protect --- .github/workflows/upstream-sync.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 73b6136..663afde 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -127,7 +127,10 @@ jobs: steps: - uses: actions/checkout@v7 with: - # Only the push step gets the token; the steps before it run downloaded tools. + # The token is not left in .git/config, where every step, and the tools it downloads and runs (ClangSharp, + # libclang, openslide-bin), could read it; only the Pin step (GitHub API) and the push step get it, in env. + # This job's token can write contents, though, and an earlier step can still change what a later one runs + # (GITHUB_PATH, GITHUB_ENV, git hooks), so this keeps the token out of plain sight, not from a malicious tool. persist-credentials: false - uses: actions/setup-dotnet@v6 with: From 08650ce9fda300ab3498db2035cf829d04073fdb Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:00:03 +0800 Subject: [PATCH 34/38] ci: say that the sync's fallback pull request needs a repository setting and gets no CI by itself A pull request opened with the workflow token starts no workflow, so CI runs on it only after it is closed and reopened; its description now says so. The merge job also notes that opening it needs "Allow GitHub Actions to create and approve pull requests". --- .github/workflows/upstream-sync.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 663afde..0ad34fb 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -215,6 +215,11 @@ jobs: merge: needs: [detect, update, ci] if: needs.detect.outputs.dry-run == 'false' + # The pull request fallback needs the repository setting "Allow GitHub Actions to create and approve pull + # requests" (Settings > Actions > General). Without it, opening the pull request fails (HTTP 403), so this job + # fails and report-failure opens an issue and deletes the branch. A pull request opened with the workflow token + # starts no workflow: CI does not run on it (a required status check would wait forever) until someone closes and + # reopens it or pushes to its branch, as its description says. runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -272,6 +277,8 @@ jobs: body=$(printf '%s\n' \ "openslide-bin \`$TAG\` passed CI on $SHA in $RUN_URL, but $reason, so it was not merged and nothing was released." \ "" \ + "A workflow opened this pull request, so no CI runs on it by itself: close and reopen it (or push to its branch) to run CI here." \ + "" \ "Merging this pull request starts the Release workflow, which tests the merged commit again before it publishes.") url=$(gh api --method POST "$repo/pulls" -f base=master -f head="$BRANCH" -f title="build: track openslide-bin $BIN_VERSION" -f body="$body" --jq .html_url) fi From f8d751dd919d2894f3d2a88ed28f0e0c5b00efc6 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:00:33 +0800 Subject: [PATCH 35/38] docs: state the server's limit on the Deep Zoom tile size plus twice the overlap --- src/OpenSlideSharp.AspNetCore/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/OpenSlideSharp.AspNetCore/README.md b/src/OpenSlideSharp.AspNetCore/README.md index 8389a83..3a84924 100644 --- a/src/OpenSlideSharp.AspNetCore/README.md +++ b/src/OpenSlideSharp.AspNetCore/README.md @@ -27,8 +27,8 @@ The native library is not included. Add the [OpenSlideSharp.runtime](https://www | `SlideCacheSize` | 10 | slides kept open, at least 1 | | `TileCacheSize` | 128 | MiB of OpenSlide tile cache shared by all open slides, at least 0; 0 keeps OpenSlide's own cache of each slide (32 MiB each) | | `ColorMode` | `Default` | see [Color](#color) | -| `DeepZoom:TileSize` | 254 | at least 1 | -| `DeepZoom:Overlap` | 1 | at least 0 | +| `DeepZoom:TileSize` | 254 | at least 1; `TileSize + 2 × Overlap` at most 536870911 (`int.MaxValue / 4`) | +| `DeepZoom:Overlap` | 1 | at least 0; see `TileSize` | | `DeepZoom:Format` | `Jpeg` | the format named in the DZI | | `DeepZoom:Quality` | 75 | JPEG quality, 0 to 100 | | `DeepZoom:LimitBounds` | `true` | only the non-empty slide region | From dba0f60c18dfc9aba4bb255b90a95eca2a0aaa2d Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:00:33 +0800 Subject: [PATCH 36/38] test: clear inherited package source mappings in the package smoke config --- test/PackageSmoke/NuGet.config | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/test/PackageSmoke/NuGet.config b/test/PackageSmoke/NuGet.config index 515e0ef..c89921c 100644 --- a/test/PackageSmoke/NuGet.config +++ b/test/PackageSmoke/NuGet.config @@ -6,8 +6,12 @@ - + + From 12f2e0128995037b34ac3e0f572316ada70c7f42 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:04:44 +0800 Subject: [PATCH 37/38] docs: record plan 5 carry-over items and mark plan 5 done --- docs/notes/2026-11-18-plan5-carryover.md | 118 ++++++++++++++++++ .../2026-11-17-openslidesharp-v4-roadmap.md | 2 +- 2 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 docs/notes/2026-11-18-plan5-carryover.md diff --git a/docs/notes/2026-11-18-plan5-carryover.md b/docs/notes/2026-11-18-plan5-carryover.md new file mode 100644 index 0000000..21e71e3 --- /dev/null +++ b/docs/notes/2026-11-18-plan5-carryover.md @@ -0,0 +1,118 @@ +# 计划 5 遗留事项(供以后使用) + +来源:计划 5(上游同步与发布)各任务审阅、整体终审及其修复轮。下列事项都已评估为**不阻塞计划 5 合并**。终审中要求在合并前、以及在设置 `NUGET_API_KEY` 之前修复的项目,已在修复轮中处理: +- `deepzoom` 的 `-s`/`-e` 过大时,先检查再动旧输出; +- README 写明快进之后发布失败的情况,以及没有 key 时同步仍会更新 `master`; +- 查看器归档不再带 runtime 包描述 nupkg 布局的 `LICENSE.txt`; +- release notes 按通道措辞,正式版紧接 nightly 发布时注明 `Native` 层可能少了只有 nightly 才有的函数; +- 三个查看器归档各自在本平台上运行 `--check`; +- 每个 ref 一个发布并发组; +- 同步回退 PR 的说明、文档与注释等小项。 + +## 设置 `NUGET_API_KEY` 之前(维护者操作) + +- **nuget.org 上的包 ID。** 预留 `OpenSlideSharp` ID 前缀,或先手动占住 4 个新 ID:`OpenSlideSharp.SkiaSharp`、`OpenSlideSharp.runtime`、`OpenSlideSharp.AspNetCore`、`OpenSlideSharp.Tool`。`OpenSlideSharp` 的 owner 是 `kiolp`。 +- **创建 key。** 由 `kiolp` 账号创建,glob 为 `OpenSlideSharp*`,勾选 “Push new packages and package versions”,存为仓库 secret `NUGET_API_KEY`。 +- **可以考虑 `environment: release`。** 把 key 放进一个部署分支只允许 `master` 的 environment,并给 release.yml 的 publish job 加上 `environment: release`。这样“只有 master 能拿到 key”由平台保证。 +- **旧包弃用。** 在 nuget.org 上把 README “Old packages” 一节列出的 6 个 1.x 包标记为弃用,并指向替代包: + - `OpenSlideSharp.Interop` + - `OpenSlideSharp.Windows` + - `OpenSlideSharp.runtime.win` + - `OpenSlideSharp.BitmapExtensions` + - `OpenSlideSharp.OpenCVExtensions` + - `OpenSlideSharp.BruTile` +- **如果要重建仓库历史,必须在设置 key 之前完成。** + - v1.0.1.3、v1.1.0、v1.1.1 所指的提交必须仍是新 `master` 的祖先,或者删除、移动这三个 tag。否则 `Test-ReleaseCommit` 会让每一次发布都失败(“does not contain the latest release”)。 + - 一旦开始发布 4.x,再改写历史会让 4.x 的 tag 也失效。 +- **保持仓库设置 “Allow GitHub Actions to create and approve pull requests” 开启。** `master` 在同步期间移动时,同步改为开 PR,这一步需要该设置。 + +## 合并之后、设置 key 之前 + +- 合并触发的 push 运行本身就是一次 Release 演练:确认它为绿色,并且没有 tag、Release 或包。 +- 在 `master` 上分别 dispatch 一次 Release 和 Upstream sync,都设 `dry_run=true`。sync 的预期结果是 detect 输出 `[]`。 +- 检查 Release 运行中的 `viewer check (win-x64)` 与 `viewer check (osx-arm64)`: + - 两个归档都在本平台上运行 `--check` 成功; + - Windows 上的 ProductVersion、应用清单和 GUI 子系统都通过检查。 + - win-x64 归档是在 Linux 上交叉发布的。.NET 8 起,SDK 在任何主机上都会把版本资源和清单写进 Windows 可执行文件,不再给出 NETSDK1074。这里第一次在 CI 中实际验证这一点。 + - 再下载 `viewer-win-x64` artifact,在 Windows 桌面上打开一次并查看文件属性;在 Mac 上运行一次 osx-arm64 归档,包括 Gatekeeper 的提示。 +- 合并后,第一次遇到上游新构建的每日同步就会以 IOL0ol1 身份向 `master` 提交。sync 的 update → ci → merge → release → report-failure 整条链路,要等上游出现新的 nightly 才会第一次真实运行;没有 key 时,其中的 release 是演练。 + +## 以后处理 + +### 发布流程(release.yml 与 eng 脚本) + +- **排队中的发布仍可能被同组的后来者取消。** + - 现在每个 ref 一个并发组(`publish-`),分支上的演练不再影响 `master`。 + - 但 `master` 上 push 触发的发布和 sync 调用的发布仍在同一组。被取消的 sync 调用以 cancelled 结束,不会开 issue。 + - GitHub 已支持 `concurrency.queue: max`(最多 100 个排队)。actionlint 1.7.12 还不认识这个键,等 actionlint 支持后可以改用。 +- **`gh release view … 2> /dev/null` 把所有错误都当成 “Release 不存在”。** 判断附件是否已上传时,只比较文件名,不比较 state 和 size。 +- **key 和写权限 token 的暴露面。** + - key 的判空在 checkout 之后,此前已经运行了仓库里的代码。 + - publish job 的 checkout 把写权限 token 留在 `.git/config`。 + - 可以改为:把判空放到第一步;publish 用 `persist-credentials: false`,只在打 tag 的那一步传入 token。 +- **正式版版本号末段为 `.0` 时,NuGet 会规范化文件名**(`X.Y.Z.0` 写成 `X.Y.Z`)。`Get-ReleaseFiles` 和 `Test-Packages` 会在推送之前失败。openslide-bin 4.x 迄今没有这样的版本。 +- **部分推送后点错重跑按钮的窄缝。** + - 较新提交的发布只推了一部分包、tag 尚未推送时,对旧提交的运行点 “Re-run all jobs” 看不到这次部分发布。 + - nuget.org 索引完成之前,flat container 返回 404,而 `--skip-duplicate` 会吞掉 409。 + - 可以在推送前再读取 nuget.org 上最高版本的 nuspec commit,要求它是 `$SHA` 的祖先或 `$SHA` 本身。 +- **清单停在已过期的 nightly 时,`Get-ReleaseFiles` 只从上游 URL 下载源码包,会失败。** 可以在失败时回退到本仓库同一 binVersion 的旧 Release 附件(低优先级)。 + +### 版本号与上游检测脚本 + +- **`Get-ReleaseVersion` 的输入校验。** + - 不校验清单的 `date`(`YYYY-MM-DD`)和 `openslideCommit`(至少 8 位十六进制)。 + - `ConvertTo-NuGetVersion` 接受空标识符和带前导 0 的数字标识符。 + - stable 路径也会无条件计算 nightly 基线。 + - 格式错误会在 pack 阶段失败,早于推送。 +- **最新 nightly 解析失败时,新的正式版也会被挡住。** 在 `Find-UpstreamUpdate` 中,如果 release 正文缺少 OpenSlide 行,或版本没有 `-g`,整个脚本失败。同时出现的新正式版,要等 nightly 恢复后才会同步。失败是显式的。 + +### Upstream sync + +- **排队的运行,或 “Re-run all jobs”,用的是触发时的 `github.sha`。** 如果 `master` 已经包含同一构建,会再同步一次,多跑一遍 CI,并开出一个多余的 PR。detect 可以先用 `git ls-remote origin refs/heads/master` 与 `github.sha` 比较。 +- **分支和 PR 的清理。** + - 被取消、或被更新构建取代的运行,会留下 `sync/*` 分支和 PR。 + - report-failure 删除分支前,不检查该分支是否有打开的 PR,会因此关闭同一构建之前开的 PR。 + +### 打包与许可证 + +- `Test-Packages` 的 `Assert-DependencyGroups` 忽略不在依赖组里的依赖。目前 SDK 总是写成分组。 +- 查看器遇到旧的 `artifacts/native` 布局时,错误信息没有提示运行 `eng/Get-OpenSlide.ps1`。 +- 查看器生成 `SOURCE.md` 时,用正则取 `openslide-bin.json` 中第一个 `url`/`sha256`,不看它属于哪个对象。目前只有 `source` 有这两个键,`Publish-Viewer` 和 `Test-Packages` 也会与清单比对。 +- 本地或非发布的 publish 生成的 `SOURCE.md` 指向 `releases/tag/v0.0.0-local`,这个 Release 不存在。 +- 查看器 `THIRD-PARTY-NOTICES.txt` 中的 `` 有两种含义:openslide-bin 的平台键,以及 NuGet 包后缀(`Win32`、`Linux`、`macOS`、`win-x64`)。 + +### 工具 + +- `TileWriter` 用 `File.WriteAllBytes` 写 `..tmp`,会跟随这个路径上预先放好的符号链接。只影响 `.dzi`,场景很刻意;计划 5 之前就存在。 + +## 计划 5 中做出的裁定(摘要) + +- **R1**:release.yml 与 upstream-sync.yml 的端到端验证放在合并之后,在 `master` 上用 `workflow_dispatch` 演练。dispatch 只能运行默认分支上的 workflow。 +- **R2**:runtime 包和 tool 包用 `PackageLicenseFile`(`LICENSE.txt` 说明随附的各组件,全文在 `licenses/`),不用简化的 SPDX 表达式。随附内容涉及 LGPL-2.1、MIT、BSD、IJG、zlib、MPL、libtiff 等多种许可。 +- **R3**:计划 3 遗留的最后一批 API 事项延后:带 `HttpContext` 的异步解析器、命名选项、公开的 `Evict(SlideLease)`。它们都是新增 API,4.x 首次发布之后再加也不破坏兼容。 +- **R4**:interop job 的 pip 哈希锁定延后。该 job 只有只读权限,也不接触 secret。 +- **R5**:LGPL 源码的长期保存。 + - runtime 包的 `LICENSE.txt` 与 README、tool 包的 `LICENSE.txt`、查看器生成的 `SOURCE.md` 都写明:同版本的 GitHub Release(tag `v`)附带 `openslide-bin-.tar.gz`,可按文件名和 `source.sha256` 校验。 + - 查看器归档只带本 RID 平台的 openslide-bin 许可证。 +- **R6**:工具 `deepzoom` 在 `-s`/`-e` 过大时先删除旧输出再失败,属于数据安全回归,合并前必须修复(已修复)。同一任务的其他小问题在收尾时处理,或列入本文件。 +- **R7**:正式版的 `InformationalVersion` 也带 openslide 的 commit hash。 + - `Get-ReleaseVersion` 输出 `openslideUpstreamVersion`:`openslideVersion` 已含 `-g` 时就是它,否则为 `.g`。 + - `informationalVersion` = `+openslide.`。 +- **R8**:`Find-UpstreamUpdate` 列出 openslide-bin 的全部 release,按 NuGet 顺序取最高的非预发布版本,不用 `releases/latest`。latest 按创建时间排序,旧系列晚发的维护版会把新系列的正式版永远挡住。 +- **R9**:nuget.org 上已知存在 `OpenSlideSharp`,所以 flat container 返回 404 或空列表视为错误,而不是“尚未发布”。否则单调检查会悄悄失效。 +- **R10**:`.N` 取同一基础版本的已有 tag 与已发布版本中的最大值再加 1。这样包已推送而 tag 没打上时,后续发布不会卡住。 +- **R11**:同步调用发布时,传入快进到 `master` 的那个提交的 SHA,而不是 `master`。发布的正是通过同步 CI、并被快进的那个提交。`master` 已经移动时改开 PR,不发布。 +- **R12**:同步失败 issue 的去重和标题逻辑放在带 `-SelfTest` 的脚本里(`eng/Report-SyncFailure.ps1`,用模拟的 GitHub API),由 CI 的 scripts job 运行。 +- **R13**:merge 退回为 PR 时,保留同步分支(PR 需要它),并跳过发布。`sync/` 只在快进成功后或失败时删除;之前运行留下的同名分支会被替换。 +- **R14**:计划 5 的计划文件中有一句不符合仓库文字规范的措辞,由该计划的首个提交引入。合并前改写功能分支上 df839f7 之后的历史,从所有版本中删去这一句,并强推功能分支;`master` 和已有 tag 不动。 +- **R15**:收尾修复轮的范围。 + - 处理合并前必须修复的项、设置 key 之前必须修复的项、整体检查新发现的小问题,以及几处只需改注释或文档的小项;其余可以以后处理的事项记入本文件。 + - 以下几项不再处理: + - runtime csproj 硬编码四个平台键:`Test-Packages` 会断言许可证目录与清单的平台键一致; + - `Find-UpstreamUpdate` 接受 3 段 binVersion:openslide-bin 的版本都是 4 段; + - release.yml 的调用方必须授予 `contents: write`:upstream-sync 已授予,并写了注释; + - push 触发的路径不含查看器、`eng/` 脚本和 `global.json`:README 已写明这类改动要手动运行 Release。 + +## 已知问题(维护者决定只写文档) + +Windows 上遇到损坏的 JPEG/PNG 会触发 CFG/longjmp 崩溃,整个 .NET 进程被终止,工具、Web 示例和查看器也一样,详见 `docs/known-issues/windows-cfg-longjmp-crash.md`。 diff --git a/docs/plans/2026-11-17-openslidesharp-v4-roadmap.md b/docs/plans/2026-11-17-openslidesharp-v4-roadmap.md index b54279c..c2dc78e 100644 --- a/docs/plans/2026-11-17-openslidesharp-v4-roadmap.md +++ b/docs/plans/2026-11-17-openslidesharp-v4-roadmap.md @@ -10,6 +10,6 @@ | 2 | `2026-11-17-plan2-rendering.md`(已完成) | `PixelImage` 合成与缩放、共享渲染流程、`OpenSlide.GetThumbnail`、`DeepZoomGenerator`、`IColorTransform`、`OmeZarrGenerator`、`OpenSlideSharp.SkiaSharp`(§6.1 其余、§6.3、§8 中 DeepZoom / Skia / OME-Zarr) | 1 | | 3 | `2026-11-18-plan3-web-tool.md`(已完成) | `OpenSlideSharp.AspNetCore`、`samples/OpenSlideSharp.Web`、`OpenSlideSharp.Tool`(§6.4–§6.6) | 2 | | 4 | `2026-11-18-plan4-viewer.md`(已完成) | `samples/OpenSlideSharp.Viewer`(Avalonia)(§6.7) | 2 | -| 5 | plan5-release(待写) | 上游同步、版本号计算、发布、GitHub Release、README 重写、旧包弃用清单(§7.2、§7.3、§9) | 1–4 | +| 5 | `2026-11-18-plan5-release.md`(已完成) | 上游同步、版本号计算、发布、GitHub Release、README 重写、旧包弃用清单(§7.2、§7.3、§9) | 1–4 | 计划 3 与计划 4 互不依赖,可以并行。 From 38437ba5067b5a0b22259b31ef5440086d7f3b07 Mon Sep 17 00:00:00 2001 From: IOL0ol1 <1353839731@qq.com> Date: Thu, 19 Nov 2026 00:05:50 +0800 Subject: [PATCH 38/38] ci: compare the archived viewer's ProductVersion as a string, so a missing one is reported --- eng/Test-ViewerArchive.ps1 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/eng/Test-ViewerArchive.ps1 b/eng/Test-ViewerArchive.ps1 index 691e3d7..fbe52bb 100644 --- a/eng/Test-ViewerArchive.ps1 +++ b/eng/Test-ViewerArchive.ps1 @@ -116,10 +116,11 @@ try { # Copied from the managed assembly into the apphost; an SDK that cannot do that on the publishing host leaves # the apphost's own resources (NETSDK1074). $info = (Get-Item $exe).VersionInfo - Write-Host "ProductVersion: $($info.ProductVersion), FileVersion: $($info.FileVersion)" - $versionOk = $InformationalVersion ? $info.ProductVersion -ceq $InformationalVersion : ($info.ProductVersion -ceq $Version -or $info.ProductVersion.StartsWith("$Version+", [StringComparison]::Ordinal)) + $productVersion = "$($info.ProductVersion)" + Write-Host "ProductVersion: $productVersion, FileVersion: $($info.FileVersion)" + $versionOk = $InformationalVersion ? $productVersion -ceq $InformationalVersion : ($productVersion -ceq $Version -or $productVersion.StartsWith("$Version+", [StringComparison]::Ordinal)) if (-not $versionOk) { - throw "$exeName has ProductVersion '$($info.ProductVersion)', expected '$($InformationalVersion ? $InformationalVersion : $Version)'." + throw "$exeName has ProductVersion '$productVersion', expected '$($InformationalVersion ? $InformationalVersion : $Version)'." } $pe = Get-PeResourceInfo $exe Write-Host "Subsystem: $($pe.Subsystem), manifests: $($pe.Manifests.Count)"