From ca1dfc3c5cfa7bc58d1b7bcfa89665da10d49092 Mon Sep 17 00:00:00 2001 From: Ondrej Fabry Date: Fri, 14 Jan 2022 15:02:10 +0100 Subject: doc: Update README Change-Id: I577ec64c78fe5684fcef109c216810e5fe6b4009 Signed-off-by: Ondrej Fabry --- README.md | 252 ++++++++++++++++++++---------------------------------- docs/ADAPTERS.md | 37 ++++++++ docs/GENERATOR.md | 68 +++++++++++++++ 3 files changed, 196 insertions(+), 161 deletions(-) create mode 100644 docs/ADAPTERS.md create mode 100644 docs/GENERATOR.md diff --git a/README.md b/README.md index 509e590..20cd37b 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,93 @@ # GoVPP -The GoVPP projects provides the API for communication with VPP from Go. - -It consists of the following packages: -- [adapter](adapter/): adapter between GoVPP core and the VPP binary/stats API -- [api](api/): API for communication with GoVPP core -- [cmd/binapi-generator](cmd/binapi-generator/): generator for the VPP binary API definitions in JSON format to Go code -- [codec](codec/): handles encoding/decoding of generated messages into binary form -- [core](core/): essential functionality of the GoVPP -- [examples](examples/): examples that use the GoVPP API in real use-cases of VPP management application -- [extras](extras/): contains Go implementation for libmemif library -- [govpp](govpp.go): provides the entry point to GoVPP functionality - -The design with separated GoVPP [API package](api/) and the GoVPP [core package](core/) enables -plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP and multiple -entities act as clients that are using the master for the communication with VPP. -The clients can be built into standalone shared libraries without the need -of linking the GoVPP core and all its dependencies into them. +[![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) -``` - +--------------+ - +--------------+ | | - | | | plugin | - | | | | - | App | +--------------+ - | | +------+ GoVPP API | - | | | +--------------+ - +--------------+ GoVPP | - | | channels | +--------------+ - | GoVPP core +------------+ | | - | | | | plugin | - +------+-------+ | | | - | | +--------------+ - | +------+ GoVPP API | - | binary API +--------------+ - | - +------+-------+ - | | - | VPP process | - | | - +--------------+ -``` +The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API. -## Prerequisites +## Overview -- [Go 1.13](https://golang.org/dl) +- [govpp](govpp.go) - the entry point for the GoVPP client + - [adapter](adapter) - VPP binary & stats API interface + - [mock](adapter/mock) - Mock adapter used for testing + - [socketclient](adapter/socketclient) - Go implementation of VPP API client for unix socket + - [statsclient](adapter/statsclient) - Go implementation of VPP Stats client for shared memory + - [vppapiclient](adapter/vppapiclient) - CGo wrapper of vppapiclient library (DEPRECATED!) + - [api](api) - GoVPP client API + - [binapigen](binapigen) - library for generating code from VPP API + - [vppapi](binapigen/vppapi) - VPP API parser + - [cmd](cmd) + - [binapi-generator](cmd/binapi-generator) - VPP binary API generator + - [vpp-proxy](cmd/vpp-proxy) - VPP proxy for remote access + - [codec](codec) - handles encoding/decoding of generated messages into binary form + - [core](core) - implementation of the GoVPP client + - [docs](docs) - documentation + - [examples](examples) - examples demonstrating GoVPP functionality + - [internal](internal) - packages used internally by GoVPP + - [proxy](proxy) - contains client/server implementation for proxy + - [test](test) - integration tests, benchmarks and performance tests -## Quick Start +## Install binapi-generator -Make sure that $GOPATH, $GOROOT, and $PATH are set. If you cloned the -govpp repo manually, you'll probably regret it. +### Prerequisites -Instead: +- Go 1.13+ ([download]((https://golang.org/dl))) -``` - go get git.fd.io/govpp.git -``` +### Install via Go toolchain -### Build and install the govpp binary api generator +```shell +# Latest version (most recent tag) +go install git.fd.io/govpp.git/cmd/binapi-generator@latest +# Development version (master branch) +go install git.fd.io/govpp.git/cmd/binapi-generator@master ``` - $ cd $GOPATH/src/git.fd.io/govpp.git/cmd/binapi-generator - $ go install - $ binapi-generator -version - govpp v0.4.0-dev # or some such + +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`. + +### Install from source + +```sh +# Clone repository anywhere +git clone https://gerrit.fd.io/r/govpp.git +cd govpp +make install-generator ``` -### Install vpp binary artifacts (including the "vpp-dev" package) -Build locally, or download from packagecloud. Beyond the scope of -README.md. +NOTE: There is no need to setup or clone inside `GOPATH` for Go 1.13+ ([more info](https://go.dev/doc/go1.13#modules)) +and you can simply clone the repository _anywhere_ you want. -### Generate binapi (Go bindings) +## Examples -Generating Go bindings for VPP binary API from the JSON files -installed with the vpp binary artifacts. +The [examples/](examples/) directory contains several examples for GoVPP -``` - $ cd $GOPATH/src/git.fd.io/govpp.git - $ binapi-generator --output-dir=binapi - INFO[0000] found 110 files in API dir "/usr/share/vpp/api" - INFO[0000] Generating 203 files -``` +- [api-trace](examples/api-trace) - trace sent/received messages +- [binapi-types](examples/binapi-types) - using common types from generated code +- [multi-vpp](examples/multi-vpp) - connect to multiple VPP instances +- [perf-bench](examples/perf-bench) - very basic performance test for measuring throughput +- [rpc-service](examples/rpc-service) - effortless way to call VPP API via RPC client +- [simple-client](examples/simple-client) - send and receive VPP API messages using GoVPP API directly +- [stats-client](examples/stats-client) - client for retrieving VPP stats data +- [stream-client](examples/stream-client) - using new stream API to call VPP API + +### Documentation + +Further documentation can be found in [docs/](docs/) directory. + +- [Adapters](docs/ADAPTERS.md) - detailed info about transport adapters and their implementations +- [Binapi Generator](docs/GENERATOR.md) - user guide for generating VPP binary API -The golang binding files land here: $GOPATH/src/git.fd.io/govpp.git/binapi +## Quick Start -#### Example Usage +### Using raw messages directly -Here's a simple sample program which prints vpp version info, and -creates a loopback interface. +Here is a sample code for low-level way to access the VPP API using the generated messages directly for sending/receiving. ```go package main import ( - "fmt" + "log" + "git.fd.io/govpp.git" "git.fd.io/govpp.git/binapi/interfaces" "git.fd.io/govpp.git/binapi/vpe" @@ -114,110 +108,46 @@ func main() { // Send the request err := ch.SendRequest(req).ReceiveReply(reply) - - if err != nil { - fmt.Errorf("SendRequest: %w\n", err) - } - - fmt.Printf("Program: %s\nVersion: %s\nBuildDate: %s\n", - reply.Program, reply.Version, reply.BuildDate) - - loop_create := &interfaces.CreateLoopback{} - loop_create_reply := &interfaces.CreateLoopbackReply{} - - err = ch.SendRequest(loop_create).ReceiveReply(loop_create_reply) - if err != nil { - fmt.Errorf("create_loopback: %w\n", err) + log.Fatal("ERROR: ", err) } - fmt.Printf("create_loopback: sw_if_index %d", - int(loop_create_reply.SwIfIndex)) + log.Print("Version: ", reply.Version) } ``` -The example above uses GoVPP API to communicate over underlying go channels, -see [example client](examples/simple-client/simple_client.go) -for more examples, including the example on how to use the Go channels directly. - -### Tracking down generated go code for a specific binary API - -Golang uses capitalization to indicate exported names, so you'll have -to divide through by binapi-generator transformations. Example: - -``` - define create_loopback -> type CreateLoopback struct ... - vpp binapi definition govpp exported type definition -``` -The droids you're looking for will be in a file named -.ba.go. Suggest: - -``` - find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName -``` - -Look at the indicated .ba.go file, deduce the package name -and import it. See the example above. - -## Build & Install - -### Using pure Go adapters (recommended) - -GoVPP now supports pure Go implementation for VPP binary API. This does -not depend on CGo or any VPP library and can be easily compiled. - -There are two packages providing pure Go implementations in GoVPP: -- [`socketclient`](adapter/socketclient) - for VPP binary API (via unix socket) -- [`statsclient`](adapter/statsclient) - for VPP stats API (via shared memory) +For more extensive example of using raw VPP API see [simple-client](examples/simple-client). -### Using vppapiclient library wrapper (requires CGo) +### Using RPC service client -GoVPP also provides vppapiclient package which actually uses -`vppapiclient.so` library from VPP codebase to communicate with VPP API. -To build GoVPP, `vpp-dev` package must be installed, -either [from packages][from-packages] or [from sources][from-sources]. +Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling. -To build & install `vpp-dev` from sources: - -```sh -git clone https://gerrit.fd.io/r/vpp -cd vpp -make install-dep -make pkg-deb -cd build-root -sudo dpkg -i vpp*.deb -``` - -To build & install GoVPP: +```go +package main -```sh -go get -u git.fd.io/govpp.git -cd $GOPATH/src/git.fd.io/govpp.git -make test -make install -``` +import ( + "context" + "log" -## Generating Go bindings with binapi-generator + "git.fd.io/govpp.git" + "git.fd.io/govpp.git/binapi/vpe" +) -Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API -using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or -as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will -be placed into `output-dir` (by default current working directory), where each Go package will be placed into -a separated directory, e.g.: +func main() { + // Connect to VPP API socket + conn, _ := govpp.Connect("/run/vpp/api.sock") + defer conn.Disconnect() -```sh -binapi-generator --input-file=acl.api.json --output-dir=binapi -binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi -``` + // Init vpe service client + client := vpe.NewServiceClient(conn) -In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation -process. It allows to specify generator instructions in any one of the regular (non-generated) `.go` files -that are dependent on generated code using special comments, e.g. the one from -[example client](examples/simple-client/simple_client.go): + reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{}) + if err != nil { + log.Fatal("ERROR: ", err) + } -```go -//go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api + log.Print("Version: ", reply.Version) +} ``` -[from-packages]: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages -[from-sources]: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package +For more extensive example of using RPC service client see [rpc-service](examples/rpc-service). diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md new file mode 100644 index 0000000..870b5fe --- /dev/null +++ b/docs/ADAPTERS.md @@ -0,0 +1,37 @@ +# Adapters + +## Pure-Go implementation (recommended) + +GoVPP now supports pure Go implementation for VPP binary API. This does +not depend on CGo or any VPP library and can be easily compiled. + +There are two packages providing pure Go implementations in GoVPP: +- [`socketclient`](adapter/socketclient) - for VPP binary API (via unix socket) +- [`statsclient`](adapter/statsclient) - for VPP stats API (via shared memory) + +## CGo wrapper for vppapiclient library (deprecated) + +GoVPP also provides vppapiclient package which actually uses +`vppapiclient.so` library from VPP codebase to communicate with VPP API. +To build GoVPP, `vpp-dev` package must be installed, +either [from packages][from-packages] or [from sources][from-sources]. + +To build & install `vpp-dev` from sources: + +```sh +git clone https://gerrit.fd.io/r/vpp +cd vpp +make install-dep +make pkg-deb +cd build-root +sudo dpkg -i vpp*.deb +``` + +To build & install GoVPP: + +```sh +go get -u git.fd.io/govpp.git +cd $GOPATH/src/git.fd.io/govpp.git +make test +make install +``` diff --git a/docs/GENERATOR.md b/docs/GENERATOR.md new file mode 100644 index 0000000..d7832ac --- /dev/null +++ b/docs/GENERATOR.md @@ -0,0 +1,68 @@ +# Binapi Generator + +## Install the binary API generator + +```sh +# Install binapi generator +make install-generator +``` + +> NOTE: This installs `binapi-generator` to `$GOPATH/bin` directory, ensure +> it is in your `$PATH` before running the command. + +## Install vpp binary artifacts + +Build locally, or download from packagecloud. Read more: https://fd.io/docs/vpp/master/gettingstarted/installing + +## Generate binapi (Go bindings) + +Generating Go bindings for VPP binary API from the JSON files +installed with the vpp binary artifacts - located in `/usr/share/vpp/api/`. + +```sh +make generate-binapi +INFO[0000] found 110 files in API dir "/usr/share/vpp/api" +INFO[0000] Generating 203 files +``` + +The generated files will be generated under `binapi` directory. + +## Generate VPP binary API code (Go bindings) + +Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API +using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or +as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will +be placed into `output-dir` (by default current working directory), where each Go package will be placed into +a separated directory, e.g.: + +```sh +binapi-generator --input-file=acl.api.json --output-dir=binapi +binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi +``` + +In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation +process. It allows specifying generator instructions in any one of the regular (non-generated) `.go` files +that are dependent on generated code using special comments: + +```go +//go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api +``` + +## Tracking down generated go code for a specific binary API + +Golang uses capitalization to indicate exported names, so you'll have +to divide through by binapi-generator transformations. Example: + +``` +define create_loopback -> type CreateLoopback struct ... + vpp binapi definition govpp exported type definition +``` +The droids you're looking for will be in a file named +.ba.go. Suggest: + +``` +find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName +``` + +Look at the indicated .ba.go file, deduce the package name +and import it. See the example above. -- cgit 1.2.3-korg