Set up a Linux development environment for Met.3D
=================================================

This page describes the steps required to set up a development environment for Met.3D
under Linux.

First, create a conda environment for building Met.3D and clone the Met.3D repository
as described at :doc:`/02_getting_started/installation/src_conda`.

Then, install and setup an IDE. We describe setups for these IDEs:

* :ref:`CLion`
* :ref:`QtCreator`


.. _`CLion`:
CLion
-----

Download and install CLion from the `JetBrains website <https://www.jetbrains.com/clion/>`_.

.. important::
    Start CLion from the terminal within your activated Met.3D conda environment.
    Otherwise it might not find the correct library and include paths.

Open Met.3D as a project
~~~~~~~~~~~~~~~~~~~~~~~~

When starting CLion for the first time, you can open a project from the start screen.
Otherwise open a project from the file menu by selecting *File-> Open*.
Choose the `CMakeLists.txt` in your cloned Met.3D repository and open it as a project.
Skip the wizard and use default settings.

Set up toolchains using your conda environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To build Met.3D, a toolchain with build tools needs to be created.
Open the CLion settings (*File -> Settings*) and navigate to the **Build, Execution and Deployment** section.
Open the **Toolchains** settings and create a new toolchain via the plus symbol
(select "System", name the new toolchain, e.g., "Met.3D toolchain").
The following settings need to be changed:

* **CMake:** Select the cmake executable in your Met.3D conda environment.
* **Build Tool:** This can be your build tool of choice that is located in your Met.3D conda environment. Here we use "ninja", also from the Met.3D conda environment.
* **C Compiler:** You can leave this on auto-detect, it will usually pick up gcc from your Met.3D conda environment.
* **C++ Compiler:** You can leave this on auto-detect, it will usually pick up g++ from your Met.3D conda environment.
* **Debugger:** You can leave this on "Bundled GDB" or "Bundled LLDB", whatever you prefer. We recommend LLDB as it is faster in our experience.

Click "Apply".

Setup cmake profiles
~~~~~~~~~~~~~~~~~~~

For building Met.3D one or more CMake profiles are required, e.g., a release and a debug profile.
Open the CLion settings (*File -> Settings*) and navigate to the **Build, Execution and Deployment** section.
Open the **CMake** settings and either edit the existing profile or create a new profile.

* **Build type:** Set this to release or debug, depending on the build type.
* **Toolchain:** Set this to the previously created toolchain.
* **Generator:** This should be set to the generator for your build tool selected in the toolchain previously. In our case this is **Ninja**.
* **CMake options:** Regardless of your build type you will need to add ``-DCMAKE_PREFIX_PATH="~/met.3d-base/local"``, or wherever you created your Met.3D base folder.
For debug builds you can also add ``-DCMAKE_CXX_FLAGS_DEBUG="-g -O0 -DENABLE_OPENGL_DEBUG"`` to disable optimization and enable OpenGL debug messaging.
* **Build directory:** Choose a build directory, e.g., "met.3d-base/cmake-build-debug-met3d"
* **Build options:** Adjust to the number of processor cores available, e.g., "-j 20"
* **Environment:** Set here your ``MET3D_HOME`` and ``MET3D_BASE`` environment variables. ``MET3D_HOME`` usually points to your repository clone of Met.3D.

After you created the CMake profiles, close the settings (*Apply* or *Ok*),
navigate to *Tools -> CMake -> Reset Cache and Reload Project*.
This generates the build folder and a default run configuration.

Next, build Met.3D by pressing the build button (hammer icon) in the top right of the editor window.

Set up run configurations
~~~~~~~~~~~~~~~~~~~~~~~~~

To run Met.3D from within CLion, you need to create run/debug configurations.
Open the run configurations dialog from the top right of your editor window,
next to the build symbol.
Select *Edit Configurations...*.

A default run configuration called *Met3D* should already exist.
If it does not exist, press the plus icon and add a new **CMake Application**.
Set the following:

* **Target:** The target should be "Met3D". If it does not exist build the application once.
* **Executable:** Should also be "Met3D".
* **Program arguments:** Add your command line arguments for Met.3D here, such as ``--datasets``. You can view all by passing ``--help``.
* **Working directory:** Can be left as is.
* **Environment variables:** Set your ``MET3D_HOME`` and ``MET3D_BASE`` environment variables. ``MET3D_HOME`` usually points to your repository clone of Met.3D.

Set up coding style
~~~~~~~~~~~~~~~~~~~

CLion automatically loads the ``.clang-format`` file in the Met.3D repository and uses it for auto-formatting.

.. note::
    We recommend to set up line endings used in the IDE to be *Unix* (``\n``) line endings.
    Find this option in the CLion settings (*File -> Settings*) in the **Editor** -> **Code Style** section.

Set up file templates
~~~~~~~~~~~~~~~~~~~~~

A useful feature are file templates.
You can set them up to follow the format guidelines as outlined in :doc:`/04_contributing/met3d_development/cpp_coding_style`
and :doc:`/04_contributing/met3d_development/glsl_coding_style`
In the CLion settings (*File -> Settings*), navigate to **Editor**.
Open the **File and Code templates** section.

In the **Includes** tab, edit the `C File Header`, which is included in all ``.c``, ``.cpp`` and ``.h`` files you create.
In the **Files** tab, additional file templates can be created, such as a template for the glsl ``.fx.glsl`` files we use.
For this, you can use the :ref:`GLSL template`.


.. _`QtCreator`:
QtCreator
---------

.. warning::
    These instructions are outdated and only kept for reference.


Unfortunately, there is no conda package for QtCreator, hence either a package of your
Linux distribution needs to be used (Ubuntu and OpenSuSE provide QtCreator through their
package managers).

Alternatively, download and install QtCreator from `the Qt website <https://download.qt.io/official_releases/qtcreator/latest/>`_.

.. important::
    Start QtCreator from the terminal within your activated Met.3D conda environment.
    Otherwise it might not find the correct library and include paths.

Open Met.3D as a project
~~~~~~~~~~~~~~~~~~~~~~~~

Open the Met.3D project (File → Open File or Project → *Select Met.3D's CMakeLists.txt*).

Set up configuration
~~~~~~~~~~~~~~~~~~~~

* Click "Manage Kits" → Make sure that all tools in the correct PATH are used
  (i.e., gcc, gdb, etc. from the conda environment - in some attempts, a "wrong" gdb was selected by default)
* Click "Make default" for "Qt 6.X.X in PATH (met3d) - temporary" (for whichever Qt version is current as you read this)
* Possibly adjust the Debug and Release paths for the Met.3D binaries
* Click "Configure Project"
* In the "Build Settings":
  * In "CMake", set CMAKE_PREFIX_PATH to ~/met.3d-base/local
  * In "Build Steps", add "-j 12" (or however many core you have available) to build arguments for parallel compilation
* In the "Run Settings":
  * Change the Met.3D working directory to point to the source directory
  * Add the MET3D_BASE and MET3D_HOME environment variables

.. note::

     QtCreator by default uses Clang to analyze the code.
     On our Ubuntu 20.04 LTS, clang is installed from the Ubuntu system
     but not in the conda environment above. This seems to interfere,
     and QtCreator displays a number of error messages  related to not finding system files.
     We switched off the plugins "C++/ClangCodeModel" and "Code Analyzer/ClangTools"
     in the Help/About plugins dialog to make the error message disappear.
     An alternative could be to install clang in the conda environment,
     or to install QtCreator from the Qt downloads in the conda environment.