Skip to content

Latest commit

 

History

History
199 lines (148 loc) · 6.29 KB

README.md

File metadata and controls

199 lines (148 loc) · 6.29 KB
Raw

Slurp Logo

Build Status Swift Package Manager Compatible Releases

A Swift task runner and file watcher that you can run from your Xcode Workspace or the Command line. Comes with everything you need to build and deploy an iOS app just by running an XCode Scheme. Inspired by Gulp.js.

Contents

Intended Uses

For automating workflows

Build your Slurp Task module as an executable. Run it from your CI server, the command line or Xcode. For example, this code builds and deploys an iOS app to the iTunes App Store:

import Slurp
import SlurpXCTools

let xcBuildConfig = XcodeBuild.Config(...)
let uploadConfig = ApplicationLoader.Config(...)
let slurp = Slurp()
slurp
    .register("buildAndDeploy") {
        return slurp
            |> Pod.Install()
            |> Version(.incrementBuildNumber, all: true)
            |> Version(.setMarketingVersion("1.0.1"), all: true)
            |> XcodeBuild([.archive, .export], config: xcBuildConfig)
            |> ApplicationLoader(.uploadApp, config: uploadConfig)
    }

try! slurp.runAndExit(taskName: "buildAndDeploy")

Monitoring the filesystem for changes, then running tasks

This is useful for development workflows that involve files generated from 3rd party tools (e.g. graphics editors). If you are looking for ways to develop in Swift without using Xcode, this may be useful for running tests and linters automatically also.

import Slurp

let slurp = Slurp()
slurp.watch(paths: ["Tests/**.swift"], recursive: true)
.flatMap { _ in
  return try! slurp.run(taskName: "runTests")
}
.subscribe(onError: { err in
  print(err)
})

RunLoop.main.run() // Keep the task running indefinitely

Installation

  1. $ git clone git@github.com:bitwit/Slurp.git
  2. $ cd Slurp && make
  3. The Slurp CLI will now be installed and the repo copied to ~/.slurp/clone for local reference in your projects

Adding Slurp to your project

In the root of the project:

  1. $ slurp init. This will create a new SlurpTasks package in <project root>/Slurp.
  2. $ slurp edit will open the the SlurpTasks Xcode project, but you can also add this project to your regular Workspace.
  3. $ slurp will run your SlurpTasks executable

Your first slurp task

A basic Sources/SlurpTasks/main.swift file would look like:

import Slurp

let slurp = Slurp()

slurp.register("sayHello", Shell(arguments: ["echo", "hello world"]))

try! slurp.runAndExit(taskName: "sayHello")

Developing and Running in Xcode

When you run your Tasks from XCode it will execute from the build folder. To get around this there are several ways to set the current working directly correctly:

  1. Set it at the top of your main.swift
Slurp.currentWorkingDirectory = "/path/to/app"
  1. Pass it as an environment variable

$ SLURP_CWD=/path/to/app slurp

  1. Change it at any point in the task flow
slurp
    .register("example") {
        return slurp
            |> CWD("~/Development/personal/Slurp")
            |> ...
    }

Note: You can pass this as an environment variable too through SLURP_CWD. This can be set in your task scheme's configuration

This git repo contains an xcworkspace and example app that mimic this suggested structure.

Currently Available Tasks

  • Shell
  • Xcodebuild (xcodebuild)
  • Version (agvtool)
  • ApplicationLoader (altool)
  • Cocoapods (pod)

Writing your own task

There are 3 ways to build your own task:

  1. Simply register an RxSwift Observable

    let myTaskObservable: Observable<Int> = Observable.create { observer in
	observer.onNext(100)
	observer.onCompleted()
	return Disposables.create()
}

slurp
.register("myTask") {
    return myTaskObservable
}

  2. Use the BasicTask class either directly or through inheritance. It can be initialized with either an RxSwift Observable or a callback function with a (Error?, T?) -> Void method signature

    open class BasicTask<T>: SlurpTask {

  public init(observable: Observable<T>)

  public convenience init(asyncTask: @escaping ( (Error?, T?) -> Void ) -> Void) 
}

  3. Make your class conform to the SlurpTask protocol:

    public protocol SlurpTask {

    associatedtype OutputType

    func onPipe<U>(from input: U) -> Observable<OutputType>
}

Note: onPipe<U>'s generic format is mostly there for posterity since all current tasks do not consume from the previous task's output. This may change in the future, particularly for file system management tasks

Options 2 & 3, which involve conforming to SlurpTask, are eligible for piping to and from other tasks.

The Pipe Operator

For convenience and cleanliness Slurp uses the pipe operator i.e |>. This is a substitute for calling func pipe(to: SlurpTask).

return slurp
            |> XcodeBuild([.archive, .export], config: xcBuildConfig)
            |> ApplicationLoader(.uploadApp, config: uploadConfig)

Is equivalent to

return slurp
            .pipe(to: XcodeBuild([.archive, .export], config: xcBuildConfig))
            .pipe(to: ApplicationLoader(.uploadApp, config: uploadConfig))

Roadmap

Some future desires/plans. Requests and contributions very welcome!

  • Solidify API
  • Dry run flag
  • Prettier output
  • Make more tasks. Personal wish list:
    • Slack API task
    • File system tasks
    • AWS S3 Management
    • AWS Cloudfront
    • Download Dsyms
    • Upload Dsyms to New Relic (and others)

Feedback

Feel free to open an issue or find me on twitter