# Go

This Go library uses CGO to consume the runtime APIs of the WAMR project which are defined in [core/iwasm/include/wasm\_export.h](https://github.com/TianlongLiang/wasm-micro-runtime/blob/main/core/iwasm/include/wasm_export.h). The API details are available in the header files.

## Installation

### Installing from the source code

Installing from local source tree is in *development mode*.

Run `./build.sh` in this folder to build the package, which builds the WAMR runtime library firstly and then builds the Go binding library.

Run `./build.sh` under `samples` folder to build and test the sample.

```bash
cd samples
./build.sh
```

## Supported APIs

All the embedding APIs supported are defined under folder [wamr](https://github.com/TianlongLiang/wasm-micro-runtime/blob/main/language-bindings/go/wamr/README.md).

### Runtime APIs

```go
func Runtime() *_Runtime
func (self *_Runtime) FullInit(alloc_with_pool bool, heap_buf []byte,
                               max_thread_num uint) error
func (self *_Runtime) Init() error
func (self *_Runtime) Destroy()
func (self *_Runtime) SetLogLevel(level LogLevel)
func (self *_Runtime) Malloc(size uint32) *uint8
func (self *_Runtime) Free(ptr *uint8)
```

### Module APIs

```go
func NewModule(wasmBytes []byte) (*Module, error)
func (self *Module) Destroy()
func (self *Module) SetWasiArgs(dirList [][]byte, mapDirList [][]byte,
                                env [][]byte, argv[][]byte)
func (self *Module) SetWasiArgsEx(dirList [][]byte, mapDirList [][]byte,
                                env [][]byte, argv[][]byte,
                                stdinfd int, stdoutfd int, stderrfd int)
func (self *Module) SetWasiAddrPool(addrPool [][]byte)
```

### Instance APIs

```go
func NewInstance(module *Module,
                 stackSize uint, heapSize uint) (*Instance, error)
func (self *Instance) Destroy()
func (self *Instance) CallFunc(funcName string,
                               argc uint32, args []uint32) error
func (self *Instance) CallFuncV(funcName string,
                                num_results uint32, results []interface{},
                                args ... interface{}) error
func (self *Instance) GetException() string
func (self Instance) ModuleMalloc(size uint32) (uint32, *uint8)
func (self Instance) ModuleFree(offset uint32)
func (self Instance) ValidateAppAddr(app_offset uint32, size uint32) bool
func (self Instance) ValidateNativeAddr(native_ptr *uint8, size uint32) bool
func (self Instance) AddrAppToNative(app_offset uint32) *uint8
func (self Instance) AddrNativeToApp(native_ptr *uint8) uint32
func (self Instance) GetAppAddrRange(app_offset uint32) (bool, uint32, uint32)
func (self Instance) GetNativeAddrRange(native_ptr *uint8) (bool, *uint8, *uint8)
func (self Instance) DumpMemoryConsumption()
func (self Instance) DumpCallStack()
```

## Sample codes

```go
    var module *wamr.Module
    var instance *wamr.Instance
    var results []interface{}
    var err error

    /* Runtime initialization */
    err = wamr.Runtime().FullInit(false, nil, 1)

    /* Read WASM/AOT file into a memory buffer */
    wasmBytes := read_wasm_binary_to_buffer(...)

    /* Load WASM/AOT module from the memory buffer */
    module, err = wamr.NewModule(wasmBytes)

    /* Create WASM/AOT instance from the module */
    instance, err = wamr.NewInstance(module, 16384, 16384)

    /* Call the `fib` function */
    results = make([]interface{}, 1, 1)
    err = instance.CallFuncV("fib", 1, results, (int32)32)
    fmt.Printf("fib(32) return: %d\n", results[0].(int32));

    /* Destroy runtime */
    wamr.Runtime().Destroy()
```

More samples can be found in [test.go](https://github.com/TianlongLiang/wasm-micro-runtime/blob/main/language-bindings/go/samples/test.go)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wamr.gitbook.io/document/wamr-in-practice/tutorial/language-embedding/go.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.