search

cue-lang / cue

The home of the CUE language! Validate and define text-based and dynamic configuration
https://cuelang.org
Apache License 2.0
5.12k stars 292 forks source link

cmd/cue: help environment docs do not mention CUE_STATS_FILE #2832

Open jpluscplusm opened 8 months ago

jpluscplusm commented 8 months ago

What version of CUE are you using (cue version)?

$ cue version
cue version v0.8.0-alpha.1

go version go1.22.0
      -buildmode exe
       -compiler gc
       -trimpath true
     CGO_ENABLED 0
          GOARCH amd64
            GOOS linux
         GOAMD64 v1

Does this issue reproduce with the latest stable release?

No; cue help environment does not exist in 0.7.0.

What did you do?

exec cue help environment
grep CUE_STATS_FILE

What did you expect to see?

A passing testscript, indicating that the envvar is explained to some degree.

What did you see instead?

A failing testscript.

mvdan commented 8 months ago

This is sort of intentional. End users should not be using or relying on CUE_STATS_FILE, at least not while we are heavily refactoring the evaluator which is bound to change the format and contents of the stats output.

Why are you interested in this environment variable and file?

jpluscplusm commented 8 months ago

Why are you interested in this environment variable and file?

Because I'm working on https://github.com/cue-lang/docs-and-content/issues/9!

I got as far as explaining some values the envvar can take (https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1176904/1/content/docs/howto/log-statistics-from-the-cue-evaluator/en.md), but I left a TODO in that doc because I don't know definitively what the stats actually mean!

However, that doc doesn't /need/ to explain them, IMHO, so I'm perfectly happy for this to be closed or parked :-)

mvdan commented 8 months ago

Gotcha, that makes sense. I think it's fine to write a tutorial mentioning it today - we can start documenting it more properly, including its format, in cue help environment once the new evaluator has stabilized a bit. We can leave this issue open as a reminder.