gonacli

README

GonaCli

This is a development tool that can quickly use Golang to develop NodeJS Addon.

English | 中文

GONACLI is a development tool that quickly uses Golang to develop NodeJS Addon. You only need to concentrate on the development of Golang, and you don't need to care about the implementation of the bridge layer. It supports JavaScript sync calls and async callbacks.

⭐️ If it helps you, please give a star.

• https://github.com/wenlng/gonacli

Compatible Support Of Gonacli

• Linux
• Mac OS
• Windows

Compatible Support Of NodeJS Addon

• Linux / Mac OS / Windows
• NodeJS(12.0+)
• Npm(6.0+)
• Node-gyp(9.0+)
• Go(1.14+)

Use Golang Install

Ensure that the system is configured with GOPATH environment variables before installation

Linux or Mac OS

# .bash_profile
export GOPATH="/Users/awen/go"
# set bin dir
export PATH="$PATH:$GOPATH:$GOPATH/bin"

Window

# set system path
GOPATH: C:\awen\go
# set bin dir
PATH: %GOPATH%\bin

Install

$ go install github.com/wenlng/gonacli@latest

$ gonacli version

Compilation Of Windows OS Environment

In the Windows OS environment, you need to install the "gcc/g++" compiler support required by Go CGO, download the MinGW installation, configure the PATH environment variable of "MinGW/bin", and execute "gcc" normally on the command line.

$ gcc -v

When compiling Node Addon in the Windows OS environment, you also need to install the c/c++ compilation tool that node-gyp depends on.

$ npm install --global --production windows-build-tools

Gonacli Command

1. generate

Generate Napi, C/C++ bridge code related to NodeJS Addon according to the configuration of goaddon

# By default, it reads the goaddon in the current directory Json configuration file
$ gonacli generate

# --config: Specify Profile
$ gonacli generate --config demoaddon.json

2. build

Same as the "go build - buildmode=c-archive" command, compile the library

# Compile to generate library
$ gonacli build

# --args: Specify the args of go build
# --config: Specify Profile
$ gonacli build --args '-ldflags "-s -w"'

3. install

Same as the "npm install"， Install NodeJS dependencies.

# --config: Specify Profile
$ gonacli install --config demoaddon.json

4. msvc

Select "dlltool.exe" in the Windows OS environment or "lib.exe"

1."dlltool.exe" of "MinGW"

2."lib.exe" of "Microsoft Visual c++ Build tools" or "Visual Studio"

# --vs: use VS "lib.exe", default is "dlltool.exe" of MinGW
# --32x: Supports 32-bit OS，default 64.
# --config: Specify Profile
$ gonacli msvc --config demoaddon.json

5. make

Same as the "node-gyp configure && node-gyp build" command，Compile NodeJS Addon

Please ensure that the node gyp compiler has been installed on the system before using the "make" command

Before using the "--npm-i" arg, ensure that the system has installed the npm package dependency management tool

# --args: Specify the parameters of node-gyp build，for example "--debug"
$ gonacli make --args '--debug'

Use Golang to develop an Demo of NodeJS Addon

Tip：Ensure that relevant commands can be used normally, This is an demo under Linux/OS environment.

# go
$ go version

# node
$ node -v

# npm
$ npm -v

# node-gyp
$ node-gyp -v

1. Create Goaddon Configure File

/goaddon.json

{
  "name": "demoaddon",
  "sources": [
    "demoaddon.go"
  ],
  "output": "./demoaddon/",
  "exports": [
    {
      "name": "Hello",
      "args": [
        {
          "name": "name",
          "type": "string"
        }
      ],
      "returntype": "string",
      "jscallname": "hello",
      "jscallmode": "sync"
    }
  ]
}

2. Write Golang Code

/demoaddon.go

package main
import "C"

// notice：//export xxxx is necessary

//export Hello
func Hello(_name *C.char) *C.char {
	// args string type，return string type
	name := C.GoString(_name)
	
	res := "hello"
	if len(name) > 0 {
	    res += "," + name
	}
	
	return C.CString(res)
}

3. Generate Rridging Napi C/C++ Code

# Save to the "./demoaddon/" directory
$ gonacli generate --config ./goaddon.json

4.Compile Libraries

# Save to the "./demoaddon/" directory
$ gonacli build

5. Install Dependencies

# Save to the "./demoaddon/build" directory
$ gonacli install

6. Compile Nodejs Adddon

# Save to the "./demoaddon/build" directory
$ gonacli make

7. Create JS Test File

/demoaddon/test.js

const demoaddon = require('.')

const name = "awen"
const res = demoaddon.hello(name)
console.log('>>> ', res)

$ node ./test.js
# >>> hello, awen

Configure File Description

{
  "name": "demoaddon",      // Name of Nodejs Addon
  "sources": [              // File list of go build，Cannot have path
    "demoaddon.go"
  ],
  "output": "./demoaddon/", // Output directory path
  "exports": [              // Exported interface, generating the Napi and C/C++ code of Addon
    {
      "name": "Hello",      // The name of the "//export Hello" interface corresponding to Golang must be consistent
      "args": [             // The parameter type of the passed parameter list must be consistent with the type table
        {                  
          "name": "name",
          "type": "string"
        }
      ],
      "returntype": "string",   // The type returned to JavaScript，has no callback type
      "jscallname": "hello",    // JavaScript call name
      "jscallmode": "sync"      // Sync is synchronous execution, and Async is asynchronous execution
    }
  ]
}

Type Table

Type	Golang Args	Golang Return	JS / TS
int	int32	C.int	number
int32	int32	C.int	number
int64	int64	C.longlong	number
uint32	uint32	C.uint	number
float	float32	C.float	number
double	float64	C.double	number
boolean	bool	bool	boolean
string	*C.char	*C.char	string
array	*C.char	*C.char	Array
object	*C.char	*C.char	Object
callback	*C.char	-	Function

The returntype field type of the configuration file

The returntype field has no callback type

array type

When there are multiple levels when returning, it is not recommended to use in the returntype

1. The "array" type received in Golang is a string "*C.Char" type, which needs to be use "[]interface{}" and "json.Unmarshal"

2. The "array" type is when Golang returns "*C.Char" type, use "json.Marshal"

3. The "array" type is an Array type when JavaScript is passed, but currently only supports one layer when receiving. Please use string method to return multiple layers in Golang, and then use JavaScript's "JSON.parse"

object type

When there are multiple levels when returning, it is not recommended to use in the returntype

1. The "object" type received in Golang is a string type. You need to use "[string]interface{}" and "json.Unmarshal"

2. 2. The "object" type is when Golang returns "*C.Char" type, use "json.Marshal"

3. The "object" type is an Object type when JavaScript is passed, but currently only supports one layer when receiving. Please use string method to return multiple layers in Golang, and then use JavaScript's "JSON.parse"

JavaScript Sync Call

/goaddon.json

{
  "name": "demoaddon",
  "sources": [
    "demoaddon.go"
  ],
  "output": "./demoaddon/",
  "exports": [
    {
      "name": "Hello",
      "args": [
        {
          "name": "name",
          "type": "string"
        }
      ],
      "returntype": "string",
      "jscallname": "hello",
      "jscallmode": "sync"
    }
  ]
}

2. Golang Code

/demoaddon.go

package main
import "C"

//export Hello
func Hello(_name *C.char) *C.char {
	// args is string type，return string type
	name := C.GoString(_name)
	
	res := "hello"
	ch := make(chan bool)

	go func() {
	    // Time consuming task processing
	    time.Sleep(time.Duration(2) * time.Second)
		if len(name) > 0 {
	        res += "," + name
	    }   
		ch <- true
	}()

	<-ch
	
	return C.CString(res)
}

3. Test

/test.js

const demoaddon = require('./demoaddon')

const name = "awen"
const res = demoaddon.hello(name)
console.log('>>> ', res)

JavaScript Async Call

/goaddon.json

{
  "name": "demoaddon",
  "sources": [
    "demoaddon.go"
  ],
  "output": "./demoaddon/",
  "exports": [
    {
      "name": "Hello",
      "args": [
        {
          "name": "name",
          "type": "string"
        },
        {
          "name": "cbs",
          "type": "callback"
        }
      ],
      "returntype": "string",
      "jscallname": "hello",
      "jscallmode": "async"
    }
  ]
}

2. Golang Code

/demoaddon.go

package main
import "C"

//export Hello
func Hello(_name *C.char, cbsFnName *C.char) *C.char {
	// args is string type，return string type
	name := C.GoString(_name)
	
	res := "hello"
	ch := make(chan bool)

    go func() {
	    // Time consuming task processing
		time.Sleep(time.Duration(2) * time.Second)
		if len(name) > 0 {
	        res += "," + name
	    }   
		ch <- true
	}()

	<-ch
	
	return C.CString(res)
}

3. Test

/test.js

const demoaddon = require('./demoaddon')

const name = "awen"
demoaddon.hello(name, funciton(res){
    console.log('>>> ', res)
})

LICENSE

MIT