{"id":13902986,"url":"https://github.com/grab/cocoapods-pod-merge","last_synced_at":"2025-05-16T16:05:21.580Z","repository":{"id":37734453,"uuid":"214105254","full_name":"grab/cocoapods-pod-merge","owner":"grab","description":"Cocoapods plugin to merge pods used by your Xcode project, reducing the number of dynamic frameworks your app has to load on startup","archived":false,"fork":false,"pushed_at":"2023-06-23T20:50:30.000Z","size":101,"stargazers_count":377,"open_issues_count":16,"forks_count":24,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-12T14:56:13.370Z","etag":null,"topics":["cocoapods","cocoapods-plugin","dylib","ios","merge","pod"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-10-10T06:34:08.000Z","updated_at":"2025-04-02T07:09:38.000Z","dependencies_parsed_at":"2023-02-16T13:16:06.216Z","dependency_job_id":"ff0f3f44-e6bf-4d82-a78f-5c211b761bbb","html_url":"https://github.com/grab/cocoapods-pod-merge","commit_stats":{"total_commits":57,"total_committers":3,"mean_commits":19.0,"dds":0.07017543859649122,"last_synced_commit":"46e2fe48fb059ca9ef4280d018e57d8df8250299"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grab%2Fcocoapods-pod-merge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grab%2Fcocoapods-pod-merge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grab%2Fcocoapods-pod-merge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grab%2Fcocoapods-pod-merge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grab","download_url":"https://codeload.github.com/grab/cocoapods-pod-merge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254564121,"owners_count":22092121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cocoapods","cocoapods-plugin","dylib","ios","merge","pod"],"created_at":"2024-08-06T22:01:32.572Z","updated_at":"2025-05-16T16:05:21.553Z","avatar_url":"https://github.com/grab.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Cocoapods Pod Merge Plugin [![Gem Version](https://badge.fury.io/rb/cocoapods-pod-merge.svg)](https://badge.fury.io/rb/cocoapods-pod-merge)\n\npod-merge is a Cocoapods plugin to **merge** dependencies (or pods) used by your Xcode project, to reduce the number of dynamic frameworks your app has to load on app startup.\n\nThe plugin introduces a new file to your project: the **MergeFile**, and hooks into the pre-install phase of `pod install` to merge your dependencies.\n\n## Benchmarks\n\nBased on measurements taken on this repo's example project, [merging 8 pods into 3](https://github.com/grab/cocoapods-pod-merge/blob/master/PodMergeExample/MergeFile).\n\n\u003cimg src=\"https://github.com/grab/cocoapods-pod-merge/raw/master/wiki/images/benchmarks_chart.png\" alt=\"pod-merge Benchmarks\" style=\"zoom:100%;\" /\u003e\n\nAccording to our experience in Grab, improvements on older devices like the iPhone 5, 6 are more drastic. As a general rule, we've seen dylib loading times decrease by **upto 50 ms** per dynamic framework reduced on our user's slowest devices. More info [here](https://github.com/grab/cocoapods-pod-merge/blob/master/wiki/benchmarks.md).\n\n## Installation\n\n#### Using Bundler \n\nIf your Xcode project does not have a `Gemfile` yet, it's highly recommended you use [**bundler**](https://bundler.io/) to maintain consistent versions of tools like cocoapods within your team.  [Learn how to set it up here](https://www.mokacoding.com/blog/ruby-for-ios-developers-bundler/).\n\nTo use cocoapods-pod-merge, add this line to your app's `Gemfile`:\n\n```ruby\ngem 'cocoapods-pod-merge'\n```\n\nAnd then install it using [bundler](https://bundler.io/) by executing:\n\n    $ bundle install\n\nNote than **this is a cocoapods plugin**, hence it requires cocoapods as a dependency.\n\n## Usage\n\nUsing this plugin to merge your pods is a simple three step process:\n\n#### 1. Create a MergeFile\n\nThis plugin requires a file called **MergeFile**. This is how it looks:\n\n```ruby\ngroup 'Networking'\n\tpod 'AFNetworking'\n\tpod 'SDWebImage'\nend\n```\n\nThe above MergeFile:\n\n* Defines a group named `Networking`. This will be the name of the resulting merged pod.\n* Tells the plugin to merge `AFNetworking` \u0026 `SDWebImage` into `Networking`\n\n**Here's a [few important tips](https://github.com/grab/cocoapods-pod-merge#tips) to decide what pods to merge.**\n\n\u003e Important: The MergeFile is pretty strict about it's syntax, so please avoid adding comments or random text to it. To make your life easier, tell your text editor to treat it like a Ruby file.\n\n#### 2. Update your Podfile\n\nNow, update your Podfile to use the plugin, as well as the merged pods:\n\nAdd the line **plugin 'cocoapods-pod-merge'** to the top of your existing `Podfile`, and modify it to use the merged pod.\n\n```ruby\nplugin 'cocoapods-pod-merge'\n\ntarget 'MyApp'\n\t# pod 'AFNetworking' # Not needed anymore, since we'll use the merged Pod\n\t# pod 'SDWebImage' # Not needed anymore, since we'll use the merged Pod\n\tpod 'Networking', :path =\u003e 'MergedPods/Networking' # The merged pod\nend\n```\n\nThings to note:\n\n* We commented out the pods 'AFNetworking' \u0026 'SDWebImage' above, since these will now be installed as part of the merged `Networking` framework.\n* We add the merged framework `Networking`, which is named as the group name defined in our MergeFile\n* The path is fixed, since the plugin will put your merged pods in the `MergedPods/\u003cgroup name\u003e` directory.\n\n#### 3. Run Pod Install \u0026 Update your Code!\n\nThat's it! Just run:\n\n    $ bundle exec pod install\n\nIf all goes well, the pods should be merged according to your MergeFile, and should be available to use in your project. \n\nThere's _one more thing_! There's no framework such as `AFNetworking` or `SDWebImage` available to your project now, since these are now merged into a pod named`Networking` So, as a one time process, replace imports of the merged libraries in your project like\n\n```swift\nimport AFNetworking\n```\n\nto \n\n```swift\nimport Networking.AFNetworking\n```\n\nAnd that's it! You're done!\n\n## Example Project\n\nThere's a example project in the repo which shows the plugin in action. To try it out, just open the Terminal in the `PodMergeExample` directory, and run:\n\n```bash\n$ bundle install\n$ bundle exec pod install\n```\n\n\n\n## Benchmarks \u0026 More Info\n\nTo learn more about the performance improvements you can expect, checkout [benchmarks](https://github.com/grab/cocoapods-pod-merge/blob/master/wiki/benchmarks.md).\n\nCurious about how the plugin actually works? Check out [inner workings](https://github.com/grab/cocoapods-pod-merge/blob/master/wiki/inner_workings.md).\n\n## MergeFile\n\nThe `MergeFile` has a very similar syntax to your `Podfile`. It also supports defining **multiple** groups, which creates **multiple** merged pods.\n\nConsider a more common **Podfile**, with lots of pods, fixed versions, and different sources:\n\n```RUBY\ntarget 'MyApp'\n\tpod 'AFNetworking', '2.7.0'\n\tpod 'SDWebImage', '~\u003e 5.0'\n\tpod 'IQKeyboardManager', '6.2.1'\n\tpod 'TTTAttributedLabel', '2.0.0'\n\tpod 'MBProgressHUD', :git =\u003e 'https://github.com/jdg/MBProgressHUD.git', :tag =\u003e '1.1.0'\n\tpod 'FLAnimatedImage', '1.0.12'\nend\n```\n\nLet's group these Pods into two: `UI`, and `Networking`. The MergeFile to achieve this would look like this:\n\n```ruby\ngroup 'Networking'\n\tpod 'AFNetworking', '2.7.0'\n\tpod 'SDWebImage', '~\u003e 5.0'\nend\n\ngroup 'UI'\n\tpod 'IQKeyboardManager', '6.2.1'\n\tpod 'TTTAttributedLabel', '2.0.0'\n\tpod 'MBProgressHUD', :git =\u003e 'https://github.com/jdg/MBProgressHUD.git', :tag =\u003e '1.1.0'\n\tpod 'FLAnimatedImage', '1.0.12'\nend\n```\n\nTwo things to note here:\n\n* The MergeFile supports defining Pods just like your Podfile, with all the options that the Podfile supports, like the `:path, :git, :branch` arguments.\n* You can have any number of groups in your MergeFile. The resulting merged dependencies will be named by the groups defined in your MergeFile.\n\nYou can now modify your original `Podfile` to use the plugin, and the merged pods instead of the individual pods: \n\n```ruby\nplugin 'cocoapods-pod-merge'\n\ntarget 'MyApp'\n\tpod 'Networking', :path =\u003e 'MergedPods/Networking'\n\tpod 'UI', :path =\u003e 'MergedPods/UI'\nend\n```\n\nThat's it! Now just run `bundle exec pod install`!\n\n\u003e Note: Once the pods are merged according to your `MergeFile`, you **should commit** the `MergeFile` into your version control system (like git)\n\n### Special Flags\n\n#### has_dependencies!\n\nIf you have a group of Pods that depend on each other and you want merge them, add this flag into that group.\n\n```ruby\ngroup 'SomePods'\n\thas_dependencies!\n\tpod 'ABC'\n\tpod 'ABCDependsOnThis'\nend\n```\n\nThis enables an experimental feature where the plugin tries to fix dependency imports. For example, If pod `ABC` has code like  `import \u003cABCDependsOnThis/File.h\u003e`, the plugin will automatically convert this import into `#import \"File.h\"`, since after the merge, the both the pods will be in the same framework.\n\n#### swift_version!\n\nIf you have a group of Swift pods, the plugin automatically finds out the common compatible Swift version across those pods, and sets that as the Swift version for the merged Pod. If you'd like to manually set the Swift version of a group, you can use the `swift_version` flag like:\n\n```ruby\ngroup 'SwiftPodsGroup'\n\tswift_version! '5.0'\n\tpod 'SwiftPodA'\n\tpod 'SwiftPodB'\n\tpod 'SwiftPodC'\nend\n```\n\nThis is especially handy if some of the pods in your group do not have a Swift Version defined in their `podspec`.\n\n#### platform\n\nIf you have multiple platforms in your base Podfile, you can specify the `platform` for each group in your MergeFile\n\n```ruby\ngroup 'SwiftPodsGroup'\n\tplatform :ios, '11.0'\n\n\tpod 'SwiftPodA'\n\tpod 'SwiftPodB'\n\tpod 'SwiftPodC'\nend\n```\n\nThis is helpful when you have a Podfile with Pods for iOS, WatchOS, etc...\n\n## Version Control (like git)\n\nYou should definitely commit the `MergeFile`  into your repository, since this is just like your Podfile, and is required for the plugin to work. \n\nThe plugin creates a directory called `MergedPods`, where it keeps the source code and podspecs for the merged pods. Whether you decide you commit this directory depends entirely on your team's workflow. A good rule of thumb is if you commit the `Pods/` directory created by Cocoapods, then you should commit this directory as well. The obvious upside is that the merged pods are cached, and the merge does not take place everytime `pod install` is run, unless something changes.\n\nThe plugin also creates another directory called `MergeCache` when it's running. While this directory is removed when the plugin is done, it can be good practice to add to your `.gitignore` file just in case the plugin fails to remove it.\n\n```bash\nMergeCache/\n```\n\nIf you decide not to commit the MergedPods directory, add that to the `.gitignore` as well:\n\n```bash\nMergeCache/\nMergedPods/\n```\n\n## Tips\n\nThis plugin is not a magic bullet that'll merge all your cocoapods into a single framework. Here's a few tips to save you from hard to debug issues after merging your pods.\n\n* **Start small**, by merging a small number (2 to 4) of your Pods, and check everything works after the merge.\n* Only pods which expose their **full source code** can be merged. Pods that do not expose sources, eg: `Fabric` / `Firebase` cannot be merged.\n* **Don't mix up** Swift and Objective-C Pods in the same group.\n* **Try to make logical sense of your groups**, don't just merge every single Pod your app uses into one giant pod. This can be very fragile, and can lead to hard to debug compilation / linking issues.\n* **Refrain from merging complex or specialized pods** (like pods written in C/C++). Such pods can have special build settings and compiler flags that can break the other pods that are merged with them.\n* **Make sure** you add the required [flags](https://github.com/grab/cocoapods-pod-merge#special-flags) to relevant groups in your `MergeFile`.\n\n\n## Troubleshooting\n\nIf the above guidelines still do not solve your problem, please [report it](https://github.com/grab/cocoapods-pod-merge/issues)! Merging Pods is a complex process, and the plugin does not cover all possible use cases or podspec formats. Any feedback or feature suggesions are also encouraged. Bug reports and pull requests are welcome. \n\n## License\n\nThe cocoapods-pod-merge plugin is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrab%2Fcocoapods-pod-merge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrab%2Fcocoapods-pod-merge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrab%2Fcocoapods-pod-merge/lists"}