Add a guide for accessing tools installed by swiftly and other places #340
Conversation
There was a problem hiding this comment.
I'll repeat this below in the commands, but I think you've got two articles here mashed into one. I suggested added section headers to try and break up the content into more concrete flows, but even with these suggestions the article seems to be serving two masters.
I made suggestions through the content to tighten up wording or rephrase to make the wording a bit more targeted. you're describing two different procedural things, and tacking in a bit of explanation in between. At a high level, what I'm seeing:
- how to use (the new) link and unlink subcommands
- a bit of explanation that swiftly adds executable proxies for common commands to your PATH
- how to use
swiftly runandswiftly use --print-locationto either invoke within a toolchain, or assemble the full path to do so yourself.
| @@ -0,0 +1,39 @@ | |||
| # Access Tools from Different Sources | |||
|
|
|||
| Access tools that can be from different sources. | |||
There was a problem hiding this comment.
| Access tools that can be from different sources. | |
| Change how you access installed toolchains. |
|
|
||
| Access tools that can be from different sources. | ||
|
|
||
| swiftly installs and manages toolchains for you that are available from swift.org. It sets up your shell environment to work well with these. There are other sources of Swift toolchains, and the common tools found in them, too. How do I access these from within my swiftly environment? |
There was a problem hiding this comment.
Is this relevant to anything other than macOS? I think it's the only platform that has that whole competing setup with xcrun that's so prevalent with macOS and iOS developers. I think making the explicit comparison of using xcrun .... to swiftly run ... would be exceptionally useful to make this connection.
| @@ -0,0 +1,39 @@ | |||
| # Access Tools from Different Sources | |||
There was a problem hiding this comment.
The title hits me as too vague - so much so that it's unclear what this article is about and what I'd want to read it from the combination of Title and abstract. I'm taking a stab with the suggested changes based on the content in the article, but I don't know if it's targeted as you'd like.
| # Access Tools from Different Sources | |
| # Access the executable tools that from different Swift toolchains. |
| # Access Tools from Different Sources | ||
|
|
||
| Access tools that can be from different sources. | ||
|
|
|
|
||
| swiftly installs and manages toolchains for you that are available from swift.org. It sets up your shell environment to work well with these. There are other sources of Swift toolchains, and the common tools found in them, too. How do I access these from within my swiftly environment? | ||
|
|
||
| Also, sometimes it's difficult to determine whether there is a bug in swiftly itself, or the bug lies in the particular toolchain at swift.org. How can I figure this out? |
There was a problem hiding this comment.
This articles seems to be trying to serve two masters - how to use the new link and unlink subcommands as well as how to wrangle seeing and controlling where a specific tool is being invoked from. I think you may be trying to go too broad here. This reads to me like two focused articles sort of mashed into one.
| swiftly run clang --version | ||
| ``` | ||
|
|
||
| If you want to bypass swiftly's run mechanism you can find the location of the tool and run it from it's fully qualified path: |
There was a problem hiding this comment.
| If you want to bypass swiftly's run mechanism you can find the location of the tool and run it from it's fully qualified path: | |
| If you want to bypass swiftly's run mechanism, use `swiftly use --print-location` to find the location of the tool and run it from there. | |
| The following example shows how to use this within a shell to create a full path to the currently active toolchain: |
| $(swiftly use --print-location)/usr/bin/clang --version | ||
| ``` | ||
|
|
||
| Normally, when you install swiftly it places a set of proxy tools for the usual Swift toolchain commands. These are run in place of the actual toolchain so that swiftly can route them to the in use toolchain based on your configuration. If you want to bypass swiftly entirely, or use tools that were installed separately from swiftly there is also the ability to "unlink" swiftly's proxy binaries from your PATH. |
There was a problem hiding this comment.
| Normally, when you install swiftly it places a set of proxy tools for the usual Swift toolchain commands. These are run in place of the actual toolchain so that swiftly can route them to the in use toolchain based on your configuration. If you want to bypass swiftly entirely, or use tools that were installed separately from swiftly there is also the ability to "unlink" swiftly's proxy binaries from your PATH. | |
| Normally, swiftly installs a set of proxy commands on your `PATH` environment variable for common Swift toolchain executables when you select a toolchain for use. | |
| These are run in place of the actual toolchain so that swiftly can route them to the in use toolchain based on your configuration. | |
| If you want to bypass swiftly entirely, or use tools that were installed separately from swiftly there is also the ability to "unlink" the proxy binaries. |
| swiftly unlink | ||
| ``` | ||
|
|
||
| Now, when you run "swift" and other tools they will be found elsewhere on your system (or not found at all). The "swiftly" command should still be available, so you can still find the location of the in use toolchain and other swiftly commands. |
There was a problem hiding this comment.
| Now, when you run "swift" and other tools they will be found elsewhere on your system (or not found at all). The "swiftly" command should still be available, so you can still find the location of the in use toolchain and other swiftly commands. | |
| After you run `swiftly unlink`, the system will search your PATH for `swift` and other executables in the toolchain without the proxy commands included. | |
| The `swiftly` command is still be available, which you can use to find and run executables within any toolchain that swiftly installed. |
if swiftly run was its own article, I'd do a "For more information on using swiftly to invoke executables from toolchains, read <doc:swiftly-run-article>.
|
|
||
| Now, when you run "swift" and other tools they will be found elsewhere on your system (or not found at all). The "swiftly" command should still be available, so you can still find the location of the in use toolchain and other swiftly commands. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
lines 29-31 seem to be repeat of what you're describing up at line 18 - I think you'd want to either move that content down here and flesh this out, or push this detail back up outside of the section on link and unlink.
| swiftly use --print-location | ||
| ``` | ||
|
|
||
| For instance, you can use this path to call a tool directly, or manually construct your path with it. You can also use swiftly to link the proxies again to get back to where you were before: |
There was a problem hiding this comment.
| For instance, you can use this path to call a tool directly, or manually construct your path with it. You can also use swiftly to link the proxies again to get back to where you were before: | |
| After you unlinked the command proxies, run the following command to enable them again: |
Document how one can access tools outside of the usual swiftly
proxy mechanism for various purposes. One possibility is to
determine if there is a bug in a particular tool. Another is that
there is a tool that is installed outside of swiftly.