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.