.. _development: Installing for development ========================== To develop with the OpenQuake Engine and Hazardlib an installation from sources must be performed. The easiest way it to use the `universal installer `__. The guide here is for people wanting to do everything manually. Prerequisites ------------- Knowledge of `Python `__ (and its `virtual environments `__), `git `__ and `software development `__ are required. Some software prerequisites are needed to build the development environment. First of your you need a Python version supported by the engine. At the moment we recommend Python 3.12. **NB: Python 3.13 and later versions are not supported yet, so please do NOT install such versions** **NB: Python version below 3.11 are not supported , so please do NOT install such versions** Linux ----- Please check the documentation of your distribution to install one of the supported version of Python. At the moment we recommend Python version 3.12 but Python 3.11 can also be used. macOS ----- Python version 3.12 is recommended but Python 3.11 can also be used. Please see instructions for the :doc:`Installing the OpenQuake Engine on MacOS ` Windows ------- Python version 3.12 is recommended but Python 3.11 can also be used. Please install Python version using the official Python installer, using the instructions below. Do NOT install using Microsoft Store. ------------------------- 1. Download Python ------------------------- 1. Open the official download page: https://www.python.org/downloads/windows/ 2. Under **Stable Releases**, click **Download Python 3.12.x**. ------------------------- 2. Run the Installer ------------------------- Locate the downloaded file (e.g., ``python-3.12.x-amd64.exe``) and double-click it. ----------------------------------------- 3. Enable PATH and Start Installation ----------------------------------------- When the installer window appears: * Check **Add Python 3.12 to PATH** * Click **Install Now** The installation process may take a few minutes. Encoding -------- Make sure that the encoding set in the terminal is ``en_US.UTF-8``. To force it, you should put the following lines in your ``~/.profile``: .. code:: bash export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8 Download the OpenQuake source code ---------------------------------- Considering that the complete repository is quite large given its long history, we recommend shallow cloning the repository to download only the latest revision. .. code:: bash mkdir src && cd src git clone https://github.com/gem/oq-engine.git --depth=1 In case you needed the source code with the full history of the repository, you can convert the shallow clone into a full repository with the command ``git fetch --unshallow``. Install OpenQuake in development mode ------------------------------------- .. code:: bash $ cd oq-engine && python3 install.py devel Loading and unloading the development environment ------------------------------------------------- To exit from the OpenQuake development environment type ``deactivate``. Before using again the OpenQuake software the environment must be reloaded running ``source openquake/bin/activate``\ (assuming that it has been installed under ‘openquake’). For more information about *virtualenv*, see https://docs.python.org/3.12/library/venv.html. To load the virtual environment automatically at every login, add the following line at the bottom of your ``~/.bashrc`` (Linux) or ``~/.zshrc`` (macOS): .. code:: bash source $HOME/openquake/bin/activate You can also add a short-hand command to enable it: .. code:: bash alias oqenv="source $HOME/openquake/bin/activate" Put it again at the bottom of ``~/.bashrc`` or ``~/.zshrc``; close and re-open the terminal. You can now load your environment just typing ``oqenv``. It is also possible to run the ``oq`` command without the corresponding virtual environment loaded. Just run ``$HOME/openquake/bin/oq``; for convenience you can also add it as an ``alias`` in your ``~/.bashrc`` (Linux) or ``~/.zshrc`` (macOS): .. code:: bash alias oq="$HOME/openquake/bin/oq" Multiple installations ---------------------- If multiple installations are required, it is recommended to use separate virtual environments to avoid dependency conflicts caused by differing package versions. This can be achieved by using install.py and specifying the corresponding venv directory to be used. .. code:: bash $ cd oq-engine && python3 install.py devel --venv VENV Running the tests ----------------- To run the OpenQuake Engine tests see the `testing `__ page. Sync the source code with remote -------------------------------- You can pull all the latest changes to the source code running .. code:: bash cd oq-engine oq dbserver stop git pull Uninstall the OpenQuake Engine ------------------------------ To uninstall the OpenQuake development make sure that its environment is not loaded, typing ``deactivate``, and then remove the folder where it has been installed: ``rm -Rf $HOME/openquake``. Install third party software ---------------------------- It is possible to install, as an example, the `Silx HDF5 viewer `__ in the same environment as the OpenQuake Engine. To make that happen run the following commands via the ``oq-console.bat`` prompt: .. code:: bash pip install PyQt5 silx Silx viewer can be then run as .. code:: bash silx view calc_NNN.hdf5 -------------- Notes ----- If your system does not support the provided binary dependencies (python wheels) .. code:: bash pip install -e oq-engine will try to download the required dependencies from `pypi `__. This may require some extra work to get all the external C dependencies resolved. Also, there is not guarantee that the engine wil work, since newer versions of the libraries could be incompatible. If you are using a non-standard python distribution (like *macports* or *anaconda*) you should use tools provided by such distribution to get the required dependencies. -------------- Getting help ------------ If you need help or have questions/comments/feedback for us, you can subscribe to the OpenQuake users mailing list: https://groups.google.com/g/openquake-users