README.md

   1 # GoVPP
   2
   3 [![stable](https://img.shields.io/github/v/tag/fdio/govpp.svg?label=release&logo=github)](https://github.com/ligato/vpp-agent/releases/latest) [![PkgGoDev](https://pkg.go.dev/badge/git.fd.io/govpp.git)](https://pkg.go.dev/git.fd.io/govpp.git)
   4
   5 The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API.
   6
   7 ## Overview
   8
   9 - [govpp](govpp.go) - the entry point for the GoVPP client
  10   - [adapter](adapter) - VPP binary & stats API interface
  11       - [mock](adapter/mock) - Mock adapter used for testing
  12       - [socketclient](adapter/socketclient) - Go implementation of VPP API client for unix socket
  13       - [statsclient](adapter/statsclient) - Go implementation of VPP Stats client for shared memory
  14       - [vppapiclient](adapter/vppapiclient) - CGo wrapper of vppapiclient library (DEPRECATED!)
  15   - [api](api) - GoVPP client API
  16   - [binapigen](binapigen) - library for generating code from VPP API
  17       - [vppapi](binapigen/vppapi) - VPP API parser
  18   - [cmd](cmd)
  19       - [binapi-generator](cmd/binapi-generator) - VPP binary API generator
  20       - [vpp-proxy](cmd/vpp-proxy) - VPP proxy for remote access
  21   - [codec](codec) - handles encoding/decoding of generated messages into binary form
  22   - [core](core) - implementation of the GoVPP client
  23   - [docs](docs) - documentation
  24   - [examples](examples) - examples demonstrating GoVPP functionality
  25   - [internal](internal) - packages used internally by GoVPP
  26   - [proxy](proxy) - contains client/server implementation for proxy
  27   - [test](test) - integration tests, benchmarks and performance tests
  28
  29 ## Install binapi-generator
  30
  31 ### Prerequisites
  32
  33 - Go 1.13+ ([download]((https://golang.org/dl)))
  34
  35 ### Install via Go toolchain
  36
  37 ```shell
  38 # Latest version (most recent tag)
  39 go install git.fd.io/govpp.git/cmd/binapi-generator@latest
  40
  41 # Development version (master branch)
  42 go install git.fd.io/govpp.git/cmd/binapi-generator@master
  43 ```
  44
  45 NOTE: Using `go install` to install programs is only supported in Go 1.16+ ([more info](https://go.dev/doc/go1.16#go-command)). For Go 1.15 or older, use `go get` instead of `go install`.
  46
  47 ### Install from source
  48
  49 ```sh
  50 # Clone repository anywhere
  51 git clone https://gerrit.fd.io/r/govpp.git
  52 cd govpp
  53 make install-generator
  54 ```
  55
  56 NOTE: There is no need to setup or clone inside `GOPATH` for Go 1.13+ ([more info](https://go.dev/doc/go1.13#modules))
  57 and you can simply clone the repository _anywhere_ you want.
  58
  59 ## Examples
  60
  61 The [examples/](examples/) directory contains several examples for GoVPP
  62
  63 - [api-trace](examples/api-trace) - trace sent/received messages
  64 - [binapi-types](examples/binapi-types) - using common types from generated code
  65 - [multi-vpp](examples/multi-vpp) - connect to multiple VPP instances
  66 - [perf-bench](examples/perf-bench) - very basic performance test for measuring throughput
  67 - [rpc-service](examples/rpc-service) - effortless way to call VPP API via RPC client
  68 - [simple-client](examples/simple-client) - send and receive VPP API messages using GoVPP API directly
  69 - [stats-client](examples/stats-client) - client for retrieving VPP stats data
  70 - [stream-client](examples/stream-client) - using new stream API to call VPP API
  71
  72 ### Documentation
  73
  74 Further documentation can be found in [docs/](docs/) directory.
  75
  76 - [Adapters](docs/ADAPTERS.md) - detailed info about transport adapters and their implementations
  77 - [Binapi Generator](docs/GENERATOR.md) - user guide for generating VPP binary API
  78
  79 ## Quick Start
  80
  81 ### Using raw messages directly
  82
  83 Here is a sample code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
  84
  85 ```go
  86 package main
  87
  88 import (
  89     "log"
  90
  91         "git.fd.io/govpp.git"
  92         "git.fd.io/govpp.git/binapi/interfaces"
  93         "git.fd.io/govpp.git/binapi/vpe"
  94 )
  95
  96 func main() {
  97         // Connect to VPP
  98         conn, _ := govpp.Connect("/run/vpp/api.sock")
  99         defer conn.Disconnect()
 100
 101         // Open channel
 102         ch, _ := conn.NewAPIChannel()
 103         defer ch.Close()
 104
 105         // Prepare messages
 106         req := &vpe.ShowVersion{}
 107         reply := &vpe.ShowVersionReply{}
 108
 109         // Send the request
 110         err := ch.SendRequest(req).ReceiveReply(reply)
 111         if err != nil {
 112         log.Fatal("ERROR: ", err)
 113         }
 114
 115     log.Print("Version: ", reply.Version)
 116 }
 117 ```
 118
 119 For more extensive example of using raw VPP API see [simple-client](examples/simple-client).
 120
 121 ### Using RPC service client
 122
 123 Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling.
 124
 125 ```go
 126 package main
 127
 128 import (
 129     "context"
 130     "log"
 131
 132         "git.fd.io/govpp.git"
 133         "git.fd.io/govpp.git/binapi/vpe"
 134 )
 135
 136 func main() {
 137         // Connect to VPP API socket
 138         conn, _ := govpp.Connect("/run/vpp/api.sock")
 139         defer conn.Disconnect()
 140
 141         // Init vpe service client
 142     client := vpe.NewServiceClient(conn)
 143
 144         reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
 145         if err != nil {
 146                 log.Fatal("ERROR: ", err)
 147         }
 148
 149         log.Print("Version: ", reply.Version)
 150 }
 151 ```
 152
 153 For more extensive example of using RPC service client see [rpc-service](examples/rpc-service).