# Support a C Library

## Install a C Library

We recommend using a package manager (such as brew, apt-get, winget, etc.) to install a C library. For example:

```bash
brew install inih
```

## Writing Go Files to Link Library Functions

1. On macOS, use `nm -gU libbar.dylib` to parse C-style symbols

```bash
0000000000003e55 T _ini_parse
```

2. Find the function prototype you want to convert in the corresponding .h file

```c
int ini_parse(const char* filename, ini_handler handler, void* user);
```

3. Create the corresponding Go file

```c
inih/
├── _demo
   ├── inih_demo
    ├──inih_demo.go
└── inih.go
```

4. In `inih.go`, use LLGoPackage to specify the location of the third-party library so that llgo can link to the third-party library. Both `pkg-config --libs inih` and `linih` are used to specify the location of the third-party library.

```go
package inih

import (
    _ "unsafe" // unsafe is necessary when using go:linkname
)

const (
    LLGoPackage = "link: $(pkg-config --libs inih); -linih"
)
```

5. Write the corresponding function in `inih.go`

Note that the basic C function type mapping to Go function type can be found at [https://github.com/goplus/llgo/blob/main/doc/Type-Mapping-between-C-and-Go.md](https://github.com/goplus/llgo/blob/main/doc/Type-Mapping-between-C-and-Go.md). Some types requiring special handling are listed at the end of this document for reference.

```go
//go:linkname Parse C.ini_parse
func Parse(filename *c.Char, handler func(user c.Pointer, section *c.Char, name *c.Char, value *c.Char) c.Int, user c.Pointer) c.Int
```

6. Write the function call in `inih_demo.go`

```go
package main

import (
"github.com/goplus/llgo/c"
"github.com/goplus/llgo/cpp/inih"
)

func main() {
filename := c.Str("path/to/yourIniFile")

if inih.Parse(filename, func(user c.Pointer, section *c.Char, name *c.Char, value *c.Char) c.Int {
        println("section:", c.GoString(section), "name:", c.GoString(name), "value:", c.GoString(value))
        return 1
    }, nil) < 0 {
        println("Error parsing config file")
        return
    }
}
```
   
7. Use llgo to run the demo

```bash
cd inih/_demo/inih_demo
llgo run .
```

## Handling Special Types

### Handling Enum Values in C

Use const to implement enum values

```go
/*
typedef enum {
    BLEND_ALPHA = 0,                // Blend textures considering alpha (default)
    BLEND_ADDITIVE,                 // Blend textures adding colors
    BLEND_MULTIPLIED,               // Blend textures multiplying colors
    BLEND_ADD_COLORS,               // Blend textures adding colors (alternative)
    BLEND_SUBTRACT_COLORS,          // Blend textures subtracting colors (alternative)
    BLEND_ALPHA_PREMULTIPLY,        // Blend premultiplied textures considering alpha
    BLEND_CUSTOM,                   // Blend textures using custom src/dst factors (use rlSetBlendFactors())
    BLEND_CUSTOM_SEPARATE           // Blend textures using custom rgb/alpha separate src/dst factors (use rlSetBlendFactorsSeparate())
} BlendMode;
*/

type BlendMode c.Int

const (
    BLEND_ALPHA             BlendMode = iota // Blend textures considering alpha (default)
    BLEND_ADDITIVE                           // Blend textures adding colors
    BLEND_MULTIPLIED                         // Blend textures multiplying colors
    BLEND_ADD_COLORS                         // Blend textures adding colors (alternative)
    BLEND_SUBTRACT_COLORS                    // Blend textures subtracting colors (alternative)
    BLEND_ALPHA_PREMULTIPLY                  // Blend premultiplied textures considering alpha
    BLEND_CUSTOM                             // Blend textures using custom src/dst factors (use rlSetBlendFactors())
    BLEND_CUSTOM_SEPARATE                    // Blend textures using custom rgb/alpha separate src/dst factors (use rlSetBlendFactorsSeparate())
)
```

### Handling Structs in C

```go
// If you need to use class member variables, like llgo/c/raylib
/*
//Vector4, 4 components
typedef struct Vector4 {
    float x;                // Vector x component
    float y;                // Vector y component
    float z;                // Vector z component
    float w;                // Vector w component
} Vector4;
*/

type Vector4 struct {
    X float32 // Vector x component
    Y float32 // Vector y component
    Z float32 // Vector z component
    W float32 // Vector w component
}

// If class member variables don't need to be exposed, like llgo/c/cjson, wrap functions that use these member variables as methods of the class. Example:

/*
typedef struct cJSON
{
    // next/prev allow you to walk array/object chains. Alternatively, use GetArraySize/GetArrayItem/GetObjectItem
    struct cJSON *next;
    struct cJSON *prev;
    // An array or object item will have a child pointer pointing to a chain of the items in the array/object.
    struct cJSON *child;

    // The type of the item, as above.
    int type;

    // The item's string, if type==cJSON_String  and type == cJSON_Raw
    char *valuestring;
    /* writing to valueint is DEPRECATED, use cJSON_SetNumberValue instead
    int valueint;
    // The item's number, if type==cJSON_Number
    double valuedouble;

    // The item's name string, if this item is the child of, or is in the list of subitems of an object.
    char *string;
} cJSON;
*/

// llgo:type C
type JSON struct {
    Unused [0]byte
}
// llgo:link (*JSON).AddItem C.cJSON_AddItemToArray
func (o *JSON) AddItem(item *JSON) c.Int { return 0 }
```

For the size of Unused, if the methods bound to the structure do not need to create objects, i.e., the receiver of the Go methods bound to this structure is of pointer type, you can declare `Unused [0]byte`. Otherwise, you need to write a simple C file using the `sizeof` operator to calculate the size of the structure. Assuming the structure size is 38 bytes, then declare `Unused [38]byte`.

### Handling Function Pointers in C

```go
// Convert function pointers to Go style and then declare function pointer types using aliases

//llgo:type C
type Comp func(a c.Int)

```

### Handling char ** Type in C

Handle char ** as `[]*c.Char`

```go
// void printStrings(const char * strings[], int size);
//
//llgo:link PrintStrings C.printStrings
func PrintStrings(strings **c.Char, size c.Int) {}

```

```go
package main

import (
	"unsafe"

	"github.com/goplus/llgo/c"
	"github.com/goplus/llgo/c/ptrtest"
)

func main() {
    strings := make([]*c.Char, 4)
    strings[0] = c.Str("hello")
    strings[1] = c.Str("world")
    strings[2] = c.Str("ni")
    strings[3] = c.Str("hao")
    ptrtest.PrintStrings(unsafe.SliceData(strings), c.Int(4))
}
```

# LLGO for C++ Third-Party Libraries

Using the C++ part of the inih library as an example

## Installation

Same as installing C libraries

## File Structure

After migrating the C part of the inih library, just continue creating files in the same directory.

```
inih/
├── _demo
    ├── inih_demo
	    ├──inih_demo.go
	  ├── INIReader_demo
		  ├──reader_demo.go
├── _wrap/cpp_wrap.cpp (optional)
└── inih.go
└── reader.go
```

## Writing Go Files to Link Library Functions

### Migrating Ordinary Functions

Since the inih library does not have C++ style ordinary functions, we'll use an ordinary method of a class as an example. The specific process is the same.

Ordinary functions can be directly linked using the corresponding symbol in the dylib. Translate C++ symbols to readable form in the dylib directory.

```bash
nm -gU $(brew --prefix inih)/lib/libINIReader.dylib > output.txt
c++filt <output.txt> symbol.txt
```

Function prototype

```cpp
int ParseError() const;
```

Example of `symbol.txt`

```bash
0000000000002992 T INIReader::ParseError() const
```

Example of `output.txt`

```bash
0000000000002992 T __ZNK9INIReader10ParseErrorEv
```

Find the offset of the function you want to use in `symbol.txt`, then go back to `output.txt` and find the symbol corresponding to that offset.

For functions, generally use `go:linkname` to link. Here, refer to the migration method of C library functions, but bind the symbol to the C++ style symbol. Note that since C. represents a `_`, `__ZNK9INIReader10ParseErrorEv` should be written as `C._ZNK9INIReader10ParseErrorEv`.

```go
// The inih library currently does not involve ordinary functions, this is for demonstration purposes only and is not needed for migrating inih
//go:linkname ParseError C.__ZNK9INIReader10ParseErrorEv
func ParseError() c.Int
```

### Migrating Classes

- Use a struct to map the class. The writing method is the same as migrating a struct in the C library migration:

  ```go
  // llgo:type C
  type Reader struct {
      Unused [32]byte
  }
  ```
- Constructor

  - Constructor is explicitly declared in the class (can find the corresponding symbol in the dynamic library):

    Bind to the `InitFromBuffer` method of the struct and call it in the `NewReaderFile` function to initialize the class and return the class for Go to use.

    ```go
    // NewReaderFile creates a new INIReader instance.
    func NewReaderFile(fileName *std.String) (ret Reader) {
        ret.InitFromFile(fileName)
        return
    }
    /*
    class INIReader
    {
    public:
        explicit INIReader(const char *buffer, size_t buffer_size);
    }
    */

    // llgo:link (*Reader).InitFromBuffer C._ZN9INIReaderC1EPKcm
    func (r *Reader) InitFromBuffer(buffer *c.Char, bufferSize uintptr) {}
    ```
  - Constructor is not explicitly declared in the class (cannot find the corresponding symbol in the dynamic library)

    If the destructor is not explicitly declared in the source code, the compiler will automatically generate a default destructor. Use `extern "C"` to wrap it in cppWrap.cpp:

    ```c
    extern "C" void INIReaderInit(INIReader* r)
    {
    	r->INIReader();
    }
    ```

    Link in Go:

    ```go
    // llgo:link (*Reader).INIReaderInit C.INIReaderInit
    func (r *Reader) INIReaderInit() {}
    ```
- Class Methods

  For general methods of the class, directly use `llgo:link` to link:

  ```go
  // llgo:link (*Reader).GetInteger C._ZNK9INIReader10GetIntegerERKNSt3__112basic_stringIcNS0_11char_traitsIcEENS0_9allocatorIcEEEES8_l
  func (r *Reader) GetInteger(section *std.String, name *std.String, defaultValue c.Long) c.Long {
  	return 0
  }
  ```

  Template or inline methods of the class will be introduced in the next section.
- Destructor

  Similar to the constructor process, after creating the class, use `defer` to call it explicitly:

  ```go
    reader := inih.NewReader(c.Str(buf), uintptr(len(buf)))
    defer reader.Dispose()
  ```

### Templates and Inlines

Templates or inlines do not generate symbols in dynamic libraries (dylib) (default constructors and destructors). To ensure that you can use C style symbols to link template or inline functions, create a C++ file and wrap it with `extern "C"`, then bind the functions directly in Go.

```c
// Using std::string as an example, not needed for migrating inih
extern "C" void stdStringInitFromCStrLen(std::string* s, const char* cstr, size_t len) {
	new(s) std::string(cstr, len);
}
```

Then use LLGoFiles to link in Go: the writing of standard library's `LLGoFiles` and `LLGoPackage` is slightly different from third-party libraries. Using `std::string` and `spdlog` library as examples, inih does not involve this step:

```go
//  std::string
const (
    LLGoFiles   = "_wrap/string.cpp"
    LLGoPackage = "link: c++"
  )
// llgo:link (*String).InitFromCStrLen C.stdStringInitFromCStrLen
func (s *String) InitFromCStrLen(cstr *c.Char, n uintptr) {}
//  If it is a third-party library, specify pkg-config, using spdlog as an example:
const (
LLGoFiles   = "$(pkg-config --cflags spdlog): cppWrap/cppWrap.cpp"
LLGoPackage = "link: $(pkg-config --libs spdlog); -lspdlog -pthread -lfmt")
```

## Writing and Running the Demo

```go
package main

import (
	"github.com/goplus/llgo/c"
	"github.com/goplus/llgo/cpp/inih"
	"github.com/goplus/llgo/cpp/std"
)

func demoFromBuffer() {
	buf := `[settings]
                username=admin
                timeout=100`   
	reader := inih.NewReader(c.Str(buf), uintptr(len(buf)))
	defer reader.Dispose()

	println(reader.ParseError())
	sec := std.Str("settings")
	name := std.Str("timeout")
	value := reader.GetInteger(sec, name, 0)
	println("value:", value)
}

func demoFromFile() {
	reader := inih.NewReaderFile(std.Str("config.ini"))
	defer reader.Dispose()

	if ret := reader.ParseError(); ret != 0 {
		println("Error parsing config file:", ret)
		return
	}
	isDatabaseEnabled := reader.GetBoolean(std.Str("database"), std.Str("enabled"), false)
	port := reader.GetInteger(std.NewString("database"), std.Str("port"), 0)
	s := reader.GetString(std.Str("database"), std.Str("server"), std.Str("unknown"))
	println("s:", s.Str())
	println("isDatabaseEnabled:", isDatabaseEnabled, "port:", port)
}

func main() {
	demoFromBuffer()
	demoFromFile()
}
```

Use `llgo run .` to run in the directory where the demo is written.