Golang bindings

Golang bindings allow you to use ICICLE as a golang library. The source code for all Golang libraries can be found here.

The Golang bindings are comprised of multiple packages.

core which defines all shared methods and structures, such as configuration structures, or memory slices.

cuda-runtime which defines abstractions for CUDA methods for allocating memory, initializing and managing streams, and DeviceContext which enables users to define and keep track of devices.

Each curve has its own package which you can find here. If your project uses BN254 you only need to install that single package named bn254.

Using ICICLE Golang bindings in your project

To add ICICLE to your go.mod file.

go get github.com/ingonyama-zk/icicle

If you want to specify a specific branch

go get github.com/ingonyama-zk/icicle@<branch_name>

For a specific commit

go get github.com/ingonyama-zk/icicle@<commit_id>

To build the shared libraries you can run this script:

./build <curve> [G2_enabled]

curve - The name of the curve to build or "all" to build all curves
G2_enabled - Optional - To build with G2 enabled 

For example if you want to build all curves with G2 enabled you would run:

./build.sh all ON

If you are interested in building a specific curve you would run:

./build.sh bls12_381 ON

Now you can import ICICLE into your project

import (
    "github.com/stretchr/testify/assert"
    "testing"

    "github.com/ingonyama-zk/icicle/wrappers/golang/core"
    cr "github.com/ingonyama-zk/icicle/wrappers/golang/cuda_runtime"
)
...

Running tests

To run all tests, for all curves:

go test --tags=g2 ./... -count=1

If you dont want to include g2 tests then drop --tags=g2.

If you wish to run test for a specific curve:

go test <path_to_curve> -count=1

How do Golang bindings work?

The libraries produced from the CUDA code compilation are used to bind Golang to ICICLE's CUDA code.

1. These libraries (named libingo_<curve>.a) can be imported in your Go project to leverage the GPU accelerated functionalities provided by ICICLE.

2. In your Go project, you can use cgo to link these libraries. Here's a basic example on how you can use cgo to link these libraries:

/*
#cgo LDFLAGS: -L/path/to/shared/libs -lingo_bn254
#include "icicle.h" // make sure you use the correct header file(s)
*/
import "C"

func main() {
    // Now you can call the C functions from the ICICLE libraries.
    // Note that C function calls are prefixed with 'C.' in Go code.
}

Replace /path/to/shared/libs with the actual path where the shared libraries are located on your system.