Merge pull request #6062 from jwhonce/wip/docs

[CI:DOC] Bring README.md up to date

cmd/podman/README.md

@@ -1,23 +1,16 @@
-# Adding a podman V2 commands
+# Podman CLI
 
-## Build podman V2
+The following is an example of how to add a new primary command (`manifest`) and a sub-command (`inspect`) to the Podman CLI.
+This is example code, the production code has additional error checking and the business logic provided.
 
-```shell script
+See items below for details on building, installing, contributing to Podman:
-$ cd $GOPATH/src/github.com/containers/libpod/cmd/podmanV2
+ - [Readme](README.md)
-```
+ - [Contributing](CONTRIBUTING.md)
-If you wish to include the libpod library in your program,
+ - [Podman Usage](transfer.md)
-```shell script
+ - [Trouble Shooting](troubleshooting.md)
-$ go build -tags 'ABISupport' .
+ - [Code Of Conduct](CODE-OF-CONDUCT.md)
-```
-The `--remote` flag may be used to connect to the Podman service using the API.
-Otherwise, direct calls will be made to the Libpod library.
-```shell script
-$ go build -tags '!ABISupport' .
-```
-The Libpod library is not linked into the executable.
-All calls are made via the API and `--remote=False` is an error condition.
 
-## Adding a new command `podman manifests`
+## Adding a new command `podman manifest`
 ```shell script
 $ mkdir -p $GOPATH/src/github.com/containers/libpod/cmd/podmanV2/manifests
 ```
@@ -27,6 +20,7 @@ package manifests
 
 import (
     "github.com/containers/libpod/cmd/podman/registry"
+    "github.com/containers/libpod/cmd/podman/validate"
     "github.com/containers/libpod/pkg/domain/entities"
     "github.com/spf13/cobra"
 )
@@ -36,11 +30,11 @@ var (
     manifestCmd = &cobra.Command{
         Use:               "manifest",
         Short:             "Manage manifests",
+        Args:              cobra.ExactArgs(1),
         Long:              "Manage manifests",
-        Example:           "podman manifests IMAGE",
+        Example:           "podman manifest IMAGE",
         TraverseChildren:  true,
-        PersistentPreRunE: preRunE,
+        RunE:              validate.SubCommandExists, // Report error if there is no sub command given
-        RunE:              registry.SubCommandExists, // Report error if there is no sub command given
     }
 )
 func init() {
@@ -51,15 +45,6 @@ func init() {
         // The definition for this command
         Command: manifestCmd,
     })
-    // Setup cobra templates, sub commands will inherit
-    manifestCmd.SetHelpTemplate(registry.HelpTemplate())
-    manifestCmd.SetUsageTemplate(registry.UsageTemplate())
-}
-
-// preRunE populates the image engine for sub commands
-func preRunE(cmd *cobra.Command, args []string) error {
-    _, err := registry.NewImageEngine(cmd, args)
-    return err
 }
 ```
 To "wire" in the `manifest` command, edit the file ```$GOPATH/src/github.com/containers/libpod/cmd/podmanV2/main.go``` to add:
@@ -87,7 +72,11 @@ var (
         Short:   "Display manifest from image",
         Long:    "Displays the low-level information on a manifest identified by image name or ID",
         RunE:    inspect,
-        Example: "podman manifest DEADBEEF",
+        Annotations: map[string]string{
+            // Add this annotation if this command cannot be run rootless
+            // registry.ParentNSRequired: "",
+        },
+        Example: "podman manifest inspect DEADBEEF",
     }
 )
 
@@ -98,6 +87,7 @@ func init() {
         Mode:    []entities.EngineMode{entities.ABIMode, entities.TunnelMode},
         // The definition for this command
         Command: inspectCmd,
+        // The parent command to proceed this command on the CLI
         Parent:  manifestCmd,
     })
 
@@ -106,8 +96,22 @@ func init() {
 
 // Business logic: cmd is inspectCmd, args is the positional arguments from os.Args
 func inspect(cmd *cobra.Command, args []string) error {
-    // Business logic using registry.ImageEngine
+    // Business logic using registry.ImageEngine()
     // Do not pull from libpod directly use the domain objects and types
     return nil
 }
 ```
+
+## Helper functions
+
+The complete set can be found in the `validate` package, here are some examples:
+
+ - `cobra.Command{ Args: validate.NoArgs }` used when the command does not accept errors
+ - `cobra.Command{ Args: validate.IdOrLatestArgs }` used to ensure either a list of ids given or the --latest flag
+ - `cobra.Command{ RunE: validate.SubCommandExists }` used to validate a subcommand given to a command
+ - `validate.ChoiceValue` used to create a `pflag.Value` that validate user input against a provided slice of values. For example:
+    ```go
+    flags := cobraCommand.Flags()
+    created := validate.ChoiceValue(&opts.Sort, "command", "created", "id", "image", "names", "runningfor", "size", "status")
+    flags.Var(created, "sort", "Sort output by: "+created.Choices())
+    ```

cmd/podman/containers/ps.go

@@ -67,8 +67,8 @@ func listFlagSet(flags *pflag.FlagSet) {
 	flags.BoolVar(&listOpts.Sync, "sync", false, "Sync container state with OCI runtime")
 	flags.UintVarP(&listOpts.Watch, "watch", "w", 0, "Watch the ps output on an interval in seconds")
 
-	created := validate.ChoiceValue(&listOpts.Sort, "command", "created", "id", "image", "names", "runningfor", "size", "status")
+	sort := validate.ChoiceValue(&listOpts.Sort, "command", "created", "id", "image", "names", "runningfor", "size", "status")
-	flags.Var(created, "sort", "Sort output by: "+created.Choices())
+	flags.Var(sort, "sort", "Sort output by: "+sort.Choices())
 
 	if registry.IsRemote() {
 		_ = flags.MarkHidden("latest")

pkg/domain/infra/abi/containers.go

@@ -523,7 +523,8 @@ func (ic *ContainerEngine) ContainerAttach(ctx context.Context, nameOrId string,
 	}
 
 	// If the container is in a pod, also set to recursively start dependencies
-	if err := terminal.StartAttachCtr(ctx, ctr, options.Stdout, options.Stderr, options.Stdin, options.DetachKeys, options.SigProxy, false, ctr.PodID() != ""); err != nil && errors.Cause(err) != define.ErrDetach {
+	err = terminal.StartAttachCtr(ctx, ctr, options.Stdout, options.Stderr, options.Stdin, options.DetachKeys, options.SigProxy, false, ctr.PodID() != "")
+	if err != nil && errors.Cause(err) != define.ErrDetach {
 		return errors.Wrapf(err, "error attaching to container %s", ctr.ID())
 	}
 	return nil