From c48a40d47961d36094b234efe5c6ef36865f7a87 Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Fri, 25 May 2018 13:36:12 +1000
Subject: [PATCH] Move several packages to bindep.txt

Move several parts of the "install_test_deps.sh" script into the more
standard bindep.txt.  This list is intentionally restricted as a first
step.

Developer documentation is updated to use bindep and clarified
slightly.

Change-Id: I7520902dc324d920a0c7c44a2d35fe49f9b05614
---
 bindep.txt                             | 29 ++++++++++++++
 doc/source/developer/invocation.rst    | 55 +++++++++++++++++---------
 doc/source/user_guide/installation.rst | 12 +-----
 tests/install_test_deps.sh             | 39 +++---------------
 tox.ini                                |  4 ++
 5 files changed, 77 insertions(+), 62 deletions(-)

diff --git a/bindep.txt b/bindep.txt
index 257bb5e1..0b7e284b 100644
--- a/bindep.txt
+++ b/bindep.txt
@@ -1,6 +1,35 @@
 # This is a cross-platform list tracking distribution packages needed by tests;
 # see https://docs.openstack.org/infra/bindep/ for additional information.
+
+# common
+bzip2
+util-linux
+dosfstools
+gdisk
+kpartx
+
 squashfs-tools [!platform:suse]
 squashfs [platform:suse]
 zypper [!platform:redhat !platform:ubuntu-trusty !platform:ubuntu-bionic]
 gnupg2 [!platform:redhat !platform:ubuntu-trusty !platform:suse]
+
+# ubuntu
+apt-transport-https [platform:dpkg]
+inetutils-ping [platform:dpkg]
+lsb-release [platform:dpkg]
+python-lzma [platform:dpkg]
+qemu-utils [platform:dpkg]
+rpm [platform:dpkg]
+uuid-runtime [platform:dpkg]
+yum-utils [platform:dpkg]
+debootstrap [platform:dpkg]
+
+# centos/fedora
+qemu-img [platform:redhat]
+policycoreutils-python [platform:redhat]
+
+# suse
+python-pyliblzma [platform:suse]
+yum-utils [platform:suse]
+qemu-tools [platform:suse]
+debootstrap [platform:suse]
diff --git a/doc/source/developer/invocation.rst b/doc/source/developer/invocation.rst
index ea3ad945..b5b58f76 100644
--- a/doc/source/developer/invocation.rst
+++ b/doc/source/developer/invocation.rst
@@ -1,37 +1,50 @@
+.. _dev_install:
+
 Developer Installation
 ======================
 
 Note that for non-development use you can use distribution packages or
-install the latest release via ``pip`` in a ``virtualenv``.
+install the latest release via ``pip`` (usually in a separate
+``virtualenv`` environment).
 
 For development purposes, you can use ``pip -e`` to install the latest
-git tree checkout into a local development/testing ``virtualenv``, or
-use ``tox -e venv -- disk-image-create`` to run within a ``tox``
-created environment.
+git tree checkout into a local development/testing ``virtualenv``.
 
-For example, to create a ``virtualenv`` and install
+However, the recommended way is to use provided ``tox`` environments;
+e.g.
 
-::
+.. code-block:: shell-session
 
-   $ mkdir dib
-   $ cd dib
-   $ virtualenv env
-   $ source env/bin/activate
    $ git clone https://git.openstack.org/openstack/diskimage-builder
    $ cd diskimage-builder
-   $ pip install -e .
+
+   $ tox -e bindep
+   $ sudo apt-get install <any-missing-packages-from-bindep>
+
+   $ tox -e venv -- disk-image-create ...
+
+This will ensure you run with the right requirements.
 
 Invocation
-==========
+----------
 
-The scripts can generally just be run. Options can be set on the
-command line or by exporting variables to override those present in
-lib/img-defaults. -h to get help.
+The ``image-create`` scripts should be run from the ``$PATH``; this
+should will be automatically set if using a ``virtualenv`` or ``tox``.
+
+A range of options can be set on the command-line.  Try ``-h`` for
+help.
+
+Other options can be set by exporting variables; some variables for
+export are listed in ``lib/img-defaults``.  See specific element
+instructions for other variables that may be obeyed.
 
 The image building scripts expect to be able to invoke commands with
-sudo, so if you want them to run non-interactively, you should either
-run them as root, with sudo -E, or allow your build user to run any
-sudo command without password.
+``sudo``.  Thus if you want them to run non-interactively, you should
+either run them as root, with ``sudo -E``, or allow your build user to
+run any ``sudo`` command without password.
+
+Element priority
+----------------
 
 The variable ``ELEMENTS_PATH`` is a colon (:) separated path list to
 search for elements.  The included ``elements`` tree is used when no
@@ -41,6 +54,9 @@ is supplied.  Earlier elements will override later elements, i.e. with
 from ``foo/my-element`` over ``bar/my-element``, or any in-built
 element of the same name.
 
+Output
+------
+
 By default, the image building scripts will not overwrite existing
 disk images, allowing you to compare the newly built image with the
 existing one. To change that behaviour, set the variable
@@ -48,6 +64,9 @@ existing one. To change that behaviour, set the variable
 zero then any existing image will be moved before the new image is
 written to the destination.
 
+Size reports
+------------
+
 Setting the variable ``DIB_SHOW_IMAGE_USAGE`` will print out a
 summarised disk-usage report for the final image of files and
 directories over 10MiB in size.  Setting ``DIB_SHOW_IMAGE_USAGE_FULL``
diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/installation.rst
index b6524afe..2ffe2c79 100644
--- a/doc/source/user_guide/installation.rst
+++ b/doc/source/user_guide/installation.rst
@@ -3,16 +3,8 @@ Installation
 
 If your distribution does not provide packages, you should install
 ``diskimage-builder`` via ``pip``, mostly likely in a ``virtualenv``
-to keep it separate.
-
-For example, to create a ``virtualenv`` and install from ``pip``
-
-::
-
-   virtualenv ~/dib-virtualenv
-   . ~/dib-virtualenv/bin/activate
-   pip install diskimage-builder
-
+to keep it separate.  For details, see the installation section in the
+:ref:`dev_install`.
 
 Once installed, you will be able to :doc:`build images
 <building_an_image>` using ``disk-image-create`` and the elements
diff --git a/tests/install_test_deps.sh b/tests/install_test_deps.sh
index befea9a0..1d7b6f45 100755
--- a/tests/install_test_deps.sh
+++ b/tests/install_test_deps.sh
@@ -5,42 +5,13 @@ set -o pipefail
 
 sudo apt-get update || true
 sudo apt-get install -y --force-yes \
-        apt-transport-https \
-        bzip2 \
-        debootstrap \
-        docker.io \
-        dosfstools \
-        gdisk \
-        inetutils-ping \
-        lsb-release \
-        kpartx \
-        python-lzma \
-        qemu-utils \
-        rpm \
-        uuid-runtime \
-        yum-utils || \
+        docker.io || \
     sudo yum -y install --enablerepo=epel \
-        bzip2 \
-        dpkg \
-        debootstrap \
-        docker \
-        dosfstools \
-        gdisk \
-        kpartx \
-        util-linux \
-        qemu-img \
-        policycoreutils-python || \
+         debootstrap \
+         dpkg \
+         docker || \
     sudo zypper -n install \
-        bzip2 \
-        debootstrap \
-        docker \
-        dosfstools \
-        gdisk \
-        kpartx \
-        util-linux \
-        python-pyliblzma \
-        yum-utils \
-        qemu-tools || \
+        docker || \
     sudo emerge \
         app-arch/bzip2 \
         app-emulation/qemu \
diff --git a/tox.ini b/tox.ini
index d33bb050..96fd911e 100644
--- a/tox.ini
+++ b/tox.ini
@@ -15,6 +15,10 @@ commands=
 passenv=
     DUMP_CONFIG_GRAPH
 
+[testenv:bindep]
+deps = bindep
+commands = bindep test
+
 [testenv:pep8]
 basepython = python3
 commands =