Go binding

This package exposes the existing Verovio C API to Go through cgo.

NewToolkit() first checks VEROVIO_RESOURCE_PATH. If that variable is unset, it creates a toolkit without configuring a resource directory.

Required files and paths

To use this binding, your system needs all of the following:

the Go package source in bindings/go
the Verovio shared library: libverovio.dylib on macOS or libverovio.so on Linux
the generated pkg-config file: verovio.pc
the Verovio runtime resources directory: share/verovio

With the example install prefix below, those paths are:

shared library: $PWD/build/go/install/lib/libverovio.dylib
pkg-config metadata: $PWD/build/go/verovio.pc
runtime resources: $PWD/build/go/install/share/verovio

Build and install Verovio

Build and install Verovio as a shared library so pkg-config can locate libverovio and the exported headers:

cd bindings
cmake ../cmake -B go -DBUILD_AS_LIBRARY=ON -DCMAKE_INSTALL_PREFIX="../build/go/install"
cmake --build go -j8
cmake --install go

This will install the build in build/go/install (from the Verovio root directory). Note that this directory needs to be available to any Go project you build since the Go compiler needs to resolve the built Verovio library, so if you need it anywhere else, you should vary the -DCMAKE_INSTALL_PREFIX value, and then adjust the paths below as necessary.

Environment variables

You typically need three environment variables:

PKG_CONFIG_PATH Build-time lookup path for verovio.pc
DYLD_LIBRARY_PATH on macOS or LD_LIBRARY_PATH on Linux Runtime lookup path for libverovio
VEROVIO_RESOURCE_PATH Runtime lookup path for the Verovio font and resource files in share/verovio

Example for macOS, assuming your build artifacts are in /path/to/verovio/build as per the CMAKE_INSTALL_PREFIX setting:

export PKG_CONFIG_PATH="/path/to/verovio/build/go"
export DYLD_LIBRARY_PATH="/path/to/verovio/build/go/install/lib"
export VEROVIO_RESOURCE_PATH="/path/to/verovio/build/go/install/share/verovio"

Example for Linux:

export PKG_CONFIG_PATH="/path/to/verovio/build/go"
export LD_LIBRARY_PATH="/path/to/verovio/build/go/install/lib"
export VEROVIO_RESOURCE_PATH="/path/to/verovio/build/go/install/share/verovio"

What each path is used for:

PKG_CONFIG_PATH Used by go build and go test through cgo so the compiler/linker can find Verovio headers and link flags.
DYLD_LIBRARY_PATH or LD_LIBRARY_PATH Used when your program or tests start, so the dynamic loader can find libverovio.
VEROVIO_RESOURCE_PATH Used by NewToolkit() so Verovio can find fonts and resource XML/CSS files at runtime.

If VEROVIO_RESOURCE_PATH is missing or wrong, you will usually see an error like:

[Error] The data cannot be loaded because the font resources are not available

Testing the binding

After setting the variables above:

cd bindings/go
go test

Example

package main

import (
	"fmt"

	verovio "github.com/rism-digital/verovio/bindings/go"
)

func main() {
	tk := verovio.NewToolkit()
	defer tk.Close()

	tk.LoadData(`<?xml version="1.0" encoding="UTF-8"?>
<mei meiversion="4.0.1" xmlns="http://www.music-encoding.org/ns/mei"><music><body><mdiv><score><scoreDef meter.count="4" meter.unit="4"><staffGrp><staffDef n="1" lines="5" clef.shape="G" clef.line="2"/></staffGrp></scoreDef><section><measure n="1"><staff n="1"><layer n="1"><note oct="4" pname="c" dur="4"/></layer></staff></measure></section></score></mdiv></body></music></mei>`)
	fmt.Println(tk.RenderToSVG(1, false))
}

A music notation engraving library