• Stars
    star
    7,655
  • Rank 4,988 (Top 0.1 %)
  • Language
    Swift
  • License
    MIT License
  • Created almost 8 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Meta-programming for Swift, stop writing boilerplate code.

macOS 13 ubuntu x86_64

docs Version License Platform

In-Depth Sourcery guide is covered as part of my SwiftyStack engineering course.

Sourcery Pro provides a powerful Stencil editor and extends Xcode with the ability to handle live AST templates: available on Mac App Store

Overview.mp4

Learn more about Sourcery Pro

Sourcery is a code generator for Swift language, built on top of Apple's own SwiftSyntax. It extends the language abstractions to allow you to generate boilerplate code automatically.

It's used in over 40,000 projects on both iOS and macOS and it powers some of the most popular and critically-acclaimed apps you have used (including Airbnb, Bumble, New York Times). Its massive community adoption was one of the factors that pushed Apple to implement derived Equality and automatic Codable conformance. Sourcery is maintained by a growing community of contributors.

Try Sourcery for your next project or add it to an existing one -- you'll save a lot of time and be happy you did!

TL;DR

Sourcery allows you to get rid of repetitive code and create better architecture and developer workflows. An example might be implementing Mocks for all your protocols, without Sourcery you will need to write hundreds lines of code per each protocol like this:

class MyProtocolMock: MyProtocol {

    //MARK: - sayHelloWith
    var sayHelloWithNameCallsCount = 0
    var sayHelloWithNameCalled: Bool {
        return sayHelloWithNameCallsCount > 0
    }
    var sayHelloWithNameReceivedName: String?
    var sayHelloWithNameReceivedInvocations: [String] = []
    var sayHelloWithNameClosure: ((String) -> Void)?

    func sayHelloWith(name: String) {
        sayHelloWithNameCallsCount += 1
        sayHelloWithNameReceivedName = name
        sayHelloWithNameReceivedInvocations.append(name)
        sayHelloWithNameClosure?(name)
    }

}

and with Sourcery ?

extension MyProtocol: AutoMockable {}

Sourcery removes the need to write any of the mocks code, how many protocols do you have in your project? Imagine how much time you'll save, using Sourcery will also make every single mock consistent and if you refactor or add properties, the mock code will be automatically updated for you, eliminating possible human errors.

Sourcery can be applied to arbitrary problems across your codebase, if you can describe an algorithm to another human, you can automate it using Sourcery.

Most common uses are:

But how about more specific use-cases, like automatically generating all the UI for your app BetaSetting? you can use Sourcery for that too

Once you start writing your own template and learn the power of Sourcery you won't be able to live without it.

How To Get Started

There are plenty of tutorials for different uses of Sourcery, and you can always ask for help in our Swift Forum Category.

Quick Mocking Intro & Getting Started Video

You can also watch this quick getting started and intro to mocking video by Inside iOS Dev:

Watch the video

Installation

  • Binary form

    Download the latest release with the prebuilt binary from release tab. Unzip the archive into the desired destination and run bin/sourcery

  • Homebrew

    brew install sourcery

  • CocoaPods

    Add pod 'Sourcery' to your Podfile and run pod update Sourcery. This will download the latest release binary and will put it in your project's CocoaPods path so you will run it with $PODS_ROOT/Sourcery/bin/sourcery

    If you only want to install the sourcery binary, you may want to use the CLI-Only subspec: pod 'Sourcery', :subspecs => ['CLI-Only'].

  • Mint

    mint run krzysztofzablocki/Sourcery

  • Building from Source

    Download the latest release source code from the release tab or clone the repository and build Sourcery manually.

    • Building with Swift Package Manager

      Run swift build -c release in the root folder and then copy .build/release/sourcery to your desired destination.

      Note: JS templates are not supported when building with SPM yet.

    • Building with Xcode

      Run xcodebuild -scheme sourcery -destination generic/platform=macOS -archivePath sourcery.xcarchive archive and export the binary from the archive.

  • SPM (for plugin use only) Add the package dependency to your Package.swift manifest from version 1.8.3.

.package(url: "https://github.com/krzysztofzablocki/Sourcery.git", from: "1.8.3")
  • pre-commit Add the dependency to .pre-commit-config.yaml.
- repo: https://github.com/krzysztofzablocki/Sourcery
  rev: 1.9.1
  hooks:
  - id: sourcery

Documentation

Full documentation for the latest release is available here.

Linux Support

Linux support is described on this page.

Usage

Running the executable

Sourcery is a command line tool; you can either run it manually or in a custom build phase using the following command:

$ ./bin/sourcery --sources <sources path> --templates <templates path> --output <output path>

Note: this command differs depending on how you installed Sourcery (see Installation)

Swift Package command

Sourcery can now be used as a Swift package command plugin. In order to do this, the package must be added as a dependency to your Swift package or Xcode project (see Installation above).

To provide a configuration for the plugin to use, place a .sourcery.yml file at the root of the target's directory (in the sources folder rather than the root of the package).

Running from the command line

To verify the plugin can be found by SwiftPM, use:

$ swift package plugin --list

To run the code generator, you need to allow changes to the project with the --allow-writing-to-package-directory flag:

$ swift package --allow-writing-to-package-directory sourcery-command

Running in Xcode

Inside a project/package that uses this command plugin, right-click the project and select "SourceryCommand" from the "SourceryPlugins" menu group.

⚠️ Note that this is only available from Xcode 14 onwards.

Command line options

  • --sources - Path to a source swift files or directories. You can provide multiple paths using multiple --sources option.
  • --templates - Path to templates. File or Directory. You can provide multiple paths using multiple --templates options.
  • --force-parse - File extensions of Sourcery generated file you want to parse. You can provide multiple extension using multiple --force-parse options. (i.e. file.toparse.swift will be parsed even if generated by Sourcery if --force-parse toparse). Useful when trying to implement a multiple phases generation. --force-parse can also be used to process within a sourcery annotation. For example to process code within sourcery:inline:auto:Type.AutoCodable annotation you can use --force-parse AutoCodable
  • --output [default: current path] - Path to output. File or Directory.
  • --config [default: current path] - Path to config file. File or Directory. See Configuration file.
  • --args - Additional arguments to pass to templates. Each argument can have an explicit value or will have implicit true value. Arguments should be separated with , without spaces (i.e. --args arg1=value,arg2). Arguments are accessible in templates via argument.name
  • --watch [default: false] - Watch both code and template folders for changes and regenerate automatically.
  • --verbose [default: false] - Turn on verbose logging
  • --quiet [default: false] - Turn off any logging, only emit errors
  • --disableCache [default: false] - Turn off caching of parsed data
  • --prune [default: false] - Prune empty generated files
  • --version - Display the current version of Sourcery
  • --help - Display help information
  • --cacheBasePath - Base path to the cache directory. Can be overriden by the config file.
  • --buildPath - Path to directory used when building from .swifttemplate files. This defaults to system temp directory
  • --hideVersionHeader [default: false] - Stop adding the Sourcery version to the generated files headers.

Configuration file

Instead of CLI arguments, you can use a .sourcery.yml configuration file:

sources:
  - <sources path>
  - <sources path>
templates:
  - <templates path>
  - <templates path>
forceParse:
  - <string value>
  - <string value>
output:
  <output path>
args:
  <name>: <value>

Read more about this configuration file here.

Issues

If you get an unverified developer warning when using binary zip distribution try: xattr -dr com.apple.quarantine Sourcery-1.1.1

Contributing

Contributions to Sourcery are welcomed and encouraged!

It is easy to get involved. Please see the Contributing guide for more details.

A list of contributors is available through GitHub.

To clarify what is expected of our community, Sourcery has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and articulates my values well. For more, see the Code of Conduct.

Sponsoring

If you'd like to support Sourcery development you can do so through GitHub Sponsors or Open Collective, it's highly appreciated 🙇‍

If you are a company and would like to sponsor the project directly and get it's logo here, you can contact me directly

Sponsors

Bumble Inc

Airbnb Engineering

License

Sourcery is available under the MIT license. See LICENSE for more information.

Attributions

This tool is powered by

Thank you! to:

  • Mariusz Ostrowski for creating the logo.
  • Artsy Eidolon team, because we use their codebase as a stub data for performance testing the parser.
  • Olivier Halligon for showing me his setup scripts for CLI tools which are powering our rakefile.
  • JP Simard for creating SourceKitten that originally powered Sourcery and was instrumental in making this project happen.

Other Libraries / Tools

If you want to generate code for asset related data like .xib, .storyboards etc. use SwiftGen. SwiftGen and Sourcery are complementary tools.

Make sure to check my other libraries and tools, especially:

  • KZPlayground - Powerful playgrounds for Swift and Objective-C
  • KZFileWatchers - Daemon for observing local and remote file changes, used for building other developer tools (Sourcery uses it)

You can follow me on Twitter for news/updates about other projects I am creating.

More Repositories

1

LifetimeTracker

Find retain cycles / memory leaks sooner.
Swift
3,144
star
2

Playgrounds

Better playgrounds that work both for Objective-C and Swift
Objective-C
2,633
star
3

Inject

Hot Reloading for Swift applications!
Swift
2,127
star
4

Swift-Macros

A curated list of awesome Swift Macros
Swift
2,120
star
5

Bootstrap

iOS project bootstrap aimed at high quality coding.
Objective-C
2,047
star
6

LineDrawing

Beatiful and fast smooth line drawing algorithm for iOS - as seen in Foldify.
Objective-C
1,288
star
7

Difference

Simple way to identify what is different between 2 instances of any type. Must have for TDD.
Swift
1,217
star
8

PropertyMapper

Property mapping for Objective-C iOS apps.
Objective-C
1,124
star
9

KZFileWatchers

A micro-framework for observing file changes, both local and remote. Helpful in building developer tools.
Swift
1,078
star
10

LinkedConsole

Clickable links in your Xcode console, so you never wonder which class logged the message.
Swift
931
star
11

Traits

Modify your native iOS app in real time.
Swift
904
star
12

IconOverlaying

Build informations on top of your app icon.
Shell
650
star
13

crafter

Crafter - Xcode project configuration CLI made easy.
Ruby
547
star
14

Strongify

Strongify is a 1-file µframework providing a nicer API for avoiding weak-strong dance.
Swift
444
star
15

KZNodes

Have you ever wonder how you could make Origami like editor in 1h ?
Objective-C
336
star
16

SFObservers

NSNotificationCenter and KVO auto removal of observers.
Objective-C
307
star
17

AutomaticSettings

Data driven settings UI generation.
Swift
302
star
18

CCNode-SFGestureRecognizers

Adding UIGestureRecognizers to cocos2d, painless.
Objective-C
202
star
19

DetailsMatter

Objective-C
199
star
20

Pinch-to-reveal

Pinch to reveal animation transition built with Layer masking, as seen in boeing app for iPad.
Objective-C
192
star
21

ViewModelOwners

Protocols that help make your MVVM setup more consistent
Swift
143
star
22

KZAsserts

Asserts on roids, test all your assumptions with ease.
Objective-C
100
star
23

OhSnap

Reproduce bugs your user saw by capturing and replaying data snapshots with ease.
Swift
89
star
24

Versionable

Migration for `Codable` objects.
Swift
83
star
25

SFContainerViewController

UIViewControllers containment predating Apple implementation. Works in both 4.x and 5.x iOS, no memory or hierarchy issues.
Objective-C
82
star
26

Swift-Observable

Native KVO like behaviour build in Swift.
Swift
64
star
27

BehavioursExample

Objective-C
58
star
28

SourceryWorkshops

Swift
45
star
29

Learn-iOS-GameDev-Level-0

Teeter clone accompanying tutorial at http://merowing.info/2013/04/learn-ios-game-dev-level-0/
Objective-C
24
star
30

XibReferencing

Simple category and sample showing how you can reference one Xib view from another
Objective-C
20
star
31

KZImageSplitView

Objective-C
17
star
32

NSObject-SFExecuteOnDealloc

A simple category on NSObject that allows you to execute block when object is deallocated
Objective-C
17
star
33

jenkins_jobs_to_statusboard

Ruby script that generates html table for embedding in StatusBoard by Panic http://panic.com/statusboard/
Ruby
15
star
34

SourceryPro-Feedback

Repository for discussing https://merowing.info/sourcery-pro/
12
star
35

krzysztofzablocki

2
star
36

krzysztofzablocki.github.io

Blog
HTML
2
star
37

starter-hugo-academic

Jupyter Notebook
1
star