Building Coriolis
=================

Ubuntu/Windows WSL2 Build Environment
=====================================

If you haven't already got them, install `build-essential` and `git`

.. code-block:: bash

   sudo apt install build-essential git ccache

Clone the repo:

.. code-block:: bash

   git clone --recurse-submodules https://github.com/lip6/coriolis
   cd coriolis

Install the build dependencies:

.. code-block:: bash

   sudo apt install python3 python3-pip python3.10-venv \
                    doxygen pelican texlive-latex-recommended \
                    bison flex \
                    qtbase5-dev libqt5svg5-dev libqwt-qt5-dev libbz2-dev \
                    rapidjson-dev libboost-all-dev libeigen3-dev libxml2-dev


Mac OSX Build Environment
=========================

To build on Mac, first install _Homebrew: https://brew.sh. Be sure to follow all the instructions it gives after install  so HOMEBREW_PREFIX gets set!

Clone the repo:

.. code-block:: bash

   git clone --recurse-submodules https://github.com/lip6/coriolis
   cd coriolis


To install the prereqisites:

.. code-block:: bash

   brew install ccache doxygen pelican qt@5 qwt-qt5 rapidjson boost eigen
   brew install --cask mactex 


We need to set some environment variables for finding the cask only components. We use dotenv to set these in the PDM venv (see below)

.. code-block:: bash

   pip install dotenv
   dotenv set CMAKE_FRAMEWORK_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/cmake/"
   dotenv set PKG_CONFIG_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/pkgconfig:$HOMEBREW_PREFIX/opt/qwt-qt5/lib/pkgconfig"



Building Coriolis
=================

To build Python wheels, you'll need the `build` package if you don't already have it installed:

.. code-block:: bash

   pip3 install build


.. code-block:: bash

   python3 -m build -w

The wheels can be found in dist and installed using pip:

.. code-block:: bash

   pip3 install dist/*.whl

Development environment
=======================

For day-to-day development, its currently best to use meson and ninja directly. Currently there are `issues with using a Python editable install`_.


We use PDM_ to manage our development environment, which uses Python's venv_ system.

.. code-block:: bash

   pip install pdm

Before starting, you'll likely want to install the `shell completion`_ and read about `using pdm with virtual environments`_.  The basics are very simple, you just use pdm to run the build commands in an environment it automatially handles.

First we set up our pdm virtual environment:

.. code-block:: bash

   pdm install --no-self -d --plugins
   
Below we are just using a local directory call builddir for our meson_ build directory, but you can put it wherever you like.

.. code-block:: bash

   pdm run meson setup builddir
   pdm run ninja -C builddir install

You can then use `pdm run` to run any programs or scripts dependant on Coriolis, for example:

.. code-block:: bash
   pdm run unittests/python/test_hurricane.py


You can also install locally using:

.. code-block:: bash

   pdm run meson setup builddir -Dpython.install_env=system
   pdm run ninja -C builddir install


For more configuration and install options, see:

.. code-block:: bash

   pdm run meson configure


.. _issues with using a Python editable install: https://github.com/lip6/coriolis/issues/67
.. _venv: https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/#how-to-use-python-environments
.. _shell completion: https://pdm.fming.dev/latest/#shell-completion
.. _using pdm with virtual environments: https://pdm.fming.dev/latest/usage/venv/
   
Other operating systems
=======================

Coriolis is currently tested on CentOS 7 (via manylinux 2014), latest Ubuntu and on MacOSX.

We welcome patches for other operating systems, though please add appropriate CI!

You'll need the following prerequisites:

* A C++11 compliant compiler.
* Python 3.9 or later
* Pip
* ninja.
* bzip2
* boost
* bison & flex.
* Qt 5 & Qt 5 Svg.
* Qwt
* libxml2.
* RapidJSON, http://rapidjson.org/ .
* Eigen 3,  http://eigen.tuxfamily.org .
* doxygen
* pelican
* latex