cocoapods / guides.cocoapods.org

The guides for CocoaPods

CocoaPods Guides Site

This is the repo for the CocoaPods Guides site.

I'd like to contribute

Great! Head over to CONTRIBUTING.

I'd like to make a suggestion

Fantastic! Take a look at our open issues, and comment on one that seems relevant or open an issue. See our CONTRIBUTING guidelines for opening issues.

I'd like to add my blog post or tutorial.

Delightful! Double check your link follows our External Resource Guidelines, then make a pull request.

I'd like to run guides.cocoapods.org locally

The guides site is built on Middleman, and runs on Ruby 2.1.3.

Steps to setup:

1. $ git clone https://github.com/CocoaPods/guides.cocoapods.org.git
2. $ cd guides.cocoapods.org
3. $ rake bootstrap
4. $ bundle exec rake generate:all
5. $ foreman start
6. Open localhost:4567 in your browser. Changes will be processed automatically

Deploying the latest version to GitHub Pages

$ bundle exec rake deploy

guides.cocoapods.org's Issues

Add a note about `pod update pod` on the pod lib create page

Improve `Private pods`

Also see #28

The Private Pods page is a little unclear in it's explanation of how to go about creating a private spec repo and adding Podspec files.

Part 1, Create a private spec repo, should be clearer about creating a repo, simply requiring an empty repo. Adding a Podspec is also more straightforward than it appears, simply creating the Podspec file and running the pod repo push command.

Ultimately, the structure description is misguiding.

Make the use of british english more consistent

Re:
CocoaPods/CocoaPods#2061 (comment)

Private Spec Repos

Moved from CocoaPods/CocoaPods#2217

@eric-horacek asked:

What do you guys think the official recommendation from CocoaPods should be for this? Does lowering the barrier to entry and making internal updates simpler beat out the loss of required linting?

@supermarin:
Michele has given a great intro on how to start and explained how this works. My talk was more on 'optimizing' and daily use-cases from the real life.

Personally - maintaining a private spec repo seemed like an overhead, because we always needed to push both source code and specs every time we updated any of the shared code. There's 15+ developers working on the code daily, so you can have an idea of how often does this happen.
Your quote has the same point:

In my experience, setting up and maintaining a private Specs repo has been a point of contention on teams in which I've done so in the past. For those that are less knowledgable about what CocoaPods does / is responsible for, it's a weak point in the development process where a lot of stuff can go wrong (users trying to push directly to it, confusion over pod repo add, and so on). However, it does force users to lint their specs before pushing, which is a good way to catch pod/podspec issues before they're committed.

We are still using private pods, but directly accessed via :git => 'path'.
For the linking part, we do have all the unit tests that would catch any failure with it.

#import within pod and when using pod

Within the pod itself should we do:
A) #import "FBTweakViewController.h"
or
B) #import <FBTweak/FBTweakViewController.h>
?

And when using a pod, should we do:
A) #import "FBTweakViewController.h"
or
B) #import <FBTweak/FBTweakViewController.h>
?

Or doesn't it matter at all?

http://guides.cocoapods.org/making/maintaining-and-best-practices.html

Create a page about the quality indicators

Go through the one's that exist and talk about how they work.

Create a guide for Creating a Podspec

A guide on taking an existing project and adding a podspec

Mention installing bunder in using unreleased features

In http://guides.cocoapods.org/using/unreleased-features

Add JS based pulling in of issue counts with d:1 easy in getting started as a dev guide

on http://guides.cocoapods.org/contributing/dev-environment.html
with URLS like https://github.com/CocoaPods/CocoaPods/issues?q=is%3Aopen+is%3Aissue+label%3Ad1%3Aeasy for each gem.

Be consistent with capitalisation and spelling of Pods, Podspecs, Podfiles

Unable to set up this project using current README

I would like to contribute PRs to this project but I first need to get the project to run. The first command does not work.

Do I need a special Ruby configuration to run this project? Should I set up a Vagrant or Docker instead on my Mac so I can it running quickly? I do not want to modify my system Ruby or mess around with a Ruby switching utility which could become a problem later. Working in a container would be preferred.

I'd appreciate some help in getting started so that I can contribute additional guides as I have run into some problems which I have overcome with CocoaPods and I believe that if I can document what I have done it will help others.

> rake bootstrap
Ignoring json-1.8.1 because its extensions are not built.  Try: gem pristine json-1.8.1
Ignoring puma-1.6.3 because its extensions are not built.  Try: gem pristine puma-1.6.3
Ignoring xcodeproj-0.17.0 because its extensions are not built.  Try: gem pristine xcodeproj-0.17.0
Ignoring xcodeproj-0.16.1 because its extensions are not built.  Try: gem pristine xcodeproj-0.16.1
Ignoring xcodeproj-0.16.0 because its extensions are not built.  Try: gem pristine xcodeproj-0.16.0
Ignoring xcodeproj-0.15.3 because its extensions are not built.  Try: gem pristine xcodeproj-0.15.3
Ignoring xcodeproj-0.14.1 because its extensions are not built.  Try: gem pristine xcodeproj-0.14.1
Ignoring yajl-ruby-1.2.0 because its extensions are not built.  Try: gem pristine yajl-ruby-1.2.0
[!] Disabled the middleman publish task, run `rake bootstrap` first.
rake aborted!
cannot load such file -- yard
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators/gem.rb:255:in `<class:Gem>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators/gem.rb:5:in `<module:Generators>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators/gem.rb:3:in `<module:Doc>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators/gem.rb:2:in `<module:Pod>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators/gem.rb:1:in `<top (required)>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators.rb:96:in `<module:Generators>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators.rb:10:in `<module:Doc>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators.rb:2:in `<module:Pod>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc/generators.rb:1:in `<top (required)>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/lib/doc.rb:6:in `<top (required)>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/Rakefile:66:in `block in <top (required)>'
/Users/brennan/Documents/Projects/GitHub/CocoaPods/guides.cocoapods.org/Rakefile:62:in `<top (required)>'
(See full trace by running task with --trace)

We should better document PodSpec and Podfile DSL

The pages in the Guides are quite poor (e.g. http://guides.cocoapods.org/syntax/podspec.html only gives an example of a PodSpec).

They should be much more exhaustive, especially listing all the attributes allowed by the PodSpec DSL (and same for Podfile DSL), as we don't seem to have a complete reference of all allowed attributes anywhere.

For example I can't seem to find any page documenting the vendored_frameworks DSL and someone searching how to reference a 3rd Party Framework in a podspec can't find a thing about that.

[email protected]

Document environment variables & config options

Pointing to unknown document

When executing pod install I am pointed to an unknown document (issue on this site):

bash-3.2$ pod install MapBox
WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.
See #26 for
possible solutions.

As can see, there are only 19 issues created, this what I am writing now probably will be issue 20, so how can I find a solution to the problem?

I get the following error message when executing install:

Stack

   CocoaPods : 0.33.1
        Ruby : ruby 2.0.0p451 (2014-02-24 revision 45167) [universal.x86_64-darwin13]
    RubyGems : 2.0.14
        Host : Mac OS X 10.9.4 (13E28)
       Xcode : 5.1.1 (5B1008)
Ruby lib dir : /System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/lib
Repositories : master - https://github.com/CocoaPods/Specs.git @ ace937d3ef44e3c8da9274e7f908b6f30ef3e93e

Error

NoMethodError - undefined method `ansi' for nil:NilClass
/Library/Ruby/Gems/2.0.0/gems/claide-0.6.1/lib/claide/command/validation_helper.rb:77:in `prettify_validation_suggestion'
/Library/Ruby/Gems/2.0.0/gems/claide-0.6.1/lib/claide/command/validation_helper.rb:21:in `argument_suggestion'
/Library/Ruby/Gems/2.0.0/gems/claide-0.6.1/lib/claide/command.rb:436:in `validate!'
/Library/Ruby/Gems/2.0.0/gems/claide-0.6.1/lib/claide/command.rb:280:in `run'
/Library/Ruby/Gems/2.0.0/gems/cocoapods-0.33.1/lib/cocoapods/command.rb:48:in `run'
/Library/Ruby/Gems/2.0.0/gems/cocoapods-0.33.1/bin/pod:33:in `<top (required)>'
/usr/bin/pod:23:in `load'
/usr/bin/pod:23:in `<main>'

[!] Oh no, an error occurred.

Search for existing github issues similar to yours:
https://github.com/CocoaPods/CocoaPods/search?q=undefined+method+%60ansi%27+for+nil%3ANilClass&type=Issues

If none exists, create a ticket, with the template displayed above, on:
https://github.com/CocoaPods/CocoaPods/issues/new

Don't forget to anonymize any private data!

---

Probably should report this issue on CocoaPods, but I am pointed here as well.

Improve documentation for `sources` and authentication

See CocoaPods/CocoaPods#2679 (comment) for context

Improve Rakefile to avoid cloning whole submodules and other errors

I tried to play with guides.cocoapods.org in order to redeploy the website (since the fix of #1 and #4 were available) but had the following problems:

Shouldn't we shallow clone?

• rake bootstrap does some git submodule update --init --recursive which will clone 6 submodules, two of which (CocoaPods and Core) are particularly huge (~200MB each). It took me 50 minutes for the submodule update to finish!!
• We should probably limit the depth of those modules instead (and don't probably need to recurse as well) and use a shallow clone of these modules, especially as those are only used to parse the yard doc from the sources. Something like git submodule update --init --depth 1?

Missing Rake task dependency?

Not knowing middleman and the process to generate the site, I tried rake build before rake generate:all and it failed, missing to find the yaml files in docs_data. The build task should maybe have a dependency on the generate:all task?

Rakefile should use bundle exec?

The Rakefiles do not embed the commands in bundle exec. For example, it seems I have to bundle exec rake generate:all in order for this task to work otherwise I will get Gem::LoadError: You have already activated rake 10.3.2, but your Gemfile requires rake 10.1.1. Prependingbundle execto your command may solve this.. The bundle exec should be done by the Rakefile itself.

Rake deploy task generates an error

When I tried to bundle exec rake deploy I got the following error:

$ bundle exec rake deploy
Building DSL Data
Generating docs_data/podfile.yaml
Generating docs_data/podspec.yaml
Building Commands Data
Generating docs_data/commands.yaml
******
cd /Users/olivier/Documents/Dev/GitHub/Rainforest/guides.cocoapods.org
cd -
cd /Users/olivier/Documents/Dev/GitHub/Rainforest/guides.cocoapods.org/build
git init
Initialized empty Git repository in /Users/olivier/Documents/Dev/GitHub/Rainforest/guides.cocoapods.org/build/.git/
git remote add origin https://github.com/CocoaPods/guides.cocoapods.org.git
git fetch origin
remote: Counting objects: 14264, done.
remote: Compressing objects: 100% (2039/2039), done.
remote: Total 14264 (delta 7726), reused 14248 (delta 7710)
Receiving objects: 100% (14264/14264), 3.75 MiB | 116.00 KiB/s, done.
Resolving deltas: 100% (7726/7726), done.
From https://github.com/CocoaPods/guides.cocoapods.org
 * [new branch]      gh-pages   -> origin/gh-pages
 * [new branch]      master     -> origin/master
git checkout master
Branch master set up to track remote branch master from origin.
Already on 'master'
git checkout gh-pages
error: The following untracked working tree files would be overwritten by checkout:
    CNAME
    contributing/components.html
    contributing/contribute-to-cocoapods.html
    contributing/dev-environment.html
    contributing/index.html
    contributing/release-process.html
    contributing/setting-up-the-environement.html
    contributing/tickets-handling.html
    index.html
    javascripts/application.js
    making/getting-setup-with-trunk.html
    making/index.html
    making/maintaining-and-best-practices.html
    making/making-a-cocoapod.html
    making/private-cocoapods.html
    making/specs-and-specs-repo.html
    reference.html
    stylesheets/app.css
    typeahead.json
    using/faq.html
    using/getting-started.html
    using/index.html
    using/the-podfile.html
    using/troubleshooting.html
    using/using-cocoapods.html
Please move or remove them before you can switch branches.
Aborting
rake aborted!
Command failed with status (1): [git checkout gh-pages...]
/Library/Ruby/Gems/2.0.0/gems/middleman-gh-pages-0.0.3/lib/middleman-gh-pages/tasks/gh-pages.rake:27:in `block (2 levels) in <top (required)>'
/Library/Ruby/Gems/2.0.0/gems/middleman-gh-pages-0.0.3/lib/middleman-gh-pages/tasks/gh-pages.rake:20:in `block in <top (required)>'
Tasks: TOP => deploy => publish => prepare_git_remote_in_build_dir => /Users/olivier/Documents/Dev/GitHub/Rainforest/guides.cocoapods.org/build/.git/refs/remotes/origin/gh-pages
(See full trace by running task with --trace)

---

I know, that's a lot of issues regrouped in one single GitHub issue entry, but I'm not sure if all those issues are related or not, not really knowing middleman and how it works and all the process around to build/deploy.

get things building on CI again

Making a CocoaPod: adding tags

http://guides.cocoapods.org/making/making-a-cocoapod.html

As a newbie using this guide, I had no idea that I was supposed to:
git tag '0.1.0'
git push --tag

Because a guide is supposed to help new users, I really think those two should be included with a brief description.

Missing "working with your first project." part of "Getting Started".

The description of getting-started.html.md say

This is a guide for setting up CocoaPods and working with your first project.

However, I observe "working with your first project" part is missing.
I mean about pod init and pod setup.

Sorry for not to contribute the doc myself directly, I'm not a native English speaker nor practiced English very, also I'm not catching up newest best practice about CocoaPods, so I thought just pointing out may work.

Article explaining the intended usage of pod install vs pod update

A lot of people are confusing pod install and pod update (e.g. use pod install only the first time to create the xcworkspace, then use pod update each time they add pods to their Podfile) and probably don't use them as intended.

See this comment for an already detailed explanation which can be used as a base for this kind of guide.

---

We could even write a more wide article / guide explaining the typical workflow of using CocoaPods in general (like having a typical scenario using some common use case examples of the lifetime of a project)

make a CocoaPods docset for Dash

You could wrap the guide content into a Dash docset. This would be quite useful for people getting familiar with the Podfile or .podspec syntax.

I did a docset generator in ruby in a while ago (here) that shows how to do some of the basics.

Full documentation for generating and sharing dockets can be found gere.

Update Setting Up For Development

It should probably reference Rainforest, for example.

Mention best practises using resources

We should show how to consume resources programatically inside the guides, I don't belive it's clear enough currently on the code involved to consume them. It's important to note that mainBundle should never be used since this changes things with frameworks.

resource_bundles

http://guides.cocoapods.org/syntax/podspec.html#resource_bundles

Example:

NSBundle(forClass:URL.class()).URLForResource(name:"Example", withExtension:"bundle")

spec.resource_bundle = { 'Example' => 'Resources/*.png' }

---

resources

http://guides.cocoapods.org/syntax/podspec.html#resources

Example:

NSBundle(forClass:URL.class())

spec.resources = 'Resources/*.png'

Update to deal with new Podfile syntax

With whatever is the outcome for CocoaPods/CocoaPods#2513

Please add the need to run 'pod setup' to install guide

See Kim's answer : http://stackoverflow.com/questions/27053344/cocoapods-install-error

This has tripped me up twice, and I've spent a couple of hours finding/re-finding the solution (bad on me for having to re-find). Thanks!

Look at the wording around Semantic Versioning

http://sealedabstract.com/rants/on-ios-packaging/

However CocoaPods goes far beyond being opinionated about your build process. They have some kind of religion about using the RubyGems versioning system (Yes, for iOS libraries. wat.) Then they require you to update your list of source files in 2 places, because parsing Xcode’s format is too hard I guess?

The wording around versioning makes sense if you come from a ruby background but should be given a second look from the perspective of a Cocoa developer. We don't use SemVer cause bundler does, though we kinda do, but because semantic versioning is a standard that makes it easy for people to understand when something is worth updating or not.

More explanation of differences between podspec's xcconfig and compiler_flags

Aka xcconfig is for final integration, compiler_flags for pod compilation only

Goes well with #63

Missing topic on installation or troubleshooting - pod setup

I recently setup a new computer for cocoa pods and followed the installation guide. Everything work up until the point when I ran pod install on an existing project. I was given the error:

/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/lib/ruby/2.0.0/pathname.rb:422:in `open': No such file or directory - /Users/mdarnall/.cocoapods/repos (Errno::ENOENT)

After digging around for a while I found on stack overflow the solution - to run pod setup.

I'm happy to contribute this to the guides - but wasn't sure if that's more troubleshooting or installation. IOW is this a normal installation step?

Update installation instructions

1. Promote CocoaPods.app
2. Promote sudo-less install, currently the documentation explains the sudo install which will not work on El Capitan due to SIP.

getting-started.html.md should contain info about using/testing pre-prereleased code

I am not talking about RC versions for that we have $ [sudo] gem install cocoapods --pre. I am talking about code from master branch or even some other branch of cocoapods.

This occurred to me when I wanted to test-drive swift support in cocoapods. I really struggled to get the cocoapods 'swift' branch working for me. @mrackwitz answered lots of questions on his PR. @orta's code also helped and finally Instruction on Quick's repo helped me get it right.

I blogged about it, but I think we should have that in the guides especially for non-ruby folks like me. We can't expect every ios dev to be familiar with Ruby right?

Now we can take 2 approaches, short and simple is that we include my blog post as external link in the guide, I am happy to edit and update the post to make it more accurate with help from you folks.

Another approach is that we include similar instructions in the guide itself. We may call that section installing 'Test' version of Cocoapods?

I am happy to do a PR with either of approaches. I thought I will first get the discussion started in an issue and get some opinions from you all.

Bundle'd plugins aren't included in the command line guide

Pod docs broken

http://guides.cocoapods.org/syntax/podfile.html#pod

Shows a blank page currently

Show detailed documentation of Podspec DSL attributes

See ruby documentation updates here: CocoaPods/Core#260

These changes are not yet rendered in the guides pages. Specifically the @overload and @option documention of the source and license hashes.

Refactor documentation for private pods

http://guides.cocoapods.org/making/private-cocoapods.html

Some things are no longer relevant:

If you plan on forking a library that is already part of the Master Spec repo, for now we suggest choosing a name that starts with a letter before M (due to spec repos loading in alphabetical order, see #982).

"The Podfile" should show sources in all example, showing master and private in some cases:

http://guides.cocoapods.org/using/the-podfile.html

Specs and Specs Repo page out of date

https://github.com/CocoaPods/guides.cocoapods.org/blob/master/source/making/specs-and-specs-repo.html.md#how-do-i-update-an-existing-pod

Needs updating for Trunk. Could link to Specs/README.md FAQ when complete.

Podspec Syntax Reference should document the JSON podspec format

The Podspec Syntax Reference should be updated to also document the JSON format. This would make it significantly easier to build tooling on top of the JSON specifications.

For example, in Ruby there are three different ways to populate the authors field. It'd be great to document if these three different ways are also valid in JSON.

Add section around why we can only support all Frameworks or all Libraries

People will be confused. They will presume this is a choice we made for them, but without having the reasoning in the open then no-one knows why. I don't know why. This in part could go along with CocoaPods/CocoaPods#3029

Update implicit source documentation

This has been un-deprecated, not sure if this changes anything in the guides. Filing this so it's taken look at.

CocoaPods/CocoaPods@7840787e05af

Building a CocoaPods Plugin

`yard` is required to run `rake bootstrap`

I am following the instructions from the README but I have had to overcome several obstacles. One is the fact that yard was missing. Details are below. I do not know how this should work, but it seems like it should not result with this error.

> rake bootstrap
[!] Disabled the middleman publish task, run `rake bootstrap` first.
rake aborted!
cannot load such file -- yard

> sudo gem install yard
Fetching: yard-0.8.7.6.gem (100%)
Successfully installed yard-0.8.7.6
Parsing documentation for yard-0.8.7.6

Quality Indexes typos

I went to clone the guides repo to fix some typos on the Quality Indexes page, so I clicked on the Pull Request link on the bottom of the page, which took me to a MarkDown file that has 8 lines - this can't be the same page, can it?

Safari's Reader Mode break the content

When enabling the "Reader mode" in Safari, the content of the guides (any guides page that supports "Reader mode" anyway) is truncated and missing paragraphs (making the content inconsistent).

E.g. in the following capture, paragraphs are missing (see original page) at the beginning (starting from 2nd paragraph) and in other places of the content, and content stops prematurely, missing the end of the article.

Improve wording on libraries sections in reference

re: https://twitter.com/taybenlor/status/497540001639698433

@CocoaPods http://t.co/4y3hkOJny3 I spent a day changing strings until I found out that it expected 'Pod/libMyLib.a'

@orta explain: what it does (adds library search path), what the string is (full path from spec root) and related fields (library)

@orta for those of us working with pods as a black box there's lots of pages for old issues, it's hard to nail down current behaviour

Commands page empty

http://guides.cocoapods.org/terminal/commands.html#commands has no content.

Checking in the Pods Folder: Inconsistent Advice

I was studying the documentation for using CocoaPods, and I noticed an annoying inconsistency in the section about adding the Pods directory to one’s .gitignore.

The contents of the “Pros” and “Cons” sections seem to imply that one should not add the Pods folder to source control (aka put it in your .gitignore), but the text immediately above says “We recommend against adding the Pods folder to your .gitignore.” This (to me) implies the exact opposite of what the text below states. It seems to me that this is a simple grammatical oversight. If you want me to provide a PR for this, I will, but it is such a simple change I thought a committer handling it directly would be faster.

tl;dr: Remove the struck-through word: “We recommend against adding the Pods directory to your .gitignore.”

Podfile syntax guide does not include information on using branches

The .md file in the repo has information on how to target a branch or a tag, but those sections are missing from the live version.

Broken link in breadcrumb

Would submit a PR but don't quite have time to track this down. Just FYI.

Add more detail to 'Podfile syntax reference: Xcodeproj'

http://guides.cocoapods.org/syntax/podfile.html#xcodeproj

From the Podfile reference I'm not understanding why or when I would use xcodeproj to specify a build configuration.

Do I always need to do this if I use configurations other than the Xcode defaults of 'Debug' and 'Release'?
What does this do?

Travis does not have the credentials to deploy guides automatically

https://travis-ci.org/CocoaPods/guides.cocoapods.org/builds/26285548