Compiling in MacOS X

This page explains several methods to compile code engines using MacOS X.

Using XCode

Most development of NairnMPM and NairnFEA is done in MacOS X and thus compiling on MacOS X should be easy. The preferred method is to use XCode (but first you must install XCode, install command line tools, and get a new compiler). A complete XCode project is located at

nairn-mpm-fea/Common/Projects/NairnMPM.xcodeproj

This project is called NairnMPM, but it includes all MPM and FEA source code in two targets named NairnMPM and NairnFEA (as well as targets for ExtractMPM and CompareGlobal). Once xerces is installed, open the NairnMPM.xcodeproj to compile the code by:

Select the target to compile - either NairnMPM or NairnFEA (or ExtractMPM or CompareGlobal)
Choose build and they will compile and be saved in XCode's derived data folder.

If a compile error occurs, you might need to change project settings to match you method for compiling for OpenMP.

If a linking error occurs, you might have conflicting architectures between the XCode settings and the xerces library you installed or be missing some important C++ libraries. To fix xerces problems edit both the project and target settings and under the "Architectures" section, set the "Architectures" option to match the architecture you used when installing xerces or recompile xerces if needed. C++ library problems are sometimes caused by MacOS updates and might need some new project settings.

Compiling Xerces on MacOS X

Before you can compile and run the project, however, you will need an installed version of the xerces library and a copy of the xerces header files. These compiling instructions assume they are installed in the default locations for MacOS X or at:

/usr/local/lib/libxerces-c.dylib

for the library and at

/usr/local/include

for the header files. These can be changed if needed by editing the project and target settings. The nairn-mpm-fea project needs access to xerces 3.0 or newer. This libraries can be obtained by downloading the xerces source code from the Apache Software Foundation web site and then building and installing xerces with the following steps:

First install XCode and command line tools.
Open Terminal app and navigate to the xerces folder expanded from the downloaded file.
Configure the code with the command:
```
./configure CFLAGS="-arch x86_64 -arch arm64" CXXFLAGS="-arch x86_64 -arch arm64"
```
where the provided arch options (or architectures) are for Intel chips (x86_64) or the new Silcon M1 chips (arm64); you can pick one for your computer or include both to have a "fat" binary with both architectures. To determine your chips, choose "About This Mac" from the Apple menu.
When the configuration is done, use the following commands:
```
cd src
make
sudo make install
```
These commands make the library (but not the unneeded xerces examples). The final install command after make is done, installs both the library and the header files at the default locations listed above. It requires sudo for you to provide your administrator password needed to authenticate installation and the default location (which is /usr/local).
When working with nairn-mpm-fea on a new Mac, the xerces installation only needs to be done once. The only reason to repeat it is when a new xerces version is available and/or the project requires a new version for compatibility.

MacOS X Command Line Compiling

It also possible to compile on MacOS X using a command line approach. After installing XCode, command line tools, and a compiler and after installing xerces and its header files, you can compile NairnMPM using:

cd nairn-mpm-fea/NairnMPM/build
make -j 8 SYSTEM=mac (or SYSTEM=mac-clang)

and compile NairnFEA using:

cd nairn-mpm-fea/NairnFEA/build
make -j 8 SYSTEM=mac (or SYSTEM=mac-clang)

The -j 8 option compiles in parallel where the number is number of available cores on your computer. The SYSTEM setting tells make process what compiler to use. Use SYSTEM=mac if you have modified Apple's compiler or SYSTEM=mac-clang if you installed a separate clang-mp.

The above command will compile the source cade and the executables will be installed in nairn-mpm-fea/NairnMPM/input or nairn-mpm-fea/NairnFEA/input, respectively. You can use an additional make install command to copy each compiled executable to your ~/bin folder if desired.

If the command-line compile does not work, the most likely explanations are:

A problem with your compiler settings. Two options are to to edit the makefile to use your chosen compiler or to pass alternate parameters to the make command.
A problem with the xerces installation. You either have to install it as specified above or edit the makefile to recognize your custom installation. The process is documented in the makefile and involves editing the xercesSo and headersPath variables for your different settings.

Compiling Old Version of the Code

You can change settings used in the make process without editing the makefile by passing alternate parameters to the make command. One reason to use this approach is to compile old versions of the code. If old versions are checked out, the XCode project may not work (because of changes in XCode versions, build settings, or compiler you have installed). When this occurs, you can use command-line compile methods instead. For example, if working with current code on on Mac and the clang-mp compiler, you may be able to compile old versions using the build folders and the command

make CC=/opt/local/bin/clang-mp-11 CCLINK=/opt/local/bin/clang++-mp-11 \
        xercesSo=/usr/local/lib/libxerces-c.dylib \
        CFLAGS="-c -O3 -fopenmp -std=c++11 -I/opt/local/include/libomp" \
        LFLAGS="-fopenmp -lc++"

where CC and CCLINK refers to a clang-mp compiler and linker you have installed (old versions of this project do not use CCLINK). The other parameters might also need changing. You can open the project's makefile to see its default options for these variables and then change as needed.

When working with current version of the project, a better approach than using command-line arguments is to edit the makefile and pick your own default settings. Support for using a modifed Apple compiler should be built in already using the SYSTEM=mac setting. To add support for a different version of clang-mp, just follow examples used for others versions in the current makefile.

Installing XCode

All compiling on Mac requires that you install XCode (even if you do not plan to use it for anything else). You can get XCode from the Mac App Store or from the Apple Developer site. It is a large install. Once installed, you then need to install command line tools. Unfortunately, the compilers provided in Apple's "Command Line Tools" do not support OpenMP used to make these code engines parallel. To compile for parallel calculations (which is important), the recommended option is to install and use the clang-mp compiler.

The current check out is configured to compile in XCode with a specific clang-mp version. Prior check outs may be set up to use earlier versions of clang-mp. It is easy to convert any checkout to use the compiler you prefer by making a few changes in the XCode project build settings. Alternatively, you can use command line compilation and specify settings for currently installed compiler

Whenever you update your MacOS or XCode, you may need to repeat some installation steps before you can return to compiling the code engines.

The following sections have more details on installations needed for compiling the code engines.

Installing Command Line Tools

Apple used to install command line tools by default, but stopped doing that a long time ago. You now have to manually install the tools before you can compile code. These steps should work:

The simplest process is to open the Terminal app and enter:
```
xcode-select --install
```
This install may or may not require XCode to already be installed. If it fails try installing XCode first. If it stall fails, refer to MacPorts documentation or try installing HomeBrew (which I think handles command-line too installation as well.
You may need to agree to XCode license by using Terminal app to enter
```
sudo xcodebuild -license
```
Most tools should now be available. You should be able to make and install the xerces library.
To compile the code engines for parallel code, you will additionally need to install a compiler that works with OpenMP (none is provided in the command line tools).

With each new system, Apple creates road blocks to keep you from using you computer for interesting programming. For now, by using a few tricks it is still possible to get around their road blocks. Hopefully these tricks will continue to work in the future.

One issue in the XCode project is that it might not find your xerces library, even if it is in the standard location. If it is not found, the library may be in red in the "External Frameworks and Libraries" folder (or may not). A potential solution is to delete the reference to the library and then add it back. The problem is that you cannot navigate to the /usr/local/lib folder anymore (another new Apple "feature"). Here is a trick to get there:

In the Finder, use the "Go to Folder..." menu command and enter "/usr/local".
After it opens, choose the "Add To Sidebar" menu command. This folder will now appear in all file selection boxes.
Go back to XCode and use command to add files for adding the xerces library.
Go through your new "local" folder and select the xerces library file in /usr/local/lib.

Compiling for OpenMP

Although Apple uses clang for compiling in XCode, for reasons that are hard to justify, they opted to disable compiling with OpenMP (i.e., they disabled the -fopenmp compiler option). They further did not include libomp.dylib, which is needed to run software written for OpenMP. Because doing parallel computations is essential for large calculations, some method to use OpenMP is needed. Two possible solutions are given in this section.

Convince Apple-Installed `clang` to Compile for OpenMP

The approach with minimal installation is to override Apple's disabling of the -fopenmp option to compile for OpenMP anyway. This approach, which minimizes the installations needed on you Mac, uses the following steps:

The only extra installation required is a signed copy of the libomp.dylib. Fortunately. a member of the R project has made this installation easy. First check your version of XCode. Next, check the R project posting to find download file name for your XCode. For eample, Xcode 14.3.x needs openmp-15.0.7-darwin20-Release.tar.gz. But do not download with the links in that web site because Apple will quarantine all files endering in unusable without more work. Instead, download it directly In Terminal app using:
```
curl -O https://mac.r-project.org/openmp/openmp-15.0.7-darwin20-Release.tar.gz
```
replacing the file name with the one you need for your version of XCode.

Once downloaded, extract and install libomp files with

sudo tar fvxz openmp-12.0.1-darwin20-Release.tar.gz -C /

The above two steps will install the following files:

/usr/local/lib/libomp.dylib
/usr/local/include/ompt.h
/usr/local/include/omp.h
/usr/local/include/omp-tools.h

Once these steps are done, you are ready to compile in XCode or compile on a command line. Before using XCode, however, you may have adjust some of the XCode project settings.

According to the R project posting, this approach works now, but uncertain if it will continue to work in the future. Furthermore, each time you upgrade XCode, you may need to install an signed and updated version of libomp.dylib. If for some reason the method stops working or an updated libomp.dylib cannot be found, you can switch to an alternate method that involves installing a separate compiler (and is explain in the next section).

Install `clang-mp` Compiler

An alternate approach to compiling parallel code using OpenMP is to install the clang-mp compiler using MacPorts as follows:

If not already installed, install MacPorts. Be aware that it might need to be reinstalled after updating your MacOS.
Open the Terminal app and enter
```
sudo port selfupdate
sudo port install clang-11 ld64 +ld64_xcode
```
The first command above is only needed to make sure your MacPorts is up to date (you might need to reinstall instead of selfupdate after updating your MacOS). The second step installs the compiler version requested (change "11" to version you want)
To verify it installed, check in Terminal app:
```
which clang-mp-11
/opt/local/bin/clang-mp-11
```
If the which command did not return the installed location, an error occurred during install.

The above install usually works. Some issues have occurred in MacOS Sonoma and new issues might happen in future MacOS version. Here are some known issues:

A MacPorts install command in MacOS Sonoma reports that clang-mp versions 11, 12, and 13 are "known to fail." It appears these version can still be installed, but the sudo port install may not finish. If it exits without a binary, repeat the install command until it (hopefully) finishes. Each repeat will pick up where it left off. If it hangs up while installing, force exit with Control-C and repeat again. If it eventually finishes, the install seems to work. I needed three repeats for one successful install of clang-mp-11.
Installing clang-mp versions 14 or newer in MacOS Sonoma does not say "known to fail", but the first install command exits with a vague "permission denied" error. Repeating the install command then picks up where it left off and finishes the install. Although these version get installed, a new issue appears when compiling the code. See XCode project settings for details on changing the XCode project file to switch to new versions of clang-mp.
The XCode project settings might need to change to match your compiler or to fix other issues caused by MacOS "upgrades."

You can install multiple versions of clang-mp, which can be useful if working with multiple checkouts of this project. More likely, you will only need only one version. If you settle on one version, you can remove older ones with

sudo port uninstall --follow-dependents clang-xx

where xx is the version you want to uninstall.

XCode Build Settings

The downloaded XCode project will have project settings for compiling with Apple's compiler or with an installed clang-mp compiler. To find out which one, open the project in XCode, find the "Build Settings" for the NairnMPM or NairnFEA target, and scroll the to bottom to see "User-Defined" settings. If there are no "User-Defined" setting the project is set up to use Apple's compiler. If there are "User-Defined" settings, the CC setting specifies the clang-mp version being used. The next to sections explain how to change project settings if you want to use a different compiler or change the clang-mp version.

Project Setting for Apple's Compiler

Compiling using Apple's compiler in XCode requires these specific project build settings. Change as needed by editing the build settings for the NairnMPM and NairnFEA targets (both need to be edited):

Compiler for C/C++/Objective-C: select the default compiler.
Other Linker Flags: add -lomp.
Other C Flags: add -Xclang -fopenmp (in one flag line).
Other C++ Flags: add $(OTHER_CFLAGS) to have same flags used for C++ compile as well.
Enable Modules (C and Objective-C): set to No
Scroll to bottom of build settings to see the "User-Defined" settings. If CC, CLANG_CXX_LIBRARY, and LDPLUSPLUS are there, delete them.
Header Search Paths: remove /opt/local/include/libomp if it is there
Runpath Search Paths: remove /opt/local/libexec/llvm-17/lib (or with other clang version number) if it is there.

Project Settings for `clang-mp`

Compiling using a clang-mp compiler in XCode requires these specific project build settings. Change as needed by editing the build settings for the NairnMPM and NairnFEA targets (both need to be edited):

Compiler for C/C++/Objective-C: select the default compiler.
Scroll to bottom of build settings to see the "User-Defined" settings. If CC, CLANG_CXX_LIBRARY, and LDPLUSPLUS are already there, make sure the clang-mp version numbers in CC and LDPLUSPLUS corresponds to one you have installed or edit them ot make them installed. If any "User-Defined" settings are missible, add them with:
1. Use menu command Editor→Add Build Setting→Add User-Defined Setting and add setting for CC with value /opt/local/bin/clang-mp-11 (using clang version number you installed).
2. Use menu command Editor→Add Build Setting→Add User-Defined Setting and add setting for LDPLUSPLUS with value /opt/local/bin/clang++-mp-11 (using clang version number you installed).
3. Use menu command Editor→Add Build Setting→Add User-Defined Setting and add setting for CLANG_CXX_LIBRARY with value libc++.
Other C Flags: add -fopenmp.
Other C++ Flags: add $(OTHER_CFLAGS) to have same flags used for C++ compile as well.
Other Linker Flags: add -fopenmp.
Enable Modules (C and Objective-C): set to No
Header Search Paths: add /opt/local/include/libomp
Runpath Search Paths: add /opt/local/libexec/llvm-17/lib (using clang version number you installed). This setting was not necessary until clang-mp-14 (or maybe it was caused by MacOS Sonoma). Without this setting the executable fails to load the standard C++ libraries. If you compile and run without this setting, you will get an error saying library not found. If you get that error, make sure this setting is correct.

Possible Changes Needed After Updating MacOS or XCode

Unfortunately, Apple does not do a very good job of preserving your prior settings after a major upgrade and you will often need a complete reinstall of anything installed using MacPorts. Some things that might be needed with each MacOS upgrade are:

Get the latest version of XCode (from developer web site or app store).
Reinstall command line tools in Terminal app by entering xcode-select --install
Agree to XCode license in Terminal app using sudo xcodebuild -license (and provide your admin password).
You may need to uninstall all installed MacPorts, reinstall MacPorts, and then reinstall all previously installed options. The process is explained in Migrating a MacPorts Installation. Sometimes a "clean" install is best, especially after a major MacOS update. See links for details, but here is a brief outline of the process:
1. Uninstall all of MacPorts
2. Install MacPorts for the new MacOS
3. Renstall latest versions of all ports needed for this project (clang-mp and maybe subversion too). If you use different ports for other projects, you might want to use one of the advanced approaches on the MacPorts web site when migrating to new a new MacOS instead.
To compile in XCode, you may need more changes (but hard to predict what Apple will require next).

Compiling in MacOS X

Contents

Using XCode

Compiling Xerces on MacOS X

MacOS X Command Line Compiling

Compiling Old Version of the Code

Installing XCode

Installing Command Line Tools

Compiling for OpenMP

Convince Apple-Installed `clang` to Compile for OpenMP

Install `clang-mp` Compiler

XCode Build Settings

Project Setting for Apple's Compiler

Project Settings for `clang-mp`

Possible Changes Needed After Updating MacOS or XCode

Navigation menu

Search

Compiling in MacOS X

Using XCode

Compiling Xerces on MacOS X

MacOS X Command Line Compiling

Compiling Old Version of the Code

Installing XCode

Installing Command Line Tools

Compiling for OpenMP

Convince Apple-Installed clang to Compile for OpenMP

Install clang-mp Compiler

XCode Build Settings

Project Setting for Apple's Compiler

Project Settings for clang-mp

Possible Changes Needed After Updating MacOS or XCode

Navigation menu

Search

Convince Apple-Installed `clang` to Compile for OpenMP

Install `clang-mp` Compiler

Project Settings for `clang-mp`