docs/gettingstarted/developers/add_plugin_goapi.rst

   1 .. _add_plugin_goapi:
   2
   3 Add a plugin's GO API
   4 =====================
   5
   6 In order to use your plugin's API with GO, you will need to use
   7 a GO client and GO definitions of the API messages that you defined
   8 in ``myplugin.api`` (go bindings).
   9
  10 These two things can be found in `govpp <https://github.com/FDio/govpp>`_
  11
  12 * The API client lives in `./core`
  13 * The api-generator lives in `./binapigen`
  14 * A sample of its output (the go bindings) for VPP's latest version lives in `./binapi`
  15
  16 To generate the go bindings for your plugin. Assuming :
  17 * ``/home/vpp`` is a VPP clone with your plugin in it.
  18 * ``/home/controlplane`` is a go controlplane repo
  19
  20 .. code-block:: console
  21
  22     $ mkdir /home/controlplane/vpp-go-bindings
  23     $ git clone https://github.com/FDio/govpp>
  24     $ cd govpp
  25     $ BINAPI_DIR=/home/controlplane/vpp-go-bindings VPP_DIR=/home/vpp make gen-binapi-from-code
  26
  27 This will generate the go-bindings in ``/home/controlplane/vpp-go-bindings``
  28 For example ``vpp-go-bindings/myplugin/myplugin.ba.go`` will contain :
  29
  30 .. code-block:: go
  31
  32     // MypluginEnableDisable defines message 'myplugin_enable_disable'.
  33     type MypluginEnableDisable struct {
  34             EnableDisable bool                           `binapi:"bool,name=enable_disable" json:"enable_disable,omitempty"`
  35             SwIfIndex     interface_types.InterfaceIndex `binapi:"interface_index,name=sw_if_index" json:"sw_if_index,omitempty"`
  36     }
  37
  38
  39 You can then use the generated go bindings in your go code like this :
  40
  41 .. code-block:: go
  42
  43     package main
  44
  45     import (
  46             "fmt"
  47             "git.fd.io/govpp.git"
  48             "git.fd.io/govpp.git/binapi/interfaces"
  49             "git.fd.io/govpp.git/binapi/vpe"
  50
  51             "myplugin.io/controlplane/vpp-go-bindings/myplugin/myplugin"
  52     )
  53
  54     func main() {
  55             // Connect to VPP
  56             conn, _ := govpp.Connect("/run/vpp/api.sock")
  57             defer conn.Disconnect()
  58
  59             // Open channel
  60             ch, _ := conn.NewAPIChannel()
  61             defer ch.Close()
  62
  63             request := &vpe.MypluginEnableDisable{
  64                 EnableDisable: true,
  65             }
  66             reply := &vpe.MypluginEnableDisableReply{}
  67
  68             err := ch.SendRequest(request).ReceiveReply(reply)
  69             if err != nil {
  70                     fmt.Errorf("SendRequest: %w\n", err)
  71             }
  72     }
  73
  74 As you will need to import (or ``go get "git.fd.io/govpp.git"``) to leverage the API
  75 client in your code, you might want to use the api-generator directly from the
  76 clone ``go build`` fetches for you. You can do this with :
  77
  78 .. code-block:: console
  79
  80   $ export GOVPP_DIR=$(go list -f '{{.Dir}}' -m git.fd.io/govpp.git)
  81   $ cd $GOVPP_DIR && go build -o /some/bin/dir ./cmd/binapi-generator
  82   $ # instead of make gen-binapi-from-code you can rewrite the code to target
  83   $ # your version ./binapi-generator