Installation
------------

The library comes with dedicated build scripts that compile and install
the library into either a shared or static library. Different
installation scripts are provided for different platforms.

All source code is provided within the ``meshReaderLib`` folder. In
order to test that the library is working correctly, the compilation can
be tested with a few tests that are provided in the ``tests`` folder.
Within that folder, the file ``mainTest.cpp`` collects all tests, which
in turn are provided in the ``tests/unit`` folder (i.e. it contains all
unit tests). Running the executable that is generated by the
``tests/mainTest.cpp`` file will verify that the compilation has worked
correctly.

In order for the library to be compiled correctly, a few libraries need
to be compiled beforehand, namely the CGNS, HDF5, and gtest library.
Below is a collection of links, together with build scripts that
automatically build these libraries on either Windows or UNIX:

-  `Install CGNS and
   HDF5 <https://cfd.university/learn/how-to-compiler-write-and-use-cfd-libraries-in-c/how-to-integrate-external-cfd-libraries-in-your-code/#aioseo-case-study-compiling-the-cgns-library>`__
-  `Install
   gtest <https://cfd.university/learn/the-complete-guide-to-software-testing-for-cfd-applications/how-to-get-started-with-gtest-in-c-for-cfd-development>`__

Once these libraries are installed and available, you can go ahead and
use one of the build scripts discussed below to compile the mesh reading
library on either Windows or UNIX.

Windows
~~~~~~~

On Windows, we can either build the mesh reading library all into a
single executable (library + tests), or into separate test code and
either static or dynamic library. The build scripts to achieve that are
given below. All instructions assume that you are using a developer
PowerShell, which is automatically installed with Visual Studio.

   [!NOTE] In order to execute PowerShell scripts, you will have to
   allow to run `remotely signed scrips first (see the first
   example) <https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.4>`__.
   You may also need to
   `unblock <https://www.tenforums.com/tutorials/5357-unblock-file-windows-10-a.html>`__
   the PowerShell files first before using them. You will also need to
   have Visual Studio with the C++ development kit installed and run
   this scrupt inside a Developer PowerShell console. You may also need
   to `activate
   64-bit <https://developercommunity.visualstudio.com/t/x64-developer-powershell-for-vs-2019/943058>`__
   compilation, which may cause issues if the compilation tries to mix
   32-bit and 64-bit binaries. If this sounds too complicated, simply
   install
   `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`__ and
   follow the (simplified) instructions for UNIX below.

.. _single-executable-tests--library:

Single executable (tests + library)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``.\buildAndRun.ps1``

Tests with separate static mesh reader library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``.\buildStaticAndRun.ps1``

Tests with separate dynamic mesh reader library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``.\buildDynamicAndRun.ps1``

.. _unix-macos-ubuntu-etc:

UNIX (macOS, Ubuntu, etc.)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Similar to the instruction given on Windows, we can run the build bash
script to check that the compilation and execution have worked
correctly. These scripts assume that you have the CGNS and HDF5 library
compiled and installed within your home directory, i.e. within
``~/libs``.

Unlike Windows, we can run scripts directly but sometimes permissions
may not be granted for the current user, in which case we can use the
``chmod`` command to grant permission to run a specific file as
``chmod +x buildAndRun.sh``, for example. We can also grant permissions
for all bash scripts using regular expressions with ``chmod +x *.sh``.

To build the tests and library, open a terminal and type in one of the
following commands depending on what you want to build

.. _single-executable-tests--library-1:

Single executable (tests + library)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``./buildAndRun.sh``

.. _tests-with-separate-static-mesh-reader-library-1:

Tests with separate static mesh reader library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``./buildStaticAndRun.sh``

.. _tests-with-separate-dynamic-mesh-reader-library-1:

Tests with separate dynamic mesh reader library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``./buildDynamicAndRun.sh``