.. _build_and_usage:

#################
Build & Benutzung
#################

.. contents:: Inhaltsverzeichnis
   :local:
   :depth: 2



Voraussetzungen
===============

Folgende Software wird benoetigt:

.. list-table::
   :header-rows: 1
   :widths: 25 35 40

   * - Tool
     - Zweck
     - Installation (Ubuntu/WSL)
   * - GCC/G++
     - C++11-Compiler
     - ``sudo apt install build-essential``
   * - SCons
     - Build-System
     - ``pipx install scons``
   * - Git
     - Versionskontrolle
     - ``sudo apt install git``
   * - Doxygen + Graphviz
     - API-Dokumentation
     - ``sudo apt install doxygen graphviz``
   * - Sphinx + RTD-Theme
     - Benutzer-Dokumentation
     - ``pip3 install sphinx sphinx_rtd_theme``
   * - Python 3
     - Fuer SCons und Sphinx
     - ``sudo apt install python3 python3-pip``


Repository einrichten
=====================

Klonen und Submodule
--------------------

.. code-block:: bash

   git clone https://git.uni-jena.de/na48gom/tsunami.git
   cd tsunami

   # Catch2 Test-Framework als Submodul initialisieren (wichtig!)
   git submodule init
   git submodule update

Kompilierung
============

Das Projekt verwendet `SCons <https://www.scons.org/>`_ als Build-System.

Build-Modi
----------

.. code-block:: bash

   # Release-Build (optimiert, -O2)
   scons

   # Debug-Build (keine Optimierung, Debug-Symbole)
   scons mode=debug

   # Debug + Address- und Undefined-Behavior-Sanitizer
   scons mode=debug+san

   # Release + Sanitizer
   scons mode=release+san

   # Paralleler Build (z.B. mit 4 Threads)
   scons -j4

   # Build aufraeumen (alle erzeugten Dateien loeschen)
   scons -c

Unit-Tests
==========

`Catch2 <https://github.com/catchorg/Catch2>`_ als Test-Framework.

Tests ausführen
-----------------

.. code-block:: bash

   # Alle Tests ausfuehren
   ./build/tests

   # Nur Tests mit einem bestimmten Tag
   ./build/tests "[FWave]"
   ./build/tests "[RoeSpeeds]"

   # Einen einzelnen Test nach Name ausfuehren
   ./build/tests "Test f-wave net-updates for steady state"

   # Alle vorhandenen Tags auflisten
   ./build/tests --list-tags

   # Alle Tests mit ausfuehrlicher Ausgabe
   ./build/tests -s


.. Simulation starten
.. ==================

.. Nach dem erfolgreichen Build kann die Simulation ausgefuehrt werden:

.. .. code-block:: bash

..    ./build/tsunami_lab N_CELLS

.. Dabei ist ``N_CELLS`` die Anzahl der Zellen in x-Richtung.
.. Beispiel mit 100 Zellen:

.. .. code-block:: bash

..    ./build/tsunami_lab 100

.. Die Simulation gibt waehrend der Berechnung den Fortschritt aus und schreibt
.. in regelmaessigen Abstaenden CSV-Dateien (``solution_0.csv``, ``solution_1.csv``, ...),
.. die den Zustand des Wellenfeldes enthalten.

.. Ausgabeformat
.. -------------

.. Die CSV-Dateien enthalten folgende Spalten:

.. .. list-table::
..    :header-rows: 1
..    :widths: 20 80

..    * - Spalte
..      - Beschreibung
..    * - ``x``
..      - x-Position der Zellmitte
..    * - ``y``
..      - y-Position der Zellmitte
..    * - ``height``
..      - Wasserhoehe :math:`h`
..    * - ``momentum_x``
..      - Impuls in x-Richtung :math:`hu`


.. Dokumentation generieren
.. ========================

.. API-Dokumentation (Doxygen)
.. ---------------------------

.. Doxygen erzeugt aus den Kommentaren im Quellcode eine HTML-Referenz
.. aller Klassen, Funktionen und Parameter:

.. .. code-block:: bash

..    cd doxygen
..    doxygen Doxyfile

.. Die generierte Dokumentation liegt anschliessend unter ``doxygen/html/index.html``.

.. Alle oeffentlichen Funktionen sollten mit Doxygen-Syntax dokumentiert werden:

.. .. code-block:: cpp

..    /**
..     * @brief Berechnet die Net-Updates.
..     *
..     * @param i_hL Wasserhoehe links.
..     * @param i_hR Wasserhoehe rechts.
..     * @param o_netUpdateL Net-Update fuer die linke Zelle.
..     */

.. Benutzer-Dokumentation (Sphinx)
.. -------------------------------

.. Diese Dokumentation wird mit Sphinx aus ``.rst``-Dateien erzeugt:

.. .. code-block:: bash

..    cd sphinx
..    make html

.. Die generierte Dokumentation liegt unter ``sphinx/build/html/index.html``.

.. Um ein neues Kapitel hinzuzufuegen:

.. 1. Neue ``.rst``-Datei unter ``sphinx/source/chapters/`` anlegen.
.. 2. Die Datei im ``toctree`` der ``sphinx/source/index.rst`` eintragen.
.. 3. ``make html`` erneut ausfuehren.


Verzeichnisstruktur
===================

.. code-block:: text

   tsunami/
   ├── SConstruct               # Build-Einstiegspunkt (SCons)
   ├── shell.nix                # Nix-Entwicklungsumgebung (Uni-Rechner)
   ├── submit.sh                # Abgabe-Skript (erstellt tar.xz)
   ├── src/
   │   ├── main.cpp             # Simulations-Einstiegspunkt
   │   ├── tests.cpp            # Catch2 Test-Runner
   │   ├── constants.h          # Globale Konstanten (t_real, t_idx, g)
   │   ├── SConscript           # Quell- und Testdatei-Listen
   │   ├── solvers/             # Riemann-Solver
   │   │   ├── Roe.h/.cpp       #   Roe-Solver (Referenzimplementierung)
   │   │   ├── FWave.h/.cpp     #   F-wave Solver
   │   │   └── *.test.cpp       #   zugehoerige Unit-Tests
   │   ├── patches/             # Wellen-Propagation
   │   ├── setups/              # Anfangsbedingungen (z.B. DamBreak)
   │   └── io/                  # Ein-/Ausgabe (CSV)
   ├── submodules/Catch2/       # Catch2 Test-Framework (Git-Submodul)
   ├── sphinx/                  # Sphinx-Dokumentation (dieses Dokument)
   ├── doxygen/                 # Doxygen-Konfiguration + generierte API-Doku
   └── build/                   # Erzeugte Binaries (nicht im Git)


.. Abgabe erstellen
.. ================

.. Das Skript ``submit.sh`` im Projektroot automatisiert die Erstellung des
.. Abgabe-Archivs:

.. .. code-block:: bash

..    chmod +x submit.sh    # einmalig: ausfuehrbar machen
..    ./submit.sh

.. Das Skript fuehrt folgende Schritte aus:

.. 1. Baut den Code (Release-Modus).
.. 2. Fuehrt alle Unit-Tests aus.
.. 3. Generiert die Doxygen-Dokumentation.
.. 4. Generiert die Sphinx-Dokumentation.
.. 5. Fragt interaktiv nach weiteren Links (z.B. zu Daten oder Visualisierungen).
.. 6. Erstellt ein ``.tar``-Archiv mit dem Namen
..    ``tsunami_lab_DATUM_Moritz_Arnhold_&_Moritz_Martin.tar``.

.. Das Git-Repository (https://git.uni-jena.de/na48gom/tsunami) wird automatisch
.. eingetragen. Alle Links werden in ``SUBMISSION_LINKS.txt`` gespeichert und
.. sind im Archiv enthalten.

.. **Schnellmodus** (ohne Link-Abfrage):

.. .. code-block:: bash

..    ./submit.sh --skip-links

.. Auf den Uni-Rechnern (NixOS) muss das Skript innerhalb der ``nix-shell``
.. ausgefuehrt werden.