docs/GENERATOR.md

   1 # Binapi Generator
   2
   3 ## Install the binary API generator
   4
   5 ```sh
   6 # Install binapi generator
   7 make install-generator
   8 ```
   9
  10 > NOTE: This installs `binapi-generator` to `$GOPATH/bin` directory, ensure
  11 > it is in your `$PATH` before running the command.
  12
  13 ## Install vpp binary artifacts
  14
  15 Build locally, or download from packagecloud. Read more: https://fd.io/docs/vpp/master/gettingstarted/installing
  16
  17 ## Generate binapi (Go bindings)
  18
  19 Generating Go bindings for VPP binary API from the JSON files
  20 installed with the vpp binary artifacts - located in `/usr/share/vpp/api/`.
  21
  22 ```sh
  23 make generate-binapi
  24 INFO[0000] found 110 files in API dir "/usr/share/vpp/api"
  25 INFO[0000] Generating 203 files
  26 ```
  27
  28 The generated files will be generated under `binapi` directory.
  29
  30 ## Generate VPP binary API code (Go bindings)
  31
  32 Once you have `binapi-generator` installed, you can use it to generate Go bindings for VPP binary API
  33 using VPP APIs in JSON format. The JSON input can be specified as a single file (`input-file` argument), or
  34 as a directory that will be scanned for all `.json` files (`input-dir`). The generated Go bindings will
  35 be placed into `output-dir` (by default current working directory), where each Go package will be placed into
  36 a separated directory, e.g.:
  37
  38 ```sh
  39 binapi-generator --input-file=acl.api.json --output-dir=binapi
  40 binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi
  41 ```
  42
  43 In Go, [go generate](https://blog.golang.org/generate) tool can be leveraged to ease the code generation
  44 process. It allows specifying generator instructions in any one of the regular (non-generated) `.go` files
  45 that are dependent on generated code using special comments:
  46
  47 ```go
  48 //go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
  49 ```
  50
  51 ## Tracking down generated go code for a specific binary API
  52
  53 Golang uses capitalization to indicate exported names, so you'll have
  54 to divide through by binapi-generator transformations. Example:
  55
  56 ```
  57 define create_loopback  -> type CreateLoopback struct ...
  58    vpp binapi definition      govpp exported type definition
  59 ```
  60 The droids you're looking for will be in a file named
  61 <something>.ba.go.  Suggest:
  62
  63 ```
  64 find git.fd.io/govpp/binapi -name "*.ba.go" | xargs grep -n GoTypeName
  65 ```
  66
  67 Look at the indicated <something>.ba.go file, deduce the package name
  68 and import it. See the example above.