runsc: implement -h and -help flags

This is consistent with runc; see containers/podman#27528.

Before this change:

```
$ ./runsc --help
Usage of ./runsc:
$ echo $?
2
$ ./runsc ps --help
<container-id> [ps options]  -format="table": output format. Select one of: table or json (default: table)
$ echo $?
2
```

After this change:

```
$ ./runsc --help
Usage: runsc <flags> <subcommand> <subcommand args>

runsc is the gVisor container runtime.

Functionality is provided by subcommands. For help with a specific subcommand,
use "runsc help <subcommand>".

Subcommands:
        checkpoint       checkpoint current state of container (experimental)
        create           create a secure container
        delete           delete resources held by a container
        do               Simplistic way to execute a command inside the sandbox. It's to be used for testing only.
        events           display container events such as OOM notifications, cpu, memory, and IO usage statistics
        exec             execute new process inside the container
        flags            describe all known top-level flags
        help             Print help documentation.
        kill             sends a signal to the container
        list             list containers started by runsc with the given root
        pause            pause suspends all processes in a container
        port-forward     port forward to a secure container
        ps               ps displays the processes running inside a container
        restore          restore a saved state of container (experimental)
        resume           Resume unpauses a paused container
        run              create and run a secure container
        spec             create a new OCI bundle specification file
        start            start a secure container
        state            get the state of a container
        tar              creates tar archives from container filesystems
        wait             wait on a process inside a container

Subcommands for debug:
        debug            shows a variety of debug information
        read-control     read a cgroups control value inside the container
        statefile        shows information about a statefile
        symbolize        Convert synthetic instruction pointers from kcov into positions in the runsc source code. Only used when Go coverage is enabled.
        usage            Usage shows application memory usage across various categories in bytes.
        write-control    write a cgroups control value inside the container

Subcommands for helpers:
        cpu-features     list CPU features supported on current machine
        install          adds a runtime to docker daemon configuration
        mitigate         mitigate mitigates the underlying system against side channel attacks
        nvproxy          shows information about nvproxy support
        trace            manages trace sessions for a given sandbox
        uninstall        removes a runtime from docker daemon configuration

Subcommands for internal use only:
        boot             launch a sandbox process
        gofer            launch a gofer process that proxies access to container files
        umount           umount the specified directory lazily when one byte is read from sync-fd

Subcommands for metrics:
        export-metrics   export metric data for the sandbox
        metric-metadata  export metric metadata of metrics registered in this build, in text proto format
        metric-server    implements Prometheus metrics HTTP endpoint

Additional help topics (Use "runsc help <topic>" to see help on the topic):
        platforms        Print a list of available platforms.
        syscalls         Print compatibility information for syscalls.

Use "runsc flags" for a list of top-level flags
$ echo $?
0
$ ./runsc ps --help
<container-id> [ps options]  -format="table": output format. Select one of: table or json (default: table)
  -h=false: equivalent to the 'help' flag
  -help=false: show this message and exit
$ echo $?
0
```

PiperOrigin-RevId: 836395969

Author: nixprime

runsc/cli/BUILD

@@ -7,7 +7,10 @@ package(
 
 go_library(
     name = "cli",
-    srcs = ["cli.go"],
+    srcs = [
+        "cli.go",
+        "help.go",
+    ],
     visibility = [
         "//runsc:__subpackages__",
     ],

runsc/cli/cli.go

@@ -58,12 +58,21 @@ var (
 // Run runs the binary, whose behavior is determined by the subcommand passed
 // on the command line. forEachCmd invokes the passed callback for each
 // supported subcommand.
-func Run(forEachCmd func(cb func(cmd subcommands.Command, group string))) {
+func Run(forEachCmd func(cb func(cmd subcommands.Command, group string), help *Help)) {
 	// Set the start time as soon as possible.
 	startTime := starttime.Get()
 
+	// Help flags, and help and flags commands, are generated automatically.
+	flagHelp := flag.Bool("help", false, "show information about runsc subcommands and exit")
+	flag.BoolVar(flagHelp, "h", false, "equivalent to the 'help' flag")
+	help := NewHelp(subcommands.DefaultCommander)
+	subcommands.Register(help, "")
+	subcommands.Register(subcommands.FlagsCommand(), "")
+
 	// Register all commands.
-	forEachCmd(subcommands.Register)
+	forEachCmd(func(cmd subcommands.Command, group string) {
+		subcommands.Register(&helpCommandWrapper{wrapped: cmd}, group)
+	}, help)
 
 	// Register with the main command line.
 	config.RegisterFlags(flag.CommandLine)
@@ -76,6 +85,12 @@ func Run(forEachCmd func(cb func(cmd subcommands.Command, group string))) {
 	// All subcommands must be registered before flag parsing.
 	flag.Parse()
 
+	// Are we showing help?
+	if *flagHelp {
+		help.printTopLevelHelp()
+		os.Exit(0)
+	}
+
 	// Are we showing the version?
 	if flag.Get(flag.Lookup(versionFlagName).Value).(bool) {
 		// The format here is the same as runc.

runsc/cmd/help.go renamed to runsc/cli/help.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package cmd
+package cli
 
 import (
 	"context"
@@ -64,22 +64,7 @@ func (h *Help) SetFlags(*flag.FlagSet) {}
 func (h *Help) Execute(ctx context.Context, f *flag.FlagSet, args ...any) subcommands.ExitStatus {
 	switch f.NArg() {
 	case 0:
-		fmt.Fprintf(h.cdr.Output, "Usage: %s <flags> <subcommand> <subcommand args>\n\n", h.cdr.Name())
-		fmt.Fprintf(h.cdr.Output, `runsc is the gVisor container runtime.
-
-Functionality is provided by subcommands. For help with a specific subcommand,
-use "%s %s <subcommand>".
-
-`, h.cdr.Name(), h.Name())
-		h.cdr.VisitGroups(func(g *subcommands.CommandGroup) {
-			h.cdr.ExplainGroup(h.cdr.Output, g)
-		})
-
-		fmt.Fprintf(h.cdr.Output, "Additional help topics (Use \"%s %s <topic>\" to see help on the topic):\n", h.cdr.Name(), h.Name())
-		for _, cmd := range h.commands {
-			fmt.Fprintf(h.cdr.Output, "\t%-15s  %s\n", cmd.Name(), cmd.Synopsis())
-		}
-		fmt.Fprintf(h.cdr.Output, "\nUse \"%s flags\" for a list of top-level flags\n", h.cdr.Name())
+		h.printTopLevelHelp()
 		return subcommands.ExitSuccess
 	default:
 		// Look for commands registered to the commander and print help explanation if found.
@@ -114,7 +99,64 @@ use "%s %s <subcommand>".
 	return subcommands.ExitUsageError
 }
 
+func (h *Help) printTopLevelHelp() {
+	fmt.Fprintf(h.cdr.Output, "Usage: %s <flags> <subcommand> <subcommand args>\n\n", h.cdr.Name())
+	fmt.Fprintf(h.cdr.Output, `runsc is the gVisor container runtime.
+
+Functionality is provided by subcommands. For help with a specific subcommand,
+use "%s %s <subcommand>".
+
+`, h.cdr.Name(), h.Name())
+	h.cdr.VisitGroups(func(g *subcommands.CommandGroup) {
+		h.cdr.ExplainGroup(h.cdr.Output, g)
+	})
+
+	fmt.Fprintf(h.cdr.Output, "Additional help topics (Use \"%s %s <topic>\" to see help on the topic):\n", h.cdr.Name(), h.Name())
+	for _, cmd := range h.commands {
+		fmt.Fprintf(h.cdr.Output, "\t%-15s  %s\n", cmd.Name(), cmd.Synopsis())
+	}
+	fmt.Fprintf(h.cdr.Output, "\nUse \"%s flags\" for a list of top-level flags\n", h.cdr.Name())
+}
+
 // Register registers a new help command.
 func (h *Help) Register(cmd subcommands.Command) {
 	h.commands = append(h.commands, cmd)
 }
+
+// helpCommandWrapper implements subcommands.Command by wrapping another
+// subcommands.Command and adding -h and -help flags.
+type helpCommandWrapper struct {
+	wrapped subcommands.Command
+	help    bool
+}
+
+// Name implements subcommands.Command.Name.
+func (h *helpCommandWrapper) Name() string {
+	return h.wrapped.Name()
+}
+
+// Synopsis implements subcommands.Command.Synopsis.
+func (h *helpCommandWrapper) Synopsis() string {
+	return h.wrapped.Synopsis()
+}
+
+// Usage implements subcommands.Command.Usage.
+func (h *helpCommandWrapper) Usage() string {
+	return h.wrapped.Usage()
+}
+
+// SetFlags implements subcommands.Command.SetFlags.
+func (h *helpCommandWrapper) SetFlags(f *flag.FlagSet) {
+	f.BoolVar(&h.help, "help", false, "show this message and exit")
+	f.BoolVar(&h.help, "h", false, "equivalent to the 'help' flag")
+	h.wrapped.SetFlags(f)
+}
+
+// Execute implements subcommands.Command.Execute.
+func (h *helpCommandWrapper) Execute(ctx context.Context, f *flag.FlagSet, args ...any) subcommands.ExitStatus {
+	if h.help {
+		f.Usage()
+		return subcommands.ExitSuccess
+	}
+	return h.wrapped.Execute(ctx, f, args...)
+}

runsc/cli/maincli/maincli.go

@@ -29,13 +29,13 @@ func Main() {
 }
 
 // forEachCmd invokes the passed callback for each command supported by runsc.
-func forEachCmd(cb func(cmd subcommands.Command, group string)) {
-	// Help and flags commands are generated automatically.
-	help := cmd.NewHelp(subcommands.DefaultCommander)
-	help.Register(new(cmd.Platforms))
-	help.Register(new(cmd.Syscalls))
-	cb(help, "")
-	cb(subcommands.FlagsCommand(), "")
+func forEachCmd(cb func(cmd subcommands.Command, group string), help *cli.Help) {
+	if help != nil {
+		// For historical reasons, these subcommands are invoked as `runsc help
+		// platforms` and `runsc help syscalls`.
+		help.Register(new(cmd.Platforms))
+		help.Register(new(cmd.Syscalls))
+	}
 
 	// Register OCI user-facing runsc commands.
 	cb(new(cmd.Checkpoint), "")

runsc/cli/maincli/maincli_test.go

@@ -66,7 +66,7 @@ func TestFlagSetIdempotent(t *testing.T) {
 		} else {
 			cmds[group] = []subcommands.Command{cmd}
 		}
-	})
+	}, nil)
 
 	for group, cmdList := range cmds {
 		t.Run(group, func(t *testing.T) {

runsc/cmd/BUILD

@@ -49,7 +49,6 @@ go_library(
         "exec.go",
         "fd_mapping.go",
         "gofer.go",
-        "help.go",
         "install.go",
         "kill.go",
         "list.go",

runsc/flag/flag.go

@@ -31,6 +31,7 @@ type Flag = flag.Flag
 // Aliases for flag functions.
 var (
 	Bool        = flag.Bool
+	BoolVar     = flag.BoolVar
 	CommandLine = flag.CommandLine
 	Duration    = flag.Duration
 	Float64     = flag.Float64