Packages instances documentation clarity

cue-lang / cue

The home of the CUE language! Validate and define text-based and dynamic configuration

Apache License 2.0

5.14k stars 294 forks source link

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.

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 }

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?

cue-lang / cue