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 PodBuilderdeintegrate
: deintegrates PodBuilder's initializationbuild
: prebuilts a specific pod declared in the PodBuilder-Podfilebuild_all
: prebuilts all pods declared in the PodBuilder-Podfileupdate
: prebuilts all pods that are out-of-sync with the Restore-Podfilerestore_all
: rebuilts all pods declared in the Restore-Podfile fileinstall_sources
: installs sources of pods to debug into prebuild frameworksswitch
: switch between prebuilt, development or standard pod in the Application-Podfileswitch_all
: switch all pods between prebuilt, development or standard in the Application-Podfileclean
: removes unused prebuilt frameworks, dSYMs and source files added by install_sourcessync_podfile
: updates the Application-Podfile with all pods declared in the PodBuilder-Podfile fileinfo
: 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 frameworkrestore_info.version
: the expected version for the podrestore_info.specs
: the expected list of specs for the podrestore_info.is_static
: true if the expected pod produces a static frameworkrestore_info.swift_version
: the expected swift compiler version to prebuild podprebuilt_info
: some additional information about the the prebuilt framework, if it exists on diskprebuilt_info.version
: the version of the pod that produced the current prebuilt frameworkprebuilt_info.specs
: the specs of the pod that produced the current prebuilt framework (there might be multiple subspec that produce a single .framework)prebuilt_info.is_static
: true if the current prebuilt framework is staticprebuilt_info.swift_version
: the swift compiler version that produced the current prebuilt framework
Version format
restore_version
and prebuilt_info.version
are hashes containing the following keys:
tag
: pods pinned to a specific tag of the CocoaPods official Specsrepo
,hash
: pods pointing to an external repo + commitrepo
,branch
: pods pointing to an external repo + branchrepo
,tag
: pods pointing to an external repo + tag
Configuration file
PodBuilder.json allows some advanced customizations.
Supported keys
development_team
Starting with Xcode 14 it is mandatory to sign both frameworks and framework bundles. PodBuilder will try to automatically extract the developer team from the application, however there are cases where this will fail and the development_team needs to be added explicitly in the configuration file.
development_language
Starting with Xcode 14, when the main language is different than english, it might be necessary to explicitly set the default app language to properly localize app's extensions. Use the ISO 639-1 code.
spec_overrides
This hash allows to add/replace keys in a podspec specification. This can be useful to solve compilation issue or change compilation behaviour (e.g. compile framework statically by specifying static_framework = true
) without having to fork the repo.
The key is the pod name, the value a hash with the keys of the podspec that need to be overridden.
As an example here we're setting module_name
in Google's Advertising SDK:
{
"spec_overrides": {
"Google-Mobile-Ads-SDK": {
"module_name": "GoogleMobileAds"
}
}
}
skip_pods
You may want to skip some pods to be prebuilt, you can do that as follows:
{
"skip_pods": [
"PodA"
]
}
skip_build_configuration_check
PodBuilder performs validation checks to prevent building pods that are marked to be built with different build configurations. In some edge case scenarious you might want to skip these checks as follows:
{
"skip_build_configuration_check": [
"PodA"
]
}
force_prebuild_pods
You may want to force some pods to be prebuilt, this might be the case for prebuilt ones (pods with a single vendored .framework) which are dependencies of othere pods
{
"force_prebuild_pods": [
"PodA"
]
}
build_settings
These settings allow you to specify the build settings to use when compiling prebuilt items. These values won't be reflected in your project once the pod has been built.
You can override the default values which are:
{
"build_settings": {
"ENABLE_BITCODE": "NO",
"GCC_OPTIMIZATION_LEVEL": "s",
"SWIFT_OPTIMIZATION_LEVEL": "-Osize",
"SWIFT_COMPILATION_MODE": "wholemodule"
}
}
If your project uses bitcode change "ENABLE_BITCODE" to "YES". Please note that all pods that have dependencies to XCTest need to be add a "ENABLE_BITCODE": "NO"
to the build_settings_overrides
below.
build_settings_overrides
Like build_settings
but per pod. Pod name can also refer to subspec.
{
"build_settings_overrides": {
"PodA": {
"SWIFT_OPTIMIZATION_LEVEL": "-O"
},
"PodB/Subspec": {
"APPLICATION_EXTENSION_API_ONLY": "NO"
}
}
}
build_system
Specify which build system to use to compile frameworks. Either Legacy
(standard build system) or Latest
(new build system). Default value: Latest
.
build_xcframeworks_all
Specify if PodBuilder should build all pods as .xcframeworks. Will enable library_evolution_support
. Default value: false
build_xcframeworks_exclude
Specify which pods PodBuilder should NOT be built as .xcframeworks when build_xcframeworks_all
is true. Default value: []
build_xcframeworks_include
Specify which pods PodBuilder should be built as .xcframeworks. Will enable library_evolution_support
. Default value: []
generate_coverage
Specify if coverage data for use with profiled execution should be generated. Default value: false
remap_coverage_to_project_root
Specify if code coverage source code references should be remapped with relative paths to the project root folder. Default value: false
library_evolution_support
Specify if Swift frameworks should be compiled with library evolution support (BUILD_LIBRARY_FOR_DISTRIBUTION). Default value: false
license_filename
PodBuilder will create two license files a plist and a markdown file which contains the licenses of each pod specified in the PodBuilder-Podfile. Defailt value: Pods-acknowledgements
(plist|md).
project_name
In complex project setups you may end up with the following error: "Found multiple xcodeproj/xcworkspaces...". If that is the case you can specify the name of your main project manually. For example if your application's project is "Example.xcworkspace" set the value for this key to Example
.
allow_building_development_pods
Building development pods is by default not allowed unless you explicitly pass the allow_warnings flag. You can override this behavior by setting this key to true
skip_licenses
PodBuilder writes a plist and markdown license files of pods specified in the PodBuilder-Podfile. You can specify pods that should not be included, for example for private pods.
{
"skip_licenses": ["Podname1", "Podname2"]
}
use_bundler
If you use bundler to pin the version of CocoaPods in your project set this to true. Default false.
pre_actions
Pre actions allow to execute custom scripts before a given command (switch
, build
) has been performed.
You need to specify a path
to the executable script which is relative to the PodBuilder folder. Optionally you can also specify whether the command should or should not print the output to stdout/stderr by passing a bool to the quiet
key (default: false).
{
"pre_actions": {
"switch" : { "path": "pre_switch_action.rb", "quiet": true },
"build" : { "path": "pre_build_action.rb", "quiet": false }
}
}
Note: The build action might be invoked more than once depending on the build strategy that PodBuilder needs to perform.
post_actions
Post actions allow to execute custom scripts after a given command (switch
, build
) has been performed.
You need to specify a path
to the executable script which is relative to the PodBuilder folder. Optionally you can also specify whether the command should or should not print the output to stdout/stderr by passing a bool to the quiet
key (default: false).
{
"post_actions": {
"switch" : { "path": "post_switch_action.rb", "quiet": true },
"build" : { "path": "post_buil_action.rb", "quiet": false }
}
}
Note: The build action might be invoked more than once depending on the build strategy that PodBuilder needs to perform.
Behind the scenes
PodBuilder leverages CocoaPods to compile pods into frameworks. Every compiled framework will be boxed (by adding it as a vendored_framework
) as a subspec of a local podspec. When needed additional settings will be automatically ported from the original podspec, like for example custom xcconfig settings.
FAQ
I get an 'Failed getting 'DEVELOPMENT_TEAM' build setting' when building
PodBuilder might fail to automatically extract the developer team from your current project which is required to sign executables. Add the development_team
key in PodBuilder.json file with your development team identifier.
PodWithError
does not specify a Swift version and none of the targets (DummyTarget
)' when building
I get an 'The podspec of the Pod you're trying to build doesn't specify the swift_version which is required in recent versions of CocoaPods. Either contact the author/mantainer of the Pod asking it to fix the podspec or add a spec_overrides
in PodBuilder.json.
"spec_overrides": {
"PodWithError": {
"swift_version": "5.3"
}
}
After prebuilding my project no longer compiles
A common problem you may encounter is with Objective-C imports. You should verify that you're properly importing all the headers of your pods with the angle bracket notation #import <FrameworkName/HeaderFile.h>
instead of directly importing #import "HeaderFile.h"
.
How to proceed in these cases?
- Rebuild all frameworks with PodBuilder
- Switch all your pods (use switch command or manually edit your Application-Podfile) back to the standard integration
- One-by-one switch your pods back to prebuilt, verifying everytime that your Project still compiles.
Do I need to commit compiled frameworks?
No. If the size of compiled frameworks in your repo is a concern (and for whatever reason you can't use Git-LFS) you can choose add the Prebuilt and dSYM folder to .gitignore and run pod_builder update
to rebuild all frameworks that need to be recompiled.
I get an 'attempt to read non existent folder `/private/tmp/pod_builder/Pods/ podname' when building
Please open an issue here. You may also add the name of the pod to the skip_pods
key in the configuration file and try rebuilding again.
Git LFS
We high encourage to use PodBuilder in combination with Git LFS. Tacking PodBuilder/Prebuilt/**/*.framework/*
and PodBuilder/Prebuilt/**/*.a
and PodBuilder/dSYM/**/*
will ensure that your repo size stays under control with all the benefits of having prebuilt dependencies ready to use.
Try it out!
Under Example there's a sample project with a Podfile adding Alamofire you can use to try PodBuilder out.
$ pod_builder init
$ pod_builder build_all
This will initialize the project to use PodBuilder and prebuild Alamofire, open the project in Xcode and compile.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Subito-it/PodBuilder.
Caveats
Code isn't probably the cleanest I ever wrote but given the usefulness of the tool I decided to publish it nevertheless.
Authors
License
The gem is available under the Apache License, Version 2.0. See the LICENSE file for more info.