|
1 | 1 | # Swift Development Environment |
2 | 2 |
|
3 | | -[](https://travis-ci.org/vknabel/swift-development-environment)   [](https://github.com/apple/swift-package-manager)   |
| 3 | +[](https://travis-ci.org/vknabel/swift-development-environment)   [](https://github.com/apple/swift-package-manager)   |
4 | 4 |
|
5 | | -SDE is a VS Code extension for extended Swift language support. It has initially been developed by @jinmingjian but is now maintained by @vknabel. |
| 5 | +**SDE** adds Swift code completion and hover help to Visual Studio Code on macOS and Linux. |
6 | 6 |
|
7 | | -## 2.0 Release Broadcast |
8 | | -The `2.0` release introduces a new tool, [SourceKite](https://github.com/jinmingjian/sourcekite), as the interface to **SourceKit** library. Since the Swift `ABI` is not stable, you need to build it if you want to use SDE. Go to [SourceKite](https://github.com/jinmingjian/sourcekite) for further instructions. |
| 7 | +> **Fork Notice:** This is the new home of SDE initially been developed by [@jinmingjian](https://github.com/jinmingjian). It is now maintained by [@vknabel](https://github.com/vknabel). [jinmingjian/sde](https://github.com/jinmingjian/sde) is no longer maintained and does only support Swift 3. This fork supports Swift 3 and 4. |
9 | 8 |
|
10 | | -Also because the Swift ABI **is not stable**, you may find that the _Hover Help_ or the _Code Completion_ don't display the right information after you upgrade your Swift toolchain. This is because the SourceKit library you linked with the [SourceKite](https://github.com/jinmingjian/sourcekite) tool can't understand the sources or binaries of your project. To fix this, **rebuild your project** and **restart vscode**. |
11 | | - |
12 | | -#### Want to downgrade? |
13 | | -If the release broke your current experience or if you accidentally upgraded, you can go back to the previous releases like this: |
14 | | - |
15 | | -1. Download the 1.x vsix from [the release page](https://github.com/vknabel/swift-development-environment/releases) |
16 | | -2. Remove the installed version in your vscode |
17 | | -3. Install the local `.vsix` package in your vscode |
18 | | - |
19 | | -#### Version history |
20 | | -Can be seen in [CHANGELOG](CHANGELOG.md). |
21 | | - |
22 | | -## Quick Preview |
23 | 9 |  |
24 | 10 |
|
25 | | -You can read a [hands-on introduction](http://blog.dirac.io/2017/01/11/get_started_sde.html) for a detailed explanation. |
26 | | - |
27 | | -## Project Status |
28 | | -The project focuses on making the following features solid: |
29 | | -* Code completion |
30 | | -* Formatting |
31 | | -* Error diagnosis |
32 | | -* Debugging |
33 | | -* Navigation/hyperlinking |
34 | | -* Hover help |
35 | | -* SPM support/preferences/tools |
36 | | - |
37 | | -Read more of the big picture in [the wiki](https://github.com/jinmingjian/sde/wiki) |
38 | | - |
39 | | -The initial goal of this project was to give myself a joyful Swift coding experience in Linux. But with the help of community, the macOS support has become as strong as it is in Linux. I hope it can drive you to start a joyful coding experience for server side Swift at Linux and macOS. *(Or if you like, try it on Windows 10 WSL)* |
40 | | - |
41 | | -The current work for this project is done in the free time of the author for his love to **swift@linux**. Therefore, it is best _(at the moment)_ to focus the limited resources on the most important functionalities. That said, your ideas are always welcome. |
42 | | - |
43 | | -## Usage |
44 | | - |
45 | | -### Installation |
46 | | - |
47 | | - - Just search "sde" and install from your vscode's _Extensions_ view. |
48 | | - |
49 | | -### Prerequisites |
50 | | - |
51 | | - - This project only depends on its companion project [sourcekite](https://github.com/jinmingjian/sourcekite), which transitively depends on the official Swift codebase and its companion-tool project [SourceKit library](https://github.com/apple/swift/tree/master/tools/SourceKit). Go to [sourcekite](https://github.com/jinmingjian/sourcekite) for more information. |
52 | | - |
53 | | - - Starting from 2.0, SDE is based on top of **Swift 3.1** and **vscode 1.8** (typescript 2.0 for development). You will be notified when these version dependencies are broken. _(**NOTE:** Swift 3.1 is intended to be source compatible with Swift 3, so you can develop with SDE and release with 3.0)_ |
54 | | - |
55 | | -### Other information |
56 | | - |
57 | | -1. The dependence to `sourcekitd-repl` has been deprecated starting from release 2.0. |
58 | | - |
59 | | - 1. The extension in the marketplace will be rolling-updated in a timed rhythm, such as some weeks. Also, there is no semantic versioning or backward compatibility guaranteed yet. It is better to check the changelog before your update. |
| 11 | +## Installation |
| 12 | +1. Install the [extension](https://marketplace.visualstudio.com/items?itemName=vknabel.vscode-swift-development-environment) itself. |
| 13 | +2. Install the companion project [sourcekite](https://github.com/vknabel/sourcekite). |
| 14 | + |
| 15 | + ```bash |
| 16 | + $ git clone https://github.com/vknabel/sourcekite |
| 17 | + $ cd sourcekite |
| 18 | + |
| 19 | + # For Linux |
| 20 | + $ swift build |
| 21 | + |
| 22 | + # For macOS (when using swiftenv or multiple Toolchains) |
| 23 | + $ swift build -Xswiftc -framework -Xswiftc sourcekitd -Xswiftc -F -Xswiftc /Library/Developer/Toolchains/swift-latest.xctoolchain/usr/lib -Xlinker -rpath -Xlinker /Library/Developer/Toolchains/swift-latest.xctoolchain/usr/lib -c release |
| 24 | + |
| 25 | + # For macOS (using Xcode's Toolchain) |
| 26 | + $ swift build -Xswiftc -framework -Xswiftc sourcekitd -Xswiftc -F -Xswiftc /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/ -Xlinker -rpath -Xlinker /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/ -c release |
| 27 | + ``` |
| 28 | +3. Add the *absolute* path to your compiled sourcekite binary `swift.path.sourcekite` to your vscode settings as `/path/to/your/sourcekite-bin/.build/release/sourcekite`. |
| 29 | + |
| 30 | +If you experience any problems during installation, file an issue or write me an [email ](mailto:[email protected]). All kind of feedback helps especially when trying to automate this. |
| 31 | + |
| 32 | +## Debugging |
| 33 | + |
| 34 | +SDE has a built-in Swift debugger which has been deprecated. Instead use [LLDB Debugger](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) which powers more features and is more stable. |
| 35 | + |
| 36 | +An example config can be seen below. `program` should contain the path to your built executable, the `preLaunchTask` is optional, but will run `swift build` before each debug session to keep your binaries up to date. |
| 37 | + |
| 38 | +> **Note:** Currently I don't know of any reliable solution to debug your Swift tests. |
| 39 | +> If you do, please file an issue or write me an [email](mailto:[email protected]). |
| 40 | +
|
| 41 | +```js |
| 42 | +// .vscode.json/launch.json |
| 43 | +{ |
| 44 | + "version": "0.2.0", |
| 45 | + "configurations": [ |
| 46 | + { |
| 47 | + "type": "lldb", |
| 48 | + "request": "launch", |
| 49 | + "name": "Run your Executable", |
| 50 | + "program": "${workspaceFolder}/.build/debug/your-executable", |
| 51 | + "args": [], |
| 52 | + "cwd": "${workspaceFolder}", |
| 53 | + "preLaunchTask": "swift-build" |
| 54 | + } |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +```js |
| 59 | +// .vscode.json/tasks.json |
| 60 | +{ |
| 61 | + "version": "2.0.0", |
| 62 | + "tasks": [ |
| 63 | + { |
| 64 | + "label": "swift-build", |
| 65 | + "type": "shell", |
| 66 | + "command": "swift build" |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
60 | 70 |
|
61 | 71 | ## Contributors |
62 | | -Valentin Knabel, @vknabel: [twitter](https://twitter.com/vknabel) |
63 | | -Jin Mingjian, @JinMingjian: [twitter](https://twitter.com/JinMingjian) |
64 | | -Felix Fischer, @felix91gr: [twitter](https://twitter.com/FelixFischer91), [github](https://github.com/felix91gr) |
| 72 | +- Valentin Knabel, [@vknabel](https://github.com/vknabel), [twitter](https://twitter.com/vknabel), *maintainer* |
| 73 | +- Jin Mingjian, [@JinMingjian](https://github.com/JinMingjian), [twitter](https://twitter.com/JinMingjian), *author* |
| 74 | +- Felix Fischer, [@felix91gr](https://github.com/felix91gr), [twitter](https://twitter.com/FelixFischer91) |
65 | 75 |
|
66 | 76 | ## FAQ |
67 | 77 |
|
68 | | -### Is it possible to use SDE if I can't build sourcekite in my Linux setup, in absence of sourcekit library? |
69 | | - |
70 | | -Strictly speaking, we should wait for the sourcekit library to be included in the official download. From _2.0.20170209_ though, SDE makes a sourcekite docker image and adds a new experimental setting `swift.path.sourcekiteDockerMode` for easier adoption for Linux users. Go to [sourcekite](https://github.com/jinmingjian/sourcekite) for more information. |
71 | | - |
72 | | -### Why don't you contribute to the existing projects? |
73 | | - |
74 | | -Current such works are all naïve to attract linux/backend users to embrace concise and elegant Swift. I am watching the communities of vscode and Swift to provide the best experience with my best effort. |
75 | | - |
76 | | -I also highly suggest the work of community (vscode & SwiftLang) should be joint. But I hope we can all be in good terms. |
77 | | - |
78 | 78 | ### How to contribute to this project? |
79 | 79 |
|
80 | 80 | Any feedback helps. |
81 | 81 |
|
82 | 82 | If you mean contributions to the **sources**, this is truely another topic. The experience of **_using_** an editor is much different than that of **_developing_** one. It might be a bit more painful than you think. But if you would like to, welcome! |
83 | 83 |
|
84 | | -There aren't too much documents about the development of this project. If you have any questions or interests, don't hesitate to file an issue _(better than a private email)_. I will help you and then drop more readings as time goes by. This is **_the way of "open source"_**. |
85 | | - |
86 | | -### Why can't I debug my executable, built by SPM in my Linux installation? |
87 | | - |
88 | | -Watch [this SR](https://bugs.swift.org/browse/SR-3280) for more and then you would be easy to dig out some workaround although there are still other problems. |
89 | | - |
90 | | -### It seems diagnostic info is not available at all? |
91 | | - |
92 | | -Did you build your project yet? Try it. Then, you can see below for a detailed explanation. |
93 | | - |
94 | | -### It seems diagnostic infos are only available after building? |
95 | | - |
96 | | -Yes. Not only the diagnostic infos, the current design and implementations are convention-based, like SPM itself. This is still far from the perfect. However, it is enough for many cases although not flexible for covering 100%. There are many reasons for this, such as, limited development resources, bugs in Sourcekit tools or the lacks of understanding to current Sourcekit protocol. I'd like to continue to improve the experience. |
| 84 | +There aren't too much documents about the development of this project. If you have any questions or interests, don't hesitate to file an [issue ](https://github.com/vknabel/swift-development-environment/issues) or write me an [email ](mailto:[email protected]). I will help you and then drop more readings as time goes by. This is **_the way of "open source" _**. |
97 | 85 |
|
98 | | -## Other questions? |
| 86 | +### Other questions? |
99 | 87 |
|
100 | 88 | If so, file an [issue](https://github.com/vknabel/swift-development-environment/issues), please :) |
101 | 89 |
|
|
0 commit comments