A Rakefile to build iOS projects
Ruby Objective-C
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Builder Test.xcodeproj
Builder Test.xcworkspace
Builder Test
Builder TestTests
rakelib
.gitignore
.ruby-version
Gemfile
Gemfile.lock
Makefile
Podfile
Podfile.lock
README.md
Rakefile

README.md

xcrake

A Rakefile to build iOS projects. Get the latest here. If you're having issues with the setup and are stuck having to use sudo or are unable to install certain gems, please read this in order to setup a good ruby / rake / (cocoapods) environment.

Features

  • Builds projects or workspaces
  • Simple YAML configuration file
  • Supports TestFlight uploading
  • Re-signs a single .app file for all generated ipas
  • Can easily be run locally and remotely for easy debugging
  • Installs committed provisioning profiles for building
  • Can resign using committed provisioning profiles without installing the profile
  • Supports using custom build tools (like xctool)
  • Verifies signing certificates (Are they revoked?)

Requirements

Ruby

xcrake is known to work best using ruby 2.0.0, though it should also work fine on any stronger version as well.

Gems

xcrake requires the following gems listed in this example Gemfile

source 'https://rubygems.org'

gem 'cocoapods', '~> 0.34.4'
gem 'rest-client', '~> 1.7.2'
gem 'plist', '~> 3.1.0'
gem 'rake', '~> 10.3.2'
gem 'wtapack', '~> 1.0.6'
gem 'xcpretty', '~> 0.1.5'

wtapack

This gem requires Xcode 6 or higher to build, so it requires Mac OS X Mavericks or higher as well.

Usage

Tasks

The tasks that the Rakefile is able to perform and generated based off of your config file. To see a list of all possible tasks and their description, run bundle exec rake --tasks. A sample output would be:

xcrake version: 1.0.0
rake .xcrake                            # Create build output folder
rake artifacts                          # Create artifacts output folder
rake artifacts/Green-release.app        # Create artifacts/Green-release.app
rake artifacts/Red-release.app          # Create artifacts/Red-release.app
rake artifacts/green.ipa                # Build green
rake artifacts/red.ipa                  # Build red
rake clean                              # Cleans build folder
rake config:create                      # Create template xcrake.config file
rake debug:print_environment            # Prints shell environment variables
rake testflight:all                     # Upload all builds to TestFlight
rake testflight:green                   # Upload green to TestFlight
rake testflight:red                     # Upload red to TestFlight

General Use Case

  • Add .xcrake/ and artifacts to your .gitignore file
  • Copy the Rakefile into your projects directory
    • Get the latest here. For instructions on building the Rakefile yourself, read Building
  • Ensure that your Gemfile exists and includes all required gems. Here's an example Gemfile
  • Run bundle install to ensure all gems have been installed.
  • Run bundle exec rake config:create to create a template xcrake.config file.
    • The template xcrake.config contains all the keys needed to build a build. If you're having trouble with the YAML, read up on it here or read a TL;DR of the format.
  • Run bundle exec rake. If everything goes right you'll end up with a new artifacts directory in your project which contains
    1. SchemeName-ConfigurationName.app the .app file for your project
    2. SchemeName-ConfigurationName.app.dSYM.zip the dSYM for the build (zipped)
    3. BuildName.ipa your app signed and packaged with the WillowTree In-House Certificate
    4. Any other .ipas for other specified configurations

The xcrake.config File

# build_profile: # Wildcard profile to use for building binaries
# build_signing_identity: # Signing identity SHA1 that goes with the above profile
builds:
  -
    name: # Name for built ipa
    scheme: # Scheme name to build
    bundle_id: # Bundle id to set in info plist
    provisioning_profile: # UUID of provisioning profile to sign with
    signing_identity: # Signing identity name
    signing_identity_SHA1: # Signing identity SHA1
    configuration: # Build configuration to use
    # extensions: # Comma separated list of extensions, no spaces, quoted
    # <extension name>: # Provisioning profile for extension named <extension name>
    # <next extension name>: # see above
    # <more extensions…>
    # testflight_team_token: # Team token for TestFlight uploads
    # testflight_api_token: # API token for TestFlight uploads
    # testflight_distribution_lists: # Distribution list for TestFlight uploads
    # testflight_notify: # true or false
    # testflight_notes: # release notes
    # display_name: # Name displayed on device home screen
# artifacts_path: # Custom path for built ipa / app / dsym files
# build_path: # Custom path for temporary build files
# profiles_path: # Custom path for provisioning profiles
# build_tool: # Custom build tool to use (for example xctool)
# additional_build_options: # Options to be used during build
# xcpretty: # boolean to turn on xcpretty to make pretty output
  • If the provisioning profile exists in profiles_path, it will be install or used from there as needed
  • The signing_identity_SHA1 can be found by right clicking the certificate in keychain and clicking "get info".
  • A template xcrake.config file can be generated by running rake config:create

Setting up on TeamCity

  • Create a new Build Configuration
  • Set Artifact Paths to artifacts/**
  • Add your Version Control Settings
  • Add Bundle Install Build Step
    • Add a Command Line Build Step
    • Name build step Bundle Install
    • Run Custom Script bundle install
  • Add Pod Install Build Step (for those not commiting their cocoapods stuff)
    • Add a Command Line Build Step
    • Name build step Pod Install
    • Run Custom Script bundle exec pod install
  • Add Rake Build Step
    • Add a Rake Build Runner Step
    • Name build step Rake Build
    • Make sure bundle exec checkmark under Bundler is checked
    • If you want verbose information check Track invoke/execute stages under Debug
    • Make sure all Attached Reporters are unchecked under Tests Reporting
  • Add a Rake Build Step for TestFlight (Optional)
    • Add a Rake Build Runner Step
    • Name build step Testflight
    • For Rake tasks: put testflight:all or testflight:buildname depending on which builds you want to submit to TestFlight
    • Make sure bundle exec checkmark under Bundler is checked
    • If you want verbose information check Track invoke/execute stages under Debug
    • Make sure all Attached Reporters are unchecked under Tests Reporting
  • Make sure that it's running on an Xcode 5 capable server with bundler and libxml2 installed
  • If the environment variable BUILD_NUMBER is set during a build, it will be appended to the CFBundleVersion. Build servers like TeamCity are able to set this for you. If you'd like to set it yourself manually, you can pass it into the Rakefile by running rake BUILD_NUMBER=2

Building

To build the Rakefile

# clone the git repo
git clone https://github.com/willowtreeapps/xcrake.git

# change directory into the cloned project
cd xcrake

# running make will execute the Makefile
# this will create build/Rakefile
make

You can now copy xcrake/build/Rakefile into your projects directory.

Debugging / Development

To make the development process easier, you can symlink the Rakefile built by make in your projects directory. Running make after making changes to xcrake/Rakefile or xcrake/rakelib/*.rake will cause xcrake/build/Rakefile to be rebuilt. If you'd rather not have to run make after making changes, you can symlink xcrake/Rakefile and xcrake/rakelib in your projects directory.

# To symlink the built Rakefile
ln -s /path/to/xcrake/build/Rakefile /path/to/MyProject/

# To symlink without having to rebuild
ln -s /path/to/xcrake/Rakefile /path/to/MyProject/
ln -s /path/to/xcrake/rakelib /path/to/MyProject/

Do keep in mind that when committing to be built on the build server, you'll need the built Rakefile in your projects directory- not the symlinks.

Special Thanks

License (MIT)

Copyright (c) 2014 WillowTree Apps

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Testimonials

  • It's just fabulous - Matt Jones
  • Incredibly easy - Jeff Gordan