Apptainer for Vortex

[rahul7rajdn]

Key Additions

1. vortex.def: Apptainer Definition File

   Base Image: ubuntu:22.04
   System Dependencies Installed: Compiler toolchains: gcc, g++, make, verilator, etc.
   Libraries: libcairo2, libtheora0, libpango, libavformat58, libavcodec58, etc.
   JDK: openjdk-11
   Python 3.9, CMake 3.26 (manually installed)

   Environment Setup:
   UTF-8 locales
   Boost and OpenSSL library paths added to LD_LIBRARY_PATH

   Post Section Enhancements:
   Package lock handling and cleanup
   fakeroot, wget, and USB/pci support
   Locale and symlink fixes
   Labels & Test Section: Metadata and verification of base environment functionality

2. install_boost_openssl.sh: Boost/OpenSSL Installer

   Installs boost-1.66 and openssl-1.1 from .deb packages
   Extracts .deb using ar and tar --zstd
   Copies to /opt/ and verifies directory structure
   Used in %post section of vortex.def

3. run_apptainer.sh: Launcher Script
   Simplifies container launch with environment variables:
   GIT_REPO_PATH, CONTAINER_IMAGE, VORTEX_TOOLCHAIN_PATH, etc.
   Uses apptainer shell with:
   --fakeroot and --cleanenv
   Bind mounts for PCI/USB, firmware, Xilinx tools, and code repositories

README Additions

1. Build Instructions:
   Interactive Slurm session setup (e.g. salloc -p rg-fpga ...)
   apptainer build --no-https vortex.sif vortex.def
2. Usage:
   chmod +x run_apptainer.sh && ./run_apptainer.sh
   Device access (e.g., lsusb) inside the container
3. Simulation and Bitstream Steps:
   SIMX, RTLSIM, XRTSIM via blackbox.sh
   Toolchain install (ci/toolchain_install.sh) and setup
   Bitstream generation with Xilinx U50 platform and Vitis
   Running FPGA jobs with ./ci/blackbox.sh --driver=xrt

Benefits:
Reproducible Environment: Same setup for simulation and hardware across machines
HPC Compatibility: Targets research clusters where Apptainer is standard
Minimal Host Requirements: Only Apptainer and bound paths needed on host
Support for USB/PCI & FPGA workflows

[Udit8348]

Hi Rahul,

I think these look good, one suggestion I have is to replace the long run command with a script that handles that. You get the benefit of version controlling the run command plus you can add env variables to the script. This could be worth investigating

Additionally, if you want the container to have support for building vortex from scratch then you can look at my modified def file

[Udit8348]

all edits look good!

[jyoung3131]

Looks good - you may want to note in the "run_apptainer" script that the bindmounts are likely specific for the user's cluster environment.