Russ Bishop: Contributing to Open Source Swift

Transcript

1. Contributing to Swift Russ Bishop My views are my own and are not endorsed by my employer in any way.
2. Contributing to Swift » I've never worked on a language, compiler, or standard library but I shipped SE-0008, SE-0017, SE-0032, and SE-0076. » They won't change the world but maybe I can give core team members more time to implement things like opening existentials or redesigning the collection protocols. » You can do it too!
3. Swift.org » master requires Xcode 8 » Create a directory to hold all related projects, eg swift-src » Clone Swift repo into that directory swift-src/swift » Run cd swift-src & ./swift/utils/update-checkout -- clone » This will clone LLVM, Clang, etc
4. Contributing Fork the relevant project » Can rename origin to upstream on that repo & add fork as origin. » However update-checkout won't work; Pull official changes git pull upstream master » Alternative: add your fork as fork. Create your branches tracking on fork. » For more information, see The Internet, git docs, read some guides. » Then ask a git expert because none of the previous advice helped whatsoever. » Open PR against Apple repo. Make sure you link JIRA bug.
5. Building » ./utils/build-script » -R for release mode, otherwise debug mode » -c for clean build » -x to generate Xcode project that can build Swift for macOS » Check build-presets.ini for examples of making your own presets » ./utils/build-script -R --debug-swift to build release mode LLVM/ Clang but still be able to debug Swift (faster?) » 33 minutes on 2015 MacBook Pro Core i7 2.5Ghz
6. Directory Structure » /include & /lib have most of the compiler C++ sources » /tools/SourceKit » /stdlib (mostly written in Swift) » /stdlib/private also includes unit test standard library » /stdlib/public the standard library (almost) » /stdlib/public/SDK look behind the curtain » /stdlib/public/runtime where we're going we don't need eyes to see
7. Directory Structure » /apinotes rename types, map selectors, wheeee » /docs don't get too excited » /unittests not the unit tests you're looking for ! » /test unit tests, mostly in Swift » /test/1_stdlib helpfully named so it runs first » /utils build script, gyb, etc » /validation-test test cases, validates shapes of types, conformances, etc
8. Generate Your Boilerplate Due to language limits and lack of macro system there is a lot of boilerplate in the standard library and in the tests. GYB is a Python script that processes templates. » Substitution: ${<python expression>} » Python Code Blocks: %{ ... }% » Single-line Python: % if True: » Makes the Xcode project generated by ninja almost useless for stdlib work » Invoke manually to see the output: gyb CollectionAlgorithms.swift.gyb > CollectionAlgorithms.swift
9. Generate Your Boilerplate % for mutable in (True, False): % Self = 'UnsafeMutablePointer' if mutable else 'UnsafePointer' public struct ${Self}<Pointee> : Strideable, Hashable, _Pointer { % if mutable: public init(allocatingCapacity count: Int) { //... } % end } % end
10. Tests » Uses LLVM lit utility; reads .cfg files to configure and discover tests » Unit tests - 13+ minutes » Validation tests - 1+ hour » build-script -R -T --debug-swift --skip-build-benchmarks » Lower t is unit tests, upper T is full validation test suite » Make sure other build settings match or you'll rebuild just for the tests
11. Tests If a test fails don't give up hope. You can run individual tests! I put this in .bashrc, substituting my real path and Ninja-ReleaseAssert+swift- DebugAssert as the build config. LLVM_DIR="/<path>/swift-src/llvm" SWIFT_BUILD_DIR="/<path>/swift-src/build/<build-config>/swift-macosx-x86_64" run-validation-test() { $LLVM_DIR/utils/lit/lit.py -a --param swift_site_config=$SWIFT_BUILD_DIR/validation-test-macosx-x86_64/lit.site.cfg $1 } run-test() { $LLVM_DIR/utils/lit/lit.py -a --param swift_site_config=$SWIFT_BUILD_DIR/test-macosx-x86_64/lit.site.cfg $1 } Execute with run-test 1_stdlib/the_test.swift.gyb
12. Tests A validation test failure will also give you the command to run. Fix, build (without -t/-T), then run the command: /some/long/path/a.out --stdlib-unittest-in-process --stdlib-unittest-filter "test/path"
13. Custom Toolchains A Toolchain is a complete package of tools required to build software, including SourceKit and Xcode integration. » Default Xcode toolchain is inside app bundle Developer/Toolchains/ XcodeDefault.toolchain » Installed to /Library/Developer/Toolchains/* » Xcode presents them in the menu » As of Xcode 8b2 you can use non-default toolchains in Playgrounds
14. Custom Toolchains » ./utils/build-toolchain does a full build for all platforms with validation tests. This takes forever and uses a lot of space. » You can use a custom build preset ini file to skip some platforms or skip tests 1 » Produces an installable package for distribution » You can also symlink into the system toolchains directory 1 http://belkadan.com/blog/2016/05/So-You-Want-To-Be-A-Compiler-Wizard/
15. Coordination Taking on work! » swift-evolution » swift-dev » bugs.swift.org
16. Future Directions » LLVM tutorial http://www.llvm.org/docs/tutorial/ » Jordan Rose's So You Want to Be a Compiler Wizard 1 » Keep working on bugs and implementing swift- evolution proposals 1 http://belkadan.com/blog/2016/05/So-You-Want-To-Be-A-Compiler-Wizard/
17. fin