llgo/doc/Rust-to-LLGO-Migration-Guide.md

Rust to LLGO Migration Document

Add Dependencies & Build Configuration

Edit Cargo.toml to include necessary dependencies and configuration:

[dependencies]
libc = "0.2"
csv = "1.1"

[lib]
crate-type = ["cdylib"] # The generated dynamic library will conform to the C standard

[build-dependencies]
cbindgen = "0.26.0"

Import C Language Types

Use types from the libc package for interoperability with C:

use libc::{c_int, c_char, strlen};

Function Decoration and Attributes

To ensure that Rust functions can be correctly called by C and LLGO, use the following decorators:

• #[no_mangle] prevents the compiler from mangling the function name.
• unsafe is used to mark operations that are unsafe, especially when dealing with raw pointers.
• extern "C" specifies the use of C calling conventions.

For example, in Rust, we write CSV code like this:

use csv::ReaderBuilder;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // Define the CSV file path
    let file_path = "example.csv";

    // Creating a CSV Reader
    let mut reader = ReaderBuilder::new().from_path(file_path)?;

    // Define a container to store records
    let mut record = csv::StringRecord::new();

    // Read records one by one
    while reader.read_record(&mut record)? {
        // Print each record
        println!("{:?}", record);
    }

    Ok(())
}

If we need to migrate the CSV library to LLGO, we need to encapsulate each CSV method with a C API, such as the following:

Memory Management

Use Box to manage dynamic memory to ensure correct memory release between Rust and C:

pub unsafe extern "C" fn sled_create_config() -> \*mut Config {
Box::into_raw(Box::new(Config::new()))
}

#[no_mangle]
pub unsafe extern "C" fn sled_free_config(config: \*mut Config) {
drop(Box::from_raw(config));
}

Handling Generic Pointers

Address the interfacing issues between generic pointers in C and Rust:

#[no_mangle]
pub extern "C" fn csv_reader_new(file_path: *const c_char) -> *mut c_void { /* ... */ }

#[no_mangle]
pub extern "C" fn csv_reader_free(ptr: *mut c_void) { /* ... */ }

String Handling

Convert strings between C and Rust:

#[no_mangle]
pub extern "C" fn csv_reader_read_record(ptr: *mut c_void) -> *const c_char { /* ... */ }

#[no_mangle]
pub extern "C" fn free_string(s: *mut c_char) {
    unsafe {
        let c_string = CString::from_raw(s);
        drop(c_string);
    }
}

Generate Header File

Edit cbindgen.toml to configure the header file generation rules:

# See https://github.com/mozilla/cbindgen/blob/master/docs.md#cbindgentoml for
# a list of possible configuration values.
language = "C"

Use cbindgen to generate a C header file, automating this process through a build.rs script:

fn main() {
    let config = cbindgen::Config::from_file("cbindgen.toml").expect("Config file not found.");
    cbindgen::generate_with_config(&crate_dir, config).unwrap().write_to_file("target/include/csv_wrapper.h");
}

Compilation and Installation

Build the dynamic library:

cargo build --release

Install dylib-installer

Install the dylib-installer tool, which is used to install dynamic libraries:

brew tap hackerchai/tap
brew install dylib-installer

Or you can install it using Cargo:

cargo install dylib_installer

Install Dynamic Library

Use dylib-installer to install the built dynamic library and the header file into the system directory:

sudo dylib_installer <dylib_lib> <header_file_lib>

Check the Installation

You can check the installation by running the following command:

pkg-config --libs --cflags <lib_name>

if everything is installed correctly, you will see the output like this (depending on your system):

-I/usr/local/include -L/usr/local/lib -l<lib_name>

LLGO Package Mapping

Map functions from the Rust library to an LLGO package, ensuring type consistency:

• LLGoPackage

Specify LLGoPackage and use pkg-config to find the location of the lib library.

const (
	LLGoPackage = "link: $(pkg-config --libs csv_wrapper); -lcsv_wrapper"
)

• Type

If you want to use variables inside the struct, you can add them accordingly. If it can't be represented directly or is not needed, it can be represented in the form Unused []byte, the length of the array is determined by its size, and if the struct is only used as a pointer, then the array length can be 0.

type Reader struct {
	Unused [0]byte
}

// type Reader struct {
//    Unused [8]byte
// }

• Ordinary functions

Ordinary functions can be mapped in the form of //go:linkname.

//go:linkname NewReader C.csv_reader_new
func NewReader(file_path *c.Char) *Reader

• Method

Methods need to be mapped in the form of // llgo:link (*Receiver).

// llgo:link (*Reader).Free C.csv_reader_free
func (reader *Reader) Free() {}

// llgo:link (*Reader).ReadRecord C.csv_reader_read_record
func (reader *Reader) ReadRecord() *c.Char { return nil }

• Function pointer

If you use a function pointer, that is, declare the function as a type separately, you need to use // llgo:type Cto declare it.

// llgo:type C
type IoReadCallback func(c.Pointer, *Context, *uint8, uintptr) uintptr

// llgo:link (*Io).SetRead C.hyper_io_set_read
func (io *Io) SetRead(callback IoReadCallback) {}

Or declare the function directly in the parameter.

// llgo:link (*Io).SetRead C.hyper_io_set_read
func (io *Io) SetRead(callback func(c.Pointer, *Context, *uint8, uintptr) uintptr) {}

Writing Examples and README

Provide example code and a detailed README file to help users understand how to use the generated library.

You can find the migrated instance from llgoexamples, in the lib directory is the migrated Rust library, and in the rust directory, the migrated mapping file and go demo.