1.0.0

LayoutX2C 1.0.0

中文

LayoutX2C 1.0.0 是首个稳定版本，提供编译期 Android XML Layout 到 Kotlin 代码的生成流程。

1.0 的核心约束是保守生成：支持的 XML 进入生成代码，不支持或无法确认等价的语义继续走平台 inflation，未支持的布局不应导致应用构建失败。这个版本适用于需要把热点 XML 布局 inflation 移到生成代码、但仍保留 Android 资源解析、主题系统、DataBinding 运行时和平台 LayoutInflater 行为的项目。

主要变化

• 稳定运行时 API 边界，使用 @PublicApi 和 @ExperimentalApi 区分兼容承诺。
• 提供 Android application 和 library 模块可用的 Gradle 插件，自动配置 KSP、runtime 依赖和 processor 参数。
• 支持通过 @FastLayoutConfig、@FastLayouts 和 @FastLayoutPattern 发现待生成布局。
• 提供 per-layout JSON 报告，以及项目级 layoutX2CReport HTML / JSON 汇总，便于在本地和 CI 中查看 fallback 情况。
• 对未支持节点、未支持属性、<include>、ViewStub 和 DataBinding 语义保持保守 fallback。
• 增量生成缓存按 layout 和资源依赖 digest 计算，覆盖递归 include 布局和引用到的 values 资源。
• 支持常见 Android / AndroidX View、ConstraintLayout 安全子集、style、资源引用、白名单自定义 View 和白名单 BindingAdapter 的静态生成。

从 0.4.1 到 1.0.0

• 增加稳定 public runtime API，作为 1.0 兼容契约的基础。
• 扩展 Text / View 展示属性、常见 widgets、容器、app bar、ScrollView / ImageView 组合，以及 ConstraintLayout 参数生成能力，包括 Guideline 和常见 chain 语义。
• 增加 @FastCustomViews 白名单自定义 View 生成能力，并支持识别继承自已支持平台容器的自定义 View。
• 增加白名单 DataBinding BindingAdapter 生成能力，并补齐 include、嵌套 include、生成字段、root 字段、变量、pending-binding 状态和部分双向绑定的 binding facade 支持。
• 改进 fallback 性能：批量处理 sibling / subtree fallback inflation，并缓存缺失的生成 registry 查询结果。
• 改进 codegen 性能：复用生成 factory 引用，减少重复 layout params 配置。
• 改进资源解析：支持 AGP resource symbol 文件、外部 R jar 和精确资源依赖 hash。
• 增加 Android 等价性覆盖，包含生成 inflate 行为、ViewStub、DataBinding、显式 View 属性、兼容 widgets 和 demo gallery 流程。
• 强化发布流程，支持 Maven Central GPG command signing 和 Central Portal bundle。

兼容信息

• Minimum SDK：23
• Compile SDK：36
• Target SDK：36
• Android Gradle Plugin：9.2.1
• Kotlin：2.2.21
• KSP：2.3.8
• Java source / target compatibility：11
• Release build toolchain：JDK 21

接入方式

plugins {
    id("io.github.donglua.layoutx2c") version "1.0.0"
}

手动依赖配置：

dependencies {
    implementation("io.github.donglua.layoutx2c:runtime:1.0.0")
    ksp("io.github.donglua.layoutx2c:ksp-processor:1.0.0")
}

发布坐标：

• io.github.donglua.layoutx2c:runtime:1.0.0
• io.github.donglua.layoutx2c:compiler-core:1.0.0
• io.github.donglua.layoutx2c:ksp-processor:1.0.0
• io.github.donglua.layoutx2c:gradle-plugin:1.0.0
• Gradle plugin id：io.github.donglua.layoutx2c

已知边界

• 未支持的 View 类或不安全属性仍会 fallback 到平台 inflation。
• RecyclerView 和 ViewPager2 只生成容器本身，adapter 和运行时行为仍由应用负责。
• DataBinding 支持是有边界的。LayoutX2C 不替代完整原生 DataBinding 运行时、表达式引擎、observable 订阅模型或 lifecycle 分发。
• 自定义 View 和 BindingAdapter 只有显式加入白名单后才会进入生成代码。

---

English

LayoutX2C 1.0.0 is the first stable release of the compile-time Android XML layout to Kotlin generation pipeline.

The 1.0 contract is intentionally conservative: supported XML is generated into code, unsupported or unsafe semantics continue to use platform inflation, and unsupported layouts should not break application builds. This release is meant for projects that want to move hot XML layout inflation paths to generated code while keeping Android resource resolution, theming, DataBinding runtime behavior, and platform LayoutInflater semantics intact.

Highlights

• Stable runtime-facing API boundary with @PublicApi and @ExperimentalApi annotations.
• Gradle plugin support for Android application and library modules, including automatic KSP, runtime dependency, and processor option wiring.
• Layout discovery through @FastLayoutConfig, @FastLayouts, and @FastLayoutPattern.
• Per-layout JSON reports plus project-level layoutX2CReport HTML / JSON summaries for fallback visibility in local builds and CI.
• Conservative fallback for unsupported nodes, unsupported attributes, <include>, ViewStub, and DataBinding semantics.
• Incremental generation cache keyed by layout and resource dependency digests, including recursively included layouts and referenced values resources.
• Static generation support for common Android / AndroidX views, safe ConstraintLayout subsets, styles, resource references, whitelisted custom views, and whitelisted BindingAdapter calls.

Changes since 0.4.1

• Added a stable public runtime API surface for the 1.0 compatibility contract.
• Expanded generation coverage for Text / View presentation attributes, common widgets, containers, app bars, ScrollView / ImageView combinations, and ConstraintLayout params including Guideline and common chain semantics.
• Added safe custom view generation through @FastCustomViews, including custom views that inherit from supported platform containers.
• Added whitelisted DataBinding BindingAdapter generation and native-style binding facade support for includes, nested includes, generated fields, root fields, variables, pending-binding state, and selected two-way bindings.
• Improved fallback performance by batching sibling / subtree fallback inflation and caching missing generated registry lookups.
• Improved codegen performance by reusing generated factory references and reducing repeated layout params configuration.
• Improved resource resolution for AGP resource symbol files, external R jars, and precise resource dependency hashing.
• Added Android equivalence coverage for generated inflate behavior, ViewStub, DataBinding, explicit View properties, compatibility widgets, and demo gallery flows.
• Hardened release publishing with Maven Central GPG command signing and a Central Portal bundle path.

Compatibility

• Minimum SDK: 23
• Compile SDK: 36
• Target SDK: 36
• Android Gradle Plugin: 9.2.1
• Kotlin: 2.2.21
• KSP: 2.3.8
• Java source / target compatibility: 11
• Release build toolchain: JDK 21

Setup

plugins {
    id("io.github.donglua.layoutx2c") version "1.0.0"
}

Manual dependency setup:

dependencies {
    implementation("io.github.donglua.layoutx2c:runtime:1.0.0")
    ksp("io.github.donglua.layoutx2c:ksp-processor:1.0.0")
}

Published coordinates:

• io.github.donglua.layoutx2c:runtime:1.0.0
• io.github.donglua.layoutx2c:compiler-core:1.0.0
• io.github.donglua.layoutx2c:ksp-processor:1.0.0
• io.github.donglua.layoutx2c:gradle-plugin:1.0.0
• Gradle plugin id: io.github.donglua.layoutx2c

Known boundaries

• Unsupported View classes or unsafe attributes still fall back to platform inflation.
• RecyclerView and ViewPager2 are generated as containers only. Adapter and runtime behavior remain application-owned.
• DataBinding support is intentionally scoped. LayoutX2C does not replace the full native DataBinding runtime, expression engine, observable subscription model, or lifecycle dispatch.
• Custom views and BindingAdapters only enter generated code when explicitly whitelisted.

0.4.1

更新内容

• 修复 Binding facade 字段类型收集逻辑，保留 XML 中具体 View 类型，避免生成 binding 字段退化成过宽类型。
• 修复 LayoutX2C 升级后仍可能复用旧 KSP digest cache 的问题。
• digest 兼容键现在包含处理器 Implementation-Version，XML 未变但处理器版本变化时会自动重新生成产物，避免旧 fallback 输出被恢复。
• Gradle 插件内置 runtime / ksp-processor 依赖版本同步升级到 0.4.1。

Commits

• 8f7971c fix(binding): preserve concrete view field types
• e68ca5c fix(ksp): invalidate stale generated cache on upgrades

验证

• ./gradlew test :demo:assembleDebug :runtime:assembleRelease :demo:assembleRelease :demo:assembleDebugAndroidTest
• GitHub Release workflow 通过，Maven artifacts 已发布。

LayoutX2C 0.4.0

主要更新

• 为支持的 DataBinding 布局生成继承 ViewDataBinding 的 {Name}X2CBinding facade。
• fallback 子节点 inflate 改为走平台 XML parser 路径，提升 fallback 语义一致性。
• DataBinding + ConstraintLayout root 在符合安全子集时保持生成路径。
• 版本命名统一使用裸版本 tag：0.4.0。

验证

• ./gradlew test :demo:assembleDebug :runtime:assembleRelease :demo:assembleRelease :demo:assembleDebugAndroidTest --no-daemon --console=plain
• ./gradlew :demo:kspDebugKotlin :demo:compileDebugKotlin --rerun-tasks --no-daemon --console=plain
• ./gradlew :compiler-core:publishToMavenLocal :ksp-processor:publishToMavenLocal :gradle-plugin:publishToMavenLocal :runtime:publishReleasePublicationToMavenLocal --no-daemon --console=plain
• GitHub Actions Release workflow 已在 0.4.0 tag 上成功完成。

说明

• 复杂 DataBinding 表达式、BindingAdapter、Observable / LiveData 订阅和 lifecycle observer 语义仍交给原生 DataBinding runtime。
• 不支持或无法安全等价生成的布局语义仍会 fallback 到平台 LayoutInflater。

0.3.5

修复

• 裸 KSP 接入时，优先从配置类中的 R import / 全限定 R.layout.* 推导生成代码使用的 R 包，避免源码 package 与 Android namespace 不一致时生成错误 R 引用。
• 找不到源码 R 引用时，兜底从 Android Gradle namespace 推导 R 包。

0.3.4

修复

• 修复 fallback 子节点的 dp LayoutParams 生成代码漏声明 density，避免 KSP 生成 Kotlin 编译时报 Unresolved reference 'density'。

发布

• 版本号更新到 0.3.4。
• 发布流水线在未配置 Gradle Plugin Portal 密钥时跳过 plugin portal 发布，避免影响 Maven artifacts 发布。

0.3.3

修复

• 修复 LayoutX2C 在 nonTransitiveRClass 下把依赖模块资源硬生成当前模块 R 引用的问题。
• 对无法确认 owner 的资源引用走 fallback，避免生成不可编译的 R.color/R.drawable/R.string/R.dimen 静态引用。
• 支持已知 owner 时生成全限定 owner R 引用。
• Release workflow 改为数字版本 tag 触发，版本号不再带 v 前缀。

验证

• ./gradlew test

0.3.0

主要变化

• 增加项目级 layoutX2CReport 汇总任务，输出稳定 JSON 和可读 HTML 报告。
• 支持通过 maxFallbackLayouts 和 failOnFallbackReasons 配置 CI fallback policy。
• LayoutDigest 纳入 include / ViewStub layout 引用图，被引用 layout 变更会触发引用方重新生成。
• 保持保守 cache 语义：digest 未变时可恢复 per-layout factory、facade 和 report，避免无意义重生成。
• 更新 Roadmap，把已完成的报告产品化和 include digest 从 Next 收敛到 Current，并明确下一步为 Android 等价性测试、README/Demo 同步和精确资源引用图。

验证

已执行：

./gradlew test :demo:assembleDebug :runtime:assembleRelease :demo:assembleRelease :demo:assembleDebugAndroidTest

结果：BUILD SUCCESSFUL。

已知后续

• values XML 仍作为 coarse input，style / dimen / color / string / drawable 精确引用图留到后续版本。
• Android generated vs inflated 等价性测试还需要继续系统补齐。