--- theme: github highlight: github --- > * 本文仅关注 **Kotlin/Native**、**Kotlin/JS**两个平台的插桩能力，Android 平台继续使用 Transform > * 本文重在探讨方案的实现思路，包含较多 Kotlin 编译器源码与流程分析、调试思路等，如果只想了解框架如何使用那么只需关注「**如何使用 EzHook**」、**「如何实现自定义 Transform**」两节即可 > * 本文基于 Kotlin 2.0.21 版本分析 # 背景 Kotlin Multiplatform近年来逐渐崭露头角，已成为备受关注的跨平台开发方案。它支持代码在 Android、iOS、Web、Destop 等多个平台之间复用，能够大幅提升开发效率与需求的多端一致性。并且随着鸿蒙 Next 的发布，越来越多公司开始着手适配 KMP 以满足未来移动端跨平台开发的需求，由此可见 KMP的发展潜力不可小觑。然而，在将 KMP 应用到实际项目中时发现缺少一个关键能力——「**代码插桩**」。这一能力对于修改第三方库、面向切片编程（AOP）以及构建业务框架等场景至关重要。在 Android 平台上，我们可以基于 **Transform** 实现自定义的字节码转换，并且社区也提供了丰富的 AOP 框架（如 [Lancet](https://github.com/eleme/lancet)）。但目前还没有一款基于 KMP 的类 Transform 能力与对应的 AOP 框架，因此本文将探索 KMP 平台上类 Transform 能力，并基于该能力开发一款适用于 KMP 的 AOP 框架——**EzHook**。 # 如何使用 EzHook > [Github 地址](https://github.com/XDMrWu/EzHook) ## 依赖配置 > 顶层组件：对于 Kolint/Native 和 Kotlin/JS 来说都会有一个处于上层的组件用于产出对应的 so 或 js 产物，这个组件我们称为顶层组件 EzHook 包含 Gradle 插件、运行时 Library 两部分，Gradle 插件提供了编译期信息采集与 IR 转换的能力，需要在顶层组件引入 ```kotlin // 根目录 build.gradle.kts buildscript { dependencies { classpath("io.github.xdmrwu:ez-hook-gradle-plugin:0.0.2") } } // 顶层组件 plugins { id("io.github.xdmrwu.ez-hook-gradle-plugin") } ``` Library则提供了必要的注解与运行时能力，在使用到 EzHook 的模块依赖即可 ```Kotlin kotlin { sourceSets { commonMain.dependencies { implementation("io.github.xdmrwu:ez-hook-library:0.0.2") } } } ``` 为了使 EzHook 生效还需要关闭 Kotlin/Native 的缓存机制 ```Properties // gradle.properties kotlin.native.cacheKind=none ``` ## 使用方式 EzHook是一个类似 Lancet 的 AOP 框架，可以将任意方法在编译期替换为指定方法，只需要提供一个 Hook 方法并添加 `@EzHook` 注解指定目标方法即可 ```Kotlin @HiddenFromObjC @EzHook("kotlin.time.Duration.toInt") fun toInt(unit: DurationUnit): Int { println("Hook to int") return 10086 } ``` 上述代码则会将`Duration`类的 toInt 方法替换为当前的 toInt 方法，需要注意的是 * `@EzHook`注解提供的是目标方法的fqName，也支持顶层方法 * Hook 方法的方法名可以随意写，但是参数数量、类型与返回值类型需要与目标方法保持一致 * Hook 方法必须是顶层方法 * 如果目标平台包括 iOS，需要添加`@HiddenFromObjC`注解 ### 调用原始方法框架也支持在 Hook 方法中调用目标方法，并修改参数。具体做法为 * 创建一个与参数同名同类型的变量来覆盖原始参数 * 通过 `callOrigin` 来调用目标方法 ```Kotlin @HiddenFromObjC @EzHook("kotlin.time.Duration.toInt") fun toInt(unit: DurationUnit): Int { val unit = DurationUnit.HOURS return callOrigin() } ``` ### 内联 Hook 方法由于 JS 模块循环依赖时容易出现运行时崩溃，框架支持将 Hook 方法内联到目标方法模块中，以此避免生成的 JS 代码存在模块间的循环依赖。只需要在 `@EzHook`注解中配置参数 `inline=true` 即可 ```Kotlin @EzHook("kotlin.time.Duration.toInt", true) fun toInt(unit: DurationUnit): Int { val unit = DurationUnit.HOURS return callOrigin() } ``` 需要注意的是Hook 方法不能依赖当前模块其他方法或变量，否则还是会出现循环依赖的问题，在实际应用中可以参考下面两条原则 * **如何判断是否需要 inline**：当目标平台包括 Kotlin/JS，且 **Hook 方法所在模块**位于**目标方法所在模块**上层 * **如何判断 Hook 方法是否可以 inline**：Hook 方法所引用的类、方法、变量所在的模块均可以被目标模块依赖 # 如何实现自定义 Transform **Transform**为 EzHook 框架提供了 IR 转换的底座，但是由于 KCP 模块无法引入外部依赖的限制，当前无法提供一个独立的**Transform** 产物用于接入，只能通过拷贝代码到自己的 GradlePlugin、KCP模块中实现，下面将介绍如何基于这种方式使用 Transform 基座。 ## 接入 Transform 1. 拷贝 [KotlinJsIrLinkConfig.kt](https://github.com/XDMrWu/EzHook/blob/main/gradle_plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/tasks/configuration/KotlinJsIrLinkConfig.kt) 到你的 Gradle Plugin 模块中，请注意保持包名一致，并且在 classpath 中将该 Gradle Plugin 放在最前面 2. 拷贝 [hook](https://github.com/XDMrWu/EzHook/tree/main/compiler_plugin/src/main/kotlin/com/wulinpeng/ezhook/compiler/hook) 目录下的代码到你的 KCP 模块中 ## 注册 `IrLoweringHookExtension` 在你的`CompilerPluginRegistrar`中通过调用`IrLoweringHookExtension.registerExtension`完成 Hook 并注册自定义的 `IrLoweringHookExtension`，`IrLoweringHookExtension`定义如下 ```Kotlin interface IrLoweringHookExtension { fun traverse(context: CommonBackendContext, module: IrModuleFragment) fun transform(context: CommonBackendContext, module: IrModuleFragment) } ``` Transform 对项目中的 IR 会进行两轮处理，分别对应 `traverse` 和 `transform` 两个方法，建议在 `traverse` 中采集代码信息，在 `transform` 中实现具体的 IR 转换逻辑 # 什么是 KCP KCP（Kotlin Compiler Plugin）是 Kotlin 提供的一种功能强大的扩展机制，用于在编译阶段对代码进行分析、变换或生成。通过 KCP开发者可以深度定制编译器行为，实现如 AOP（面向切面编程）、代码插桩、静态检查等高级功能。KCP 的核心特点是它直接作用于 Kotlin 编译器的中间表示（IR），具有高度的灵活性和跨平台支持（包括 JVM、JS 和 Native）。本文不会介绍如何实现 KCP，推荐先阅读 [Writing Your Second Kotlin Compiler Plugin](https://bnorm.medium.com/writing-your-second-kotlin-compiler-plugin-part-1-project-setup-7b05c7d93f6c)。 # KMP Transform实现为了实现类 Android 的 Transform 底座，我们需要实现统一处理应用所有模块 IR 数据的能力。虽然 Kotlin 允许我们自定义编译器插件（KCP）进行 IR 处理，但 KCP 只能处理单一模块的 IR，无法直接访问或修改应用程序中所有依赖模块的 IR 信息。因此仅依赖 KCP 实现全局统一的 IR 处理是不可行的，我们需要探索其他解决思路。 ## 实现思路 Kotlin/Native 和 Kotlin/JS 发布的库产物以 klib 形式存在，而 klib 文件存储了该模块编译后的 Kotlin IR 数据。因此可以合理猜测，当编译顶层模块生成平台可执行产物（如 so 文件或 js 文件）时，编译器会收集整个项目中所有依赖模块的 IR 数据，并在这一阶段将其整合、优化，最终统一编译成目标平台的产物。 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/2a0e8f69713d4400bba323ab8d922d40~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=BoMhKyNmGT1mXHd8b217rYNgVYA%3D) 如果我们可以在这个阶段注入我们自定义的 IR 转换逻辑，就可以实现全局 IR 的处理能力。下面将分别分析**Kotlin** **/Native** 和 **Kotlin/** **JS** 的编译流程，尝试找到这一阶段并实现逻辑注入。 ## Kotlin/Native ### 编译流程分析 Kotlin/Native 编译主要会触发 **KotlinNativeCompile** 和 **KotlinNativeLink** 两个 Gradle Task，前者负责将当前模块编译为 Library 产物（也就是包含Kotlin IR 的 klib），后者负责将当前项目编译为平台可执行产物。 #### **KotlinNativeCompile** KMP 的编译逻辑并不与 Gradle 耦合，Gradle Task 只是负责整合编译参数、通过 `KotlinToolRunner` 执行编译命令触发编译，相关代码如下所示 ```Kotlin @CacheableTask abstract class KotlinNativeCompile { @TaskAction fun compile() { val buildMetrics = metrics.get() addBuildMetricsForTaskAction( metricsReporter = buildMetrics, languageVersion = resolveLanguageVersion() ) { // 构建编译参数 val arguments = createCompilerArguments() val buildArguments = buildMetrics.measure(GradleBuildTime.OUT_OF_WORKER_TASK_ACTION) { val output = outputFile.get() output.parentFile.mkdirs() buildFusService.orNull?.reportFusMetrics { NativeCompilerOptionMetrics.collectMetrics(compilerOptions, it) } ArgumentUtils.convertArgumentsToStringList(arguments) } // 触发编译命令 objectFactory.KotlinNativeCompilerRunner( settings = runnerSettings, metricsReporter = buildMetrics ).run(buildArguments) } } } // KotlinNativeCompilerRunner.run 最终会触发到 KotlinToolRunner#runInProcess abstract class KotlinToolRunner { private fun runInProcess(args: List, metricsReporter: BuildMetricsReporter = DoNothingBuildMetricsReporter) { metricsReporter.measure(GradleBuildTime.NATIVE_IN_PROCESS) { // 编译转换参数，在参数前增加 konanc val transformedArgs = transformArgs(args) // 获取 ClassLoader 加载 cli class val isolatedClassLoader = getIsolatedClassLoader() // ... try { val mainClass = isolatedClassLoader.loadClass(mainClass) val entryPoint = mainClass.methods .singleOrNull { it.name == daemonEntryPoint } ?: error("Couldn't find daemon entry point '$daemonEntryPoint'") metricsReporter.measure(GradleBuildTime.RUN_ENTRY_POINT) { // 通过 cli 执行 konanc 命令完成编译 entryPoint.invoke(null, transformedArgs.toTypedArray()) } } catch (t: InvocationTargetException) { throw t.targetException } } } } ``` 可以看到 `KotlinNativeCompile` 整合编译参数后通过 cli 触发了 konanc 命令进行编译，完整的命令如下所示 konanc -g -enable-assertions -library /Users/wulinpeng/.konan/kotlin-native-prebuilt-macos-aarch64-2.0.21/klib/common/stdlib -library /Users/wulinpeng/Desktop/kcp_project/EzHook/demo-v2/build/classes/kotlin/macosArm64/main/klib/demo-v2.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/io.github.xdmrwu/ez-hook-library-macosarm64/0.0.2/3e8f0d77f5add361fdd0332ed43ef732b13ba860/library.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-datetime-macosarm64/0.6.1/8f8b97995e611b9f5207cf52b1d98d64100b9e3/kotlinx-datetime.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-serialization-core-macosarm64/1.6.2/9b73a3c99322130d2aba72d7a382879546251058/kotlinx-serialization-core.klib -module-name EzHook:demo -no-endorsed-libs -nostdlib -output /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/classes/kotlin/macosArm64/main/klib/demo.klib -produce library -Xshort-module-name=demo -target macos_arm64 -Xfragment-refines=macosArm64Main:macosMain,macosMain:appleMain,appleMain:nativeMain,nativeMain:commonMain -Xfragment-sources=commonMain:/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/Main.kt,commonMain:/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/hook/TestManagerHook.kt -Xfragments=macosArm64Main,macosMain,appleMain,nativeMain,commonMain -Xmulti-platform -Xplugin=/Users/wulinpeng/Desktop/kcp_project/EzHook/local-plugin-repository/io/github/xdmrwu/ez-hook-compiler-plugin/0.0.2/ez-hook-compiler-plugin-0.0.2.jar /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/Main.kt /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/hook/TestManagerHook.kt 核心参数总结如下 * **--module-name**：当前编译的模块名称 * **-produce**：产物类型，当前指定编译为 Library * **-Xplugin**：如果当前模块配置了自定义的 KCP 插件，那么会通过改参数传递KCP 插件的 jar 包路径最终 `konanc` 会触发编译器代码进行编译，入口在 `K2Native`中，这里首先会解析前面传递的`-Xplugin`参数，将 KCP 插件通过 ClassLoader 加载到内存中并完成注册 ```Kotlin class K2Native : CLICompiler() { override fun doExecute(@NotNull arguments: K2NativeCompilerArguments, @NotNull configuration: CompilerConfiguration, @NotNull rootDisposable: Disposable, @Nullable paths: KotlinPaths?): ExitCode { // ... // 加载 KCP 插件并完成注册 val pluginLoadResult = PluginCliParser.loadPluginsSafe(arguments.pluginClasspaths, arguments.pluginOptions, arguments.pluginConfigurations, configuration) if (pluginLoadResult != ExitCode.OK) return pluginLoadResult // .. try { // 执行编译逻辑 runKonanDriver(configuration, environment, rootDisposable) } catch (e: Throwable) { // ... throw e } return ExitCode.OK } } ``` 最终的代码编译逻辑在`DynamicCompilerDriver`中实现，该类负责 Kotlin/Native 所有类型产物的编译，`KotlinNativeCompile` 传递的是 library 类型产物，最终编译产物为 klib，具体逻辑如下所示 ```Kotlin internal class DynamicCompilerDriver(private val performanceManager: CommonCompilerPerformanceManager?) : CompilerDriver() { override fun run(config: KonanConfig, environment: KotlinCoreEnvironment) { usingNativeMemoryAllocator { usingJvmCInteropCallbacks { PhaseEngine.startTopLevel(config) { engine -> if (!config.compileFromBitcode.isNullOrEmpty()) produceBinaryFromBitcode(engine, config, config.compileFromBitcode!!) else when (config.produce) { CompilerOutputKind.PROGRAM -> produceBinary(engine, config, environment) CompilerOutputKind.DYNAMIC -> produceCLibrary(engine, config, environment) CompilerOutputKind.STATIC -> produceCLibrary(engine, config, environment) CompilerOutputKind.FRAMEWORK -> produceObjCFramework(engine, config, environment) // 编译为 library CompilerOutputKind.LIBRARY -> produceKlib(engine, config, environment) CompilerOutputKind.BITCODE -> error("Bitcode output kind is obsolete.") CompilerOutputKind.DYNAMIC_CACHE -> produceBinary(engine, config, environment) CompilerOutputKind.STATIC_CACHE -> produceBinary(engine, config, environment) CompilerOutputKind.HEADER_CACHE -> produceBinary(engine, config, environment) CompilerOutputKind.TEST_BUNDLE -> produceBundle(engine, config, environment) } } } } } private fun produceKlib(engine: PhaseEngine, config: KonanConfig, environment: KotlinCoreEnvironment) { val serializerOutput = if (environment.configuration.getBoolean(CommonConfigurationKeys.USE_FIR)) // 编译为 KotlinIR serializeKLibK2(engine, config, environment) else serializeKlibK1(engine, config, environment) // 写入 klib serializerOutput?.let { engine.writeKlib(it) } } } ``` 综上，`KotlinNativeCompile` 整体流程流程如下图所示 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/49d1c42d9378434f8ad4c56003c0443d~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=nj7SzyLN3LOhhKmBQxvsDFwzfqo%3D) #### **KotlinNativeLink** `KotlinNativeLink`整体流程与 `KotlinNativeCompile` 类似，最终也是通过 CLI 触发 konanc 编译，但是编译参数有所不同，具体参数如下所示 konanc -g -enable-assertions -Xinclude=/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/classes/kotlin/macosArm64/main/klib/demo.klib -library /Users/wulinpeng/.konan/kotlin-native-prebuilt-macos-aarch64-2.0.21/klib/common/stdlib -library /Users/wulinpeng/Desktop/kcp_project/EzHook/demo-v2/build/classes/kotlin/macosArm64/main/klib/demo-v2.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/io.github.xdmrwu/ez-hook-library-macosarm64/0.0.2/3e8f0d77f5add361fdd0332ed43ef732b13ba860/library.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-datetime-macosarm64/0.6.1/8f8b97995e611b9f5207cf52b1d98d64100b9e3/kotlinx-datetime.klib -library /Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-serialization-core-macosarm64/1.6.2/9b73a3c99322130d2aba72d7a382879546251058/kotlinx-serialization-core.klib -entry com.wulinpeng.ezhook.demo.main -no-endorsed-libs -nostdlib -output /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/bin/macosArm64/debugExecutable/Shared.kexe -produce program -target macos_arm64 -Xmulti-platform -Xexternal-dependencies=/var/folders/dj/fry6r1852kn99cjp70_14dm00000gn/T/kotlin-native-external-dependencies14182981270788071442.deps 这段参数是用于编译 macos 上的可执行文件，核心参数如下 * **-entry**：指定程序运行的入口方法 main * **-** **output**：指定输出产物为 .kexe * **-produce**：指定产物类型为 program，配合--target 可以确定平台与 `KotlinNativeCompile` 相比少了-Xplugin 参数，这也可以解释为什么 KCP 只能处理单一模块的 IR。在编译器侧的逻辑和前面 `KotlinNativeCompile` 的逻辑一样，区别在于最后调用了`produceBinary` 生成可执行文件。 ```Kotlin /** * Produce a single binary artifact. */ private fun produceBinary(engine: PhaseEngine, config: KonanConfig, environment: KotlinCoreEnvironment) { // ... performanceManager.trackGeneration { val backendContext = createBackendContext(config, frontendOutput, psiToIrOutput) // 执行后端编译逻辑，生成 binary 产物 engine.runBackend(backendContext, psiToIrOutput.irModule) } } // TopLevelPhases.kt internal fun PhaseEngine.runBackend(backendContext: Context, irModule: IrModuleFragment) { // ... useContext(backendContext) { backendEngine -> fun createGenerationStateAndRunLowerings(fragment: BackendJobFragment): NativeGenerationState { // ... try { val module = fragment.irModule newEngine(generationState) { generationStateEngine -> // ... rootPerformanceManager.trackIRLowering { // 对当前模块以及所有依赖模块执行 lower generationStateEngine.lowerModuleWithDependencies(module) } } return generationState } catch (t: Throwable) { generationState.dispose() throw t } } val fragments = backendEngine.splitIntoFragments(irModule) val threadsCount = context.config.threadsCount if (threadsCount == 1) { fragments.forEach { fragment -> runAfterLowerings(fragment, createGenerationStateAndRunLowerings(fragment)) } } else { // ... } } } internal fun PhaseEngine.lowerModuleWithDependencies(module: IrModuleFragment) { // ... // 获取所有依赖的 IrModule val allModulesToLower = listOf(module) + dependenciesToCompile.reversed() // 执行所有 lower phase runIrValidationPhase(validateIrBeforeLowering, allModulesToLower) runLowerings(getLoweringsUpToAndIncludingInlining(), allModulesToLower) runIrValidationPhase(validateIrAfterInlining, allModulesToLower) runLowerings(getLoweringsAfterInlining(), allModulesToLower) runIrValidationPhase(validateIrAfterLowering, allModulesToLower) mergeDependencies(module, dependenciesToCompile) } ``` 从源码可以看出在`lowerModuleWithDependencies`中会整合当前模块和所有依赖模块的 IR，并进行 `lower` 处理。然而 Kotlin 编译器为了提升编译效率，会在首次编译时将三方依赖编译为目标平台的binary并缓存，下次编译直接使用缓存参与目标平台产物的编译，具体实现如下 ```Kotlin class KonanDriver( val project: Project, val environment: KotlinCoreEnvironment, val configuration: CompilerConfiguration, val compilationSpawner: CompilationSpawner ) { fun run() { val cacheBuilder = CacheBuilder(konanConfig, compilationSpawner) if (cacheBuilder.needToBuild()) { // 为三方依赖库构建缓存 cacheBuilder.build() konanConfig = KonanConfig(project, configuration) // TODO: Just set freshly built caches. } // 执行编译 DynamicCompilerDriver(performanceManager).run(konanConfig, environment) } } ``` `cacheBuilder.build` 会并发执行所有三方库的缓存构建，触发类型为`CompilerOutputKind.STATIC_CACHE`，从该类的定义可以看出在 macos 平台上缓存产物为 `.a` 文件 ```Kotlin enum class CompilerOutputKind { STATIC_CACHE { override fun suffix(target: KonanTarget?) = ".${target!!.family.staticSuffix}" override fun prefix(target: KonanTarget?) = target!!.family.staticPrefix }, } enum class Family( val exeSuffix: String, val dynamicPrefix: String, val dynamicSuffix: String, val staticPrefix: String, val staticSuffix: String ) { OSX("kexe", "lib", "dylib", "lib", "a"), IOS("kexe", "lib", "dylib", "lib", "a"), TVOS("kexe", "lib", "dylib", "lib", "a"), WATCHOS("kexe", "lib", "dylib", "lib", "a"), LINUX("kexe", "lib", "so", "lib", "a"), MINGW("exe", "", "dll", "lib", "a"), ANDROID("kexe", "lib", "so", "lib", "a"); } ``` 综上，`KotlinNativeLink` 整体流程流程如下图所示 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/38528dc52bfb446bb05a77bffffa43d2~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=kanECqiqEHReZVNoDrQMO16wIoI%3D) ### Transform 逻辑实现 #### 实现 Hook 逻辑从上面的编译流程分析可以看出 `KotlinNativeLink` 阶段就是负责将当前项目依赖模块统一处理、编译成可执行产物，也确实在这个阶段对所有 IR 进行了统一的处理(`Lower`)。但是由于缓存机制的存在，这个阶段只会处理当前项目所有源码模块，而三方依赖模块会直接使用处理后的缓存，这样看来我们仍然无法统一处理整个项目所有的 IR。然而经过一番源码研究后发现这个缓存机制是可配置的，我们可以通过指定 gradle 参数来关闭这个缓存机制 // gradle.properties kotlin.native.cacheKind=none 关闭之后在`KotlinNativeLink`阶段会统一处理所有三方库与项目源码的 IR，我们只需要想办法在这个阶段注入我们自定义的 IR 处理逻辑即可达成目标。上面提到最终会调用`lowerModuleWithDependencies`方法执行 lower，我们来看一下这块代码 ```Kotlin internal fun PhaseEngine.lowerModuleWithDependencies(module: IrModuleFragment) { // ... // 获取所有依赖的 IrModule val allModulesToLower = listOf(module) + dependenciesToCompile.reversed() // 执行所有 lower phase runIrValidationPhase(validateIrBeforeLowering, allModulesToLower) runLowerings(getLoweringsUpToAndIncludingInlining(), allModulesToLower) runIrValidationPhase(validateIrAfterInlining, allModulesToLower) runLowerings(getLoweringsAfterInlining(), allModulesToLower) runIrValidationPhase(validateIrAfterLowering, allModulesToLower) mergeDependencies(module, dependenciesToCompile) } // NativeLoweringPhases.kt internal val validateIrBeforeLowering = createSimpleNamedCompilerPhase( name = "ValidateIrBeforeLowering", description = "Validate IR before lowering", op = { context, module -> IrValidationBeforeLoweringPhase(context.context).lower(module) } ) ``` 最终会使用`NativeLoweringPhases.kt`中定义的各个 `LoweringPhase` 对 IR 进行处理，由于该文件中定义的所有 `LoweringPhase` 都是顶层属性，那么我们很容易想到利用 java 反射来 Hook 这些`LoweringPhase`注入自定义的 IR 处理逻辑。以第一个`validateIrBeforeLowering`为例，它是通`createSimpleNamedCompilerPhase`创建的对象，具体 IR 处理逻辑在 `op` 参数中，`createSimpleNamedCompilerPhase`实现如下 ```Kotlin fun createSimpleNamedCompilerPhase( name: String, description: String, preactions: Set> = emptySet(), postactions: Set> = emptySet(), prerequisite: Set> = emptySet(), outputIfNotEnabled: (PhaseConfigurationService, PhaserState, Context, Input) -> Output, op: (Context, Input) -> Output ): SimpleNamedCompilerPhase = object : SimpleNamedCompilerPhase( name, description, preactions = preactions, postactions = postactions.map { f -> fun(actionState: ActionState, data: Pair, context: Context) = f(actionState, data.second, context) } .toSet(), prerequisite = prerequisite, ) { override fun outputIfNotEnabled(phaseConfig: PhaseConfigurationService, phaserState: PhaserState, context: Context, input: Input): Output = outputIfNotEnabled(phaseConfig, phaserState, context, input) override fun phaseBody(context: Context, input: Input): Output = op(context, input) } ``` 本质上创建了一个匿名内部类，该类会捕获外部的 op 参数，在生成的字节码中会有一个参数与之对应`$op`，我们只需要通过反射替换该属性即可完成自定义逻辑注入，具体实现如下 ```Kotlin private fun hookValidateIrBeforeLowering(allModules: MutableList, transformer: (CommonBackendContext, IrModuleFragment) -> Unit) { val clazz = Class.forName("org.jetbrains.kotlin.backend.konan.driver.phases.NativeLoweringPhasesKt") // 获取 validateIrBeforeLowering val lower = clazz.declaredFields.firstOrNull { it.name == "validateIrBeforeLowering" } ?.apply { isAccessible = true } !!.get(null) // 替换 $op 属性 lower.javaClass.getDeclaredField("$op").apply { isAccessible = true } .set(lower, { context: LoggingContext, module: IrModuleFragment -> val innerContext = context.javaClass.getDeclaredField("context").apply { isAccessible = true } .get(context) as CommonBackendContext // 在这插入自定义逻辑 // ... // 调用原始逻辑 IrValidationBeforeLoweringPhase(innerContext as CommonBackendContext).lower(module) }) } ``` 在 Transform 的设计中会有 traverse 和 transform 两个阶段，前者用于信息采集，后者实现 IR 转换，所以我们可以 Hook Lower 阶段前两个`LoweringPhase`，分别实现这两个阶段，具体代码见[NativeIrLoweringExtension.kt](https://github.com/XDMrWu/EzHook/blob/main/compiler_plugin/src/main/kotlin/com/wulinpeng/ezhook/compiler/hook/NativeIrLoweringExtension.kt) #### 注入 Hook 逻辑在实现 Hook 逻辑后，我们还需要选择合适的时机来执行这个 Hook 方法。通过前面的分析，我们知道 `KotlinNativeCompile` 阶段会调用自定义的编译器插件。同时，`KotlinNativeCompile` 和 `KotlinNativeLink` 这两个任务默认在同一进程中运行，并复用相同的 ClassLoader。因此，在自定义编译器插件中执行 Hook 方法是可以对后续的 `KotlinNativeLink` 任务产生影响，具体代码见[EzHookCompilerRegister.kt](https://github.com/XDMrWu/EzHook/blob/main/compiler_plugin/src/main/kotlin/com/wulinpeng/ezhook/compiler/EzHookCompilerRegister.kt) ## Kotlin/JS **Kotlin** **/** **JS** 与 **Kotlin/Native** 整体流程比较像，在 Gradle 层面也有`Kotlin2JsCompile`和`KotlinJsIrLink`两个 Task，`Kotlin2JsCompile`负责将模块编译为 klib，`KotlinJsIrLink` 负责将所有 IR 编译为 JS 代码。 ### 如何调试在分析过程中发现 JS 的编译器后端无端断点调试，排查后发现编译 JS 默认会启动新的进程执行编译，为了能够正常断点调试可以在 gradle.properties 中添加配置开启当前进程编译 kotlin.compiler.execution.strategy=in-process ### 编译流程分析 #### Kotlin2JsCompile 与 Kotlin/Native 类似，`Kotlin2JsCompile`负责整合编译参数、通过 `GradleKotlinCompilerRunner` 执行编译命令触发编译，相关代码如下所示 ```Kotlin @CacheableTask abstract class Kotlin2JsCompile { override fun callCompilerAsync( args: K2JSCompilerArguments, inputChanges: InputChanges, taskOutputsBackup: TaskOutputsBackup?, ) { // 处理参数 processArgsBeforeCompile(args) // 触发编译 compilerRunner.runJsCompilerAsync( args, environment, taskOutputsBackup ) compilerRunner.errorsFiles?.let { gradleMessageCollector.flush(it) } } } ``` 完整的编译命令如下所示 -Xir-only -Xir-produce-klib-dir -libraries /Users/wulinpeng/Desktop/kcp_project/EzHook/demo-v2/build/libs/demo-v2-js.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/io.github.xdmrwu/ez-hook-library-js/0.0.2/4503db3c0c0cc648166c944bbbd0cd97f2ef0779/library-js.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-dom-api-compat/2.0.21/537dbda0c5c5ee06c81b2c0d1f466df60d810e3f/kotlin-dom-api-compat-2.0.21.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-js/2.0.21/8047778f196f3cdc817f1e90eb45f08b4837ba9/kotlin-stdlib-js-2.0.21.klib -main call -meta-info -ir-output-name demo -no-stdlib -ir-output-dir /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/classes/kotlin/js/main -source-map -source-map-embed-sources never -target es5 -Xfragment-refines=jsMain:commonMain -Xfragment-sources=commonMain:/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/Main.kt,commonMain:/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/hook/TestManagerHook.kt -Xfragments=jsMain,commonMain -Xmulti-platform -Xplugin=/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-scripting-compiler-embeddable/2.0.21/ac0c290312174e309c3e65711ab29fed1442532a/kotlin-scripting-compiler-embeddable-2.0.21.jar,/Users/wulinpeng/Desktop/kcp_project/EzHook/local-plugin-repository/io/github/xdmrwu/ez-hook-compiler-plugin/0.0.2/ez-hook-compiler-plugin-0.0.2.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-scripting-compiler-impl-embeddable/2.0.21/84c79a332f515fd6dd3ea2ab50c227c4a5756c37/kotlin-scripting-compiler-impl-embeddable-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-scripting-jvm/2.0.21/939d8b644308f8d97c60317df76ee40299475831/kotlin-scripting-jvm-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-scripting-common/2.0.21/2aeb50e2df2ef94f6b90b7ab2c56d5e18d3687c1/kotlin-scripting-common-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/2.0.21/618b539767b4899b4660a83006e052b63f1db551/kotlin-stdlib-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-gradle-plugin-api/2.0.21/2fe6828d39788b439f1a44576c4fd2d98862e77b/kotlin-gradle-plugin-api-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/13.0/919f0dfe192fb4e063e7dacadee7f8bb9a2672a9/annotations-13.0.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-gradle-plugin-annotations/2.0.21/585ea547101485df5165acbffc51b760b0bf2728/kotlin-gradle-plugin-annotations-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-native-utils/2.0.21/ccdbc49a5d23f7ab782fbdff20c9426cf074f2d7/kotlin-native-utils-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-tooling-core/2.0.21/952179e9b7f114e78274ca73cea6df8fce3c8b3b/kotlin-tooling-core-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-script-runtime/2.0.21/c9b044380ad41f89aa89aa896c2d32a8c0b2129d/kotlin-script-runtime-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-util-klib/2.0.21/cc042c4a50a1ee46695a8f2f928c196223bdd7dc/kotlin-util-klib-2.0.21.jar,/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-util-io/2.0.21/4467ad395771e3d12ca864fd9949e1404920f558/kotlin-util-io-2.0.21.jar -Xir-per-module-output-name=EzHook-demo -Xir-per-module-output-name=EzHook-demo -Xir-module-name=EzHook:demo /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/Main.kt /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/src/commonMain/kotlin/com/wulinpeng/ezhook/demo/hook/TestManagerHook.kt * **-Xir-module-name：** 当前编译模块名称 * **-Xir-produce-klib-dir**：编译 klib * **-Xplugin**：如果当前模块配置了自定义的 KCP 插件，那么会通过改参数传递KCP 插件的 jar 包路径最终会触发编译器代码进行编译，入口在 `K2JsIrCompiler`中，这里首先会解析前面传递的`-Xplugin`参数，将 KCP 插件通过 ClassLoader 加载到内存中并完成注册 ```Kotlin class K2JsIrCompiler : CLICompiler() { override fun doExecute( arguments: K2JSCompilerArguments, configuration: CompilerConfiguration, rootDisposable: Disposable, paths: KotlinPaths? ): ExitCode { // ... // 加载插件 val pluginLoadResult = loadPlugins(paths, arguments, configuration) if (pluginLoadResult != OK) return pluginLoadResult // ... try { // 执行代码编译 val ir2JsTransformer = Ir2JsTransformer(arguments, module, phaseConfig, messageCollector, mainCallArguments) val outputs = ir2JsTransformer.compileAndTransformIrNew() // ... } catch (e: CompilationException) { // ... return INTERNAL_ERROR } return OK } } ``` 综上，`Kotlin2JsCompile` 整体流程流程如下图所示 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/a6f6d659a5be4928849174144ed7cb1d~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=vdhoRkT%2Fq5xmBp75vqNorwEQ6cA%3D) #### KotlinJsIrLink `KotlinJsIrLink` 和 `Kotlin2JsCompile` 流程相似，区别在于编译参数，具体参数如下 -Xcache-directory=/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/klib/cache/js/developmentLibrary -Xinclude=/Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/classes/kotlin/js/main -Xir-only -Xir-produce-js -libraries /Users/wulinpeng/Desktop/kcp_project/EzHook/demo-v2/build/libs/demo-v2-js.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/io.github.xdmrwu/ez-hook-library-js/0.0.2/4503db3c0c0cc648166c944bbbd0cd97f2ef0779/library-js.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-datetime-js/0.6.1/723f6ab9f4c7b370bbee0d79d63c96af9b68055f/kotlinx-datetime-js-0.6.1.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-serialization-core-js/1.6.2/27bceec3b89d0eec8f951f8b25f16fffa0df214e/kotlinx-serialization-core-js-1.6.2.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-dom-api-compat/2.0.21/537dbda0c5c5ee06c81b2c0d1f466df60d810e3f/kotlin-dom-api-compat-2.0.21.klib:/Users/wulinpeng/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-js/2.0.21/8047778f196f3cdc817f1e90eb45f08b4837ba9/kotlin-stdlib-js-2.0.21.klib -main call -meta-info -no-stdlib -ir-output-dir /Users/wulinpeng/Desktop/kcp_project/EzHook/demo/build/compileSync/js/main/developmentLibrary/kotlin -source-map -source-map-embed-sources never -target es5 -Xmulti-platform -Xir-module-name=EzHook:demo -Xir-per-module -ir-output-name=EzHook-demo * **-Xir-produce-js**：编译成 JS 产物和 KotlinNativeLink 类似，在这个阶段不会带上 KCP 插件。最终的编译逻辑在`JsIrCompilerWithIC` 中实现 ```Kotlin class JsIrCompilerWithIC { override fun compile(allModules: Collection, dirtyFiles: Collection): List<() -> JsIrProgramFragments> { // ... // 执行 lower lowerPreservingTags(allModules, context, phaseConfig, context.irFactory.stageController as WholeWorldStageController) val transformer = IrModuleToJsTransformer(context, shouldReferMainFunction = mainArguments != null) return transformer.makeIrFragmentsGenerators(dirtyFiles, allModules) } } ``` ### Transform 逻辑实现 #### 实现 Hook 逻辑与 Kotlin/Native 类似，我们只需要 Hook 对应的 `LoweringPhase` 即可，代码见[JsIrLoweringExtension.kt](https://github.com/XDMrWu/EzHook/blob/main/compiler_plugin/src/main/kotlin/com/wulinpeng/ezhook/compiler/hook/JsIrLoweringExtension.kt) #### 注入 Hook 逻辑 ##### In-progress 上面介绍过在 **Kotlin** **/Native** 下是在 KCP 的执行入口来触发 Hook 逻辑，Compile 与 Link 两个 Task 在一个进程且复用 ClassLoader 是改方案可行的重要前提。然而在 **Kotlin/** **JS** 中，尽管我们设置 `in-progress` 保证了 Compile 和 Link在一个进程中，但是 `GradleKotlinCompilerWork`在不同 Task 之间没有复用 ClassLoader ，导致该方案无效。 ```Kotlin class GradleKotlinCompilerWork { private fun compileInProcessImpl(messageCollector: MessageCollector): ExitCode { val stream = ByteArrayOutputStream() val out = PrintStream(stream) // todo: cache classloader? val classLoader = URLClassLoader(config.compilerFullClasspath.map { it.toURI().toURL() } .toTypedArray()) val servicesClass = Class.forName(Services::class.java.canonicalName, true, classLoader) val emptyServices = servicesClass.getField("EMPTY").get(servicesClass) val compiler = Class.forName(config.compilerClassName, true, classLoader) // ... } } ``` 那么是否可以将 `KotlinJsIrLink` 的编译参数中应用 KCP 插件来实现呢？首先从源码入手看一下为什么`KotlinJsIrLink`没有应用 KCP，将 KCP 插件路径赋值到编译参数中的逻辑在`AbstractKotlinCompileConfig`中 ```Kotlin internal abstract class AbstractKotlinCompileConfig> constructor(compilationInfo: KotlinCompilationInfo) : this( compilationInfo.project, compilationInfo.project.topLevelExtension ) { configureTask { task -> // ,,, compilationInfo.tcs.compilation.let { compilation -> // ... task.pluginClasspath.from( compilation.internal.configurations.pluginConfiguration ) } // ... } } } ``` 而`KotlinJsIrLinkConfig`继承该类后主动清空了 `pluginClassplugin`，因此 `KotlinJsIrLink` 不会应用 KCP ```Kotlin internal open class KotlinJsIrLinkConfig( private val binary: JsIrBinary, ) : BaseKotlin2JsCompileConfig(KotlinCompilationInfo(binary.compilation)) { private val compilation get() = binary.compilation init { configureTask { task -> // Link tasks are not affected by compiler plugin, so set to empty task.pluginClasspath.setFrom(objectFactory.fileCollection()) // ... } } } ``` 如果你具备 Gradle Hook 相关经验，可能已经想到一种方法：**通过调整 classpath 顺序来覆盖 KGP 的实现类**。在这里，我们可以覆盖 `KotlinJsIrLinkConfig` 类的实现。具体步骤是将 `KotlinJsIrLinkConfig` 的代码拷贝到自定义的 Gradle Plugin 中，并确保该插件在 classpath 中优先加载，从而取代原始的 `KotlinJsIrLinkConfig` 实现。以下是具体的实现方式： ```Kotlin internal open class KotlinJsIrLinkConfig( private val binary: JsIrBinary, ) : BaseKotlin2JsCompileConfig(KotlinCompilationInfo(binary.compilation)) { private val compilation get() = binary.compilation init { configureTask { task -> // 注释掉这一行，应用 KCP 到 KotlinJsIrLink // task.pluginClasspath.setFrom(objectFactory.fileCollection()) // ... } } } ``` ##### daemon 然而默认情况下 Kotlin/JS 是走 daemon 模式的，改模式下 Compile 与 Link 共用一个 daemon 进程并复用 ClassLoader。由于上面为 `KotlinJsIrLink` 任务应用了 KCP 会导致相关的类被 Hook 两次(加载 KCP 没有复用 ClassLoader)，进而导致运行时异常，因此需要在对应的 Hook 逻辑中判断原始 Lower 是否已经被 Hook，具体逻辑见[JsIrLoweringExtension.kt](https://github.com/XDMrWu/EzHook/blob/main/compiler_plugin/src/main/kotlin/com/wulinpeng/ezhook/compiler/hook/JsIrLoweringExtension.kt) # EzHook实现 ## 实现逻辑框架核心需要实现的功能是**替换目标方法的实现，并且在 Hook 方法中能够调用原始方法并修改参数，** 实现逻辑如下 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/7f0a78f14cd748c5b9cde5cbadb679ed~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=rNsYmdo4k8pDOtqAXehkJMf%2FtH8%3D) 1. **拷贝目标方法用于后续调用原始方法** ```Kotlin class EzHookIrTransformer(val collectInfos: List, val pluginContext: CommonBackendContext): IrElementTransformerVoidWithContext() { companion object { private const val LAST_PARAM_NAME = "ez_hook_origin" private const val NEW_FUNCTION_SUFFIX = "_ez_hook" } override fun visitFunctionNew(function: IrFunction): IrStatement { // ... val newFunction = function.copyFunctionToParent("${function.name.asString()}$NEW_FUNCTION_SUFFIX") } } fun IrFunction.copyFunctionToParent(newName: String, newParent: IrDeclarationParent = parent): IrFunction { return deepCopyWithSymbols(newParent).apply { name = Name.identifier(newName) setDeclarationsParent(newParent) (newParent as IrDeclarationContainer).addChild(this) } } ``` 2. **将目标方法实现替换为调用 Hook 方法，并传递当前对象** ```Kotlin class EzHookIrTransformer(val collectInfos: List, val pluginContext: CommonBackendContext): IrElementTransformerVoidWithContext() { companion object { private const val LAST_PARAM_NAME = "ez_hook_origin" private const val NEW_FUNCTION_SUFFIX = "_ez_hook" } override fun visitFunctionNew(function: IrFunction): IrStatement { // ... function.body = pluginContext.createIrBuilder(function.symbol).irBlockBody(function) { val result = createTmpVariable( irExpression = irCall(hookFunction).apply { function.valueParameters.forEachIndexed { index, param -> putValueArgument(index, irGet(param)) } // put dispatch receiver as the last param if exist if (function.isClassMember()) { putValueArgument(function.valueParameters.size, irGet(function.dispatchReceiverParameter!!)) } } , nameHint = "returnValue", origin = IrDeclarationOrigin.DEFINED ) +irReturn(irGet(result)) } } } ``` 3. **为 Hook 方法增加一个参数作为目标对象** ```Kotlin class EzHookIrTransformer(val collectInfos: List, val pluginContext: CommonBackendContext): IrElementTransformerVoidWithContext() { companion object { private const val LAST_PARAM_NAME = "ez_hook_origin" private const val NEW_FUNCTION_SUFFIX = "_ez_hook" } override fun visitFunctionNew(function: IrFunction): IrStatement { // ... if (function.isClassMember()) { hookFunction.addValueParameter(Name.identifier(LAST_PARAM_NAME), function.parentAsClass.defaultType) } } } ``` 4. **找到 Hook 方法中的** **`callOrigin`** **调用，替换为目标对象的 copy 方法调用** ```Kotlin class EzHookIrTransformer(val collectInfos: List, val pluginContext: CommonBackendContext): IrElementTransformerVoidWithContext() { companion object { private const val LAST_PARAM_NAME = "ez_hook_origin" private const val NEW_FUNCTION_SUFFIX = "_ez_hook" } override fun visitFunctionNew(function: IrFunction): IrStatement { // ... hookFunction.transform(EzHookCallOriginTransformer(hookFunction, newFunction, pluginContext), null) } } class EzHookCallOriginTransformer(val hookFunction: IrFunction, val targetFunction: IrFunction, val context: CommonBackendContext): IrElementTransformerVoidWithContext() { companion object { private const val CALL_ORIGIN = "com.wulinpeng.ezhook.runtime.callOrigin" } /** * variables to override this function params */ private val overrideParams = mutableListOf() override fun visitVariable(declaration: IrVariable): IrStatement { val name = declaration.name.asString() val type = declaration.type.getClass()!!.kotlinFqName!!.asString() if (hookFunction.valueParameters.any { it.name.asString() == name && it.type.getClass()!!.kotlinFqName!!.asString() == type }) { overrideParams.add(declaration) } return super.visitVariable(declaration) } override fun visitCall(expression: IrCall): IrExpression { if (expression.symbol.owner.fqNameWhenAvailable?.asString() == CALL_ORIGIN) { context.createIrBuilder(hookFunction.symbol).apply { return irCall(targetFunction.symbol).apply { // for class member function, make the last param as dispatch receiver if (targetFunction.isClassMember()) { val lastParam = hookFunction.valueParameters.last() dispatchReceiver = irGet(lastParam) } for (i in 0 until targetFunction.valueParameters.size) { val valueParam = targetFunction.valueParameters[i] // override param val irVariable = overrideParams.find { it.name.asString() == valueParam.name.asString() } putValueArgument(i, irGet(irVariable ?: valueParam)) } } } } else { return super.visitCall(expression) } } } ``` ## 问题适配 1. ### Invalid record 在 iOS Target 上运行时会出现编译问题，具体信息如下 error: Invalid record (Producer: 'LLVM11.1.0' Reader: 'LLVM 11.1.0') 1 error generated. at org.jetbrains.kotlin.konan.exec.Command.handleExitCode(ExecuteCommand.kt:129) at org.jetbrains.kotlin.konan.exec.Command.execute(ExecuteCommand.kt:85) at org.jetbrains.kotlin.backend.konan.BitcodeCompiler.runTool(BitcodeCompiler.kt:35) at org.jetbrains.kotlin.backend.konan.BitcodeCompiler.hostLlvmTool(BitcodeCompiler.kt:44) at org.jetbrains.kotlin.backend.konan.BitcodeCompiler.clang(BitcodeCompiler.kt:72) at org.jetbrains.kotlin.backend.konan.BitcodeCompiler.makeObjectFile(BitcodeCompiler.kt:87) at org.jetbrains.kotlin.backend.konan.driver.phases.ObjectFilesKt.ObjectFilesPhase$lambda$0(ObjectFiles.kt:22) at org.jetbrains.kotlin.backend.common.phaser.PhaseBuildersKt$createSimpleNamedCompilerPhase$3.phaseBody(PhaseBuilders.kt:91) at org.jetbrains.kotlin.backend.common.phaser.PhaseBuildersKt$createSimpleNamedCompilerPhase$3.phaseBody(PhaseBuilders.kt:79) at org.jetbrains.kotlin.backend.common.phaser.SimpleNamedCompilerPhase.phaseBody(CompilerPhase.kt:226) at org.jetbrains.kotlin.backend.common.phaser.AbstractNamedCompilerPhase.invoke(CompilerPhase.kt:113) at org.jetbrains.kotlin.backend.konan.driver.PhaseEngine.runPhase(Machinery.kt:120) at org.jetbrains.kotlin.backend.konan.driver.PhaseEngine.runPhase$default(Machinery.kt:111) at org.jetbrains.kotlin.backend.konan.driver.phases.TopLevelPhasesKt.compileAndLink(TopLevelPhases.kt:295) at org.jetbrains.kotlin.backend.konan.driver.phases.TopLevelPhasesKt.runBackend$lambda$12$runAfterLowerings(TopLevelPhases.kt:127) at org.jetbrains.kotlin.backend.konan.driver.phases.TopLevelPhasesKt.runBackend(TopLevelPhases.kt:139) at org.jetbrains.kotlin.backend.konan.driver.DynamicCompilerDriver.produceObjCFramework(DynamicCompilerDriver.kt:83) at org.jetbrains.kotlin.backend.konan.driver.DynamicCompilerDriver.run$lambda$2$lambda$1$lambda$0(DynamicCompilerDriver.kt:43) at org.jetbrains.kotlin.backend.konan.driver.PhaseEngine$Companion$startTopLevel$topLevelPhase$1.phaseBody(Machinery.kt:79) at org.jetbrains.kotlin.backend.konan.driver.PhaseEngine$Companion$startTopLevel$topLevelPhase$1.phaseBody(Machinery.kt:73) at org.jetbrains.kotlin.backend.common.phaser.SimpleNamedCompilerPhase.phaseBody(CompilerPhase.kt:226) at org.jetbrains.kotlin.backend.common.phaser.AbstractNamedCompilerPhase.invoke(CompilerPhase.kt:113) at org.jetbrains.kotlin.backend.konan.driver.PhaseEngine$Companion.startTopLevel(Machinery.kt:86) at org.jetbrains.kotlin.backend.konan.driver.DynamicCompilerDriver.run(DynamicCompilerDriver.kt:37) at org.jetbrains.kotlin.backend.konan.KonanDriver.run(KonanDriver.kt:135) at org.jetbrains.kotlin.cli.bc.K2Native.runKonanDriver(K2Native.kt:157) at org.jetbrains.kotlin.cli.bc.K2Native.doExecute(K2Native.kt:65) at org.jetbrains.kotlin.cli.bc.K2Native.doExecute(K2Native.kt:34) 这是由于在编译期为 Hook 方法添加了参数，导致 Hook 方法签名变更，最终与生成的头文件签名不一致造成编译失败。**Compose Compiler** 也有类似的问题，它们在编译期会为 `@Composable` 方法添加额外的参数，解决方案就是为这些方法加上`@HiddenFromObjC`注解，保证这些方法不会导出，下面是 Compose Compiler 的实现 ```Kotlin /** * AddHiddenFromObjCLowering looks for functions and properties with @Composable types and * adds the `kotlin.native.HiddenFromObjC` annotation to them. * [docs](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native/-hidden-from-obj-c/) */ class AddHiddenFromObjCLowering { override fun visitFunction(declaration: IrFunction): IrStatement { val f = super.visitFunction(declaration) as IrFunction // 非 public 的方法不会被导出，不需要添加 @HiddenFromObjC if (f.isLocal || f.isSyntheticFun() || !(f.visibility == DescriptorVisibilities.PUBLIC || f.visibility == DescriptorVisibilities.PROTECTED) ) return f // 为 @Composable 方法添加 @HiddenFromObjC 注解 if (f.hasComposableAnnotation() || f.needsComposableRemapping()) { f.addHiddenFromObjCAnnotation() hideFromObjCDeclarationsSet?.add(f) currentShouldAnnotateClass = true } return f } } ``` 由于我们 Hook 的时机比较靠后，使用这种方式加上`@HiddenFromObjC` 注解也无法解决该问题，所以就需要使用方主动在 Hook 方法上增加`@HiddenFromObjC`注解来规避这个问题。 2. ### Cannot read properties of undefined (reading 'a') 通过执行`jsNodeDevelopmentRun`运行 js 代码时会出现崩溃，堆栈如下 /Users/wulinpeng/Desktop/kcp_project/EzHook/build/js/packages/EzHook-demo/kotlin/EzHook-demo-v2.js:15 }(function (_, kotlin_kotlin, kotlin_EzHook_demo) { ^ TypeError: Cannot read properties of undefined (reading 'a') at /Users/wulinpeng/Desktop/kcp_project/EzHook/build/js/packages/EzHook-demo/kotlin/EzHook-demo-v2.js:19:40 at /Users/wulinpeng/Desktop/kcp_project/EzHook/build/js/packages/EzHook-demo/kotlin/EzHook-demo-v2.js:5:5 at Object. (/Users/wulinpeng/Desktop/kcp_project/EzHook/build/js/packages/EzHook-demo/kotlin/EzHook-demo-v2.js:15:2) at Module._compile (node:internal/modules/cjs/loader:1455:14) at Object.Module._extensions..js (node:internal/modules/cjs/loader:1534:10) at Module.load (node:internal/modules/cjs/loader:1265:32) at Function.Module._load (node:internal/modules/cjs/loader:1081:12) at Module.require (node:internal/modules/cjs/loader:1290:19) at require (node:internal/modules/helpers:188:18) at /Users/wulinpeng/Desktop/kcp_project/EzHook/build/js/packages/EzHook-demo/kotlin/EzHook-demo.js:5:29 这是由于在编译期我们为目标方法添加了对 Hook 方法的依赖(引用)，导致模块间存在循环依赖。而在 JS 中模块循环依赖时非常容易出现初始化错误，比如这里 `undefined` 就是因为 demo 模块和 demo-v2 模块循环依赖导致 demo 模块未完成初始化。 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/6765f27092e841938b23131f95eb9d33~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgWERNcld1:q75.awebp?rk3s=f64ab15b&x-expires=1758231602&x-signature=2YiAmSYm1zL%2BE3aYVkBdjr2ntCw%3D) 针对这种情况需要将 Hook 方法内联到目标模块中，以此来避免生成 JS 代码出现循环依赖的问题。