From 98186cacc2d07dd0e505489e5c71ed6edb304a42 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Sat, 14 Oct 2023 23:11:41 +0100 Subject: [PATCH] Update INSTALL.rst for a decent developer experience --- INSTALL.rst | 199 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 143 insertions(+), 56 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index bf35c898..42ae979e 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,74 +1,161 @@ Building Coriolis ================= -To build Coriolis, ensure the following prerequisites are met: +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. -* make or ninja. -* cmake. +* Python 3.9 or later +* Pip +* ninja. * bzip2 -* boost. +* boost * bison & flex. * Qt 5 & Qt 5 Svg. * Qwt * libxml2. * RapidJSON, http://rapidjson.org/ . * Eigen 3, http://eigen.tuxfamily.org . -* Lemon, http://lemon.cs.elte.hu/trac/lemon . * doxygen * pelican * latex -The build system relies on a fixed directory tree from the root -of the user currently building it. Thus first step is to get a clone of -the repository in the right place. Proceed as follow: -.. code-block:: bash - $ git clone --recurse-submodules https://github.com/lip6/coriolis - $ cd coriolis - -Then, to build Python wheels: - -.. code-block:: bash - - $ poetry build - -The wheels can be found in dist and installed using pip: - -.. code-block:: bash - - $ pip install dist/*.whl - -Building for Mac OSX -==================== - -To build on mac, first install _Homebrew: https://brew.sh - -To install the prereqisites: - -.. code-block:: bash - - brew install doxygen qt@5 qwt-qt5 rapidjson boost eigen - brew install --cask mactex - -.. code-block:: bash - - CMAKE_FRAMEWORK_PATH=/opt/homebrew/opt/qt@5/lib/cmake/ - -Using Coriolis -============== - -Prior to using Coriolis, you need to setup your UNIX environment by running -the following command: - -.. code-block:: bash - - ego@home:~$ eval `~/coriolis-2.x/OS.DISTRIB/Release.Shared/install/etc/coriolis2/coriolisEnv.py` - -Then you can launch the GUI: - -.. code-block:: bash - - ego@home:~$ cgt -V