Building Swift Frameworks

Given at the Swift meetup in San Francisco: http://www.meetup.com/San-Francisco-SWIFT-developers/events/216384462/

Source and image attribution at: https://github.com/hpique/Talks/blob/master/Building%20Swift%20frameworks/Building%20Swift%20frameworks.md

Transcript

1. BUILDING SWIFT FRAMEWORKS @HPIQUE
2. iOS developers can now create dynamic frameworks. Frameworks are a collection of code and resources to encapsulate functionality that is valuable across multiple projects. — New Features in Xcode 6
3. NO MORE HEADER TINKERING!
4. CREATING A NEW FRAMEWORK
5. SWIFT FRAMEWORKS ▸ CAN mix-and-match Objective-C code ▸ CAN import all Objective-C system frameworks (e.g., UIKit) ▸ CAN import C libraries defined as modules (e.g., Dispatch) ▸ CAN'T use other libraries directly (e.g., CommonCrypto) See: Swift and Objective-C in the Same Project
6. WHAT ABOUT STATIC LIBRARIES?
7. Xcode does not support building static libraries that include Swift code. — Xcode 6.0 Beta 5 release notes
8. LET'S TRY ANYWAY! Add a Swift file to a static library and build: error: /Applications/Xcode.app/Contents/Developer/Toolchains/ XcodeDefault.xctoolchain/usr/bin/libtool: unknown option character `X' in: -Xlinker Follow: http://stackoverflow.com/q/24020986/143378
9. USING FRAMEWORKS
10. NO COCOAPODS
11. STEP 1: ADD THE FRAMEWORK AS A SUBPROJECT Drag the framework project into your app project.
12. STEP 2: SET THE FRAMEWORK AS BUILD DEPENDENCY 1. Select your project and then your app target 2. Open the Build Phases panel 3. Expand Target Dependencies 4. Click + and select the framework
13. STEP 3: COPY THE FRAMEWORK DURING BUILD From Build Phases: 1. Click on the + button at the top left of the panel and select New Copy Files Phase 2. Set Destination to Frameworks 3. Click + and select the framework
15. FINALLY import MyFramework
16. ACCESS CONTROL
17. [I]f you are writing a single-target app, you may not need to specify explicit access control levels at all. — The Swift Programming Language
18. BUT YOU'RE WRITING A FRAMEWORK
19. ACCESS LEVELS ▸ Public: accessible everywhere ▸ Internal (default): accessible within any source file from the defining module, but not outside of that module ▸ Private: accessible only within its own defining source file
20. WE KIND* OF HAD THAT ALREADY In Objective-C land: ▸ Public: declared in public headers ▸ Internal: declared in project headers ▸ Private: declared in implementation files * (without enforcing access control)
21. GUIDING PRINCIPLE NO ENTITY CAN BE DEFINED IN TERMS OF ANOTHER ENTITY THAT HAS A LOWER (MORE RESTRICTIVE) ACCESS LEVEL
22. BAD private struct PrivateThing {} struct InternalThing {} public struct PublicThing { let t1 : PrivateThing public let t2 : InternalThing func doSomething(t : PrivateThing) {} public func doSomethingElse(t : InternalThing) {} }
23. EXAMPLE Consider a framework with a public function that fetches a string asynchronously. The function returns a Fetch object that can have a callback for success. let fetch = fetchSomething().onSuccess { println($0) } Let's define the access levels of the Fetch class.
24. class Fetch { var onSuccess : ((String) -> ())? var state : FetchState = FetchState.Pending func onSuccess(onSuccess : ((String) -> ())) -> Self { self.onSuccess = onSuccess switch self.state { case FetchState.Success(let value): onSuccess(value) default: break } return self } func succeed(value : String) { self.state = FetchState.Success(value) self.onSuccess?(value) } }
25. public class Fetch { private var onSuccess : ((String) -> ())? private var state : FetchState = FetchState.Pending public func onSuccess(onSuccess : ((String) -> ())) -> Self { self.onSuccess = onSuccess switch self.state { case FetchState.Success(let value): onSuccess(value) default: break } return self } func succeed(value : String) { self.state = FetchState.Success(value) self.onSuccess?(value) } }
26. NAMESPACING
27. Namespacing is implicit in swift, all classes (etc) are implicitly scoped by the module (Xcode target) they are in. no class prefixes needed — Chris Lattner
29. FRAMEWORK NAMESPACE The framework name is the namespace. When importing a framework types can be accessed implicitly or explicitly.
30. FUN WITH NAMESPACES Consider: A framework FrameworkA that defines a public type Thing. An app MyApp that imports FrameworkA.
31. import FrameworkA var a : FrameworkA.Thing? var t : Thing? The two variables have the same type.
32. import FrameworkA public class Thing { } var a : FrameworkA.Thing? var t : Thing? var t2 : MyApp.Thing? What is the type of t?
33. NAMESPACE CONFLICT What if MyApp also imports a FrameworkB that also defines a public type Thing? import FrameworkA import FrameworkB var a : Thing? We get a nice error.
34. 'Thing' is ambiguous for type lookup in this context let t1 : Thing? = nil ^~~~~ FrameworkA.Thing:1:7: note: found this candidate class Thing ^ FrameworkB.Thing:1:7: note: found this candidate class Thing ^
35. Solution: use fully qualified names. import FrameworkA import FrameworkB public class Thing { } var a : FrameworkA.Thing? var t : Thing? var b : FrameworkB.Thing? t is of type MyApp.Thing.
36. NAMESPACE SHENANIGANS What if FrameworkB also defines a public type named... FrameworkA ?
37. import FrameworkA import FrameworkB var a : FrameworkA.Thing? var b : FrameworkB.Thing? We get a misleading error: 'Thing' is not a member type of 'FrameworkA'
38. Workaround: define a typealias somewhere else in MyApp. import FrameworkA typealias ThingA = Thing Then: import FrameworkA import FrameworkB var a : ThingA? var b : FrameworkB.Thing?
39. BEST PRACTICES Limit the scope* of types whenever possible. Even more so for public types. Don't define a type named like the framework (Haneke oops!). *(THIS IS ALWAYS A GOOD PRACTICE)
40. LIMITING THE SCOPE
41. BAD public static let ErrorDomain = "io.haneke" GOOD public struct HanekeGlobals { public static let ErrorDomain = "io.haneke" } let s = HanekeGlobals.ErrorDomain
42. BAD public enum ScaleMode { case Fill case AspectFit case AspectFill } public struct ImageResizer { public var scaleMode: ScaleMode }
43. GOOD public struct ImageResizer { public enum ScaleMode { case Fill case AspectFit case AspectFill } public let scaleMode: ScaleMode }
44. WHAT ABOUT GENERICS? Generic types can't define static types. This fails to compile: public class NetworkFetcher<T> { public enum ErrorCode : Int { case InvalidData = -400 case MissingData = -401 case InvalidStatusCode = -402 } }
45. Workaround: abuse the globals struct from before. extend HanekeGlobals { public struct NetworkFetcher { public enum ErrorCode : Int { case InvalidData = -400 case MissingData = -401 case InvalidStatusCode = -402 } } } public class NetworkFetcher<T> {}
46. DO EXTENSIONS NEED PREFIXES?
47. PREFIXING EXTENSIONS Extensions of Objective-C types (NSObject subclasses) are categories and as such need prefixes. extension UIImage { public func hnk_hasAlpha() -> Bool { ... } } See: http://stackoverflow.com/q/25567743/143378
48. USING C LIBRARIES
49. IN AN APP PROJECT Easy. Simply import the library in the bridging header: #import <CommonCrypto/CommonCryptor.h> More info: Swift and Objective-C in the Same Project
50. BUT... SWIFT FRAMEWORKS DON'T HAVE A BRIDGING HEADER!
51. WORKAROUND A MODULE MAP
52. import works with modules. So let's define a module for the C library. Using CommonCrypto as an example...
53. STEP 1: DEFINE THE MODULE 1. Create a CommonCrypto directory inside the framework directory 2. Within, create a module.map file module CommonCrypto [system] { header "/Applications/Xcode.app/Contents/Developer/Platforms/ iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator8.0.sdk/us r/include/CommonCrypto/CommonCrypto.h" link "CommonCrypto" export * }
54. STEP 2: SET A IMPORT PATH 1. Go to the framework Build Settings 2. Find Swift Compiler - Search Paths 3. Add the CommonCrypto directory to Import Paths
55. FINALLY import CommonCrypto func MD5(aString : String) -> String { if let data = aString.dataUsingEncoding(NSUTF8StringEncoding) { let result = NSMutableData(length: Int(CC_MD5_DIGEST_LENGTH)) let resultBytes = UnsafeMutablePointer<CUnsignedChar>(result.mutableBytes) CC_MD5(data.bytes, CC_LONG(data.length), resultBytes) let e = UnsafeBufferPointer<CUnsignedChar>(start: resultBytes, length: result.length) let MD5 = NSMutableString() for c in e { MD5.appendFormat("%02x", c) } return MD5 } return "" }
56. LIMITATIONS Projects that use the framework must repeat step 2. The given module map is not platform independent. Is it possible to make the header path relative to the current platform? Follow: http://stackoverflow.com/q/25248598/143378
57. WORKAROUND B BRIDGING FRAMEWORK
58. Objective-C frameworks can use C libraries without any issues. So let's create one that wraps the C library. Using CommonCrypto as an example...
59. STEP 1: CREATE THE BRIDGING FRAMEWORK 1. Add a new target to the project. 2. Select Cocoa Touch Framework. 3. Name it MyFrameworkBridge and select Objective-C as a language.
60. STEP 2: WRAP THE C LIBRARY 1. Add a public wrapper class or category. 2. Import and use the library in the implementation file. 3. Import the wrapper header (e.g., NSString+CommonCrypto.h) in the framework header (MyFrameworkBridge.h).
61. #import "NSString+CommonCrypto.h" #import <CommonCrypto/CommonCrypto.h> @implementation NSString(Haneke) - (NSString*)hnk_MD5String { NSData *data = [self dataUsingEncoding:NSUTF8StringEncoding]; unsigned char result[CC_MD5_DIGEST_LENGTH]; CC_MD5(data.bytes, (CC_LONG)data.length, result); NSMutableString *MD5String = [NSMutableString stringWithCapacity:CC_MD5_DIGEST_LENGTH * 2]; for (int i = 0; i < CC_MD5_DIGEST_LENGTH; i++) { [MD5String appendFormat:@"%02x",result[i]]; } return MD5String; }
62. NO CHEATING Importing the C library in a public header of the bridging framework will cause a compile error: include of non-modular header inside framework module 'MyFrameworkBridge'
63. FINALLY import MyFrameworkBridge var s : NSString ... let MD5 = s.hnk_MD5String
64. LIMITATIONS Projects that use the framework must also include the bridging framework. The wrapper methods of the bridging framework will be visible to projects who use the original framework.
65. BTW If you need to use simple cryptography such as MD5 in a framework, check out CryptoSwift.
66. UNIT TESTING
67. "A LIMITATION OF THE ACCESS CONTROL SYSTEM IS THAT UNIT TESTS CANNOT INTERACT WITH THE CLASSES AND METHODS IN AN APPLICATION UNLESS THEY ARE MARKED PUBLIC." Xcode 6.0 beta 4 release notes
68. We're aware that our access control design isn't great for unit testing (and this was in the release notes), we're evaluating the situation to see what we can do. — Chris Lattner
69. NO EXCUSES
70. WHY TEST INTERNALS? Internals are not public API but they're "public" API within the scope of the framework. Do you always work alone? Helper functions/extensions/types will most likely internal and are great candidates for unit testing. extension CGSize { func hnk_aspectFillSize(size: CGSize) -> CGSize { ... } }
71. WE SHALL UNIT TEST ANYWAY 1. Add all the framework files to the test target. 2. Remove the framework from Target Dependencies and Link Binary With Libraries build phases of the test target (to prevent naming collisions). You can now test public and internal elements.
72. THANKS! @HPIQUE