#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the Common Development
# and Distribution License Version 1.0 (the "License").
#
# You can obtain a copy of the license at
# http://www.opensource.org/licenses/CDDL-1.0.  See the License for the
# specific language governing permissions and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each file and
# include the License file in a prominent location with the name LICENSE.CDDL.
# If applicable, add the following below this CDDL HEADER, with the fields
# enclosed by brackets "[]" replaced with your own identifying information:
#
# Portions Copyright (c) [yyyy] [name of copyright owner]. All rights reserved.
#
# CDDL HEADER END
#

#
# Copyright (c) 2013--2017, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ryan S. Elliott
#    Ellad B. Tadmor
#

#
# Release: This file is part of the kim-api-v1.8.1 package.
#


============================= The KIM API package ===========================--

This file contains instructions for installing the KIM API package.  If you are
new to KIM and the KIM API (application programming interface) start by reading
the README file in this directory.


TABLE OF CONTENTS

A. System requirements

B. Quick start

C. Package layout and operation overview
   C.1 Build types
       C.1.1 Installed-build
       C.1.2 Inplace-build
   C.2 Model and Model Driver collections
       C.2.1 The system-collection
       C.2.2 The user-collection
       C.2.3 The environment-variable-collection
       C.2.4 The CWD-collection

D. KIM API Installation scenario recipes
   D.1 Installed-build
       D.1.1 Installed-(standard)-build
       D.1.2 Installed-(nonstandard)-build
   D.2 Inplace-build

E. Adding Models and/or Model Drivers to the collections
   E.1 Adding Models and/or Model Drivers to the system-collection
   E.2 Setting up and adding Models and/or Model Drivers to the user-collection
       E.2.1 Setting up the user-collection
       E.2.2 Adding Models and Model Drivers to the user-collection
   E.3 Adding Models and/or Model Drivers to the environment-variable-collection
   E.4 Adding Models and/or Model Drivers to the CWD-collection

F. Advanced documentation for KIM API build and install process
   F.1 The Makefile.KIM_Config file
   F.2 Make targets defined by the top level KIM API Makefile
   F.3 Advanced details of the installation process

-------------------------------------------------------------------------------

A. SYSTEM REQUIREMENTS


To install the KIM API package you need the following:

1. A Unix/Linux/Mac OSX/Cygwin system.

2. GNU make (3.81 or later).

3. GNU compilers (gcc, g++, gfortran) version 4.2.x or higher or the
   corresponding Intel compilers, version 11.1 or higher.  NOTE: gfortran 4.6.x
   is known to have subtle bugs, and SHOULD NOT BE USED with the KIM API
   software package.

4. Standard utilities: xxd, ar, printf, sed, grep, find, cat, test, cp, touch,
   rm, rmdir, ln, chmod, install (needed for use in the build system).

5. wget and tar (needed for use with the `make add-<...>' build targets).

-------------------------------------------------------------------------------

B. QUICK START: For those who don't like to read and are a bit audacious.


Jump directly to sections D.1 or D.2.

If you have any problems with the commands found there, please read the rest of
this file.  If, however, you have successfully installed the KIM API and you
would like to learn more, read the README file in the docs directory for a
step-by-step guide to learning more about the KIM API.

-------------------------------------------------------------------------------

C. PACKAGE LAYOUT AND OPERATION OVERVIEW


The KIM API package is a system-level library that aims to give computer
programmers the ability to write atomistic or molecular simulation programs
that can seamlessly interface with implementations of interatomic models,
regardless of the programming language in which the codes are written.

C.1. BUILD TYPES

The KIM API package consists of a main library and a small number of associated
helper executables.  The KIM API can be built and used in one of two modes of
operation:  "installed-build" or "inplace-build".

C.1.1 INSTALLED-BUILD

This build type comes in two flavors: installed-(standard)-build and
installed-(nonstandard)-build.  These two flavors are identical except for
where the KIM API is installed within the system's file system.

The KIM API package is designed to be installed to a standard system-wide
directory ("/usr/local", by default, but "/" or "/usr" are also standard
locations) with its libraries placed in /usr/local/lib, header files placed
in /usr/local/include, and binaries placed in /usr/local/bin.  If you do
not have root access to your system, the KIM API may be installed to the
standard directories (${HOME}/local/lib, ${HOME}/local/include, and
${HOME}/local/bin, respectively) within your user account home directory.  Of
course, if you prefer to install the KIM API elsewhere, there are settings that
will allow you to do so.  Once the KIM API is installed, the package source
code directories are no longer needed and should be removed in order to keep
your system tidy.

With the KIM API successfully installed on your system, it is possible to build
KIM-Compliant Simulators (such as molecular dynamics programs) against the
KIM API library.  Each such Simulator has its own build instructions that should
be followed in order to build it with KIM API support enabled.

C.1.2 INPLACE-BUILD

This build type allows for the use of the KIM API package directly from the
package source code directories.  This type of usage is primarily for initial
evaluation and testing of the package.  It is not meant to be used as a
permanent alternative to the installed-build described above.

For inplace-build, the KIM API source code is compiled and setup so that you
can run the example Simulator codes with the example models.  This is also a
good way to explore the example source code and learn about the KIM API.

It is possible to build other KIM-Compliant Simulators against an inplace-build
of the KIM API.  This may involve nothing more than adding the
kim-api-vX.Y.Z/src/utils directory to you PATH.  However, using an
installed-build is preferred.

C.2 MODEL AND MODEL DRIVER COLLECTIONS

When compiled with the KIM_LINK option (see section H.1) set to its default
value of "dynamic-load", a build of the KIM API supports four "collections" of
Models and Model Drivers.  These are the "system-collection", the
"user-collection", the "environment-variable-collection", and the
"CWD-collection" as described below.  If the KIM_LINK option is set to
"static-link" a build of the KIM API supports only the system-collection.

When the KIM API needs to use a particular Model or Model Driver, it looks for
the Model by name, first in the CWD-collection, then in the
environment-variable-collection, then in the user-collection, and finally in
the system-collection.  It uses the first match that it finds.  Note, it is
possible for a Model and its Driver to be located in different collections.
The search for each is a separate and independent procedure.

C.2.1 THE SYSTEM-COLLECTION

The system-collection is a collection of Models and Model Drivers that are
available to all Simulators that use the KIM API library.  This collection is
located in the same subdirectory as the KIM API main library.  The
system-collection may be populated with Models and Model Drivers during the
initial build of the KIM API and it is installed along with the rest of the KIM
API package files during the install process.

Additional Models and Model Drivers may be built and installed to the
system-collection at anytime after an installed-build of the KIM API has been
completed and the original KIM API package source code directories have been
deleted.  However, if the KIM_LINK option was set to "static-link" for the KIM
API build, then the system-collection may not be modified after its initial
installation.

C.2.2 THE USER-COLLECTION

The user-collection is a collection of Models and Model Drivers that are
available only to the system user who owns the process for the Simulator that
uses the KIM API library.  This collection is located in a subdirectory
location that is set by a configuration file in the user's home directory.  The
user-collection may be populated with Models and Model Drivers after an
installed-build of the KIM API has been completed.

C.2.3 THE ENVIRONMENT-VARIABLE-COLLECTION

The environment-variable-collection is a collection of Models and Model Drivers
that are specified by the run-time environment of the process for the Simulator
that uses the KIM API library.  The locations of this collection are specified
by the environment variables "KIM_API_MODELS_DIR" and
"KIM_API_MODEL_DRIVERS_DIR".  These variables should contain colon ':'
separated lists of absolute directory names where the collection Models and
Model Drivers, respectively, are located.  (For example, in bash you could
execute the command

$ export KIM_API_MODELS_DIR=/my-kim-stuff/models-i-am-developing:/my-kim-stuff/misc-models

to have the KIM API look for Models in /my-kim-stuff/models-i-am-developing
first and then look in /my-kim-stuff/misc-models.  Similarly for Model
Drivers.)  The environment-variable-collection may be populated with Models and
Model Drivers after an installed-build of the KIM API has been completed.


C.2.4 THE CWD-COLLECTION

The CWD-collection is a collection of Models and Model Drivers that are
available to a Simulator at run-time.  The collection is located in the
Simulator process's current working directory (CWD).  The CWD-collection may be
populated with Models and Model Drivers after an installed-build of the KIM API
has been completed.

-------------------------------------------------------------------------------

D. KIM API INSTALLATION SCENARIO RECIPES


D.1 INSTALLED-BUILD

In this scenario the KIM API is built and installed and the system-collection
is populated with a single Model and its associated Model Driver, both from
openkim.org.  Additionally, one of the example Simulators is copied to the
user's home directory and used to test the installed-build.  If you need
special settings, see `./configure --help` and section H.1 for details about
the KIM API build settings.  The commands given below are for the bash shell.

We'll detail the two flavors: installed-(standard)-build and
installed-(nonstandard)-build.

D.1.1 INSTALLED-(STANDARD)-BUILD

To create an installed-(standard)-build and install to the default directory
"/usr/local" do the below.  Here we assume that "/usr/local/bin" is included as
part of the system's standard PATH setting.

$ cd "${HOME}"
$ wget https://s3.openkim.org/kim-api/kim-api-vX.Y.Z.tgz  # replace X.Y.Z with the current version number
$ tar zxvf kim-api-vX.Y.Z.tgz
$ cd kim-api-vX.Y.Z
$ ./configure
$ make add-EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001
$ make
$ sudo make install
$ sudo make install-set-default-to-vX  # replace X with the major version of this package
$ sudo ldconfig  # on Redhat-like systems you may need to first add /usr/local/lib to /etc/ld.so.conf
$ cp -r ./examples/openkim_tests/vc_forces_numer_deriv "${HOME}/"
$ cd "${HOME}"
$ rm -r kim-api-vX.Y.Z  kim-api-vX.Y.Z.tgz # replace X.Y.Z with the current version number
$ cd vc_forces_numer_deriv
$ make
$ printf "EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001" | ./vc_forces_numer_deriv

Congratulations, you have now successfully installed the KIM API.  If you would
like to learn more about the KIM API, read the README file in the docs
directory for a step-by-step guide.

D.1.2 INSTALLED-(NONSTANDARD)-BUILD

To create an installed-(nonstandard)-build and install to the user's home
directory "${HOME}/local" do the below.  Here we will add a line to the user's
.bashrc file that puts "${HOME}/local/bin" on the user's PATH setting.

$ cd "${HOME}"
$ wget https://s3.openkim.org/kim-api/kim-api-vX.Y.Z.tgz  # replace X.Y.Z with the current version number
$ tar zxvf kim-api-vX.Y.Z.tgz
$ cd kim-api-vX.Y.Z
$ ./configure --prefix=${HOME}/local
$ make add-EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001
$ make
$ make install
$ make install-set-default-to-vX  # replace X with the major version of this package
$ cp -r ./examples/openkim_tests/vc_forces_numer_deriv "${HOME}/"
$ cd "${HOME}"
$ rm -r kim-api-vX.Y.Z kim-api-vX.Y.Z.tgz  # replace X.Y.Z with the current version number
$ printf "PATH=${PATH}:${HOME}/local/bin\n" >> "${HOME}/.bashrc"
$ source "${HOME}/.bashrc"
$ cd vc_forces_numer_deriv
$ make
$ printf "EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001" | ./vc_forces_numer_deriv

Congratulations, you have now successfully installed the KIM API.  If you would
like to learn more about the KIM API, read the README file in the docs
directory for a step-by-step guide.

D.2 INPLACE-BUILD

In this scenario the KIM API is built inplace and the system-collection is
populated with a single Model and its associated Model Driver, both from
openkim.org.  Additionally, the example Models, Model Drivers, and Simulators
are built and used to test the inplace-build.  This scenario uses the default
settings, which are appropriate for most 64bit Linux systems.  If you need
different settings, see section H.1 for details about the KIM API build
settings.  The commands given below are for the bash shell.

$ cd "${HOME}"
$ wget https://s3.openkim.org/kim-api/kim-api-vX.Y.Z.tgz  # replace X.Y.Z with the current version number
$ tar zxvf kim-api-vX.Y.Z.tgz
$ rm kim-api-vX.Y.Z.tgz
$ cd kim-api-vX.Y.Z  # replace X.Y.Z with the package version number
$ ./configure
$ make add-EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001
$ make
$ make examples
$ cd ./examples/openkim_tests/ex_test_Ar_free_cluster_CLUSTER_F03
$ printf "ex_model_Ar_P_MLJ_CLUSTER_C" | ./ex_test_Ar_free_cluster_CLUSTER_F03

(See the README files in the examples/openkim_tests/* directories for an
explanation of what the Tests do.)

$ cd ../vc_forces_numer_deriv
$ printf "EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001" | ./vc_forces_numer_deriv

Congratulations, you have now successfully installed the KIM API.  If you would
like to learn more about the KIM API, read the README file in the docs
directory for a step-by-step guide.

-------------------------------------------------------------------------------

E. ADDING MODELS AND/OR MODEL DRIVERS TO THE COLLECTIONS


Here we describe how to add Models and/or Model Drivers to the
system-collection, user-collection, environment-variable-collection, and the
CWD-collection.

E.1 ADDING MODELS AND/OR MODEL DRIVERS TO THE SYSTEM-COLLECTION

Once you have an installed-build, it is easy to add additional Models and/or
Model Drivers to the system-collection.  Here we will demonstrate how to add
a Model that requires a Model Driver, so we first install the Driver and then
the Model.  We'll assume an installed-(standard)-build.

$ cd "${HOME}"
$ kim-api-build-config --makefile-kim-config > ./Makefile.KIM_Config
$ md=Pair_Morse_Shifted__MD_552566534109_001
$ wget --content-disposition "https://openkim.org/download/${md}.tgz"
$ tar zxvf "${md}.tgz"
$ cd "${md}"
$ make
$ sudo make install
$ cd "${HOME}"
$ rm -r "${md}" "${md}.tgz"

$ cd "${HOME}"
$ kim-api-build-config --makefile-kim-config > ./Makefile.KIM_Config
$ mo=Pair_Morse_Shifted_Jelinek_Ar__MO_831902330215_001
$ wget --content-disposition "https://openkim.org/download/${mo}.tgz"
$ tar zxvf "${mo}.tgz"
$ cd "${mo}"
$ make
$ sudo make install
$ cd "${HOME}"
$ rm -r "${mo}" "${mo}.tgz"

$ cd "${HOME}/vc_forces_numer_deriv"  # we'll assume this is already built
$ printf "Pair_Morse_Shifted_Jelinek_Ar__MO_831902330215_001" | ./vc_forces_numer_deriv

* NOTE: for Parameterized Models, such as ${mo}, you must install and
        delete the associated Model Driver before installing the Model,
        as we have done above.

E.2 SETTING UP AND ADDING MODELS AND/OR MODEL DRIVERS TO THE USER-COLLECTION

E.2.1 SETTING UP THE USER-COLLECTION

The user-collection of Models and Model Drivers is stored in a user
configurable location (actually one location for Models and one location for
Model Drivers, although these can, in fact, be the same).  The user
configuration file is "${HOME}/.kim-api/config-vX". (Here, X is the major
version number.)  Alternatively, the user configuration file can be specified
by the environment variable KIM_API_USER_CONFIG_FILE.  (For example, in bash
you could execute the command

$ export KIM_API_USER_CONFIG_FILE=/my-kim-stuff/config-file

to have the KIM API look in /my-kim-stuff/config-file for the user-collection
configuration values as described below.)  The environment variable, if set,
takes precedence over the standard file name.

The user configuration file has a strict format.  It must contain exactly two
lines.  These must be of the form:

  model_drivers_dir = XXX
  models_dir = YYY

where XXX and YYY are replaced by paths (beginning with `/' or `~/' only) which
indicate where you will store your Model Drivers and Models, respectively.

The following commands will set up a user-collection with Models and Model
Driver directories under "${HOME}/local/my-user-collection".  (Below, remember
to change the X in "config-vX" to the major version number.)

$ cd "${HOME}"
$ mkdir .kim-api
$ cd .kim-api
$ printf "model_drivers_dir = ~/local/my-user-collection/model_drivers\n" > config-vX
$ printf "models_dir = ~/local/my-user-collection/models\n" >> config-vX
$ cd "${HOME}/local"
$ mkdir my-user-collection
$ cd my-user-collection
$ mkdir model_drivers
$ mkdir models
$ kim-api-build-config --makefile-kim-config > ./model_drivers/Makefile.KIM_Config
$ kim-api-build-config --makefile-kim-config > ./models/Makefile.KIM_Config
$ cd "${HOME}"

E.2.2 ADDING MODELS AND MODEL DRIVERS TO THE USER-COLLECTION

The process for adding Models and Model Drivers to the user-collection involves
just downloading and building the items.  Here, we'll illustrate the process
with an example, using the setup described in the above section E.2.1.

$ umd="${HOME}/local/my-user-collection/model_drivers"
$ md=Pair_Lennard_Jones_Shifted__MD_498634107543_001
$ cd "${umd}"
$ wget --content-disposition "https://openkim.org/download/${md}.tgz"
$ tar zxvf "${md}.tgz"
$ cd "${md}"
$ make
$ cd ../
$ rm "${md}.tgz"

$ umo="${HOME}/local/my-user-collection/models"
$ mo=Pair_Lennard_Jones_Shifted_Bernardes_HighCutoff_Ar__MO_242741380554_001
$ cd "${umo}"
$ wget --content-disposition "https://openkim.org/download/${mo}.tgz"
$ tar zxvf "${mo}.tgz"
$ cd "${mo}"
$ make
$ cd ../
$ rm "${mo}.tgz"

$ cd "${HOME}/vc_forces_numer_deriv"  # we'll assume this is already built
$ printf "Pair_Lennard_Jones_Shifted_Bernardes_HighCutoff_Ar__MO_242741380554_001" | ./vc_forces_numer_deriv

E.3 ADDING MODELS AND/OR MODEL DRIVERS TO THE ENVIRONMENT-VARIABLE-COLLECTION

The process for adding Models and Model Drivers to the
environment-variable-collection involves just downloading and building the
items.  Here, we'll illustrate the process with an example.

$ mkdir -p "${HOME}/my-env-collection/model_drivers"
$ export KIM_API_MODEL_DRIVERS_DIR="${HOME}/my-env-collection/model_drivers"
$ md=Pair_Morse_Shifted__MD_552566534109_001
$ cd "${KIM_API_MODEL_DRIVERS_DIR}"
$ wget --content-disposition "https://openkim.org/download/${md}.tgz"
$ tar zxvf "${md}.tgz"
$ cd "${md}"
$ make
$ cd ../
$ rm "${md}.tgz"

$ mkdir -p "${HOME}/my-env-collection/models"
$ export KIM_API_MODELS_DIR="${HOME}/my-env-collection/models"
$ mo=Pair_Morse_Shifted_GirifalcoWeizer_HighCutoff_Cu__MO_151002396060_001
$ cd "${KIM_API_MODELS_DIR}"
$ wget --content-disposition "https://openkim.org/download/${mo}.tgz"
$ tar zxvf "${mo}.tgz"
$ cd "${mo}"
$ make
$ cd ../
$ rm "${mo}.tgz"

$ cd "${HOME}/vc_forces_numer_deriv"  # we'll assume this is already built
$ printf "Pair_Morse_Shifted_GirifalcoWeizer_HighCutoff_Cu__MO_151002396060_001" | ./vc_forces_numer_deriv

E.4 ADDING MODELS AND/OR MODEL DRIVERS TO THE CWD-COLLECTION

The process for adding Models and Model Drivers to the CWD-collection involves
just downloading and building the items.  Here, we'll illustrate the process
with an example.

$ cd "${HOME}/vc_forces_numer_deriv"  # we'll assume this is already built
$ kim-api-build-config --makefile-kim-config > ./Makefile.KIM_Config
$ mo=Pair_Exp6_Hogervorst_Mixing_Kong_Chakrabarty_ArNe__MO_946046425752_001
$ wget --content-disposition "https://openkim.org/download/${mo}.tgz"
$ tar zxvf "${mo}.tgz"
$ cd "${mo}"
$ make
$ cd ../
$ rm "${mo}.tgz"
$ printf "Pair_Exp6_Hogervorst_Mixing_Kong_Chakrabarty_ArNe__MO_946046425752_001" | ./vc_forces_numer_deriv

-------------------------------------------------------------------------------

F. ADVANCED DOCUMENTATION FOR KIM API BUILD AND INSTALL PROCESS


F.1. THE Makefile.KIM_Config FILE

Here we describe the process of creating the configuration settings for the KIM
API build, which are contained in the Makefile.KIM_Config file.  This is
usually done by the `configure' script.  However, it may also be done by hand
if necessary.

(a) Copy the file `Makefile.KIM_Config.example' to `Makefile.KIM_Config'.
    For example, if you untarred the `kim-api-vX.Y.Z.tgz' tarball in your
    home directory, you would do:

    $ cd ${HOME}/kim-api-vX.Y.Z
    $ cp Makefile.KIM_Config.example Makefile.KIM_Config

    (Above `vX.Y.Z' represents the current version number.)

(b) Edit the file Makefile.KIM_Config and set the appropriate value for the
    KIM_DIR variable.  This must expand to an absolute path.  Using the same
    assumptions as in (a), this would be

    KIM_DIR = $(HOME)/kim-api-vX.Y.Z

(c) Set the value of KIM_COMPILERSUITE.
    Possible values are `GCC' and `INTEL'.

    KIM_COMPILERSUITE = GCC

(d) Set the value of KIM_SYSTEMLINKER.
    Possible values are `linux', `freebsd', and `darwin'.

    KIM_SYSTEMLINKER = linux

(e) Set the value of KIM_SYSTEMARCH.
    Possible values are `32bit' and `64bit'.

    KIM_SYSTEMARCH = 64bit

(f) Set the value of KIM_LINK.
    Possible values are `dynamic-load' and `static-link'.

    KIM_LINK = dynamic-load

    `dynamic-load' is the default and preferred setting.  (Unless performance
    or other issues require it, you should use dynamic-load.)  `static-link'
    only works with ONE Model and AT MOST ONE Model Driver (in order to avoid
    the possibility of symbol clashes).  This setting is designed for use in
    production runs on massively parallel computing systems where the use of
    dynamic libraries may have a significant negative impact on run times.

    * NOTE: When using the static-link setting the entire KIM API must be
            recompiled in order to make changes to the system-collection.  This
            is not the case for the dynamic-load setting.

(g) Set the value of KIM_BUILD_VERBOSITY, if a value other than the default
    (`quiet') is desired.  Possible values are `quiet' and `full'.

    KIM_BUILD_VERBOSITY = quiet

    * NOTE: Alternatively you can override this variable's setting from the
            command line as you invoke make:

      $ make KIM_BUILD_VERBOSITY=full

(h) Override default compiler options and other variables, if necessary, by
    adding the desired variable name (after the "# override default compiler
    options and other variables here" line) and filling in appropriate
    values.


    # override default compiler options and other variables here

    # override default compiler executable names and settings
    CC =
    CXX =
    FC =
    LD =

    # override default compiler option flag lists
    FFLAGS   =
    CFLAGS   =
    CXXFLAGS =
    LDFLAGS  =
    LDLIBS   =


    * NOTE: GCC 4.4 requires that LDLIBS be set as
            `LDLIBS = -lgfortran -lgfortranstart' or possibly
            `LD = $(FC)' and `LDLIBS = -lstdc++'.

    * NOTE: As of 2014-01-20, gfortran on Darwin OS (Mac OSX) has a bug
            associated with the use of iso_c_binding Fortran/C
            interoperability features which are now standard in KIM API.
            (See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=59888 for
            details.)  We have reported this bug and are awaiting its fix.
            In the meantime, the following workaround has been identified:

            (1) You must have a "multi-library" version of gfortran
                installed on your mac due the need (see (2) below) to
                build for a 32bit architecture.  This means that GCC must
                have been configured with the "--enable-multilib" flag.  To
                check your version execute `gfortran -v' and look for the
                string "--enable-multilib".  In order to install a multilib
                version of gfortran on your mac you can use a package
                manager such as Homebrew, Mac Ports, or fink.  Follow the
                instructions for installing the package manager of your
                choice.  Then execute the command to install gfortran.

                For Homebrew the command is:
                  $ brew install gcc

                For Mac Ports the command is:
                  $ sudo port install gcc48 +universal
                  $ sudo port select --set gcc mp-gcc48
                  (Note, this may require that you build the package from
                   source in order to get the correct version.)

            (2) You must build the KIM API and associated Model Drivers,
                Models, and examples using the `KIM_SYSTEMARCH = 32bit'
                setting.

            (3) If appropriate, make sure the build system uses the brew
                installed compilers
                  `CC = gcc-4.8'
                  `CXX = g++-4.8'

            (4) You need to have the following line in this section of the
                Makefile.KIM_Config file in order to avoid harmless compiler
                errors:
                  `LDFLAGS += -read_only_relocs suppress'

    * NOTE: For Cygwin systems add the following line `PICFLAG =' to avoid
            warnings about the -fPIC option.

(i) Override default name options, if necessary, by adding the desired variable
    name (after the "# override default name options" line) and filling in
    appropriate values.

    # override default name options
    package_name =               # default is 'kim-api'
    user_config_file_dir_name =  # default is '.$(package_name)'


    * NOTE: The package_name variable is used as part of the installation
            directory name and the KIM API library file name.

    * NOTE: The KIM API library will look for the user-collection configuration
            file in the directory '${HOME}/${user_config_file_dir_name}'

(i) Override default install options, if necessary, by adding the desired
    variable name (after the "# override default install options" line) and
    filling in appropriate values.

    # override default install options
    prefix =       # default is '/usr/local'
    includedir =   # default is '$(prefix)/include'
    exec_prefix =  # default is '$(prefix)'
    libdir =       # default is '$(exec_prefix)/lib'
    bindir =       # default is '$(exec_prefix)/bin'


    * NOTE: See item F.3 below for more details on the installation process.

    * NOTE: See the GNU Coding Standards, Section 7.2 for more details on
            the meaning of the remaining standard variables.

    * NOTE: Staged installs are supported via the DESTDIR variable.  See
            Section 7.2.4 of the GNU Coding Standards.

F.2 MAKE TARGETS DEFINED BY THE TOP LEVEL KIM API Makefile

The targets defined by the top level KIM API Makefile include:

TARGETS FOR BUILDING AND CLEANING THE KIM API PACKAGE
`help'                       -- print this list of targets
`all'                        -- build the KIM API library and all "added"
                                Model Drivers and Models; same as `make'
`clean'                      -- delete appropriate .o, .mod, .a, .so and
                                executable files from src/ directory and
                                its subdirectories

TARGETS FOR MANIPULATING THE SYSTEM-COLLECTION AT BUILD TIME
`ls-all'                     -- list all "added" Model Drivers and Models
`ls-model-drivers'           -- list all "added" Model Drivers
`ls-models'                  -- list all "added" Models

`add-OpenKIM'                -- "add" all OpenKIM Model Drivers and Models
`add-<Extended KIM ID>'      -- "add" Model <Extended KIM ID> from OpenKIM
                                including the associated Model Driver, if
                                appropriate
`add-examples'               -- "add" example Model Drivers and Models

`rm-all'                     -- "rm" all "added" Model Drivers and Models
`rm-all-model-drivers'       -- "rm" all "added" Model Drivers
`rm-all-models'              -- "rm" all "added" Models
`rm-<Extended KIM ID>'       -- "rm" the "added" <Extended KIM ID> item
`rm-examples'                -- "rm" the "added" example Drivers and Models

TARGETS FOR INSTALLING THE KIM API PACKAGE
`install'                    -- install KIM API library, associated
                                executable utilities, and "added" Model
                                Drivers and Models to system-wide location
                                as described in item 7 below.
`install-set-default-to-vX'  -- create generic
                                $(includedir)/$(package_name) and
                                ${libdir}/${package_name} symlinks to the
                                corresponding $(package_name)-vX versions.
                                This effectively sets the "default"
                                library available for users on the system.

TARGETS FOR UNINSTALLING THE KIM API PACKAGE
`uninstall'                  -- delete files installed by `make install'
`uninstall-set-default'      -- remove the generic
                                $(includedir)/$(package_name) and
                                $(libdir)/$(package_name) symlinks.


TARGETS FOR BUILDING AND CLEANING THE EXAMPLES
`examples'                   -- build all provided examples
`examples-all'               -- same as `make examples'
`examples-clean'             -- delete appropriate .o, .mod, .a, .so and
                                executable files from examples/ directory
                                and its subdirectories

F.3 ADVANCED DETAILS OF THE INSTALLATION PROCESS

Upon `make install', the compiled versions of the KIM API library, associated
binary utilities, and the system-collection of Model Drivers and Models will be
copied to `$(libdir)/$(full_package_name)/'.  The bindir and includedir
directories are also populated.  The default values for libdir, bindir, and
includedir are `$(exec_prefix)/lib', `$(exec_prefix)/bin', and
`$(prefix)/include', respectively.  The default value for exec_prefix is
`$(prefix)', and the default value for prefix is `/usr/local'.  Thus, the
default values of libdir, bindir, and includedir are `/usr/local/lib',
`/usr/local/bin', and `/usr/local/include', respectively.  The value of
full_package_name is `$(package_name)-v$(VERSION_MAJOR)'.  Additionally the
supporting header and `.mod' files will be copied to
`$(libdir)/$(full_package_name)/include' to support subsequent compilation
against the installed KIM API package.

The following symbolic links are created to the content in
$(libdir)/$(full_package_name):

   $(bindir)/$(full_package_name)-build-config  ->  $(libdir)/$(full_package_name)/bin/$(full_package_name)-build-config
   $(bindir)/$(full_package_name)-descriptor-file-match  ->  $(libdir)/$(full_package_name)/bin/$(full_package_name)-descriptor-file-match
   $(includedir)/$(full_package_name)  ->  $(libdir)/$(full_package_name)/include
   $(libdir)/lib$(full_package_name).so  ->  $(libdir)/$(full_package_name)/lib$(full_package_name).so

If you want this version of the KIM API to be the default on your system (i.e.,
accessible via ${includedir}/${package_name} and
${libdir}/lib${package_name}.so), then do:

$ make install-set-default-to-vX

This will create the following symbolic links:

   $(bindir)/$(package_name)-build-config  ->  $(full_package_name)-build-config
   $(bindir)/$(package_name)-descriptor-file-match  ->  $(full_package_name)-descriptor-file-match
   $(bindir)/$(package_name)-collections-info  ->  $(full_package_name)-collections-info
   $(includedir)/$(package_name)  -> $(full_package_name)
   $(libdir)/$(package_name)  -> $(full_package_name)
   $(libdir)/lib$(package_name).so  ->  $(full_package_name).so

*******************************************************************************

SUPPORT

If you have problems or questions, send an email with your question and all
relevant information to

openkim@googlegroups.com

The members of the OpenKIM development team actively monitor this email list
and will do their best to help you with your question in a timely fashion.

*******************************************************************************
