Added apptainer instructions for Vortex tutorials

README.md

@@ -116,6 +116,11 @@ Provided are seven hands-on tutorial assignments covering various aspects of Vor
 ### Remote Access
 A terminal interface hosted by the [CRNCH Rogues Gallery](https://crnch-rg.cc.gatech.edu/) is provided. [Instructions can be found here](./REMOTE_ACCESS.md).
 
+
+### Apptainer
+See the [Apptainer instructions](./apptainer/README.md) for how to set up the apptainer and run simulation for Vortex.
+
+
 ### Docker (Experimental)
 See the [Docker instructions](./docker/README.md) for how to set up a Docker image for Vortex.
 

apptainer/INSTALL.md

@@ -0,0 +1,114 @@
+Apptainer (formerly Singularity) is a container system optimized for HPC and secure scientific environments, so installation varies by OS family.
+
+
+## 🐧 1. Ubuntu / Debian
+#### ✅ Option A — Install via .deb package 
+
+```
+sudo apt update
+sudo apt install -y build-essential libseccomp-dev pkg-config squashfs-tools cryptsetup wget
+
+# Download the latest stable release
+wget https://github.com/apptainer/apptainer/releases/download/v1.2.2/apptainer_1.2.2_amd64.deb
+
+# Install
+sudo apt install ./apptainer_1.2.2_amd64.deb
+
+# Verify
+apptainer --version
+```
+
+#### ✅ Option B — Build from source (if .deb not available)
+```
+sudo apt update
+sudo apt install -y build-essential uuid-dev libseccomp-dev pkg-config squashfs-tools cryptsetup wget git golang-go
+
+cd /tmp
+wget https://github.com/apptainer/apptainer/releases/download/v1.2.2/apptainer-1.2.2.tar.gz
+tar -xzf apptainer-1.2.2.tar.gz
+cd apptainer-1.2.2
+./mconfig
+make -C builddir
+sudo make -C builddir install
+
+# Verify
+apptainer --version
+```
+
+
+## 🧱 2. RHEL / AlmaLinux / Rocky / CentOS
+#### ✅ Option A — Install via EPEL (Recommended)
+```
+sudo dnf install -y epel-release
+sudo dnf config-manager --set-enabled crb
+sudo dnf install -y apptainer
+```
+
+Works for RHEL 8/9, AlmaLinux, Rocky Linux, CentOS Stream, etc.
+
+#### ✅ Option B — Build from source
+```
+sudo dnf groupinstall -y "Development Tools"
+sudo dnf install -y golang libseccomp-devel squashfs-tools cryptsetup wget git pkg-config make
+
+cd /tmp
+wget https://github.com/apptainer/apptainer/releases/download/v1.2.2/apptainer-1.2.2.tar.gz
+tar -xzf apptainer-1.2.2.tar.gz
+cd apptainer-1.2.2
+./mconfig
+make -C builddir
+sudo make -C builddir install
+
+# Verify
+apptainer --version
+```
+
+
+## 🍎 3. macOS
+
+Apptainer doesn’t run natively on macOS — it’s a Linux-only system (needs Linux kernel namespaces).
+But you can run it using Linux virtual environments:
+
+#### ✅ Option A — Using Homebrew + Apptainer inside a Linux VM
+
+Install Homebrew and a lightweight Linux VM (like multipass):
+
+```
+brew install --cask multipass
+multipass launch --name ubuntu --cpus 4 --mem 4G --disk 20G
+multipass shell ubuntu
+```
+
+Inside the VM, follow the Ubuntu install steps above.
+
+#### ✅ Option B — Using Docker + Apptainer inside container
+```
+docker run -it --privileged ghcr.io/apptainer/apptainer:latest bash
+
+# Verify
+apptainer --version
+```
+
+
+## 🪟 4. Windows 10/11
+
+Apptainer requires Linux namespaces → it cannot run directly on native Windows.
+
+#### ✅ Option A — Use WSL2 (Windows Subsystem for Linux)
+
+Enable WSL2 and install Ubuntu:
+```
+wsl --install -d Ubuntu
+```
+Inside WSL Ubuntu terminal: Follow the Ubuntu install steps above (either using Ubuntu Debian package / Build from source).
+
+
+#### ✅ Option B — Use a full Linux VM (VirtualBox, VMware, or WSL2 Ubuntu)
+
+If you need GPU or privileged access, use a full Linux VM with Apptainer installed inside.
+
+
+
+
+### Reference:
+https://apptainer.org/docs/admin/main/installation.html

apptainer/README.md

@@ -0,0 +1,77 @@
+# Apptainer Build Process
+
+Prerequisite: Install `apptainer` package on your machine by following [INSTALL.md](./INSTALL.md)
+
+
+# Clone Vortex repo
+
+Create tools directory for mounting vortex-toolchains onto the apptainer
+```
+$   mkdir -p tools
+```
+
+```
+$	git clone --depth=1 --recursive https://github.com/vortexgpgpu/vortex.git
+```
+
+Go to `apptainer` directory and build the vortex apptainer
+
+```
+$   ls
+    tools  vortex
+
+$   cd vortex/miscs/apptainer
+
+$  apptainer build --no-https vortex.sif vortex.def
+
+```
+
+To start the apptainer,
+```
+apptainer shell --fakeroot --cleanenv --writable-tmpfs  --bind ../../../vortex:/home/vortex --bind ../../../tools:/home/tools vortex.sif
+```
+
+
+# Vortex Simulation inside Apptainer
+
+Go to the bind of vortex repo,
+```
+Apptainer> cd /home/vortex
+Apptainer> ./ci/install_dependencies.sh
+Apptainer> mkdir build
+Apptainer> cd build
+Apptainer> ../configure --xlen=32 --tooldir=$HOME/tools
+
+
+Skip the below 3 steps, if toolchains are already present in the $HOME/tools; (These steps are compulsory while getting the setup ready for the first time)
+Apptainer> sed -i 's/\btar /tar --no-same-owner /g' ci/toolchain_install.sh
+Apptainer> ./ci/toolchain_install.sh --all
+Apptainer> sed -i 's/\btar --no-same-owner /tar /g' ci/toolchain_install.sh
+
+Apptainer> ls $HOME/tools/
+libc32  libc64  libcrt32  libcrt64  llvm-vortex  pocl  riscv32-gnu-toolchain  riscv64-gnu-toolchain  sv2v  verilator  yosys
+
+Apptainer> source ./ci/toolchain_env.sh
+Apptainer> verilator --version
+```
+
+
+### Running SIMX, RTLSIM and XRTSIM
+```
+Compile the Vortex codebase
+Apptainer> make -s
+
+Run the programs by specifying the appropriate driver as shown below:
+
+SIMX
+Apptainer> ./ci/blackbox.sh --cores=2 --app=demo --driver=simx
+
+RTLSIM
+Apptainer> ./ci/blackbox.sh --cores=2 --app=demo --driver=rtlsim
+
+XRTSIM
+Apptainer> ./ci/blackbox.sh --cores=2 --app=demo --driver=xrt
+
+
+Apptainer> make -C runtime/ clean
+```