docs/GENERATOR.md

   1 # Generator
   2
   3 This document contains information about GoVPP generator which is used for generating Go bindings for VPP binary API.
   4
   5 ## Installation
   6
   7 ### Prerequisites
   8
   9 - Go 1.13+ ([download](https://golang.org/dl))
  10
  11 ### Install via Go toolchain
  12
  13 ```shell
  14 # Latest version (most recent tag)
  15 go install git.fd.io/govpp.git/cmd/binapi-generator@latest
  16
  17 # Development version (master branch)
  18 go install git.fd.io/govpp.git/cmd/binapi-generator@master
  19 ```
  20
  21 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`.
  22
  23 ### Install from source
  24
  25 ```sh
  26 # Clone repository anywhere
  27 git clone https://gerrit.fd.io/r/govpp.git
  28 cd govpp
  29
  30 # Install binapi-generator
  31 make install-generator
  32 ```
  33
  34 NOTE: There is no need to setup or clone inside `GOPATH` for Go 1.13+ ([more info](https://go.dev/doc/go1.13#modules))
  35 and you can simply clone the repository _anywhere_ you want.
  36
  37 ### Generating binapi
  38
  39 ### Install vpp binary artifacts
  40
  41 Build locally, or download from packagecloud. Read more: https://fd.io/docs/vpp/master/gettingstarted/installing
  42
  43 ### Generate binapi (Go bindings)
  44
  45 Generating Go bindings for VPP binary API from the JSON files
  46 installed with the vpp binary artifacts - located in `/usr/share/vpp/api/`.
  47
  48 ```sh
  49 make generate-binapi
  50 INFO[0000] found 110 files in API dir "/usr/share/vpp/api"
  51 INFO[0000] Generating 203 files
  52 ```
  53
  54 The generated files will be generated under `binapi` directory.
  55
  56 ### Generate VPP binary API code (Go bindings)
  57
  58 Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API
  59 using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
  60 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
  61 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
  62 a separated directory, e.g.:
  63
  64 ```sh
  65 binapi-generator --input-file=acl.api.json --output-dir=binapi
  66 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
  67 ```
  68
  69 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
  70 process. It allows specifying generator instructions in any one of the regular (non-generated) `.go` files
  71 that are dependent on generated code using special comments:
  72
  73 ```go
  74 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
  75 ```
  76
  77 ### Tracking down generated go code for a specific binary API
  78
  79 Golang uses capitalization to indicate exported names, so you'll have
  80 to divide through by binapi-generator transformations. Example:
  81
  82 ```
  83 define create_loopback  -> type CreateLoopback struct ...
  84    vpp binapi definition      govpp exported type definition
  85 ```
  86 The droids you're looking for will be in a file named
  87 <something>.ba.go.  Suggest:
  88
  89 ```
  90 find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName
  91 ```
  92
  93 Look at the indicated <something>.ba.go file, deduce the package name
  94 and import it. See the example above.