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 + + $ 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 ` 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 =