Compile Met.3D from source code: Linux (conda)
==============================================

This page describes how to setup a development environment to compile Met.3D from its source code
using conda under Linux.
If you would like to simply use the software, please use the 
:doc:`precompiled binary package <conda>` instead. 
If you would like to use a specific branch, or change parts of the source code yourself, 
this page is for you.

Our recommended approach for setting up a development environment for Met.3D under Linux
is using the `conda`_ system via `mamba`_.
Conda provides package management that is independent from your Linux distribution
and safely keeps all packages in an environment.
This way, everything you install for Met.3D will not interfere with your base system.
Also, using conda is independent of your Linux distribution,
hence the described approach should work with any Linux distribution and version.
Mamba is a fast alternative to conda that is fully compatible with the conda system.

.. important::

    The installation procedure described here works for **Met.3D v1.16** and higher versions.
    With version 1.16, we have updated to Qt6. If you would like to build 1.15 or an
    earlier version of Met.3D with Qt5, please refer to earlier versions of this page
    (before 17 June 2025) in the documentation repository (https://gitlab.com/wxmetvis/met.3d.docs).
    Note that the installation procedure described here does not work at all for version 1.6 and earlier.


1) Check GPU requirements and 2) Setup miniforge
------------------------------------------------

First, follow steps 1) and 2) as described for the :doc:`precompiled binary package <conda>`
to check you GPU installation and to install `miniforge`_.

.. important::
    In the following, we assume that you use the `miniforge`_ distribution with `mamba`_.


3) Setup a conda development environment for Met.3D
---------------------------------------------------

Create and activate a new conda environment using `mamba`::

    mamba create -n met3d
    mamba activate met3d

Next, install dependencies and development packages available via conda.
Most dependencies for Met.3D are available as conda packages.
Note that the following installation command may take a while,
since all packages need to be downloaded and installed::

    mamba install cxx-compiler fortran-compiler unzip make ninja cmake pkg-config gdb log4cplus libgdal eccodes netcdf-cxx4 gsl proj "qt6-main>=6.9" qt6-advanced-docking-system qt6-multimedia qt6-charts git mesa-libgl-devel-cos7-x86_64 mesa-dri-drivers-cos7-aarch64 libxau-devel-cos7-aarch64 libselinux-devel-cos7-aarch64 libxdamage-devel-cos7-aarch64 libxxf86vm-devel-cos7-aarch64 libxext-devel-cos7-aarch64 xorg-libxfixes xorg-libxau pybind11 xarray netcdf4 metpy libzip tinygltf


Some dependencies are not (yet) available via conda and need to be installed from source:
*glfx* an OpenGL shader library (note that we use our own fork with some changes),
the *freefont* package for text labels, *naturalearth* data for coastlines and
basemap files, and the *ScientificColourMaps* package for, as the name says, colour maps.
Here, we install everything into a directory ``met.3d-base`` in your home directory.
This, of course, can be a different directory as well::

    # Create a "met.3d-base" directory in your home directory, with sub-dirs "local" and "third-party".
    cd ~
    mkdir met.3d-base && cd met.3d-base
    mkdir local
    mkdir third-party
    
    # Checkout and install glfx.
    cd ~/met.3d-base/third-party/
    git clone https://github.com/thorwin-vogt/glfx.git --branch qt6
    cd glfx
    cmake -DCMAKE_INSTALL_PREFIX:PATH=~/met.3d-base/local -G Ninja CMakeLists.txt
    ninja
    cmake --install .
    
    # Download remaining third-party dependencies
    cd ~/met.3d-base/third-party
    wget http://ftp.gnu.org/gnu/freefont/freefont-ttf-20120503.zip
    unzip freefont-ttf-20120503.zip

    mkdir naturalearth
    cd naturalearth
    wget https://naciscdn.org/naturalearth/50m/physical/ne_50m_coastline.zip
    unzip ne_50m_coastline.zip
    wget https://naciscdn.org/naturalearth/50m/cultural/ne_50m_admin_0_boundary_lines_land.zip
    unzip ne_50m_admin_0_boundary_lines_land.zip
    wget https://naciscdn.org/naturalearth/50m/raster/HYP_50M_SR_W.zip
    unzip HYP_50M_SR_W.zip
    
    # Download remaining but optional third-party dependencies
    cd ~/met.3d-base/third-party
    wget https://zenodo.org/record/5501399/files/ScientificColourMaps7.zip
    unzip ScientificColourMaps7.zip


4) Clone the Met.3D repository and compile
------------------------------------------

Once the development environment exists, checkout the Met.3D repository and compile::

    cd ~/met.3d-base/
    git clone https://gitlab.com/wxmetvis/met.3d.git
    mkdir build && cd build
    cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_PREFIX_PATH=~/met.3d-base/local -G "Ninja" ../met.3d
    ninja


5) Run Met.3D
-------------

For executing the Met.3D binary, the environment variables ``MET3D_BASE`` and ``MET3D_HOME``
need to be set::

    # Make sure your "met3d" conda environment is activated!
    # The Met.3D binary is now located at "~/met.3d-base/build/". To run:
    cd ~/met.3d-base/build/
    MET3D_HOME=~/met.3d-base/met.3d MET3D_BASE=~/met.3d-base ./Met3D

6) Compiling and running Met.3D from within an IDE
--------------------------------------------------

If you would like to contribute to Met.3D, we provide guidelines to compile and run
Met.3D from within integrated development environments (IDEs) here:
:doc:`/04_contributing/met3d_development/setup_devel_env`.

.. _conda: https://docs.conda.io/projects/conda/en/latest/
.. _mamba: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html
.. _miniforge: https://conda-forge.org/download/