3 This set of packages provide the API for communication with VPP from Go.
5 It consists of the following packages:
6 - [adapter](adapter/): adapter between GoVPP core and the VPP
7 - [api](api/api.go): API for communication with GoVPP core
8 - [binapi-generator](cmd/binapi-generator/): Generator for the VPP binary API definitions in JSON format to Go code
9 - [codec](codec/): handles encoding/decoding of generated messages into binary form
10 - [core](core/): main functionality of the GoVPP
11 - [examples](examples/): examples that use the GoVPP API in real use-cases of VPP management application
12 - [extras](extras/): contains Go implementation for libmemif library
13 - [govpp](govpp.go): provides the entry point to GoVPP functionality
15 The design with separated GoVPP [API package](api/api.go) and the GoVPP [core package](core/) enables
16 plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP and multiple
17 entities act as clients that are using the master for the communication with VPP.
18 The clients can be built into standalone shared libraries without the need
19 of linking the GoVPP core and all its dependencies into them.
26 | App | +--------------+
27 | | +------+ GoVPP API |
28 | | | +--------------+
30 | | channels | +--------------+
31 | GoVPP core +------------+ | |
33 +------+-------+ | | |
35 binary API | +------+ GoVPP API |
36 (shmem) | +--------------+
49 Generating Go bindings from the JSON files located in the `/usr/share/vpp/api/` directory
50 into the Go packages that will be created inside of the `bin_api` directory:
52 binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
57 Usage of the generated bindings:
61 conn, _ := govpp.Connect()
62 defer conn.Disconnect()
64 ch, _ := conn.NewAPIChannel()
67 req := &acl.ACLAddReplace{
69 Tag: []byte("access list 1"),
73 SrcIPAddr: net.ParseIP("10.0.0.0").To4(),
75 DstIPAddr: net.ParseIP("192.168.1.0").To4(),
81 SrcIPAddr: net.ParseIP("8.8.8.8").To4(),
83 DstIPAddr: net.ParseIP("172.16.0.0").To4(),
89 reply := &acl.ACLAddReplaceReply{}
91 err := ch.SendRequest(req).ReceiveReply(reply)
95 The example above uses simple wrapper API over underlying go channels, see [example client](examples/cmd/simple-client/simple_client.go)
96 for more examples, including the example on how to use the Go channels directly.
98 ## Build & Installation Procedure
100 Govpp uses `vppapiclient` library from VPP codebase to communicate with VPP. To build GoVPP, vpp-dev package must be installed,
101 either [from packages](https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages) or
102 [from sources](https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package).
104 To build & install `vpp-dev` from sources:
107 git clone https://gerrit.fd.io/r/vpp
113 sudo dpkg -i vpp*.deb
116 To build & install all GoVPP binaries into your `$GOPATH`:
119 go get git.fd.io/govpp.git
120 cd $GOPATH/src/git.fd.io/govpp.git
125 ## Building Go bindings from VPP binary APIs
127 Once you have `binapi-generator` installed in your `$GOPATH`, you can use it to generate Go bindings from
128 VPP APis in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
129 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
130 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
131 a separated directory, e.g.:
134 binapi-generator --input-file=examples/bin_api/acl.api.json --output-dir=examples/bin_api
135 binapi-generator --input-dir=examples/bin_api --output-dir=examples/bin_api
138 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
139 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
140 that are dependent on generated code using special comments, e.g. the one from
141 [example client](examples/cmd/simple-client/simple_client.go):
144 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api