Set up an open source Xcode framework project

This is part of a series on FootlessParser, a parser combinator written in Swift.


I find these steps helpful when setting up any new open source framework project in Xcode.

Create project

https://github.com/kareman/FootlessParser/commit/414e3961d3bb2a2df8a257804534578bc7a06461

Create a new project in Xcode, and select OS X framework if it is for both iOS and OS X. The iOS framework target can be added later, besides OS X frameworks are more practical for unit testing. No simulators needed.

Do not select to add it to Git right away. Because of this.

And that’s it. I so do love a fresh project.

Create root folders “tests” and “source” and move stuff in place in Xcode

https://github.com/kareman/FootlessParser/commit/9e43f2f3d284c960c011aa2eecb646df4eb75d15

The file structure of Xcode projects looks better, especially on GitHub, if the code for the product itself is in “source” and the test code in “tests”. It’s better than just dumping all Xcode targets in the root folder. Especially for this project, as it will have test targets for both unit tests, speed tests and integration tests.

Share the only scheme.

https://github.com/kareman/FootlessParser/commit/4eac262ad46fdb846b968d2bb8d5936a3c26d941

Schemes are not shared by default in Xcode. It’s best to share this now since you’re bound to be making changes to it in the future, and if it’s not shared no one else will receive those changes. While you will be merrily coding along, assuming what you see everyone else sees too.

Add license.

https://github.com/kareman/FootlessParser/commit/4ee0dda754593e4355e348d43c7dce4869d00ac6

Which licence to release open source code under is of course entirely a matter of preference. Personally I agree most with the Eclipse licence because I would prefer anyone who make any changes to make them public and open source as well. But I also want my open source projects to be available to as many people as possible, and the MIT license is very popular and compatible with most other licences, including GPL. And it is used by all the open source frameworks this project uses. It is also very short, which is always a good thing for legalese text.

Upload to GitHub

After adding some actual code it’s time to share the work with the world. It is easiest to use GitHub for Mac as it both creates the project on GitHub and uploads the code.

Adding an XCode project to Git

When creating a new project in Xcode it is best to leave the “Create Git repository” box unchecked because it will immediately add all files to Git, including those that are specific to you and are of no interest to anyone else. Instead you can run this script from the project folder, which will add only the files that should be under version control:


#!/bin/bash -x

# create the ignore file
cat > .gitignore <<_EOF_
# Xcode
#
.DS_Store
build/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.mode2v3
!default.mode2v3
*.perspectivev3
!default.perspectivev3
xcuserdata
*.xccheckout
*.moved-aside
DerivedData
*.hmap
*.ipa

# CocoaPods
#
# We recommend against adding the Pods directory to your .gitignore. However
# you should judge for yourself, the pros and cons are mentioned at:
# http://guides.cocoapods.org/using/using-cocoapods.html#should-i-ignore-the-pods-directory-in-source-control?
#
# Pods/
_EOF_

git init
git add .
git commit -m 'Initial commit'