Introduction
In this tutorial you will use CUE’s Go API to work with a CUE module dependency fetched from the Central Registry.
Along the way you will:
- Login to the Central Registry, and authenticate the
cue
command - Create a CUE module that depends on an existing, well-known module
- Use
cue mod tidy
to fetch and organise your module’s dependencies - Load your CUE using the Go API working in a modules-aware mode
Prerequisites
- Access to the Central Registry – if you need to practise using the Central Registry, then first follow the tutorial Working with modules and the Central Registry
- A tool to edit text files – any text editor you have will be fine; for example: VSCode or Vim
- A command terminal – the
cue
command works on all platforms; use any terminal on Linux or macOS, or PowerShell,cmd.exe
or WSL on Windows. - An installed
go
binary – installation details - An installed
cue
binary – installation details
This tutorial uses the following version of CUE:
$ cue version
cue version v0.10.1
...
Set up the cue
command
Authenticate the cue
command with the Central Registry:
$ cue login
Later in this tutorial the cue
command will fetch a well-known module from
the Central Registry, which requires authentication.
Create a CUE module
Initialize a new main CUE module in an empty directory:
$ cue mod init an.example/config@v0
You won’t publish this module, so the name you give it is unimportant.
Create the file main.cue
, holding the code for the main module:
package config
import "github.com/cue-labs/examples/frostyconfig@v0"
config: frostyconfig.#Config & {
appName: "alpha"
port: 80
features: logging: true
}
Your main module defines some concrete values for a configuration,
constrained by the frostyconfig.#Config
schema.
frostyconfig
package first introduced in the tutorial
Working with a custom module registry.
You don’t need to follow that tutorial right now - it’s only mentioned for context.Ensure the CUE module is tidy:
$ cue mod tidy
This fetches the frostyconfig
module (and any dependencies it might have)
from the Central Registry.
Export the configuration from your CUE module:
$ cue export
{
"config": {
"appName": "alpha",
"port": 80,
"features": {
"logging": true
}
}
}
This export shows that your CUE is valid and you can successfully use a dependency from the Central Registry.
Create a Go module and program
Initialize a Go module for your program:
$ go mod init an.example/config
...
You won’t publish this module, so the name you give it is unimportant.
Create the file main.go
containing this Go program:
package main
import (
"fmt"
"log"
"cuelang.org/go/cue"
"cuelang.org/go/cue/cuecontext"
"cuelang.org/go/cue/load"
"cuelang.org/go/mod/modconfig"
)
func main() {
ctx := cuecontext.New()
// Create a registry client. Passing a nil config
// will give us client that behaves like the cue command.
reg, err := modconfig.NewRegistry(nil)
if err != nil {
log.Fatal(err)
}
// Load the package from the current directory.
// We don't need to specify a Config in this example.
insts := load.Instances([]string{"."}, &load.Config{
Registry: reg,
})
// The current directory just has one file without any build tags,
// and that file belongs to the example package, so we get a single
// instance as a result.
v := ctx.BuildInstance(insts[0])
if err := v.Err(); err != nil {
log.Fatal(err)
}
// Lookup the 'config' field and print it out
config := v.LookupPath(cue.ParsePath("config"))
fmt.Println(config)
}
This program loads the CUE package in the current directory,
and then prints a message based on the config
field.
Add a dependency on cuelang.org/go
and ensure the Go module is tidy:
$ go get cuelang.org/go@v0.10.1
...
$ go mod tidy
...
You can use @latest
in place of the specific version mentioned here.
Run the Go program
Run the Go program:
$ go run .
{
appName: "alpha"
port: 80
features: {
logging: true
}
}
Summary
Well done - you’ve finished this tutorial! In completing it, you:
- created a main module that depends on a well-known module from the Central Registry, and
- used the Go API to load the main module, transparently using the module’s dependencies.
Related content
- Reference: CUE Modules
- Tutorial: Working with a custom module registry