diff --git a/Makefile b/Makefile index f0f35f7..14083e3 100644 --- a/Makefile +++ b/Makefile @@ -8,13 +8,18 @@ TOOLS := \ oci-create-runtime-bundle \ oci-image-validate \ oci-unpack +MAN := $(TOOLS:%=%.1) default: help help: @echo "Usage: make " @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 \ diff --git a/README.md b/README.md index 5698daf..8d7528e 100644 --- a/README.md +++ b/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). diff --git a/cmd/oci-unpack/oci-unpack.1.md b/cmd/oci-unpack/oci-unpack.1.md index 95219ee..fcbbd92 100644 --- a/cmd/oci-unpack/oci-unpack.1.md +++ b/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 │   ├── [