Docker / podman support
=======================

In directory administration_tools/docker there are scripts and configuration
files to build docker or podman containers that can be used to build the
RTEMS crosstools and the RTEMS kernel for some specific Linux distributions.

Change Directory
----------------

First enter the docker directory::

  cd administration_tools/docker

Selection of docker/podman
--------------------------

The default is that podman is used to build containers. If you want to use
docker, change the definition of variable `DOCKER` in file 'docker.config'.

How to build a container
------------------------

You can build all containers with::

  ./docker-build-all.sh

or you can build a specific container with::

  ./docker-build.sh DOCKERFILE

List all dockerfiles with::

  ./docker-build.sh -h

How to run the container
-------------------------

Start the container with::

  ./docker-run.sh DOCKERFILE

How to use rtems-from-scratch in inside the container
-----------------------------------------------------

.. note::
   For a more generic description see: :doc:`introduction`.

Your initial working directory in the container is::

  /root/rtems-from-scratch

Now run :doc:`setup.sh <setup>` to specify the RTEMS install directory. A
common choice for the install directory in the container is:

- /opt/rtems
- /opt/lib/rtems

.. note::
   Directory "/opt" in the container is "dist/LINUXVERSION/opt" on your
   dockerhost. So everything you put in "/opt" will still be accessible when
   the container is stopped.

.. note::
   python2 is (probably) not needed for RTEMS version 6 and newer

.. note::
   RTEMS version 5 and newer do not build a loadable kernel image but only
   some libraries. For these versions you have to run one of the
   \*.exe2boot.sh scripts from the rtems-build-tool project to create a file
   that can be booted by the target host. See also
   https://rtems-build-tool.sourceforge.io.

The next steps are:

- build python2: :doc:`bin/build-python2.sh <python2>`
- build crosstools: :doc:`bin/build-crosstools.sh <crosstools>`
- build kernel: :doc:`bin/build-kernel.sh <kernel>`

How to export crosstools from the container
-------------------------------------------

Directory `dist/LINUXVERSION/opt` from your docker host is mounted as
directory `/opt` in the container. If you install the crosstools in a sub
directory in `/opt`, they are directly available on your docker host. You
can, for example, pack these in a tar file and install them on another host
which has the same Linux version.

How to build a deb (debian) or rpm (redhat) package
---------------------------------------------------

There is a helper script, `simple-package-build.sh` which is a thin wrapper
aound the `fpm` program that actually creates the package.

.. note::
   This helper script will ask you to install `fpm`, just enter 'I'
   for 'install' when asked.

.. note::
   `fpm` is a recent application and was tested with Debian-13. On older Linux
   Versions like Debian-11 this may not work-

Here is an example how to create a package from the RTEMS 4.9 cross compiler
tools. Enter::

  bin/simple-package-build.sh /opt/csr/rtems/crosstools/4.9 \
    rtems-4.9-powerpc-crosstools "$(bin/setup.sh --prgversion)-1" \
    "Goetz Pfeiffer <goetzpf@googlemail.com" \
    --desc "RTEMS 4.9 cross-development tools for PowerPC"

This creates the package in the project directory. To make this available
outside the container, copy it to the distribution directory::

  cp -a rtems-4.9-powerpc-crosstools_1.0-1_amd64.deb /opt