What is PodBuilder

PodBuilder is a complementary tool to CocoaPods that allows to prebuild pods into frameworks which can then be included into a project’s repo. Instead of committing pod’s source code you add its compiled counterpart. While there is a size penalty in doing so compilation times will decrease significantly because pod's source files no longer need to be recompiled very often and there's also a lot less for SourceKit to index. Additionally frameworks contain all architecture so they’re ready to be used both on any device and simulator.

Depending on the size of the project and number of pods this can translate in a significant reduction of compilation times (for a large project we designed this tool for we saw a 50% faster compile times, but YMMV).

Installation

Like CocoaPods PodBuilder is built with Ruby and will be installable with default version of Ruby available on macOS.

Unless you're using a Ruby version manager you should generally install using sudo as follows

$ sudo gem install pod-builder

Requirements

Ruby 2.6.3 or newer. Cocoapods 1.9.0 or newer

Quick start

You can the initialize your project to use the tool using the init command

$ cd path-to-your-repo;
$ pod_builder init

This will add a PodBuilder folder which will contain all files needed and generated by the PodBuilder.

To prebuild just one or more specific dependencies run

$ pod_builder build Pod1 Pod2

To prebuild all dependencies run

$ pod_builder build_all

This will generate the pod frameworks which can be committed to your repo (using git LFS is highly suggested) for much faster compilation.

Should PodBuilder not work the way you expect you can get rid of it by running

$ pod_builder deintegrate

Which will restore all changes that PodBUilder applied to the project (the PodBuilder folder and the changes to the Podfile).

Usage

Podfile

The workflow is very similar to the one you're used to with CocoaPods. The most significant difference is that PodBuilder relies on 3 Podfiles:

1. PodBuilder/Podfile (aka PodBuilder-Podfile)

This is your original Podfile and remains your master Podfile that you will update as needed. It is used by PodBuilder to determine which versions and dependencies need to be compiled when prebuilding.

2. Podfile (aka Application-Podfile)

Based on the one above but will replace precompiled frameworks with references to the local PodBuilder podspec. It is autogenerated and shouldn't be manually changed

3. PodBuilder/Podfile.restore (aka Restore-Podfile)

This acts as a sort of lockfile and reflects the current state of what is installed in the application, pinning pods to a particular tag or commit. This will be particularly useful until Swift reaches ABI stability, because when you check out an old revision of your code you won't be able to get your project running unless the Swift frameworks were compiled with a same version of Xcode you're currently using. This file is used internally by PodBuilder and shouldn't be manually changed. It is autogenerated and shouldn't be manually changed

Commands

PodBuilder comes with a rich set of commands:

• init: initializes a project to use PodBuilder
• deintegrate: deintegrates PodBuilder's initialization
• build: prebuilts a specific pod declared in the PodBuilder-Podfile
• build_all: prebuilts all pods declared in the PodBuilder-Podfile
• update: prebuilts all pods that are out-of-sync with the Restore-Podfile
• restore_all: rebuilts all pods declared in the Restore-Podfile file
• install_sources: installs sources of pods to debug into prebuild frameworks
• switch: switch between prebuilt, development or standard pod in the Application-Podfile
• switch_all: switch all pods between prebuilt, development or standard in the Application-Podfile
• clean: removes unused prebuilt frameworks, dSYMs and source files added by install_sources
• sync_podfile: updates the Application-Podfile with all pods declared in the PodBuilder-Podfile file
• info: outputs json-formatted information reflecting the current status of prebuilt pods

Commands can be run from anywhere in your project's repo that is required to be under git.

init command

This will sets up a project to use PodBuilder.

The following will happen:

• Create a PodBuilder folder in your repo's root.
• Copy your original Podfile to PodBuilder/Podfile (PodBuilder-Podfile)
• Add a PodBuilder.json configuration file
• Modify the original Podfile (Application-Podfile) with some minor customizations
• Create/Update your Gemfile adding the gem 'pod-builder' entry

deintegrate command

This will revert init's changes.

build command

Running pod_builder build [pod name] will precompile the pod that should be included in the PodBuilder-Podfile.

The following will happen:

• Create one or more (if there are dependencies) .framework file/s under PodBuilder/Prebuilt along with its corresponding dSYM files (if applicable)
• Update the Application-Podfile replacing the pod definition with the precompiled ones
• Update/create the Podfile.restore (Restore-Podfile)
• Update/create PodBuilder.podspec which is a local podspec for your prebuilt frameworks (more on this later)

By default PodBuilder will only rebuild pods when changes are detected in source code. This behaviour can be overridden by passing the --force flag.

build_all command

As build but will prebuild all pods defined in PodBuilder-Podfile.

update command

If you decide not to commit the Prebuilt and dSYM folders you can use this command to rebuild all those frameworks that are out-of-sync with the Restore-Podfile or that were built with a different version of the Swift compiler.

restore_all command

Will recompile all pods to the versions defined in the Restore-Podfile. You would typically use this when checking out an older revision of your project that might need to rebuild frameworks (e.g. You're using a different version of the Swift compiler) to the exact same version at the time of the commit.

install_sources command

Once you prebuild a pod you can no longer debug its origianl code, to overcome this limitation you can use this command which downloads the pod's source code to PodBuilder/Sources and with some tricks restores the ability to use the debugger and step into the code of your prebuilt dependencies. This can be very helpful to catch the exact location of a crash when it occurs (showing something more useful than assembly code). It is however advisable to switch to the original pod when doing any advanced debugging during development of code that involves a pod.

generate_lldbinit command

In some situations you may already have source code for your prebuilt frameworks, for example if your project is organized as a monorepo. In this case there is no need to use the install_sources, you can run this command passing the folder that contains the source code that you used to generate the prebuilt frameworks.

This command will generate a custom lldinit file which will be stored in the PodBuilder folder. Note that this file is added to the .gitignore since it contains absolute path information. Since Xcode 11.5 customly defined lldbinit can be selected in the Run tab in your scheme project ("LLDB Init File"). You should select the generated llbb file path or, if you're using project generation tools such as XcodeGen, you can set it to ${SRCROOT}/../PodBuilder/lldbinit.

The most convenient place to update the lldbinit file is in your Podfile pre_install or post_install actions. It is suggested to add the following lines

    pid = spawn("pod_builder generate_lldbinit")
    Process.detach(pid)

To generate lldbinit file. We're generating it asynchronously to avoid unnecessarily slow down pod install since this file will be needed only when build and running your application.

switch command

Once you prebuild a framework you can change the way it is integrated in your project.

Using the switch command you can choose to integrate it:

• standard. Reverts to the default one used by CocoaPods
• development. The Development Pod used by CocoaPods
• prebuilt. Use the prebuilt pod

To support development pods you should specify the path(s) that contain the pods sources in PodBuilder/PodBuilderDevPodsPaths.json as follows

[
    "~/path_to_pods_1",
    "~/path_to_pods_2",
]

PodBuilder will automatically determine the proper path when switching a particular pod.

switch_all command

As switch but will switch all pods defined in PodBuilder-Podfile.

clean command

Deletes all unused files by PodBuilder, including .frameworks, .dSYMs and Source repos.

sync_podfile command

Updates the Application with all pods declared in the PodBuilder-Podfile file. This can come in handy when adding a new pod to the PodBuilder-Podfile file you don't won't to prebuild straight away.

info command

Outputs json-formatted information reflecting the current status of prebuilt pods.

The output hash contains one key for each pod containing the following keys:

• framework_path: the expected path for the prebuilt framework
• restore_info.version: the expected version for the pod
• restore_info.specs: the expected list of specs for the pod
• restore_info.is_static: true if the expected pod produces a static framework
• restore_info.swift_version: the expected swift compiler version to prebuild pod
• prebuilt_info: some additional information about the the prebuilt framework, if it exists on disk
• prebuilt_info.version: the version of the pod that produced the current prebuilt framework
• prebuilt_info.specs: the specs of the pod that produced the current prebuilt framework