cocoapods-podfile-local 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a2d1a17a228a1b6d6f1d73d24a9b85b66dd5492550d710a3bb373cea510ba3a
+  data.tar.gz: 39d97d0c86deb19c3eaf8f95bbc8f64a362b3b532949bb55c27eb6ba1b9ed964
+SHA512:
+  metadata.gz: 96f8f2de20ce2f498e20a9d1468781baabbc9527e1cd037a5e4ed3f5c3a15dead86d9c9861db42e031901d9b8a181e40b808677f5bcd805e2bb8e9e805ff98b6
+  data.tar.gz: ac6653cab35a5938172d731abbb55c11e4e1a4f22d99f83743c3a01247b4ff8a85436b05fe926a8a92b7224af930dfb01e0ce6b688b2a2299fa15c42cc8f9fe1

data/README.md

@@ -0,0 +1,166 @@
+# cocoapods-podfile-local
+
+一个 CocoaPods 插件，让每个开发者通过 `Podfile.local` 文件覆盖 pod 的引入方式（git 分支、本地路径等），无需修改共享的 Podfile。
+
+## 使用方法
+
+### 1. 创建 Podfile.local
+
+在项目根目录创建 `Podfile.local`（已加入 `.gitignore`，不会被提交）：
+
+```ruby
+# 指向本地路径（联调开发最常用）
+edit 'VKRouteKit', :path => '../VKRouteKit'
+
+# 指向 git 仓库 + feature 分支
+edit 'CustomLib', :git => 'git@gitlab.com:xxx/CustomLib.git', :branch => 'feature/login'
+
+# 指向 git tag
+edit 'SomeSDK', :git => 'git@gitlab.com:xxx/SomeSDK.git', :tag => 'v1.2.3'
+
+# 指向特定 commit
+edit 'SomeSDK', :git => 'git@gitlab.com:xxx/SomeSDK.git', :commit => 'abc123'
+
+# 使用自定义 podspec
+edit 'MyPod', :podspec => './local_specs/MyPod.podspec'
+
+# 只覆盖非来源选项（保留原始版本/来源）
+edit 'DebugTool', :configurations => ['Debug']
+
+# 组合覆盖
+edit 'VKWebBridge', :git => 'git@gitlab.com:xxx/VKWebBridge.git', :branch => 'hotfix/crash', :configurations => ['Debug']
+```
+
+### 2. 执行安装
+
+```bash
+bundle exec pod install
+```
+
+控制台会输出覆盖日志：
+
+```
+[Podfile.local] Loading /path/to/project/Podfile.local
+[Podfile.local] Overriding 'VKRouteKit' with {:path=>"../VKRouteKit"}
+[Podfile.local] Overriding 'CustomLib' with {:git=>"git@gitlab.com:xxx/CustomLib.git", :branch=>"feature/login"}
+```
+
+### 3. 恢复原始状态
+
+删除或清空 `Podfile.local`，重新 `pod install` 即可。
+
+## 互斥源自动清理
+
+覆盖来源时，插件会自动清除与之冲突的旧选项：
+
+| edit 指定     | 自动清除                                    |
+|---------------|---------------------------------------------|
+| `:git`        | `:path`, `:podspec`                         |
+| `:path`       | `:git`, `:branch`, `:tag`, `:commit`, `:podspec` |
+| `:podspec`    | `:git`, `:branch`, `:tag`, `:commit`, `:path`    |
+
+例如原始 pod 用 `:git` + `:branch` 引入，你 edit 为 `:path`，插件会自动清除 `:git` 和 `:branch`，无需手动处理。
+
+## 工作原理
+
+### CocoaPods 生命周期
+
+```
+pod install
+    │
+    ▼
+① 加载 gem（插件在此阶段加载）     ← 插件读取 Podfile.local，拦截 pod 方法
+    │
+    ▼
+② 解析 Podfile（逐行执行 Ruby 代码） ← 拦截的 pod 方法在此阶段替换参数
+    │
+    ▼
+③ 解析依赖（resolver 计算版本来源）   ← 此时 Kingfisher 已经是 :path 来源
+    │
+    ▼
+④ 下载 & 安装
+```
+
+### 核心机制
+
+插件在加载阶段（早于 Podfile 解析）完成两件事：
+
+**1. 读取 Podfile.local，收集覆盖配置**
+
+创建一个独立的 `PodfileLocalLoader` 对象，用 `instance_eval` 执行 `Podfile.local` 内容。每个 `edit` 调用将覆盖选项注册到 `OverrideManager` 单例。
+
+**2. 用 `prepend` 拦截 `Pod::Podfile::DSL#pod` 方法**
+
+在 `pod` 方法的查找链前面插入一个包装模块。当 Podfile 解析到 `pod 'Kingfisher', '~> 8.0'` 时：
+
+1. 包装方法检查 OverrideManager 中是否有 `'Kingfisher'` 的覆盖 → 有
+2. 从原始参数中分离版本号（`'~> 8.0'`）和选项 Hash
+3. 执行互斥源清理 + 选项合并
+4. 如果覆盖指定了 `:path` / `:git` / `:podspec`，移除版本号约束
+5. 用合并后的参数调用 `super`（原始 `pod` 方法）
+
+对 CocoaPods 来说，就好像 Podfile 里直接写的就是覆盖后的内容。
+
+### 时序图
+
+```mermaid
+sequenceDiagram
+    participant User as pod install
+    participant CP as CocoaPods
+    participant Plugin as cocoapods-podfile-local
+    participant OM as OverrideManager
+    participant PF as Podfile
+
+    User->>CP: bundle exec pod install
+    CP->>Plugin: require cocoapods_plugin.rb
+    Plugin->>Plugin: setup!
+    Plugin->>Plugin: load_podfile_local!
+    Plugin->>OM: edit 'Kingfisher', path:... → register
+    Plugin->>Plugin: patch_pod_dsl! (prepend)
+
+    CP->>PF: 开始解析 Podfile
+    PF->>Plugin: pod 'Alamofire', '~> 5.9'
+    Plugin->>OM: 有覆盖? → 无
+    Plugin->>CP: super → 原样注册
+
+    PF->>Plugin: pod 'Kingfisher', '~> 8.0'
+    Plugin->>OM: 有覆盖? → 有!
+    OM->>OM: merge + 互斥源清理
+    Plugin->>CP: super('Kingfisher', path:'...') → 替换注册
+
+    CP->>CP: 解析依赖 (Kingfisher 已是 path 来源)
+    CP->>CP: 下载 & 安装
+```
+
+### 文件结构
+
+```
+plugins/cocoapods-podfile-local/
+├── cocoapods-podfile-local.gemspec   # gem 描述
+├── README.md                         # 本文档
+└── lib/
+    ├── cocoapods_plugin.rb           # CocoaPods 插件入口（硬性约定）
+    ├── cocoapods-podfile-local.rb    # 主入口，require 各模块 + 调用 setup!
+    └── cocoapods_podfile_local/
+        ├── version.rb                # 版本号
+        ├── dsl.rb                    # 注入 edit 方法到 Pod::Podfile
+        ├── override_manager.rb       # 覆盖注册、互斥清理、选项合并
+        └── hook.rb                   # 加载 Podfile.local + prepend 拦截 pod 方法
+```
+
+### 关键设计决策
+
+- **为什么不用 `pre_install` hook？** `pre_install` 在依赖解析之后才执行，此时修改 Dependency 对象已经不影响解析结果。必须在 Podfile 解析阶段拦截。
+
+- **为什么用 `prepend` 而不是 `alias_method`？** `prepend` 是 Ruby 推荐的方法拦截方式，在方法查找链中插入模块，可以用 `super` 调用原始方法，不会污染命名空间。
+
+- **为什么 Podfile.local 用独立 Loader 而不是在 Podfile 上下文中 eval？** 插件加载时 Podfile 实例尚不存在，无法在其上下文中执行。用独立的 `PodfileLocalLoader` 对象来收集配置，与 Podfile 解析过程解耦。
+
+- **为什么 `cocoapods_plugin.rb` 是必须的？** CocoaPods 通过检查 gem 中是否存在 `lib/cocoapods_plugin.rb` 来判断是否为合法插件，这是硬性约定。
+
+## 注意事项
+
+- `Podfile.local` 已加入 `.gitignore`，每个开发者独立维护
+- edit 一个 Podfile 中不存在的 pod 会输出警告但不会中断安装
+- 首次使用需要先 `bundle install` 安装插件
+- 插件作为本地 gem 内嵌在项目中，无需发布到 RubyGems

data/lib/cocoapods-podfile-local.rb

@@ -0,0 +1,6 @@
+require 'cocoapods_podfile_local/version'
+require 'cocoapods_podfile_local/override_manager'
+require 'cocoapods_podfile_local/dsl'
+require 'cocoapods_podfile_local/hook'
+
+CocoapodsPodfileLocal.setup!

data/lib/cocoapods_plugin.rb

@@ -0,0 +1 @@
+require 'cocoapods-podfile-local'

data/lib/cocoapods_podfile_local/dsl.rb

@@ -0,0 +1,13 @@
+module CocoapodsPodfileLocal
+  module DSL
+    def edit(pod_name, options = {})
+      CocoapodsPodfileLocal::OverrideManager.instance.register(pod_name, options)
+    end
+  end
+end
+
+module Pod
+  class Podfile
+    include CocoapodsPodfileLocal::DSL
+  end
+end

data/lib/cocoapods_podfile_local/hook.rb

@@ -0,0 +1,57 @@
+module CocoapodsPodfileLocal
+  TAG = '[Podfile.local]'.freeze
+
+  class PodfileLocalLoader
+    def edit(pod_name, options = {})
+      OverrideManager.instance.register(pod_name, options)
+    end
+  end
+
+  class << self
+    def setup!
+      load_podfile_local!
+      return if OverrideManager.instance.empty?
+      patch_pod_dsl!
+    end
+
+    private
+
+    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
+      loader.instance_eval(local_file.read, local_file.to_s)
+    end
+
+    def patch_pod_dsl!
+      manager = OverrideManager.instance
+
+      Pod::Podfile::DSL.prepend(Module.new do
+        define_method(:pod) do |name = nil, *requirements|
+          if name && manager.overrides.key?(name)
+            override_opts = manager.overrides[name]
+
+            original_opts = requirements.last.is_a?(Hash) ? requirements.pop : {}
+            version_reqs = requirements
+
+            merged = manager.merge(original_opts, override_opts)
+
+            if merged.key?(:path) || merged.key?(:git) || merged.key?(:podspec)
+              version_reqs = []
+            end
+
+            Pod::UI.message "#{TAG} Overriding '#{name}' with #{merged}"
+
+            new_requirements = version_reqs
+            new_requirements << merged unless merged.empty?
+            super(name, *new_requirements)
+          else
+            super(name, *requirements)
+          end
+        end
+      end)
+    end
+  end
+end

data/lib/cocoapods_podfile_local/override_manager.rb

@@ -0,0 +1,51 @@
+module CocoapodsPodfileLocal
+  class OverrideManager
+    SOURCE_KEYS = %i[git path podspec].freeze
+    GIT_EXTRAS  = %i[branch tag commit].freeze
+
+    EXCLUSIVE_RULES = {
+      git:     %i[path podspec],
+      path:    %i[git branch tag commit podspec],
+      podspec: %i[git branch tag commit path],
+    }.freeze
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def self.reset!
+      @instance = nil
+    end
+
+    def initialize
+      @overrides = {}
+    end
+
+    def register(pod_name, options)
+      @overrides[pod_name] = options
+    end
+
+    def overrides
+      @overrides.dup
+    end
+
+    def empty?
+      @overrides.empty?
+    end
+
+    # Merge override options into the original options, with exclusive-source cleanup.
+    def merge(original_options, override_options)
+      merged = original_options.dup
+
+      keys_to_remove = []
+      EXCLUSIVE_RULES.each do |source_key, conflicting_keys|
+        if override_options.key?(source_key)
+          keys_to_remove.concat(conflicting_keys)
+        end
+      end
+
+      keys_to_remove.uniq.each { |k| merged.delete(k) }
+      merged.merge(override_options)
+    end
+  end
+end

data/lib/cocoapods_podfile_local/version.rb

@@ -0,0 +1,3 @@
+module CocoapodsPodfileLocal
+  VERSION = '0.1.0'.freeze
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: cocoapods-podfile-local
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dairuiquan
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cocoapods
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  A CocoaPods plugin that lets each developer maintain a local Podfile.local
+  file (git-ignored) to override pod sources — pointing to git branches,
+  local paths, tags, commits, or custom podspecs — without modifying the
+  shared Podfile.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/cocoapods-podfile-local.rb
+- lib/cocoapods_plugin.rb
+- lib/cocoapods_podfile_local/dsl.rb
+- lib/cocoapods_podfile_local/hook.rb
+- lib/cocoapods_podfile_local/override_manager.rb
+- lib/cocoapods_podfile_local/version.rb
+homepage: https://rubygems.org/gems/cocoapods-podfile-local
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Override pod sources via Podfile.local without touching the shared Podfile.
+test_files: []