.. -------------------------------------------------------------------------
.. pyCGNS - CFD General Notation System - 
.. See license.txt file in the root directory of this Python module source  
.. -------------------------------------------------------------------------

Build and Install
+++++++++++++++++

.. index::
   single: CHLone
   pair: Installation; Python
   pair: Installation; numpy
   pair: Installation; hdf5
   pair: Installation; CHLone

Required libraries
~~~~~~~~~~~~~~~~~~

The first step of the installation is to make sure you have the required
libraries. The mandatory libs are *Python*, *numpy*, *HDF5* and *CHLone*. 
Then, if you wan to build *CGNS.WRA* (we recommend to do so), you 
need *libcgns*.

.. warning::

  **OUPS !** you mean I don't need *libcgns* for the *CGNS/Python* mapping ?

  **NO** you don't, *CGNS* is a data model (so-called *CGNS/SIDS*) and some
  mapping definitions of this model (such as *CGNS/HDF* for example).
  *pyCGNS* uses *`CHLone <http://chlone.sourceforge.net>`_*
  which is another *CGNS/HDF5* compliant implementation.

* `Python <http://www.python.org>`_ (starting from v2.4)
* `numpy <http://numpy.scipy.org>`_ (v1.1 +)
* `hdf5 <http://www.hdfgroup.org>`_ (v1.8.5 +)
* `CHLone <http://chlone.sourceforge.net>`_ (v0.4 +)
* `tktreectrl <http://sourceforge.net/projects/tktreectrl>`_ (v2.2 +)

.. index::
   single: CGNS/MLL
   single: CGNS/ADF
   pair: Installation; CGNS/MLL

Optional libraries
~~~~~~~~~~~~~~~~~~
The so-called `mid-level` library is not mandatory, 
the :ref:`WRA module <wrainter:wraintro>`
is the only one to have dependancies on.
The :ref:`NAV module <navinter:navintro>` also uses *CGNS/MLL* as optional
if you want to be able to read *CGNS/ADF* files
(see :ref:`File formats <wrainter:v3multifileformat>`)

 * `CGNS/MLL (libcgns) <http://www.cgns.org>`_ (starting v3.0) 

Installation process
~~~~~~~~~~~~~~~~~~~~

Once you have these installed you can proceed with pyCGNS.
You go into the top directory and you edit the ``pyCGNSconfig.py.in``
(see :ref:`pycgnsconfigpyin`).
You have to set the correct paths and various values such as directory search
libs or flags.

.. index::
   single: Installation

Then you run::

  python setup.py build

and then::

  python setup.py install

or::

  python setup.py install --prefix=/local/tools/installation

All the modules of the pyCGNS package are installed and you can now
proceed with tutorial examples.

Single module installation
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can ask for a single module installation::

  python setup.py build --single-module=MAP
  python setup.py install

You have to check that this installation doesn't overwrite an existing
installation with the other pyCGNS modules.

.. _pycgnsconfigpyin:

Configuration file contents
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   pair: Installation; pyCGNSconfig_user.py

The ``pyCGNSconfig_user.py`` should work with no modification if you have
a standard installation. All you have to declare is the directory in which
we can find *Python/numpy/hdf5/CHLone/cgns* libraries.

If you have specific installations you can change some paths/flags for each
external library: *hdf5*, *numpy*, *CGNS/MLL* and *CHLone*. The configuration
file is a Python file, it is imported after the default configuration. The
changes you make in the configuration file will overwrite the defaults::

  # --- stuff to add for HDF5 

  #HDF5_VERSION          = ''
  HDF5_PATH_INCLUDES    = ['/home/myself/hdf5/include']
  HDF5_PATH_LIBRARIES   = ['/home/myself/hdf5/lib']
  #HDF5_LINK_LIBRARIES   = []
  #HDF5_EXTRA_ARGS       = []

To avoid overwriting, use Python to update the config::

  # --- stuff to add for HDF5 

  #HDF5_VERSION          = ''
  HDF5_PATH_INCLUDES    = ['/home/myself/hdf5/include']
  HDF5_PATH_LIBRARIES   = ['/home/myself/hdf5/lib']
  #HDF5_LINK_LIBRARIES   = []
  HDF5_EXTRA_ARGS       = HDF5_EXTRA_ARGS + ['-DMYFLAG']
  
Release Notes
-------------

 Many changes in this v4 release, you can only use MAP, WRA, PAT and NAV.
 The other modules, VAL, TRA and DAT are present for archival/development
 purpose but you should NOT use them.

 Please go to `http://www.python-science.org/projects/pyCGNS` to have the
 version/tickets list.

Module dependancies
-------------------

The pyCGNS modules have dependancies with their brothers. The list below
gives you the required modules (or optional) for each of them.

 - MAP : None
 - PAT : MAP
 - WRA : PAT MAP
 - APP : PAT MAP
 - NAV : PAT MAP APP (WRA)

NAV depends
~~~~~~~~~~~

The *TkTreectrl* module is required. You first need to install *tktreectrl*
(last version tested is *tktreectrl-2.3) and *TkinterTreectrl* to map it
to Python (last version tested is *TkinterTreectrl-1.0*).
You may have to add the *tktreectrl* path into a `TCLLIBPATH` shell
variable (maybe you should add a `LD_LIBRARY_PATH` as well).

MAP depends
~~~~~~~~~~~

The *CHLone* librarie is required and thus *HDF5* is required.

WRA depends
~~~~~~~~~~~

*CGNS/MLL* and *CGNS/ADF* libraries are required.
You should build the CGNS libraries with the ``CG_BUILD_SCOPE`` 
set to ``True``. To do so, edit your ``CMakeCache.txt`` file
and set the following variable to ``ON``.

.. highlight:: c

.. code-block:: c
 
 //Enable or disable scoping of enumeration values
 ENABLE_SCOPING:BOOL=ON
 

.. -------------------------------------------------------------------------
