search

adamwaite / iOS-Build-Kit

☠️ BuildKit is a modular command line interface for automating iOS project builds. Bundled build tasks include: Increment app version • Xcode build • Overlay version number on icon files • Run unit tests • Create .ipa artefact.
MIT License
568 stars 54 forks source link

readme

iOS BuildKit

BuildKit is a modular command line interface for automating iOS project builds. BuildKit aims to relieve you from the pain of configuring continuous integration environments and build processes.

💀 BuildKit is no longer maintained. Fastlane does everything BuildKit does, and much more. It was useful at the time, and it a lot of fun to write, but it's behind the times. Thanks to all contributors!

Bundled build tasks include:

BuildKit is distributed as a Ruby gem with an executable that can be launched either in a continuous integration server environment or on your development machine. The process is configured with a simple YAML file that describes the tasks to run and your project-specific options. This means that you can tailor the build process to meet your requirements.

It's compatible with the iOS7 and iOS8 SDK with Objective-C and Swift projects.

Version: 0.0.6

demo-vid

Dependencies

Installation

After the dependencies have been installed, BuildKit can be installed with:

gem install ios_build_kit

Usage

BuildKit is launched from a command line environment with:

buildkit

Pass a configuration file to BuildKit with:

buildkit your-config-file.yml

Configuration Files

The configuration file describes three things:

  1. Task modules to run (and task-specific options)
  2. Project configuration
  3. User preferences

An example configuration file:

:tasks:
  :increment_version:
    :run: true
    :options:
  :decorate_icon:
    :run: true
    :options:
  :xcode_build:
    :run: true
    :options:
      :log: true
      :clean: true
  :run_tests:
    :run: false
    :options:
        :log: true
  :create_ipa:
    :run: true
    :options:
        :log: true

:configuration:
  :app_name: "BuildKit"
  :workspace: "BuildKit.xcworkspace"
  :info_plist: "BuildKit/BuildKit-Info.plist"
  :build_configuration: "Release"
  :scheme: "BuildKit"
  :sdk: "iphoneos"
  :provisioning_profile: "Provisioning/BuildKitTest.mobileprovision"
  :code_sign: "iPhone Distribution: Alpaca Labs"
  :icon_dir: "BuildKit/Icon/"
  :build_dir: "Builds"

:preferences:
  :reports: "Reports"

Setting Tasks

The :tasks: symbol is used to define what tasks you would like your process to run. If :run: is set to true on a particular task then that task will be executed as part of the build process. Setting :run: to false will mean that the task is skipped (note that some tasks depend on others, and may cause a graceful failure). In the examle above all tasks but for run_tests will be executed.

The tasks will be run in the order that they appear in the list. It's recommended to follow the order shown in the example as they've been ordered to provide the best value to the process. In the example:

  1. The build version is incremented with increment_version
  2. The newly incremented version is rendered on the app icon with decorate_icon
  3. Lastly xcode_build and create_ipa are run to build and create an ipa, which if installed on a device, will have the version number overlayed on the icon.

Anything passed with the :options: symbol will be provided as an option. For example, taking the example configuration file above the :log: option on the run_tests task is set to true so the test output will be printed to the CLI.

The Tasks section in this README describes all of the options available to each task.

Setting Project Configuration

To run the task modules successfully requires some project-specific configuration, this is done under the :configuration: symbol.

Note: if some required configuration has not been provided, or an invalid location has been provided for an option that requires a path, then BuildKit will gracefully fail.

Setting User Preferences

BuildKit can be configured to suit your own preference too. This is done under the :preferences: symbol. For example, to switch on build report generation set the :reports: symbol to true. User preferences are further described in the User Preferences section of this README.

Build Tasks

BuildKit comes packaged with the following task modules:

increment_version

Increments the build version number in the Info-plist.

Requires configuration:

decorate_icon

Duplicates your app icon files and renders the version number on top (incremented with increment_version or not).

decorate_icon-example

Decorate icon requires some convention for optimal usage:

  1. The app icon files should be contained in a dedicated directory of their own.
  2. Drop the icon directory in to Xcode as a folder reference rather than a group.
  3. Set the icon files in your Info-plist as:
<key>CFBundleIcons</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>CONTAININGFOLDER/Decorated-ICONFILENAME</string>
            <string>CONTAININGFOLDER/Decorated-ICONFILENAME</string>
            <string>CONTAININGFOLDER/Decorated-ICONFILENAME</string>
        </array>
    </dict>
</dict>

If you're unsure check the example project.

Requires configuration:

xcode_build

Builds the project (with optional clean before build).

Options:

Requires configuration:

Note: Special thanks to @supermarin for making the output beautiful with his xcpretty gem (same for run_tests)

run_tests

Runs unit tests. XCTest, Kiwi and Specta/Expecta are all supported

Options:

Requires configuration:

create_ipa

Creates an .ipa build artefact and drops it in build directory specified in the config file.

Options:

Requires previous tasks:

Requires configuration:

User Preferences

BuildKit includes some user preferences that can be enabled under the :preferences: symbol of a config file.

User Preferences: Create Reports

Set :reports: to a directory in your config file to create a JSON report containing the project configuration, build time, build outputs and test outputs after a BuildKit run has completed.

Leaving the :reports: preference blank will skip report generation.

Examples

An example workspace has been included in the repo if you want to try it out. You may need to change the paths in the build_config.yml configuration file first and run a pod install.

Roadmap

Lots of plans for BuildKit:

Contributing

All pull requests welcome! Please ensure that all existing RSpec specs pass, and that any new features are covered with specs. Please keep the README up to date. Run specs from the root directory with rspec spec.

Contact

@adamwaite

Build Errors

And finally, a list of cryptic build error annoyances and how to deal with them:

License

Copyright (c) 2014 Adam Waite. All rights reserved.

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.