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 is easy. The preferred method is to use XCode (but first you must fix its compiler problem). 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. Once xerces is installed, open the NairnMPM.xcodeproj to compile the code by:

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

If a linking error occurs, you might have conflicting architectures between the XCode settings and the xerces library you installed. To fix this problem 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.

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. Since revision 274 of the nairn-mpm-fea project, this library must be xerces 3.0 or newer; prior to that revision, it had be xerces 2.8 or older. These 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 (after seeing potential startup issues on Lion or newer systems):

Open Terminal app and navigate to the xerces source folder expanded from the downloaded file.
Configure the code with the command:
```
./configure CFLAGS="-arch x86_64" CXXFLAGS="-arch x86_64"
```
where the provided arch (or architecture) is the desired option for your machine. The main Mac options are i386 for 32 bit Intel processors, x86_64 for 64 bit Intel processors, ppc for 32 bit PowerPC chips, or ppc64 for 64 bit PowerPC64 chips. Although i386 will work on any Intel processor, you should use x86_64 if you have a 64 bit processor, because the code will run faster. To determine how many bits your Intel chip has, chose "About This Mac" from the Apple menu, click "More Info..." button, and look up the processor name in the hardware section. The "Intel Core Solo" and "Intel Core Duo" are 32 bit chips and most others are 64 bit chips.
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 is easy to compile on MacOS X using a command line approach (after seeing potential startup issues on Lion or newer systems and after updating the compiler). First (and first time only) install xerces and its header files as explained above and make sure they are in the specified default locations. Once xerces is ready, you can compile NairnMPM using:

cd nairn-mpm-fea/NairnMPM/build
make SYSTEM=mac

and compile NairnFEA using:

cd nairn-mpm-fea/NairnFEA/build
make SYSTEM=mac

All source code will be compiled 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 explanation is 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.

You can pass additional parameters to the make command to alter the compilation process. See comments in the makefile for all the latest options.

Using Eclipse IDE

Because the Eclipse IDE can run on multiple platforms, you can use it on Mac OS X for compiling as well. For details, see help on compiling using Eclipse IDE.

MacOS X Lion or Newer Command Line Tools

Apple choose not to install command line tools on Lion (and newer systems) and makes it hard to access some very useful folders (such as your home "Library" folder). With these changes, you cannot compile nairn-fea-mpm code engines or xerces until you install command line tools. For Lion (10.7) and newer, you can do the following:

You will need to install XCode (even if you do not plan to use it) and in addition install command line tools. These steps keep getting harder with each new MacOS update. For up to date information on installing XCode and command lines tools, see MacPorts instructions. You can also get the command line tools from the Apple developer website and search for command line tools (being sure the correct tells for you current Xcode and MacOS versions). You may need to be signed up as an Apple developer.
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 project and then use the provided XCode project to build OSParticulas, NairnMPM, and NairnFEA (but see compiler issues for compiling options with XCode).

With each now system, Apple seems to creating 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.

MacOS X Compiler

The "Command Line Tools" installed by XCode include only Apple-approved compilers. Unfortunately, it seems none of their recent compilers support OpenMP used to make the code engines parallel. On some Macs, code compiled with the default compiler will randomly crash when run in parallel. On others, the code will not even compile. The two solutions are to compile without OpenMP (and lose all advantages of multiprocessor execution) or to install and use an unsupported GCC compiler.

Compile Without OpenMP

To compile without OpenMP, simply comment out the line

#include <OpenMP>

in the MPMPrefix.hpp file, change the compiler to an Apple-approved compiler, and then compile to get serial version of the code engines.

The preferred solution is to switch to a compiler that supports OpenMP such as GCC 4.8 or newer. This process requires two more steps as explained in the next two sections.

Install GCC 4.8 or Newer

The first step is to install a new compiler. A good way is to install GCC 4.8 or newer is to use MacPorts. Once MacPorts tool is installed, the installation of GCC is easy, as explained in this blog. In brief, all you need is to open the Terminal app and enter:

sudo port selfupdate
sudo port install gcc48

The first command above is only needed to make sure your MacPorts is up to date (and you may need to update MacPorts after installing a new MacOS). The second step will install the compiler at

/opt/local/bin/g++-mp-4.8

On a new Mac computer with El Capitan (10.11.x), I was not able to install GCC 4.8 (it failed in the final build step). I was able, however, to install GCC 4.9 using above method with 4.9 replacing 4.8. The last step will install the compiler at

/opt/local/bin/g++-mp-4.9

If you want to remove GCC 4.8, you may be able to use

sudo port uninstall --follow-dependents gcc48

For command line compiling, installing GCC 4.8, 4.9, (or newer) is enough. The makefiles in the build folders currently assume the above path for GCC 4.8 when command-line compiling on a Mac. If needed, you can update the makefile for a differently compiler on a Mac or you can use the CC option to specify path any compiler, such as:

make SYSTEM=mac CC=/opt/local/bin/g++-mp-4.9

If you prefer to compile in XCode instead, continue to the next step.

Using GCC 4.8 or Newer in XCode

Using an unsupported compiler in XCode requires a hack. Fortunately, a friend of this project (Hammd Mazhar) has provided a solution. The process is explained on this blog (for XCode 4.x) with an update for Xcode 6.x. In brief, the goal is to install a custom plug in. The shortest approach is download a plug in and install it:

For GCC 4.8 or GCC 4.9 installed as explained above, download this GCC 4.8 XCode plug in or this GCC 4.9 XCode plug in. For GCC newer then 4.9, you might find a plug in in the repository xcode-gcc.

For XCode 7.x and 6.x (and probably 5.x), the plug in must be installed in the application at:

/Applications/Xcode.app/Contents/Plugins/Xcode3Core.ideplugin/Contents\
/SharedSupport/Developer/Library/Xcode/Plug-ins/

For Xcode 4.x it can alternatively be installed at

/Library/Application Support/Developer/Shared/Xcode/Plug-ins/

In your XCode project under "Other Warning Flags" remove the -Wmost option (if needed).
You should now be able to select GCC 4.8 or GCC 4.9 from the compiler pop-up menu and compile code using that compiler.
Note that this approach fails in El Capitan with XCode 7.x and fails when trying to link to the xerces library installed in its default location. One way to compile in El Capitan with XCode 7.x is:
- Install GCC 4.9
- Go to /opt/local/lib/gcc49 and create a symbolic link to the xerces library using:
```
ln -s /usr/local/lib/libxerces-c-3.1.dylib libxerces-c-3.1.dylib 
```
  Note that the symbolic link is to a versioned xerces file and not the standard libxerces-c.dylib because linking to this link did not work. Because the xerces version is hard coded into the name, you will need to update when xerces is changed or alter the "3.1" if using a different version now. Although it should be possible to set Library Search Paths instead of creating this link, I could not get that approach to work, while the link did work.
- Make sure to select compiler GCC 4.9 in XCode
- Add -fopemp to "Other C++ Flags" to make sure it is compiled with OpenMP

The second approach is to build the plug in yourself (this approach can also be used to customize the plug ins downloaded above). The details (from Hammad's blog 1 and blog 2) are as follows (and for GCC 4.9 or newer, replace all uses of 4.8 with the desired version):

For XCode 4.x, copy a current compiler plug in into to a /Library level plug in folder:

Go to XCode's plug-ins folder, which is in the application package:

cd /Applications/Xcode.app/Contents/PlugIns/Xcode3Core.ideplugin/Contents\
/SharedSupport/Developer/Library/Xcode/Plug-ins

Create a copy of "GCC 4.2.xcplugin", put it in the Xcode plugin folder (create that folder if needed), and go to its contents:

sudo mkdir -p "/Library/Application Support/Developer/Shared/Xcode/Plug-ins/"
sudo cp -r "GCC 4.2.xcplugin" "/Library/Application Support/Developer/Shared\
/Xcode/Plug-ins/GCC 4.8.xcplugin"
cd "/Library/Application Support/Developer/Shared/Xcode/Plug-ins/GCC 4.8.xcplugin/Contents"

For XCode 5.x and newer you have to either download the plug in (see above) or copy the one mentioned in the previous step from a copy of XCode 4.x. Once copied, in must be installed in the new XCode app instead of the folder in the previous step. The correct folder is
```
/Applications/Xcode.app/Contents/PlugIns/Xcode3Core.ideplugin/Contents\
/SharedSupport/Developer/Library/Xcode/Plug-ins
```
Once copied to that folder, navigate to the contents of the plug in:
```
cd /Applications/Xcode.app/Contents/PlugIns/Xcode3Core.ideplugin/Contents\
/SharedSupport/Developer/Library/Xcode/Plug-insGCC 4.8.xcplugin/Contents
```
Using Terminal app inside the plug in, convert the binary plist into text xml and then open for editing (done with vi here, but could use another tool):
```
sudo plutil -convert xml1 Info.plist
sudo vi Info.plist
```

Make the following changes:

"com.apple.xcode.compilers.gcc.42" -> "com.apple.xcode.compilers.gcc.48"
"GCC 4.2 Compiler Xcode Plug-in" -> "GCC 4.8 Compiler Xcode Plug-in"

Save and convert Info.plist back to binary:

sudo plutil -convert binary1 Info.plist

In the "Resources" folder rename two files:

cd Resources/
sudo mv GCC\ 4.2.xcspec GCC\ 4.8.xcspec
cd English.lproj/
sudo mv GCC\ 4.2.strings GCC\ 4.8.strings

Open the "GCC 4.8.xcspec" for editing (e.g., using sudo vi) and make the changes:

Identifier = "com.apple.compilers.gcc.4_8";
Name = "GCC 4.8";
Description = "GNU C/C++ Compiler 4.8";
Version = "4.8";
ExecPath = "gcc-mp-4.8";
ShowInCompilerSelectionPopup = YES;
IsNoLongerSupported = NO;

Down further in that file, make the following changes:

under Name = "GCC_ENABLE_PASCAL_STRINGS"; set DefaultValue = NO;
under Name = "GCC_CW_ASM_SYNTAX"; set DefaultValue = NO;

Make other customizations, if desired.
In your Xcode project under "Other Warning Flags" remove the -Wmost option (if needed).
You should now be able to select GCC 4.8 from the compiler pop-up menu and compile code using that compiler.