Skip to content

README.md

Latest commit

 

History

History
250 lines (192 loc) · 9.03 KB

README.md

File metadata and controls

250 lines (192 loc) · 9.03 KB
Raw

AFNI for Apple Silicon macOS

Unofficial AFNI binaries for Apple Silicon Macs. The package is built with Clang and Homebrew libraries and is intended for arm64 macOS systems using the /opt/homebrew prefix.

Important

This is a community build, not an official AFNI release. For supported installation methods, see the AFNI macOS Apple Silicon guide.

TL;DR: Install AFNI

These steps install the updater-compatible AFNI 26.2.01 revision 2 package.

1. Install the runtime requirements

Install Homebrew first, then run:

brew install --cask xquartz
brew install fontconfig glib gsl jpeg-turbo libomp libpng \
  libx11 libxext libxft libxmu libxp libxpm libxt \
  mesa mesa-glu openmotif zlib-ng-compat

If your organization manages software installations, ask IT to install XQuartz instead of running the first command yourself.

2. Download and verify AFNI

cd "$HOME/Downloads"
curl -LO https://github.com/cecilyen/MacM2_AFNI/releases/download/v26.2.01-arm64-clang.2/macos_13_ARM.AFNI_26.2.01.arm64-clang.2.tgz
echo "65c5903b0a418ff76b396f782c50672944023ae23e80f19fd451478e6c6f94a9  macos_13_ARM.AFNI_26.2.01.arm64-clang.2.tgz" | shasum -a 256 -c -

The checksum command must print OK. Stop if it does not.

3. Install or update AFNI

If AFNI is already installed in the dedicated ~/abin directory, use its updater:

"$HOME/abin/@update.afni.binaries" \
  -local_package "$HOME/Downloads/macos_13_ARM.AFNI_26.2.01.arm64-clang.2.tgz" \
  -bindir "$HOME/abin" \
  -make_backup yes \
  -sys_ok \
  -no_recur

-sys_ok is needed when upgrading the older package because it included a python symlink. Use this command only when ~/abin is dedicated to AFNI. The updater preserves the previous files in an auto_backup.* directory.

For a first installation, extract the archive directly:

mkdir -p "$HOME/abin"
tar -xzf "$HOME/Downloads/macos_13_ARM.AFNI_26.2.01.arm64-clang.2.tgz" \
  -C "$HOME/abin" --strip-components=1

The AFNI updater uses -package for package names hosted on the AFNI server. Use -local_package for this downloaded GitHub archive.

4. Check and launch AFNI

"$HOME/abin/afni" -ver
"$HOME/abin/afni_system_check.py" -check_all
"$HOME/abin/afni"

Package Contents

The published v26.2.01-arm64-clang.2 archive contains:

  • AFNI 26.2.01 arm64 programs and GUI plugins
  • SUMA programs
  • AFNI atlases, templates, refacer data, and support files
  • 2,126 regular files under a single updater-compatible top-level directory
  • no R_io.so from the older official package
  • no Python cache files

Download it from the revision 2 release page. Earlier packages remain available from the releases page.

Runtime Requirements

The binaries directly link to these Homebrew formulae, all listed explicitly in the TL;DR installation command:

fontconfig  glib       gsl       jpeg-turbo  libomp   libpng
libx11      libxext    libxft    libxmu      libxp    libxpm
libxt       mesa       mesa-glu  openmotif   zlib-ng-compat

Homebrew may install additional transitive dependencies. The package uses the macOS system copies of Expat and libiconv. Build-only tools such as autoconf, netpbm, and pkgconf are not required at runtime.

XQuartz is required for the AFNI and SUMA graphical interfaces. R and optional Python modules are needed only by AFNI programs that specifically use them.

This package assumes Apple Silicon Homebrew at /opt/homebrew. It is not an Intel (x86_64) build.

Build Details

AFNI 26.2.01 is compiled as a generic Apple arm64 build rather than being tuned for one M-series processor.

Build profile:

Compiler: Apple clang 21.0.0
CFLAGS/CXXFLAGS: -O3 -arch arm64 -flto=thin -pipe
LDFLAGS: -arch arm64 -flto=thin -Wl,-dead_strip
OpenMP: Homebrew libomp with -Xpreprocessor -fopenmp -DUSE_OMP
zlib: Homebrew zlib-ng-compat
JPEG: Homebrew jpeg-turbo
Expat/iconv: macOS system libraries

The package was stripped with strip -x, which retains global plugin symbols. Validation found:

445/445 Mach-O files: arm64
Missing non-system libraries: 0
AFNI GUI plugins loaded: 49
Plugin load errors: 0
Dataset and JPEG smoke tests: passed
Python cache files: 0

The older R_io.so is not included because it was built against a different AFNI/R library set and requires an R 4.3 framework not present on the test system. Core AFNI and SUMA programs do not require it.

OpenMP on Apple Silicon

AFNI's top-level source README says that Apple's C compiler does not support OpenMP and recommends GCC or Intel icc. The first part remains partly true for the default toolchain, but the compiler recommendations are outdated.

Apple Clang 21 on the build system rejects a plain -fopenmp option and does not include an OpenMP runtime. However, its Clang frontend can compile AFNI's CPU OpenMP code when explicitly connected to Homebrew's LLVM libomp runtime. This package was built with Apple Clang and these OpenMP options:

-Xpreprocessor -fopenmp
-I/opt/homebrew/opt/libomp/include
-L/opt/homebrew/opt/libomp/lib -lomp
-DUSE_OMP

LLVM Clang supports OpenMP, and Homebrew provides both LLVM Clang and an Apple Silicon libomp package. Homebrew LLVM Clang can use the normal -fopenmp option, so GCC is not required. Intel icc is not a current Apple Silicon alternative: Intel ended oneAPI toolkit support for macOS starting with the 2024.0 release. Intel's macOS notice documents that change.

OpenMP validation for this release found:

  • afni_check_omp reported 12 available threads on the M2 Max build system.
  • 35 installed Mach-O programs linked to Homebrew libomp.
  • AFNI 26.2.01 contained 510 OpenMP pragmas across 61 C source/header files.

Parallel regions occur in programs such as 3dQwarp, 3dAllineate, 3dClustSim, 3dREMLfit, 3dTproject, and 3dDespike. OpenMP improves only the parallel portions of a workload; small inputs, serial phases, memory bandwidth, and thread startup can limit or eliminate the speed gain. AFNI's OpenMP notes describe this behavior and the OMP_NUM_THREADS environment variable.

Because the published binaries link /opt/homebrew/opt/libomp/lib/libomp.dylib, libomp is a runtime requirement and is already included in the TL;DR install command.

Official Package Comparison

The archive layout and payload were compared with AFNI's official macos_13_ARM.AFNI_25.3.03.tgz. Common paths had zero file-type or permission-mode mismatches.

File differences after merging portable support data:

  • Added from the official package: funstuff/face_lincoln1.jpg
  • Official-only and excluded: R_io.so
  • Present only in this AFNI 26.2.01 package:
3dSpaceTimeCorr2
adjunct_refacer_make_master_addendum2
afni_refacer2
afnipy/lib_cluster_rois.py
afnipy/lib_cluster_table.py
afnipy/lib_info_items.py
afnipy/lib_torch_util.py
funstuff/face_darwin.jpg
funstuff/face_x2zhang.jpg
gen_cluster_table.py
install_bootcamp_data.tcsh

R_io.so remains excluded because the official file is an older compiled module with the incompatible R and library dependencies described above.

The revision-2 archive was installed successfully with @update.afni.binaries -local_package, including backup mode and an upgrade from the older package's python symlink. All 2,126 installed files matched the package manifest.

Build Choices

  • zlib-ng-compat provides the zlib-compatible API used by AFNI.
  • jpeg-turbo provides the libjpeg-compatible API used by AFNI.
  • Apple Clang with LLVM libomp retains OpenMP without a GCC runtime dependency.
  • The build targets generic Apple arm64; it does not use M2-only CPU flags.

License and Support

AFNI is developed and distributed by the AFNI project. Report problems specific to these packaged binaries in this repository. Report general AFNI questions through the official AFNI support channels.