cocoapods/pod-template

An opinionated template for creating a Pod.

pod-template

An opinionated template for creating a Pod with the following features:

• Git as the source control management system
• Clean folder structure
• Project generation
• MIT license
• Testing as a standard
• Turnkey access to Travis CI
• Also supports Carthage

Getting started

There are two reasons for wanting to work on this template, making your own or improving the one for everyone's. In both cases you will want to work with the ruby classes inside the setup folder, and the example base template that it works on from inside template/ios/.

Best practices

The command pod lib create aims to be ran along with this guide: https://guides.cocoapods.org/making/using-pod-lib-create.html so any changes of flow should be updated there also.

It is open to communal input, but adding new features, or new ideas are probably better off being discussed in an issue first. In general we try to think if an average Xcode user is going to use this feature or not, if it's unlikely is it a very strongly encouraged best practice ( ala testing / CI. ) If it's something useful for saving a few minutes every deploy, or isn't easily documented in the guide it is likely to be denied in order to keep this project as simple as possible.

Requirements:

• CocoaPods 1.0.0+

pod-template's Issues

"Usage" section in POD_README.md should be improved

I think the Usage header suggests that the section is going to contain informations on how to use a project. But what's there are steps necessary to run an example project.

We could improve it in one of these ways:

• rename Usage to Demo or Example
• add a hint to the pod owner that he/she should include code samples in this section
• merge it with Installation section (it's probably a bad idea)

Adopt flat style badges

See http://shields.io

They rock!

Enabling warnings on the library

The current approach is suboptimal because doesn't allow to easily enable warnings in the library. This is the case because the Pod is imported as a development pod. I can see two solutions:

• Implement a feature which allows CocoaPods to specify the warnings of a target
• Import the library manually and implement a feature which tells CocoaPods

VERSION file

Now that all the specs are evaluated and serialized to JSON, I vote for making the default spec's version read from a VERSION file in the root of the project, and basing the rake tasks off of that. Thoughts?

Should we move the project to the root?

Having to cd to the Project dir just to perform pod install is inconvenient. Moreover, Travis install CocoaPods dependencies automatically if a Podfile is detected in the root and this sounds like a great heuristic reasonable in other scenarios.

The reason why the project was moved to a dedicated folder was to keep the root of the repo clean. We could still recommend to keep the files of the targets (usually the demo and the tests) in the project dir.

If you say yes to view testing you have to have a target bundle to host snapshots in

Why does release push only to master

Is there a special reason why the release task only push to master? If not I would work on a solution to push also to other branches and then create a pull request.

Make default pod use resource_bundles

https://twitter.com/KrauseFx/status/503942026942251008

The Folder structure differs from the CocoaPods Guides

The initial folder structure from the CocoaPods Guides differs from the pod-template structure.

Reduce and clarify scope of this project

I need a small and reasonable starting point for making modular Cocoa code. Currently my model is:

1. open XCode
2. create sample project put modular code in a separate class
3. wait for someone to make a CocoaPod for me.

I would like to replace step one with "download the template" using the output of this project. This ISSUE is a suggestion to have this pod-template project be just that.

Following are the most popular CocoaPods sorted by GitHub stars (it overweights older projects):

AFNetworking/AFNetworking   2708    10169
facebook/three20    1527    7443
RestKit/RestKit 1355    5294
BradLarson/GPUImage 1181    4861
pokeb/asi-http-request  1156    4785
jdg/MBProgressHUD   1266    4286
rs/SDWebImage   1162    4207
facebook/facebook-ios-sdk   1599    4069
magicalpanda/MagicalRecord  680 3942
johnezang/JSONKit   981 3856
ccgus/fmdb  847 3715
Inferis/ViewDeck    753 3565
Grouper/FlatUIKit   431 3554
libgit2/libgit2 762 3516
jverkoey/nimbus 811 3447
devinross/tapkulibrary  557 3311
stig/json-framework 680 3186
levey/AwesomeMenu   495 3100
cocos2d/cocos2d-iphone  845 3019
samvermette/SVProgressHUD   603 2919
path/FastImageCache 277 2885
ReactiveCocoa/ReactiveCocoa 273 2858
nicklockwood/iCarousel  665 2611
escoz/QuickDialog   541 2564
square/PonyDebugger 271 2514
tombenner/nui   291 2409
twitter/twui    220 2389
CocoaLumberjack/CocoaLumberjack 418 2337

Whichever of these has the best "layout" we should copy.

To resolve this "issue" please

• create a Wiki page that describes the scope of this 'pod-template' project (wiki/Pod-Template-Project-Discussion)
• create a Wiki page where I can discuss the research above and post code like I used to create the above list (wiki-Cocoa-Pods-Best-Practice-Research)
• remove CHANGELOG and POD_README
• create a 0.0.1 release
• update the README to start with "download the 0.0.1 tarball" and support the use case above

Please reply to show your support or comment

Example of how the template is perceived by the users

http://code.dblock.org/your-first-cocoapod

When using Specta, xctool doesn't run the tests

Thanks for this template. As a library author who's not super-familiar with CocoaPods, I've found it helpful.

I created a project using this template and Specta. The tests seem to run okay in Xcode, but they don't run during the Travis build, or when I run xctool test.

Is this a known issue? I saw mention in #67 that Specta isn't working well on Xcode 6.1. I tried Specta 0.3.0.beta1 but it seems to have the same problem.

Since the problem would affect any users of the template, it would seem, I opened the issue here.

Running test from the command line sometimes fails

I reported this bug CocoaPods/CocoaPods#2929. I think the problem is in the template because I tried with xctool, xcodebuild, xcode 6.0, 6.1, 6.1.1, mac os x 10.9 & 10.10, cocoapods 0.33.0 and 0.35.0 and the problem remains. The only thing in common with all this setups is the template

Swift support

• No class prefix

Add preconfigured demo/test project

`pod lib create` should offer the option to create a JSON podspec

Right now it will always create a Ruby podspec. Since CocoaPods supports JSON podspecs as well, pod lib create should offer this functionality (I'd argue that JSON should be the default, but I wouldn't expect to win that argument, so I won't 😄)

Complete implementation

The original description of the implementation can be found at: CocoaPods/CocoaPods#850

Support user configurable licenses

Stumbled across this cool stuff here https://github.com/licenses/license-templates https://github.com/licenses/lice-js/blob/master/templates.json. We can integrate and allow the user a selection.

Running pod lib create should give me a way to opt out of 3rd Party testing framework

@segiddins

It's nice that you offer the option, but it shouldn't be a requirement.

Proper implementation of resource bundles

I am using the pod lib create to use this template and bring my project into CocoaPods.

The included s.resource_bundle does not seem to work out of the box in bring assets into the bundle.

This issue is documented further at https://stackoverflow.com/questions/25835862/creating-a-cocoapod-library-and-uiimage-imagenamed-returns-null

I am not sure if this is just my ignorance in using CocoaPods (likely) or if pod-template could provide better documentation or build scripts to make this process easier.

Create a full test

We should have a repo which is the result of pod-template which specific arguments. Then a test that runs though the same options and then does a diff on output.

Similar to https://github.com/QueryKit/mogenerator-template/blob/master/Makefile#L7-8. We don't need any complex ruby, simple diff does the job.

This should give us more visibility on the output and how it looks, and also allows us to know when we unintentionally break something.

The rake spec task could have a default implementation based on the xctool

Bad podspec resources location suggestion

It looks like
s.resources = 'Resources'
doesn't work. [1, 2]

I did this instead
s.resource = 'Resource'

Worked for me.

[1] http://stackoverflow.com/a/12835590/337735
[2] http://stackoverflow.com/a/15775258/337735

Improve template to read information from .gitconfig

I think it would be cool to substitute URLs in the generated podspec. Maybe this is a bit too opinionated. I'm not entirely sure if people still do this, but I once set my username in my gitconfig for hub I think it was. We could detect this and use it if available. I've at least spotted it in the wild in @Keithbsmiley's dotfiles.

$ git config github.username
kylef

If we have the username, along with the pod name we can substitute the following things:

s.homepage = "https://github.com/kylef/PodName"
s.source = { :git => "https://github.com/kylef/PodName.git", :tag => s.version }

Shields.io Badges Invalid

I am creating a number of Pods using the pod-template repo and pod lib create. They are working great; however, the badges automatically placed in the README don’t say anything useful. I have long since submitted a Pod through trunk, I have verified that it is present in the Specs repo, but the badges still say “pod invalid”. Does anyone know why this is?

new .travis.yml file passes on a fail

https://travis-ci.org/orta/ar_dispatch/builds/42975318

Rake release auto-tag recognition does not work

When using single quotes the release task does not recognize the correct version:

Sample podspec:

Pod::Spec.new do |s|
  s.name = "MyPod"
  s.version = '0.0.12'
....
end

Output:

* Running version
rake version
-- fetching version number from github
git fetch
The current released version of your pod is 0.0.12
Enter the version you want to release (0.0.13)

You are about to release `0.0.12`, is that correct? [y/n]
n

Changing it to double quotes results in the right output:

* Running version
rake version
-- fetching version number from github
git fetch
The current released version of your pod is 0.0.12
Enter the version you want to release (0.0.13)

You are about to release `0.0.13`, is that correct? [y/n]
y
* Running specs
rake spec

"No such file or directory - VERSION" when doing pod install on example project

When I run pod install within the /Example directory to setup my example project, I get an error:

Analyzing dependencies
Fetching podspec for `RMCoreDataStack` from `../`

[!] Invalid `RMCoreDataStack.podspec` file: No such file or directory - VERSION. Updating CocoaPods might fix the issue.

 #  from /Users/robmaceachern/workspace/personal/RMCoreDataStack/Example/Pods/Local Podspecs/RMCoreDataStack.podspec:3
 #  -------------------------------------------
 #    s.name             = "RMCoreDataStack"
 >    s.version          = File.read('VERSION')
 #    s.summary          = "Hit the ground running with a sane Core Data stack."
 #  -------------------------------------------

Here's my /Example/podfile

target "BasicDemo" do
  pod "RMCoreDataStack", :path => "../"
end

I just noticed that there is a bit of discussion about this issue here #50.

Print a link to the best practices

Print a link to the best practices (once they have been implemented) after the generation of the scaffold.

Not sure if this should be performed by the template or by the pod lib command in cocoapods proper.

Wrong description in pod template expecta tests

Just a quick note, I couldn't find the original file, where I could hand in a pull request.

When generating a pod with expecta there are 2 blocks, one with failing tests and one with working ones.

In the working ones in Tests.m:36 it says 'will wait and fail' while it should say 'will wait and succeed'

Add recommendations beyond the template

Recommendations should be stored in a file where pull requests are possible. A file in this repo or a file in the guides.cocoapods.org repo should be fine.

An example recommendation might be:

• Include an umbrella header for your library named after itself. For example the AwesomePod library should include a header which can be imported like #import <AwesomePod/AwesomePod.h>
  • This simplifies the adoption of your library.

DEV_README.md || CONTRIBUTING.md

Does is make sense to have a file that's only for the developer to read that tells them a little bit about the template's functions. It's a bad idea to presume people know to do rake --tasks to find out about the Rakefile and that the /Example/ should have an Xcode project and what they Podfile will do you you. Etc. Etc.

Remove Podfile.lock

orta/ORStackView#4 (comment)

So I don't forgot, i'll tackle this if no one beats me to it

Development pod files not going to the right place

› pod --version
0.35.0.rc2

I have created a new pod with

pod lib create FDTake

Then added my classes h and m file into XCode like so.

However they were placed here instead of the expected arrowed location.

Account for invalid characters (for github repos) in pod name

Moved from CocoaPods/CocoaPods#2337.

Pod lib create improvements

Originally submitted by @orta in CocoaPods/CocoaPods#1921

Rakefile should use allow-empty for pushing

git commit --allow-empty

   expecta-container-classes   master ✔  rake release                                                                                                                                                                                                                                                          15:25:28
* Running version
rake version
-- fetching version number from github
git fetch
The current released version of your pod is 1.0.0
Enter the version you want to release (1.0.1)
1.0.0
You are about to release `1.0.0`, is that correct? [y/n]
y
* Running specs
rake spec
* Linting the podspec
pod lib lint

 -> Expecta+ContainerClasses (1.0.0)

Expecta+ContainerClasses passed validation.
git commit Expecta+ContainerClasses.podspec CHANGELOG.md -m 'Release 1.0.0'
# On branch master
nothing to commit, working directory clean
rake aborted!
Command failed with status (1): [git commit Expecta+ContainerClasses.podspe...]
/Users/orta/dev/ios/expecta-container-classes/Rakefile:63:in `block in <top (required)>'
Tasks: TOP => release
(See full trace by running task with --trace)

Add sample Travis file

Although Travis is a proprietary system is the most widespread option for CI in the OSS world. Adding a sample file, ready to be tuned could be very handy for newcomers.

A sample file could be:

# .travis.yml

language: objective-c
before_install:
    - brew update
    - brew install xctool
install: cd Project; pod install
script: xctool -workspace Project/NAME.xcworkspace -scheme Demo test

We could debate whether we should recommend the usage of the xctool.

Make link to guide blue and include an underline

Also, stop people at that point if they're running through this for the first time.

'pod lib create' missing .travis.yml file

I created a new lib and I did not get a .travis.yml file generated, has anyone had the same experience?

Not having an example breaks the Podfile generation

See CocoaPods/CocoaPods#2616

example Podspec doesn't have social media url

rake release fails if you don't have push access to the master repo

Here is the error I get.

Adding the spec to the `master' repo

 - [Add] NHSeeThroughView (0.1.0)

Pushing the `master' repo

error: The requested URL returned error: 403 while accessing https://github.com/CocoaPods/Specs.git/info/refs
fatal: HTTP request failed

`puts` within template are not printed out

Because of the default non-verbose mode any puts in the templates would never be printed out.

Sample output:

~$ pod lib create Sample
Creating `Sample` Pod
Configuring template

To learn more about the template see `https://github.com/CocoaPods/pod-template.git`.
To learn more about creating a new pod, see `http://guides.cocoapods.org/making/making-a-cocoapod`.

Should output:

~$ pod lib create Sample
Creating `Sample` Pod
Configuring template
Configuring Sample
user name:Piet Brauer
user email:[email protected]
year:2014

To learn more about the template see `https://github.com/CocoaPods/pod-template.git`.
To learn more about creating a new pod, see `http://guides.cocoapods.org/making/making-a-cocoapod`.

Lines suppressed:

https://github.com/CocoaPods/pod-template/blob/master/configure#L13
https://github.com/CocoaPods/pod-template/blob/master/configure#L24-L26

Also questions will not be asked in production.
https://github.com/orta/pod-template/blob/master/configure#L39-L48

Example Podfile causes crash by default

The example podfile includes the pod line outside of the target entities. This causes a crash on pod install. This is a known issue and the workaround is to move the pod line inside a target entity.

Notes from testing orta pod-template

No joke, this well written.

remove return in port dtemplate

add the file to your classes dir
edit podspec
( tags? )
`pod install` in the folder
open UnitTests.xcworkspace
`cmd + y` 
XCCONFIG NOT GETTING SET?!
tests = OK
make github repo
travis


Add a "switch + to - for github stuff" - open source?
go to travis/profile - turn on your new repo
"make a change, trigger a build on travis"
"403 error on pod push"
"cocoapods/specs"

The first time the CLI needs to access the user's defaults system - there's an ugly message from the system

I don't remember what the message is anymore

Use Xcodeproj to generate the example (and framework) project

I think it would be nice to replace the current Example project which is just renamed to some code that can generate framework targets for all selected platforms along with test target and example target depending on the users options.

I'd suggest the new layout would look something like this (using Stencil as the name of this pod).

.
├── LICENSE
├── README.md
├── Stencil.podspec
├── Stencil.xcodeproj

├── Stencil
│   ├── (Shared Code).swift
│   ├── ios
│   │   ├── (iOS only code)
│   ├── osx
│   │   ├── (OSX only code)
├── StencilTests
│   ├── The tests
│   ├── ios
│   │   ├── (iOS only tests)
│   ├── osx
│   │   ├── (OSX only tests)
├── StencilExample
│   ├── Any example code

The project would have the following targets:

• Stencil-iOS (Framework)
• Stencil-OSX (Framework)
• Stencil-iOSTests
• Stencil-OSXTests
• Stencil-Example (Example OS X or iOS application?)

Would also have some script (Makefile, Rakefile or .travis.yml) that can build everything and run both platform tests.

Many files are not wrapped at 80 chars

add license for template