README.md

   1 ## GoVPP
   2
   3 This set of packages provide the API for communication with VPP from Go. It consists of the following packages:
   4
   5 - [govpp](govpp.go): provides the entry point to govpp functionality
   6 - [api](api/api.go): API for communication with govpp core using Go channels (without the need of importing the govpp core package itself),
   7 - [core](core/): main functionality of the govpp, sends and receives the messages to/from VPP using the adapter, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP,
   8 - [adapter](adapter/): adapter between govpp core and the VPP, responsible for sending and receiving binary-encoded data via shared memory,
   9 - [binapi_generator](binapi_generator/generator.go): Generator of Go structs out of the VPP binary API definitions in JSON format,
  10 - [examples](examples/): example VPP management application that exercises the govpp API on real-world use-cases.
  11
  12 The design with separated govpp API package ([api](api/api.go)) and the govpp core package ([core](core/)) enables
  13 plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP (e.g. Agent
  14 Core on the schema below) and multiple entities act as clients that are using the master for the communication with
  15 VPP (Agent Plugins on the schema below). The clients can be built into standalone shared libraries without the need
  16 of linking the govpp core and all its dependencies into them.
  17
  18 ```
  19                                        +--------------+
  20     +--------------+                   |              |
  21     |              |                   | Agent Plugin |
  22     |              |                   |              |
  23     |  Agent Core  |                   +--------------+
  24     |              |            +------+  govpp API   |
  25     |              |            |      +--------------+
  26     +--------------+     Go     |
  27     |              |  channels  |      +--------------+
  28     |  govpp core  +------------+      |              |
  29     |              |            |      | Agent Plugin |
  30     +------+-------+            |      |              |
  31            |                    |      +--------------+
  32 binary API |                    +------+  govpp API   |
  33   (shmem)  |                           +--------------+
  34            |
  35     +------+-------+
  36     |              |
  37     |      VPP     |
  38     |              |
  39     +--------------+
  40 ```
  41
  42
  43 ## Example usage
  44 Generating Go bindings from the JSON files located in the `/usr/share/vpp/api/` directory
  45 into the Go packages that will be created inside of the `bin_api` directory:
  46 ```
  47 go run binapi_generator/generator.go --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
  48 ```
  49
  50 Usage of the generated bindings:
  51 ```go
  52 func main() {
  53         conn, _ := govpp.Connect()
  54         defer conn.Disconnect()
  55
  56         ch, _ := conn.NewAPIChannel()
  57         defer ch.Close()
  58
  59         req := &acl.ACLAddReplace{
  60                 ACLIndex: ^uint32(0),
  61                 Tag:      []byte("access list 1"),
  62                 R: []acl.ACLRule{
  63                         {
  64                                 IsPermit:       1,
  65                                 SrcIPAddr:      net.ParseIP("10.0.0.0").To4(),
  66                                 SrcIPPrefixLen: 8,
  67                                 DstIPAddr:      net.ParseIP("192.168.1.0").To4(),
  68                                 DstIPPrefixLen: 24,
  69                                 Proto:          6,
  70                         },
  71                         {
  72                                 IsPermit:       1,
  73                                 SrcIPAddr:      net.ParseIP("8.8.8.8").To4(),
  74                                 SrcIPPrefixLen: 32,
  75                                 DstIPAddr:      net.ParseIP("172.16.0.0").To4(),
  76                                 DstIPPrefixLen: 16,
  77                                 Proto:          6,
  78                         },
  79                 },
  80         }
  81         reply := &acl.ACLAddReplaceReply{}
  82
  83         err := ch.SendRequest(req).ReceiveReply(reply)
  84 }
  85 ```
  86
  87 The example above uses simple wrapper API over underlying go channels, see [example_client](examples/example_client.go)
  88 for more examples, including the example on how to use the Go channels directly.
  89
  90
  91 ## Build & Installation Procedure
  92 Govpp uses `vppapiclient` library from VPP codebase to communicate with VPP. To build govpp, vpp-dev package must be installed,
  93 either [from packages](https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages) or
  94 [from sources](https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package).
  95
  96 To build & install `vpp-dev` from sources:
  97 ```
  98 git clone https://gerrit.fd.io/r/vpp
  99 cd vpp
 100 make install-dep
 101 make bootstrap
 102 make pkg-deb
 103 cd build-root
 104 sudo dpkg -i vpp*.deb
 105 ```
 106
 107 To build & install all govpp binaries into your `$GOPATH`:
 108 ```
 109 cd govpp
 110 go build ./...
 111 go install ./...
 112 ```
 113
 114
 115 ## Building Go bindings from VPP binary APIs
 116 Once you have `binapi_generator` installed in your `$GOPATH`, you can use it to generate Go bindings from
 117 VPP APis in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
 118 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
 119 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
 120 a separated directory, e.g.:
 121
 122 ```
 123 binapi_generator --input-file=examples/bin_api/acl.api.json --output-dir=examples/bin_api
 124 binapi_generator --input-dir=examples/bin_api --output-dir=examples/bin_api
 125 ```
 126
 127 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
 128 process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files
 129 that are dependent on generated code using special comments, e.g. the one from [example_client](examples/example_client.go):
 130 ```go
 131 // go:generate binapi_generator --input-dir=bin_api --output-dir=bin_api
 132 ```
 133
 134 The comment must start at the beginning of the line and have no spaces between the `//` and the `go:generate`.
 135 After that marker, the rest of the line specifies a command for `go generate` to run.
 136
 137 The `go generate` tool automatically traverses the code base, looks for the special comments in Go code and
 138 invokes the code generation, e.g.:
 139 ```
 140 go generate ./...
 141 ```
 142 Invokes all `go:generate` rules in all Go packages recursively.