Migrate remaining binaries to use cobra

[ajm188]

General Process

1. Make a cli subpackage in that binary's cmd directory to house the cobra command and supporting files.

Example

// go/cmd/vtorc/cli/cli.go

package cli

import (
	"github.com/spf13/cobra"

	"vitess.io/vitess/go/acl"
	"vitess.io/vitess/go/vt/servenv"
	"vitess.io/vitess/go/vt/vtorc/config"
	"vitess.io/vitess/go/vt/vtorc/inst"
	"vitess.io/vitess/go/vt/vtorc/logic"
	"vitess.io/vitess/go/vt/vtorc/server"
)

var Main = &cobra.Command{
	Use: "vtorc",
	Short: "help text goes here",
	Args: cobra.NoArgs, // (ExactArgs, MinimumArgs, RangeArgs, and so on, if the binary can take positional arguments)
	Version: servenv.AppVersion.String(),
	PreRunE: servenv.CobraPreRunE, // loads viper registry and sets up debug handler
	Run: run, // use RunE if you need to return an error to exit early
}

func run(cmd *cobra.Command, args []string) {
	// All logic from binaries original main() that happened _after_ servenv.ParseFlags()
	// goes here.
}

func init() {
	// Flag registration goes here. For example:
	servenv.RegisterDefaultFlags()
	servenv.RegisterFlags()
	servenv.RegisterGRPCServerFlags()
	servenv.RegisterGRPCServerAuthFlags()
	servenv.RegisterServiceMapFlag()

	// This moves any flags registered with servenv.OnParseFor(<cmd>) where `Main.Use` == <cmd>.
	servenv.MoveFlagsToCobraCommand(Main)

	acl.RegisterFlags(Main.Flags())
}

2. Move any plugin files to the cli subpackage.

Example

$ git mv go/cmd/vtorc/plugin_* go/cmd/vtorc/cli

Note that the goal here is to ensure all flags get registered by the time the cli subpackage is finished imported. This way the website doc generation (next step) includes all the flags, as anything defined in a main package won't get imported and will get lost.

So, if there are other files in the binary's main package that define or import flags, you'll need to move those as well.

3. Create a docgen subpackage to facilitate automatic website doc generation.

Example

// go/cmd/vtorc/docgen/main.go

package main

import (
	"github.com/spf13/cobra"

	"vitess.io/vitess/go/cmd/internal/docgen"
	"vitess.io/vitess/go/cmd/vtorc/cli"
)

func main() {
	var dir string
	cmd := cobra.Command{
		Use: "docgen [-d <dir>]",
		RunE: func(cmd *cobra.Command, args []string) error {
			return docgen.GenerateMarkdownTree(cli.Main, dir)
		},
	}

	cmd.Flags().StringVarP(&dir, "dir", "d", "doc", "output directory to write documentation")
	_ = cmd.Execute()
}

4. Add make targets to vitessio/website repo to generate docs for the new cobra-fied binary.

Example

# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtorc-docs
vtorc-docs:
	go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtorc

Note: if you wish to run this now, you must first ensure your changes to vitessio/vitess are committed at least locally to a branch, then you may run VITESS_DIR=~/dev/vitess COBRADOC_VERSION_PAIRS="HEAD:18.0" make vtorc-docs. You may to need to mkdir -p content/en/docs/18.0/reference/programs/vtorc first.

5. Tidying up!

• Ensure new files have copyright headers (omitted here to reduce size of text to read)
• Update flag test data in vitessio/vitess using make build generate-flag-testdata

Binaries

Full list

• mysqlctl
• mysqlctld
• [ ] query_analyzer (deleted)
• topo2topo (in progress - @ajm188)
• vtaclcheck
• vtbackup
• vtbench
• vtclient
• vtcombo
• vtctlclient (deprecated)
• vtctl
• vtctld
• vtexplain
• vtgate
• vtgateclienttest (in progress - @ajm188)
• vtorc
• vttablet
• vttestserver (in progress - @ajm188)
• vttlstest (in progress - @ajm188)
• zk (in progress - @ajm188)
• zkctl (in progress - @ajm188)
• zkctld (in progress - @ajm188)