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 #### Generate binapi (Go bindings)
  48
  49 Generating Go bindings for VPP binary API from the JSON files located in the
  50 `/usr/share/vpp/api/` directory into the Go packages that will be created
  51 inside of the `binapi` directory:
  52
  53 ```
  54 binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=binapi
  55 ```
  56
  57 #### Example Usage
  58
  59 Here is a usage sample of the generated binapi messages:
  60
  61 ```go
  62 func main() {
  63     // Connect to VPP
  64         conn, _ := govpp.Connect()
  65         defer conn.Disconnect()
  66
  67         // Open channel
  68         ch, _ := conn.NewAPIChannel()
  69         defer ch.Close()
  70
  71         // Prepare messages
  72         req := &vpe.ShowVersion{}
  73         reply := &vpe.ShowVersionReply{}
  74
  75         // Send the request
  76         err := ch.SendRequest(req).ReceiveReply(reply)
  77 }
  78 ```
  79
  80 The example above uses GoVPP API to communicate over underlying go channels,
  81 see [example client](examples/simple-client/simple_client.go)
  82 for more examples, including the example on how to use the Go channels directly.
  83
  84 ## Build & Install
  85
  86 ### Using pure Go adapters (recommended)
  87
  88 GoVPP now supports pure Go implementation for VPP binary API. This does
  89 not depend on CGo or any VPP library and can be easily compiled.
  90
  91 There are two packages providing pure Go implementations in GoVPP:
  92 - [`socketclient`](adapter/socketclient) - for VPP binary API (via unix socket)
  93 - [`statsclient`](adapter/statsclient) - for VPP stats API (via shared memory)
  94
  95 ### Using vppapiclient library wrapper (requires CGo)
  96
  97 GoVPP also provides vppapiclient package which actually uses
  98 `vppapiclient.so` library from VPP codebase to communicate with VPP API.
  99 To build GoVPP, `vpp-dev` package must be installed,
 100 either [from packages][from-packages] or [from sources][from-sources].
 101
 102 To build & install `vpp-dev` from sources:
 103
 104 ```sh
 105 git clone https://gerrit.fd.io/r/vpp
 106 cd vpp
 107 make install-dep
 108 make pkg-deb
 109 cd build-root
 110 sudo dpkg -i vpp*.deb
 111 ```
 112
 113 To build & install GoVPP:
 114
 115 ```sh
 116 go get -u git.fd.io/govpp.git
 117 cd $GOPATH/src/git.fd.io/govpp.git
 118 make test
 119 make install
 120 ```
 121
 122 ## Generating Go bindings with binapi-generator
 123
 124 Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API
 125 using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
 126 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
 127 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
 128 a separated directory, e.g.:
 129
 130 ```sh
 131 binapi-generator --input-file=acl.api.json --output-dir=binapi
 132 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
 133 ```
 134
 135 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
 136 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
 137 that are dependent on generated code using special comments, e.g. the one from
 138 [example client](examples/simple-client/simple_client.go):
 139
 140 ```go
 141 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
 142 ```
 143
 144 [from-packages]: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages
 145 [from-sources]: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package