blob: 9cc40fcb6d45d2e891f05d20b427d13f111414ec (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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 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
# 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.
|
