Merge pull request #4088 from baude/varlinkbuildoutput

Document the required varlink build args

2 files changed, 72 insertions, 2 deletions

diff --git a/API.md b/API.md
index f0e5cf18f..3d2a6b01f 100755
--- a/API.md
+++ b/API.md
@@ -304,8 +304,43 @@ method AttachControl(name: [string](https://godoc.org/builtin#string)) </div>
 
 method BuildImage(build: [BuildInfo](#BuildInfo)) [MoreResponse](#MoreResponse)</div>
 BuildImage takes a [BuildInfo](#BuildInfo) structure and builds an image.  At a minimum, you must provide the
-'dockerfile' and 'tags' options in the BuildInfo structure. It will return a [MoreResponse](#MoreResponse) structure
+contextDir tarball path, the 'dockerfiles' path, and 'output' option in the BuildInfo structure.  The 'output'
+options is the name of the of the resulting build. It will return a [MoreResponse](#MoreResponse) structure
 that contains the build logs and resulting image ID.
+#### Example
+~~~
+$ sudo varlink call -m unix:///run/podman/io.podman/io.podman.BuildImage '{"build":{"contextDir":"/tmp/t/context.tar","dockerfiles":["Dockerfile"], "output":"foobar"}}'
+{
+ "image": {
+   "id": "",
+   "logs": [
+     "STEP 1: FROM alpine\n"
+   ]
+ }
+}
+{
+ "image": {
+   "id": "",
+   "logs": [
+     "STEP 2: COMMIT foobar\n"
+   ]
+ }
+}
+{
+ "image": {
+   "id": "",
+   "logs": [
+     "b7b28af77ffec6054d13378df4fdf02725830086c7444d9c278af25312aa39b9\n"
+   ]
+ }
+}
+{
+ "image": {
+   "id": "b7b28af77ffec6054d13378df4fdf02725830086c7444d9c278af25312aa39b9",
+   "logs": []
+ }
+}
+~~~
 ### <a name="BuildImageHierarchyMap"></a>func BuildImageHierarchyMap
 <div style="background-color: #E8E8E8; padding: 15px; margin: 10px; border-radius: 10px;">
 
diff --git a/cmd/podman/varlink/io.podman.varlink b/cmd/podman/varlink/io.podman.varlink
index 4692525e3..7239f5d2e 100644
--- a/cmd/podman/varlink/io.podman.varlink
+++ b/cmd/podman/varlink/io.podman.varlink
@@ -765,8 +765,43 @@ method ListImages() -> (images: []Image)
 method GetImage(id: string) -> (image: Image)
 
 # BuildImage takes a [BuildInfo](#BuildInfo) structure and builds an image.  At a minimum, you must provide the
-# 'dockerfile' and 'tags' options in the BuildInfo structure. It will return a [MoreResponse](#MoreResponse) structure
+# contextDir tarball path, the 'dockerfiles' path, and 'output' option in the BuildInfo structure.  The 'output'
+# options is the name of the of the resulting build. It will return a [MoreResponse](#MoreResponse) structure
 # that contains the build logs and resulting image ID.
+# #### Example
+# ~~~
+# $ sudo varlink call -m unix:///run/podman/io.podman/io.podman.BuildImage '{"build":{"contextDir":"/tmp/t/context.tar","dockerfiles":["Dockerfile"], "output":"foobar"}}'
+# {
+#  "image": {
+#    "id": "",
+#    "logs": [
+#      "STEP 1: FROM alpine\n"
+#    ]
+#  }
+# }
+# {
+#  "image": {
+#    "id": "",
+#    "logs": [
+#      "STEP 2: COMMIT foobar\n"
+#    ]
+#  }
+# }
+# {
+#  "image": {
+#    "id": "",
+#    "logs": [
+#      "b7b28af77ffec6054d13378df4fdf02725830086c7444d9c278af25312aa39b9\n"
+#    ]
+#  }
+# }
+# {
+#  "image": {
+#    "id": "b7b28af77ffec6054d13378df4fdf02725830086c7444d9c278af25312aa39b9",
+#    "logs": []
+#  }
+# }
+# ~~~
 method BuildImage(build: BuildInfo) -> (image: MoreResponse)
 
 # This function is not implemented yet.