Hide unused legacy --sdk and --toolchain options from CLI help

[MaxDesiatov]

These options are not recommended for general use and are confusing for end users that don't clearly distinguish between SDKs and Swift SDKs. These options also predate Swift SDK introduction, that's why historically they were kept in help output still. Now that Swift SDKs are no longer experimental, we should hide legacy options to reduce the chance for confusion.

[MaxDesiatov]

@swift-ci test

[MaxDesiatov]

@swift-ci test self hosted windows

[bkhouri]

Since we are changing the command line arguments, should this go through a Swift Evolution proposal process?

I wonder if we should also mark these command line arguments as deprecated too.

[dschaefer2]

Actually, I'm about to start using --sdk to test my hand built SDK. There's a chance that becomes the future of how we do SDKs for cross. I think that's still a legitimate option.

I'm not sure what the --toolchain options does. In theory, the host toolchain should be able to build everything cross. Unless you're hand rolling you're own toolchain, which I guess could be a thing.

[MaxDesiatov]

Since we are changing the command line arguments, should this go through a Swift Evolution proposal process?

@bkhouri We're not changing command-line arguments in this PR. --sdk stays as valid as it was before.

I wonder if we should also mark these command line arguments as deprecated too.

I'm not sure that's currently warranted based on what Doug says below.

Actually, I'm about to start using --sdk to test my hand built SDK. There's a chance that becomes the future of how we do SDKs for cross. I think that's still a legitimate option.

@dschaefer2 No debating that, it may be a legitimate option, but in the current situation it's untenable to have it in help output with no help whatsoever and no clear use cases for the majority of our users. My proposal is to hide it until we have clear and detailed guidelines for its usage.

I'm not sure what the --toolchain options does. In theory, the host toolchain should be able to build everything cross. Unless you're hand rolling you're own toolchain, which I guess could be a thing.

Similarly, that's one more reason to have it as hidden until we figure that out.

[MaxDesiatov]

Just a few examples to illustrate the problem:

https://forums.swift.org/t/differences-between-sdk-swift-sdk-toolchain-and-toolset/82438
https://forums.swift.org/t/cross-compiling-for-linux/83523/14

Our users are confused by these legacy options. They frequently use --sdk by mistake, where they clearly meant --swift-sdk. I'm sharing only a few posts on Swift Forums here, but there were more over longer timespan, and I'm answering questions about these on Discord and Slack regularly. I've never seen an end user having legitimate use case for --sdk after the introduction of --swift-sdk. It's great to have --sdk for people like us experimenting, but it should not confuse end users who don't need it and put an unnecessary support burden on us as a consequence.

When we figure out how and when --sdk should be used, we'll update the help output and our documentation and unhide this option. Until then we'll do ourselves and end users a big favour by reducing the confusion hiding it from --help.

[finagolfin]

Completely agree, these flags were added five years ago as a simple hack in #2604 to give users CLI overrides over the original destination JSON format, which has changed since then and the flags haven't kept up.

I'm looking into changing --triple to work with the new JSON format in #9229 and will update that flag's help also there, but these two should be hidden until we get them working well again.