diff --git a/work/notes/webkit-macos-version-mapping.md b/work/notes/webkit-macos-version-mapping.md index c97a99ca..be02b5c8 100755 --- a/work/notes/webkit-macos-version-mapping.md +++ b/work/notes/webkit-macos-version-mapping.md @@ -1,80 +1,291 @@ --- -title: WebKit release → macOS version mapping -tags: [webkit, safari, macos, reference] +title: WebKit release ↔ macOS build mapping +tags: [webkit, safari, macos, crash, ravel, reference] created: 2026-10-06 -source: ~/Downloads/WebKit_sparse (git checkout of github.com/WebKit/WebKit, main @ 99051d5d08) +updated: 2026-10-06 +sources: + - ~/Downloads/WebKit_sparse + - https://ravel.dbg.re + - https://github.com/mdn/browser-compat-data/blob/main/browsers/safari.json --- -# WebKit release → macOS version mapping +# WebKit release ↔ macOS build mapping -## TL;DR -Готовой опубликованной таблицы «релиз WebKit → macOS-релиз» не существует. -Маппинг **выводится из исходников** — он в самом дереве WebKit, а не на сайте. +## Коротко -## Механизм (ground truth) +DuckDuckGo поддерживает macOS **12.3+** (`main/macOS/Configuration/Common.xcconfig`). -AppleWebKit-версия в User-Agent собирается из двух частей: +Точное соответствие строится для **конкретного macOS build**, а не только для major/minor: -``` -AppleWebKit = SYSTEM_VERSION_PREFIX (зависит от macOS) + FULL_VERSION WebKit +```text +macOS version + build + → UUID WebKit из crash log + → тот же UUID в Ravel + → CFBundleVersion системного WebKit + → убрать macOS SYSTEM_VERSION_PREFIX + → FULL_VERSION WebKit + → найти WebKit source tag/branch + → проверить нужный commit или изменение кода ``` -### 1. macOS → SYSTEM_VERSION_PREFIX +Если точный source tag ещё не опубликован, соответствие заканчивается на версии бинарника. Наличие конкретного source fix тогда нельзя доказать одним номером версии. -Файл: `Configurations/Version.xcconfig`, строки 35–53. +## Не путать версии -| macOS | SYSTEM_VERSION_PREFIX | -|---|---| -| 15 Sequoia | 20 | -| 16 | 21 | -| 26 Tahoe | 21 | -| 27 Golden Gate | 22 | -| 28 | 23 | -| 29 | 24 | -| 30 | 25 | -| (default) | 22 | +| Значение | Пример | Назначение | +|---|---:|---| +| macOS version | `27.0.1` | Marketing version | +| macOS build | `26A434` | Точная сборка ОС; ключ для Ravel | +| Mach-O UUID | `70BEE322-…` | Точная идентичность бинарника WebKit | +| WebKit `CFBundleVersion` | `22625.1.29.11.28` | Версия системного framework | +| `SYSTEM_VERSION_PREFIX` | `22` | Префикс, зависящий от macOS major | +| WebKit `FULL_VERSION` | `625.1.29.11.28` | Версия release train без системного префикса | +| WebKit source tag | `WebKit-7625.1.29.11.28` | Ожидаемое имя тега исходников | +| HTTP User-Agent | `AppleWebKit/605.1.15` | Заморожен; для маппинга непригоден | -### 2. FULL_VERSION WebKit (текущий main) +## Базовые release-линейки macOS 12+ -`Configurations/Version.xcconfig`: -- MAJOR = 627, MINOR = 1, TINY = 2 → FULL_VERSION = `627.1.2` +Это соответствие **GA macOS major → Safari major → базовая WebKit-линейка**. Оно не заменяет проверку конкретного macOS build: Safari/WebKit обновляется внутри одного macOS major. -### Пример сборки UA-токена +| macOS | Минимум DDG | Prefix | Safari GA | WebKit base | Production bundle base | Expected source-tag family | +|---|---:|---:|---:|---:|---:|---| +| 12 Monterey | 12.3 | `17` | 15 | `612.1.27` | `17612.1.27` | `WebKit-7612.1.27.*` | +| 13 Ventura | да | `18` | 16 | `614.1.25` | `18614.1.25` | `WebKit-7614.1.25.*` | +| 14 Sonoma | да | `19` | 17 | `616.1.27` | `19616.1.27` | `WebKit-7616.1.27.*` | +| 15 Sequoia | да | `20` | 18 | `619.1.26` | `20619.1.26` | `WebKit-7619.1.26.*` | +| 26 Tahoe | да | `21` | 26 | `622.1.22` | `21622.1.22` | `WebKit-7622.1.22.*` | +| 27 Golden Gate | да | `22` | 27 | `625.1.29` | `22625.1.29` | `WebKit-7625.1.29.*` | +| 27.2 beta | да | `22` | 27.2 | `625.2.4` | `22625.2.4` | ожидается `WebKit-7625.2.4.*` | -| macOS | prefix | AppleWebKit/… | -|---|---|---| -| 15 Sequoia | 20 | `20627.1.2` | -| 16 | 21 | `21627.1.2` | -| 26 Tahoe | 21 | `21627.1.2` | -| 27 Golden Gate | 22 | `22627.1.2` | -| 30 | 25 | `25627.1.2` | +Источники базовых версий: MDN `browsers/safari.json` и Apple Safari release notes. Prefix 12–14 подтверждается `Configurations/Version.xcconfig` в `WebKit-7616.1.27`; prefix 15–30 — текущим `Configurations/Version.xcconfig`. -> Примечание: префиксы 21 у macOS 16 и 26 — это одно и то же системное поколение нумерации, отсюда совпадение. +## Точные сборки, проверенные через Ravel -## Что есть в дереве +Ravel сейчас индексирует не все исторические macOS. Отсутствие записи означает пробел покрытия Ravel, а не отсутствие WebKit в macOS. -| Что | Путь | Содержимое | -|---|---|---| -| macOS → prefix + текущая версия | `Configurations/Version.xcconfig` | таблица префиксов + MAJOR/MINOR/TINY | -| macOS ↔ кодовые имена | `Tools/Scripts/webkitpy/common/version_name_map.py` | Leopard … Tahoe, Golden Gate | -| таймлайн релизов WebKit | `git log Configurations/Version.xcconfig` | коммиты «Versioning. WebKit-XXXX.Y.Z» | -| отгруженные релизы | `git ls-remote --heads origin` | 498 веток `safari-XXXX-branch` | -| генератор deployment target | `Configurations/Scripts/generate-deployment-target-xcconfig.py` | 6-значные minor-версии → semver | +| macOS | Build | WebKit UUID | CFBundleVersion | FULL_VERSION | +|---|---|---|---:|---:| +| 26.5.2 | `25F84` | `49B21D99-8716-31B8-8686-71B287325F1D` | `21624.2.5.11.8` | `624.2.5.11.8` | +| 26.6 | `25G72` | `B090AABF-9A3B-3110-9DA9-F0F40FCEC972` | `21624.4.5.11.5` | `624.4.5.11.5` | +| 26.6.1 | `25G76` | `B090AABF-9A3B-3110-9DA9-F0F40FCEC972` | `21624.4.5.11.5` | `624.4.5.11.5` | +| 26.6.2 | `25G83` | `844AF253-CAF6-3623-9DAD-A055C5274E62` | `21624.5.1.11.3` | `624.5.1.11.3` | +| 27.0.1 | `26A434` | `70BEE322-37EE-3B22-8012-4F76BA105C29` | `22625.1.29.11.28` | `625.1.29.11.28` | +| 27.2 beta | `26B5086k` | `6F6AB57E-1492-3950-9962-85B6AFD430A3` | `22625.2.4.1` | `625.2.4.1` | +| 27.2 beta 2 | `26B5091g` | `56B4AA44-CB66-3641-8B22-723C39B5BC6E` | `22625.2.5.11.1` | `625.2.5.11.1` | +| 27.2 beta 3 | `26B5101f` | `B32D7081-AE42-3A2E-ACBB-CF4D4BE4F296` | `22625.2.7.1` | `625.2.7.1` | -## Чего в дереве НЕТ -Готовой таблицы «релиз WebKit → macOS-релиз». Она собирается из трёх источников: -1. prefix-таблица (в дереве, `Version.xcconfig`); -2. Apple Safari/iOS release notes — какая версия вошла в какой macOS; -3. `git log Configurations/Version.xcconfig` — таймлайн бампов версии. +Пример показывает, почему нужен UUID: macOS 26.6 и 26.6.1 используют один и тот же WebKit binary — совпадают и UUID, и `CFBundleVersion`. -## Источники (проверено) -- Файл: `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig` — 76 строк, 3640 байт. -- Строки 35–53 — таблица префиксов и `SYSTEM_VERSION_PREFIX_macosx_*`. -- Строки 24–29 — MAJOR/MINOR/TINY/FULL. -- Источник: рабочий чекаут Alex (`WebKit_sparse`), не внешний сайт. +## Полная методика -## Pitfalls -- Префикс `SYSTEM_VERSION_PREFIX_macosx_` (пустой) = `22` — это default для неизвестного macOS; не путать с реальным. -- `Version.xcconfig` есть **только** в `Configurations/` (один файл); вложенных копий в `Source/` нет. -- Sparse/shallow клоны содержат лишь ~10 последних бампов версии — полная история требует полного клона. -- Ветки `origin` содержат `integration/...safari-XXX-branch` (мусор от CI) — фильтровать по чистому `^safari-[0-9.]*-branch$`. +### 1. Извлечь macOS build и UUID из crash log + +```bash +rg 'OS Version:|WebKit \(arm64e\)' +``` + +Нужны: + +```text +OS Version: macOS 27.0.1 (26A434) +WebKit (arm64e) <70BEE322-37EE-3B22-8012-4F76BA105C29> +``` + +UUID сравнивать без учёта регистра и дефисов. Для Intel и Apple Silicon UUID могут различаться; архитектура должна совпадать. + +### 2. Найти тот же бинарник в Ravel + +Искать путь: + +```text +/System/Library/Frameworks/WebKit.framework/Versions/A/WebKit +``` + +URL-шаблон: + +```text +https://ravel.dbg.re/binary?build=&domain=dyld_cache&path=%2FSystem%2FLibrary%2FFrameworks%2FWebKit.framework%2FVersions%2FA%2FWebKit +``` + +Проверить в `Binary metadata and fingerprint`: + +1. macOS build; +2. архитектуру; +3. UUID — должен совпасть с crash log. + +В `Quick search` искать начало bundle version: `17`, `18`, `19`, `20`, `21` или `22`. В restricted strings находится полный номер вроде `22625.1.29.11.28`. + +### 3. Получить версию непосредственно на Mac + +```bash +sw_vers +defaults read /System/Library/Frameworks/WebKit.framework/Resources/Info CFBundleVersion +``` + +Из приложения: + +```swift +let webKitBundleVersion = Bundle(for: WKWebView.self) + .object(forInfoDictionaryKey: "CFBundleVersion") as? String +``` + +Это проверено на macOS 26.7.1: возвращается `21624.5.1.11.3`. + +### 4. Убрать системный prefix + +Production WebKit собирает номер так: + +```text +CFBundleVersion = SYSTEM_VERSION_PREFIX + FULL_VERSION +``` + +| macOS | Prefix | +|---|---:| +| 12 | `17` | +| 13 | `18` | +| 14 | `19` | +| 15 | `20` | +| 16 / 26 | `21` | +| 27 | `22` | +| 28 | `23` | +| 29 | `24` | +| 30 | `25` | + +Пример: + +```text +22625.1.29.11.28 - prefix 22 = 625.1.29.11.28 +``` + +### 5. Построить имя source tag + +Современные Apple release tags обычно называются: + +```text +WebKit-7 +``` + +Пример: + +```text +FULL_VERSION: 625.1.29.11.28 +candidate tag: WebKit-7625.1.29.11.28 +``` + +Проверить точный тег: + +```bash +git ls-remote --tags origin \ + 'WebKit-7625.1.29.11.28' \ + 'WebKit-7625.1.29.11.28^{}' +``` + +Если точного тега нет, найти опубликованную семью: + +```bash +git ls-remote --tags origin 'WebKit-7625.1.29*' +git ls-remote --heads origin 'safari-7625*' +``` + +Отсутствующий exact tag нельзя заменять ближайшим и считать точным соответствием. Ближайший тег даёт только нижнюю или верхнюю границу. + +### 6. Проверить наличие fix в source release + +Надёжнее проверять изменённый код, а не только ancestry: Apple может cherry-pick fix с другим commit SHA. + +Для текущего бага: + +```bash +git show :Source/WebKit/UIProcess/WebFrameProxy.h \ + | rg 'commitCertificateInfo' +``` + +Старая версия: + +```cpp +void commitCertificateInfo(const URL&); +``` + +Исправленная версия (`318982@main`): + +```cpp +void commitCertificateInfo(const URL&, bool hasCertificateInfo); +``` + +Дополнительно искать bug id и commit message: + +```bash +git log --grep='321456' +git log --grep='Send bool indicating presence of CertificateInfo' +``` + +### 7. Если exact source tag отсутствует + +Остаются три уровня доказательства: + +1. точный UUID + `CFBundleVersion` — доказана версия бинарника; +2. символ crash stack или disassembly — можно доказать конкретную сигнатуру/поведение бинарника; +3. воспроизведение теста на нужном macOS build — можно доказать наличие или отсутствие бага. + +Версия STP не доказывает версию системного WebKit: Safari Technology Preview — отдельная сборка. + +## Текущий баг: результат сопоставления + +### macOS 27.0.1 + +```text +macOS: 27.0.1 (26A434) +Crash UUID: 70BEE322-37EE-3B22-8012-4F76BA105C29 +Ravel UUID: 70BEE322-37EE-3B22-8012-4F76BA105C29 +CFBundleVersion: 22625.1.29.11.28 +Prefix: 22 +FULL_VERSION: 625.1.29.11.28 +Expected tag: WebKit-7625.1.29.11.28 +``` + +Exact tag `.11.28` публично не найден; опубликована `.11.27`. Базовая ветка `WebKit-7625.1.29` содержит старую одноаргументную сигнатуру. Crash stack также показывает: + +```text +WebKit::WebFrameProxy::commitCertificateInfo(WTF::URL const&) +``` + +Вывод: **в macOS 27.0.1 fix отсутствует**. + +### macOS 27.2 beta + +Ravel подтверждает бинарные версии `625.2.4.1`, `625.2.5.11.1` и `625.2.7.1` для beta 1–3. Публичных `WebKit-7625.2.*` tags/branches пока нет. + +Fix `318982@main` вошёл в STP 251, но это не доказывает его inclusion в системный WebKit macOS 27.2. + +Вывод: **macOS 27.2 — сильный кандидат на первую исправленную версию, но source inclusion пока не доказан**. + +## Телеметрия DuckDuckGo + +Текущие pixels не отправляют точный `CFBundleVersion` WebKit. HTTP UA использовать нельзя: WebKit намеренно возвращает замороженный `AppleWebKit/605.1.15`. + +Для корреляции crash/pixel с таблицей выше нужен параметр: + +```text +webkit_build=22625.1.29.11.28 +``` + +Получать его через `Bundle(for: WKWebView.self).CFBundleVersion`, а не через `WebKitVersionProvider`, который парсит замороженный UA. + +## Источники + +- `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig` +- `~/Downloads/WebKit_sparse/Source/WebCore/platform/mac/UserAgentMac.mm` +- `main/macOS/Configuration/Common.xcconfig` +- [Ravel binary catalogue](https://ravel.dbg.re/browse) +- [MDN Safari → WebKit versions](https://github.com/mdn/browser-compat-data/blob/main/browsers/safari.json) +- [Safari release notes](https://developer.apple.com/documentation/safari-release-notes) +- [WebKit commit 318982@main](https://commits.webkit.org/318982@main) +- [Safari Technology Preview 251](https://webkit.org/blog/18194/release-notes-for-safari-technology-preview-251/) + +## Ограничения + +- Ravel находится в beta и имеет неполное покрытие. +- Один macOS major содержит много Safari/WebKit updates; базовая таблица не заменяет lookup конкретного build. +- Совпадение версии без UUID слабее, чем совпадение версии и UUID. +- Exact tag может быть опубликован позже бинарника Apple. +- Cherry-pick может иметь другой SHA; проверять итоговый код в release tag.