==============================
J.U.S.T. Singularity Functions
==============================

.. default-domain:: bash

.. file:: just_singularity_functions.bsh

.. function:: singular_defaultify

.. command:: singularity_import

Converts a docker image to a singularity image, writing the image to the just directory.

:Arguments: * ``$1`` - Singularity image path
            * [``$2`` ...] - Additional arguments to pass along to ``singularity build`` (build spec). If no additional arguments are given, then the spec file is read in from stdin.
:Parameters: * ``SINGULARITY_DOCKER_SOCKET`` - An array to specify a custom docker socket to connect to docker. If SINGULARITY_DOCKER_SOCKET is not an array, it is converted to an array where whitespaces will be split. Default: ``(--mount source=/var/run/docker.sock,destination=/var/run/docker.sock,type=bind)``
             * ``SINGULARITY_IMAGE_UID`` - The user id to set the image to after it is built (as root). Default: current uid
             * ``SINGULARITY_IMAGE_GID`` - The group id to set the image to after it is built (as root). Default: current gid
             * ``SINGULARITY_CMD`` - Optional name for a singularity executable to use. If this is not set, the default behavior is to create a docker and install singularity in there. Using ``SINGULARITY_CMD`` ignores ``SINGULARITY_DOCKER_SOCKET``, ``SINGULARITY_IMAGE_UID``, and ``SINGULARITY_IMAGE_GID``. Spaces are treated as multiple arguments.
             * ``SINGULARITY_IMPORT_FORCE`` - Setting this variable to anything other than null will add the ``--force`` flag to singularity build, overwriting the destination image if it already exists without prompting. Default behavior is to prompt and wait for user input, and defaults to "no" if there is no stdin.

.. command:: singularity_exec
.. command:: singularity_instance-start
.. command:: singularity_run
.. command:: singularity_shell
.. command:: singularity_test

Starts a singularity container using :func:`singularity_functions.bsh Singularity`.

.. command:: singular-compose

singular-compose take the equivalent place of ``docker compose``, but for singularity. This does not use `singularity-compose <https://github.com/singularityhub/singularity-compose>`_, instead it is a much simpler and plainer bash version.

:Arguments: [``-f {filename}`` | ``--file {filename}``] - Optionally specify one or more singular-compose files, and ignoring the default found ``singular-compose.env`` file.

A singular-compose file (default ``singular-compose.env``) is written 100% in bash and gives you the freedom to do anything you need in it. It is designed to be sourced by :cmd:`singular-compose` and has few requirements.

* ``instances`` - must be an array of names of instances. If an instance name is not included here, it will be ignored by :cmd:`singular-compose`. You should use the ``+=`` operator when setting instances, so that multiple files can work together
* ``{instance_name}_image`` - The filename of the singularity image.
* [``{instance_name}_volumes``] - An array of bind mounts that will have the ``-B`` flag added to them.
* [``{instance_name}_environment``] - A paired array of key/value pairs of environment variables that will be set in the singularity container. Even indexes are keys, odd indexes are values (if contiguous).
* [``{instance_name}_singular_flags``] - List of extra flags to be passed to the singularity subcommand.

.. rubric:: Example ``singular-compose.env``

.. code-block:: bash
   :caption: singular-compose.env

   instances+=(django mysql)

   # I can even include other compose files
   source "${DJANGO_SOURCE_DIR}/singular-compose2.env"

   django_environment=(
     TZ "${TZ}"
     DISPLAY "${DISPLAY}"
     JUSTFILE /src/docker/django.Justfile
     JUST_SETTINGS /src/django.env
   )
   django_volumes=(
     "${DJANGO_SOURCE_DIR}:${DJANGO_INSTALL_DIR_DOCKER}:ro"
     "${VSI_COMMON_DIR}:/vsi:ro"
   )
   django_singular_flags=(-c -e --nv)
   : ${django_image=${DJANGO_CWD}/django_${DJANGO_USERNAME}.simg}

   # I can even just copy other arrays (like an anchor)
   mysql_environment=("${django_environment[@]}")
   # Add a data dir, but copy all but the first volume from django
   mysql_volumes=(
     "${DJANGO_SOURCE_DIR}/singular/data:/data:rw"
     "${django_volumes[@]:1}"
   )
   mysql_singular_flags=("${django_singular_flags[@]}")
   : ${mysql_image=${DJANGO_CWD}/mysql_${DJANGO_USERNAME}.simg}

:cmd:`singular-compose` currently supports a few subcommands:

 * ``run`` - ``singularity run`` your singular-compose instance using :func:`singularity_functions.bsh Singularity`.
 * ``shell`` - ``singularity shell`` your singular-compose instance using :func:`singularity_functions.bsh Singularity`.
 * ``exec`` - ``singularity exec`` your singular-compose instance using :func:`singularity_functions.bsh Singularity`.
 * ``test`` - ``singularity test`` your singular-compose instance using :func:`singularity_functions.bsh Singularity`.
 * ``instance start`` - ``singularity instance start`` your singular-compose instance using :func:`singularity_functions.bsh Singularity`.
 * ``config`` - Prints out the configuration for a specific instance, using bash ``declare -p`` notation. This output can be sourced or eval'ed
 * ``config-null`` - A binary version of ``config`` using :func:`string_tools.bsh null_dump`, more useful when sending the information to languages not bash.
 * ``instance`` - Handles other ``singularity`` instance commands for instance management.