diff --git a/README.md b/README.md index 28b303e..0f10171 100644 --- a/README.md +++ b/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. diff --git a/apptainer/INSTALL.md b/apptainer/INSTALL.md new file mode 100644 index 0000000..2827b4d --- /dev/null +++ b/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 \ No newline at end of file diff --git a/apptainer/README.md b/apptainer/README.md new file mode 100644 index 0000000..234b3a9 --- /dev/null +++ b/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 +```