README.md

   1 # GoVPP
   2
   3 This set of packages provide 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 API
   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
  14
  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.
  20
  21 ```
  22                                        +--------------+
  23     +--------------+                   |              |
  24     |              |                   |  App plugin  |
  25     |              |                   |              |
  26     |     App      |                   +--------------+
  27     |              |            +------+  GoVPP API   |
  28     |              |            |      +--------------+
  29     +--------------+     Go     |
  30     |              |  channels  |      +--------------+
  31     |  GoVPP core  +------------+      |              |
  32     |              |            |      |  App plugin  |
  33     +------+-------+            |      |              |
  34            |                    |      +--------------+
  35 binary API |                    +------+  GoVPP API   |
  36  (shmem)   |                           +--------------+
  37            |
  38     +------+-------+
  39     |              |
  40     |  VPP process |
  41     |              |
  42     +--------------+
  43 ```
  44
  45 ## Quick Start
  46
  47 #### Code Generator
  48
  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:
  51 ```
  52 binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
  53 ```
  54
  55 #### Example Usage
  56
  57 Usage of the generated bindings:
  58
  59 ```go
  60 func main() {
  61         conn, _ := govpp.Connect()
  62         defer conn.Disconnect()
  63
  64         ch, _ := conn.NewAPIChannel()
  65         defer ch.Close()
  66
  67         req := &acl.ACLAddReplace{
  68                 ACLIndex: ^uint32(0),
  69                 Tag:      []byte("access list 1"),
  70                 R: []acl.ACLRule{
  71                         {
  72                                 IsPermit:       1,
  73                                 SrcIPAddr:      net.ParseIP("10.0.0.0").To4(),
  74                                 SrcIPPrefixLen: 8,
  75                                 DstIPAddr:      net.ParseIP("192.168.1.0").To4(),
  76                                 DstIPPrefixLen: 24,
  77                                 Proto:          6,
  78                         },
  79                         {
  80                                 IsPermit:       1,
  81                                 SrcIPAddr:      net.ParseIP("8.8.8.8").To4(),
  82                                 SrcIPPrefixLen: 32,
  83                                 DstIPAddr:      net.ParseIP("172.16.0.0").To4(),
  84                                 DstIPPrefixLen: 16,
  85                                 Proto:          6,
  86                         },
  87                 },
  88         }
  89         reply := &acl.ACLAddReplaceReply{}
  90
  91         err := ch.SendRequest(req).ReceiveReply(reply)
  92 }
  93 ```
  94
  95 The example above uses simple wrapper API over underlying go channels,
  96 see [example client](examples/simple-client/simple_client.go)
  97 for more examples, including the example on how to use the Go channels directly.
  98
  99 ## Build & Installation Procedure
 100
 101 GoVPP uses `vppapiclient` library from VPP codebase to communicate with VPP.
 102 To build GoVPP, vpp-dev package must be installed,
 103 either [from packages](https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages) or
 104 [from sources](https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package).
 105
 106 To build & install `vpp-dev` from sources:
 107
 108 ```
 109 git clone https://gerrit.fd.io/r/vpp
 110 cd vpp
 111 make install-dep
 112 make bootstrap
 113 make pkg-deb
 114 cd build-root
 115 sudo dpkg -i vpp*.deb
 116 ```
 117
 118 To build & install all GoVPP binaries into your `$GOPATH`:
 119
 120 ```
 121 go get git.fd.io/govpp.git
 122 cd $GOPATH/src/git.fd.io/govpp.git
 123 make
 124 make install
 125 ```
 126
 127 ## Building Go bindings from VPP binary APIs
 128
 129 Once you have `binapi-generator` installed in your `$GOPATH`, you can use it to generate Go bindings from
 130 VPP APis in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
 131 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
 132 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
 133 a separated directory, e.g.:
 134
 135 ```
 136 binapi-generator --input-file=examples/bin_api/acl.api.json --output-dir=examples/bin_api
 137 binapi-generator --input-dir=examples/bin_api --output-dir=examples/bin_api
 138 ```
 139
 140 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
 141 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
 142 that are dependent on generated code using special comments, e.g. the one from
 143 [example client](examples/simple-client/simple_client.go):
 144
 145 ```go
 146 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
 147 ```