Swiftpack.co - Package - jpsim/SourceKitten

SourceKitten

An adorable little framework and command line tool for interacting with SourceKit.

SourceKitten links and communicates with sourcekitd.framework to parse the Swift AST, extract comment docs for Swift or Objective-C projects, get syntax data for a Swift file and lots more!

Azure Pipelines

Installation

Building SourceKitten requires Xcode 10 or later or a Swift 4.2 toolchain or later with the Swift Package Manager.

SourceKitten typically supports previous versions of SourceKit.

Homebrew

Run brew install sourcekitten.

Swift Package Manager

Run swift build in the root directory of this project.

Xcode (via Make)

Run make install in the root directory of this project.

Package

Download and open SourceKitten.pkg from the releases tab.

Command Line Usage

Once SourceKitten is installed, you may use it from the command line.

$ sourcekitten help
Available commands:

   complete    Generate code completion options
   doc         Print Swift or Objective-C docs as JSON
   format      Format Swift file
   help        Display general or command-specific help
   index       Index Swift file and print as JSON
   request     Run a raw sourcekit request
   structure   Print Swift structure information as JSON
   syntax      Print Swift syntax information as JSON
   version     Display the current version of SourceKitten

How is SourceKit resolved?

SourceKitten searches for SourceKit in the following order:

  • $XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
  • $TOOLCHAIN_DIR
  • xcrun -find swift
  • /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
  • /Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
  • ~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
  • ~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

On Linux, SourceKit is expected to be located in /usr/lib/libsourcekitdInProc.so or specified by the LINUX_SOURCEKIT_LIB_PATH environment variable.

Projects Built With SourceKitten

  • SwiftLint: A tool to enforce Swift style and conventions.
  • Jazzy: Soulful docs for Swift & Objective-C.
  • Sourcery: Meta-programming for Swift, stop writing boilerplate code.
  • SwiftyMocky: Framework for mock generation.
  • SourceKittenDaemon: Swift Auto Completions for any Text Editor.
  • SourceDocs: Command Line Tool that generates Markdown documentation from inline source code comments.
  • Cuckoo: First boilerplate-free mocking framework for Swift.
  • IBAnalyzer: Find common xib and storyboard-related problems without running your app or writing unit tests.
  • Taylor: Measure Swift code metrics and get reports in Xcode, Jenkins and other CI platforms.
See More
  • https://github.com/appsquickly/TyphoonSwift
  • https://github.com/banjun/bansan
  • https://github.com/Beaver/BeaverCodeGen
  • https://github.com/Ben-G/Meet
  • https://github.com/dfreemanRIIS/ETAMock
  • https://github.com/dostu/SwiftMetric
  • https://github.com/draven-archive/MetaKit
  • https://github.com/geosor/SwiftVisualizer
  • https://github.com/godfreynolan/AgileSwiftTst
  • https://github.com/godfreynolan/CodeCraftsman
  • https://github.com/ilyapuchka/dipgen
  • https://github.com/ilyapuchka/SourceKittenEditorExtension
  • https://github.com/interstateone/Unused
  • https://github.com/ishkawa/DIKit
  • https://github.com/IvanovGeorge/FBAuth
  • https://github.com/jmpg93/NavigatorSwift
  • https://github.com/jpmartha/Pancake
  • https://github.com/jpweber/Kontext
  • https://github.com/KenichiroSato/CatDogTube
  • https://github.com/klundberg/grift
  • https://github.com/kovtun1/DependenciesGraph
  • https://github.com/lvsti/Bridgecraft
  • https://github.com/maralla/completor-swift
  • https://github.com/marcsnts/Shopify-Winter18-Technical
  • https://github.com/momentumworks/Formula
  • https://github.com/nevil/UNClassDiagram
  • https://github.com/norio-nomura/LinuxSupportForXcode
  • https://github.com/paulofaria/swift-package-crawler-data
  • https://github.com/rajat-explorer/Github-Profiler
  • https://github.com/rockbruno/swiftshield
  • https://github.com/S2dentik/Enlight
  • https://github.com/seanhenry/SwiftMockGeneratorForXcode
  • https://github.com/sharplet/swiftags
  • https://github.com/siejkowski/Croupier
  • https://github.com/SwiftKit/CuckooGenerator
  • https://github.com/SwiftKit/Torch
  • https://github.com/SwiftTools/SwiftFelisCatus
  • https://github.com/swizzlr/lux
  • https://github.com/tid-kijyun/XcodeSourceEditorExtension-ProtocolImplementation
  • https://github.com/tjarratt/fake4swift
  • https://github.com/tkohout/Genie
  • https://github.com/tomquist/MagicMirror
  • https://github.com/TurfDb/TurfGen
  • https://github.com/vadimue/AwesomeWeather
  • https://github.com/yonaskolb/Beak
  • https://github.com/zenzz/vs-swifter-server
  • https://github.com/zenzz/zxxswifter-server
  • https://github.com/scribd/Weaver
  • https://github.com/Nonchalant/FactoryProvider

Complete

Running sourcekitten complete --file file.swift --offset 123 or sourcekitten complete --text "0." --offset 2 will print out code completion options for the offset in the file/text provided:

[{
  "descriptionKey" : "advancedBy(n: Distance)",
  "associatedUSRs" : "s:FSi10advancedByFSiFSiSi s:FPSs21RandomAccessIndexType10advancedByuRq_S__Fq_Fqq_Ss16ForwardIndexType8Distanceq_ s:FPSs16ForwardIndexType10advancedByuRq_S__Fq_Fqq_S_8Distanceq_ s:FPSs10Strideable10advancedByuRq_S__Fq_Fqq_S_6Strideq_ s:FPSs11_Strideable10advancedByuRq_S__Fq_Fqq_S_6Strideq_",
  "kind" : "source.lang.swift.decl.function.method.instance",
  "sourcetext" : "advancedBy(<#T##n: Distance##Distance#>)",
  "context" : "source.codecompletion.context.thisclass",
  "typeName" : "Int",
  "moduleName" : "Swift",
  "name" : "advancedBy(n: Distance)"
},
{
  "descriptionKey" : "advancedBy(n: Self.Distance, limit: Self)",
  "associatedUSRs" : "s:FeRq_Ss21RandomAccessIndexType_SsS_10advancedByuRq_S__Fq_FTqq_Ss16ForwardIndexType8Distance5limitq__q_",
  "kind" : "source.lang.swift.decl.function.method.instance",
  "sourcetext" : "advancedBy(<#T##n: Self.Distance##Self.Distance#>, limit: <#T##Self#>)",
  "context" : "source.codecompletion.context.superclass",
  "typeName" : "Self",
  "moduleName" : "Swift",
  "name" : "advancedBy(n: Self.Distance, limit: Self)"
},
...
]

To use the iOS SDK, pass -sdk and -target arguments preceded by --:

sourcekitten complete --text "import UIKit ; UIColor." --offset 22 -- -target arm64-apple-ios9.0 -sdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS9.0.sdk

Doc

Running sourcekitten doc will pass all arguments after what is parsed to xcodebuild (or directly to the compiler, SourceKit/clang, in the --single-file mode).

Example usage

  1. sourcekitten doc -- -workspace SourceKitten.xcworkspace -scheme SourceKittenFramework
  2. sourcekitten doc --single-file file.swift -- -j4 file.swift
  3. sourcekitten doc --module-name Alamofire -- -project Alamofire.xcodeproj
  4. sourcekitten doc -- -workspace Haneke.xcworkspace -scheme Haneke
  5. sourcekitten doc --objc Realm/Realm.h -- -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd)

Structure

Running sourcekitten structure --file file.swift or sourcekitten structure --text "struct A { func b() {} }" will return a JSON array of structure information:

{
  "key.substructure" : [
    {
      "key.kind" : "source.lang.swift.decl.struct",
      "key.offset" : 0,
      "key.nameoffset" : 7,
      "key.namelength" : 1,
      "key.bodyoffset" : 10,
      "key.bodylength" : 13,
      "key.length" : 24,
      "key.substructure" : [
        {
          "key.kind" : "source.lang.swift.decl.function.method.instance",
          "key.offset" : 11,
          "key.nameoffset" : 16,
          "key.namelength" : 3,
          "key.bodyoffset" : 21,
          "key.bodylength" : 0,
          "key.length" : 11,
          "key.substructure" : [

          ],
          "key.name" : "b()"
        }
      ],
      "key.name" : "A"
    }
  ],
  "key.offset" : 0,
  "key.diagnostic_stage" : "source.diagnostic.stage.swift.parse",
  "key.length" : 24
}

Syntax

Running sourcekitten syntax --file file.swift or sourcekitten syntax --text "import Foundation // Hello World" will return a JSON array of syntax highlighting information:

[
  {
    "offset" : 0,
    "length" : 6,
    "type" : "source.lang.swift.syntaxtype.keyword"
  },
  {
    "offset" : 7,
    "length" : 10,
    "type" : "source.lang.swift.syntaxtype.identifier"
  },
  {
    "offset" : 18,
    "length" : 14,
    "type" : "source.lang.swift.syntaxtype.comment"
  }
]

Request

Running sourcekitten request --yaml [FILE|TEXT] will execute a sourcekit request with the given yaml. For example:

key.request: source.request.cursorinfo
key.sourcefile: "/tmp/foo.swift"
key.offset: 8
key.compilerargs:
  - "/tmp/foo.swift"

SourceKittenFramework

Most of the functionality of the sourcekitten command line tool is actually encapsulated in a framework named SourceKittenFramework.

If you’re interested in using SourceKitten as part of another tool, or perhaps extending its functionality, take a look at the SourceKittenFramework source code to see if the API fits your needs.

Note: SourceKitten is written entirely in Swift, and the SourceKittenFramework API is not designed to interface with Objective-C.

License

MIT licensed.

Github

link
Stars: 1612
Help us keep the lights on

Used By

Total:

Releases

0.24.0 - Jul 22, 2019

Breaking
  • Change Module.init?(spmName:) to Module.init?(spmName:inPath:).
    Norio Nomura

  • SourceKitObjectConvertible now has SourceKitObject parameter requirement instead of sourcekitd_object_t. SourceKitObject isn't publicly initializable (this helps memory management).
    Colton Schlosser

  • Dictionary and Array now conditionally conform to SourceKitObjectConvertible, instead of crashing when using unexpected types.
    Colton Schlosser

Enhancements
  • Add cursorInfoUSR case to the Request.
    Timofey Solonin

  • Add a Dictionary<String, SourceKitRepresentable>.referencedUSRs computed property to retrieve referenced USRs from a SourceKit cursor info response.
    Colton Schlosser

Bug Fixes
  • Fix testCommandantDocsSPM failed on using Swift Package in Xcode 11, because Xcode 11 does not use SRCROOT as current directory on executing tests in Package.swift.
    Norio Nomura

  • Release memory created for sourcekitd requests.
    Colton Schlosser realm/SwiftLint#2812

0.23.2 - May 12, 2019

Breaking
  • None.
Enhancements
Bug Fixes
  • None.

0.23.1 - Apr 29, 2019

Breaking
  • None.
Enhancements
  • None.
Bug Fixes
  • Fix warnings or errors when compiling in Swift 5 language mode.
    Yi Wang JP Simard

0.23.0 - Apr 8, 2019

Breaking
  • None.
Enhancements
  • Introduce XcodeBuildSetting for interacting with project build settings.
    Chris Zielinski

  • Improve module name inference for Module.
    Chris Zielinski

  • Add Swift 5 support. Add new SwiftDeclarationAttributeKind and SwiftDeclarationKind members and make those enums conform to CaseIterable.
    Norio Nomura

Bug Fixes
  • “.swift”-suffixed directory in xcodebuild arguments no longer detected as Swift file.
    Minh Nguyễn #574

  • Fix xcodebuild clean path for new build system and Xcode 10.2.
    John Fairhurst realm/jazzy#1057

  • Pathnames containing shell-escaped characters in xcodebuild arguments no longer prevent documentation generation.
    John Fairhurst

  • swiftc no longer passed as a compiler argument when using doc and the new build system.
    John Fairhurst

0.22.0 - Nov 27, 2018

Breaking
  • SourceKitten now requires Swift 4.2 or higher to build.
    JP Simard
Enhancements
  • Add Request.syntaxTree to get a serialized representation of the file's SwiftSyntax tree.
    JP Simard
Bug Fixes