3 The GoVPP projects provides 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 binary/stats API
7 - [api](api/): API for communication with GoVPP core
8 - [cmd/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/): essential 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/) 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 | | | +--------------+
29 +--------------+ GoVPP |
30 | | channels | +--------------+
31 | GoVPP core +------------+ | |
33 +------+-------+ | | |
35 | +------+ GoVPP API |
36 | binary API +--------------+
47 - [Go 1.13](https://golang.org/dl)
51 Make sure that $GOPATH, $GOROOT, and $PATH are set. If you cloned the
52 govpp repo manually, you'll probably regret it.
57 go get git.fd.io/govpp.git
60 ### Build and install the govpp binary api generator
63 $ cd $GOPATH/src/git.fd.io/govpp.git/cmd/binapi-generator
65 $ binapi-generator -version
66 govpp v0.4.0-dev # or some such
68 ### Install vpp binary artifacts (including the "vpp-dev" package)
70 Build locally, or download from packagecloud. Beyond the scope of
73 ### Generate binapi (Go bindings)
75 Generating Go bindings for VPP binary API from the JSON files
76 installed with the vpp binary artifacts.
79 $ cd $GOPATH/src/git.fd.io/govpp.git
80 $ binapi-generator --output-dir=binapi
81 INFO[0000] found 110 files in API dir "/usr/share/vpp/api"
82 INFO[0000] Generating 203 files
85 The golang binding files land here: $GOPATH/src/git.fd.io/govpp.git/binapi
89 Here's a simple sample program which prints vpp version info, and
90 creates a loopback interface.
98 "git.fd.io/govpp.git/binapi/interfaces"
99 "git.fd.io/govpp.git/binapi/vpe"
104 conn, _ := govpp.Connect("/run/vpp/api.sock")
105 defer conn.Disconnect()
108 ch, _ := conn.NewAPIChannel()
112 req := &vpe.ShowVersion{}
113 reply := &vpe.ShowVersionReply{}
116 err := ch.SendRequest(req).ReceiveReply(reply)
119 fmt.Errorf("SendRequest: %w\n", err)
122 fmt.Printf("Program: %s\nVersion: %s\nBuildDate: %s\n",
123 reply.Program, reply.Version, reply.BuildDate)
125 loop_create := &interfaces.CreateLoopback{}
126 loop_create_reply := &interfaces.CreateLoopbackReply{}
128 err = ch.SendRequest(loop_create).ReceiveReply(loop_create_reply)
131 fmt.Errorf("create_loopback: %w\n", err)
134 fmt.Printf("create_loopback: sw_if_index %d",
135 int(loop_create_reply.SwIfIndex))
139 The example above uses GoVPP API to communicate over underlying go channels,
140 see [example client](examples/simple-client/simple_client.go)
141 for more examples, including the example on how to use the Go channels directly.
143 ### Tracking down generated go code for a specific binary API
145 Golang uses capitalization to indicate exported names, so you'll have
146 to divide through by binapi-generator transformations. Example:
149 define create_loopback -> type CreateLoopback struct ...
150 vpp binapi definition govpp exported type definition
152 The droids you're looking for will be in a file named
153 <something>.ba.go. Suggest:
156 find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName
159 Look at the indicated <something>.ba.go file, deduce the package name
160 and import it. See the example above.
164 ### Using pure Go adapters (recommended)
166 GoVPP now supports pure Go implementation for VPP binary API. This does
167 not depend on CGo or any VPP library and can be easily compiled.
169 There are two packages providing pure Go implementations in GoVPP:
170 - [`socketclient`](adapter/socketclient) - for VPP binary API (via unix socket)
171 - [`statsclient`](adapter/statsclient) - for VPP stats API (via shared memory)
173 ### Using vppapiclient library wrapper (requires CGo)
175 GoVPP also provides vppapiclient package which actually uses
176 `vppapiclient.so` library from VPP codebase to communicate with VPP API.
177 To build GoVPP, `vpp-dev` package must be installed,
178 either [from packages][from-packages] or [from sources][from-sources].
180 To build & install `vpp-dev` from sources:
183 git clone https://gerrit.fd.io/r/vpp
188 sudo dpkg -i vpp*.deb
191 To build & install GoVPP:
194 go get -u git.fd.io/govpp.git
195 cd $GOPATH/src/git.fd.io/govpp.git
200 ## Generating Go bindings with binapi-generator
202 Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API
203 using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
204 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
205 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
206 a separated directory, e.g.:
209 binapi-generator --input-file=acl.api.json --output-dir=binapi
210 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
213 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
214 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
215 that are dependent on generated code using special comments, e.g. the one from
216 [example client](examples/simple-client/simple_client.go):
219 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
222 [from-packages]: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages
223 [from-sources]: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package