Packages instances documentation clarity

[btrepp]

https://cuelang.org/docs/concept/modules-packages-instances/#instances

This documentation implies

./root.cue

package ?
name: string

would unify with
./folder/b.cue

package ?
struct: { test: name}

However I couldn't seem to get the affect described, with any combination of running cue in the leaf folder, and mismatching or matching package names.

I'll accept this could be a me problem, but it could also be a docs bug, because instances are complex. I can't find anything in the discord, or the discussions where someone seems to be able to explain them, not that an example of their usage to help me understand.

At a minimum, this documentation that describes instances could have an explanation and an example. I'd be happy to contribute it, but I have no idea what it's actually trying to tell me currently

Note: I do have a cue.mod folder aswell

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

$ cue version
cue version v0.10.0

go version go1.23.0
      -buildmode exe
       -compiler gc
       -trimpath true
     CGO_ENABLED 0
          GOARCH arm64
            GOOS linux
         GOARM64 v8.0
cue.lang.version v0.10.0

Does this issue reproduce with the latest stable release?

Yes

What did you do?

Followed the description from the docs

What did you expect to see?

Files would unify

What did you see instead?

Error that name is undefined.

Extra notes

Perhaps instances only work for files in cue.mod/pkg? eg being exported as an external package, but then why doesn't it work in a folder that way?

I have tried to get cue for working with packages for a month or so trying to understand this.

At the moment, I am leaning to just use a 'flat folder for cue', and organise by My_folder_file.cue in that folder, as it's a just too complex otherwise. I am sure it's understood by those familiar with the language, but the mental model is just really hard to get out.

I've noticed this is a pretty common struggle among those trying to use cue, so hence raising as a bug, either in the module definition or at least in the docs. As I desperately want to use it, but its behaviours with folders is beyond my understanding.

I've also noticed two patterns for those working around this

1. Preprocess into a flat directory.
2. Use a shell command to dump all the files you need into the cli/import.

That would work, but ideally I would love to use cue modules properly, so I can contribute some modules others could use.

[jpluscplusm]

👋 Hi @btrepp! :-)

I agree - modules, package and instances do need some more docs aimed at "getting started" / "getting up to speed with the fundamental mechanisms that CUE makes available". I'm just in the middle of updating that specific guide to bring it into line with features exposed by recent versions of CUE, but that update didn't extend as far as making it newcomer focused. Writing /that/ guide is definitely high on my list, so please allow me to ask a few questions that will inform it, later!

So here's a txtar reproducer of a very simple instance in action:

exec cue mod init
cd foo
exec cue eval
cmp stdout ../out
-- root.cue --
package foo

name: string
-- foo/folder.cue --
package foo

struct: {
	test: name
}
-- out --
name: string
struct: {
    test: string
}

Running this with https://testscri.pt/ results in a pass, so we know that out matches the cue eval output:

$ testscript demo.txtar 
PASS

Can you extrapolate from that guide's example, and get a similar instance running locally?

If "no", please use the txtar link I gave you above to construct an example that shows us, explicitly and precisely, the problems you're having. Here's a daft example of doing that:

---

Here's my reproducer:

```
exec date
cmp stdout out
-- out --
Thu Jan 01 18:04:10 BST 1999
```

I expected it to pass, but instead I saw this:

```
$ testscript example.txtar
> exec date
[stdout]
Thu Oct 17 18:05:51 BST 2024
> cmp stdout out
diff stdout out
--- stdout
+++ out
@@ -1,1 +1,1 @@
-Thu Oct 17 18:05:51 BST 2024
+Thu Jan 01 18:04:10 BST 1999

FAIL: /tmp/testscript2519812758/example.txtar/script.txtar:2: stdout and out differ
```

Clearly, today *is* Jan 1, 1999 - so what's going wrong?

---

If "yes", then (a) excellent :-) ... and (b) I have a favour to ask!

I'd find it really really useful if you could mentally step back in the debugging process that led to you opening this issue, and try to figure out the gnarly sticking points that prevented you getting to a place of "aaaaah, that all works now!". Why, I guess, the words in the guide you found didn't lead you to a working example. And let me be really clear: this is 100% not because I want you to say "oh yes, I should have got THAT bit right!", but because understanding the newcomer-to-CUE (or newcomer-to-feature-X) experience, and where it falls down and could be improved, is such an incredibly valuable resource for those of us writing the CUE docs! If you were able to articulate the problems you had, that would be super, super useful! :-D