What does :submodules => true mean in a CocoaPod Podspec?

Question

TL ; DR :

What does CocoaPods do if you set :submodules (part of spec.source) as true?

Full Version:

My previous project structure looked like

Project
Linked To --> Core static library (submodule added as a subproject)
            --> Linked To --> several dependent submodules (files added within subproject)

I'm now in the process of transitioning to CocoaPods for dependency management.

My new (transitional) structure looks like

Project
--> Depends on Core CocoaPod and few other CocoaPods
     --> Core depends on several open-source libraries
     --> Core also depends on a few submodules (in process of converting these)

I've seen other projects (e.g. AFNetworking) specify their source like this:

s.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git', :tag => "2.1.0", :submodules => true }

What does CocoaPods do if you pass :submodules as true as in this example? Is this the right setting for this use case?

I can't seem to find this documented anywhere on CocoaPods.org.

Answer 1

This is to do with git repositories that have submodules (See Git Submodules for more information on them). Normally when you clone a git repository you need to do something like:

git submodule init 
git submodule update

to pull down the submodules which the git repository depends on (e.g. if the git library has a reference to another git library it could add it as a submodule instead of adding the files to its own versioning - meaning the submodule could update and the git library would have access to the latest version automatically)

I don't know exactly what cocoapods does as part of the git clone process but I imagine it would run these 2 commands after cloning the repository to ensure all the submodule dependancies are valid.

FYI this command does inits and updates all submodules and any submodules they depend on - so it's is probably what cocoapods uses

git submodule update --init --recursive

This change was introduced in 0.12.0: (see changelog)

Hope it helps!

Answer 2

It means the pod contains git submodules, however if you use your pod via a git url in your Podfile it has no effect. In that case you again need to specify :submodules => true in the Podfile.

If AFNetworking specifies this param but actually has no git submodules then it must simply be a mistake.

If you depend on other pods then use the dependencies param instead.