README.md: how to install image-tools

Signed-off-by: Sn0rt <wanggh-fnst@cn.fujitsu.com>

Makefile

@@ -8,13 +8,18 @@ TOOLS := \
 	oci-create-runtime-bundle \
 	oci-image-validate \
 	oci-unpack
+MAN := $(TOOLS:%=%.1)
 
 default: help
 
 help:
 	@echo "Usage: make <target>"
 	@echo
+	@echo " * 'all' - Build the oci tools and manual pages"
+	@echo " * 'install' - Install binaries and manual pages"
+	@echo " * 'uninstall' - Remove the oci tools and manual pages"
 	@echo " * 'tools' - Build the oci image tools binaries"
+	@echo " * 'man' - Build the oci image manual pages"
 	@echo " * 'check-license' - Check license headers in source files"
 	@echo " * 'lint' - Execute the source code linter"
 	@echo " * 'test' - Execute the unit tests"
@@ -26,9 +31,24 @@ check-license:
 
 tools: $(TOOLS)
 
+man: $(MAN)
+
+all: $(TOOLS) $(MAN)
+
 $(TOOLS): oci-%:
 	go build -ldflags "-X main.gitCommit=${COMMIT}" ./cmd/$@
 
+.SECONDEXPANSION:
+$(MAN): %.1: cmd/$$*/$$*.1.md
+	go-md2man -in "$<" -out "$@"
+
+install: $(TOOLS) $(MAN)
+	install -m 755 $(TOOLS) /usr/local/bin/
+	install -m 644 $(MAN) /usr/local/share/man/man1
+
+uninstall: clean
+	rm -f $(MAN:%=/usr/local/share/man/man1/%) $(TOOLS:%=/usr/local/bin/%)
+
 lint:
 	@echo "checking lint"
 	@./.tool/lint
@@ -57,7 +77,7 @@ endif
 
 .PHONY: install.tools
 
-install.tools: .install.gitvalidation .install.glide .install.glide-vc .install.gometalinter
+install.tools: .install.gitvalidation .install.glide .install.glide-vc .install.gometalinter .install.go-md2man
 
 .install.gitvalidation:
 	go get github.com/vbatts/git-validation
@@ -72,12 +92,18 @@ install.tools: .install.gitvalidation .install.glide .install.glide-vc .install.
 	go get github.com/alecthomas/gometalinter
 	gometalinter --install --update
 
+.install.go-md2man:
+	go get github.com/cpuguy83/go-md2man
+
 clean:
-	rm -rf *~ $(OUTPUT_DIRNAME) $(TOOLS)
+	rm -rf *~ $(OUTPUT_DIRNAME) $(TOOLS) $(MAN)
 
 .PHONY: \
+	all \
 	tools \
-	$(TOOLS) \
+	man \
+	install \
+	uninstall \
 	check-license \
 	clean \
 	lint \

README.md

@@ -2,6 +2,71 @@
 
 `image-tools` is a collection of tools for working with the [OCI image format specification](https://github.com/opencontainers/image-spec).
 
+## Install
+
+It is recommended that use `go get` to download a single command tools.
+
+```
+$ go get -d github.com/opencontainers/image-tools/cmd/oci-unpack
+$ cd $GOPATH/src/github.com/opencontainers/image-tools/
+$ make all
+$ sudo make install
+```
+
+## Uninstall
+
+```
+$ sudo make uninstall
+```
+
+## Example
+
+### Obtaining an image
+
+The following examples assume you have a [image-layout](https://github.com/opencontainers/image-spec/blob/v1.0.0-rc2/image-layout.md) tar archive at `busybox-oci`.
+One way to acquire that image is with [skopeo](https://github.com/projectatomic/skopeo#installing):
+
+```
+$ skopeo copy docker://busybox oci:busybox-oci
+```
+
+### oci-create-runtime-bundle
+
+More information about `oci-create-runtime-bundle` can be found in its [man page](./cmd/oci-create-runtime-bundle/oci-create-runtime-bundle.1.md)
+
+```
+$ mkdir busybox-bundle
+$ oci-create-runtime-bundle --ref latest busybox-oci busybox-bundle
+$ cd busybox-bundle && sudo runc run busybox
+```
+
+### oci-image-validate
+
+More information about `oci-image-validate` can be found in its [man page](./cmd/oci-image-validate/oci-image-validate.1.md)
+
+```
+$ oci-image-validate --type imageLayout --ref latest busybox-oci
+busybox-oci: OK
+```
+
+### oci-unpack
+
+More information about `oci-unpack` can be found in its [man page](./cmd/oci-unpack/oci-unpack.1.md)
+
+```
+$ mkdir busybox-bundle
+$ oci-unpack --ref latest busybox-oci busybox-bundle
+$ tree busybox-bundle
+busybox-bundle
+├── bin
+│   ├── [
+│   ├── [[
+│   ├── acpid
+│   ├── addgroup
+│   ├── add-shell
+[...]
+```
+
 # Contributing
 
 Development happens on GitHub. Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).

cmd/oci-unpack/oci-unpack.1.md

@@ -29,7 +29,7 @@ oci-unpack \- Unpack an image or image source layout
 $ skopeo copy docker://busybox oci:busybox-oci
 $ mkdir busybox-bundle
 $ oci-unpack --ref latest busybox-oci busybox-bundle
-tree busybox-bundle
+$ tree busybox-bundle
 busybox-bundle
 ├── bin
 │   ├── [