Step by step guide on using Carthage dependency manager

I just used Carthage dependency manager for the first time. I followed this guide on raywenderlich.com, but there seems to be a missing step which causes a runtime crash. After some searching and troubleshooting, I eventually got it to work. I just want to document here for future reference and for anyone who might have running to the same problem.

• Download the latest Carthage pkg and of course run it to install it.
• Create a new Xcode project and save it (I call my app SnapAuth)
• Launch a terminal (I use iTerm2)
• cd to the directory of the project (which is where the xcodeproj file is)
• Type touch Cartfile
• Add this following line in the Cartfile file.

github "Alamofire/Alamofire"

• Type the command below:

carthage update --platform iOS

• This takes a few minutes, and eventually you’ll see something like

• In the terminal, type

ls Carthage/Build/iOS

and note the file Alamofire.framework will be listed as we will use it shortly.

• Back to Xcode, we want to add the above file Alamofire.framework to the Linked Frameworks and Libraries of the project. Do so by dropping the Alamofire.framework file from a Finder window into the drop target (where it says “Add Files here”).

• Switch to Build Phases tab.
• Click on + icon and select New run script phase
• Expand the Run Script section. Once expanded, in the Shell text field, type

/usr/local/bin/carthage copy-frameworks

Click on the + button under Input Files and type

$(SRCROOT)/Carthage/Build/iOS/Alamofire.framework

• Check both checkboxes as shown in the picture above.
• Now, do a Product->Build. This will succeed.
• Run the app and it will fail. The error says

dyld: Library not loaded: @rpath/Alamofire.framework/Alamofire
Referenced from:...
Reason: image not found

This is what I was talking about. There seems to be a missing step in the guide on raywenderlich.com site. This might be due to an older version of Xcode or some other reasons. Anyway, to fix the problem, here is the missing step:

• Navigate to Build Phases tab
• Click on the + button and select New Copy Files Phase
• Expand the Copy Files section.
• For Destination dropdown, select Frameworks.
• Drop the Alamofire.framework file in the drop target (where it says “Add Files here”). When prompted, check the Destination: Copy items if needed checkbox.
• Also make sure the checkbox Code Sign On Copy is checked. Leave the Copy only when installing box unchecked.

• Now the app will run without crashing. If I need to add one more dependency, I would just add a new line in the Cartfile file. Let’s say I want to add the SnapKit dependency. My Cartfile file now looks like

github “Alamofire/Alamofire”
github “SnapKit/SnapKit” >= 0.15.0

• Run this command again

carthage update --platform iOS

The file SnapKit.framework will be generated. Confirm by typing this ls command in the terminal

ls Carthage/Build/iOS

Now, there are 3 places in Xcode to edit.

• In the General tab, Linked Frameworks and Libraries section, add the SnapKit.framework as shown below:

• In the Build Phases tab, Run Script section and Copy Files section:

That’s all. Write your code as normal. Import Alamofire and SnapKit in your code and use them wherever it makes sense, and the app will continue to work without crashing.