.. |br| raw:: html

   <br/>

.. _linux-host-modern-kernel:

Compile errors with modern Kernel on Host
-----------------------------------------

.. warning:: This article concerns only advanced Linux users!
.. note:: Concerning Yocto Zeus release.


Problem:
~~~~~~~~

If you use a Linux distribution with a modern Kernel (v5.4+), e.g. Arch Linux, Artix Linux, Gentoo, etc., which are **NOT** supported Linux distributions as given by `Yocto Reference Manual`_\ , to compile the current release, which is based upon the current stable Yocto Zeus (v3.0, see `Releases`_),
then there will be most likely a compile error in the QEMU part of the Yocto. That is because of an incompatibility between QEMU 4.1 as used by Zeus and the systems Kernel (v5.4+) and also most likely the far more current Python (v3.7++) of the distribution.


Cause:
~~~~~~

There two causes:

1. Kernel ABI/API changes

   The host's (being Kernel 5.4+) is what the Yocto QEMU package is compiled against. As QEMU is a virtualisation solution thought to allow product development without
   bare-metal and/or physical hardware access and therefore requires the availability of specific Kernel API/ABI interface. Since development of QEMU version 4.1
   and to Linux 5.4 these have changed and as such is the setup used by Yocto incompatible with the one given by the host's Linux 5.4 kernel headers.


2. Python syntax changes

   Arch Linux already uses a Python 3.7++ as default. The language's syntax has from Python 3.6 to Python 3.7 changed and thus has deprecated some syntax used
   by build scripts in the QEMU package.


Workaround:
~~~~~~~~~~~

Upgrade/Backport the included QEMU 4.1 structure of Zeus to the newer `QEMU 4.2`_ from `Yocto Poky master branch`_

This requires to find the top commit of the specific directory (in this case ``meta/recipes-devtools/qemu/`` of poky)


Procedure:
~~~~~~~~~~

Find the top commit of a file/directory with git? `Here`_\ .

Replace the current version, via git checkout of specific commit id (see [1]_ [2]_):

.. prompt::
   :prompts: $

   git rm meta/recipes-devtools/qemu/
   rm -rf meta/recipes-devtools/qemu/
   git checkout 1e97c962f -- meta/recipes-devtools/qemu/


Set the current version of QEMU for Yocto:

Edit the file ``meta/conf/distro/include/tcmode-default.inc`` to effect of these "`patch`" lines:

.. code-block:: text

   -QEMUVERSION ?= "4.1%"
   +QEMUVERSION ?= "4.2%"

which is similar to this specific part (respectively file) of the `patch`_\ .

Be aware that to cherrypick the ``tcmode-default.inc`` file directly from the commit **will** bring merge conflicts. It is on the other
hand more than sufficient enough to just adjust the ``QEMUVERSION`` variable, i.e. been set to the new version used.

While not setting this variable specifically will (because this is essentially a full replacement of the QEMU package) not stop
Yocto from running; but Yocto will do so only begrudgingly and throw warnings of "incorrect version", etc.

.. hint:: Don't forget to check in these changes into the repository, best is to make your own branch right away also, because otherwise any ``repo sync`` will either throw errors or worse permanently get rid of these changes.


.. [1] `@Stackoverflow <https://stackoverflow.com/questions/6119036/how-to-revert-a-folder-to-a-particular-commit-by-creating-a-patch>`_
.. [2] `@Coderwall <https://coderwall.com/p/pgqlkq/git-checkout-a-single-file-from-a-specific-commit>`_

.. _`Yocto Reference Manual`: https://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html#detailed-supported-distros
.. _`Releases`: https://wiki.yoctoproject.org/wiki/Releases
.. _`QEMU 4.2`: https://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/meta/recipes-devtools/qemu?id=1e97c962f29815971cac8c22b111c95709c8ad2b
.. _`Here`: https://stackoverflow.com/questions/16343659/how-to-show-git-log-history-for-a-sub-directory-of-a-git-repo
.. _`Yocto Poky master branch`: https://git.yoctoproject.org/cgit/cgit.cgi/poky/
.. _`patch`: https://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/meta/conf/distro/include/tcmode-default.inc?id=1e97c962f29815971cac8c22b111c95709c8ad2b