Creating Intuitive Developer Tool in Swift

Talked at KWDC24 https://kwdc.dev/en/2024/speaker/6/

Transcript

1. @giginet 2024/10/25 @giginet Creating Intuitive Developer Tool in Swift Slide
2. Self Introduction • giginet / Kohki Miki • X / GitHub : @giginet • Tokyo 🇯🇵 • Work for LY Corporation(2022~) • iOS DevOps Engineer for LINE • iOS Development experience since iOS 4 (2010~) • ❤ 👾 Gaming
3. Agenda and Goals • Finding the issue • History of Swift ecosystem • Practical Examples of Developer tools • Implement your tool • Implementation / Testing • For the more usable tools • Documentation / Deployment / CI • Contribute to Community
4. My OSS Contribution as a core contributor fastlane Carthage XcodeGen
5. My Recent Work : giginet/Scipio (⭐450) • A next-generation build tool to generate XCFramework • Convert Swift Package to XCFramework • Share prebuilt frameworks among developers 1. Resolve and checkout package manifest with SwiftPM 2. Scipio generates Xcode Project from each package 3. Build the projects with xcodebuild 4. xcodebuild generates XCFramework How does Scipio work? Resolve manifests Fetch packages Generate Xcode Project Build XCFrameworks https://speakerdeck.com/giginet/standardizing-build-system-using-modern-swift-packages-in-line
6. giginet/swift-testing-revolutionary (⭐200) • Convert test cases written in XCTest into swift-testing • Providing Command Plugin and Xcode GUI
7. Finding the issue History and practical example of developer tools
8. Tool Developments What should I develop? How to develop? How to spread? Why should I publish it?
9. History of iOS Developer’s Tools 2014 2019 Prehistoric Period Dawn Period Maturity Period Swift is released Maturation of Swift ecosystem
10. Before Swift era(~2015) • ObjC is not suitable for tool development • Most tools were developed in Ruby or other languages • CocoaPods(2011) • fastlane(2015) • danger(2015) • xcpretty • xcode-select
11. Swift released (2015~2019) • Some useful tools are available • Carthage(2015) • SwiftLint(2015) • XcodeGen(2017) • tuist(2018) • No de-facto standard foundations • SwiftCLI / Commandant / Commander (argument parser) • Quick / Nimble / Spectre… (Testing Framework)
12. Today : Ecosystem of tools development • The o ff i cial development foundations are available • Swift Package Manager (2015) • Xcode Integration (2019) • swift-syntax(2017) • swift-argument-parser(2020) • Package Plugin (2022) • swift-testing(2023)
13. What should we develop?
14. Begin to develop for your team!
15. Practical Example : line-tools • In-house tool collections for LINE development • Implemented many features in Swift • Build script of dependencies • Prebuilt tasks • CI scripts • linter / formatter
16. Example 1 : Building dependencies • Share XCFrameworks using Remote Server • Based on Scipio • Features • Resolve Swift Packages • Build XCFramework • Download XCFrameworks
17. Example 2 : Prebuilt Tasks • Useful wrapper tools of XcodeGen • Features • Verify Project Spec and dependencies • Generate Xcode projects from Project Specs
18. Example 3 : CI script • A tool generates TestPlan on CI for Pull Requests Builder • Generate Test Plan from Pull Request fi le di ff s • Features • Generate TestPlan by PR di ff s
19. Example 4 : Extend IDE features • A linter to warn company rules • Run custom linter on Xcode • We can use swift-syntax • Features • Lint dependency tree • Lint coding guidelines
20. Benefit of developing tools in Swift • Ubiquitous Language • Write complex tasks with a powerful language feature • Using Swift foundations (e.g. swift-syntax) • Maintainability • Testability • Type Safety
21. Implement your tools Basic techniques to create your tools
23. CI / Testing
24. Documentation
25. Distribution
26. Backward Compatibility
27. For useful developer tools • Various technics • CI / Tests • Documentation • Cross-platform / Multi versioning • Binary distribution • These also help for OSS or in-house tool
28. Kind of developer tools • Executable • Good for any purpose • Difficult to distribute • Package Plugin (Introduced from Swift 5.6) • Build Tools Plugin • Command Plugin
29. Build Tools Plugin • A mechanism to distribute build hooks via Swift Package ecosystem • Introduced in Swift 5.6 • Code Generator ( Pre-built hook) • SwiftGen / openapi-generator / License generator • Linter / Formatter (Post-built hook) • SwiftLint / SwiftFormat
30. Command Plugin • Distributing command via Swift Package ecosystem • Can provide Command Line Interface / Xcode GUI • Example • docc-plugin • swift-testing-revolutionary • See ”Meet Package Plugins" in WWDC22 • https://developer.apple.com/videos/play/wwdc2022/110359/
31. swift-argument-parser • A first-party library to make Command Line Interface(CLI) • https://github.com/apple/swift-argument-parser
32. import ArgumentParser @main struct Repeat: ParsableCommand { @Flag(help: "Include a counter with each repetition.") var includeCounter = false @Option(name: .shortAndLong, help: "The number of times to repeat 'phrase'.") var count: Int? = nil @Argument(help: "The phrase to repeat.") var phrase: String mutating func run() throws { let repeatCount = count ?? 2 for i in 1...repeatCount { if includeCounter { print("\(i): \(phrase)") } else { print(phrase) } } } } Options
33. import ArgumentParser @main struct Repeat: ParsableCommand { @Flag(help: "Include a counter with each repetition.") var includeCounter = false @Option(name: .shortAndLong, help: "The number of times to repeat 'phrase'.") var count: Int? = nil @Argument(help: "The phrase to repeat.") var phrase: String mutating func run() throws { let repeatCount = count ?? 2 for i in 1...repeatCount { if includeCounter { print("\(i): \(phrase)") } else { print(phrase) } } } } Implementations
34. To write tests my-awesome-tool executable • Difficult to write tests for single executable target
35. Package Architecture • Separate targets executable and frameworks my-awesome-tool MyAwesomeKit MyAwesomeKitTests executable framework test target Testable
36. Package Architecture • Good for minimize the dependencies my-awesome-tool MyAwesomeKit MyAwesomeKitTests executable framework test target swift-argument-parser other dependencies
37. Implement your tool!
38. For the more usable tools Tips for getting many users for your tool
39. README • Badges • https://shields.io/ • Installation methods • Feature Lists • LICENSE
40. README • Badges • https://shields.io/ • Installation methods • Feature Lists • LICENSE
41. README • Badges • https://shields.io/ • Installation methods • Feature Lists • LICENSE
42. README • Badges • https://shields.io/ • Installation methods • Feature Lists • LICENSE
43. Write articles with DocC
44. Build DocC Archive • Use DocC plugin • https://github.com/swiftlang/swift-docc-plugin • Distributing to GitHub Pages • Update DocC page with every commits Swift Package DocC Archive GitHub Pages
45. Register to Swift Package Index • Register your package to Swift Package Index • https://swiftpackageindex.com/add-a-package
46. Distribution • Many methods for distribution • Source Build • Binary / Artifact Bundle • Command Plugin • Homebrew
47. Source Builds • Nothing to do for developers • No official way to manage binaries for the user side • Mint • https://github.com/yonaskolb/Mint • No way to distribute prebuilt binaries • Need to build by users
48. Artifact Bundle • The official distribution format for executables • Host executables for multi architecture in ZIP file • https://github.com/swiftlang/swift-evolution/blob/main/proposals/ 0305-swiftpm-binary-target-improvements.md
49. Build Artifact Bundle • No official way to make Artifact Bundles • freddi-kit/ArtifactBundleGen • Command Plugin to wrap executables in Artifact Bundle format • https://github.com/freddi-kit/ArtifactBundleGen
50. Use Artifact Bundle • No official way to manage it • mtj0928/nest • Download and run prebuilt binary using Artifact Bundle • https://github.com/mtj0928/nest
51. Prepare CI environment • Must prepare CI environment! • CI provides some automation • Tests • Lint • Documentation • Generate DocC Archive • Distribute to GitHub pages • Distribution • Build Artifact Bundle
52. GitHub Action • Using GitHub Action solves everything • Separate workflows for purposes • tests/lints/release/docc
53. name: Tests on: push: branches: - main pull_request: branches: - '*' jobs: Tests: strategy: matrix: xcode_version: - "15.2" # 5.9 - "15.4" # 5.10 - "16.0" # 6.0 env: DEVELOPER_DIR: "/Applications/Xcode_${{ matrix.xcode_version }}.app/Contents/Developer" runs-on: macos-14 steps: - name: Get swift version run: swift --version - uses: actions/checkout@v2 - name: Run Tests run: | swift test --verbose env: ENABLE_INTEGRATION_TESTS: 1 IS_CI: 1 Make PR builder Build for multi versions
54. Contribute to community Make your tools great
55. Why publish a tool? • Improve your presence and career • Give inspires to communities • Receive feedback / Make collaboration Your Team Community Contributions / Inspires Feedback / Improvements
57. Use your tool • Just publishing to OSS wouldn’t work fine • It’s difficult to maintain only for the community • You should be a heavy user Great Tool Contribute to Community Use your tools
58. Conclusion • Finding issues is the most important topic • Learn Techniques and Tips to Build Tools • Contributing to Swift community to publish your tool • Keep to use your tools
59. References • See my products for examples! • Scipio • swift-testing-revolutionary • Feel free to ask anything on X / Ask the Speaker • https://x.com/giginet
60. Thank you for listening!