README.md

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