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)
5 The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API.
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
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
29 ## Install binapi-generator
33 - Go 1.13+ ([download]((https://golang.org/dl)))
35 ### Install via Go toolchain
38 # Latest version (most recent tag)
39 go install git.fd.io/govpp.git/cmd/binapi-generator@latest
41 # Development version (master branch)
42 go install git.fd.io/govpp.git/cmd/binapi-generator@master
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`.
47 ### Install from source
50 # Clone repository anywhere
51 git clone https://gerrit.fd.io/r/govpp.git
53 make install-generator
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.
61 The [examples/](examples/) directory contains several examples for GoVPP
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
74 Further documentation can be found in [docs/](docs/) directory.
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
81 ### Using raw messages directly
83 Here is a sample code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
92 "git.fd.io/govpp.git/binapi/interfaces"
93 "git.fd.io/govpp.git/binapi/vpe"
98 conn, _ := govpp.Connect("/run/vpp/api.sock")
99 defer conn.Disconnect()
102 ch, _ := conn.NewAPIChannel()
106 req := &vpe.ShowVersion{}
107 reply := &vpe.ShowVersionReply{}
110 err := ch.SendRequest(req).ReceiveReply(reply)
112 log.Fatal("ERROR: ", err)
115 log.Print("Version: ", reply.Version)
119 For more extensive example of using raw VPP API see [simple-client](examples/simple-client).
121 ### Using RPC service client
123 Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling.
132 "git.fd.io/govpp.git"
133 "git.fd.io/govpp.git/binapi/vpe"
137 // Connect to VPP API socket
138 conn, _ := govpp.Connect("/run/vpp/api.sock")
139 defer conn.Disconnect()
141 // Init vpe service client
142 client := vpe.NewServiceClient(conn)
144 reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
146 log.Fatal("ERROR: ", err)
149 log.Print("Version: ", reply.Version)
153 For more extensive example of using RPC service client see [rpc-service](examples/rpc-service).