.. _detailed:

***************************************
Installing ChemShell: An Advanced Guide
***************************************

This section explains in more detail how ChemShell platform files are used
to help install ChemShell to known machines. The material here should be
helpful to write your own platform files or to help you modify them if
you are having issues installing ChemShell successfully.

Some default platform files are included in ``chemsh/utils/platforms``.
Please let us know if you run into any issues installing ChemShell 
on these platforms at the ChemShell forum (https://discourse.chemshell.org/).

Setup defaults
==============

The file ``setup.py`` is used to install ChemShell, in combination with command
line options and platform files.

In order to get detailed information on the available options, run the following command: ::

./setup.py --help

The output of this command is also documented here: :ref:`options`.

If you run ``./setup.py`` without further options, the present behavior is to 
attempt an Intel install with the Ubuntu platform file.

Platform files
==============

A platform file stores specific options to be passed to ``setup.py``. If you look
in a platform file you will see lines like the following: ::

  args.fc = "ifx"

This is equivalent to the following command: ::

  ./setup --fc="ifx"

Both these commands instruct ChemShell to use ``ifx`` as the Fortran compiler for the build.
The only difference between these two choices is that the value specified in the platform file
overwrites the setup option given by the user. If neither of these options is given the default
value given in ``setup.py`` will be used instead, which in version 23.0.1 is ``ifort``. 

The default values of setup arguments can also be modified by platform files in order to provide
more platform specific values: ::

  args.__setarg("fc", "ftn")

So for this example, the ``ftn`` compiler would be used, unless the user has given a specific
compiler option using the ``--fc`` flag which would then overwrite this value. Be aware that 
the default values given by ``setup.py --help``

As an example of both of these kinds of options, consider the ``ubuntu.py`` and ``archer2.py``
platform files. For Ubuntu systems, we are specifying defaults that might be helpful, but
want you to be able to set system specific options that match the configuration of your
system. For instance, we do not know what compilers you have chosen to install or where
these installations have been placed. In contrast, on ARCHER2, we have a known system
configuration and it will be much more challenging to build ChemShell with an alternative
compiler you have installed yourself. In this case, you would be better served by creating
your own platform file.

HPC platforms
=============

The main difference in installing ChemShell on HPC platforms is the need to load
modules before compiling. In order to ensure that the ChemShell script chemsh can 
load the correct modules when it is run, a platform file should be used in order
to specify the required modules to load and unload.

Troubleshooting
===============

When running into issues, there are a few points to be aware of:

- The build process uses CMake extensively, which does cache variables. Additionally, ChemShell
  will reuse shared objects that have been compiled previously. So if you change your setup variables,
  it is safer to start with a fresh install. There is also the option ``setup.py --clean``, but
  this might not always be reliable. Not all interface codes in ChemShell use CMake for their own build
  system, so resetting the CMake environment may not fully restore the state of the build.

- Changes in local configuration of the target machine can change the behavior of platform
  files. In particular, environment variables can have an effect.
 
- Intel is in the process of changing their compilers:
  ``ifort`` --> ``ifx``
  ``icc``   --> ``icx``
  This can create additional problems and some interface codes do not support the new compilers
  yet.

- At the moment (v25.0.0) it is not possible to link NWChem to ChemShell directly when using GNU compilers.