diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 81 |
1 files changed, 41 insertions, 40 deletions
@@ -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. |