summaryrefslogtreecommitdiff
path: root/cmd/podman/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'cmd/podman/README.md')
-rw-r--r--cmd/podman/README.md66
1 files changed, 35 insertions, 31 deletions
diff --git a/cmd/podman/README.md b/cmd/podman/README.md
index c1b8f48a7..da92d0216 100644
--- a/cmd/podman/README.md
+++ b/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
-$ cd $GOPATH/src/github.com/containers/libpod/cmd/podmanV2
-```
-If you wish to include the libpod library in your program,
-```shell script
-$ go build -tags 'ABISupport' .
-```
-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.
+See items below for details on building, installing, contributing to Podman:
+ - [Readme](README.md)
+ - [Contributing](CONTRIBUTING.md)
+ - [Podman Usage](transfer.md)
+ - [Trouble Shooting](troubleshooting.md)
+ - [Code Of Conduct](CODE-OF-CONDUCT.md)
-## 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: registry.SubCommandExists, // Report error if there is no sub command given
+ RunE: validate.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())
+ ```