Add in a single Configuration file which can generate most ModEM Makefiles (#25)

This merge adds in a single configuration file, Configure, which has the ability to generate make files for all solvers, compilers and ModEM build options.

There is already a lot of description in the Configure file itself, so no need to re-hash it here, but the goal of this single configure file is to make our lives easier as developers. Rather than making changes to all 30 something configuration files, we now only need to manage one.

This Configure file only supports GFortran and Intel Fortran compilers, but could easily be added to support more.

Currently, this configuration file does not have the capability to generate HIP/Cuda compatible makefiles. Perhaps that enough is a reason to use a different build system, currently, we are quite limited with building anything that is not a Fortran module.

Regardless, this should be easier to maintain, and easier for users to understand.

This script does make some assumptions, by default it will use MPI, rather than serial, and will build SP2, if the solver method is not specified. In the future we might want to make more assumptions, or could test to see if the user has specific compilers avaliable, i.e. check for gfortran, ifort, mpifort, but I don't think we have the number of new-users to justify that. We can always make that change if we get feedback that ModEM is hard to configure.

Author: MiCurry

README.md

@@ -83,35 +83,59 @@ variables of the Makefile.
 
 ## Creating Makefiles from Configuration files
 
-The current build system for ModEM uses the `fmkmf.pl` pearl script and the
-configuration scripts that are in `f90/CONFIG`. Although ModEM uses Make and
-Makefiles, makefiles are meant to be created by these configuration scripts.
+The current build system for ModEM uses the `fmkmf.pl` Perl Script and the
+configuration scripts that are in `f90/CONFIG`: `f90/CONFIG/Configure`.
+Although ModEM uses Make and Makefiles, makefiles are meant to be created by
+these configuration scripts.
 
-To create Makefiles, run the configuration scripts that match your system,
-desired compiler and desired ModEM version. These configuration scripts
-call the `fmkmf.pl` script:
+The current build system for ModEM uses the `fmkmf.pl` Perl script and the
+configure script, `f90/CONFIG/configure`. Although ModEM uses Make and
+Makefiles, makefiles are meant to be generated by `f90/CONFIG/configure` and
+not by hand.
+
+To create a new Makefile, run the configuration script and pass in your desired
+arguments This configuration scripts call the `fmkmf.pl` script:
 
 ``` bash
 $ cd f90/
-$ ./CONFIG/Configure.3D_MT.MAC.GFortran makefile.gnu.mpi MPI
+$ ./CONFIG/configure Makefile gfortran
 ```
 
-All configuration scripts take the same arguments:
+The `configure` scripts has the following usage:
 
 ```bash
-$ /CONFIG/Configfile <desired-makefile-name> <type>
+$ Usage: ./CONFIG/configure [-h] [-u] [-g release|debug] [-m mpi|serial] [-l solver] [-f] makefile-name compiler
+  -h Display full help message
+  -u Display this usage message
+  -g <release | debug> Specify whether to build with debug symbols or not
+     release - Default - Create Makefile with full optimizations (i.e. -O3)
+     debug   - Create Makefile with debug symbols (i.e. -g) and no optimizations
+  -m <mpi* | serial> Specify MPI or serial
+     mpi - Default - Builds with MPI
+     serial - Builds Serially
+  -l <MF | SP | SP2> Specify solver
+     MF - Builds with MF
+     SP - Builds with SP
+     SP2 - Default - Builds with SP2
+  -f Build with the Fine-Grained Parallel Version (-DFG on SP2)
+     Only available with SP2
+  -s Build spherical version of ModEM
 ```
 
-Where `type` is either: `MPI, release, debug`:
+### Examples using Configure
+
+A few examples using configure:
 
-* `MPI` - Generates a makefile that will compile an MPI version of ModEM
-* `release` - Generates a makefile that will compile a serial version of ModEM
-* `debug` -  Generates a makefile that will compile a serial version of ModEM
- with `-O0` (no optimizations) and debug symbols (`-g`, bounds checking ,etc)
+```bash
+ $ ./CONFIG/configure Makefile gfortran
+  Generates a Makefile with GFortran options using MPI
 
-Of course, any generated makefile can be altered as you see fit. For instance,
-it is often helpful to add the `-g` to compile with debug symbols when working
-with an MPI makefile.
+ $ ./CONFIG/configure -g debug Makefile gfortran
+   Generates an MPI Makefile with GFortran debugging options
+
+ $ ./CONFIG/configure -m serial -l MF Makefile gfortran
+   Generates a serial Makefile with GFortran with the MF solver
+```
 
 ## Compiling
 

docs/source/getting_started.rst

@@ -50,12 +50,8 @@ Configure Scripts
 There are a number of configure scripts inside ``./f90/CONFIG`` in the form of
 ``Configure.***``, ``Configure.SP.***``, ``Configure.3D_MT.**``, etc. These
 configure files are considered deprecated, and the ``configure`` script inside
-``f90`` should be used instead; however, the deprecated configure scripts are
-left for backwards compatibility.
-
-The ``configure`` script inside ``f90`` can be used to generate ModEM makefiles
-for various configurations and compilers. This ``configure`` should be used
-to generate makefiles for ModEM.
+``f90/CONFIG`` should be used instead; however, the deprecated configure
+scripts are left for backwards compatibility.
 
 Creating Makefiles from configure 
 ----------------------------------
@@ -78,8 +74,8 @@ Currently, ModEM has three different forwards 'flavors':
 .. code-block:: bash
 
     $ cd f90/
-    $ # By default ./configure creates a SP2 Makefile with MPI
-    $ ./configure Makefile gfortran
+    $ # By default ./CONFIG/configure creates a SP2 Makefile with MPI
+    $ ./CONFIG/configure Makefile gfortran
 
 The Configure scripts has the following usage::
 
@@ -115,24 +111,24 @@ A few examples using Configure
 
 .. code-block:: bash
 
-    $ ./configure Makefile gfortran
+    $ ./CONFIG/configure Makefile gfortran
     $ # Generates a Makefile with GFortran options using MPI
 
-    $ ./configure -d debug Makefile ifort
+    $ ./CONFIG/configure -d debug Makefile ifort
     $ # Generates an MPI Makefile with ifort debugging options
 
-    $ ./configure -m serial -l MF Makefile gfortran
+    $ ./CONFIG/configure -m serial -l MF Makefile gfortran
     $ # Generates a serial Makefile with GFortran with the MF solver
 
-    $ FC=ftn LDFLAGS=-L/home/username/install/lib ./configure Makefile gfortran
+    $ FC=ftn LDFLAGS=-L/home/username/install/lib ./CONFIG/configure Makefile gfortran
     $ # Generates an SP2, MPI capabile makefile, adding LDFLAGS to the link step and
     $ # specifies the compiler to be `ftn`.
 
-    $ FFLAGS='-mSSE2' ./configure Makefile ifort
+    $ FFLAGS='-mSSE2' ./CONFIG/configure Makefile ifort
     $ # Create a SP2, MPI capabile makefile, with ifort/intel compiler options and add
     $ # the '-mSSE2' to all compiling steps.
 
-    $ LDFLAGS="-L/path/to/install/lib/" ./configure Makefile gfortran
+    $ LDFLAGS="-L/path/to/install/lib/" ./CONFIG/configure Makefile gfortran
     $ # Generates a Makefile with GFortran options using MPI and passes
     $ # the location of /path/to/install/lib to the linker step
 
@@ -145,9 +141,9 @@ by setting the ``FC`` environment variable:
 
 .. code-block:: bash
 
-    $ FC=ftn ./configure Makefile gfortran
+    $ FC=ftn ./CONFIG/configure Makefile gfortran
     $ # Or for intel:
-    $ FC=ftn ./configure Makefile ifort
+    $ FC=ftn ./CONFIG/configure Makefile ifort
 
 
 Ensure BLAS and LAPACK are linked
@@ -159,7 +155,7 @@ the linker where to find them. You can specify this when you run configure:
 
 .. code-block:: bash
 
-   $ LDFLAGS="-L/path/to/install/lib/" ./configure Makefile gfortran
+   $ LDFLAGS="-L/path/to/install/lib/" ./CONFIG/configure Makefile gfortran
 
 If you have already created your makefile, you can also add the ``-L``
 specification to the ``LIBS_PATH`` of the Macro-Def section of your Makefile:
@@ -377,9 +373,9 @@ Now, we can move into ``~/ModEM-main`` to configure, build and run ModEM:
     $ cd ~/ModEM-main
     $ cd f90/
     $ # Compile with MPI, SP2 solver:
-    $ ./configure Makefile gfortran
+    $ ./CONFIG/configure Makefile gfortran
     $ # or compile serial, SP2 solver
-    $ ./configure -m serial Makefile gfortran
+    $ ./CONFIG/configure -m serial Makefile gfortran
     $ make
     $ # Run ModEM serially or with MPI:
     $ mpiexec -n 2 ./Mod3DMT ...