Commit 94645520 authored by Sebastian Müller's avatar Sebastian Müller 🐈
Browse files

update readme

parent 8052fd38
Pipeline #31873 passed with stages
in 7 minutes and 22 seconds
# Fortran Template
# Fortran Lib Test
<div align="center">
<img src="https://git.ufz.de/chs/logos/-/raw/master/FORP.png" alt="LOGO" width="251px" style="width:251px;"/>
</div>
This project is a fortran library that provides global variables and interfaces to manipulated them.
In addition, this library is also linking against [FORCES](https://git.ufz.de/chs/forces/).
Template of a Fortran program depending on FORCES provided by
> Department Computational Hydrosystems<br/>
> Helmholtz Centre for Environmental Research - UFZ<br/>
> Permoserstr. 15<br/>
> 04318 Leipzig, Germany
The purpose of this library is to be later used by a python wrapper.
## Structure
- `src/`: folder containing your fortran modules and pfUnit tests (`src/tests`)
- `mo_your_module.f90` - simple example module
- `mo_your_program_info.f90` - simple information including `version` and `version_date` generated by the pre-processor from the version files `version.txt` and `version_date.txt`
- `tests/test_your_module.pf` - simple pfUnit test for `mo_your_module.f90`
- `app/`: (optional) folder containing your fortran main program
- `main.f90` simple example program
- `doc/`: folder containing the doxygen documentation
- `doxygen-awesome-css/`: subrepo from https://github.com/jothepro/doxygen-awesome-css containing an awesome css theme for the doxygen generated html files (MIT license)
- `cmake/`: subrepo from https://git.ufz.de/chs/cmake-fortran-scripts containing cmake modules
- `hpc-module-loads/`: subrepo from https://git.ufz.de/chs/HPC-Fortran-module-loads containing module load scripts for EVE and JUWELS
## Requirements
The simplest way to compile this project on your local computer is to use a conda
environment (on Linux or MacOS) providing your with NetCDF, a fortran compiler, make, cmake and fypp.
On Windows we recommend to use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) (WSL2) to be able to use Linux.
For installing Miniconda follow this: https://conda.io/projects/conda/en/latest/user-guide/install
You can always get the latest version of Miniconda with (and then follow the instructions):
- Linux (including WSL2):
```bash
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
```
- MacOS:
```bash
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh
```
### Installation
To create the (local) conda environment type the following:
```bash
conda create -y --prefix ./fortran_env
conda activate ./fortran_env
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install -y cmake make fypp fortran-compiler netcdf-fortran
```
Then you can compile and install your program:
```bash
cmake -DCMAKE_BUILD_TYPE=Release -B build -S .
cmake --build build --parallel
cmake --install build --prefix $CONDA_PREFIX
```
Afterwards you can execute your program by typing `PROJ` (name of the Fortran Project) since it is now installed and available in your conda environment (done by `--prefix $CONDA_PREFIX`).
### Testing
You need to provide [pfUnit](https://github.com/Goddard-Fortran-Ecosystem/pFUnit) to run the tests (unfortunately not available on conda yet).
Then you can compile and run the tests (same conda environment as above, copy&paste all following lines):
```bash
ctest --build-and-test . build \
--build-generator "Unix Makefiles" \
--build-options -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON \
--test-command ctest
```
### Documentation
Follow the doxygen documentation guide for documenting your code: https://www.doxygen.nl.
Doxygen (v1.9.1 and above) can also be installed via conda (same environment as above):
```bash
conda install -y doxygen graphviz
```
Graphviz (https://graphviz.org) is needed to generate call graphs.
Then you can create the html and latex documentation by
```bash
doxygen doc/doxygen.config
```
Afterwards you can look at the `html/index.html` with your browser.
To generate a PDF (refman.pdf) from the generated latex files you need to provide Latex (https://www.latex-project.org/get/) and then do
```bash
cd latex && make
```
### On EVE
We provide loading scripts for different compilers in `hpc-module-loads/`, that is a subrepo hosted at https://git.ufz.de/chs/HPC-Fortran-module-loads.
You can use for example the intel 19 compiler on EVE with:
```bash
source hpc-module-loads/eve.intel19
```
Then you can install your app (into `<username>/.local/`):
```bash
cmake -DCMAKE_BUILD_TYPE=Release -B build -S .
cmake --build build --parallel
cmake --install build --prefix ~/.local/
```
Testing is also possible (pfUnit is automatically loaded with the loading script, copy&paste all following lines):
```bash
ctest --build-and-test . build \
--build-generator "Unix Makefiles" \
--build-options -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON \
--test-command ctest
```
## License
This project is part of the UFZ CHS Fortran code base.
The package is released under the GNU Lesser General Public License. The following applies:
The UFZ Fortran library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
### Doxygen Awesome
Doxygen Awesome is included as subrepo under `doc/doxygen-awesome-css/` from https://github.com/jothepro/doxygen-awesome-css. It is released under the MIT license.
### Cmake Fortran Scripts
The CHS Cmake Fortran Scripts repository is included as subrepo under `cmake/` from https://git.ufz.de/chs/cmake-fortran-scripts. It is released under the GNU LGPLv3 license.
### HPC Fortran Module Loads
The CHS HPC Fortran Module Loads repository is included as subrepo under `hpc-module-loads/` from https://git.ufz.de/chs/HPC-Fortran-module-loads. It is released under the GNU LGPLv3 license.
(C) Sebastian Mueller
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment