Should be installable via CocoaPods

[jchris]

This looks like it could help some users: http://cocoapods.org

[snej]

Personally I’m skeptical of CocoaPods because it tries to build arbitrary libraries by adding them all to your main target, instead of building them as separate libraries and linking them in. This means those libraries can’t use their own prefix headers, compiler settings, etc; instead they have to build using whatever the developer set up for their app. I’ve worked on a number of big projects and I consider the target configurations just as much a part of the project as the source code, so I don’t like to see them ripped out.

There are already CocoaPods for TouchDB and CouchCocoa; I don't know who created or maintains them.

[snej]

See also couchbaselabs/TouchDB-iOS#161

[jchris]

There should be a bug status of "we're not going to write this but if someone works with us to do a clean patch we'll consider it" because I think that's what this is.

Can't decide if we should leave it closed or open.

[nossipova]

CocoaPods is a great way to manage library dependencies and used in many Objective-C projects. It would be awesome if Couchbase Lite would provide a pod spec.

[jchris]

We discussed doing this as a downstream package from our official builds. Similar to how we do the PhoneGap plugin, with some scripts that turn the ios-build.zip into a CocoaPod.

Here's how we do the PhoneGap stuff https://github.com/couchbaselabs/couchbase-lite-phonegap-plugin-builder

[jchris]

related to FMDB packaging https://github.com/couchbaselabs/TouchDB-iOS/issues/45

[mtitolo]

Just stepping in to clarify a few CocoaPods things here.

As of 0.21.0-rc1 Pods are all built as dedicated targets within the Pods.xcodeproj. So prefix headers, framework dependencies, build settings, etc, can now be specified per Pod. Those then get included in a .xcconfig on the main project, so it doesn't even touch your normal project settings, while at the same time everything is there.

Pods work best when source is included, but in 0.23.0 vendored_frameworks were introduced (think GA, Crashlytics, etc) to include pre-built frameworks and libraries. So that is also an option if you'd rather not do a large rewrite of your header files.

While we do accept Podspecs created by non-maintainers of libraries, we really prefer maintainers to have control over those. It ends up being better for everyone. There really isn't a transition process, since all the specs are just in a Git repo, so you can make a PR whenever you are ready.

If you have any specific questions, we'd be more than happy to answer them over on the Google Group.

[snej]

That's great to hear! Sounds like we should definitely investigate CocoaPods, then. There isn't time before our beta release, but hopefully for 1.0.

[rulien]

That would be awsome, since we are considering moving from TouchDB to Couchbase Lite these days

[suprememoocow]

+1 for Cocoapods!

[davidquon]

This would be great as we are also looking to move from TouchDB to Couchbase Lite and having it in CocoaPods would be helpful.

@snej - Any idea when this would be possible now that 1.0-beta is out? Or if you'd like help with the initial CocoaPod setup please let us know as well.

[snej]

I suspect this isn't likely to happen any time soon unless someone who already knows/uses CocoaPods donates a pod spec as a pull request. So yes, we'd appreciate the help!

[davidquon]

It's nice to hear @snej that you're open to supporting CocoaPods. As @mtitolo stated it seems preferable if the maintainer owned the Podspec which is why I was hesitant before this discussion. I'll see if we can fit the initial creation of the Podspec into our schedule. However, if someone else gets to it first I would have no problem with that. 😉

[davidquon]

Hi @snej. So I started to look into this and it's a bit more complicated than I hoped it would be. I'm at the point of running the pod spec lint which does some checking of the code and dependencies. I'm probably going to have some questions for you to ensure that I make the correct assumptions when making the necessary changes in couchbase-lite.

Should I put my questions in this issue, should I create new issues when questions arise, or should I email or message you directly? I'm unsure how much support I'm going to need at the moment as the pod spec lint only outputs so many errors before giving up.

The first such question I have is I get this error when running pod spec lint.

- ERROR | [xcodebuild]  couchbase-lite-ios/Source/CBLGNUstep.m:25:5: error: redefinition of 'digittoint'
- NOTE  | [iOS] [xcodebuild]  /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS7.0.sdk/usr/include/ctype.h:305:1: note: previous definition is here

I'm not sure if it's safe to remove the digittoint or if you needed the special implementation of it in CBLGNUstep for some reason.

[snej]

You can put questions here and I’ll try to answer them as soon as I can.

You shouldn’t be building CBLGNUstep.m; it’s only for the (ancient, almost certainly broken) GNUstep build. If you look at the Xcode project you can see that source file isn’t in any targets.

You should be trying to reproduce the existing target(s) as closely as possible including the set of source files built and the various build configurations. If you’re just looking at iOS support for now, the targets to build are “CBL iOS Library” and “Listener iOS Library”.

[davidquon]

Ah that makes sense. That's why I was kind of confused how this fit into the picture. Good point about looking at the targets. Thanks for the quick response.

[davidquon]

So now I'm seeing an error here:

- ERROR | [iOS] [xcodebuild]  couchbase-lite-ios/vendor/MYUtilities/CollectionUtils.m:98:32: error: pointer to non-const type 'id' with no explicit ownership

The piece of code it's referring to is:

case '@':   return *(id*)value;

Seems like lint might have caught something here but I wanted to get your opinion on this @snej. Thanks.

[snej]

The source files in MYUtilities shouldn’t be compiled with ARC.

Isn't there a way CocoaPods can import an existing target from another project? Recreating it by hand, which is what you seem to be doing, is kind of painful. I’m afraid you might miss something that doesn’t break the build but causes trouble at runtime, for example omitting a source file that contains only category methods.

Also, doesn’t this mean that any time I add a source file or change a build setting or something, it’ll break the podspec unless the equivalent change is added to it?

[mtitolo]

@snej Yes, the podspec will have to be updated when source files or build settings change. We currently don't have a way of automating this (though it's been talked about). But these changes will not be immediately breaking. The spec only needs to be updated with each new versioned release of the library. Think about it this way: if you need to update your manual installation instructions, you need to update the spec. Once created, the spec should be just as easy to update as those instructions.

[snej]

Once created, the spec should be just as easy to update as those instructions.

That’s not true in the case of Couchbase Lite. The installation instructions are (1) Build appropriate target of Couchbase Lite project; (2) copy built framework to your own project folder; (3) link your target with the framework. That pretty much never needs to change.

The kinds of changes you’re saying the podspec needs are equivalent to every single time I add a new source file or remove one or change a build setting. This happens a lot.

I think what you’re saying is based on the type of repo where you’re just supposed to dump the source files of the repo into your own Xcode project and build them along with your own code. Couchbase Lite isn’t like that.

[mtitolo]

@snej you know that CocoaPods can just import a built .framework, right? Just needs to be downloadable and versioned.

[snej]

@mtitolo But that doesn’t sound like what @davidquon is doing, though, based on the issues he’s running into reported above. I agree, I’d much rather the podspec just import the compiled framework.

[mtitolo]

Yeah, things will go much more smoothly if the framework is just imported, as this does seem like a complicated compilation. Then a new version release would just be bumping the version and changing the source URL. c/ @davidquon

[davidquon]

Ah I forgot that CocoaPods can just import a built framework. 😢 At least all this 😓 was a good learning experience about both CocoaPods and Couchbase Lite. I'll give the framework a try tomorrow.

I found one last potential lint error @snej.

- ERROR | [iOS] [xcodebuild]  couchbase-lite-ios/vendor/MYUtilities/MYURLUtils.m:150:1: error: control reaches end of non-void function [-Werror,-Wreturn-type]

My guess is that it's just missing:

#import "Test.h"

No big deal if I can get the frameworks working properly. Just thought I'd pass it along since I got to that point.

[snej]

In Couchbase Lite, Test.h is already imported by the prefix header. But you’re right that I should add an import for the benefit of other projects using MYUtilities.

I wonder why this is being flagged on line 150, though? That’s right in the middle of the test-case, not at the end.

[snej]

In general, Couchbase Lite’s targets already build with -Wall and -Werror and several other warning flags, and I run the Clang static analyzer over it pretty often. There’s not really a need to do these sorts of checks externally.

[davidquon]

Yeah I didn't understand that either about the line. Assuming I can get the framework CocoaPod for Couchbase Lite to work tomorrow I won't need to worry about these pods lint errors anymore. 👍

Just to make my life a little easier, @mtitolo do you have any links or examples of how to import a built .framework in CocoaPods?

Also @snej do you have a link for a downloadable and versioned framework for Couchbase Lite?

Thank you both for your help and support.

[davidquon]

Nice thanks! Yeah I suspected it might be something with the libPods creation as well. I just wanted to verify what the Couchbase Lite was built for and I learned something new with file. Thanks @jchris!

[mtitolo]

@davidquon That's a typical CocoaPods error that we've been dealing with since the GM with 64 bit support dropped. There are some user configurations that have to change due to a change in Xcode.

[davidquon]

Thanks @mtitolo and @jchris. Got what I needed for testing:
https://github.com/davidquon/Grocery-Sync-iOS/tree/cocoapod_test

I also updated the gist with the copy that works and created a PR above to CocoaPods.
https://gist.github.com/davidquon/7435722

[davidquon]

This PR CocoaPods/Specs#5443 should now bring in both CouchbaseLite.framework and CouchbaseLiteListener.framework as well as the LICENSE.txt from the couchbase-lite-community-ios_1.0-beta.zip. The PR should hopefully fix this issue at least on the iOS side.

@snej - I tried to make it easy for you to manage so hopefully you can take over the updates when you update your framework zip files. However, I'd be happy to help if needed. Let me know if you have any questions.

This is how I locally tested the podspec in case you'd like to reference/merge it.
https://github.com/davidquon/Grocery-Sync-iOS/tree/cocoapod_test

Thanks everyone for your help with this.

[snej]

Thanks, David.

I’m not familiar with podspec syntax, but I’ve looked over the file. The only part that seems like it might be wrong is the line s.library = ‘sqlite3’, which I think means to add libsqlite3.dylib to the app’s link list. There are actually several other link dependencies: CFNetwork.framework, Security.framework, SystemConfiguration.framework, and libz.dylib. Shouldn’t those appear in the podspec too?

[davidquon]

Thanks for your feedback @snej. I'll have a look at this to see why it worked for me without those dependencies and make a fix if necessary.

[davidquon]

Okay after further investigation your were correct @snej. I updated the podspec here for your review.
https://gist.github.com/davidquon/7435722

This got overlooked because the Grocery-Sync-iOS app was already bringing in CFNetwork.framework, Security.framework, SystemConfiguration.framework, and libz.dylib to the project.pbxproj.

Also my bare bones basic app podfile accidentally still had a reference to https://github.com/CocoaPods/Specs/blob/master/NewRelicAgent/1.0.0/NewRelicAgent.podspec as I was using that as a reference and it brings in SystemConfiguration.framework and libz.dylib which is why it worked.

Now my question to you @snej is that by just brining in SystemConfiguration.framework and libz.dylib everything seems to compile and run as far as I can tell. Is CFNetwork.framework and Security.framework still needed and are there hidden problem by not including them? I don't mind adding them to the podspec if needed but I figure why include them if they aren't needed anymore.

Thanks for the feedback and help.

[snej]

Security and CFNetwork are definitely used by several classes in Couchbase Lite. For example, I removed Security.framework from Grocery Sync and got a ton of link errors including:

Undefined symbols for architecture armv7:
  "_SecTrustSetAnchorCertificates", referenced from:
      -[CBL_Replicator checkSSLServerTrust:forHost:port:] in CouchbaseLite(CBL_Replicator.o)
  "_SecTrustSetAnchorCertificatesOnly", referenced from:
      -[CBL_Replicator checkSSLServerTrust:forHost:port:] in CouchbaseLite(CBL_Replicator.o)
  "_SecTrustGetCertificateAtIndex", referenced from:
      _WarnUntrustedCert in CouchbaseLite(CBLRemoteRequest.o)
…

CFNetwork is definitely used too.

[davidquon]

Okay thanks @snej. I'll include those frameworks. Not sure why I'm not getting compilation errors or linking errors when I removed them from the Grocery Sync app. Maybe the libraries are being cached or something by Xcode however that doesn't explain why SystemConfiguration.framework and libz.dylib both gave compilation errors when removed. Anyway I'll update accordingly as they are obviously needed.

[davidquon]

How does this look now @snej?
https://gist.github.com/davidquon/7435722

[snej]

Not sure why I'm not getting compilation errors or linking errors when I removed them from the Grocery Sync app.

If this is when you’re building Grocery Sync using CocoaPods(?) then we should look at the reasons for this, because it might point to a problem with the podspec. For instance, it’s possible the link succeeded only because it incorrectly dead-stripped all the Couchbase Lite code that uses those libraries. Did you try running Grocery Sync after removing those libraries?

Maybe the libraries are being cached or something by Xcode

Unlikely, but the Clean command should take care of that. Or deleting the build directory.

[snej]

Writing about dead-stripping reminded me, you need to make sure your podspec enables the -ObjC linker flag in the app. Otherwise some Couchbase Lite code (category methods) will get dead-stripped and cause runtime errors on launch.

[davidquon]

Did you try running Grocery Sync after removing those libraries?

Yes and everything seem to run fine. Meaning I could launch Grocery Sync and add an item and delete an item.

Unlikely, but the Clean command should take care of that. Or deleting the build directory.

I did numerous cleans as well as removing all the Pod generated items.
rm -rf Pods/ Podfile.lock *.xcworkspace/
However I didn't try removing the build directory. I could try that just out of curiosity.

Writing about dead-stripping reminded me, you need to make sure your podspec enables the -ObjC linker flag in the app. Otherwise some Couchbase Lite code (category methods) will get dead-stripped and cause runtime errors on launch.

Pods seems to automatically enable the -ObjC linker flag as I had originally got some warnings about the project flags taking precedence over the pod flags. Additionally here are the flags set by CocoaPods.

Pods-couchbase-lite-ios-Private.xcconfig:OTHER_LDFLAGS = -ObjC ${PODS_COUCHBASE_LITE_IOS_OTHER_LDFLAGS}
Pods.xcconfig:OTHER_LDFLAGS = -ObjC -lsqlite3 -lz -framework CFNetwork -framework CouchbaseLite -framework CouchbaseLiteListener -framework Security -framework SystemConfiguration

[davidquon]

So I did try to remove the DerivedData, clean everything, and removing the CFNetwork.framework and Security.framework from the podspec and everything still seemed to work okay. It's almost like something else is already bringing it CFNetwork.framework and Security.framework. I'm just not sure how that would be possible in my bare bones app.
https://github.com/davidquon/TestCouchbaseLite

That being said I don't mind doing it the correct way and leaving in the CFNetwork.framework and Security.framework in the podspec as that is obviously correct.

@snej - Any other comments on this?
https://gist.github.com/davidquon/7435722

[snej]

Ah, your app target has “Enable Modules” and “Link Frameworks Automatically” set to Yes. Apparently that makes Xcode smart enough to figure out what libraries it needs to link with.

These settings seem to be turned on in new projects, but are not on by default (so they don’t change the behavior of existing projects.) I think you should explicitly include the libraries/frameworks, so the podspec will work correctly in projects that predate Xcode 5.

[davidquon]

Ah, your app target has “Enable Modules” and “Link Frameworks Automatically” set to Yes. Apparently that makes Xcode smart enough to figure out what libraries it needs to link with.

Those settings explain the behavior. I agree we should explicitly include the libraries/frameworks, so the podspec will work correctly in projects that predate Xcode 5. I'll open a PR for that change. Thanks again for your help and support.

[davidquon]

For anyone that is interested in using Couchbase Lite with CocoaPods:
http://cocoapods.org/?q=couchbase

I plan on converting our app to use Couchbase Lite using CocoaPods but if anyone else has any issues with this podspec let me know.

[snej]

David, since you did the work, do you want to announce this on the mobile-couchbase mailing list? If not I’m glad to do it.

[jchris]

How close are we to being able to support Mac with this Podspec? Seems like a nice-to-have, not a blocker.

[snej]

Well, first we need to host a binary build of the Mac framework. After that, I think it just involves changing a few lines in the podspec to point to that URL, and maybe change some library dependencies.

[davidquon]

@snej - Feel free to announce it on mobile-couchbase mailing list. Also I think your assumptions are correct about supporting Mac with a podspec. Whether or not it's in the same podspec is a different story as just by the naming of the pod it might warrant a separate podspec but I'll leave that decision up to you.

[snej]

OK, it’s announced!

[alladinian]

Hi guys!
One quick question regarding the pod...
Since Couchbase-lite framework includes several other projects/pods (such as CocoaHTTPServer for example) shouldn't they be included in the spec's dependencies? Wouldn't they conflict in case one or more of these projects/pods are already included in the same Podfile for example?