KCL Multiple Language Bindings and SDKs

This repo mainly includes the binding of the low-level API and spec of the KCL language core, and the SDKs of various languages are based on this to encapsulate higher-level APIs.

The prebuilt native runtimes are not on main. go/lib/<platform>/ and wasm/kcl.wasm are ~370MB of compiled binaries, reproducible from the kcl-lang/kcl release of the same version. Development branches do not carry them; run hack/download-libs.sh (add --wasm for the npm package) before building anything that links against the runtime. Release branches and release tags do carry them — see docs/lib-vendoring.md.

Bindings

Rust

cargo add --git https://github.com/kcl-lang/lib

Write the Code

use kcl_lang::*;
use anyhow::Result;

fn main() -> Result<()> {
    let api = API::default();
    let args = &ExecProgramArgs {
        k_filename_list: vec!["main.k".to_string()],
        k_code_list: vec!["a = 1".to_string()],
        ..Default::default()
    };
    let exec_result = api.exec_program(args)?;
    println!("{}", exec_result.yaml_result);
    Ok(())
}

More Rust APIs can be found here. If you want to use the sub crate of KCL Rust core, you can run the following command.

# Take the kcl-runtime as an example.
cargo add --git https://github.com/kcl-lang/kcl kcl-runtime

Go

go get kcl-lang.io/lib

Write the Code

package main

import (
	"fmt"

	"kcl-lang.io/lib/go/api"
	"kcl-lang.io/lib/go/native"
)

func main() {
	client := native.NewNativeServiceClient()
	result, err := client.ExecProgram(&api.ExecProgramArgs{
		KFilenameList: []string{"main.k"},
		KCodeList:     []string{"a = 1"},
	})
	if err != nil {
		t.Fatal(err)
	}
	fmt.Println(result.YamlResult)
}

Full Go SDK can be found here, which depends on the kcl-lang/lib Go bindings.

Java

Refer to this to configure your Maven; set up your GitHub account and Token in the settings.xml.

Maven

In your project's pom.xml, configure our repository as follows:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/kcl-lang/*</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

This way you'll be able to import the above dependency to use the SDK.

<dependency>
    <groupId>com.kcl</groupId>
    <artifactId>kcl-lib</artifactId>
    <version>0.13.1</version>
</dependency>

Write the code

import com.kcl.api.API;
import com.kcl.api.Spec.ExecProgramArgs;
import com.kcl.api.Spec.ExecProgramResult;

public class ExecProgramTest {
    public static void main(String[] args) throws Exception {
        API api = new API();
        ExecProgramResult result = api
                .execProgram(ExecProgramArgs.newBuilder().addKFilenameList("path/to/kcl.k").build());
        System.out.println(result.getYamlResult());
    }
}

.NET

dotnet add package KclLib

Write the code

using KclLib.API;

var api = new API();
var execArgs = new ExecProgramArgs();
var path = Path.Combine("test_data", "schema.k");
execArgs.KFilenameList.Add(path);
var result = api.ExecProgram(execArgs);
Console.WriteLine(result.YamlResult);

The KclTool package ships the cross-platform kcl (or kcl.exe on Windows) executable under runtimes/<rid>/native/ (and tools/<rid>/) for every supported RID, together with a KclTool.KclRunner helper for invoking it from C#:

using KclTool;

string yaml = KclRunner.Run(new[] { "run", "schema.k", "--format", "yaml" }, capture: true);

Python

python3 -m pip install kcl-lib

Write the code

import kcl_lib.api as api

args = api.ExecProgramArgs(k_filename_list=["./tests/test_data/schema.k"])
api = api.API()
result = api.exec_program(args)
print(result.yaml_result)

Ruby

gem install kcl-lib

Write the code

require "kcl_lib"

args = KclLib::ExecProgramArgs.new(k_filename_list: ["./test_data/schema.k"])
api = KclLib::API.new
result = api.exec_program(args)
puts result.yaml_result

See here for the initial version build notes.

Julia

Unlike the other bindings, the Julia binding does not build any Rust code: it ccalls the same prebuilt libkcl shared libraries shipped under go/lib (see julia/README.md for platform details and the KCL_JL_LIB override).

using Pkg
Pkg.add(url="https://github.com/kcl-lang/lib.git", subdir="julia")

Write the code

using KclLib

result = exec_program(ExecProgramArgs(k_filename_list=["test_data/schema.k"]))
println(result.yaml_result)

Node.js

npm install kcl-lib

Write the code

import { execProgram, ExecProgramArgs } from 'kcl-lib'

function main() {
  const result = execProgram(new ExecProgramArgs(['__test__/test_data/schema.k']))
  console.log(result.yamlResult)
}

main();

Kotlin

Refer to this to configure your Maven; set up your GitHub account and Token in the settings.xml.

Maven

In your project's pom.xml, configure our repository as follows:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/kcl-lang/*</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

This way you'll be able to import the above dependency to use the SDK.

<dependency>
    <groupId>com.kcl</groupId>
    <artifactId>kcl-lib</artifactId>
    <version>0.13.1</version>
</dependency>

Write the code

import com.kcl.api.API
import com.kcl.api.execProgramArgs

val args = execProgramArgs { kFilenameList += "schema.k" }
val api = API()
val result = api.execProgram(args)

Dart / Flutter

Install in a Dart project via git (until the package is published to pub.dev):

dart pub add 'kcl_lib': \
  { git: 'https://github.com/kcl-lang/lib.git', subdir: 'dart' }

Or in pubspec.yaml:

dependencies:
  kcl_lib:
    git: https://github.com/kcl-lang/lib.git
    path: dart

Write the code

import 'package:kcl_lib/kcl_lib.dart';

void main() {
  final result = execProgram(
    ExecProgramArgs(kFilenameList: ['test_data/schema.k']),
  );
  print(result.yamlResult);
}

The binding is a thin dart:ffi wrapper over the same prebuilt libkcl.{so,dylib,dll,a} binaries that the Go binding ships under go/lib/. At runtime, point it at the prebuilt binary by setting the KCL_DART_LIB environment variable:

export KCL_DART_LIB="$PWD/go/lib/darwin-arm64/libkcl.dylib"  # adjust platform

Flutter mobile auto-resolves the right archive: drop libkcl.so into android/app/src/main/jniLibs/<abi>/ and link libkcl.a into the iOS target — see dart/README.md for the full Flutter setup. The mobile archives are produced in this repo by .github/workflows/build-libkcl-mobile.yaml.

See dart/README.md for full API reference and dart/test/ for usage examples.

Swift

import KclLib

let api = API()
var execArgs = ExecProgramArgs()
execArgs.kFilenameList.append("schema.k")
let result = try api.execProgram(execArgs)

C++

For CMake, you can use FetchContent to add KCL C++ Lib to your project.

FetchContent_Declare(
  kcl-lib
  GIT_REPOSITORY https://github.com/kcl-lang/lib.git
  GIT_TAG        v0.13.1
  SOURCE_SUBDIR  cpp
)
FetchContent_MakeAvailable(kcl-lib)

Or you can download the source code and add it to your project.

mkdir third_party
cd third_party
git clone https://github.com/kcl-lang/lib.git

add_subdirectory(third_party/lib/cpp)

target_link_libraries(your_target kcl-lib-cpp)

Write the code

#include "kcl_lib.hpp"
#include <iostream>

int main()
{
    auto args = kcl_lib::ExecProgramArgs {
        .k_filename_list = { "../test_data/schema.k" },
    };
    auto result = kcl_lib::exec_program(args);
    std::cout << result.yaml_result.c_str() << std::endl;
    return 0;
}

C

See here

WASM

See here

Documents

See here

License