What is evalv3?

evalv3 is a new major version of the CUE evaluator which brings many enhancements, such as:

  • a new disjunction algorithm
  • a new cycle detection algorithm
  • a new closedness algorithm, and
  • a new cue trim algorithm.

Most importantly, the new version unlocks many performance improvements which target larger CUE configurations.

The old evaluator, evalv2, is affected by dozens of bugs which would have been very difficult to fix incrementally due to limitations in its design. Many of these bugs are already fixed in evalv3, with more improvements still to come.

How can I switch to evalv3?

You can switch to evalv3 by setting the CUE_EXPERIMENT=evalv3=1 environment variable. This variable affects invocations of the cue command (such as cue export) as well as Go programs using CUE’s Go API such as cue/load.

Users of the Go API can also directly specify the evaluator version with a cuecontext option:

main.go
package main

import (
	"cuelang.org/go/cue/cuecontext"
	"fmt"
)

func main() {
	ctx := cuecontext.New(cuecontext.EvaluatorVersion(cuecontext.EvalV3))
	v := ctx.CompileString("42")
	fmt.Println(v)
}

Which CUE version do I need to use evalv3?

We strongly recommend that you upgrade to the latest release of CUE before you try evalv3 as the new evaluator is under active development – otherwise you may run into bugs or performance issues which have already been fixed. The latest release is currently:

TERMINAL
$ cue version
cue version v0.12.0
...

If you encounter any unexpected issues, we would also encourage you to try evalv3 on the development version of CUE, as your issue may have already been fixed since the latest release.

What might break when I switch to evalv3?

We expect the vast majority of users to be able to upgrade to evalv3 seamlessly, thanks to the continuous testing of third party projects provided by Unity. Add your project to the Unity corpus to ensure it is tested with future language and evaluator changes.

If you encounter a new bug which still happens with the development version of CUE, and it’s not already tracked on GitHub, please file a new bug report with details.