Contributing to Nuclide’s Swift Integration: Why and How

August 1, 2016

I was surprised by the amount of interest in my hackathon project to add Swift support to Nuclide. I'd love it if you helped me complete my vision for the project.

Why are people interested in nuclide-swift?

• There are only a few choices when it comes to Swift editors. I imagine most people use Xcode, and some use AppCode. In time, Nuclide could be another option.
• Nuclide is open-source. You can see exactly how each feature is implemented. This encourages collaboration. For example, I was thrilled to see Ryan Lovelett release a VS Code extension inspired by Nuclide.
• By using Swift tooling, like SourceKit, Nuclide provides useful feedback to the Swift team. I'm excited to work on testing framework integration, for example, since I think it will expose a lot of opportunities for Swift evolution proposals.

Why contribute?

• I learned a lot of JavaScript by contributing to Nuclide. Nuclide uses modern JavaScript, combined with type checking provided by Flow. Nuclide code uses generics, optionals, promises, and more. I'd never written JavaScript professionally before, and Nuclide was a great place to start.
• If you're looking to contribute to Swift tooling like SourceKit, or the Swift evolution process, working on Nuclide's Swift integration provides a lot of opportunities to do so. As just one example, I think both Nuclide and VS Code would benefit from JavaScript bindings to SourceKit. You could be the person to send a pull request to apple/swift to add those bindings.
• There's still a lot of features left to implement in nuclide-swift. Personally, I find it much more fun to work on something with a lot of low-hanging fruit, as opposed to something that's pretty much finished.

What are good resources for getting started with Nuclide package development?

• These instructions explain how to set up a Nuclide development environment.
• Nuclide is an Atom package. The Atom Flight Manual introduces the major concepts behind Atom's design.
• Nuclide uses the Atom services API to expose APIs for other packages to implement autocompletion, type hints, and more. All of Nuclide's Swift support is built using these services.
• Nuclide uses a "functional reactive" programming pattern. It uses the RxJS library to do so. If you've never used this "reactive" mumbo-jumbo before, don't worry: I hadn't either. This tutorial taught me everything I needed to know.
• Many Nuclide packages, including nuclide-swift, use the Flux pattern.

How does nuclide-swift work?

Here's the basic structure of the nuclide-swift package:

nuclide-swift/
    package.json
    lib/
        main.js
        sourcekitten/
            SourceKitten.js
            Complete.js
        taskrunner/
            toolbar/
                SwiftPMTaskRunnerToolbar.js
            LlbuildYamlParser.js
            SwiftPMTaskRunnerStore.js
            SwiftPMTaskRunnerActions.js
            SwiftPMTaskRunner.js
            providers/
                SwiftPMAutocompletionProvider.js

• package.json describes the services nuclide-swift uses, and the ones it provides.
• main.js is the entry point for the nuclide-swift package.
• SourceKitten.js provides utilities to invoke sourcekitten.
• Complete.js provides a function to invoke SourceKitten, with a set of compiler commands, to get autocompletion suggestions.
• SwiftPMTaskRunnerToolbar.js defines the UI for the Swift build toolbar.
• LlbuildYamlParser.js parses the YAML files produced by the Swift package manager. This extracts the compiler commands used to compile each Swift source file in a package. nuclide-swift uses these compiler commands when invoking SourceKitten, in order to get accurate code completion suggestions.
• SwiftPMTaskRunnerStore.js stores the state of the package: what Swift package is being built, the set of compiler commands necessary to compile each Swift source file, and more.
• SwiftPMTaskRunnerActions.js provides an interface to update the store.
• SwiftPMTaskRunner.js coordinates between the store and the toolbar.
• SwiftPMAutocompletionProvider.js passes the compiler commands saved in the store to SourceKitten, then surfaces those results to Atom.

What's left to do?

• Integrate swift test into the Nuclide test runner service.
• Display an outline view for the symbols in a Swift source file.
• Display diagnostics for Swift source files, so developers can see syntax errors inline.
• Display the type of Swift symbols as developers hover over them with their mouse.
• Display a "busy signal" indicator while SourceKitten is parsing Swift code.
• Allow developers to command-click on a Swift symbol to jump to its declaration.
• Provide syntax highlighting via SourceKitten.
• Add JavaScript bindings to SourceKit. SourceKit has Python bindings, but VS Code and Nuclide would benefit from being able to call SourceKit directly from JavaScript.