embed: document how to use embedding from the Go API

[mvdan]

As @DavidGamba points out in #3264 (comment), it's not at all obvious how to use CUE_EXPERIMENT=embed from the Go API. He shows a snippet like:

ctx := cuecontext.New(cuecontext.Interpreter(embed.New())

This is basically what cmd/cue does.

However, note that unlike CUE_EXPERIMENT=evalv3 or CUE_EXPERIMENT=toposort, simply using os.Setenv("CUE_EXPERIMENT", "embed") will not make embedding work out of the box; this is because cue/interpreter/embed imports cue/cuecontext for various reasons, so cuecontext cannot import embed to enable it following CUE_EXPERIMENT.

This gets trickier once CUE_EXPERIMENT=embed is on by default; presumably we would want it to work out of the box with cuecontext.New just like it would for cmd/cue.

It's a different story if we want embedding to be opt-in for the Go API even though it would always be on for the cmd/cue CLI. Personally I would find that a bit puzzling, but we haven't explicitly made a choice as part of the proposal design.

My instinct is that we should make cuecontext.New enable embedding out of the box just like cmd/cue does, but note that this would require untangling the import cycle caused by it. My instinct is that we want to untangle that anyway; having low-level packages like internal/filetypes depend on a high-level public package like cue/cuecontext is going to cause other trouble down the line.

[rogpeppe]

Relevant issue: #3280

[mvdan]

Indeed, if we could resolve that and avoid loading/evaluating CUE at init time in the filetypes package, then untangling this cycle would be much more feasible :)