Announcing qml v1 for Go

After a few weeks of slow progress on the qml package for Go, action is starting again.

The first important change is the release of the new v1 API, which is motivated by conversations and debugging sessions we’ve had at GopherCon back in April. The problem being solved is that Mac OS requires its graphic activities to be held in the first thread in the running process, and that’s incompatible with the API provided by the qml package in v0.

In practice, code in v0 looked like this:

func main() {
        qml.Init(nil)
        engine := qml.NewEngine()
        ...
}

This interface implies that logic must continue running in the initial goroutine after the GUI initialization is performed by qml.Init. Internally qml.Init will spawn a goroutine which will take over a process thread to hold the main GUI loop, and this works fine in most OSes, and used to work okay in Mac OS too, probably by chance (there’s a chance the thread locked up is the first one), but recently it started to fail more consistently and enabled the problem to be more clearly spotted and solved.

The solution requires a minor incompatible change. In v1, the initialization procedure takes the following form:

func main() {
        err := qml.Run(run)
        ...
}

func run() error {
        engine := qml.NewEngine()
        ...
}

This subtle change allows the qml package to deterministically take over the initial process thread for running the GUI loop, and is all that needs to change for an application to be initialized under the new API.

This issue also affects testing, but qml.Run isn’t suitable in those cases because the “go test” machinery doesn’t provide an appropriate place for calling it. As a good workaround, the GUI loop may be setup from an init function within any *_test.go file with:

func init() { qml.SetupTesting() }

With that in place, all tests can assume the GUI loop is running and may then use the qml package functionality arbitrarily.

Besides these changes related to initialization, the v1 API will also hold a new GL interface that is still being worked on. The intention was to have that interface ready by the announcement date, but developing the new API in an isolated branch is hindering collaboration on the new package, and is also unfortunate for people that depend on the Mac OS fixes, so v1 is being released with an unstable gl package under the path "gopkg.in/qml.v1/work-in-progress/gl". This package will suffer significant changes in the coming weeks, so it’s best to avoid publishing any applications that depend on it before it is moved to the final import path.

The package source code, documentation, and import path are referenced from gopkg.in, and to talk about any of these changes please join the mailing list.

Thanks to Andrew Gerrand for the help debugging and testing the new initialization procedure.