README.md

   1 # GoVPP
   2
   3 The GoVPP projects provides the API for communication with VPP from Go.
   4
   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
  14
  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.
  20
  21 ```
  22                                        +--------------+
  23     +--------------+                   |              |
  24     |              |                   |    plugin    |
  25     |              |                   |              |
  26     |     App      |                   +--------------+
  27     |              |            +------+  GoVPP API   |
  28     |              |            |      +--------------+
  29     +--------------+   GoVPP    |
  30     |              |  channels  |      +--------------+
  31     |  GoVPP core  +------------+      |              |
  32     |              |            |      |    plugin    |
  33     +------+-------+            |      |              |
  34            |                    |      +--------------+
  35            |                    +------+  GoVPP API   |
  36            | binary API                +--------------+
  37            |
  38     +------+-------+
  39     |              |
  40     |  VPP process |
  41     |              |
  42     +--------------+
  43 ```
  44
  45 ## Prerequisites
  46
  47 - [Go 1.13](https://golang.org/dl)
  48
  49 ## Quick Start
  50
  51 Make sure that $GOPATH, $GOROOT, and $PATH are set. If you cloned the
  52 govpp repo manually, you'll probably regret it.
  53
  54 Instead:
  55
  56 ```
  57     go get git.fd.io/govpp.git
  58 ```
  59
  60 ### Build and install the govpp binary api generator
  61
  62 ```
  63     $ cd $GOPATH/src/git.fd.io/govpp.git/cmd/binapi-generator
  64     $ go install
  65     $ binapi-generator -version
  66     govpp v0.4.0-dev  # or some such
  67 ```
  68 ### Install vpp binary artifacts (including the "vpp-dev" package)
  69
  70 Build locally, or download from packagecloud. Beyond the scope of
  71 README.md.
  72
  73 ### Generate binapi (Go bindings)
  74
  75 Generating Go bindings for VPP binary API from the JSON files
  76 installed with the vpp binary artifacts.
  77
  78 ```
  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
  83 ```
  84
  85 The golang binding files land here: $GOPATH/src/git.fd.io/govpp.git/binapi
  86
  87 #### Example Usage
  88
  89 Here's a simple sample program which prints vpp version info, and
  90 creates a loopback interface.
  91
  92 ```go
  93 package main
  94
  95 import (
  96         "fmt"
  97         "git.fd.io/govpp.git"
  98         "git.fd.io/govpp.git/binapi/interfaces"
  99         "git.fd.io/govpp.git/binapi/vpe"
 100 )
 101
 102 func main() {
 103         // Connect to VPP
 104         conn, _ := govpp.Connect("/run/vpp/api.sock")
 105         defer conn.Disconnect()
 106
 107         // Open channel
 108         ch, _ := conn.NewAPIChannel()
 109         defer ch.Close()
 110
 111         // Prepare messages
 112         req := &vpe.ShowVersion{}
 113         reply := &vpe.ShowVersionReply{}
 114
 115         // Send the request
 116         err := ch.SendRequest(req).ReceiveReply(reply)
 117
 118         if err != nil {
 119                 fmt.Errorf("SendRequest: %w\n", err)
 120         }
 121
 122         fmt.Printf("Program: %s\nVersion: %s\nBuildDate: %s\n",
 123                 reply.Program, reply.Version, reply.BuildDate)
 124
 125         loop_create := &interfaces.CreateLoopback{}
 126         loop_create_reply := &interfaces.CreateLoopbackReply{}
 127
 128         err = ch.SendRequest(loop_create).ReceiveReply(loop_create_reply)
 129
 130         if err != nil {
 131                 fmt.Errorf("create_loopback: %w\n", err)
 132         }
 133
 134         fmt.Printf("create_loopback: sw_if_index %d",
 135                 int(loop_create_reply.SwIfIndex))
 136 }
 137 ```
 138
 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.
 142
 143 ### Tracking down generated go code for a specific binary API
 144
 145 Golang uses capitalization to indicate exported names, so you'll have
 146 to divide through by binapi-generator transformations. Example:
 147
 148 ```
 149     define create_loopback  -> type CreateLoopback struct ...
 150       vpp binapi definition      govpp exported type definition
 151 ```
 152 The droids you're looking for will be in a file named
 153 <something>.ba.go.  Suggest:
 154
 155 ```
 156     find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName
 157 ```
 158
 159 Look at the indicated <something>.ba.go file, deduce the package name
 160 and import it. See the example above.
 161
 162 ## Build & Install
 163
 164 ### Using pure Go adapters (recommended)
 165
 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.
 168
 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)
 172
 173 ### Using vppapiclient library wrapper (requires CGo)
 174
 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].
 179
 180 To build & install `vpp-dev` from sources:
 181
 182 ```sh
 183 git clone https://gerrit.fd.io/r/vpp
 184 cd vpp
 185 make install-dep
 186 make pkg-deb
 187 cd build-root
 188 sudo dpkg -i vpp*.deb
 189 ```
 190
 191 To build & install GoVPP:
 192
 193 ```sh
 194 go get -u git.fd.io/govpp.git
 195 cd $GOPATH/src/git.fd.io/govpp.git
 196 make test
 197 make install
 198 ```
 199
 200 ## Generating Go bindings with binapi-generator
 201
 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.:
 207
 208 ```sh
 209 binapi-generator --input-file=acl.api.json --output-dir=binapi
 210 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
 211 ```
 212
 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):
 217
 218 ```go
 219 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
 220 ```
 221
 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