From dc04b3f5bf59d87df709950d18562d48af8b287a Mon Sep 17 00:00:00 2001 From: Tim <0xtimc@gmail.com> Date: Fri, 7 Jan 2022 15:01:29 +0000 Subject: [PATCH 1/6] Add remote dev docs --- docs/README.md | 7 +++++ docs/remote-dev.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/remote-dev.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..b6333313a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# Swift for VSCode Documentation + +Documentation on how to use the Swift for VSCode extension with remote containers etc and how to customize the extension. + +* [VSCode Remote Development](remote-dev.md) + +Want to add your own guide? See the [contributing guidelines](CONTRIBUTING.md)! \ No newline at end of file diff --git a/docs/remote-dev.md b/docs/remote-dev.md new file mode 100644 index 000000000..855659861 --- /dev/null +++ b/docs/remote-dev.md @@ -0,0 +1,68 @@ +# Visual Studio Code Remote Development + +[VSCode Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux to ensure there are no compatibility issues in Foundation when running your code. + +## Requirements + +As well as installing this extension, you must install Docker on your machine to run the remote container in. See the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/containers) for more details. + +Next, install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) that contains extensions for working in remote environments in VSCode. + +## Running in a container + +### Manual Setup + +VSCode requires a `.devcontainer` directory which defines the settings in `devcontainer.json` and a `Dockerfile` defining the container to run in. + +First create the directory. Next, create `devcontainer.json` and insert the following: + +```json +{ + "name": "Swift 5.5", + "image": "swift:5.5", + "extensions": [ + "sswg.swift-lang", + ], + "settings": { + "lldb.library": "/usr/lib/liblldb.so" + }, + "forwardPorts": [8080] +} +``` + +This defines the minimum settings required to run a Swift package in a remote container. Here's what each thing does: + +* `name`: Used to specify the name of the remote container. +* `image`: The Docker container image to run. You can choose whichever version of Swift you like, including [nightlies](https://hub.docker.com/r/swiftlang/swift). +* `extensions`: Extensions to install in your remote environment. You do not need to specify extensions' dependencies, such as LLDB. +* `settings`: Override any settings for extensions. The above example sets the LLDB path to stop the Swift extension from attempting to set it up. +* `forwardPorts`: Ports to enable forwarding for. You may want to include this if building a Swift server application for example. + +That's all you need to get a dev container working! + +#### Using a custom Dockerfile + +You may want to use a custom Docker container that's version controlled to make it easy to set up a development environment for you team. In `devcontainer.json` replace `image` with the following: + +```json +{ + "build": { "dockerfile": "Dockerfile" }, + // ... +} +``` + +This will use the `Dockerfile` provided in `.devcontainer`. Create that file and insert your custom Dockerfile. For example: + +```docker +FROM swift:5.5 +``` + +### Automatic Setup + +VSCode allows you to automatically configure your project with a dev container. In the command palette (`F1`) choose **Remote-Containers: Add Development Container Configuration Files...** and choose Swift. + +### Running in a container + +Once you've set up your `.devcontainer`, in the command palette run **Remote-Containers: Reopen in Container**. VSCode will relaunch running in your remote container! + +For more details about running your project in a remote container, and the available configuration options, see the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/remote-overview). \ No newline at end of file From 121870744cdfa8ea3e8a125265ead542203aca59 Mon Sep 17 00:00:00 2001 From: Tim <0xtimc@gmail.com> Date: Fri, 7 Jan 2022 15:03:40 +0000 Subject: [PATCH 2/6] Add link to docs to README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index b62a755d8..feef48566 100644 --- a/README.md +++ b/README.md @@ -55,3 +55,7 @@ When you open a Swift package (a directory containing a **Package.swift**) the e Press `F5` to run an executable and start debugging. If you have multiple launch configurations you can choose which launch configuration to use in the debugger view. CodeLLDB has a version of `lldb` packaged with it and by default this is the version it uses for debugging. However, this version of `lldb` does not work with Swift. Fortunately, CodeLLDB allows you to choose an alternate version. The Swift extension will attempt to ascertain which version is required and give you the option to update the CodeLLDB configuration. + +### Documentation + +For docs on how to configure the extension or use it with the Remote Development extension, see the [Documentation](Documentation/README.md). \ No newline at end of file From 67291701b4980c82c4d4be0e5408cb3934bd3e4b Mon Sep 17 00:00:00 2001 From: Tim Condon <0xTim@users.noreply.github.com> Date: Sat, 8 Jan 2022 15:57:44 +0000 Subject: [PATCH 3/6] Update docs/remote-dev.md Co-authored-by: Adam Fowler --- docs/remote-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/remote-dev.md b/docs/remote-dev.md index 855659861..0ba00a2d7 100644 --- a/docs/remote-dev.md +++ b/docs/remote-dev.md @@ -12,7 +12,7 @@ Next, install the [Remote Development extension pack](https://marketplace.visual ### Manual Setup -VSCode requires a `.devcontainer` directory which defines the settings in `devcontainer.json` and a `Dockerfile` defining the container to run in. +VSCode requires a `.devcontainer` directory which defines the settings in `devcontainer.json` and optionally a `Dockerfile` defining the container to run in. First create the directory. Next, create `devcontainer.json` and insert the following: From 0e014f7b1421ce3b342ade101e6d5b5970bc7b64 Mon Sep 17 00:00:00 2001 From: Tim <0xtimc@gmail.com> Date: Sat, 8 Jan 2022 15:59:04 +0000 Subject: [PATCH 4/6] Remove docs top level README --- README.md | 2 +- docs/README.md | 7 ------- 2 files changed, 1 insertion(+), 8 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index feef48566..50abe1dbb 100644 --- a/README.md +++ b/README.md @@ -58,4 +58,4 @@ CodeLLDB has a version of `lldb` packaged with it and by default this is the ver ### Documentation -For docs on how to configure the extension or use it with the Remote Development extension, see the [Documentation](Documentation/README.md). \ No newline at end of file +For docs on how to configure the extension or use it with the Remote Development extension, see the [Documentation](Documentation/). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index b6333313a..000000000 --- a/docs/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Swift for VSCode Documentation - -Documentation on how to use the Swift for VSCode extension with remote containers etc and how to customize the extension. - -* [VSCode Remote Development](remote-dev.md) - -Want to add your own guide? See the [contributing guidelines](CONTRIBUTING.md)! \ No newline at end of file From 62b4ee385098a667ec731c9a33219a55ffe6062d Mon Sep 17 00:00:00 2001 From: Tim <0xtimc@gmail.com> Date: Mon, 10 Jan 2022 17:06:12 +0000 Subject: [PATCH 5/6] Address code review comments --- README.md | 2 +- docs/remote-dev.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 50abe1dbb..82fc294c4 100644 --- a/README.md +++ b/README.md @@ -58,4 +58,4 @@ CodeLLDB has a version of `lldb` packaged with it and by default this is the ver ### Documentation -For docs on how to configure the extension or use it with the Remote Development extension, see the [Documentation](Documentation/). \ No newline at end of file +For docs on how to use the extension, see the [Documentation](Documentation/). \ No newline at end of file diff --git a/docs/remote-dev.md b/docs/remote-dev.md index 0ba00a2d7..8634124af 100644 --- a/docs/remote-dev.md +++ b/docs/remote-dev.md @@ -1,12 +1,12 @@ # Visual Studio Code Remote Development -[VSCode Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux to ensure there are no compatibility issues in Foundation when running your code. +[VSCode Remote Development](https://code.visualstudio.com/docs/remote/containers) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux. You can ensure there are no compatibility issues in Foundation when running your code. ## Requirements -As well as installing this extension, you must install Docker on your machine to run the remote container in. See the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/containers) for more details. +As well as installing the Swift extension, you must install Docker on your machine to run the remote container in. See the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/containers) for more details. -Next, install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) that contains extensions for working in remote environments in VSCode. +Next, install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) that contains extensions for working in remote environments in VSCode. If you only want to work with remote containers (and not use the SSH or WSL containers), you may want to only install the [Remote Development Container extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) instead. ## Running in a container @@ -57,9 +57,9 @@ This will use the `Dockerfile` provided in `.devcontainer`. Create that file and FROM swift:5.5 ``` -### Automatic Setup + ### Running in a container From 2a003df7afca8abc3ca3bb8e7812974ee1faba9d Mon Sep 17 00:00:00 2001 From: Tim <0xtimc@gmail.com> Date: Tue, 11 Jan 2022 11:48:08 +0000 Subject: [PATCH 6/6] Add link to new doc in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 82fc294c4..b53120918 100644 --- a/README.md +++ b/README.md @@ -58,4 +58,4 @@ CodeLLDB has a version of `lldb` packaged with it and by default this is the ver ### Documentation -For docs on how to use the extension, see the [Documentation](Documentation/). \ No newline at end of file +* [Visual Studio Code Remote Development](docs/remote-dev.md) \ No newline at end of file