diskimage-builder/diskimage_builder/elements/package-installs
Ian Wienand 4dbfab66a1 Pre-install python3 for CentOS
CentOS 7 is the only distro we support currently that doesn't have
Python 3 installed in some form in the base images.  For centos 7 add
an early install of it in the yum element so we can have all the
in-chroot scripts assume Python 3.  There is only one package that
causes issues; yaml which comes from EPEL.  Everywhere else it is a
base package, but we don't have a way to say "enable epel to install
this".  Just hack it in, we don't want to go reworking the world for
CentOS 7 at this point.

Also add python3 and it's yaml library to the centos 8 path.  This
brings in the "user" python3 in /urs/bin/python3 (the "system" python3
is already installed).  Again, this just lets us assume
/usr/bin/python3 in scripts for all platforms.

package-installs is one of these things running python in the chroot,
and unfortunately we have elements that use it at 01- level in
pre-installd.  Thus to make sure python3 is there nice and early, run
it at 0 level, but make sure it comes after yum/dnf update.

Change-Id: I088fc4284e889147ca9a375d4a159264cff53484
2020-08-07 10:34:03 +10:00
..
bin Fix DIB scripts python version 2020-07-07 12:53:51 -07:00
extra-data.d squash-package-install to use the correct python 2017-03-13 20:24:39 +11:00
install.d Move elements & lib relative to diskimage_builder package 2016-11-01 17:27:41 -07:00
post-install.d Move elements & lib relative to diskimage_builder package 2016-11-01 17:27:41 -07:00
pre-install.d Pre-install python3 for CentOS 2020-08-07 10:34:03 +10:00
tests Stop bringing the test environment into the mocks 2020-06-12 10:37:36 +02:00
__init__.py package-installs: provide for skip from env var 2018-11-30 10:02:47 +11:00
element-deps Move elements & lib relative to diskimage_builder package 2016-11-01 17:27:41 -07:00
README.rst package-installs : allow a list of parameters 2020-05-27 06:17:57 +10:00

================
package-installs
================

The package-installs element allows for a declarative method of installing and
uninstalling packages for an image build. This is done by creating a
package-installs.yaml or package-installs.json file in the element directory.

In order to work on Gentoo hosts you will need to manually install
`dev-python/pyyaml`.

example ``package-installs.yaml``

.. code-block:: YAML

  libxml2:
  grub2:
    phase: pre-install.d
  networkmanager:
    uninstall: True
  os-collect-config:
    installtype: source
  linux-image-amd64:
    arch: amd64
  dmidecode:
    not-arch: ppc64, ppc64le
  lshw:
    arch: ppc64, ppc64le
  python-dev:
    dib_python_version: 2
  python3-dev:
    dib_python_version: 3
  libssl-dev:
    build-only: True
  package-a:
    when: DIB_USE_PACKAGE_A = 1
  package-b:
    when: DIB_USE_PACKAGE_A != 1

example package-installs.json

.. code-block:: json

    {
    "libxml2": null,
    "grub2": {"phase": "pre-install.d"},
    "networkmanager": {"uninstall": true}
    "os-collect-config": {"installtype": "source"}
    }


Setting phase, uninstall, or installtype properties for a package overrides
the following default values::

    phase: install.d
    uninstall: False
    installtype: * (Install package for all installtypes)
    arch: * (Install package for all architectures)
    dib_python_version: (2 or 3 depending on DIB_PYTHON_VERSION, see dib-python)

Setting the installtype property causes the package only to be installed if
the specified installtype would be used for the element. See the
diskimage-builder docs for more information on installtypes.

Setting ``build-only`` will cause the package to be added both to the
list of packages to be installed and to the list of packages to be
uninstalled. This allows expressing build-time dependencies that should
not end up in the final image.

The ``arch`` property is a comma-separated list of architectures to
install for.  The ``not-arch`` is a comma-separated list of
architectures the package should be excluded from.  Either ``arch`` or
``not-arch`` can be given for one package - not both.  See
documentation about the ARCH variable for more information.

The ``when`` property is a simple ``=`` or ``!=`` match on a value in
an environment variable.  If the given environment variable matches
the operation and value, the package is installed.  If the variable is
not available in the environment, an exception is raised (thus
defaults will likely need to be provided in ``environment.d`` files or
similar for flags used here).  For example, to install an extra
package when a feature is enabled::

  package:
    when: DIB_FEATURE_FLAG=1

To install ``package`` when ``DIB_FEATURE_FLAG=0`` but
``other_package`` when ``DIB_FEATURE_FLAG=1`` (i.e. toggle between two
packages), you can use something like::

  package:
    when: DIB_FEATURE_FLAG=0
  other_package:
    when: DIB_FEATURE_FLAG!=0

You can also use a list of items in the ``when`` statement, which will
be effectively combined with *and*.

If you need to filter multiple paths for a single package, you can
make the parameters a list.  For example, if ``linux-image-generic``
package should be installed when ``DIB_UBUNTU_KERNEL =
linux-image-generic`` is set *except* on ``arm64`` Xenial hosts, where
we would like to install ``linux-generic-hwe-16.04`` you could use the
following:

.. code-block:: YAML

 linux-image-generic:
  - not-arch: arm64
    when: DIB_UBUNTU_KERNEL = linux-image-generic
  - arch: arm64
    when:
     - DIB_RELEASE != xenial
     - DIB_UBUNTU_KERNEL = linux-image-generic

 linux-generic-hwe-16.04:
   arch: arm64
   when:
    - DIB_RELEASE = xenial
    - DIB_UBUNTU_KERNEL = linux-image-generic

DEPRECATED: Adding a file under your elements pre-install.d, install.d, or
post-install.d directories called package-installs-<element-name> will cause
the list of packages in that file to be installed at the beginning of the
respective phase.  If the package name in the file starts with a "-", then
that package will be removed at the end of the install.d phase.

Using post-install.d for cleanup
================================

Package removal is done in post-install.d at level 95.  If you a
running cleanup functions before this, you need to be careful not
to clean out any temporary files relied upon by this element.
For this reason, generally post-install cleanup functions should
occupy the higher levels between 96 and 99.