From b22a39b6b15bd082f7d4c83d306e43b2e6ca856b Mon Sep 17 00:00:00 2001 From: Jhon Honce Date: Fri, 1 May 2020 08:36:48 -0700 Subject: [CI:DOCS] Bring README.md up to date * Add notes on helper functions * Update example Signed-off-by: Jhon Honce --- cmd/podman/README.md | 66 ++++++++++++++++++++++++--------------------- cmd/podman/containers/ps.go | 4 +-- 2 files changed, 37 insertions(+), 33 deletions(-) (limited to 'cmd') 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()) + ``` diff --git a/cmd/podman/containers/ps.go b/cmd/podman/containers/ps.go index c5696a158..e9146bda7 100644 --- a/cmd/podman/containers/ps.go +++ b/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") - flags.Var(created, "sort", "Sort output by: "+created.Choices()) + sort := validate.ChoiceValue(&listOpts.Sort, "command", "created", "id", "image", "names", "runningfor", "size", "status") + flags.Var(sort, "sort", "Sort output by: "+sort.Choices()) if registry.IsRemote() { _ = flags.MarkHidden("latest") -- cgit v1.2.3-54-g00ecf