.. _installation:

############
Installation
############

This section can be skipped if KPP is already installed on your system.

.. _installation-download:

========================
Download KPP from GitHub
========================

Clone the KPP source code from the `KPP GitHub repository
<https://github.com/KineticPreProcessor/KPP>`_:

.. code-block:: console

   cd $HOME
   git clone https://github.com/KineticPreProcessor/KPP.git

This will create a directory named :file:`KPP` in your home directory.

.. _installation-env-vars:

========================================
Define the KPP_HOME environment variable
========================================

Define the :envvar:`KPP_HOME` environment variable to point to the
complete path where KPP was cloned.  Also add the path of the KPP
executable to the :envvar:`PATH` environment variable.  These commands
may be placed in your shell startup file, as shown below.

.. important::

   The :file:`git clone` command above creates a directory named
   :file:`KPP` (uppercase).  Make sure that :envvar:`KPP_HOME` points
   to this exact directory name.  On case-sensitive Linux filesystems,
   :file:`KPP` and :file:`kpp` are **different** directories.


**If you use bash:**

   Add these statements to your :file:`$HOME/.bashrc` file:

   .. code-block:: bash

      export KPP_HOME=$HOME/KPP
      export PATH=$PATH:$KPP_HOME/bin

   Then apply the settings with:

   .. code-block:: console

      $ source $HOME/.bashrc

**If you use zsh (macOS Catalina and later)**

   Add these statements to your :file:`$HOME/.zshrc` file:

   .. code-block:: zsh

      export KPP_HOME=$HOME/KPP
      export PATH=$PATH:$KPP_HOME/bin

   Then apply the settings with:

   .. code-block:: console

      $ source $HOME/.zshrc


   .. important::

      macOS Catalina (2019) and later versions use :program:`zsh`
      as the default shell instead of :program:`bash`.  If you are
      using :program:`bash` on macOS, source :file:`~/.bash_profile`
      rather than :file:`~/.bashrc`, because macOS Terminal opens a
      login shell by default and login shells do not source
      :file:`~/.bashrc` automatically.  The safest approach is to
      add the following line to your :file:`~/.bash_profile`:

      .. code-block:: bash

         [ -f ~/.bashrc ] && source ~/.bashrc

**If you use csh or tcsh:**

   Add these statements to your :file:`$HOME/.cshrc` file:

   .. code-block:: csh

      setenv KPP_HOME $HOME/KPP
      setenv PATH ${PATH}:$KPP_HOME/bin

   Then apply the settings with:

   .. code-block:: console

      $ source $HOME/.cshrc

.. _installation-dependencies:

======================================
Test if KPP dependencies are installed
======================================

KPP depends on several other Unix/Linux packages.  Before using KPP
for the first time, test whether these are installed on your system.
If any packages are missing, you can install them with your system
package manager (e.g. :program:`apt` for Ubuntu, :program:`yum` for
Fedora, :program:`homebrew` for macOS) or with
`Spack <https://spack.readthedocs.io>`_.

.. _installation-gcc:

gcc
---

.. important::

   macOS users: please read :ref:`installation-macos-gcc` before
   proceeding.

KPP uses the `GNU Compiler Collection <https://gcc.gnu.org>`_
(:program:`gcc`) by default.  A version of :program:`gcc` comes
pre-installed with most Linux systems.  To test whether
:program:`gcc` is installed, type:

.. code-block:: console

   gcc --version

This will display version information such as:

.. code-block:: none

   gcc (GCC) 11.2.0
   Copyright (C) 2021 Free Software Foundation, Inc.
   This is free software; see the source for copying conditions.
   There is NO warranty; not even for MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE.

.. _installation-sed:

sed
---

The :program:`sed` utility searches for and replaces text in files.
To test whether :program:`sed` is installed, type:

.. code-block:: console

   which sed

This will print the path to :program:`sed` on your system.

.. _installation-bison:

bison
-----

The :program:`bison` utility parses the chemical mechanism file into
a computer-readable syntax.  To test whether :program:`bison` is
installed, type:

.. code-block:: console

   which bison

This will print the path to :program:`bison` on your system.

.. _installation-flex:

flex
----

.. important::

   macOS users: please read :ref:`installation-macos-flex` before
   proceeding.

The :program:`flex` (Fast Lexical Analyzer) utility creates a scanner
that recognizes the syntax generated by :program:`bison`.  To test
whether :program:`flex` is installed, type:

.. code-block:: console

   which flex

This will print the path to :program:`flex` on your system.

You will also need to specify the path to the :program:`flex` library
files (:file:`libfl.so` or :file:`libfl.a`) in order to build the KPP
executable.  Use the :program:`find` command to locate them:

.. code-block:: console

   find /usr/ -name "*libfl*" -print

This generates output similar to the following.  Look for the entry
containing :file:`libfl.`:

.. code-block:: none

   /usr/include/libflashrom.h
   /usr/lib/gthumb/extensions/libflicker.so
   /usr/lib/gthumb/extensions/libflicker_utils.so
   /usr/lib/libflashrom.so.1.0.0
   /usr/lib/libfl.so                # <---- This is the flex library file
   ... etc ...

Once you have located the directory containing the flex library file
(in this example :file:`/usr/lib`), define the
:envvar:`KPP_FLEX_LIB_DIR` environment variable in your shell startup
file as shown below.

**If you use bash:**

   Add this code to your :file:`~/.bashrc` file:

   .. code-block:: bash

      export KPP_FLEX_LIB_DIR=/usr/lib
      export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.bashrc

**If you use zsh:**

   Add this code to your :file:`~/.zshrc` file:

   .. code-block:: bash

      export KPP_FLEX_LIB_DIR=/usr/lib
      export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.zshrc

**If you use csh or tcsh:**

   Add this code to your :file:`~/.cshrc` file:

   .. code-block:: csh

      setenv KPP_FLEX_LIB_DIR /usr/lib
      setenv LD_LIBRARY_PATH  ${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.cshrc

KPP will use the path specified by :envvar:`KPP_FLEX_LIB_DIR`
in the following section.

.. _installation-build:

========================
Build the KPP executable
========================

Change to the :file:`KPP/src` directory:

.. code-block:: console

   cd $KPP_HOME/src

.. note::

   The following :program:`make clean` and :program:`make distclean`
   commands are only necessary if you have previously built KPP and
   wish to start from a clean state.  You can skip them on a fresh
   clone.

To remove previously-built KPP object files and example output:

.. code-block:: console

   make clean

To also remove a previously-built KPP executable:

.. code-block:: console

   make distclean

KPP uses :program:`gcc` as the default compiler.  If you would like
to use a different compiler (e.g. :program:`icc`), edit
:file:`src/Makefile.defs` to specify your compiler.

Create the KPP executable with:

.. code-block:: console

   make

You should see output similar to:

.. code-block:: none

   gcc -g -Wall -Wno-unused-function -I/usr/include -c code.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c code_c.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c code_f77.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c code_f90.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c code_matlab.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c debug.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c gen.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c kpp.c
   flex -olex.yy.c scan.l
   bison -d -o y.tab.c scan.y
   gcc -g -Wall -Wno-unused-function -I/usr/include -c lex.yy.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c scanner.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c scanutil.c
   gcc -g -Wall -Wno-unused-function -I/usr/include -c y.tab.c
   gcc -g -Wall -Wno-unused-function code.o code_c.o \
       code_f77.o code_f90.o code_matlab.o debug.o gen.o kpp.o \
       lex.yy.o scanner.o scanutil.o y.tab.o -L/usr/lib -lfl -o kpp

This creates the executable file :file:`$KPP_HOME/bin/kpp`.

To verify that the KPP executable is accessible, type:

.. code-block:: console

   which kpp

The path displayed should match :file:`$KPP_HOME/bin/kpp`.

.. note::

   This check must be performed **after** running :command:`make`.
   The executable does not exist before the build step completes.

.. _installation-macos:

==========================
Additional steps for macOS
==========================

When installing KPP on a macOS system, some additional configuration
steps are necessary.  The sections below address each one.

.. _installation-macos-gcc:

Force macOS to use the GNU gcc compiler
---------------------------------------

On macOS, the command:

.. code-block:: console

   gcc --version

will typically produce output similar to:

.. code-block:: none

   Apple clang version 13.1.6 (clang-1316.0.21.2.5)
   Target: x86_64-apple-darwin21.5.0
   Thread model: posix
   InstalledDir: /Library/Developer/CommandLineTools/usr/bin

This is because macOS installs :program:`clang` as :program:`gcc`.
Follow the steps below to make your shell use the GNU
:program:`gcc` compiler instead.

1. Install gcc with Homebrew
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

   brew install gcc

2. Determine which version of gcc was installed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

   ls $(brew --prefix gcc)/bin/ | grep "^gcc-"

You will see output such as:

.. code-block:: none

   gcc-13
   gcc-ar-13
   gcc-nm-13
   gcc-ranlib-13

This indicates that gcc version 13 was installed and that the
executable is named :file:`gcc-13`.  Your installed version may differ.

.. important::

   The version number returned by the command above may differ from
   the examples shown here.  Always use the actual version number
   found on your system in the steps that follow.

3. Define compiler settings in your shell startup file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following code block uses :command:`brew --prefix` to locate the
Homebrew installation directory automatically.  This works correctly
on both Intel Macs (:file:`/usr/local`) and Apple Silicon Macs
(:file:`/opt/homebrew`).

**If you use bash:**

   Add the following to your :file:`~/.bashrc` (or
   :file:`~/.bash_profile` if you do not have a
   :file:`~/.bashrc`):

   .. code-block:: bash

      #==================================================================
      # Compiler settings (macOS)
      #
      # Detect the gcc version installed by Homebrew and define
      # aliases and environment variables accordingly.
      # This overrides the Apple clang that macOS installs as gcc.
      #==================================================================
      _GCC_VER=$(ls "$(brew --prefix gcc)/bin/" \
                 | grep '^gcc-[0-9]' \
                 | grep -oP '[0-9]+$' \
                 | sort -n | tail -1)

      if [[ -n "${_GCC_VER}" ]]; then
          alias gcc="gcc-${_GCC_VER}"
          alias g++="g++-${_GCC_VER}"
          alias gfortran="gfortran-${_GCC_VER}"
          export CC="gcc-${_GCC_VER}"
          export CXX="g++-${_GCC_VER}"
          export FC="gfortran-${_GCC_VER}"
          export F77="gfortran-${_GCC_VER}"
      fi
      unset _GCC_VER

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.bashrc

**If you use zsh:**

   Add the following to your :file:`~/.zshrc`:

   .. code-block:: zsh

      #==================================================================
      # Compiler settings (macOS)
      #
      # Detect the gcc version installed by Homebrew and define
      # aliases and environment variables accordingly.
      # This overrides the Apple clang that macOS installs as gcc.
      #==================================================================
      _GCC_VER=$(ls "$(brew --prefix gcc)/bin/" \
                 | grep '^gcc-[0-9]' \
                 | grep -oE '[0-9]+$' \
                 | sort -n | tail -1)

      if [[ -n "${_GCC_VER}" ]]; then
          alias gcc="gcc-${_GCC_VER}"
          alias g++="g++-${_GCC_VER}"
          alias gfortran="gfortran-${_GCC_VER}"
          export CC="gcc-${_GCC_VER}"
          export CXX="g++-${_GCC_VER}"
          export FC="gfortran-${_GCC_VER}"
          export F77="gfortran-${_GCC_VER}"
      fi
      unset _GCC_VER

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.zshrc

4. Verify that your shell now recognizes the GNU gcc compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

   gcc --version

You should see output similar to:

.. code-block:: none

   gcc-13 (Homebrew GCC 13.2.0) 13.2.0
   Copyright (C) 2023 Free Software Foundation, Inc.
   This is free software; see the source for copying conditions.
   There is NO warranty; not even for MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE.

This confirms that your shell is using GNU :program:`gcc` rather
than :program:`clang`.

.. _installation-macos-flex:

Install and configure flex on macOS
------------------------------------

If your macOS system does not have the :program:`flex` library
installed, install it with Homebrew:

.. code-block:: console

   brew install flex

Unlike Linux package managers, which install the flex library files
under :file:`/usr/lib/`, Homebrew installs them under its own prefix
directory.

Define the :envvar:`KPP_FLEX_LIB_DIR` environment variable using
:command:`brew --prefix` so that the path is determined automatically
regardless of the Homebrew prefix or the installed flex version:

**If you use bash:**

   Add the following to your :file:`~/.bashrc` (or
   :file:`~/.bash_profile`):

   .. code-block:: bash

      export KPP_FLEX_LIB_DIR=$(brew --prefix flex)/lib
      export DYLD_LIBRARY_PATH="${DYLD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.bashrc

**If you use zsh:**

   Add the following to your :file:`~/.zshrc`:

   .. code-block:: zsh

      export KPP_FLEX_LIB_DIR=$(brew --prefix flex)/lib
      export DYLD_LIBRARY_PATH="${DYLD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"

   Then apply the changes with:

   .. code-block:: console

      $ source ~/.zshrc

.. note::

   macOS uses :envvar:`DYLD_LIBRARY_PATH` to locate shared libraries
   at runtime, not :envvar:`LD_LIBRARY_PATH` (which is the Linux
   equivalent).  If you find that :envvar:`DYLD_LIBRARY_PATH` is
   blocked by System Integrity Protection (SIP), you can instead force
   a hard link:

   .. code-block:: console

      brew link --force flex

.. _installation-macos-stack:

Request maximum stack memory
-----------------------------

macOS imposes a hard limit on stack memory of 65532 bytes, which is
considerably less than what is available on typical GNU/Linux systems.
To ensure that KPP uses the maximum available stack memory, add the
following line to your shell startup file:

**If you use bash:**

   Add this code to your :file:`~/.bashrc` file:

   .. code-block:: bash

      ulimit -s 65532

   Then apply the change with:

   .. code-block:: console

      $ source ~/.bashrc

**If you use zsh:**
      
   Add this code to your :file:`~/.zshrc` file:

   .. code-block:: zsh

      ulimit -s 65532

   Then apply the change with:

   .. code-block:: console

      $ source ~/.zshrc

This stack memory restriction means that KPP cannot parse mechanisms
with more than approximately 2000 equations and 1000 species.  To
account for this, the KPP header file :file:`src/gdata.h` defines the
:c:macro:`MAX_EQN` and :c:macro:`MAX_SPECIES` parameters conditionally:

.. code-block:: c

   #ifdef MACOS
   #define MAX_EQN        2000   // Max number of equations (macOS only)
   #define MAX_SPECIES    1000   // Max number of species   (macOS only)
   #else
   #define MAX_EQN       11000   // Max number of equations
   #define MAX_SPECIES    6000   // Max number of species
   #endif

If KPP cannot parse your mechanism you can adjust :c:macro:`MAX_EQN`
and :c:macro:`MAX_SPECIES` in :file:`src/gdata.h` and then rebuild
the KPP executable.

.. _installation-macos-case:

macOS is case-insensitive
--------------------------

.. warning::

   macOS uses a case-insensitive filesystem by default.  If your
   project contains two files whose names differ only in case (for
   example :file:`integrator.F90` and :file:`integrator.f90`), macOS
   will treat them as the same file.  This can cause build failures
   and unexpected behaviour when working with version control systems
   such as Git.  Ensure that no two files in your project share a
   case-insensitive name.