summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorOndrej Fabry <ofabry@cisco.com>2018-08-15 12:59:25 +0200
committerOndrej Fabry <ofabry@cisco.com>2018-08-16 15:03:29 +0200
commita3bb834db727a3ac9a1ffcfeae9265e5dead851f (patch)
tree6ffe64d2dd78a4c3434c2889dd7582b74619fe2b /README.md
parentda815585c3f75c4ac073b0766dd668abf83844d8 (diff)
Refactor GoVPP
Squashed commit of the following: commit 348930db31575e9f59b3834d9fec07411f011e05 Author: Ondrej Fabry <ofabry@cisco.com> Date: Wed Aug 15 11:30:13 2018 +0200 Use debug level for log about different context commit 9fc963c559cea67a41b85c6cdadc322fb3b1fc7c Author: Ondrej Fabry <ofabry@cisco.com> Date: Wed Aug 15 11:22:03 2018 +0200 Remove annoying logs and add env vars for debugging commit fdc9fd624d13feadb602e0d03d58f8a44b7a565f Author: Ondrej Fabry <ofabry@cisco.com> Date: Wed Aug 15 11:18:47 2018 +0200 Fix printing unknown VPPApiError commit 8f968be36a91de4d4a8ea17593ba314f82aa9583 Author: Ondrej Fabry <ofabry@cisco.com> Date: Tue Aug 14 17:25:10 2018 +0200 Refactor entire GoVPP - fix some cases with inconsistent VPP messages, causing messages to be incorrectly identified as event or request - simplify API, remove direct access to internal Go channels - add module name with message to registration of messages - start watching filesystem only when vpe-api file does not exist - simplify code in message codec and remove unneeded parts - retrieve IDs of all registered messages after connect to VPP - define fallback for control ping in core to avoid duplicate registration - add SetLogLevel function to set logger level more easily - remove lot of unused code commit 34dd1b7e10ef0324aa8c4e4cc42375bd6021c6cb Author: Ondrej Fabry <ofabry@cisco.com> Date: Mon Aug 13 11:29:54 2018 +0200 Rename VnetError to VPPApiError commit c6549d6f77847a1367a12ff47fb716e2955e973a Author: Ondrej Fabry <ofabry@cisco.com> Date: Mon Aug 13 10:23:43 2018 +0200 Fix examples and regenerate binapi commit 4612e36b416779771f5efab4fc654c2766d2cb1c Author: Ondrej Fabry <ofabry@cisco.com> Date: Mon Aug 13 09:51:22 2018 +0200 Add parsing and generation for services commit ac9c5280c5aa27e325f327609e2364cc66f3723f Author: Ondrej Fabry <ofabry@cisco.com> Date: Fri Aug 10 14:30:15 2018 +0200 Fix exit status on error and add continue-onerror flag commit 9b3f4ef9fc7c8c62037fa107085eae18a8725314 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 15:20:56 2018 +0200 Return VnetError when Retval != 0 commit 8fd21a907b5e628ec4d2026215b83d15da96c297 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 14:59:05 2018 +0200 Add all missing errors from api_errno.h commit 08450f288d3046ebaecf40203174ae342a07f1eb Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 14:29:27 2018 +0200 Update README commit d8dced0728dd62243539be741868fb7d9b8de4cc Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 13:59:59 2018 +0200 Regenerate vpe in core commit 254da7592cdbf634cf7aa46ae36ce7bb6d4ee555 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 13:37:00 2018 +0200 Add VnetError type for Retvals commit 4475c1087fb53ab4c788e530bc7fef7cfc89d2cd Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 13:36:07 2018 +0200 Add registration API commit 892a3ea5a2c703e2f7c29331663f6a6fa706bff5 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 13:30:43 2018 +0200 Generate registration for messages and check all IDs on connect commit 389ed03b6e7082260281866c3449d72d72347c99 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 11:32:41 2018 +0200 Show error for empty adapter (on Darwin/Windows) commit ef1ea040d656ade64242432dc5f06810ed8dcde6 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 11:31:37 2018 +0200 Improve logged info commit d4adae3b14ed54c8d693060dd857fa9ba5ec8e06 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 11:27:48 2018 +0200 Update examples commit 63921e1346014701a22639a2611129563bb1eb78 Author: Ondrej Fabry <ofabry@cisco.com> Date: Thu Aug 9 11:02:56 2018 +0200 Generate unions and fix some issues - add comments between sections - define structs on single line if it has no fields - generate unions with setters/getters for each field - fix detection of message type commit 6ab3e3fa590b245898306a6ffaf32c7721eab60c Author: Ondrej Fabry <ofabry@cisco.com> Date: Wed Aug 8 15:37:10 2018 +0200 Refactor binapi-generator - split JSON parsing from code generation - parse and generate enums - parse unions (no generation yet) - change output file suffix to '.ba.go' - cleanup and simplify code - split code into files - add flag for debug mode Change-Id: I58f685e0d4c7a38e9a7b6ea0a1f47792d95d7399 Signed-off-by: Ondrej Fabry <ofabry@cisco.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md81
1 files changed, 41 insertions, 40 deletions
diff --git a/README.md b/README.md
index a5088f6..f1c83c6 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,61 @@
-## GoVPP
-
-This set of packages provide the API for communication with VPP from Go. It consists of the following packages:
-
-- [govpp](govpp.go): provides the entry point to govpp functionality
-- [api](api/api.go): API for communication with govpp core using Go channels (without the need of importing the govpp core package itself),
-- [core](core/): main functionality of the govpp, sends and receives the messages to/from VPP using the adapter, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP,
-- [adapter](adapter/): adapter between govpp core and the VPP, responsible for sending and receiving binary-encoded data via shared memory,
-- [binapi-generator](cmd/binapi-generator/generator.go): Generator of Go structs out of the VPP binary API definitions in JSON format,
-- [examples](examples/): example VPP management application that exercises the govpp API on real-world use-cases.
-
-The design with separated govpp API package ([api](api/api.go)) and the govpp core package ([core](core/)) enables
-plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP (e.g. Agent
-Core on the schema below) and multiple entities act as clients that are using the master for the communication with
-VPP (Agent Plugins on the schema below). The clients can be built into standalone shared libraries without the need
-of linking the govpp core and all its dependencies into them.
+# GoVPP
+
+This set of packages provide the API for communication with VPP from Go.
+
+It consists of the following packages:
+- [adapter](adapter/): adapter between GoVPP core and the VPP
+- [api](api/api.go): API for communication with GoVPP core
+- [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/): main 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/api.go) 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.
```
+--------------+
+--------------+ | |
- | | | Agent Plugin |
+ | | | App plugin |
| | | |
- | Agent Core | +--------------+
- | | +------+ govpp API |
+ | App | +--------------+
+ | | +------+ GoVPP API |
| | | +--------------+
+--------------+ Go |
| | channels | +--------------+
- | govpp core +------------+ | |
- | | | | Agent Plugin |
+ | GoVPP core +------------+ | |
+ | | | | App plugin |
+------+-------+ | | |
| | +--------------+
-binary API | +------+ govpp API |
- (shmem) | +--------------+
+binary API | +------+ GoVPP API |
+ (shmem) | +--------------+
|
+------+-------+
| |
- | VPP |
+ | VPP process |
| |
+--------------+
```
+## Quick Start
+
+#### Code Generator
-## Example usage
Generating Go bindings from the JSON files located in the `/usr/share/vpp/api/` directory
into the Go packages that will be created inside of the `bin_api` directory:
```
binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
```
+#### Example Usage
+
Usage of the generated bindings:
+
```go
func main() {
conn, _ := govpp.Connect()
@@ -87,13 +95,14 @@ func main() {
The example above uses simple wrapper API over underlying go channels, see [example client](examples/cmd/simple-client/simple_client.go)
for more examples, including the example on how to use the Go channels directly.
-
## Build & Installation Procedure
-Govpp uses `vppapiclient` library from VPP codebase to communicate with VPP. To build govpp, vpp-dev package must be installed,
+
+Govpp uses `vppapiclient` library from VPP codebase to communicate with VPP. To build GoVPP, vpp-dev package must be installed,
either [from packages](https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages) or
[from sources](https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package).
To build & install `vpp-dev` from sources:
+
```
git clone https://gerrit.fd.io/r/vpp
cd vpp
@@ -104,7 +113,8 @@ cd build-root
sudo dpkg -i vpp*.deb
```
-To build & install all govpp binaries into your `$GOPATH`:
+To build & install all GoVPP binaries into your `$GOPATH`:
+
```
go get git.fd.io/govpp.git
cd $GOPATH/src/git.fd.io/govpp.git
@@ -112,8 +122,8 @@ make
make install
```
-
## Building Go bindings from VPP binary APIs
+
Once you have `binapi-generator` installed in your `$GOPATH`, you can use it to generate Go bindings from
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
@@ -129,16 +139,7 @@ In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to
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/cmd/simple-client/simple_client.go):
-```go
-// go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
-```
-
-The comment must start at the beginning of the line and have no spaces between the `//` and the `go:generate`.
-After that marker, the rest of the line specifies a command for `go generate` to run.
-The `go generate` tool automatically traverses the code base, looks for the special comments in Go code and
-invokes the code generation, e.g.:
-```
-go generate ./...
+```go
+//go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
```
-Invokes all `go:generate` rules in all Go packages recursively.