Nice thank you!
I’m slightly confused about the PR title. Is this only referring to daml-head as that one sets the environment variable? Once you’ve created a project with daml-head new, it will just pick up the version from daml.yaml so this shouldn’t change much.

Updated title: it was meant to be the env var, so DAML_SDK_VERSION.

daml-head sets the env var before calling daml, so I believe it ignores daml.yaml for that. It does bring this issue though:

$ daml-head version
DAML SDK versions:
  0.0.0                                    (selected by env var DAML_SDK_VERSION)
  1.4.0                                    (project SDK version from daml.yaml)
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3

As a user, this does not leave me with a clear answer as to which version I'm using. Any suggestion on how to deal with that?

I'd always just show one indicator:

Inside a project:

DAML SDK versions:
  0.0.0
  1.4.0                                    (project SDK version from daml.yaml)
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3

Outside a project without an env variable:

DAML SDK versions:
  0.0.0
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3  (default SDK version for new projects)

Outside a project with an env variable:

DAML SDK versions:
  0.0.0                                    (selected by env var DAML_SDK_VERSION)
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3

I think your last point should probably be Inside a project with env var. Personally I find it useful to see the version in the daml.yaml even if I have an env var. Maybe we can add overridden by env var to the version in the daml.yaml or overrides version in daml.yaml to the env var.

Perhaps a star like git branch? Or a more detailed output, like:

DAML SDK versions installed:
  0.0.0
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3
SDK version selected:
* 0.0.0 (env var SDK_DAML_VERSION)
  1.4.0 (/full/path/to/daml.yaml)
  1.5.0 (default)

I like the star!

I don't really like this approach as it seems messy both in implementation and for the user. They have to read all the way to the end of the line to find out that it overrides, and there is nothing on the 1.4 line that indicates it's not actually selected.

The more I think about it the less I believe we can get something clear without having a separate section. If you don't like the star, how about:

DAML SDK versions installed:
  0.0.0
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3
SDK version selected:
  using 0.0.0 from env var SDK_DAML_VERSION
  ignoring 1.4.0 from /full/path/to/daml.yaml
  ignoring 1.5.0 (default)

Without the env var set that would become:

DAML SDK versions installed:
  0.0.0
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3
SDK version selected:
  ignoring env var SDK_DAML_VERSION (unset)
  using 1.4.0 from /full/path/to/daml.yaml
  ignoring 1.5.0 (default)

and without a project:

DAML SDK versions installed:
  0.0.0
  1.4.0
  1.5.0-snapshot.20200811.4959.0.bbc2fe56
  1.5.0-snapshot.20200818.5027.0.1b33d374
  1.5.0-snapshot.20200902.5118.0.2b3cf1b3
SDK version selected:
  ignoring env var SDK_DAML_VERSION (unset)
  ignoring daml.yaml (not found)
  using 1.5.0 (default)

In addition to being extra clear, this also makes the various ways to set the version used discoverable.

@cocreature I did mean "Outside a project with an env variable:". I thought daml.yaml would take precedence over environment variable. My rationale for thinking that is:

• Global Default (latest installed) is lowest specificity
• Global override (env var) is higher specificity
• Local override (daml.yaml) is highest specificity

I can see how the specificity could be interpreted in the opposite direction if we consider the env var a command override DAML_SDK_VERSION=0.0.0; daml ... or a terminal session override. The reason I stumbled into this in the first place was that I had set the SDK version using an export statement and then had unexpected behaviour.

The env var takes precedence over the project version atm and we do have users relying on that, e.g., they pull in finlib and want to compile it in the current version so rather than trying to patch the file, they set the env var. This behavior is also explicitly documented with exactly this usecase.

@garyverhaegen-da Could you finish merging this PR and open an issue for making the "SDK version selection process" clearer for users in daml version, as you just suggested? It feels like a promising approach but also a bit different from this PR, and more involved. This PR is already a step in the right direction.