platform_requirements.txt

================================================================================
MACOS/SMACOS Build Requirements by Platform
================================================================================
Date: April 2026

================================================================================
WINDOWS (x86-64)
================================================================================

COMPILERS (required)
  Intel oneAPI HPC Toolkit
    - ifx  (Intel Fortran Compiler)
    - icx  (Intel C Compiler)
    - MKL  (Math Kernel Library — provides BLAS/LAPACK)
    Download: https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit.html

BUILD TOOLS (required)
  CMake >= 3.21
    Download: https://cmake.org/download/
  Ninja (recommended build system)
    Download: https://github.com/ninja-build/ninja/releases
    Or via: winget install Ninja-build.Ninja

GRAPHICS (required for USE_GIZA=ON)
  All bundled — no external installation needed:
    zlib 1.3.1        (bundled in macos_f90/giza/src/subprojects/zlib)
    libpng 1.6.43     (bundled in macos_f90/giza/src/subprojects/libpng)
    pixman 0.35.1     (bundled in macos_f90/giza/src/subprojects/pixman)
    cairo 1.13.1      (bundled in macos_f90/giza/src/subprojects/cairo)
    giza 1.2.0        (bundled in macos_f90/giza/src)
  Win32 windowed display uses native Windows APIs (user32, gdi32, msimg32)
  — no extra installation needed

WINDOWED DISPLAY DEVICE
  /xw device uses native Win32 HWND — no X server needed

PREPROCESSOR DEFINES
  macos target:  CMACOS MSWIN PGPLOT
  smacos target: CSMACOS MSWIN

COMPILER FLAGS
  Fortran: /fpp /extend-source:132 /align /names:uppercase /assume:underscore
           /warn:nointerfaces /DPGPLOT /DMSWIN
  Release: /O2 /fp:strict /Qmkl
  C:       /nologo /D_CRT_SECURE_NO_WARNINGS /DMSWIN

BUILD COMMANDS
  rd /s /q build
  cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DUSE_GIZA=ON
  cmake --build build --target macos
  cmake --build build --target smacos

OUTPUT
  build\bin\macos.exe        (executable)
  build\lib\smacos.lib       (static library)

================================================================================
LINUX (x86-64)
================================================================================

COMPILERS (required)
  Intel oneAPI HPC Toolkit
    - ifx  (Intel Fortran Compiler)
    - icx  (Intel C Compiler)
    - MKL  (Math Kernel Library — provides BLAS/LAPACK)
    Download: https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit.html
    Or via package manager:
      wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
      sudo apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
      sudo apt-get install intel-hpckit

BUILD TOOLS (required)
  CMake >= 3.21
    sudo apt-get install cmake        # Ubuntu/Debian
    sudo dnf install cmake            # RHEL/Fedora
  Ninja (recommended)
    sudo apt-get install ninja-build  # Ubuntu/Debian
    sudo dnf install ninja-build      # RHEL/Fedora

GRAPHICS — system libraries (required for USE_GIZA=ON)
  X11 development headers
    sudo apt-get install libx11-dev           # Ubuntu/Debian
    sudo dnf install libX11-devel             # RHEL/Fedora
  XRender development headers
    sudo apt-get install libxrender-dev       # Ubuntu/Debian
    sudo dnf install libXrender-devel         # RHEL/Fedora

  Verify X11/XRender are present:
    pkg-config --exists x11 && echo "X11 found" || echo "X11 missing"
    pkg-config --exists xrender && echo "XRender found" || echo "XRender missing"

  All graphics libraries bundled — no system install needed:
    zlib, libpng, pixman, cairo, giza

WINDOWED DISPLAY DEVICE
  /xw device uses X11 (Xlib) — requires a running X server or XWayland
  For interactive display over SSH: use ssh -Y with VcXsrv or MobaXterm
    on Windows side, or XQuartz on macOS side
  On headless servers: use /png, /pdf, /eps, /svg for file output instead

PREPROCESSOR DEFINES
  macos target:  CMACOS LNXOS PGPLOT
  smacos target: CSMACOS LNXOS
  NOTE: smacos does NOT define CMACOS on Linux (matches original Makefile)

COMPILER FLAGS
  Fortran: -fpp -extend-source 132 -align -warn nointerfaces -DPGPLOT -DLNXOS
           NOTE: No -names uppercase or -assume underscore (Linux default)
  Release: -O2 -fp-model strict -qmkl
  C:       -D_CRT_SECURE_NO_WARNINGS -DLNXOS

BUILD COMMANDS
  source /opt/intel/oneapi/setvars.sh   # activate Intel oneAPI environment
  rm -rf build
  cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DUSE_GIZA=ON
  cmake --build build --target macos
  cmake --build build --target smacos

OUTPUT
  build/bin/macos           (executable)
  build/lib/libsmacos.a     (static library)

================================================================================
macOS (x86-64 or Apple Silicon)
================================================================================

STATUS: Not yet tested. CMake infrastructure in place, compiler flags TBD.

COMPILERS (required)
  GCC/gfortran (recommended — works on both Intel and Apple Silicon Macs)
    brew install gcc
    (provides gfortran and gcc)
  NOTE: Intel oneAPI is NOT supported on macOS.
    Apple Silicon uses ARM architecture which Intel oneAPI does not support.
    Even on older Intel Macs, GCC/gfortran is the standard choice.

  CMakeLists.txt currently only sets flags for Intel oneAPI (IntelLLVM).
  GCC/gfortran flag support will be added after Linux is confirmed stable.

  GCC/gfortran flag translation from Intel oneAPI:
    -fpp               → -cpp
    -extend-source 132 → -ffixed-line-length-132
    -names uppercase   → (not needed, gfortran uses lowercase by default)
    -assume underscore → (default on gfortran)
    -qmkl              → link OpenBLAS or Apple Accelerate instead

BLAS/LAPACK
  Apple Accelerate framework (built into macOS — no install needed)
  Or: brew install openblas

BUILD TOOLS (required)
  CMake >= 3.21
    brew install cmake
  Ninja (recommended)
    brew install ninja
  Xcode Command Line Tools (provides system headers and linker)
    xcode-select --install

GRAPHICS — system libraries (required for USE_GIZA=ON)
  X11/XRender via XQuartz — for /xw interactive window
    Download: https://www.xquartz.org/
    Or: brew install --cask xquartz
    (XRender is included with XQuartz)

  All graphics libraries bundled — no system install needed:
    zlib, libpng, pixman, cairo, giza

BUILD COMMAND (once GCC flag support is added)
  rm -rf build
  cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DUSE_GIZA=ON \
        -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_C_COMPILER=gcc
  cmake --build build --target macos

================================================================================
SUMMARY TABLE
================================================================================

Requirement            Windows              Linux                macOS
-----------------------------------------------------------------------
Fortran compiler       ifx (oneAPI)         ifx (oneAPI)         gfortran (GCC)
C compiler             icx (oneAPI)         icx (oneAPI)         gcc (GCC)
BLAS/LAPACK            MKL (oneAPI)         MKL (oneAPI)         Accelerate/OpenBLAS
CMake                  >= 3.21              >= 3.21              >= 3.21
Ninja                  required             required             required
X11 headers            not needed (Win32)   libx11-dev           XQuartz
XRender headers        not needed (Win32)   libxrender-dev       XQuartz
zlib                   bundled              bundled              bundled
libpng                 bundled              bundled              bundled
pixman                 bundled              bundled              bundled
cairo                  bundled              bundled              bundled
giza                   bundled              bundled              bundled
Interactive window     Win32 /xw            X11 /xw              XQuartz /xw
File output            PNG/PDF/EPS/SVG/PS   PNG/PDF/EPS/SVG/PS   PNG/PDF/EPS/SVG/PS
macos build            Working              Working              Planned
smacos build           Working              Working              Planned
CMACOS defines         CMACOS only          CMACOS only          TBD
CSMACOS defines        CSMACOS only         CSMACOS only         TBD

================================================================================
IMPORTANT NOTES FOR DEVELOPERS
================================================================================

1. PREPROCESSOR SYMBOL CONVENTION — BOTH PLATFORMS
   On Windows:  macos defines CMACOS only. smacos defines CSMACOS only.
   On Linux:    macos defines CMACOS only. smacos defines CSMACOS only.
   Both platforms now match the original Makefile convention.
   Code that uses #ifdef CMACOS will be true for macos builds only.
   Code that uses #ifdef CSMACOS will be true for smacos builds only.
   Do NOT use #ifdef CMACOS to select between macos and smacos — it works
   correctly because the two defines are now mutually exclusive.

2. SYMBOL NAMING CONVENTION DIFFERENCE
   Windows (ifx): -names uppercase -assume underscore → UPPERCASE_ symbols
   Linux (ifx):   default → lowercase_ symbols
   C files that interface with Fortran must handle this difference.
   See utilsub_c.c FTN_NAME macro and splicubi2.c for examples.

3. CAIRO GENERATED HEADERS
   cairo-features.h and config.h are generated by CMake into the build
   directory. They use #ifdef _WIN32 guards to select platform-specific
   content (Win32 surface vs Xlib surface, pthread vs CRITICAL_SECTION).
   These files should never be committed to version control.

4. GIZA SOURCE FILES IN VERSION CONTROL
   Delete these files from the source tree before committing — they are
   generated by CMake and will cause build failures if stale versions
   from another platform are present:
     macos_f90/giza/src/subprojects/cairo/src/config.h
     macos_f90/giza/src/subprojects/cairo/src/cairo-features.h

================================================================================
END OF REQUIREMENTS
================================================================================