Build examples ============== The `SingularityCE Definition Files`_ provided at `rat-containers/singularityCE`_ use chaining in order to build several containers for different purposes. .. mermaid:: ../../graphs/repo-rat-containers/singularityCE_examples_chain.mmd Overview -------- - ``nvidia/cuda_11.5.2-devel-rockylinux8``: base image from Docker library to start bootstrap from, contains Rocky Linux 8 OS as well as packages required to compile CUDA related projects. It is however incomplete to compile Rat C++ libraries and more dependencies need to be installed on this system. - ``rocky-cuda``: local image bootstrapped from previous image with more development dependencies required to compile Rat C++ libraries (e.g; Git, CMake, Ninja, LAPACK, OpenBLAS, Boost, etc...). This images installs all dependencies available in the package manager repositories of Rocky Linux using ``dnf``. - ``rocky-cuda-project-rat``: local image bootstrapped from ``rocky-cuda``. This one installs all other libraries that could not be installed beforehand to compile Rat C++ libraries. It compiles from source TCLAP, Armadillo, SuiteSparse, Sundials, NLopt, and of course all Rat libraries. - ``rocky-cuda-pyrat``: local image bootstrapped from ``rocky-cuda``. Very similar to ``rocky-cuda-project-rat`` with the addition of Python related packages to simplify building and packaging of pyRat_ Python wheels. The `definition files`_ contain all the necessary commands to build Rat C++ compliant containers with the adequate development environements, as well as a definition for pyRat_. Build examples -------------- This subsection describes how to build the above images using the `definition files`_ available at `rat-containers/singularityCE`_ by chaining them like in the above diagram. .. hint:: **Feel free to take these as bases and implement images as see fit.** One could for instance: - "Flatten" the NVIDIA, ``rocky-cuda`` and the ``rocky-cuda-project-rat`` definitions into a single definition file to be more direct. - Update the libraries versions to newer ones (e.g. Rat ``v2.022.2``) and patch some errors (if there are any). - Change the base OS from Rocky Linux 8 to another base image. - Install more libaries in the environment to compose Rat with other programs. The following images are built within the `rat-containers/singularityCE`_ directory. .. code-block:: bash cd singularityCE ``rocky-cuda`` image -------------------- This image serves as the base for ``rocky-cuda-project-rat`` and ``rocky-cuda-pyrat`` and should be built first if chaining. - Pull the NVIDIA CUDA Rocky Linux 8 image from Docker_: .. code-block:: bash singularity pull docker://nvidia/cuda:11.5.2-devel-rockylinux8 This image contains the `CUDA Toolkit`_ (``nvcc``, ``libcublas``, ``libcublasLt``, ...) needed to enable GPU acceleration for Rat. It is also possible to install the `CUDA Toolkit`_ inside the container from conventional methods as described in `CUDA Toolkit installation guide`_, however pulling it from an existing image seems quite faster. Unfortunately this image does not contain basic C/C++ development tools and dependencies needed to compile Rat (yet). - Bootstrap the ``rocky-cuda`` image from the previous one: .. code-block:: bash sudo singularity build --force rocky-cuda.sif rocky-cuda.def This will build the ``rocky-cuda.sif`` container from the ``rocky-cuda.def`` definition file. It bootstraps from the previous Docker_ image and adds tools and libraries such as CMake, Boost, VTK and many others. Dependency libraries are installed with ``-devel`` to include development files such as headers for compilation and linking. Some other dependencies not being available in the ``dnf`` package manager repositories will need to be compiled locally for Rat. This will be done in the next images. ``rocky-cuda-project-rat`` image -------------------------------- This image utilizes the previous ``rocky-cuda.sif`` image to compile and install the rest of the dependencies as well as the Rat C++ libraries. .. code-block:: bash sudo singularity build --force rocky-cuda-project-rat.sif rocky-cuda-project-rat.def This definition file: - downloads needed tarball sources, - compiles and install last dependencies such as NLopt or SuiteSparse, - compiles and install Rat libraries. The result is the ``rocky-cuda-project.sif`` container which includes everything needed to compile a Rat project with CUDA. ``rocky-cuda-pyrat`` image -------------------------- This image the very similar to the previous one. It simply adds a few utilities to easily compile pyRat_ and build wheels from within, such as UV_ and PatchELF_. .. code-block:: bash sudo singularity build --force rocky-cuda-pyrat.sif rocky-cuda-pyrat.def The result is the ``rocky-cuda-project.sif`` container which includes everything needed to compile a Rat project with CUDA, as well as tools to easily build pyRat_ and Python wheels. .. Links .. _CUDA Toolkit: https://developer.nvidia.com/cuda-downloads .. _CUDA Toolkit installation guide: https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Rocky&target_version=8&target_type=rpm_local .. _Docker: https://www.docker.com/ .. _Docs: https://gitlab.com/project-rat-extras/docs .. _Nix: https://en.wikipedia.org/wiki/Nix_(package_manager) .. _PatchELF: https://github.com/nixos/patchelf .. _Project-Rat: https://gitlab.com/project-rat .. _pyRat: https://gitlab.com/project-rat-extras/pyrat .. _PRE Docs: https://gitlab.com/project-rat-extras/docs .. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation .. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers .. _rat-containers/singularityCE: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/singularityCE/ .. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg .. _Singularity: https://sylabs.io/singularity/ .. _SingularityCE: https://sylabs.io/singularity/ .. _SingularityCE definition files: https://docs.sylabs.io/guides/4.4/user-guide/definition_files.html .. _definition files: https://docs.sylabs.io/guides/4.4/user-guide/definition_files.html .. _SingularityCE preferred bootstrap agents: https://docs.sylabs.io/guides/4.3/user-guide/definition_files.html#preferred-bootstrap-agents .. _UV: https://docs.astral.sh/uv/