My Xcode Project Structure for Open Source Project

Recently I decided to make some of my custom made iOS controls open source. Thus I fire up my Xcode, select “Create a new Xcode project” and then I am stuck… What project template should I choose? I will have to make my custom control a Cocoa Touch Framework, but at the same time I also need an example app for testing as well as showcasing my cool custom control after published to Github.

Apparently we can use CocoaPods command: pod lib create to generate an Xcode project with proper structure and start working on it right away. However I would like to have more flexibility and more control on the project structure, thus I decided to setup my own project manually.

After some research and trial & error, I have come up with a project structure which is suitable for any kind of open source projects. Thus I would like to share this to anyone who are interested, and hopefully this can provide a good starting point to other developers that plan to start their first open source project. 😃

Creating Necessary Projects

Let’s get started by creating the Xcode projects that you need. The first project will be the project that contain all your open source project source code. Make sure you select “Cocoa Touch Framework” as your desire project template. For demo purpose, let’s name the project “MyOpenSource”.

Select “Cocoa Touch Framework” as you open source project template

After finish creating project for your open source project source code, you will need to create another project for your example app. This time select “Single View Application” as the project template and name it “MyOpenSourceExample

Select “Single View Application” as you open source project template

Creating Workspace for the Example Project

Right now you should be able to see two Xcode projects have been created.

Created Xcode projects

Double click MyOpenSourceExample.xcodeproj to launch the example project and drag MyOpenSource.xcodeproj from finder into the example project as shown in the screenshot below.

Drag MyOpenSource.xcodeproj from finder into the example project

Xcode will prompt you to save the example project in a new workspace. What is workspace? According to Apple documentation:

A workspace is an Xcode document that groups projects and other documents so you can work on them together.
Save example project in new workspace

Click “Save” to proceed. Name the workspace MyOpenSourceExample and save it at the root folder.

Workspace file saved at root folder

You can now close your example project and launch the workspace you just saved. Notice that Xcode now showing both MyOpenSource and MyOpenSourceExample in the project navigator.

Both project in Xcode project navigator

Linking up Framework

In order for MyOpenSourceExample to be able to access your code in MyOpenSource, you will have to link MyOpenSource framework to the example project.

Select MyOpenSourceExample in project navigator and open the “Build Phases” tab. Expand the “Link Binary With Libraries” section, click on “+” and select MyOpenSource.framework.

Linking “MyOpenSource.framework” to example project

After that, open the “General” tab, expand the “Embedded Binaries” section, click on “+” and select MyOpenSource.framework in MyOpenSource project.

Embed “MyOpenSource.framework” to example project

Lastly to check whether you have linked the framework correctly, add import MyOpenSource to AppDelegate.swift and build the MyOpenSourceExample project. You should be able to build the project without any error. ✅

That’s it! The workspace is now ready and you can start adding code to your open source project and test your open source framework using the example project.

Thanks 🙏

Thank you for taking your precious time to read this article, hopefully it helps you to get started on your first open source project. I have used this project structure for both of my open source projects, if you are interested, feel free to checkout KSFacebookButton and KSImageCarousel.

Make sure you hit the 👏 button if you like this article. Feel free to drop your comment or question below.

For those who interested, here’s my LinkedIn and Twitter.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.