XIOS on an Apple Silicon Mac - Revision history

Mwolff: /* Compiling XIOS on macOS (Apple Silicon) with openmpi and clang */

2026-10-16T10:37:41Z

‎Compiling XIOS on macOS (Apple Silicon) with openmpi and clang

Mwolff: /* Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang */

2026-10-16T10:29:01Z

‎Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang

Mwolff: /* Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang */

2026-10-16T10:27:08Z

‎Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang

Mwolff: /* Building */

2026-10-16T10:25:33Z

‎Building

Mwolff: Created page with "= Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang = This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Home..."

2026-10-16T10:14:32Z

Created page with "= Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang = This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Home..."

New page

= Compiling XIOS on macOS (Apple Silicon) with Open MPI and Clang =

This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Homebrew Open MPI. In this setup the Open MPI C++ wrapper calls Apple '''clang''', not GCC. Because of that, two settings differ from the stock <code>arch-gfortran</code> files. They are explained in [[#Background: Open MPI uses Clang, not GCC|the background section]] below.

== Tested environment ==

* macOS 26 (Darwin 25.6.0), Apple Silicon (arm64)
* GNU Fortran 16.2.0 (Homebrew), installed as <code>gfortran</code>
* Apple clang 21, which provides <code>/usr/bin/cpp</code> and is called by <code>mpiCC</code>
* Open MPI 5.0.11 (Homebrew)
* netCDF-C 4.10.1 and netCDF-Fortran 4.6.4, compiled from source against Open MPI and installed in <code>/opt/parallel-netcdf</code>

== Arch files ==

Create these three files in the <code>arch/</code> directory of your XIOS source tree.

=== arch/arch-CLANG_MACOSX.env ===

Change <code>NETCDF_DIR</code> to match your netCDF installation.

<pre>
# Environment to compile XIOS on Mac OS X with NETCDF compiled with CLANG
#
# Tested successfully with :
# Mac OS X 25.6.0
# Prerequisite softwares installed with Homebrew
# gfortran : 16.2.0
# openmpi : 5.0.11
#
# Compiled from source with open-mpi
# netcdf : netCDF 4.10.1 netCDF-Fortran 4.6.4
#
#
export NETCDF_DIR=/opt/parallel-netcdf
export NETCDF_INC_DIR=${NETCDF_DIR}/include
export NETCDF_LIB_DIR=${NETCDF_DIR}/lib
</pre>

=== arch/arch-CLANG_MACOSX.fcm ===

<pre>
################################################################################
################### Projet XIOS ###################
################################################################################
#Build environment (2026-10-13):
#
#- macOS 26 (Darwin 25.6.0), arm64
#- GNU Fortran 16.2.0 (Homebrew), installed as `gfortran`
#- Apple clang 21, which provides `/usr/bin/cpp` and is wrapped by `mpiCC`
#- Open MPI 5.0.11 (Homebrew)
## Summary

%CCOMPILER mpiCC
%FCOMPILER mpif90
%LINKER mpif90

%BASE_CFLAGS -w -std=gnu++11
%PROD_CFLAGS -O3 -D BOOST_DISABLE_ASSERTS
%DEV_CFLAGS -g
%DEBUG_CFLAGS -g -O2

%BASE_FFLAGS -D__NONE__ -ffree-line-length-none
%PROD_FFLAGS -O3
%DEV_FFLAGS -g -O2
%DEBUG_FFLAGS -g

%BASE_INC -D__NONE__
%BASE_LD -lc++

%CPP cpp -P -undef
%FPP cpp-16 -P
%MAKE make
</pre>

=== arch/arch-CLANG_MACOSX.path ===

This file gets the netCDF flags from <code>nc-config</code> and <code>nf-config</code>, so both must be on your <code>PATH</code>.

<pre>
NETCDF_INCDIR="$(nc-config --cflags) $(nf-config --fflags)"
NETCDF_LIBDIR="$(nc-config --libs) $(nf-config --flibs)"
NETCDF_LIB=""
</pre>

== Building ==

From the top of the XIOS source tree:

<pre>
./make_xios --arch CLANG_MACOSX --job 8 --full > make_xios.out 2>&1
</pre>

Use <code>--full</code> to rebuild from scratch. <code>make_xios</code> has no <code>--clean</code> option, and it ignores unknown options without any warning. So <code>./make_xios --clean</code> cleans nothing. FCM then keeps reusing old preprocessed files in <code>ppsrc/</code>, and a fix to the preprocessor settings does not take effect.

A successful build produces:
* <code>lib/libxios.a</code>
* <code>bin/xios_server.exe</code>
* <code>bin/generic_testcase.exe</code>

== Background: Open MPI uses Clang, not GCC ==

On Linux, <code>mpif90</code>, <code>mpicc</code> and <code>mpicxx</code> usually all call the GNU compilers. With Homebrew on macOS, Open MPI is built with Apple's toolchain. Only the Fortran wrapper calls GCC:

{| class="wikitable"
! Component !! Wrapper !! Underlying compiler !! C++ standard library
|-
| XIOS (C++ core) || <code>mpiCC</code> || Apple '''clang''' || '''libc++''' (LLVM), linked with <code>-lc++</code>
|-
| XIOS Fortran interface, and the model (e.g. LMDZ / PCM) || <code>mpif90</code> || Homebrew '''gfortran''' || none (GCC Fortran runtime)
|}

This mix causes two problems: one with the preprocessor and one at link time.

=== Why mpiCC is really clang ===

macOS filesystems are case-insensitive by default, so the files <code>mpiCC</code> and <code>mpicc</code> cannot both exist. Homebrew's Open MPI makes <code>/opt/homebrew/bin/mpiCC</code> a symlink to the C wrapper <code>mpicc</code>, which calls Apple <code>clang</code>:

<pre>
$ mpiCC --showme
clang -I/opt/homebrew/Cellar/open-mpi/5.0.11/include -L/opt/homebrew/Cellar/open-mpi/5.0.11/lib -lmpi
</pre>

clang still compiles the XIOS <code>.cpp</code> files as C++, because it picks the language from the file extension. But it compiles them against '''libc++''', LLVM's C++ standard library, not GCC's '''libstdc++'''.

A side effect: <code>OMPI_CXX</code> has no effect on <code>mpiCC</code>, because <code>mpiCC</code> is really <code>mpicc</code>, and <code>mpicc</code> reads <code>OMPI_CC</code>.

=== 1. Link library: <code>-lc++</code> instead of <code>-lstdc++</code> ===

The stock <code>arch-gfortran.fcm</code> sets <code>%BASE_LD -lstdc++</code>. With clang-compiled C++ objects, the link of <code>xios_server.exe</code> fails with errors like:

<pre>
Undefined symbols for architecture arm64:
"std::__1::basic_string<...>::copy(...) const", referenced from: ...
"std::__1::regex_error::regex_error(...)", referenced from: ...
ld: symbol(s) not found for architecture arm64
</pre>

The <code>std::__1::</code> prefix is libc++'s inline namespace. libstdc++ uses different names, such as <code>std::__cxx11::</code>. The two libraries are '''not interchangeable''' at link time: an object compiled against libc++ can only be linked with libc++.

The final link is done by <code>mpif90</code> (gfortran), and gfortran does not add any C++ library on its own. The arch file must name the right one, so <code>%BASE_LD</code> is set to <code>-lc++</code>.

'''This also applies to every program that links against this <code>libxios.a</code>.''' For example, the LMDZ / PCM arch <code>.path</code> file must use:

<pre>
XIOS_LIB="-lxios -lc++"
</pre>

and not <code>-lstdc++</code>. Otherwise the model build compiles all its sources and then fails at the final link with hundreds of undefined <code>std::__1::</code> symbols coming from <code>libxios.a</code>.

To check which C++ library an existing <code>libxios.a</code> needs:

<pre>
nm -C lib/libxios.a | grep -m1 'std::__1::' # match -> libc++ (-lc++)
nm -C lib/libxios.a | grep -m1 'std::__cxx11::' # match -> libstdc++ (-lstdc++)
</pre>

The rule: '''the C++ library named at link time must be the same one that compiled XIOS.''' If you rebuild XIOS with GCC's <code>g++</code> instead (for example <code>%CCOMPILER mpicxx</code> with <code>export OMPI_CXX=g++-16</code>), switch back to <code>-lstdc++</code> in both the XIOS and the model arch files.

=== 2. Fortran preprocessor: <code>cpp-16</code> instead of <code>cpp</code> ===

The XIOS Fortran interface builds its names with a token-pasting macro, defined in <code>src/interface/fortran/xios_fortran_prefix.hpp</code>:

<pre>
#define xios(arg) xios_##arg
#define txios(arg) xios_##arg
</pre>

On macOS, <code>/usr/bin/cpp</code> is Apple clang. It does not expand <code>##</code> in these files, so <code>txios(duration)</code> comes out as <code>xios_##duration</code> instead of <code>xios_duration</code>. Compilation then fails, for example in <code>duration_interface.f90</code>:

<pre>
IMPORT :: xios_##duration
Error: Syntax error in IMPORT statement at (1)
TYPE(xios_##duration), VALUE :: dur
Error: Malformed type-spec at (1)
</pre>

The fix is to use the GNU C preprocessor that comes with Homebrew GCC for Fortran files: <code>%FPP cpp-16 -P</code>. The <code>-16</code> suffix follows the major version of Homebrew GCC. If GCC is upgraded, update this line to match. Check the installed version with:

<pre>
ls /opt/homebrew/bin/cpp-*
</pre>

<code>gfortran -E -P -cpp</code> may also work as the Fortran preprocessor, but it has not been tested.

=== Harmless warning ===

The XIOS build and the model builds may print:

<pre>
ld: warning: ignoring duplicate libraries: '-lnetcdf'
</pre>

It appears because <code>nc-config --libs</code> and <code>nf-config --flibs</code> both list <code>-lnetcdf</code>. You can ignore it.

[[Category:XIOS]]
[[Category:macOS]]

@@ Line 1: / Line 1: @@
 = Compiling XIOS on macOS (Apple Silicon) with openmpi and clang =
-This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Homebrew Open MPI. In this setup the Open MPI C++ wrapper calls Apple '''clang''', not GCC. Because of that, two settings differ from the stock <code>arch-gfortran</code> files. They are explained in [[#Background: Open MPI uses Clang, not GCC|the background section]] below.
+This page makes the assumption that you have built and installed the parallel version of NetCDF similarly to that described on the page [[NetCDF-Parallel on an Apple Silicon Mac]].  Below, one finds the three XIOS arch files needed to build XIOS on macOS (using Homebrew gfortran and Homebrew Open MPI).  The customizations here with respect to the stock <code>arch-gfortran</code> files are driven by the Open MPI C++ wrapper calling Apple '''clang''', not GCC (e.g., [[#Background: Open MPI uses Clang, not GCC|the background section]]).
 == Tested environment ==

← Older revision		Revision as of 10:29, 16 October 2026
Line 1:		Line 1:
−	= Compiling XIOS on macOS (Apple Silicon) with ~~Open MPI~~ and ~~Clang~~ =	+	= Compiling XIOS on macOS (Apple Silicon) with openmpi and clang =

	This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Homebrew Open MPI. In this setup the Open MPI C++ wrapper calls Apple '''clang''', not GCC. Because of that, two settings differ from the stock <code>arch-gfortran</code> files. They are explained in [[#Background: Open MPI uses Clang, not GCC\|the background section]] below.		This page provides the three XIOS arch files needed to build XIOS on macOS with Homebrew gfortran and Homebrew Open MPI. In this setup the Open MPI C++ wrapper calls Apple '''clang''', not GCC. Because of that, two settings differ from the stock <code>arch-gfortran</code> files. They are explained in [[#Background: Open MPI uses Clang, not GCC\|the background section]] below.

@@ Line 9: / Line 9: @@
 * Apple clang 21, which provides <code>/usr/bin/cpp</code> and is called by <code>mpiCC</code>
 * Open MPI 5.0.11 (Homebrew)
-* netCDF-C 4.10.1 and netCDF-Fortran 4.6.4, compiled from source against Open MPI and installed in <code>/opt/parallel-netcdf</code>
+* netCDF-C 4.10.1 and netCDF-Fortran 4.6.4, compiled from source against Open MPI(which is where the CLANG dependence originates) and installed in <code>/opt/parallel-netcdf</code>
 == Arch files ==
@@ Line 20: / Line 20: @@
 <pre>
-# Environment to compile XIOS on Mac OS X with NETCDF compiled with CLANG
+# Environment to compile XIOS on Mac OS X with NETCDF compiled with CLANG (through openmpi)
+#
 # Tested successfully with :

@@ Line 91: / Line 91: @@
 </pre>
-Use <code>--full</code> to rebuild from scratch. <code>make_xios</code> has no <code>--clean</code> option, and it ignores unknown options without any warning. So <code>./make_xios --clean</code> cleans nothing. FCM then keeps reusing old preprocessed files in <code>ppsrc/</code>, and a fix to the preprocessor settings does not take effect.
+Use <code>--full</code> to rebuild from scratch.
 A successful build produces:
 * <code>lib/libxios.a</code>
 == Background: Open MPI uses Clang, not GCC ==