diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ADAPTERS.md | 37 | ||||
| -rw-r--r-- | docs/GENERATOR.md | 94 |
2 files changed, 131 insertions, 0 deletions
diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md new file mode 100644 index 0000000..d3fa8b2 --- /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 go.fd.io/govpp +cd $GOPATH/src/go.fd.io/govpp +make test +make install +``` diff --git a/docs/GENERATOR.md b/docs/GENERATOR.md new file mode 100644 index 0000000..4787a05 --- /dev/null +++ b/docs/GENERATOR.md @@ -0,0 +1,94 @@ +# 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 go.fd.io/govpp/cmd/binapi-generator@latest + +# Development version (master branch) +go install go.fd.io/govpp/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 + +# Install binapi-generator +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. + +### Generating binapi + +### 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 +<something>.ba.go. Suggest: + +``` +find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName +``` + +Look at the indicated <something>.ba.go file, deduce the package name +and import it. See the example above. |