Improve UI for `stack setup --stack-setup-yaml` option

[spl]

Is the --stack-setup-yaml flag ignored by stack setup? If I pass something with that flag, it doesn't seem to affect the operation. The only place I see --stack-setup-yaml mentioned is in the Changlog entry for v0.1.5.0.

The reason I'm bringing this up is that I was confused for a bit trying to specify a different stack.yaml file other than the default. I eventually realized it should be stack --stack-yaml <file> setup. So having both stack setup --stack-setup-yaml <file> and stack --stack-yaml <file> setup is confusing. If --stack-setup-yaml is not being used, I think it should be removed.

[sjakobi]

Did you see the help text?

~ $ stack setup --help
...
  --stack-setup-yaml ARG   Location of the main stack-setup.yaml
                           file (default: "https://raw.githubusercontent.com/fpco/stackage-content/master/stack/stack-setup-2.yaml")
...

Given that the option causes a failure when supplied with a bogus argument

~ $ stack --stack-root ~/.tmp-sr setup --stack-setup-yaml bla
Using latest snapshot resolver: lts-7.1
Writing implicit global project config file to: /home/simon/.tmp-sr/global-project/stack.yaml
Note: You can change the snapshot via the resolver field there.Downloaded lts-7.1 build plan.    Fetched package index.                                                                    
Populated index cache.
bla: openBinaryFile: does not exist (No such file or directory)

and succeeds when supplied with the default argument

~ $ stack --stack-root ~/.tmp-sr setup --stack-setup-yaml https://raw.githubusercontent.com/fpco/stackage-content/master/stack/stack-setup-2.yaml
Preparing to install GHC to an isolated location.
This will not interfere with any system-level installation.
Downloaded ghc-8.0.1.                                      
Installed GHC.                                                                  
stack will use a sandboxed GHC it installed
For more information on paths, see 'stack path' and 'stack exec env'
To use this GHC and packages outside of a project, consider using:
stack ghc, stack ghci, stack runghc, or stack exec

it seems to work as intended.

The option probably didn't have an effect in your case as the compiler was already present.

Given that no corresponding config.yaml option is documented at https://docs.haskellstack.org/en/stable/yaml_configuration/, I'd believe that there is little use for the flag, so maybe it can indeed be removed?!

If it stays, the help text should be made clearer (it doesn't say what the file is used for), and it should be checked if the argument is actually a URL.

[decentral1se]

Introduced with 54c34c5. It's over a year old. What would be a better description? Here's a stab:

URL of stack.yaml for setup related .tar files

Probably needs the name of the issue changed to be more relevant.

[spl]

@sjakobi:

Did you see the help text?

I did see it. That's where I got the idea to use the flag from. Am I supposed to know what “the main stack-setup.yaml” is? As I said, I didn't find anything documenting that flag or the help text.

Given that the option causes a failure when supplied with a bogus argument

It doesn't always fail. This is what I saw:

$ stack setup --stack-setup-yaml stack-ghc-yaml
stack will use a sandboxed GHCJS it installed
For more information on paths, see 'stack path' and 'stack exec env'
To use this GHCJS and packages outside of a project, consider using:
stack ghc, stack ghci, stack runghc, or stack exec

Actually, that should not be using GHCJS since the stack-ghc.yaml is for GHC while there is a stack.yaml file in the same directory for GHCJS. Hence, my observation that (1) it didn't fail and (2) it didn't seem to affect anything.

Since you point out that it fails for a nonexistent file, I wonder what it's doing with the file I provide. I ran stack setup --verbose and stack setup --stack-setup-yaml stack-ghc-yaml --verbose and diffed the outputs: the only differences were timestamps.

@lwm:

I'm also not sure what a “stack.yaml for setup related .tar files” is. This doesn't mean the message needs to be more verbose, but whatever is put there perhaps could be expanded on with documentation in the guide.

It seems that stack.yaml has a particular semi-consistent meaning across uses and documentation, and it seems that this file serves a different purpose. If you do want to keep it, would you consider using a different term that doesn't include some extension of stack.yaml in it? Perhaps something like setup.yaml?

[sjakobi]

Did you see the help text?

I did see it. That's where I got the idea to use the flag from. Am I supposed to know what “the main stack-setup.yaml” is?

Ok, that confirms that the option info needs to be improved. ;)

Actually, that should not be using GHCJS since the stack-ghc.yaml is for GHC while there is a stack.yaml file in the same directory for GHCJS. Hence, my observation that (1) it didn't fail and (2) it didn't seem to affect anything.

Since you point out that it fails for a nonexistent file, I wonder what it's doing with the file I provide. I ran stack setup --verbose and stack setup --stack-setup-yaml stack-ghc-yaml --verbose and diffed the outputs: the only differences were timestamps.

As I indicated above, the argument isn't used unless a compiler (or other tool) has to be downloaded. In your case the compiler was determined by your project's default stack.yaml and already present on the system.

It seems that stack.yaml has a particular semi-consistent meaning across uses and documentation, and it seems that this file serves a different purpose. If you do want to keep it, would you consider using a different term that doesn't include some extension of stack.yaml in it? Perhaps something like setup.yaml?

How about --setup-info-yaml? That would also create a link to the setup-info config option.

The argument metavar should also be URL instead of ARG to be more clear.

For the help text, how about

URL of yaml file that contains metadata for various tools that stack relies on (default …)

?

[spl]

@sjakobi:

As I indicated above, the argument isn't used unless a compiler (or other tool) has to be downloaded.

Okay, now I finally understand what the flag does: it indicates where tools are downloaded from and is only used if a download is needed. That was not clear from the statement that “the option probably didn't have an effect in your case as the compiler was already present.” Perhaps the above would be a good note to have in the help text or documentation.

How about --setup-info-yaml? That would also create a link to the setup-info config option.

That's interesting. Is it reasonable to describe the argument to --stack-setup-yaml as the default setup-info? If so, then yes, I could see --setup-info-yaml being more informative and less confusing.

As for the help text, would it be better to be more specific and refer to sources for download (rather than use a vague term such as “metadata”), as mentioned in the setup-info documentation? Or does the file actually serve a more general purpose than that? (But even if its purpose is more general, maybe it's not necessary to mention the full generality.)

[sjakobi]

Just a quick note: the --stack-setup-yaml option can actually take a local filepath as an argument too!

Also, this is a valid config.yaml setting:

setup-info: https://raw.githubusercontent.com/fpco/stackage-content/master/stack/stack-setup-2.yaml

Both things should be documented.

Oh, and given that this command-line flag is only the analogon to the setup-info config option, I guess we can stop considering its removal.

PRs welcome!