CocoaPods 源码导读：从命令到依赖求解

# CocoaPods/bin/pod : 24
if $PROGRAM_NAME == __FILE__ && !ENV['COCOAPODS_NO_BUNDLER']
  ENV['BUNDLE_GEMFILE'] = File.expand_path('../../Gemfile', __FILE__)
  require 'rubygems'
  require 'bundler/setup'
  $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
elsif ENV['COCOAPODS_NO_BUNDLER']
  require 'rubygems'
  gem 'cocoapods'
end

STDOUT.sync = true if ENV['CP_STDOUT_SYNC'] == 'TRUE'
require 'cocoapods'

if profile_filename = ENV['COCOAPODS_PROFILE']
  # 开 ruby-prof 做性能剖析
  # ...
  reporter.new(RubyProf.profile { Pod::Command.run(ARGV) }).print(io)
else
  Pod::Command.run(ARGV)
end

# CocoaPods/lib/cocoapods/command.rb : 16
class Command < CLAide::Command
  require 'cocoapods/command/options/repo_update'
  require 'cocoapods/command/options/project_directory'
  include Options

  require 'cocoapods/command/cache'
  require 'cocoapods/command/env'
  require 'cocoapods/command/init'
  require 'cocoapods/command/install'
  # ...

  self.abstract_command = true
  self.command = 'pod'
  self.version = VERSION
  self.description = 'CocoaPods, the Cocoa library package manager.'
  self.plugin_prefixes = %w(claide cocoapods)
  # ...
end

# CocoaPods/lib/cocoapods/command.rb : 47
def self.run(argv)
  ensure_not_root_or_allowed! argv    # 不允许 root 运行 (除非 --allow-root)
  verify_minimum_git_version!         # git >= 1.8.5
  verify_xcode_license_approved!      # xcodebuild -license
  super(argv)                         # ← 进 CLAide::Command.run
ensure
  UI.print_warnings                   # 打印积累的 warning
end

# CLAide/lib/claide/command.rb : 324
def self.run(argv = [])
  plugin_prefixes.each do |plugin_prefix|
    PluginManager.load_plugins(plugin_prefix)   # ① 加载插件
  end

  argv = ARGV.coerce(argv)
  command = parse(argv)                          # ② 解析到具体 Command 实例
  ANSI.disabled = !command.ansi_output?
  unless command.handle_root_options(argv)
    command.validate!                            # ③ 参数校验
    command.run                                  # ④ 执行
  end
rescue Object => exception
  handle_exception(command, exception)
end

# CLAide/lib/claide/command.rb : 347
def self.parse(argv)
  argv = ARGV.coerce(argv)
  cmd = argv.arguments.first
  if cmd && subcommand = find_subcommand(cmd)
    argv.shift_argument
    subcommand.parse(argv)          # 递归 → Command::Install.parse
  elsif abstract_command? && default_subcommand
    load_default_subcommand(argv)
  else
    new(argv)                       # 叶子节点，实例化
  end
end

Pod::Command.parse(['install', '--repo-update'])
 └─ Pod::Command::Install.parse(['--repo-update'])
     └─ Pod::Command::Install.new(ARGV.new(['--repo-update']))

# CocoaPods/lib/cocoapods/command/install.rb : 1
class Install < Command
  include RepoUpdate
  include ProjectDirectory

  def self.options
    [
      ['--repo-update',  'Force running `pod repo update` before install'],
      ['--deployment',   'Disallow any changes to the Podfile or the Podfile.lock during installation'],
      ['--clean-install','Ignore the contents of the project cache and force a full pod installation. ...'],
    ].concat(super).reject { |(name, _)| name == '--no-repo-update' }
  end

  def initialize(argv)
    super
    @deployment = argv.flag?('deployment', false)
    @clean_install = argv.flag?('clean-install', false)
  end

  def run
    verify_podfile_exists!
    installer = installer_for_config
    installer.repo_update = repo_update?(:default => false)
    installer.update = false
    installer.deployment = @deployment
    installer.clean_install = @clean_install
    installer.install!
  end
end

# CocoaPods/lib/cocoapods/command.rb : 149
def installer_for_config
  Installer.new(config.sandbox, config.podfile, config.lockfile)
end

# Core/lib/cocoapods-core/podfile.rb : 311
def self.from_ruby(path, contents = nil)
  contents ||= File.open(path, 'r:utf-8', &:read)

  # ... 编码修正 + 智能引号转换 ...

  podfile = Podfile.new(path) do
    begin
      eval(contents, nil, path.to_s)   # ← 关键
    rescue Exception => e
      message = "Invalid `#{path.basename}` file: #{e.message}"
      raise DSLError.new(message, path, e, contents)
    end
  end
  podfile
end

# Core/lib/cocoapods-core/podfile.rb : 42
def initialize(defined_in_file = nil, internal_hash = {}, &block)
  self.defined_in_file = defined_in_file
  @internal_hash = internal_hash
  if block
    default_target_def = TargetDefinition.new('Pods', self)
    default_target_def.abstract = true
    @root_target_definitions = [default_target_def]
    @current_target_definition = default_target_def
    instance_eval(&block)       # ← 在 Podfile 实例上执行 block
  else
    @root_target_definitions = []
  end
end

# Core/lib/cocoapods-core/podfile/dsl.rb : 301
def pod(name = nil, *requirements)
  raise StandardError, 'A dependency requires a name.' unless name
  current_target_definition.store_pod(name, *requirements)
end

# Core/lib/cocoapods-core/podfile/dsl.rb : 395
def target(name, options = nil)
  raise Informative, "Unsupported options `#{options}` ..." if options

  parent = current_target_definition
  definition = TargetDefinition.new(name, parent)
  self.current_target_definition = definition
  yield if block_given?
ensure
  self.current_target_definition = parent
end

platform :ios, '13.0'
source 'https://cdn.cocoapods.org'

abstract_target 'Common' do
  pod 'AFNetworking', '~> 4.0'

  target 'MyApp' do
    pod 'SDWebImage'
  end

  target 'MyAppTests' do
    inherit! :search_paths
  end
end

# CocoaPods/lib/cocoapods/installer.rb : 160
def install!
  prepare                    # 本文：§5
  resolve_dependencies       # 本文：§6~§9
  download_dependencies      # 下一篇
  validate_targets           # 下一篇
  clean_sandbox
  if installation_options.skip_pods_project_generation?
    show_skip_pods_project_generation_message
    run_podfile_post_install_hooks
  else
    integrate                # 下一篇
  end
  write_lockfiles
  perform_post_install_actions
end

# CocoaPods/lib/cocoapods/installer.rb : 218
def prepare
  if Dir.pwd.start_with?(sandbox.root.to_path)
    raise Informative, 'Command should be run from a directory outside Pods directory.' \
      "\n\n\tCurrent directory is #{UI.path(Pathname.pwd)}\n"
  end
  UI.message 'Preparing' do
    deintegrate_if_different_major_version
    sandbox.prepare
    ensure_plugins_are_installed!
    run_plugins_pre_install_hooks
  end
end

# CocoaPods/lib/cocoapods/installer.rb : 235
def resolve_dependencies
  plugin_sources = run_source_provider_hooks
  analyzer = create_analyzer(plugin_sources)

  UI.section 'Updating local specs repositories' do
    analyzer.update_repositories                   # --repo-update 落点
  end if repo_update?

  UI.section 'Analyzing dependencies' do
    analyze(analyzer)
    validate_build_configurations
  end

  UI.section 'Verifying no changes' do
    verify_no_podfile_changes!
    verify_no_lockfile_changes!
  end if deployment?

  analyzer
end

# CocoaPods/lib/cocoapods/installer/analyzer.rb : 102
def analyze(allow_fetches = true)
  return @result if @result
  validate_podfile!                                    # ① 校验 Podfile
  validate_lockfile_version!                           # ② 校验 Lockfile 版本
  if installation_options.integrate_targets?
    target_inspections = inspect_targets_to_integrate  # ③ 扫描用户工程
  else
    verify_platforms_specified!
    target_inspections = {}
  end
  podfile_state = generate_podfile_state               # ④ 对比 Podfile vs Lockfile

  store_existing_checkout_options
  if allow_fetches == :outdated
    # 特殊路径：pod outdated
  elsif allow_fetches == true
    fetch_external_sources(podfile_state)              # ⑤ 拉 :path/:git/:podspec 的 podspec
  elsif !dependencies_to_fetch(podfile_state).all?(&:local?)
    raise Informative, 'Cannot analyze without fetching ...'
  end

  locked_dependencies = generate_version_locking_dependencies(podfile_state)  # ⑥ 生成锁定约束
  resolver_specs_by_target = resolve_dependencies(locked_dependencies)        # ⑦ 调 Resolver
  validate_platforms(resolver_specs_by_target)
  specifications = generate_specifications(resolver_specs_by_target)
  aggregate_targets, pod_targets = generate_targets(resolver_specs_by_target, target_inspections)
  sandbox_state = generate_sandbox_state(specifications)
  # ... 汇总 specs_by_source / specs_by_target ...
  @result = AnalysisResult.new(podfile_state, specs_by_target, specs_by_source, specifications, sandbox_state,
                               aggregate_targets, pod_targets, @podfile_dependency_cache)
end

# analyzer.rb : 260
def generate_podfile_state
  if lockfile
    pods_state = nil
    UI.section 'Finding Podfile changes' do
      pods_by_state = lockfile.detect_changes_with_podfile(podfile)
      pods_state = SpecsState.new(pods_by_state)
      pods_state.print if config.verbose?
    end
    pods_state
  else
    state = SpecsState.new
    state.added.merge(podfile_dependencies.map(&:root_name))
    state
  end
end

# analyzer.rb : 969
def fetch_external_sources(podfile_state)
  verify_no_pods_with_different_sources!
  deps = dependencies_to_fetch(podfile_state)
  pods = pods_to_fetch(podfile_state)
  return if deps.empty?
  UI.section 'Fetching external sources' do
    deps.sort.each do |dependency|
      fetch_external_source(dependency, !pods.include?(dependency.root_name))
    end
  end
end

# analyzer.rb : 1000
def dependencies_to_fetch(podfile_state)
  @deps_to_fetch ||= begin
    deps_to_fetch = []
    deps_with_external_source = podfile_dependencies.select(&:external_source)

    if update_mode == :all
      deps_to_fetch = deps_with_external_source
    else
      deps_to_fetch = deps_with_external_source.select { |dep| pods_to_fetch(podfile_state).include?(dep.root_name) }
      deps_to_fetch_if_needed = deps_with_external_source.select { |dep| podfile_state.unchanged.include?(dep.root_name) }
      deps_to_fetch += deps_to_fetch_if_needed.select do |dep|
        sandbox.specification_path(dep.root_name).nil? ||
          !dep.external_source[:path].nil? ||
          !sandbox.pod_dir(dep.root_name).directory? ||
          checkout_requires_update?(dep)
      end
    end
    deps_to_fetch.uniq(&:root_name)
  end
end

# locking_dependency_analyzer.rb : 32
def self.generate_version_locking_dependencies(lockfile, pods_to_update, pods_to_unlock = [])
  dependency_graph = Molinillo::DependencyGraph.new

  if lockfile
    added_dependency_strings = Set.new

    explicit_dependencies = lockfile.dependencies
    explicit_dependencies.each do |dependency|
      dependency_graph.add_vertex(dependency.name, dependency, true)
    end

    pods = lockfile.to_hash['PODS'] || []
    pods.each do |pod|
      add_to_dependency_graph(pod, [], dependency_graph, pods_to_unlock, added_dependency_strings)
    end

    pods_to_update = pods_to_update.flat_map do |u|
      root_name = Specification.root_name(u).downcase
      dependency_graph.vertices.each_key.select { |n| Specification.root_name(n).downcase == root_name }
    end

    pods_to_update.each do |u|
      dependency_graph.detach_vertex_named(u)   # ← 要 update 的 pod 从锁图里摘掉
    end
    # ...
  end

  dependency_graph
end

# analyzer.rb : 934
def generate_version_locking_dependencies(podfile_state)
  if update_mode == :all || !lockfile
    LockingDependencyAnalyzer.unlocked_dependency_graph       # 全解
  else
    deleted_and_changed = podfile_state.changed + podfile_state.deleted
    deleted_and_changed += pods_to_update[:pods] if update_mode == :selected
    local_pod_names = podfile_dependencies.select(&:local?).map(&:root_name)
    pods_to_unlock = local_pod_names.to_set.delete_if do |pod_name|
      next unless sandbox_specification = sandbox.specification(pod_name)
      sandbox_specification.checksum == lockfile.checksum(pod_name)
    end
    LockingDependencyAnalyzer.generate_version_locking_dependencies(lockfile, deleted_and_changed, pods_to_unlock)
  end
end

# analyzer.rb : 1071
def resolve_dependencies(locked_dependencies)
  duplicate_dependencies = podfile_dependencies.group_by(&:name).
    select { |_name, dependencies| dependencies.count > 1 }
  duplicate_dependencies.each do |name, dependencies|
    UI.warn "There are duplicate dependencies on `#{name}` in #{UI.path podfile.defined_in_file}:\n\n" \
     "- #{dependencies.map(&:to_s).join("\n- ")}"
  end

  resolver_specs_by_target = nil
  UI.section "Resolving dependencies of #{UI.path(podfile.defined_in_file) || 'Podfile'}" do
    resolver = Pod::Resolver.new(sandbox, podfile, locked_dependencies, sources, @specs_updated, :sources_manager => sources_manager)
    resolver_specs_by_target = resolver.resolve
    resolver_specs_by_target.values.flatten(1).map(&:spec).each(&:validate_cocoapods_version)
  end
  resolver_specs_by_target
end

# analyzer.rb : 430
def generate_targets(resolver_specs_by_target, target_inspections)
  resolver_specs_by_target = resolver_specs_by_target.reject { |td, _| td.abstract? && !td.platform }
  pod_targets = generate_pod_targets(resolver_specs_by_target, target_inspections)
  pod_targets_by_target_definition = group_pod_targets_by_target_definition(pod_targets, resolver_specs_by_target)
  aggregate_targets = resolver_specs_by_target.keys.reject(&:abstract?).map do |target_definition|
    generate_aggregate_target(target_definition, target_inspections, pod_targets_by_target_definition)
  end
  # search_paths_aggregate_targets 回填、embedded target 处理
  [aggregate_targets, pod_targets]
end

# analyzer.rb : 1123
def generate_sandbox_state(specifications)
  sandbox_state = nil
  UI.section 'Comparing resolved specification to the sandbox manifest' do
    sandbox_analyzer = SandboxAnalyzer.new(sandbox, podfile, specifications, update_mode?)
    sandbox_state = sandbox_analyzer.analyze
    sandbox_state.print
  end
  sandbox_state
end

# analyzer/sandbox_analyzer.rb : 9
# Added
# - If not present in the sandbox lockfile.
# - The directory of the Pod doesn't exits.
#
# Changed
# - The version of the Pod changed.
# - The SHA of the specification file changed.
# - The specific installed (sub)specs of the same Pod changed.
# - The specification is from an external source and the
#   installation process is in update mode.
# - The directory of the Pod is empty.
# - The Pod has been pre-downloaded.
#
# Removed
# - If a specification is present in the lockfile but not in the resolved
#   specs.

# CocoaPods/lib/cocoapods/resolver.rb : 86
def resolve
  dependencies = @podfile_dependency_cache.target_definition_list.flat_map do |target|
    @podfile_dependency_cache.target_definition_dependencies(target).each do |dep|
      next unless target.platform
      @platforms_by_dependency[dep].push(target.platform)
    end
  end.uniq
  @platforms_by_dependency.each_value(&:uniq!)
  @activated = Molinillo::Resolver.new(self, self).resolve(dependencies, locked_dependencies)
  resolver_specs_by_target
rescue Molinillo::ResolverError => e
  handle_resolver_error(e)
end

# resolver.rb : 266
def sort_dependencies(dependencies, activated, conflicts)
  dependencies.sort_by! do |dependency|
    name = name_for(dependency)
    [
      activated.vertex_named(name).payload ? 0 : 1,    # 已激活的优先
      dependency.external_source ? 0 : 1,               # external 优先（它只有一个版本）
      dependency.prerelease? ? 0 : 1,                   # 明确要 prerelease 的优先
      conflicts[name] ? 0 : 1,                          # 以前冲突过的优先（尽早失败）
      search_for(dependency).count,                     # 候选越少越先解（MRV）
    ]
  end
end

# resolver.rb : 295
def before_resolution;    end
def after_resolution;     end
def indicate_progress;    end

# resolver.rb : 157
def search_for(dependency)
  @search[dependency] ||= begin
    additional_requirements = if locked_requirement = requirement_for_locked_pod_named(dependency.name)
                                [locked_requirement]
                              else
                                Array(@podfile_requirements_by_root_name[dependency.root_name])
                              end
    specifications_for_dependency(dependency, additional_requirements).freeze
  end
end

# resolver.rb : 356
def specifications_for_dependency(dependency, additional_requirements = [])
  requirement_list = dependency.requirement.as_list + additional_requirements.flat_map(&:as_list)
  requirement_list.uniq!
  requirement = Requirement.new(requirement_list)
  find_cached_set(dependency).
    all_specifications(warn_for_multiple_pod_sources, requirement).
    map { |s| s.subspec_by_name(dependency.name, false, true) }.
    compact
end

# resolver.rb : 374
def find_cached_set(dependency)
  name = dependency.root_name
  cached_sets[name] ||= begin
    if dependency.external_source
      spec = sandbox.specification(name)
      raise StandardError, "[Bug] Unable to find the specification for `#{dependency}`." unless spec
      set = Specification::Set::External.new(spec)
    else
      set = create_set_from_sources(dependency)
    end
    raise Molinillo::NoSuchDependencyError.new(dependency) unless set
    set
  end
end

# Molinillo/lib/molinillo/resolution.rb : 167
def resolve
  start_resolution

  while state
    break if !state.requirement && state.requirements.empty?
    indicate_progress
    if state.respond_to?(:pop_possibility_state) # DependencyState
      debug(depth) { "Creating possibility state for #{requirement} (#{possibilities.count} remaining)" }
      state.pop_possibility_state.tap do |s|
        if s
          states.push(s)
          activated.tag(s)
        end
      end
    end
    process_topmost_state
  end

  resolve_activated_specs
ensure
  end_resolution
end

# resolution.rb : 252
def process_topmost_state
  if possibility
    attempt_to_activate
  else
    create_conflict
    unwind_for_conflict      # ← 回溯
  end
rescue CircularDependencyError => underlying_error
  create_conflict(underlying_error)
  unwind_for_conflict
end

# resolution.rb : 667
def attempt_to_activate
  debug(depth) { 'Attempting to activate ' + possibility.to_s }
  existing_vertex = activated.vertex_named(name)
  if existing_vertex.payload
    debug(depth) { "Found existing spec (#{existing_vertex.payload})" }
    attempt_to_filter_existing_spec(existing_vertex)   # A. 已经有了，收紧候选
  else
    latest = possibility.latest_version
    possibility.possibilities.select! do |possibility|
      requirement_satisfied_by?(requirement, activated, possibility)
    end
    if possibility.latest_version.nil?
      possibility.possibilities << latest if latest
      create_conflict
      unwind_for_conflict                              # B. 没候选了，回溯
    else
      activate_new_spec                                # C. 取最高版本，激活
    end
  end
end

# resolution.rb : 734
def require_nested_dependencies_for(possibility_set)
  nested_dependencies = dependencies_for(possibility_set.latest_version)
  debug(depth) { "Requiring nested dependencies (#{nested_dependencies.join(', ')})" }
  nested_dependencies.each do |d|
    activated.add_child_vertex(name_for(d), nil, [name_for(possibility_set.latest_version)], d)
    parent_index = states.size - 1
    parents = @parents_of[d]
    parents << parent_index if parents.empty?
  end

  push_state_for_requirements(requirements + nested_dependencies, !nested_dependencies.empty?)
end

# resolution.rb : 293
def unwind_for_conflict
  details_for_unwind = build_details_for_unwind
  unwind_options = unused_unwind_options
  debug(depth) { "Unwinding for conflict: #{requirement} to #{details_for_unwind.state_index / 2}" }
  conflicts.tap do |c|
    sliced_states = states.slice!((details_for_unwind.state_index + 1)..-1)
    raise_error_unless_state(c)
    activated.rewind_to(sliced_states.first || :initial_state) if sliced_states
    state.conflicts = c
    state.unused_unwind_options = unwind_options
    filter_possibilities_after_unwind(details_for_unwind)     # 关键：修剪候选
    index = states.size - 1
    @parents_of.each { |_, a| a.reject! { |i| i >= index } }
    state.unused_unwind_options.reject! { |uw| uw.state_index >= index }
  end
end

# resolution.rb : 216
def resolve_activated_specs
  activated.vertices.each do |_, vertex|
    next unless vertex.payload

    latest_version = vertex.payload.possibilities.reverse_each.find do |possibility|
      vertex.requirements.all? { |req| requirement_satisfied_by?(req, activated, possibility) }
    end

    activated.set_payload(vertex.name, latest_version)
  end
  activated.freeze
end

# resolver.rb : 105
def resolver_specs_by_target
  @resolver_specs_by_target ||= {}.tap do |resolver_specs_by_target|
    @podfile_dependency_cache.target_definition_list.each do |target|
      next if target.abstract? && !target.platform

      explicit_dependencies = @podfile_dependency_cache.target_definition_dependencies(target).map(&:name).to_set
      used_by_aggregate_target_by_spec_name = {}
      used_vertices_by_spec_name = {}

      @activated.tsort.reverse_each do |vertex|      # ← 拓扑排序
        spec_name = vertex.name
        explicitly_included = explicit_dependencies.include?(spec_name)
        if explicitly_included || vertex.incoming_edges.any? { |edge| used_vertices_by_spec_name.key?(edge.origin.name) && edge_is_valid_for_target_platform?(edge, target.platform) }
          validate_platform(vertex.payload, target)
          used_vertices_by_spec_name[spec_name] = vertex
          used_by_aggregate_target_by_spec_name[spec_name] = vertex.payload.library_specification? &&
            (explicitly_included || vertex.predecessors.any? { |predecessor| used_by_aggregate_target_by_spec_name.fetch(predecessor.name, false) })
        end
      end

      resolver_specs_by_target[target] = used_vertices_by_spec_name.each_value.
        map do |vertex|
          payload = vertex.payload
          non_library = !used_by_aggregate_target_by_spec_name.fetch(vertex.name)
          spec_source = payload.respond_to?(:spec_source) && payload.spec_source
          ResolverSpecification.new(payload, non_library, spec_source)
        end.
        sort_by(&:name)
    end
  end
end

# CocoaPods/lib/cocoapods/installer/analyzer/analysis_result.rb
AnalysisResult = Struct.new(
  :podfile_state,             # SpecsState：added / changed / deleted / unchanged
  :specs_by_target,           # {TargetDefinition => [Specification]}
  :specs_by_source,           # {Source => [Specification]}
  :specifications,            # [Specification]（全部，用于生成 Manifest）
  :sandbox_state,             # SpecsState：Sandbox 侧的 add/change/delete
  :targets,                   # [AggregateTarget]
  :pod_targets,               # [PodTarget]
  :podfile_dependency_cache,  # 给下游用的缓存
)

# installer.rb : 421
def analyze(analyzer = create_analyzer)
  @analysis_result = analyzer.analyze
  @aggregate_targets = @analysis_result.targets
  @pod_targets = @analysis_result.pod_targets
end