Do instances only exist for packages within a CUE module?

[seh]

Continuing from preceding discussion in the "language" channel (see below) of the "CUE" Slack workspace, when one invokes the cue tool against a set of CUE files that lack a package declaration, is that still considered to be processing an instance, or do instances only exist for packages within a CUE module?

My repeated reading of the “Instances” document tells me that the instance concept only makes sense within modules, as it’s both disambiguating a view of a package (among many potential views across the module’s directories) and combining files in a way that’s only sensible in the context of a module.

The CUE source code is less clear on the matter. Looking at the Instance struct type, I see that the “Module” field is optional. The cueFilesPackage function returns a *build.Instance, and cue calls on that function to load the files listed on the command line. Is a build.Instance the same as the notional instance involving file ancestry within a module?

Slack conversation history

seh 6 May at 16:56

When one invokes the cue tool against a set of CUE files that lack a package declaration, is that still considered to be processing an instance, or do instances only exist for packages within a CUE module?

---

Tony Worm 25 days ago

they get an implicit "main" package applied behind the scenes iirc

seh 25 days ago

And is that then an instance of that synthesized package?

Tony Worm 25 days ago

My understanding is that is a package like any other

seh 25 days ago

I get that, but CUE uses instances to distinguish between multiple views or subsets of the same nominal package. In this case, there can be only one view of it, but I don’t know if that’s still considered to be an instance or not.

seh 25 days ago

Based on the discussion here, it sounds like the answer could be no, because there are no transitive ancestor directories to consider, since we’re not in a module.Then again, the answer could instead be yes, but with an empty set of ancestor directories, for lack of a module.

seh 25 days ago

Looking at the Instance struct defined here, I see that the “Module” field is optional.

instance.go

// An Instance describes the collection of files, and its imports, necessary  
// to build a CUE instance.  
//  
// A typical way to create an Instance is to use the cue/load package.  
type Instance struct {  

Tony Worm 24 days ago

One thing I've never been clear on is when load.Instances would return more than one instance. I haven't seen it do so in my code anyhow

seh 24 days ago

And here, the cueFilesPackage function returns an Instance.

loader.go

func (l *loader) cueFilesPackage(files []*build.File) *build.Instance {  
    pos := token.NoPos  
    cfg := l.cfg  
    cfg.filesMode = true  
    // ModInit() // TODO: support modules  

[mpvl]

is that still considered to be processing an instance

I'm missing the Slack context, but it is a bit of semantics here. It creates an on-the-fly instance, but I don't think that answers your question.

Here are some orthogonal rules:

1. A file may import other CUE instances only if it is within a module.
2. To allow files to import other instances from the same module, the module must be named (e.g. "example.com/foo").
3. Files selected by the user on the command line must have the same package name or be anonymous.
4. Files that have a package declaration with the same name, and are part of the same instance, may refer to each other's top-level fields. This is also true for files specified on the command line.

The API can return an Instance for instances in the strictest sense and for instances created by users on the fly by specifying a bunch of files. Note that we intend to deprecate the Instance type. It just causes confusion and makes the API more cumbersome to use. Most of the API can be used without the need for an Instance.

[seh]

Thank you, Marcel. This is helpful. Please indulge me with a few clarifications:

Files selected by the user on the command line must have the same package name or be anonymous.

Does this mean that of all the files specified on the command line, if any have a package, that package must match the package of any other files that also specify a package, but that any of the files can lack a package? In other words, can this be a mixture of in-package and non-packaged files, so long as the in-package files are all members of the same package?

This is also true for files specified on the command line.

Here, I take it you mean files specified on the command line that are in a package. I thought that each file without a package is treated in isolation, as opposed to forming an ad hoc, unnamed package shared by all files that do not declare a package.

[myitcv]

Does this mean that of all the files specified on the command line, if any have a package, that package must match the package of any other files that also specify a package, but that any of the files can lack a package? In other words, can this be a mixture of in-package and non-packaged files, so long as the in-package files are all members of the same package?

Correct.

Here, I take it you mean files specified on the command line that are in a package.

Correct.

[myitcv]

(For the record, I edited the original question here to include the conversation history (copy-pasted via https://stackedit.io which does a very nice job of converting rich-text rendered in the Slack (web) app to markdown))

[cueckoo]

This discussion has been migrated to cue-lang/cue#973.

For more details about CUE's migration to a new home, please see cue-lang/cue#1078.