aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorOndrej Fabry <ofabry@cisco.com>2022-01-17 11:17:56 +0100
committerOndrej Fabry <ofabry@cisco.com>2022-01-17 11:17:56 +0100
commit151da936ea8952dd57261f2038fc2dcb78e8dcd7 (patch)
tree42017afebdd9e9ecb0633061ef6bd4a3f1189930
parentca1dfc3c5cfa7bc58d1b7bcfa89665da10d49092 (diff)
Update README
Change-Id: Id070a39c871a1d428523cbf2eec58dcb51e2c14a Signed-off-by: Ondrej Fabry <ofabry@cisco.com>
-rw-r--r--README.md99
-rw-r--r--docs/GENERATOR.md44
2 files changed, 72 insertions, 71 deletions
diff --git a/README.md b/README.md
index 20cd37b..5581928 100644
--- a/README.md
+++ b/README.md
@@ -2,22 +2,25 @@
[![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)
-The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API.
+The GoVPP repository contains a Go client library for interacting with the VPP,
+generator of Go bindings for the VPP binary API and various other tooling for VPP.
## Overview
+Here is a brief overview for the repository structure.
+
- [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!)
+ - [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
+ - [vppapi](binapigen/vppapi) - VPP API parser
+ - 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
@@ -26,61 +29,13 @@ The GoVPP repository contains a Go client library for interacting with the VPP a
- [proxy](proxy) - contains client/server implementation for proxy
- [test](test) - integration tests, benchmarks and performance tests
-## Install binapi-generator
-
-### Prerequisites
-
-- Go 1.13+ ([download]((https://golang.org/dl)))
-
-### Install via Go toolchain
-
-```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
-```
-
-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
-```
-
-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.
-
-## Examples
-
-The [examples/](examples/) directory contains several examples for GoVPP
-
-- [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
-
## Quick Start
+Below are some code examples showing GoVPP client interacting with VPP API.
+
### Using raw messages directly
-Here is a sample code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
+Here is a code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
```go
package main
@@ -116,7 +71,7 @@ func main() {
}
```
-For more extensive example of using raw VPP API see [simple-client](examples/simple-client).
+For a complete example see [simple-client](examples/simple-client).
### Using RPC service client
@@ -150,4 +105,24 @@ func main() {
}
```
-For more extensive example of using RPC service client see [rpc-service](examples/rpc-service).
+For a complete example see [rpc-service](examples/rpc-service).
+
+### More code examples
+
+More examples can be found in [examples](examples) directory.
+
+- [api-trace](api-trace) - trace sent/received messages
+- [binapi-types](binapi-types) - using common types from generated code
+- [multi-vpp](multi-vpp) - connect to multiple VPP instances
+- [perf-bench](perf-bench) - very basic performance test for measuring throughput
+- [rpc-service](rpc-service) - effortless way to call VPP API via RPC client
+- [simple-client](simple-client) - send and receive VPP API messages using GoVPP API directly
+- [stats-client](stats-client) - client for retrieving VPP stats data
+- [stream-client](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
diff --git a/docs/GENERATOR.md b/docs/GENERATOR.md
index d7832ac..9cc40fc 100644
--- a/docs/GENERATOR.md
+++ b/docs/GENERATOR.md
@@ -1,20 +1,46 @@
-# Binapi Generator
+# Generator
-## Install the binary API generator
+This document contains information about GoVPP generator which is used for generating Go bindings for VPP binary API.
+
+## Installation
+
+### Prerequisites
+
+- Go 1.13+ ([download](https://golang.org/dl))
+
+### Install via Go toolchain
+
+```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
+```
+
+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
-# Install binapi generator
+# Clone repository anywhere
+git clone https://gerrit.fd.io/r/govpp.git
+cd govpp
+
+# 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.
+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.
+
+### Generating binapi
-## Install vpp binary artifacts
+### Install vpp binary artifacts
Build locally, or download from packagecloud. Read more: https://fd.io/docs/vpp/master/gettingstarted/installing
-## Generate binapi (Go bindings)
+### 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/`.
@@ -27,7 +53,7 @@ INFO[0000] Generating 203 files
The generated files will be generated under `binapi` directory.
-## Generate VPP binary API code (Go bindings)
+### 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
@@ -48,7 +74,7 @@ that are dependent on generated code using special comments:
//go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
```
-## Tracking down generated go code for a specific binary 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: