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 ## Quick Start
  46
  47 Make sure that $GOPATH, $GOROOT, and $PATH are set. If you cloned the
  48 govpp repo manually, you'll probably regret it.
  49
  50 Instead:
  51
  52 ```
  53     go get git.fd.io/govpp.git
  54 ```
  55
  56 ### Build and install the govpp binary api generator
  57
  58 ```
  59     $ cd $GOPATH/src/git.fd.io/govpp.git/cmd/binapi-generator
  60     $ go install
  61     $ binapi-generator -version
  62     govpp v0.4.0-dev  # or some such
  63 ```
  64 ### Install vpp binary artifacts (including the "vpp-dev" package)
  65
  66 Build locally, or download from packagecloud. Beyond the scope of
  67 README.md.
  68
  69 ### Generate binapi (Go bindings)
  70
  71 Generating Go bindings for VPP binary API from the JSON files
  72 installed with the vpp binary artifacts.
  73
  74 ```
  75     $ cd $GOPATH/src/git.fd.io/govpp.git
  76     $ binapi-generator --output-dir=binapi
  77     INFO[0000] found 110 files in API dir "/usr/share/vpp/api"
  78     INFO[0000] Generating 203 files
  79 ```
  80
  81 The golang binding files land here: $GOPATH/src/git.fd.io/govpp.git/binapi
  82
  83 #### Example Usage
  84
  85 Here's a simple sample program which prints vpp version info, and
  86 creates a loopback interface.
  87
  88 ```go
  89 package main
  90
  91 import (
  92         "fmt"
  93         "git.fd.io/govpp.git"
  94         "git.fd.io/govpp.git/binapi/interfaces"
  95         "git.fd.io/govpp.git/binapi/vpe"
  96 )
  97
  98 func main() {
  99         // Connect to VPP
 100         conn, _ := govpp.Connect("/run/vpp/api.sock")
 101         defer conn.Disconnect()
 102
 103         // Open channel
 104         ch, _ := conn.NewAPIChannel()
 105         defer ch.Close()
 106
 107         // Prepare messages
 108         req := &vpe.ShowVersion{}
 109         reply := &vpe.ShowVersionReply{}
 110
 111         // Send the request
 112         err := ch.SendRequest(req).ReceiveReply(reply)
 113
 114         if err != nil {
 115                 fmt.Errorf("SendRequest: %w\n", err)
 116         }
 117
 118         fmt.Printf("Program: %s\nVersion: %s\nBuildDate: %s\n",
 119                 reply.Program, reply.Version, reply.BuildDate)
 120
 121         loop_create := &interfaces.CreateLoopback{}
 122         loop_create_reply := &interfaces.CreateLoopbackReply{}
 123
 124         err = ch.SendRequest(loop_create).ReceiveReply(loop_create_reply)
 125
 126         if err != nil {
 127                 fmt.Errorf("create_loopback: %w\n", err)
 128         }
 129
 130         fmt.Printf("create_loopback: sw_if_index %d",
 131                 int(loop_create_reply.SwIfIndex))
 132 }
 133 ```
 134
 135 The example above uses GoVPP API to communicate over underlying go channels,
 136 see [example client](examples/simple-client/simple_client.go)
 137 for more examples, including the example on how to use the Go channels directly.
 138
 139 ### Tracking down generated go code for a specific binary API
 140
 141 Golang uses capitalization to indicate exported names, so you'll have
 142 to divide through by binapi-generator transformations. Example:
 143
 144 ```
 145     define create_loopback  -> type CreateLoopback struct ...
 146       vpp binapi definition      govpp exported type definition
 147 ```
 148 The droids you're looking for will be in a file named
 149 <something>.ba.go.  Suggest:
 150
 151 ```
 152     find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName
 153 ```
 154
 155 Look at the indicated <something>.ba.go file, deduce the package name
 156 and import it. See the example above.
 157
 158 ## Build & Install
 159
 160 ### Using pure Go adapters (recommended)
 161
 162 GoVPP now supports pure Go implementation for VPP binary API. This does
 163 not depend on CGo or any VPP library and can be easily compiled.
 164
 165 There are two packages providing pure Go implementations in GoVPP:
 166 - [`socketclient`](adapter/socketclient) - for VPP binary API (via unix socket)
 167 - [`statsclient`](adapter/statsclient) - for VPP stats API (via shared memory)
 168
 169 ### Using vppapiclient library wrapper (requires CGo)
 170
 171 GoVPP also provides vppapiclient package which actually uses
 172 `vppapiclient.so` library from VPP codebase to communicate with VPP API.
 173 To build GoVPP, `vpp-dev` package must be installed,
 174 either [from packages][from-packages] or [from sources][from-sources].
 175
 176 To build & install `vpp-dev` from sources:
 177
 178 ```sh
 179 git clone https://gerrit.fd.io/r/vpp
 180 cd vpp
 181 make install-dep
 182 make pkg-deb
 183 cd build-root
 184 sudo dpkg -i vpp*.deb
 185 ```
 186
 187 To build & install GoVPP:
 188
 189 ```sh
 190 go get -u git.fd.io/govpp.git
 191 cd $GOPATH/src/git.fd.io/govpp.git
 192 make test
 193 make install
 194 ```
 195
 196 ## Generating Go bindings with binapi-generator
 197
 198 Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API
 199 using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
 200 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
 201 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
 202 a separated directory, e.g.:
 203
 204 ```sh
 205 binapi-generator --input-file=acl.api.json --output-dir=binapi
 206 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
 207 ```
 208
 209 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
 210 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
 211 that are dependent on generated code using special comments, e.g. the one from
 212 [example client](examples/simple-client/simple_client.go):
 213
 214 ```go
 215 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
 216 ```
 217
 218 [from-packages]: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages
 219 [from-sources]: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package