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,
   6 generator of Go bindings for the VPP binary API and various other tooling for VPP.
   7
   8 ## Overview
   9
  10 Here is a brief overview for the repository structure.
  11
  12 - [govpp](govpp.go) - the entry point for the GoVPP client
  13   - [adapter](adapter) - VPP binary & stats API interface
  14     - [mock](adapter/mock) - Mock adapter used for testing
  15     - [socketclient](adapter/socketclient) - Go implementation of VPP API client for unix socket
  16     - [statsclient](adapter/statsclient) - Go implementation of VPP Stats client for shared memory
  17     - [vppapiclient](adapter/vppapiclient) - CGo wrapper of vppapiclient library (DEPRECATED!)
  18   - [api](api) - GoVPP client API
  19   - [binapigen](binapigen) - library for generating code from VPP API
  20     - [vppapi](binapigen/vppapi) - VPP API parser
  21   - cmd/
  22     - [binapi-generator](cmd/binapi-generator) - VPP binary API generator
  23     - [vpp-proxy](cmd/vpp-proxy) - VPP proxy for remote access
  24   - [codec](codec) - handles encoding/decoding of generated messages into binary form
  25   - [core](core) - implementation of the GoVPP client
  26   - [docs](docs) - documentation
  27   - [examples](examples) - examples demonstrating GoVPP functionality
  28   - [internal](internal) - packages used internally by GoVPP
  29   - [proxy](proxy) - contains client/server implementation for proxy
  30   - [test](test) - integration tests, benchmarks and performance tests
  31
  32 ## Quick Start
  33
  34 Below are some code examples showing GoVPP client interacting with VPP API.
  35
  36 ### Using raw messages directly
  37
  38 Here is a code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
  39
  40 ```go
  41 package main
  42
  43 import (
  44     "log"
  45
  46         "git.fd.io/govpp.git"
  47         "git.fd.io/govpp.git/binapi/interfaces"
  48         "git.fd.io/govpp.git/binapi/vpe"
  49 )
  50
  51 func main() {
  52         // Connect to VPP
  53         conn, _ := govpp.Connect("/run/vpp/api.sock")
  54         defer conn.Disconnect()
  55
  56         // Open channel
  57         ch, _ := conn.NewAPIChannel()
  58         defer ch.Close()
  59
  60         // Prepare messages
  61         req := &vpe.ShowVersion{}
  62         reply := &vpe.ShowVersionReply{}
  63
  64         // Send the request
  65         err := ch.SendRequest(req).ReceiveReply(reply)
  66         if err != nil {
  67         log.Fatal("ERROR: ", err)
  68         }
  69
  70     log.Print("Version: ", reply.Version)
  71 }
  72 ```
  73
  74 For a complete example see [simple-client](examples/simple-client).
  75
  76 ### Using RPC service client
  77
  78 Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling.
  79
  80 ```go
  81 package main
  82
  83 import (
  84     "context"
  85     "log"
  86
  87         "git.fd.io/govpp.git"
  88         "git.fd.io/govpp.git/binapi/vpe"
  89 )
  90
  91 func main() {
  92         // Connect to VPP API socket
  93         conn, _ := govpp.Connect("/run/vpp/api.sock")
  94         defer conn.Disconnect()
  95
  96         // Init vpe service client
  97     client := vpe.NewServiceClient(conn)
  98
  99         reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
 100         if err != nil {
 101                 log.Fatal("ERROR: ", err)
 102         }
 103
 104         log.Print("Version: ", reply.Version)
 105 }
 106 ```
 107
 108 For a complete example see [rpc-service](examples/rpc-service).
 109
 110 ### More code examples
 111
 112 More examples can be found in [examples](examples) directory.
 113
 114 - [api-trace](api-trace) - trace sent/received messages
 115 - [binapi-types](binapi-types) - using common types from generated code
 116 - [multi-vpp](multi-vpp) - connect to multiple VPP instances
 117 - [perf-bench](perf-bench) - very basic performance test for measuring throughput
 118 - [rpc-service](rpc-service) - effortless way to call VPP API via RPC client
 119 - [simple-client](simple-client) - send and receive VPP API messages using GoVPP API directly
 120 - [stats-client](stats-client) - client for retrieving VPP stats data
 121 - [stream-client](stream-client) - using new stream API to call VPP API
 122
 123 ## Documentation
 124
 125 Further documentation can be found in [docs](docs) directory.
 126
 127 - [Adapters](docs/ADAPTERS.md) - detailed info about transport adapters and their implementations
 128 - [Binapi Generator](docs/GENERATOR.md) - user guide for generating VPP binary API