llcppg - LLGo autogen tool for C/C++ libraries

How to install

This project depends on LLGO's C ecosystem integration capability, and some components of this tool must be compiled with LLGO. For LLGO installation, please refer to: https://github.com/goplus/llgo?tab=readme-ov-file#how-to-install

brew install cjson # macos
apt-get install libcjson-dev # linux
llgo install ./_xtool/llcppsymg
llgo install ./_xtool/llcppsigfetch
go install ./cmd/llcppcfg
go install ./cmd/gogensig
go install .

Usage

llcppg.cfg file is a configure file used by llcppg. Once llcppg.cfg is generated then you can run llcppg command to generate go pacakge for the c/c++ lib.

llcppg [config-file]

If config-file is not specified, a llcppg.cfg file is used in current directory. Here's a demo configuration to generate LLGO bindings for cjson library:

{
  "name": "cjson",
  "cflags": "$(pkg-config --cflags libcjson)",
  "include": ["cJSON.h","cJSON_Utils.h"],
  "libs": "$(pkg-config --libs libcjson libcjson_utils)",
  "trimPrefixes": ["cJSONUtils_","cJSON_"]
}

After creating the configuration file, run:

llcppg llcppg.cfg

After execution, a Go project will be generated in a directory named after the config name (which is also the package name). For example, with the cjson configuration above, you'll see:

cjson/
├── cJSON.go
├── cJSON_Utils.go
├── cjson_autogen_link.go
├── go.mod
└── go.sum

Import the generated cjson package and try this demo:

package main

import (
    "cjson"
    "github.com/goplus/llgo/c"
)

func main() {
	mod := cjson.CreateObject()
	mod.AddItemToObject(c.Str("hello"), cjson.CreateString(c.Str("llgo")))
	mod.AddItemToObject(c.Str("hello"), cjson.CreateString(c.Str("llcppg")))
	cstr := mod.PrintUnformatted()
	c.Printf(c.Str("%s\n"), cstr)
}

Run the demo with llgo run ., you will see the following output:

{"hello":"llgo","hello":"llcppg"}

Generated Bindings

You can see that functions from the C header files have been automatically mapped and converted to corresponding LLGO binding functions.

Original C function:

CJSON_PUBLIC(cJSON *) cJSON_CreateObject(void);

Converted to LLGO binding function:

//go:linkname CreateObject C.cJSON_CreateObject
func CreateObject() *CJSON 

The types defined in the header file are also converted, for example the cJSON struct:

Original C struct:

typedef struct cJSON
{
    struct cJSON *next;
    struct cJSON *prev;
    struct cJSON *child;
    int type;
    char *valuestring;
    int valueint;
    double valuedouble;
    char *string;
} cJSON;

Converted to Go struct:

type CJSON struct {
	Next        *CJSON
	Prev        *CJSON
	Child       *CJSON
	Type        c.Int
	Valuestring *int8
	Valueint    c.Int
	Valuedouble float64
	String      *int8
}

Notably, to make the API more idiomatic in Go, when a C function's first parameter is a converted type (like cJSON *), the function is automatically converted into a method of that type.

Original C function:

CJSON_PUBLIC(cJSON_bool) cJSON_AddItemToArray(cJSON *array, cJSON *item);

Converted to Go method:

// llgo:link (*CJSON).AddItemToObject C.cJSON_AddItemToObject
func (p *CJSON) AddItemToObject(string *int8, item *CJSON) CJSONBool {
	return 0
}

Customizing Bindings

When you run llcppg directly with the above configuration, it will generate function names according to the configuration. After execution, you'll find a llcppg.symb.json file in the current directory.

[
  {
    "mangle": "cJSON_CreateObject",
    "c++": "cJSON_CreateObject()",
    "go": "CreateObject"
  },
  {
    "mangle": "cJSON_AddItemToObject",
    "c++": "cJSON_AddItemToObject(cJSON *, const char *, cJSON *)",
    "go": "(*CJSON).AddItemToObject"
  },
  {
    "mangle": "cJSON_PrintUnformatted",
    "c++": "cJSON_PrintUnformatted(const cJSON *)",
    "go": "(*CJSON).PrintUnformatted"
  },
]

• mangle field contains the symbol name of function

• c++ field shows the function prototype from the header file

• go field displays the function name that will be generated in LLGO binding.

  You can customize this field to:

  1. Change function names (e.g. "CreateObject" to "Object" for simplicity)
  2. Remove the method receiver prefix to generate a function instead of a method

For example, to convert (*CJSON).PrintUnformatted from a method to a function, simply remove the (*CJSON). prefix in the configuration file:

[
  {
    "mangle": "cJSON_PrintUnformatted",
    "c++": "cJSON_PrintUnformatted(const cJSON *)",
    "go": "PrintUnformatted"
  },
]

This will generate a function instead of a method in the Go code:

//go:linkname PrintUnformatted C.cJSON_PrintUnformatted
func PrintUnformatted(item *CJSON) *int8

You can customize the generated bindings by modifying the llcppg.symb.json file.

After modifying the file, run llcppg again to apply your customized bindings.

The symbol table is generated by llcppsymg, which is internally called by llcppg to generate the symbol table as input for Go code generation. You can also run llcppsymg separately to customize the symbol table before running llcppg.

More demo projects and configuration files can be found under _llcppgtest directory.

Important Note on Header File Ordering

llcppg follows C language's dependency resolution order when processing header files. The order of files in the includes configuration determines the processing sequence, and incorrect ordering can lead to type resolution failures. Here's an example from the LZMA library that demonstrates the dependency relationships:

lzma/vli.h:

typedef uint64_t lzma_vli;

lzma/filter.h:

/**
 * \file        lzma/filter.h
 * \brief       Common filter related types and functions
 * \note        Never include this file directly. Use <lzma.h> instead.
 */
typedef struct {
    lzma_vli id;      // Uses lzma_vli from vli.h
    void *options;
} lzma_filter;

lzma.h:

/**
 * \file        lzma.h
 * \brief       Main LZMA library header
 */
#include "lzma/vli.h"
#include "lzma/filter.h"

Since llcppg processes headers in the order specified in the configuration, you need to list them in the correct dependency order:

✅ Correct ordering:

{
   "includes": ["lzma.h", "lzma/vli.h", "lzma/filter.h"]
}

❌ Incorrect ordering:

{
   "includes": ["lzma/filter.h", "lzma.h", "lzma/vli.h"]
}

The incorrect ordering will fail because filter.h uses the lzma_vli type before it's defined.

Translation Unit Processing

When processing headers with the correct ordering, llcppg employs a caching strategy:

1. First, it creates a translation unit starting from lzma.h. During this process:

   • It follows normal C language parsing order for includes
   • When processing lzma/vli.h (included by lzma.h), the lzma_vli type definition is cached in this translation unit
   • When it reaches lzma/filter.h, the type references work correctly because lzma_vli is already defined in this translation unit

2. For subsequent includes in the configuration:

   • When processing lzma/vli.h, llcppg creates a new translation unit
   • When reaching lzma/filter.h, if it was already processed in a previous translation unit (like the one starting from lzma.h), llcppg will use the cached version that has proper type resolution

This caching strategy ensures that type references are properly maintained when headers are processed in the correct order.

Development Tools

llcppcfg - Configuration Generator

llcppcfg [libname]

llcppcfg tool is used to generate llcppg.cfg file.

Design

See llcppg Design.