Merge pull request #29 from UCL-ARC/lint-with-fortitude

Lint with fortitude

Author: connoraird

.github/workflows/linting.yaml

@@ -0,0 +1,32 @@
+---
+name: Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types:
+      - opened
+      - ready_for_review
+      - reopened
+      - synchronize
+
+concurrency:
+  cancel-in-progress: true
+  group: >-
+    ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+
+jobs:
+  linting:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      
+      - name: Install pre-commit and fortitude
+        run: python -m pip install pre-commit fortitude-lint
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files --color always --verbose

.gitignore

@@ -3,4 +3,6 @@
 *.DS_Store
 build/
 build-cmake/
-*Temporary
+*Temporary
+.vscode
+*.egg-info

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+---
+repos:
+  - repo: https://github.com/PlasmaFAIR/fortitude-pre-commit
+    rev : v0.7.2
+    hooks:
+    # Idealy, we would not need to specify the entry point, but the fortitude cli 
+    # requires the `--config-file` option to be specified before the `check` subcommand
+    # and the pre-commit hook correctly states check in the entry.
+    - id: fortitude
+      entry: fortitude --config-file formatting/fortitude.toml check --force-exclude

README.md

@@ -1,6 +1,6 @@
 # UCL ARC Fortran Tooling Recommendations and Examples
 
-This repository aims to improve Fortran best practices within UCL and the wider Fortran community by documenting a growing list of Fortran tools recommended by [UCL ARC](https://ucl.ac.uk/arc). 
+This repository aims to improve Fortran best practices within UCL and the wider Fortran community by documenting a growing list of Fortran tools recommended by [UCL ARC](https://ucl.ac.uk/arc).
 
 ## Topics covered
 
@@ -9,14 +9,14 @@ This repository aims to improve Fortran best practices within UCL and the wider
 - compiling
 - [debugging](./debugging)
 - documentation
-- formatting
+- [formatting](./formatting)
 - interfaces
 - libraries
 - package management
 - profiling and tracing
 - [testing](./testing)
 
-## ARC Fortran projects 
+## ARC Fortran projects
 
 | Name | Start | End | Repo | Opportunity | Tools | Lessons |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -25,41 +25,50 @@ This repository aims to improve Fortran best practices within UCL and the wider
 | ALPS | Aug 2022 | Jul 2023 | [GitHub](https://github.com/danielver02/ALPS) | [#691](https://github.com/UCL-ARC/research-software-opportunities/issues/691) | Autotools, Ford | |
 | FruitDemand | Apr 2021 | Mar 2023 |  | [#382](https://github.com/UCL-ARC/research-software-opportunities/issues/382) |  Make, Ford, PFUnit | |
 | Trove | Jan 2021 | Aug 2021 | [GitHub](https://github.com/Trovemaster/TROVE/tree/merge-develop-mpi) | [#404](https://github.com/UCL-ARC/research-software-opportunities/issues/404) | Make, pFUnit (see the [PR](https://github.com/Trovemaster/TROVE/pull/44/files#diff-beda42571c095172ab63437d050612a571d0d9ddd3ad4f2aecbce907a9b7e3d0)) | |
-| Zacros | Jan 2021 | Sep 2022 | | [#349](https://github.com/UCL-ARC/research-software-opportunities/issues/349) & older | CMake, CTest | | 
+| Zacros | Jan 2021 | Sep 2022 | | [#349](https://github.com/UCL-ARC/research-software-opportunities/issues/349) & older | CMake, CTest | |
 
 ## src code
 
-There are two src codes within this repository [mesh_generator](./src/mesh_generator/) and [poisson](./src/poisson/). These are designed to work together. 
+There are two src codes within this repository [mesh_generator](./src/mesh_generator/) and [poisson](./src/poisson/). These are designed to work together.
+
 - `mesh_generator` generates a basic square 2D triangular mesh (see [mesh_generator.f90](./src/mesh_generator/mesh_generator.f90) for more details).
-- `poisson` is a solver which finds the solution of the steady-state heat conduction equation represented by the Poisson equation over a 2D traingular mesh (see [poisson.f90](./src/poisson/poisson.f90) for more details).
+- `poisson` is a solver which finds the solution of the steady-state heat conduction equation represented by the Poisson equation over a 2D triangular mesh (see [poisson.f90](./src/poisson/poisson.f90) for more details).
 
 ## Building
 
 A bash script is provided for building ([build.sh](./build.sh)). However, there are some instructions below for building without this script.
 
 ### CMake
->Note: we have some [PFunit tests](./testing/pFUnit/) which require a local version of PFunit to be pre-built on your device. Once built, the path to the PFunit `installed` dir will need to be passed via `-DCMAKE_PREFIX_PATH`.
+
+>Note: we have some [pFUnit tests](./testing/pFUnit/) which require a local version of pFUnit to be pre-built on your device. Once built, the path to the pFUnit `installed` dir will need to be passed via `-DCMAKE_PREFIX_PATH`.
 
 One build system we are utilising is cmake (see [CMakeLists.txt](./CMakeLists.txt)). Therefore, to build this repository, please run the following
+
 ```sh
 cmake -DCMAKE_PREFIX_PATH=/path/to/pfunit/installed/dir -B build-cmake 
 ``` 
 This will create a [build](./build) directory from within which the project can be compiled...
+
 ```sh
 cmake --build build-cmake
 ```
+
 This will produce executables for the two src codes, `fortran-tooling-mesh-generator` and `fortran-tooling-poisson`.
 
 ### FPM
+
 To build the project using FPM, from the root of the repo, run
+
 ```sh
 fpm build
 ```
 
 ## Running the src
 
 ### Mesh generator
+
 If you have built using CMake, you can run the mesh generator by directly calling the executable
+
 ```sh
 ./build/fortran-tooling-mesh-generator <box_size> <edge_size>
 ```
@@ -81,12 +90,33 @@ fpm run poisson -- <path_to_mesh_file>
 ```
 
 ## Running the tests
+
 If you have built using CMake, you can run the tests by running the following from within the `build-cmake` directory.
+
 ```sh
 ctest
 ```
 
-If you have built using fpm, you can run the tests by running the following from the root of the repo
+If you have built using FPM, you can run the tests by running the following from the root of the repo
+
 ```sh
 fpm test
 ```
+
+## pre-commit
+
+[pre-commit](https://pre-commit.com/) is utilised within this repo. pre-commit is a tool to help enforce formatting standards as early as possible.
+pre-commit works by running a provided set of checks every time a `git commit` is attempted.
+
+To utilise pre-commit, it must be installed locally. This can be done in several ways but the easiest is to use the provided `pyproject.toml` via...
+```
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+``` 
+
+Then, from the root of the repo, you start using pre-commit by running
+
+```sh
+pre-commit install
+```

build.sh

@@ -46,21 +46,13 @@ shift $((OPTIND -1))
 
 if [ "$clean_build" == "true" ]
 then
-    if [ "$build_cmake" == "true" ]
-    then
-        echo "Cleaning cmake build"
-        rm -rf build-cmake
-    fi
-
-    if [ "$build_fpm" == "true" ]
-    then
+    if [ -d "build" ]; then
         echo "Cleaning fpm build"
         rm -rf build
     fi
-
-    if [ "$build_cmake" == "false" ] && [ "$build_fpm" == "false" ]
-    then
-        echo "No build type specified"
+    if [ -d "build-cmake" ]; then
+        echo "Cleaning cmake build"
+        rm -rf build-cmake
     fi
 fi
 
@@ -82,11 +74,6 @@ fi
 # Build fpm version
 if [ "$build_fpm" == "true" ]
 then
-    if [ "$clean_build" == "true" ]
-    then
-        echo "Cleaning fpm build"
-        rm -rf build
-    fi
     echo "Building using fpm"
     fpm build
 fi

debugging/README.md

@@ -1,10 +1,10 @@
-# fortran-unit-testing
+# Fortran debugging
 
 ## Candidate Tools
 
 | tool | description | Known issues |
 | ---- | ----------- | ------------ |
 | [GDB](https://www.sourceware.org/gdb/) | | <ul></ul>  |
 | [linaro DDT](https://www.linaroforge.com/linaroDdt/) | | <ul></ul>  |
-| [mdb](https://github.com/TomMelt/mdb) | A lightweight wrapper of [gdb](https://www.sourceware.org/gdb/) and [lldb](https://lldb.llvm.org/) intended to make debugging MPI a lot simpler. | <ul><li>Not compatible with Apple ARM.</li><li>Maintained by only one person</li></ul> |
-| print statement | Great for small programs and simple problems but provides very limited information and requires recompiling to alter that information. We recomend spending the time to learn how to use a debugging tool such as the others in this list. | <ul></ul>  |
+| [mdb](https://github.com/TomMelt/mdb) | A lightweight wrapper of [gdb](https://www.sourceware.org/gdb/) and [lldb](https://lldb.llvm.org/) intended to make debugging MPI a lot simpler. | <ul><li>Not compatible with Apple ARM.</li><li> Maintained by only one person</li></ul> |
+| print statement | Great for small programs and simple problems but provides very limited information and requires recompiling to alter that information. We recommend spending the time to learn how to use a debugging tool such as the others in this list. | <ul></ul>  |

debugging/mdb.md

@@ -7,50 +7,60 @@ Python >= 3.10
 ## Installation
 
 Clone the repository
-```
+
+```sh
 git clone https://github.com/TomMelt/mdb.git
 cd mdb
 ```
 
 Create a virtual Python virtual environment
-```
+
+```sh
 python3 -m venv $HOME/mdb-venv
 ```
 
 Activate the virtual environement
-```
+
+```sh
 source $HOME/mdb-venv/bin/activate
 ```
 
 Install mdb and the optional dependency with pip3
-```
+
+```sh
 pip3 install .
 pip3 install termgraph
 ```
 
 ## Notes
 
 As part of the CONQUEST project. I (Connor Aird) tried using mdb on the UCL cluster, Myriad. I installed mdb following the above guide within an interactive session with the following modules loaded.
-```
+
+```sh
 Currently Loaded Modulefiles:
  1) beta-modules      3) compilers/intel/2022.2     5) libxc/6.2.2/intel-2022   7) openssl/1.1.1u   9) gerun                 11) emacs/28.1
  2) gcc-libs/10.2.0   4) mpi/intel/2021.6.0/intel   6) cmake/3.21.1             8) python/3.11.4   10) git/2.41.0-lfs-3.3.0  12) userscripts/1.4.0
-``` 
-
-I then launched an mdb sessions in the background using 
 ```
+
+I then launched an mdb sessions in the background using
+
+```sh
 mdb launch -b gdb -n 4 -t ./Conquest
 Ctrl+z
 bg
 ```
+
 Then, attached to the session, which appeared to be successful.
-```
+
+```sh
 (mdb-venv) [ccaecai@node-d00a-124 np-4-debug]$ mdb attach
 mdb - mpi debugger - built on various backends. Type ? for more info. To exit interactive mode type "q", "quit", "Ctrl+D" or "Ctrl+]".
 (mdb 0-3) 
 ```
+
 Adding a breakpoint seems to be successful,
-```
+
+```sh
 (mdb 0-3) command break exx_kernel_default.f90:204
 0:	Breakpoint 2 at 0x7ee299: file exx_kernel_default.f90, line 204.
 ************************************************************************
@@ -60,8 +70,10 @@ Adding a breakpoint seems to be successful,
 ************************************************************************
 3:	Breakpoint 2 at 0x7ee299: file exx_kernel_default.f90, line 204.
 ```
+
 However, trying to run until hitting this breakpoint results in an error
-```
+
+```sh
 (mdb 0-3) command c
 0:	Continuing.
 0:	[cli_0]: write_line error; fd=9 buf=:cmd=init pmi_version=1 pmi_subversion=1
@@ -146,4 +158,4 @@ However, trying to run until hitting this breakpoint results in an error
 3:	MPIR_Err_return_comm (comm_ptr=0x7fffffff1100, fcname=0x0, errcode=1090831) at ../../src/mpi/errhan/errutil.c:309
 3:	309	../../src/mpi/errhan/errutil.c: No such file or directory.
 3:	Missing separate debuginfos, use: debuginfo-install numactl-libs-2.0.12-5.el7.x86_64
-``` 
+```

formatting/README.md

@@ -0,0 +1,7 @@
+# Fortran formatting
+
+## Candidate Tools
+
+| tool | description | Known issues |
+| ---- | ----------- | ------------ |
+| [Fortitude](https://fortitude.readthedocs.io/en/stable/) | A [Ruff](https://docs.astral.sh/ruff/) style linter for Fortran. | |

formatting/fortitude.md

@@ -0,0 +1,52 @@
+# [Fortitude](https://fortitude.readthedocs.io/en/stable/)
+
+## Prerequisite
+
+A tool for installing, i.e. `pip` or `homebrew`
+
+## Installation
+
+To install fortitude we can utilise the provided `pyproject.toml` by following the instructions in [the pre-commit install instructions](../README.md#pre-commit). The [quickstart page](https://fortitude.readthedocs.io/en/stable/#quickstart) for Fortitude details multiple other ways of installing the tool.
+
+## Usage in this repo
+
+This repo has been formatted with Fortitude. To check this repo with Fortitude, simply run the following from the root of this repository
+
+```sh
+fortitude --config-file formatting/fortitude.toml check
+```
+
+The config file, [fortitude.toml](./fortitude.toml), we have provided in the above command contains our rules which alter the [default fortitude rules](https://fortitude.readthedocs.io/en/stable/rules/).
+
+### pre-commit
+
+We have also integrated Fortitude with pre-commit. To set this up, follow the [instructions on the main README.md](../README.md#pre-commit).
+Once this is set up, if you then try and commit a poorly formatted Fortran file...
+
+```sh
+$ git commit -m "Adding a bad commit"       
+Fortran Tooling hooks....................................................Failed
+- hook id: fortran-tooling-hooks
+- exit code: 1
+
+testing/veggies/test_poisson.f90:2:5: C121 'use' statement missing 'only' clause
+  |
+1 | module veggies_poisson
+2 |     use poisson
+  |     ^^^^^^^^^^^ C121
+3 |     use veggies, only: &
+4 |             assert_equals, &
+  |
+
+fortitude: 1 files scanned.
+Number of errors: 1
+
+For more information about specific rules, run:
+
+    fortitude explain X001,Y002,...
+```
+
+Fortitude has helpfully alerted us to our mistake. In the above case, we have tried to use a module without specifying which bits of
+the module we require via an `only` clause. If we disagree with a rule we can investigate further by searching the rule ID, here the
+rule ID is `C121` which has the description `'use' statement missing 'only' clause` and further info can be found on the
+[Fortitude website](https://fortitude.readthedocs.io/en/stable/rules/use-all/)  

formatting/fortitude.toml

@@ -0,0 +1,5 @@
+[check]
+ignore = [
+    "C003", # 'implicit none' missing 'external'
+]
+line-length = 132