Update podman build to match buildah bud functionality

Add --label, --annotations, --idfile, --squash

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

Closes: #824
Approved by: TomSweeneyRedHat

1 files changed, 94 insertions, 21 deletions

diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index 430cbe51d..e5406b728 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -3,7 +3,7 @@
 # podman-build "7" "December 2017" "podman"
 
 ## NAME
-podman-build - Build a container image using a Dockerfile.
+podman\-build - Build a container image using a Dockerfile.
 
 ## SYNOPSIS
 **podman** **build** [*options* [...]] **context**
@@ -27,9 +27,15 @@ Add a custom host-to-IP mapping (host:ip)
 
 Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times.
 
+**--annotation** *annotation*
+
+Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple times.
+
+Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats.
+
 **--authfile** *path*
 
-Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
+Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
 If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
 
 **--build-arg** *arg=value*
@@ -39,15 +45,25 @@ instructions read from the Dockerfiles in the same way that environment
 variables are, but which will not be added to environment variable list in the
 resulting image's configuration.
 
+**--cache-from**
+
+Images to utilize as potential cache sources. Podman does not currently support caching so this is a NOOP.
+
 **--cert-dir** *path*
 
-Use certificates at *path* (*.crt, *.cert, *.key) to connect to the registry.
+Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
 Default certificates directory is _/etc/containers/certs.d_.
 
 **--cgroup-parent**=""
 
 Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist.
 
+**--compress**
+
+This option is added to be aligned with other containers CLIs.
+Podman doesn't communicate with a daemon or a remote server.
+Thus, compressing the data before sending it is irrelevant to Podman.
+
 **--cpu-period**=*0*
 
 Limit the CPU CFS (Completely Fair Scheduler) period
@@ -62,7 +78,7 @@ Limit the container's CPU usage. By default, containers run with the full
 CPU resource. This flag tell the kernel to restrict the container's CPU usage
 to the quota you specify.
 
-**--cpu-shares**=*0*
+**--cpu-shares, -c**=*0*
 
 CPU shares (relative weight)
 
@@ -117,7 +133,7 @@ The [username[:password]] to use to authenticate with the registry if required.
 If one or both values are not supplied, a command line prompt will appear and the
 value can be entered.  The password is entered without echo.
 
-**-f, --file** *Dockerfile*
+**--file, -f** *Dockerfile*
 
 Specifies a Dockerfile which contains instructions for building the image,
 either a local file or an **http** or **https** URL.  If more than one
@@ -128,6 +144,10 @@ If a build context is not specified, and at least one Dockerfile is a
 local file, the directory in which it resides will be used as the build
 context.
 
+**--force-rm**
+
+Always remove intermediate containers after a build. Podman does not currently support caching so this is a NOOP.
+
 **--format**
 
 Control the format for the built image's manifest and configuration data.
@@ -144,8 +164,11 @@ Podman is not currently supported on Windows, and does not have a daemon.
 If you want to override the container isolation you can choose a different
 OCI Runtime, using the --runtime flag.
 
-**-m**, **--memory**=""
+**--label** *label*
+
+Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times.
 
+**--memory, -m**=""
 Memory limit (format: <number>[<unit>], where unit = b, k, m or g)
 
 Allows you to constrain the memory available to a container. If the host
@@ -164,16 +187,31 @@ the value of --memory.
 The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
 `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a
 unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
+
+**--no-cache**
+
+Do not use caching for the container build. Podman does not currently support caching so this is a NOOP.
+
+**--pull**
+
+Pull the image if it is not present.  If this flag is disabled (with
+*--pull=false*) and the image is not present, the image will not be pulled.
+Defaults to *true*.
+
 **--pull-always**
 
 Pull the image even if a version of the image is already present.
 
-**-q, --quiet**
+**--quiet, -q**
 
 Suppress output messages which indicate which instruction is being processed,
 and of progress when pulling images from a registry, and when writing the
 output image.
 
+**--rm**
+
+Remove intermediate containers after a successful build. Podman does not currently support caching so this is a NOOP.
+
 **--runtime** *path*
 
 The *path* to an alternate OCI-compatible runtime, which will be used to run
@@ -181,7 +219,11 @@ commands specified by the **RUN** instruction.
 
 **--runtime-flag** *flag*
 
-Adds global flags for the container runtime.
+Adds global flags for the container rutime. To list the supported flags, please
+consult the manpages of the selected container runtime (`runc` is the default
+runtime, the manpage to consult is `runc(8)`).
+Note: Do not pass the leading `--` to the flag. To pass the runc flag `--log-format json`
+to podman build, the option given would be `--runtime-flag log-format=json`.
 
 **--security-opt**=[]
 
@@ -205,26 +247,49 @@ Security Options
 Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`.
 Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes).
 If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`.
-**--signature-policy** *signature-policy-file*
 
-Path name of a signature policy file to use.  It is not recommended that this
+**--signature-policy** *signaturepolicy*
+
+Pathname of a signature policy file to use.  It is not recommended that this
 option be used, as the default behavior of using the system-wide default policy
 (frequently */etc/containers/policy.json*) is most often preferred.
 
-**-t, --tag** *imageName*
+**--squash**
+
+Squash all of the new image's layers (including those inherited from a base image) into a single new layer.
+
+**--tag, -t** *imageName*
 
 Specifies the name which will be assigned to the resulting image if the build
 process completes successfully.
+If _imageName_ does not include a registry name, the registry name *localhost* will be prepended to the image name.
 
 **--tls-verify** *bool-value*
 
-Require HTTPS and verify certificates when talking to container registries (defaults to true)
-
-**--ulimit**=[]
-
-Ulimit options
-
-**-v**|**--volume**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
+Require HTTPS and verify certificates when talking to container registries (defaults to true).
+
+**--ulimit**=*type*:*soft-limit*[:*hard-limit*]
+
+Specifies resource limits to apply to processes launched when processing `RUN` instructions.
+This option can be specified multiple times.  Recognized resource types
+include:
+  "core": maximimum core dump size (ulimit -c)
+  "cpu": maximum CPU time (ulimit -t)
+  "data": maximum size of a process's data segment (ulimit -d)
+  "fsize": maximum size of new files (ulimit -f)
+  "locks": maximum number of file locks (ulimit -x)
+  "memlock": maximum amount of locked memory (ulimit -l)
+  "msgqueue": maximum amount of data in message queues (ulimit -q)
+  "nice": niceness adjustment (nice -n, ulimit -e)
+  "nofile": maximum number of open files (ulimit -n)
+  "nproc": maximum number of processes (ulimit -u)
+  "rss": maximum size of a process's (ulimit -m)
+  "rtprio": maximum real-time scheduling priority (ulimit -r)
+  "rttime": maximum amount of real-time execution between blocking syscalls
+  "sigpending": maximum number of pending signals (ulimit -i)
+  "stack": maximum stack size (ulimit -s)
+
+**--volume, -v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
 
    Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman
    bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the podman
@@ -236,12 +301,14 @@ Ulimit options
 
 The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR`
 must be an absolute path as well. Podman bind-mounts the `HOST-DIR` to the
-path you specify. For example, if you supply the `/foo` value, podman creates a bind-mount.
+path you specify. For example, if you supply `/foo` as the host path,
+Podman copies the contents of `/foo` to the container filesystem on the host
+and bind mounts that into the container.
 
 You can specify multiple  **-v** options to mount one or more mounts to a
 container.
 
-You can add `:ro` or `:rw` suffix to a volume to mount it read-only or
+You can add the `:ro` or `:rw` suffix to a volume to mount it read-only or
 read-write mode, respectively. By default, the volumes are mounted read-write.
 See examples.
 
@@ -339,7 +406,13 @@ podman build --volume /home/test:/myvol:ro,Z -t imageName .
 
  `podman build -f dev/Dockerfile https://10.10.10.1/podman/context.tar.gz`
 
-  Note: The supported compression formats are `xz`, `bzip2`, `gzip` and `identity` (no compression).
+  Note: supported compression formats are 'xz', 'bzip2', 'gzip' and 'identity' (no compression).
+
+## Files
+
+**registries.conf** (`/etc/containers/registries.conf`)
+
+registries.conf is the configuration file which specifies which registries should be consulted when completing image names which do not include a registry or domain portion.
 
 ## SEE ALSO
 podman(1), buildah(1)