docs: better documentation for cue/load package

[ckkkcsg]

const label_traitdef = `
	import "k8s.io/api/core/v1"

	parameter: {
		endpoints: v1.#Endpoints
	}
    output: {
		//endpoints: parameter.endpointSubset[0].address[0]
		for subset in parameter.endpoints.subsets {
			endpoints: #Endpoints & [
				for addr in subset.address {
					ip: addr.ip
				}
				for po in subset.ports {
					port: po.port
				}
			]
		}
		
    }
`

 func test()  {
	ctx := cuecontext.New()

	value := ctx.CompileString(label_traitdef)
	if value.Err() != nil {
		fmt.Println("load error:", value.Err())
		return
	}
 }

i used "go get k8s.io/api/core/v1", "cue get go k8s.io/api/core/v1"

i got error: "load error: package "k8s.io/api/core/v1" imported but not defined in (and 1 more errors)"

I've read the document, but I don't understand it

[verdverm]

You need to use the cue/load Go package to support imports

[rogpeppe]

@ckkcsg Thanks for the report.

Here's a self-contained example of how to do what you want. Use the testscript command to run this example. I'm going to repurpose this issue as a failure in documentation, because it should be clearer how to do this kind of thing, but it's not actually an bug as such.

exec go get k8s.io/api/core/v1
exec cue get go k8s.io/api/core/v1
exec go mod tidy
exec go run .

-- cue.mod/module.cue --
module: "example.com/m"
-- go.mod --
module example.com/m

go 1.18

require cuelang.org/go v0.4.2

require (
	github.com/cockroachdb/apd/v2 v2.0.1 // indirect
	github.com/google/go-cmp v0.5.5 // indirect
	github.com/google/uuid v1.2.0 // indirect
	github.com/kr/pretty v0.2.0 // indirect
	github.com/kr/text v0.2.0 // indirect
	github.com/mpvl/unique v0.0.0-20150818121801-cbe035fff7de // indirect
	github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e // indirect
	github.com/pkg/errors v0.9.1 // indirect
	github.com/stretchr/testify v1.7.0 // indirect
	golang.org/x/net v0.0.0-20211209124913-491a49abca63 // indirect
	golang.org/x/text v0.3.7 // indirect
	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
	gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f // indirect
	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
)
-- m.go --
package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"cuelang.org/go/cue"
	"cuelang.org/go/cue/cuecontext"
	"cuelang.org/go/cue/load"
)

const code = `
package m

import "k8s.io/api/core/v1"

parameter: endpoints: v1.#Endpoints
`

func main() {
	wd, err := os.Getwd()
	if err != nil {
		log.Fatal(err)
	}
	ctx := cuecontext.New()
	_, err = loadInstance(ctx, ".", &load.Config{
		Overlay: map[string]load.Source{
			filepath.Join(wd, "code.cue"): load.FromString(code),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("ok")
}

// loadInstance loads a CUE instance from the given CUE package path
// in the context of ctx and using config as load configuration.
func loadInstance(ctx *cue.Context, path string, config *load.Config) (cue.Value, error) {
	insts := load.Instances([]string{path}, config)
	if len(insts) != 1 {
		return cue.Value{}, fmt.Errorf("unexpected instance count")
	}
	if err := insts[0].Err; err != nil {
		return cue.Value{}, fmt.Errorf("cannot load CUE instances: %w", err)
	}
	vals, err := ctx.BuildInstances(insts)
	if err != nil {
		return cue.Value{}, fmt.Errorf("cannot build instances: %w", err)
	}
	if len(vals) != 1 {
		return cue.Value{}, fmt.Errorf("wrong value count")
	}
	val := vals[0]
	if err := val.Err(); err != nil {
		return cue.Value{}, fmt.Errorf("cannot build configuration: %w", err)
	}
	return val, nil
}

[rogpeppe]

Specific docs suggestions:

• better docs for load.Config fields: it's not clear that ModuleRoot is a directory rather than a module path; it's not clear that overlay paths cannot be relative.
• point towards the cue/load package from the lower level Context.Compile* methods.