Use containers
==============

Once containers are built it is time to use them to compile some code.

SingularityCE_ provides many ways to interact with containers.
The idea is to use the development environment compiled within
the container to build and run Rat C++ projects through it.

.. seealso::

    `SingularityCE - Interacting with images`_

.. important::

    These containers are have no "memory" and everything that was
    done in them that has not been saved to disk via a bind mount
    will NOT persist.

    Results should be stored in a bound/mounted path via the ``-B``
    flag (e.g. in the ``/io`` directory following below examples),
    or within the current working directory which should be
    automatically mounted upon entering the container.

Interactive shell
-----------------

The most straightforward way to interact with
containers is via the interactive shell.

This approach is more suited for
exploration, testing and development.

.. code-block:: bash

    singularity shell -B $(pwd):/io <container>.sif

This will:

    - enter the shell container
      (should see the ``Singularity>`` prompt),

    - bind the current wordking directory to a ``/io``
      directory accessible from the container
      (``-B $(pwd):/io``).

Commands can be executed through this shell to access programs
within the container such as ``cmake``, ``ninja``, CUDA,
Rat libraries, and everything else that is installed in it.

.. hint::

    The `rat-containers/env.sh`_ file defines a simple utility
    script to have a some colors for the prompt as well as some
    basic shell aliases that are nice to have when exploring.

    Source it with ``source env.sh`` from the interactive shell.

Declarative commands
--------------------

Commands can directly be passed to
containers to be run in their environment.

This approach is more suited for
running programs (e.g. on HPC).

.. code-block:: bash

    singularity exec -B $(pwd):/io <container>.sif bash -c "echo /etc/os-release"

This will:

    - run the ``echo /etc/os-release`` from within the container
      (which should print some lore about the Linux distribution),

    - bind the current wordking directory to a ``/io``
      directory accessible from the container
      (``-B $(pwd):/io``).

.. Links
.. _rat-containers/singularity: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/singularity/
.. _rat-containers/env.sh: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/env.sh
.. _SingularityCE: https://sylabs.io/singularity/
.. _SingularityCE - Interacting with images: https://docs.sylabs.io/guides/4.3/user-guide/quick_start.html#interacting-with-images