cocoapods-podfile-local 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a2d1a17a228a1b6d6f1d73d24a9b85b66dd5492550d710a3bb373cea510ba3a
-  data.tar.gz: 39d97d0c86deb19c3eaf8f95bbc8f64a362b3b532949bb55c27eb6ba1b9ed964
+  metadata.gz: 6dde6f4485ef1ea469899415b9e21f24dca2ab4b80c5671e0677202ae98a93ee
+  data.tar.gz: 1308d7accd337a4326ae8b42d0a128d7fa7e144214cf913a3baacb55412b252c
 SHA512:
-  metadata.gz: 96f8f2de20ce2f498e20a9d1468781baabbc9527e1cd037a5e4ed3f5c3a15dead86d9c9861db42e031901d9b8a181e40b808677f5bcd805e2bb8e9e805ff98b6
-  data.tar.gz: ac6653cab35a5938172d731abbb55c11e4e1a4f22d99f83743c3a01247b4ff8a85436b05fe926a8a92b7224af930dfb01e0ce6b688b2a2299fa15c42cc8f9fe1
+  metadata.gz: 59544d3511a1873d8f83839e98ad65df635e36e52cc823f1af1cfcf997b8a172f518ed7f339a0af05ac558f54b15f14bf1c304f48931d6235cb3b6355d420ff5
+  data.tar.gz: d38806881cc4bb885a9b1d1c48d695226917b067dea44cac99996114e6956b20bad6c0e27ad0137f6623e7d274bd8fec07fbbc624628a591c2baee1d27cd5e2b

data/README.md

@@ -45,7 +45,11 @@ bundle exec pod install
 [Podfile.local] Overriding 'CustomLib' with {:git=>"git@gitlab.com:xxx/CustomLib.git", :branch=>"feature/login"}
 ```
 
-### 3. 恢复原始状态
+### 3. 在 Xcode 中查看
+
+当根目录存在 `Podfile.local` 时，`pod install` 会把它像 `Podfile` 一样加入 **Pods** 工程（`Pods.xcodeproj` 根分组），打开 `*.xcworkspace` 后在左侧 **Pods** 项目里紧挨 `Podfile` 即可编辑。若删除了 `Podfile.local`，下次 `pod install` 会同步移除该文件引用。
+
+### 4. 恢复原始状态
 
 删除或清空 `Podfile.local`，重新 `pod install` 即可。
 

data/lib/cocoapods-podfile-local.rb

@@ -1,6 +1,15 @@
+# 插件主入口：被 Gemfile / cocoapods_plugin 加载后顺序执行。
+#
+# 流程概览：
+# 1. setup! —— 读 Podfile.local、若无覆盖则结束；若有则 prepend 拦截 Podfile 里的 `pod`。
+# 2. register_post_install_hook! —— 安装结束后把 Podfile.local 挂进 Pods.xcodeproj，方便 Xcode 浏览。
+
 require 'cocoapods_podfile_local/version'
 require 'cocoapods_podfile_local/override_manager'
 require 'cocoapods_podfile_local/dsl'
 require 'cocoapods_podfile_local/hook'
+require 'cocoapods_podfile_local/pods_project_integration'
 
 CocoapodsPodfileLocal.setup!
+# 注册 post_install：在 Pods 工程里同步 Podfile.local 的文件引用，便于在 Xcode 中浏览编辑。
+CocoapodsPodfileLocal::PodsProjectIntegration.register_post_install_hook!

data/lib/cocoapods_plugin.rb

@@ -1 +1,3 @@
+# CocoaPods 约定：名为 cocoapods_plugin.rb 的文件会在解析 Podfile 的 `plugin '...'` 时自动 require。
+# 这里只做一件事：加载同 gem 里的主入口 cocoapods-podfile-local.rb。
 require 'cocoapods-podfile-local'

data/lib/cocoapods_podfile_local/dsl.rb

@@ -1,5 +1,7 @@
 module CocoapodsPodfileLocal
+  # 声明式 DSL：`edit 'PodName', ...` 与 Podfile 里 `pod` 的关键字参数风格一致。
   module DSL
+    # 将某个 pod 的覆盖选项登记到 OverrideManager，后续在解析主 Podfile 的 `pod` 时合并生效。
     def edit(pod_name, options = {})
       CocoapodsPodfileLocal::OverrideManager.instance.register(pod_name, options)
     end
@@ -8,6 +10,8 @@ end
 
 module Pod
   class Podfile
+    # 把 `edit` 混进官方 Podfile 类（与主 Podfile 同一解析上下文时可用）。
+    # 实际团队约定把覆盖写在 Podfile.local；hook 里另用 PodfileLocalLoader 做 instance_eval，不依赖此处。
     include CocoapodsPodfileLocal::DSL
   end
 end

data/lib/cocoapods_podfile_local/hook.rb

@@ -1,6 +1,9 @@
 module CocoapodsPodfileLocal
+  # 控制台日志前缀，便于 grep 与区分 CocoaPods 自带输出。
   TAG = '[Podfile.local]'.freeze
 
+  # 仅用于执行 Podfile.local 的轻量对象：提供 `edit`，内部转给 OverrideManager。
+  # 不能用主 Podfile 实例去 eval，因为插件加载时主 Podfile 尚未开始解析。
   class PodfileLocalLoader
     def edit(pod_name, options = {})
       OverrideManager.instance.register(pod_name, options)
@@ -8,6 +11,7 @@ module CocoapodsPodfileLocal
   end
 
   class << self
+    # 插件被 require 时调用：先收集覆盖，再（若有覆盖）改写 Podfile::DSL#pod 的查找链。
     def setup!
       load_podfile_local!
       return if OverrideManager.instance.empty?
@@ -16,15 +20,18 @@ module CocoapodsPodfileLocal
 
     private
 
+    # 在工程根目录查找 Podfile.local，存在则 Ruby 实例内执行其内容（仅应包含 edit 调用）。
     def load_podfile_local!
       local_file = Pathname.pwd + 'Podfile.local'
       return unless local_file.exist?
 
       Pod::UI.message "#{TAG} Loading #{local_file}"
       loader = PodfileLocalLoader.new
+      # 第二个参数为「虚拟文件名」，栈追踪里会显示 Podfile.local 路径，便于排错。
       loader.instance_eval(local_file.read, local_file.to_s)
     end
 
+    # 在 Pod::Podfile::DSL 前插入一个匿名模块：先处理覆盖再 call super，对未覆盖的 pod 原样透传。
     def patch_pod_dsl!
       manager = OverrideManager.instance
 
@@ -33,11 +40,13 @@ module CocoapodsPodfileLocal
           if name && manager.overrides.key?(name)
             override_opts = manager.overrides[name]
 
+            # CocoaPods 约定：版本/requirement 在前，最后一项可为 Hash（:path、:git 等）。
             original_opts = requirements.last.is_a?(Hash) ? requirements.pop : {}
             version_reqs = requirements
 
             merged = manager.merge(original_opts, override_opts)
 
+            # 一旦指定了 path/git/podspec 等「外部源」，版本号约束无意义，与 CocoaPods 行为对齐。
             if merged.key?(:path) || merged.key?(:git) || merged.key?(:podspec)
               version_reqs = []
             end

data/lib/cocoapods_podfile_local/override_manager.rb

@@ -1,8 +1,12 @@
 module CocoapodsPodfileLocal
+  # 单例：在「解析 Podfile.local」与「prepend 后的 pod 方法」之间共享覆盖表。
   class OverrideManager
+    # 表示「依赖来源」的三类主键，与 CocoaPods pod 声明一致（与下方互斥规则对应）。
     SOURCE_KEYS = %i[git path podspec].freeze
+    # 依附于 :git 的附加字段；与 path/podspec 来源互斥时一并清理。
     GIT_EXTRAS  = %i[branch tag commit].freeze
 
+    # 当 edit 指定某一来源时，应从「原 Podfile 选项」里删掉的冲突键，避免 path 与 git 等同时存在。
     EXCLUSIVE_RULES = {
       git:     %i[path podspec],
       path:    %i[git branch tag commit podspec],
@@ -13,6 +17,7 @@ module CocoapodsPodfileLocal
       @instance ||= new
     end
 
+    # 测试或多次加载场景下可清空单例（一般 pod install 单次进程不需要）。
     def self.reset!
       @instance = nil
     end
@@ -33,7 +38,7 @@ module CocoapodsPodfileLocal
       @overrides.empty?
     end
 
-    # Merge override options into the original options, with exclusive-source cleanup.
+    # 先把原 Hash 里与「新来源」冲突的键删掉，再 merge 覆盖项；覆盖键优先，其余保留原 Podfile。
     def merge(original_options, override_options)
       merged = original_options.dup
 

data/lib/cocoapods_podfile_local/pods_project_integration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Podfile.local 的 Xcode 集成：与依赖覆盖逻辑（hook.rb）独立，仅影响工程导航展示。
+require 'pathname'
+
+module CocoapodsPodfileLocal
+  # 把 Podfile.local 挂到 Pods.xcodeproj 的根分组里（和 CocoaPods 自带的 Podfile 引用方式一致），
+  # 这样打开 .xcworkspace 后能在 Xcode 左侧导航里直接点开编辑；若本地删掉了 Podfile.local，下次 install 会去掉引用。
+  module PodsProjectIntegration
+    # Pods 工程在 `项目/Pods/` 下，根目录的 Podfile.local 相对路径就是上一级目录里的文件。
+    PODFILE_RELATIVE = '../Podfile.local'
+
+    class << self
+      # 向 CocoaPods 注册「安装结束后」执行的钩子；同一 Ruby 进程里只注册一次，避免重复执行。
+      def register_post_install_hook!
+        return if @post_install_registered
+
+        @post_install_registered = true
+        # post_install 时 CocoaPods 已生成/更新完 Pods.xcodeproj，此时改工程文件是安全的。
+        Pod::HooksManager.register('cocoapods-podfile-local', :post_install) do |context|
+          sync_podfile_local_file_reference(context)
+        end
+      end
+
+      private
+
+      # context 由 CocoaPods 传入，内含 sandbox、pods_project（即 Pods.xcodeproj 的 Xcodeproj 对象）等。
+      def sync_podfile_local_file_reference(context)
+        pods_project = context.pods_project
+        return unless pods_project
+
+        # main_group：Xcode 里 Pods 工程最顶层那个分组，Podfile 的引用就挂在这里。
+        main = pods_project.root_object.main_group
+        # sandbox_root 一般是 `.../Pods`，上一级才是壳工程根目录，Podfile.local 与 Podfile 同级。
+        local_path = Pathname(context.sandbox_root).parent + 'Podfile.local'
+        # 若上次 install 已加过引用，避免重复插入。
+        existing = main.files.find { |f| f.path == PODFILE_RELATIVE }
+        changed = false
+
+        if local_path.file?
+          unless existing
+            # :project 表示路径相对于「工程文件所在目录」，即 Pods/，会得到与 Podfile 相同的 SOURCE_ROOT + ../Podfile.local。
+            ref = main.new_reference(local_path, :project)
+            ref.name = 'Podfile.local'
+            # 下面这些属性与 CocoaPods 为 Podfile 生成的 PBXFileReference 一致，便于 Xcode 按 Ruby 语法高亮。
+            ref.set_explicit_file_type('text.script.ruby')
+            ref.last_known_file_type = 'text'
+            ref.indent_width = '2'
+            ref.tab_width = '2'
+            ref.xc_language_specification_identifier = 'xcode.lang.ruby'
+
+            # new_reference 默认把新文件加在分组末尾；这里挪到 Podfile 后面，导航里两条挨在一起。
+            podfile_ref = main.files.find { |f| f.path == '../Podfile' }
+            if podfile_ref
+              main.children.delete(ref)
+              idx = main.children.index(podfile_ref)
+              main.children.insert(idx + 1, ref) if idx
+            end
+            changed = true
+          end
+        elsif existing
+          # 开发者删了 Podfile.local 后，工程里会剩「断链」引用，主动删掉保持干净。
+          existing.remove_from_project
+          changed = true
+        end
+
+        # 无变更不写盘，减少 pbxproj 无意义 diff、也略快一点。
+        pods_project.save if changed
+      end
+    end
+  end
+end

data/lib/cocoapods_podfile_local/version.rb

@@ -1,3 +1,4 @@
 module CocoapodsPodfileLocal
-  VERSION = '0.1.0'.freeze
+  # 语义化版本；发布到 RubyGems 或 `gem build` 时与 gemspec 共用此常量。
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocoapods-podfile-local
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - dairuiquan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods
@@ -46,6 +46,7 @@ files:
 - lib/cocoapods_podfile_local/dsl.rb
 - lib/cocoapods_podfile_local/hook.rb
 - lib/cocoapods_podfile_local/override_manager.rb
+- lib/cocoapods_podfile_local/pods_project_integration.rb
 - lib/cocoapods_podfile_local/version.rb
 homepage: https://rubygems.org/gems/cocoapods-podfile-local
 licenses: