cocoapods-podgenerate 0.1.3 → 0.1.4

data/lib/cocoapods-podgenerate/patches/project_writer_patch.rb

@@ -1,18 +1,37 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches PodsProjectWriter to support incremental + parallel project saves.
+# Monkey-patches PodsProjectWriter 以支持增量 + 并行项目保存。
 #
-# v0.1.1 Optimizations:
-#  1. SHA256 digest — skip sort+save for unchanged projects
-#  2. Parallel save — multiple xcodeproj files saved in threads
+# 优化原理：
+#   `generate_multiple_pod_projects` 启用后，每个 pod 有独立的 xcodeproj 文件，
+#   每个文件的操作（清理空组、重建用户 scheme、排序、保存）天然线程安全，
+#   因为不同 xcodeproj 在不同目录，不存在共享状态。
 #
-# v0.1.2 Optimizations:
-#  3. Parallel cleanup_projects — empty group removal across projects
-#  4. Parallel recreate_user_schemes — scheme file creation across projects
+# v0.1.1 优化：
+#   1. SHA256 摘要比对，跳过未变更项目的 sort+save
+#   2. 多项目文件并行保存
 #
-# Reference: CocoaPods — lib/cocoapods/installer/xcode/pods_project_generator/pods_project_writer.rb
+# v0.1.2 优化：
+#   3. 并行 cleanup_projects（空 group 清理）
+#   4. 并行 recreate_user_schemes（scheme 文件创建）
+#
+# v0.1.4 修复：
+#   - L1: digest_file 返回 nil 时 nil==nil 导致误跳过保存，改为只有
+#         两个摘要都有效且相等时才跳过
+#   - M1: wait_for_termination 加 120s 超时
+#   - L2: 移除无效的 || [] 死代码
+#
+# 线程安全保证：
+#   - 每个 xcodeproj 是独立目录，project.save 写项目名.pbxproj
+#   - cleanup_single_project 只操作传入的 project 对象
+#   - recreate_schemes_for_project 只操作传入的 project 对象
+#   - results_by_native_target 在所有线程间只读共享（构建一次后不变）
+#
+# 参考：CocoaPods 源码
+#   - lib/cocoapods/installer/xcode/pods_project_generator/pods_project_writer.rb
 
+require 'digest'
 require 'concurrent'
 require 'etc'
 
@@ -21,37 +40,55 @@ module Pod
     module Patches
       module ProjectWriterPatch
         def self.apply
-          Pod::UI.message '[cocoapods-podgenerate] Applying ProjectWriterPatch v3 (incremental + parallel save + parallel write steps)'
+          Pod::UI.message '[cocoapods-podgenerate] Applying ProjectWriterPatch v4 (incremental + parallel save + parallel write)'
           Pod::Installer::Xcode::PodsProjectWriter.prepend(IncrementalAndParallelSave)
         end
 
         module IncrementalAndParallelSave
+          # 初始化：调用原始构造器后，计算所有项目的初始 SHA256 摘要
+          #
+          # @param sandbox [Sandbox]
+          # @param projects [Array<Project>] 所有需要管理的 Xcodeproj 项目
+          # @param pod_target_installation_results [Hash] pod target 安装结果
+          # @param installation_options [InstallationOptions]
           def initialize(sandbox, projects, pod_target_installation_results, installation_options)
             super
-            @project_digests = {}
-            @projects = projects
-            @sort_needed = {}
+            @project_digests = {}    # project.object_id => SHA256 摘要
+            @sort_needed = {}        # project.object_id => 是否需要排序
             compute_initial_digests
           end
 
-          # ── Optimizations 3+4+2: Parallel write! with parallel cleanup + schemes + save ──
+          # 并行清理、重建 scheme、然后增量保存所有项目
+          #
+          # 流程:
+          #   1. 并行清理每个项目的空 groups
+          #   2. 并行重建 scheme（将 test target 附加到 library target）
+          #   3. 执行 post-install hooks（yield）
+          #   4. SHA256 增量判断 + 并行保存
           def write!
-            # Parallel cleanup (each project is independent)
             parallel_cleanup_projects(@projects)
-
-            # Parallel recreate_user_schemes (each project is independent)
             parallel_recreate_user_schemes(@projects)
-
             yield if block_given?
-
             save_projects(@projects)
           end
 
-          # ── Optimization 1: SHA256 skip + parallel save ──
+          # 增量 + 并行保存项目
+          #
+          # 流程:
+          #   1. 过滤: 跳过 pbxproj 内容未变的项目（SHA256 摘要比对）
+          #   2. 排序: 对需要保存的项目调用 sort(:groups_position => :below)
+          #   3. 保存: 多项目并行写入（每个 xcodeproj 独立目录）
+          #
+          # 【Bug 修复 L1】
+          # 只有当 old_digest 和 current_digest 都非 nil 且相等时才跳过。
+          # 如果任一为 nil（例如文件不可读），一律重新保存以确保项目完整性。
+          #
+          # @param projects [Array<Project>] 要保存的项目列表
           def save_projects(projects)
-            # Filter: skip projects whose pbxproj is unchanged
             to_save = projects.select do |project|
-              if project_unchanged?(project)
+              old = @project_digests[project.object_id]
+              cur = digest_pbxproj(project)
+              if old && cur && old == cur
                 Pod::UI.message "- Skipping unchanged project #{UI.path project.path}"
                 false
               else
@@ -60,36 +97,38 @@ module Pod
             end
             return if to_save.empty?
 
-            # Sort each project
+            # 排序（串行 — sort 操作轻量，并行开销反而更大）
             to_save.each { |p| p.sort(:groups_position => :below) if needs_sort?(p) }
 
-            # Parallel save (safe: each xcodeproj is an independent directory)
+            # 并行保存
             if to_save.size > 1
               Pod::UI.message "- Saving #{to_save.size} projects in parallel"
               threads = to_save.map do |project|
                 Thread.new do
-                  begin
-                    Pod::UI.message "- Writing Xcode project file to #{UI.path project.path}"
-                    project.save
-                    update_digest(project)
-                  rescue StandardError => e
-                    Pod::UI.warn "[cocoapods-podgenerate] Parallel save error: #{e.message}"
-                  end
+                  Pod::UI.message "- Writing Xcode project file to #{UI.path project.path}"
+                  project.save
+                  update_digest(project)
+                rescue StandardError => e
+                  Pod::UI.warn "[cocoapods-podgenerate] Parallel save error: #{e.message}"
                 end
               end
               threads.each(&:join)
             else
-              Pod::UI.message "- Writing Xcode project file to #{UI.path to_save.first.path}" do
-                to_save.first.save
-                update_digest(to_save.first)
-              end
+              project = to_save.first
+              Pod::UI.message "- Writing Xcode project file to #{UI.path project.path}"
+              project.save
+              update_digest(project)
             end
           end
 
           private
 
-          # ── Optimization 3: Parallel cleanup_projects ──
+          # ── 并行清理项目空 groups ──
 
+          # 移除每个项目中为空的 pods、support_files、development_pods、dependencies groups
+          #
+          # 每个 project 独立，使用 Concurrent::FixedThreadPool 并行执行。
+          # 如果 concurrent-ruby 不可用（NameError），回退到串行处理。
           def parallel_cleanup_projects(projects)
             pool_size = compute_pool_size
             Pod::UI.message "- Cleaning up #{projects.size} projects (pool: #{pool_size})"
@@ -97,25 +136,24 @@ module Pod
             pool = begin
               Concurrent::FixedThreadPool.new(pool_size)
             rescue NameError
-              nil
+              nil # concurrent-ruby 不可用，回退到串行
             end
 
             if pool
               projects.each do |project|
-                pool.post do
-                  cleanup_single_project(project)
-                rescue StandardError => e
-                  Pod::UI.warn "[cocoapods-podgenerate] Cleanup error: #{e.message}"
-                end
+                pool.post { cleanup_single_project(project) }
+              rescue StandardError => e
+                Pod::UI.warn "[cocoapods-podgenerate] Cleanup error: #{e.message}"
               end
               pool.shutdown
-              pool.wait_for_termination
+              pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT) || pool.kill
             else
-              # Fallback: sequential (Concurrent not available)
+              # 串行回退
               projects.each { |p| cleanup_single_project(p) }
             end
           end
 
+          # 清理单个项目的空 groups
           def cleanup_single_project(project)
             [project.pods, project.support_files_group,
              project.development_pods, project.dependencies_group].each do |group|
@@ -123,12 +161,16 @@ module Pod
             end
           end
 
-          # ── Optimization 4: Parallel recreate_user_schemes ──
+          # ── 并行重建用户 scheme ──
 
+          # 为所有项目重建 scheme 文件，将 test target 附加到 library target
+          #
+          # results_by_native_target 在所有线程间是只读共享缓存，
+          # 每个线程读取同一个 Hash 但从不修改它 → 线程安全。
           def parallel_recreate_user_schemes(projects)
             library_product_types = [:framework, :dynamic_library, :static_library]
 
-            # Pre-build results_by_native_target once (shared read-only cache)
+            # 预构建 native target → InstallationResult 的查找缓存（只读、线程安全）
             results_by_native_target = build_native_target_cache
 
             pool_size = compute_pool_size
@@ -144,20 +186,24 @@ module Pod
               projects.each do |project|
                 pool.post do
                   recreate_schemes_for_project(project, library_product_types, results_by_native_target)
-                rescue StandardError => e
-                  Pod::UI.warn "[cocoapods-podgenerate] Scheme recreation error: #{e.message}"
                 end
+              rescue StandardError => e
+                Pod::UI.warn "[cocoapods-podgenerate] Scheme recreation error: #{e.message}"
               end
               pool.shutdown
-              pool.wait_for_termination
+              pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT) || pool.kill
             else
-              # Fallback: sequential (Concurrent not available)
               projects.each do |project|
                 recreate_schemes_for_project(project, library_product_types, results_by_native_target)
               end
             end
           end
 
+          # 为单个项目重建 scheme
+          #
+          # @param project [Project] Xcodeproj 项目
+          # @param library_product_types [Array<Symbol>] 需要添加 test target 的 library 类型
+          # @param results_by_native_target [Hash] native_target => InstallationResult 缓存
           def recreate_schemes_for_project(project, library_product_types, results_by_native_target)
             project.recreate_user_schemes(false) do |scheme, target|
               next unless target.respond_to?(:symbol_type)
@@ -170,6 +216,7 @@ module Pod
             end
           end
 
+          # 构建 native_target → InstallationResult 查找缓存
           def build_native_target_cache
             cache = {}
             @pod_target_installation_results.each do |_, result|
@@ -178,56 +225,42 @@ module Pod
             cache
           end
 
-          # ── Digest helpers (from v0.1.1) ──
+          # ── SHA256 摘要工具方法 ──
 
+          # 计算所有项目的初始 SHA256 摘要
           def compute_initial_digests
-            @projects.each do |project|
-              update_digest(project)
-            end
+            @projects.each { |p| update_digest(p) }
             @projects.each { |p| @sort_needed[p.object_id] = true }
           end
 
-          def project_unchanged?(project)
-            pbx_path = pbxproj_path(project)
-            return false unless pbx_path && File.exist?(pbx_path)
-
-            old_digest = @project_digests[project.object_id]
-            return false unless old_digest
-
-            current_digest = digest_file(pbx_path)
-            current_digest == old_digest
-          end
-
+          # 是否需要排序（首次写入总是需要）
           def needs_sort?(project)
             @sort_needed[project.object_id] != false
           end
 
+          # 更新项目的 SHA256 摘要缓存
           def update_digest(project)
-            pbx_path = pbxproj_path(project)
-            return unless pbx_path && File.exist?(pbx_path)
-
-            @project_digests[project.object_id] = digest_file(pbx_path)
+            digest = digest_pbxproj(project)
+            return unless digest
+            @project_digests[project.object_id] = digest
             @sort_needed[project.object_id] = false
           end
 
-          def pbxproj_path(project)
+          # 计算指定项目的 pbxproj 文件的 SHA256 摘要
+          #
+          # @param project [Project] Xcodeproj 项目
+          # @return [String, nil] SHA256 十六进制字符串，或 nil（文件不存在/不可读）
+          def digest_pbxproj(project)
             path = project.path
             return nil unless path
-            if path.to_s.end_with?('.xcodeproj')
-              File.join(path.to_s, 'project.pbxproj')
-            else
-              path.to_s
-            end
-          end
-
-          def digest_file(path)
-            require 'digest'
-            return nil unless File.file?(path)
-            Digest::SHA256.file(path).hexdigest
+            pbx_path = path.to_s.end_with?('.xcodeproj') ? File.join(path.to_s, 'project.pbxproj') : path.to_s
+            return nil unless File.file?(pbx_path)
+            Digest::SHA256.file(pbx_path).hexdigest
           rescue StandardError
             nil
           end
 
+          # 计算线程池大小
           def compute_pool_size
             [[Etc.nprocessors - 1, 2].max, 16].min
           rescue NameError

data/lib/cocoapods-podgenerate/patches/user_integrator_patch.rb

@@ -31,30 +31,52 @@ module Pod
 
         module ParallelIntegration
           # ── Optimization 1: Parallel integrate_user_targets ──
+          # 集成用户项目中的所有 Pod target（添加构建阶段、修改配置等）。
+          #
+          # 【竞态条件修复 H2】
+          # 多个 AggregateTarget 可能属于同一个 Xcodeproj::Project 文件
+          # （例如同一个 .xcodeproj 中包含多个 native target）。
+          # TargetIntegrator#integrate! 会修改项目（添加 build phases、修改
+          # configurations），如果两个线程同时修改同一个 Xcodeproj::Project 对象，
+          # 就会产生竞态条件，导致 pbxproj 文件损坏。
+          #
+          # 修复策略：
+          #   1. 按 user_project 将所有 target 分组
+          #   2. 同一个项目内的 target → 串行集成（避免竞态）
+          #   3. 不同项目之间 → 并行集成（利用多核性能）
           def integrate_user_targets
             target_integrators = targets_to_integrate.sort_by(&:name).map do |target|
               Pod::Installer::UserProjectIntegrator::TargetIntegrator.new(target, :use_input_output_paths => use_input_output_paths?)
             end
 
-            if target_integrators.size <= 1
-              target_integrators.each(&:integrate!)
-              return
-            end
+            return if target_integrators.empty?
+            return target_integrators.each(&:integrate!) if target_integrators.size <= 1
 
-            Pod::UI.message "- Integrating #{target_integrators.size} targets in parallel"
-            threads = target_integrators.map do |integrator|
-              Thread.new do
-                begin
-                  integrator.integrate!
-                rescue StandardError => e
-                  Pod::UI.warn "[cocoapods-podgenerate] Target integration error: #{e.message}"
+            # 按 user_project 分组：同一项目的 target 共享同一个 Xcodeproj::Project 对象
+            groups = target_integrators.group_by { |ti| ti.send(:target).user_project }
+
+            if groups.size <= 1
+              # 所有 target 都属于同一项目 → 串行执行，避免竞态条件
+              target_integrators.each(&:integrate!)
+            else
+              # 不同项目 → 跨组并行，组内串行（同一项目内只有一个线程在修改）
+              Pod::UI.message "- Integrating #{target_integrators.size} targets across #{groups.size} projects in parallel"
+              threads = groups.map do |project, integrators|
+                Thread.new do
+                  integrators.each(&:integrate!)
                 end
               end
+              threads.each(&:join)
             end
-            threads.each(&:join)
           end
 
           # ── Optimization 2: Parallel save_projects ──
+          # 保存修改后的用户项目文件。
+          #
+          # 使用并行线程保存多个 Xcodeproj 项目以提高性能。
+          # 脏项目调用 project.save 写入 pbxproj，非脏项目则 touch pbxproj
+          # 以更新文件修改时间（确保增量构建工具能正确检测变更）。
+          # FileUtils.touch 操作用 Mutex 保护，因为 touch 不是线程安全的。
           def save_projects(projects)
             projects = projects.uniq
 
@@ -90,7 +112,16 @@ module Pod
           end
 
           # ── Optimization 3: Parallel warn_about_xcconfig_overrides ──
-          # Overrides the original method by prepend — called automatically from integrate!
+          # 检查并警告用户项目中 xcconfig 构建设置的覆盖情况。
+          #
+          # 通过 prepend 覆盖原始方法，在 integrate! 内部被自动调用。
+          # 使用 Concurrent::FixedThreadPool 线程池并行检查多个 target，
+          # 池大小由 compute_pool_size 计算（CPU 核心数 - 1，范围 2..16）。
+          # 如果 NameError（例如 concurrent-ruby 不可用），回退到串行执行。
+          #
+          # 注意：此方法操作的是 targets_to_integrate（AggregateTarget 数组），
+          # 不同 target 属于不同项目（或部分属于同一项目），但由于只是读取
+          # xcconfig 设置并打印警告，不修改项目，因此不存在竞态条件。
           def warn_about_xcconfig_overrides
             targets = targets_to_integrate
             return if targets.empty?
@@ -111,17 +142,32 @@ module Pod
               end
             end
             pool.shutdown
-            pool.wait_for_termination
+            unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+              Pod::UI.warn '[cocoapods-podgenerate] UserIntegratorPatch: timed out waiting for xcconfig override checks'
+            end
           rescue NameError
             targets.each { |t| warn_single_target(t) }
           end
 
           private
 
-          # Per-target xcconfig override check. Runs inside a thread pool slot.
-          # NOTE: `print_override_warning` is a private method on the original
-          # UserProjectIntegrator class. Ruby allows implicit-receiver calls to
-          # private methods from prepended modules (no explicit `self.` prefix).
+          # 对单个 AggregateTarget 检查其所有 user target 的 xcconfig 覆盖情况。
+          #
+          # 遍历逻辑：
+          #   1. 遍历 aggregate_target 的所有 user_target
+          #   2. 对每个 user_target 的每个构建配置，取出对应 xcconfig 中的设置
+          #   3. 比较 xcconfig 设置与当前构建设置：如果用户已在构建设置中赋值
+          #      （非 $(inherited)），则打印覆盖警告
+          #
+          # 忽略 CODE_SIGN_IDENTITY 等特定 key（定义在 IGNORED_KEYS 中），
+          # 这些 key 的覆盖是预期行为，不需要警告。
+          #
+          # 在线程池的某个槽位中运行，通过 rescue 捕获异常避免单 target 错误
+          # 影响其他 target 的检查。
+          #
+          # 注意：print_override_warning 是原始 UserProjectIntegrator 类的
+          # private 方法。Ruby 允许从 prepended module 中以隐式 receiver 的
+          # 方式调用 private 方法（无需显式 self. 前缀）。
           def warn_single_target(aggregate_target)
             aggregate_target.user_targets.each do |user_target|
               user_target.build_configurations.each do |config|

data/lib/cocoapods-podgenerate.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
+# [cocoapods-podgenerate]
+# 插件入口文件 — 加载所有补丁和工具模块，激活优化。
+#
+# 加载顺序（重要—有依赖关系）:
+#   1. 各 patch 文件（通过 prepend monkey-patch CocoaPods 内部类）
+#   2. 并行工具模块（线程池、批处理器）
+#   3. 性能分析器
+#
+# 激活方式:
+#   - `plugin 'cocoapods-podgenerate'` in Podfile → CocoaPods 加载 cocoapods_plugin.rb
+#     → require 此文件 → 如果 Pod::HooksManager 已定义则立即 activate
+#   - 如果 Pod::HooksManager 尚未定义（例如加载顺序不同），
+#     使用 TracePoint 延迟激活（带 500 次安全检查防止资源泄漏）
+#   - hooks.rb 注册了 :pre_install hook 作为兜底（如果 TracePoint 也错过了）
+
 require 'cocoapods-podgenerate/patches/installer_patch'
 require 'cocoapods-podgenerate/patches/project_patch'
 require 'cocoapods-podgenerate/patches/project_writer_patch'
@@ -13,8 +28,19 @@ require 'cocoapods-podgenerate/benchmark/profiler'
 
 module Pod
   module PodGenerate
+    # 激活所有优化补丁
+    #
+    # 幂等安全：多次调用只执行一次（@activated 守卫）。
+    # 所有补丁通过 Module#prepend 注入，如果重复 prepend 会导致
+    # 祖先链中出现重复模块，super 调用链混乱。
     def self.activate
-      # Register all patches
+      return if @activated
+      @activated = true
+
+      # 确保 hooks 被加载（pre_install hook 作为兜底激活路径）
+      require_relative 'cocoapods-podgenerate/hooks'
+
+      # 按依赖顺序注册补丁
       Pod::PodGenerate::Patches::InstallerPatch.apply
       Pod::PodGenerate::Patches::ProjectPatch.apply
       Pod::PodGenerate::Patches::ProjectWriterPatch.apply
@@ -23,7 +49,7 @@ module Pod
       Pod::PodGenerate::Patches::MultiProjectGeneratorPatch.apply
       Pod::PodGenerate::Patches::CacheAnalyzerPatch.apply
 
-      # Install hook for profiler
+      # 安装性能分析器钩子
       Pod::PodGenerate::Benchmark::Profiler.install
 
       Pod::UI.message '[cocoapods-podgenerate] Activated!'
@@ -31,15 +57,30 @@ module Pod
   end
 end
 
-# Auto-activate when loaded via `plugin` directive in Podfile
+# 自动激活机制
+#
+# CocoaPods 的插件加载流程:
+#   1. Podfile 中 `plugin 'cocoapods-podgenerate'` → CLAide 加载 cocoapods_plugin.rb
+#   2. cocoapods_plugin.rb → require 'cocoapods-podgenerate' → 此文件
+#   3. 此时 Pod::HooksManager 通常已由 cocoapods gem 的初始化过程定义
+#
+# 如果 Pod::HooksManager 已定义 → 立即激活
+# 否则 → TracePoint 延迟激活，监听 :class 事件直到 HooksManager 被定义
 if defined?(Pod::HooksManager)
   Pod::PodGenerate.activate
 else
-  # Defer activation: when CocoaPods is loaded after this file
-  TracePoint.trace(:class) do |tp|
-    if tp.self == Pod::HooksManager
+  # TracePoint 延迟激活（带安全检查）
+  # [:class] 事件在 Ruby 每次打开 class/module 时触发
+  # 500 次上限：正常情况下 HooksManager 在前 10-20 次就会被发现，
+  # 如果超过 500 次说明加载环境异常，及时禁用避免永久性能开销
+  count = 0
+  tp = TracePoint.trace(:class) do |tp_event|
+    count += 1
+    if tp_event.self == Pod::HooksManager
       Pod::PodGenerate.activate
-      tp.disable
+      tp_event.disable
+    elsif count > 500
+      tp_event.disable # 安全阀：防止资源泄漏
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cocoapods-podgenerate
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - PodGenerate Team