doc: package import example

[cueckoo]

Originally opened by @fabxc in cuelang/cue#41

I can't seem to get import of a local package to work. An example would be great. Maybe that could be folded into kubernetes/manual?

[cueckoo]

Original reply by @mpvl in cuelang/cue#41 (comment)

Yes, this is not documented yet. At least not properly, partly because it is very new. The cue tool (not language) assumes files are layed out in a directory tree. You can mark the root with an empty cue.mod file, which will ultimately hold more configuration. In that same directory, there can be a pkg directory.

import "path" looks for the directory rooted at pkg and loads all files in that directory as a single package, with the package name as the identifier (conventionally the base of the dir). If you know Go, this is pretty much exactly how Go works. And like Go, the first path component is a simple identifier for core packages, whereas for non-core packages it starts with a domain name.

The pkg directory is somewhat like a vendor directory. It is also the destination for code generation, though. For instance
cue get go k8s.io/api/extensions/v1beta1 github.com/prometheus/prometheus/pkg/rulefmt
will get down the respective go packages transitively, analyses how types would be marshalled with encoding/json (or yaml) and then generates CUE templates from that.
Generated files end with _gen.cue. Users may add other cue files in the same directories to augment the definitions, although ideally that should be done elsewhere.

[cueckoo]

Original reply by @xinau in cuelang/cue#41 (comment)

If somebody like me also stumbles about this issue and needs a quick fix. I hope the following change to the documentation helps https://cue-review.googlesource.com/c/cue/+/2601.

[cueckoo]

Original reply by @joshburkart in cuelang/cue#41 (comment)

I actually can't figure out how to perform imports the way I expect... Is it possible to have two files in some directory, foo.cue and bar.cue, and import foo.cue from bar.cue? When I try this naively, I get an error:

// foo.cue
a: 7

// bar.cue
import "foo"
b: foo.a

// Command line
 $ cue eval bar.cue 
package "foo" not found:
    ./bar.cue:1:8
terminating because of errors

I know I can remove the import statement, put e.g. package blah on the first line of both files, and then run cue eval bar.cue foo.cue, which works. But that's not the type of modularity I'm used to... I prefer explicit linkages between files...

[cueckoo]

Original reply by @xinau in cuelang/cue#41 (comment)

@joshburkart could you provide a more detailed view of your directory layout. Since as far as I understand it cue packages need to reside in the pkg directory beside your cue.mod file (this file can be empty). Something like the following:

$ tree .       
.
├── bar.cue
├── cue.mod
└── pkg
    └── foo
        └── foo.cue

2 directories, 3 files

And if I'm not mistaken your foo.cue file needs the following package directive package foo at the top. Maybe the following change does help https://cue.googlesource.com/cue/+/refs/changes/01/2601/6/doc/tutorial/basics/instances.md#modules

[cueckoo]

Original reply by @mpvl in cuelang/cue#41 (comment)

@joshburkart: CUE uses Go-like importing, which only happens at the package level, not file level. So typically you don't import files from within the same directory. Instead, files marked with the same package directory can see each other's top-level symbols.

The works extra well in CUE: as order doesn't matter, you can just lump definitions together.

But yes, this is not well documented. Like with Go, package organization is not part of the language spec, so you can't find how this works in the spec. But documentation for this is in the works and coming soon. See @xinau 's CL for now.

[cueckoo]

Original reply by @joshburkart in cuelang/cue#41 (comment)

@mpvl @xinau Thanks so much for the responses! I'll try to wrap my head around Go-style imports. :)

[cueckoo]

Original reply by @joshburkart in cuelang/cue#41 (comment)

@xinau I tried to follow your demo (thanks!), but unfortunately couldn't get it to work... Any help would be appreciated...

Here's my directory layout:

 $ tree
.
├── channels_demo.cue
├── cue.mod
└── pkg
    └── schemas
        └── channel
            └── channel.cue

3 directories, 3 files

File contents:

# cue.mod (empty)

# channel.cue:

package channel

Channel: {
    name: string
}

# channels_demo.cue:

package demo

import "schemas/channel"

channels: [...channel.Channel] & [
    channel.Channel & {name: "blah"},
]

Invocation attempt:

 $ cue eval channels_demo.cue 
package "schemas/channel" not found:
    ./channels_demo.cue:3:8
terminating because of errors

[cueckoo]

Original reply by @mpvl in cuelang/cue#41 (comment)

Like with Go, the first path component of a package path must be a domain name (and thus have a "." in the name). This gives it a globally unique name.

Like Go, CUE also uses this to distinguish between builtin packages and external ones.

A first version of the website is up. A concepts section with a special section on packages and modules is high on the list of things to write next.

[cueckoo]

Original reply by @joshburkart in cuelang/cue#41 (comment)

Thanks; I'll give that a try.

New website looks awesome!