CocoaPods 源码导读：从下载到工程集成

# CocoaPods/lib/cocoapods/installer.rb : 160
def install!
  prepare
  resolve_dependencies
  download_dependencies       # §2
  validate_targets            # §3
  clean_sandbox
  if installation_options.skip_pods_project_generation?
    show_skip_pods_project_generation_message
    run_podfile_post_install_hooks
  else
    integrate                 # §4 + §5
  end
  write_lockfiles             # §6
  perform_post_install_actions
end

# installer.rb : 185
def download_dependencies
  UI.section 'Downloading dependencies' do
    install_pod_sources
    run_podfile_pre_install_hooks
    clean_pod_sources
  end
end

# installer.rb : 505
def install_pod_sources
  @downloaded_specs = []
  @installed_specs = []
  pods_to_install = sandbox_state.added | sandbox_state.changed
  sorted_root_specs = root_specs.sort_by(&:name)

  if installation_options.parallel_pod_downloads
    require 'concurrent/executor/fixed_thread_pool'
    thread_pool_size = installation_options.parallel_pod_download_thread_pool_size
    thread_pool = Concurrent::FixedThreadPool.new(thread_pool_size, :idletime => 300)

    sorted_root_specs.each do |spec|
      next unless pods_to_install.include?(spec.name)
      title = section_title(spec, 'Downloading')
      UI.titled_section(title.green, title_options) do
        thread_pool.post { download_source_of_pod(spec.name) }
      end
    end
    thread_pool.shutdown
    thread_pool.wait_for_termination
  end

  sorted_root_specs.each do |spec|
    if pods_to_install.include?(spec.name)
      UI.titled_section(section_title(spec, 'Installing').green, title_options) do
        install_source_of_pod(spec.name)        # 复用已下载内容 / 本地拷贝
      end
    else
      UI.section("Using #{spec}", '-> '.green) { create_pod_installer(spec.name) }
    end
  end
end

# CocoaPods/lib/cocoapods/installer/pod_source_installer.rb : 66
def install!
  download_source unless predownloaded? || local?
  PodSourcePreparer.new(root_spec, root).prepare! if local?
  sandbox.remove_local_podspec(name) unless predownloaded? || local? || external?
end

~/Library/Caches/CocoaPods/
├── VERSION                       # 当前 CocoaPods 版本，不匹配就清空
├── Pods/
│   ├── Release/<Name>/<Version>-<checksum5>/   # 发布版 pod 的缓存
│   └── External/<Name>/<md5 of params>-<checksum5>/  # :git / :podspec 的缓存
└── Specs/
    ├── Release/<Name>/<Version>-<checksum5>.podspec.json
    └── External/<Name>/<md5 of params>-<checksum5>.podspec.json

# CocoaPods/lib/cocoapods/downloader/request.rb : 61
def slug(name: self.name, params: self.params, spec: self.spec)
  checksum = spec && spec.checksum && '-' << spec.checksum[0, 5]
  if released_pod?
    "Release/#{name}/#{spec.version}#{checksum}"
  else
    opts = params.to_a.sort_by(&:first).map { |k, v| "#{k}=#{v}" }.join('-')
    digest = Digest::MD5.hexdigest(opts)
    "External/#{name}/#{digest}#{checksum}"
  end
end

# CocoaPods/lib/cocoapods/downloader/cache.rb : 32
def download_pod(request)
  cached_pod(request) || uncached_pod(request)
end

# downloader/cache.rb : 237
def uncached_pod(request)
  in_tmpdir do |target|
    result, podspecs = download(request, target)
    result.location = nil

    podspecs.each do |name, spec|
      destination = path_for_pod(request, :name => name, :params => result.checkout_options)
      copy_and_clean(target, destination, spec)
      write_spec(spec, path_for_spec(request, :name => name, :params => result.checkout_options))
      if request.name == name
        result.location = destination
      end
    end
    result
  end
end

# downloader/cache.rb : 282
def copy_and_clean(source, destination, spec)
  specs_by_platform = group_subspecs_by_platform(spec)
  destination.parent.mkpath
  Cache.write_lock(destination) do
    rsync_contents(source, destination)
    Pod::Installer::PodSourcePreparer.new(spec, destination).prepare!
    Sandbox::PodDirCleaner.new(destination, specs_by_platform).clean!
  end
end

# downloader/cache.rb : 113
def self.write_lock(location, &block)
  lock(location, File::LOCK_EX, &block)
end

def self.read_lock(location, &block)
  lock(location, File::LOCK_SH, &block)
end

def self.lock(location, lock_type)
  lockfile = "#{location}.lock"
  File.open(lockfile, File::CREAT, 0o644) do |f|
    f.flock(lock_type)
    yield
  end
ensure
  FileUtils.rm_f(lockfile) if File.exist?(lockfile) && lock_type == File::LOCK_EX
end

# cocoapods-downloader/lib/cocoapods-downloader/git.rb : 72
def download!
  clone
  checkout_commit if options[:commit]
end

def clone(force_head = false, shallow_clone = true)
  ui_sub_action('Git download') do
    begin
      git! clone_arguments(force_head, shallow_clone)
      update_submodules
    rescue DownloaderError => e
      if e.message =~ /^fatal:.*does not support (--depth|shallow capabilities)$/im
        clone(force_head, false)                 # 服务端不支持 shallow 时自动降级
      else
        raise
      end
    end
  end
end

def clone_arguments(force_head, shallow_clone)
  command = ['clone', url, target_path, '--template=']
  command += %w(--single-branch --depth 1) if shallow_clone && !options[:commit]
  unless force_head
    if tag_or_branch = options[:tag] || options[:branch]
      command += ['--branch', tag_or_branch]
    end
  end
  command
end

# installer/pod_source_downloader.rb
def download!
  result = Downloader.download(download_request, root, :can_cache => can_cache?)
  if (!specification.local? && sandbox.predownloaded?(root_spec.name)) || sandbox.checkout_sources[root_spec.name].nil?
    sandbox.store_checkout_source(root_spec.name, result.checkout_options)
  end
end

# installer.rb : 664
def validate_targets
  validator = Xcode::TargetValidator.new(aggregate_targets, pod_targets, installation_options)
  validator.validate!
end

# installer.rb : 285
def generate_pods_project
  stage_sandbox(sandbox, pod_targets)
  cache_analysis_result = analyze_project_cache
  pod_targets_to_generate = cache_analysis_result.pod_targets_to_generate
  aggregate_targets_to_generate = cache_analysis_result.aggregate_targets_to_generate

  pod_targets_to_generate.each do |pod_target|
    pod_target.build_headers.implode_path!(pod_target.headers_sandbox)
    sandbox.public_headers.implode_path!(pod_target.headers_sandbox)
  end

  create_and_save_projects(pod_targets_to_generate, aggregate_targets_to_generate,
                           cache_analysis_result.build_configurations, cache_analysis_result.project_object_version)
  SandboxDirCleaner.new(sandbox, pod_targets, aggregate_targets).clean!

  update_project_cache(cache_analysis_result, target_installation_results)
end

# installer/project_cache/project_cache_analyzer.rb : 73
def analyze
  target_by_label = Hash[(pod_targets + aggregate_targets).map { |target| [target.label, target] }]
  cache_key_by_target_label = create_cache_key_mappings(target_by_label)

  full_install_results = ProjectCacheAnalysisResult.new(pod_targets, aggregate_targets, cache_key_by_target_label,
                                                        build_configurations, project_object_version)
  if clean_install
    UI.message 'Ignoring project cache from the provided `--clean-install` flag.'
    return full_install_results
  end

  if cache.build_configurations != build_configurations ||
      cache.project_object_version != project_object_version ||
      YAMLHelper.convert(cache.podfile_plugins) != YAMLHelper.convert(podfile_plugins) ||
      YAMLHelper.convert(cache.installation_options) != YAMLHelper.convert(installation_options)
    UI.message 'Ignoring project cache due to project configuration changes.'
    return full_install_results
  end

  if project_names_changed?(pod_targets, cache)
    UI.message 'Ignoring project cache due to project name changes.'
    return full_install_results
  end

  pod_targets_to_generate = Set[]
  aggregate_targets_to_generate = Set[]
  added_targets = compute_added_targets(target_by_label, cache_key_by_target_label.keys, cache.cache_key_by_target_label.keys)
  # ... changed / deleted ...
end

# installer/xcode/pods_project_generator.rb (骨架)
install_file_references(project, pod_targets_to_generate)    # FileReferencesInstaller
install_pod_targets(project, pod_targets_to_generate)        # 每个 PodTarget → PodTargetInstaller
install_aggregate_targets(project, aggregate_targets_to_generate)  # 每个 AggregateTarget → AggregateTargetInstaller
integrate_targets(pod_target_installation_results)           # PodTargetDependencyInstaller / AggregateTargetDependencyInstaller
wire_resource_bundle_targets(...)

# installer/xcode/pods_project_generator/pod_target_installer.rb : 39
def install!
  UI.message "- Installing target `#{target.name}` #{target.platform}" do
    create_support_files_dir                                 # Pods/Target Support Files/<Pod>
    # ... 拆出 library/test/app file accessors

    native_target = target.should_build? ? add_target : add_placeholder_target
    resource_bundle_targets = add_resources_bundle_targets(library_file_accessors).values.flatten
    test_native_targets = add_test_targets
    test_app_host_targets = add_test_app_host_targets
    app_native_targets = add_app_targets

    add_files_to_build_phases(native_target, test_native_targets, app_native_targets)

    create_xcconfig_file(native_target, resource_bundle_targets)
    create_test_xcconfig_files(test_native_targets, test_resource_bundle_targets)
    create_app_xcconfig_files(app_native_targets, app_resource_bundle_targets)

    if target.should_build? && target.defines_module? && !skip_modulemap?(target.library_specs)
      create_module_map(native_target) do |generator| ... end
      create_umbrella_header(native_target) do |generator| ... end
    end

    if target.should_build? && target.build_as_framework?
      create_info_plist_file(...) unless skip_info_plist?(native_target)
      create_build_phase_to_symlink_header_folders(native_target)
    end

    create_prefix_header(...) unless skip_pch?(target.library_specs)
    create_dummy_source(native_target) if target.should_build?
    # ... 静态库、on-demand resources、vendored frameworks、scheme 等
  end
end

# installer.rb : 334
projects_writer = Xcode::PodsProjectWriter.new(sandbox, generated_projects,
                                               target_installation_results.pod_target_installation_results, installation_options)
projects_writer.write! do
  run_podfile_post_install_hooks        # ← Podfile 的 post_install 在这里
end

project.new_target(:framework, 'AFNetworking-iOS13.0', :ios, '13.0', product_group)
native_target.add_file_references([source_ref, header_ref])
native_target.build_configurations.each { |c| c.base_configuration_reference = xcconfig_ref }

# installer/user_project_integrator.rb : 70
def integrate!
  create_workspace
  deintegrated_projects = deintegrate_removed_targets
  integrate_user_targets
  warn_about_xcconfig_overrides
  projects_to_save = (user_projects_to_integrate + deintegrated_projects).uniq
  save_projects(projects_to_save)
end

# user_project_integrator.rb : 94
def create_workspace
  all_projects = user_project_paths.sort.push(sandbox.project_path).uniq
  file_references = all_projects.map do |path|
    relative_path = path.relative_path_from(workspace_path.dirname).to_s
    Xcodeproj::Workspace::FileReference.new(relative_path, 'group')
  end

  if workspace_path.exist?
    workspace = Xcodeproj::Workspace.new_from_xcworkspace(workspace_path)
    new_file_references = file_references - workspace.file_references
    unless new_file_references.empty?
      new_file_references.each { |fr| workspace << fr }
      workspace.save_as(workspace_path)
    end
  else
    UI.notice "Please close any current Xcode sessions and use `#{workspace_path.basename}` for this project from now on."
    workspace = Xcodeproj::Workspace.new(*file_references)
    workspace.save_as(workspace_path)
  end
end

# installer/user_project_integrator/target_integrator.rb : 559
def integrate!
  UI.section(integration_message) do
    XCConfigIntegrator.integrate(target, native_targets)         # ① 注入 xcconfig

    remove_obsolete_script_phases                                 # ② 清理老版本遗留的 script phase
    add_pods_library                                              # ③ 链上 libPods-xxx.a / Pods_xxx.framework
    add_embed_frameworks_script_phase                             # ④ Embed frameworks 脚本
    remove_embed_frameworks_script_phase_from_embedded_targets
    add_copy_resources_script_phase                               # ⑤ Copy resources 脚本
    add_check_manifest_lock_script_phase                          # ⑥ 校验 Podfile.lock / Manifest.lock 一致
    add_user_script_phases                                        # ⑦ Podfile 里 `script_phase` 声明
    add_on_demand_resources
  end
end

# user_project_integrator.rb : 180
def warn_about_xcconfig_overrides
  targets_to_integrate.each do |aggregate_target|
    aggregate_target.user_targets.each do |user_target|
      user_target.build_configurations.each do |config|
        xcconfig = aggregate_target.xcconfigs[config.name]
        if xcconfig
          (xcconfig.to_hash.keys - IGNORED_KEYS).each do |key|
            target_values = config.build_settings[key]
            if target_values &&
                !INHERITED_FLAGS.any? { |flag| target_values.include?(flag) }
              print_override_warning(aggregate_target, user_target, config, key)
            end
          end
        end
      end
    end
  end
end

# installer.rb : 756  (简化)
def write_lockfiles
  @lockfile = generate_lockfile
  UI.message "- Writing Lockfile in #{UI.path config.lockfile_path}" do
    @lockfile.write_to_disk(config.lockfile_path)
  end
  UI.message "- Writing Manifest in #{UI.path sandbox.manifest_path}" do
    FileUtils.cp(config.lockfile_path, sandbox.manifest_path)
  end
end

def generate_lockfile
  external_source_pods = analysis_result.podfile_dependency_cache.podfile_dependencies.select(&:external_source).map(&:root_name).uniq
  checkout_options = sandbox.checkout_sources.select { |root_name, _| external_source_pods.include? root_name }
  Lockfile.generate(podfile, analysis_result.specifications, checkout_options, analysis_result.specs_by_source)
end

# installer.rb : 682
def perform_post_install_actions
  run_plugins_post_install_hooks           # 插件侧 post_install
  warn_for_deprecations                    # deprecated spec / 对应替代方案
  warn_for_installed_script_phases         # Podfile 里 script_phase 声明时警告
  warn_for_removing_git_master_specs_repo  # 还在用 master spec repo 的项目
  print_post_install_message               # "Pod installation complete! ..."
end