Skip to content

Add a guide for accessing tools installed by swiftly and other places #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+39 −0
Open

Add a guide for accessing tools installed by swiftly and other places #340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions Documentation/SwiftlyDocs.docc/use-tools-different-sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Access Tools from Different Sources
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# Access Tools from Different Sources
# Access the executable tools that from different Swift toolchains.


Access tools that can be from different sources.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Access tools that can be from different sources.
Change how you access installed toolchains.


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Overview

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?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Use the run subcommand to invoke executables in a Swift toolchain

This sort of overlaps with content you have in use-toolchains.md - maybe it's worth breaking this out into it's own article on using swiftly run - since you can do quite a bit with it - and referencing that article from here?

If the tool is in a toolchain managed by swiftly it will call it directly when you run "swift", "clang", or "lldb". If you want to access the particular tool directly you can use `swiftly run` to run it like this wit the particular version of toolchain that you want:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the tool is in a toolchain managed by swiftly it will call it directly when you run "swift", "clang", or "lldb". If you want to access the particular tool directly you can use `swiftly run` to run it like this wit the particular version of toolchain that you want:
If the tool is in a toolchain managed by swiftly it calls it directly when you run "swift", "clang", or "lldb".
If you want to access the particular tool directly, use `swiftly run` to run it with the toolchain you choose.
The following example illustrates how to invoke `clang --version` from the currently enabled toolchain:


```
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Link and Unlink Swiftly's command proxy

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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>.


```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:


```
swiftly link
```

In this guide you have seen a few different ways to access tools installed by swiftly, and ones that are installed separately.