BBP on OS X Guide 16 5

From SCECpedia
Jump to navigationJump to search

Introduction

The Broadband Platform is compatible with Linux as well as OS X. However, due to some recent changes that Apple has made to their Xcode development tools, users on Mavericks (OS X 10.9) and later version (Yosemite (OS X 10.10), El Capitan (OS X 10.11.0)) will need to follow some additional steps to make the installation work. There are several installation issues or limitations related to the BBP on a Mac.

The key Mac OS X-specific issues include:

  1. Mac must have a gcc compiler environment, and the Mac command line tools, obtained through the Xcode software distribution available through the Mac App store.
  2. Mac must have a gfortran compiler installed, which is not available in the Mac Xcode distribution. We recommend use of a gnu Mac binary distribution of gfortran.
  3. Mac must have a full Python installation that includes NumPy, SciPy, matplotlib and other packages. We recommend use of a free commercial Python distribution called Anaconda, that includes all these required python libraries.
  4. Mac must have specialized Python language geographic project module, called pyproj, installed. The required pyproj can be installed using the Anaconda package update tool.
  5. The current SDSU BBToolbox software is not compatible with the Mac environment. The code will crash and as a result the SDSU method will not be tested by the Unit tests when compiled on a Mac. This is a known, Mac-specific issue. The SDSU method passes all tests in the target Linux environment. We will provide a resolution to this know limitation of the Mac-version of the BBP, as soon as one is available.

Installing BBP v16.5.0 on Mac OS X 10.11.5 (El Capitan)

This section describes the installation of the BBP 16.5.0 distribution on Mac OS X system. The following steps were tested on a Macbook Pro running Mac OS 10.11.5 (El Capitan).

The steps below will guide you through installation of the necessary C/Fortran GNU compilers in addition to the Python packages required by the Broadband Platform. At the end of this section, we provide information about running the Unit and Acceptance Tests available on the Broadband Platform, along with some Mac OS X-specific details.

The following steps will install the BBP v16.5.0 installation on a Mac running a new, default, installation of OS 10.11.5 (El Capitan). Some of these steps may not be required if you have already added compilers, or other libraries, to your Mac.

  1. Install Xcode from the Mac App Store.
  2. Install the Xcode command line tools.
  3. Install a gfortran compiler from the gnu site.
  4. Install a collection of Python libraries using the Continuum Anaconda distribution.
  5. Update a Python library, called pyproj, using Anaconda's conda install command.
  6. Install the Broadband Platform software and required libraries using the BBP easy install script.
  7. Update the .bash_profile in your user account
  8. Run the unit tests and acceptance tests to ensure the platform is working properly on your Mac.
  9. Use the Broadband Platform for your research purposes.

Step-by-Step Installation of BBP v16.50 on Mac OS

The following sections provide a step-by-step process for installing Broadband Platform v16.5.0 on Mac OS 10.11.5 (El Capitan). Several steps, including the installation of the Xcode compilers (gcc) and the fortran compilers (gfortran) require administrator access on the Mac. These instruction assume the account you are using has administrator privileges. If your Mac account does not have administrator privileges, you will need to modify some of the commands to include "sudo" commands. Those are not included here.

Install Xcode from the Mac App Store

Mac OS does not ship with compilers. However, the Mac App store provides a software distribution called Xcode that include current gcc compilers, and other tools, such as makefile system needed to build the BBP Platform. To download and install the Xcode distribution, you will need to go to the Mac App store, find the Xcode software, and install it on your Mac. This will required an Apple ID (free) and administrator privileges on your Mac.

Xcode is listed in the Mac App store under "developer tools". The current version that we tested with, as of May 2016 is Version 7.3.1 Please following apple instruction for downloading and installing the Xcode software. You will need to agree to Apple licenses. Once the Xcode is installed, you should open a Terminal window on your Mac and confirm the gcc compilers are installed and work by invoking the gcc compiler.

Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal)

If you type gcc -v in the terminal window, you should see something like the following: 

$ gcc -v
Using built-in specs.
COLLECT_GCC=gcc
COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/x86_64-apple-darwin14.0.0/4.9.2/lto-wrapper
Target: x86_64-apple-darwin14.0.0
Configured with: ../gcc-4.9-20141029/configure --enable-languages=c++,fortran
Thread model: posix
gcc version 4.9.2 20141029 (prerelease) (GCC)

Install the Xcode command line tools.

Not all required software tools are included in the default Xcode installation. To update the Xcode installation with the additional "command line" tools (free) needed by the Broadband Platform type the following:

Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal) Type xcode-select --install and respond to the the dialogs that open. These dialogs may ask you to agree to the apple license.

Install Fortran Compiler

Xcode does not include a fortran compiler which is required by the BBP platform software. We recommend that you download a Mac binary installation of the GFortran compiler from the GNU web site (free).

Selest the appropriate version of the Mac Fortran compiler from the following gnu website:

It should be possible to install the fortran from the gnu source code, but we have not tested this approach.

Once fortran is installed, you should open a terminal window, and type gfortran -v to verify the compiler is installed and working. To do this, in your Terminal window, if should look something like this 

$ gfortran -v
Using built-in specs.
COLLECT_GCC=gfortran
COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/x86_64-apple-darwin14.0.0/4.9.2/lto-wrapper
Target: x86_64-apple-darwin14.0.0
Configured with: ../gcc-4.9-20141029/configure --enable-languages=c++,fortran
Thread model: posix
gcc version 4.9.2 20141029 (prerelease) (GCC)

Install Python 2.7 Distribution

The BBP v16.5.0 requires Python v2.7+ and several optional python libraries. It is possible to collect all necessary Python libraries, but we recommend using a Python distribution that includes nearly all the required libraries. We recommend use of the Continuum Anaconda Python distribution (free).

Go to the Continuum Anaconda download site, and download the Python 2.7 command line distribution tool (free).

Once this is downloaded, run the installer by typing: 

% bash Anaconda2-4.0.0-MacOSX-x86_64.sh

It will ask you to agree to the license, and then install a current version of Python 2.7 and most of the Python libraries required by the BBP v16.5.0. Anaconda Python can be installed in your user directory and does not require administrator privileges.

The end of the installation process will update your .bash_profile to put the Anaconda Python into your default path. We tested using the Anaconda version given above, and it worked with BBP v16.5.0

Update the PyProj library in Anaconda Python

One Python package that must be updated to in the pyproj library. Use the Anaconda update tool. Open a terminal window and type: 

% conda install pyproj

The conda installer program will run, and it will identify what needs to be installed, or updated. When it asks for approval to proceed, enter yes. Pyproj will be added/updated to your Mac.

Install the Broadband Platform using the Easy Install Script

At this point, your Mac has all the software tools needed to install, compile and run the Broadband Platform. Please return to the Broadband Users Guide and follow the easy install instructions. Continue the installation instructions at Broadband Platform Easy Installation

Once the easy install process completes, users should run the Unit Tests and Acceptance tests to ensure the BBP v16.5.0 is installed and operating properly on your Mac, following instructions given on Broadband_User_Guide_v16.5.0#Running_the_Tests. When the Unit Tests and Acceptance tests pass on your computer, it provides evidence that the platform is properly installed and is producing results equivalent to the released version used for SCEC research purposes.

Additional information about the installation process is included on the Broadband Platform Manual Installation page.

Related Entries

Retrieved from "https://strike.scec.org/scecwiki/index.php?title=BBP_on_OS_X_Guide_16_5&oldid=16546"