From 150eb5bf1816277c0671006faa505d0dc18a8a67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 17:12:25 +0200 Subject: [PATCH 1/8] Add Fedora instructions for installing go-md2man It would be nice to have macOS instructions as well. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fb95c694ec..3e5580dffc 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,8 @@ Building - To build the manual you will need go-md2man. ```sh -$ sudo apt-get install go-md2man +Debian$ sudo apt-get install go-md2man +Fedora$ sudo dnf install go-md2man ``` To build the `skopeo` binary you need at least Go 1.5 because it uses the latest `GO15VENDOREXPERIMENT` flag. Also, make sure to clone the repository in your `GOPATH` - otherwise compilation fails. ```sh From 7db0aab3301b3b04a0f1ab7a97b972ab336f7514 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 17:13:44 +0200 Subject: [PATCH 2/8] Move documentation build instructions to the end, with a separate header MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We want to start with the Go 1.5 dependency and build/checkout instructions. Also create a separate subsection, to match the future “Building in/without a container” subsections --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3e5580dffc..fc38785501 100644 --- a/README.md +++ b/README.md @@ -103,11 +103,6 @@ you'll get an error. You can fix this by either logging in (via `docker login`) Building - -To build the manual you will need go-md2man. -```sh -Debian$ sudo apt-get install go-md2man -Fedora$ sudo dnf install go-md2man -``` To build the `skopeo` binary you need at least Go 1.5 because it uses the latest `GO15VENDOREXPERIMENT` flag. Also, make sure to clone the repository in your `GOPATH` - otherwise compilation fails. ```sh $ git clone https://github.com/projectatomic/skopeo $GOPATH/src/github.com/projectatomic/skopeo @@ -124,6 +119,18 @@ You may need to install additional development packages: `gpgme-devel` and `liba ```sh $ sudo dnf install gpgme-devel libassuan-devel btrfs-progs-devel device-mapper-devel ``` + +### Building documentation +To build the manual you will need go-md2man. +```sh +Debian$ sudo apt-get install go-md2man +Fedora$ sudo dnf install go-md2man +``` +Then +```sh +$ make docs +``` + Installing - If you built from source: From a2499d3451aed83123a304646fe2fea988f57b03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 16:38:38 +0200 Subject: [PATCH 3/8] =?UTF-8?q?Create=20=E2=80=9CBuilding=20{without=20a?= =?UTF-8?q?=20container,in=20a=20container}=E2=80=9D=20subsections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit To make it clearer that the two are alternatives. Document that a docker command is needed for the in-container build. Also move the “checkout in $GOPATH” warning into the “without a container” section, where it belongs. --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc38785501..8d5db6379c 100644 --- a/README.md +++ b/README.md @@ -103,10 +103,14 @@ you'll get an error. You can fix this by either logging in (via `docker login`) Building - -To build the `skopeo` binary you need at least Go 1.5 because it uses the latest `GO15VENDOREXPERIMENT` flag. Also, make sure to clone the repository in your `GOPATH` - otherwise compilation fails. +To build the `skopeo` binary you need at least Go 1.5 because it uses the latest `GO15VENDOREXPERIMENT` flag. + +### Building without a container +Make sure to clone the repository in your `GOPATH` - otherwise compilation fails. + ```sh $ git clone https://github.com/projectatomic/skopeo $GOPATH/src/github.com/projectatomic/skopeo -$ cd $GOPATH/src/github.com/projectatomic/skopeo && make all +$ cd $GOPATH/src/github.com/projectatomic/skopeo && make binary-local ``` To build localy on OSX: @@ -120,6 +124,12 @@ You may need to install additional development packages: `gpgme-devel` and `liba $ sudo dnf install gpgme-devel libassuan-devel btrfs-progs-devel device-mapper-devel ``` +### Building in a container +If your system has a `docker` command and can run Linux containers, +```sh +$ make binary # Or (make all) to also build documentation, see below. +``` + ### Building documentation To build the manual you will need go-md2man. ```sh From 3d0d2ea6bbbb272f5163c909ddb60b23ec19c721 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Mon, 29 May 2017 18:50:35 +0200 Subject: [PATCH 4/8] Document that there is a choice in using containers, and what the trade-off is --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d5db6379c..40fcf93f3c 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,14 @@ Building - To build the `skopeo` binary you need at least Go 1.5 because it uses the latest `GO15VENDOREXPERIMENT` flag. +There are two ways to build skopeo: in a container, or locally without a container. Choose the one which better matches your needs and environment. + ### Building without a container +Building without a container requires a bit more manual work and setup in your environment, but it is more flexible: +- It should work in more environments (e.g. for native macOS builds) +- It does not require root privileges (after dependencies are installed) +- It is faster, therefore more convenient for developing `skopeo`. + Make sure to clone the repository in your `GOPATH` - otherwise compilation fails. ```sh @@ -125,7 +132,10 @@ $ sudo dnf install gpgme-devel libassuan-devel btrfs-progs-devel device-mapper-d ``` ### Building in a container -If your system has a `docker` command and can run Linux containers, +Building in a container is simpler, but more restrictive: +- It requires the `docker` command and the ability to run Linux containers +- The created executable is a Linux executable, and depends on dynamic libraries which may only be available only in a container of a similar Linux distribution. + ```sh $ make binary # Or (make all) to also build documentation, see below. ``` From 49f10736d19031dc300eb14aed0e27faa825f882 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 16:41:32 +0200 Subject: [PATCH 5/8] =?UTF-8?q?Restructure=20the=20=E2=80=9CBuilding=20wit?= =?UTF-8?q?hout=20a=20container=E2=80=9D=20version?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consolidate the Fedora and macOS instructions to prevent duplication, and to suggest using $GOPATH for both. Start with installing dependencies. --- README.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 40fcf93f3c..4f43a26c8b 100644 --- a/README.md +++ b/README.md @@ -113,22 +113,17 @@ Building without a container requires a bit more manual work and setup in your e - It does not require root privileges (after dependencies are installed) - It is faster, therefore more convenient for developing `skopeo`. -Make sure to clone the repository in your `GOPATH` - otherwise compilation fails. - +Install the necessary dependencies: ```sh -$ git clone https://github.com/projectatomic/skopeo $GOPATH/src/github.com/projectatomic/skopeo -$ cd $GOPATH/src/github.com/projectatomic/skopeo && make binary-local +Fedora$ sudo dnf install gpgme-devel libassuan-devel btrfs-progs-devel device-mapper-devel +macOS$ brew install gpgme ``` -To build localy on OSX: -```sh -$ brew install gpgme -$ make binary-local -``` +Make sure to clone this repository in your `GOPATH` - otherwise compilation fails. -You may need to install additional development packages: `gpgme-devel` and `libassuan-devel` ```sh -$ sudo dnf install gpgme-devel libassuan-devel btrfs-progs-devel device-mapper-devel +$ git clone https://github.com/projectatomic/skopeo $GOPATH/src/github.com/projectatomic/skopeo +$ cd $GOPATH/src/github.com/projectatomic/skopeo && make binary-local ``` ### Building in a container From 0debda0bbbcca2de7fb1d705755d2ef0a3904a14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 16:47:10 +0200 Subject: [PATCH 6/8] Start all command examples with $ That has mostly been the case, with one outlier. Fix it. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4f43a26c8b..9e647c7ab6 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ $ sudo make install ``` `skopeo` is also available from Fedora 23 (and later): ```sh -sudo dnf install skopeo +$ sudo dnf install skopeo ``` TODO - From fc88117065fc88cdc0d673dd982a5255a9be5156 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 12 May 2017 16:48:18 +0200 Subject: [PATCH 7/8] Drop finished work from TODO - We now have the docker-archive: transport - Integration tests with built registries also exist --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 9e647c7ab6..4373313e50 100644 --- a/README.md +++ b/README.md @@ -160,9 +160,7 @@ TODO - - list all images on registry? - registry v2 search? -- support output to docker load tar(s) - show repo tags via flag or when reference isn't tagged or digested -- add tests (integration with deployed registries in container - Docker-like) - support rkt/appc image spec NOT TODO From 9d12d72fb7065d561c4f2a2a2bb269d01a61c1d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Fri, 2 Jun 2017 23:23:46 +0200 Subject: [PATCH 8/8] Improve documentation on what to do with containers/image failures in test-skopeo --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4373313e50..7bab473073 100644 --- a/README.md +++ b/README.md @@ -184,10 +184,20 @@ In order to update an existing dependency: - update the relevant dependency line in `vendor.conf` - run `vndr github.com/pkg/errors` -In order to test out new PRs from [containers/image](https://github.com/containers/image) to not break `skopeo`: +When new PRs for [containers/image](https://github.com/containers/image) break `skopeo` (i.e. `containers/image` tests fail in `make test-skopeo`): +- create out a new branch in your `skopeo` checkout and switch to it - update `vendor.conf`. Find out the `containers/image` dependency; update it to vendor from your own branch and your own repository fork (e.g. `github.com/containers/image my-branch https://github.com/runcom/image`) - run `vndr github.com/containers/image` +- make any other necessary changes in the skopeo repo (e.g. add other dependencies now requied by `containers/image`, or update skopeo for changed `containers/image` API) +- optionally add new integration tests to the skopeo repo +- submit the resulting branch as a skopeo PR, marked “DO NOT MERGE” +- iterate until tests pass and the PR is reviewed +- then the original `containers/image` PR can be merged, disregarding its `make test-skopeo` failure +- as soon as possible after that, in the skopeo PR, restore the `containers/image` line in `vendor.conf` to use `containers/image:master` +- run `vndr github.com/containers/image` +- update the skopeo PR with the result, drop the “DO NOT MERGE” marking +- after tests complete succcesfully again, merge the skopeo PR License -