From ea63fdd02f7da49fbd7235d381883e0a4f5b3f93 Mon Sep 17 00:00:00 2001 From: David A Minton Date: Fri, 28 Jul 2023 11:23:09 -0400 Subject: [PATCH] Updated README.md with new directions on compiling --- README.md | 60 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index f45a812c3..4ffe2667c 100644 --- a/README.md +++ b/README.md @@ -63,55 +63,63 @@ $ git pull You now have a Swiftest repository on your personal machine that you may compile, edit, and run as you see fit. -**Compiling Swiftest** +**Compiling the Swiftest driver program** -Swiftest is written in modern Fortran and must be compiled before it can be run. After compilation, an executable, called the Swiftest driver, will have been created in the ```/swiftest/bin/``` directory. - -Swiftest is compiled through [CMake](https://cmake.org/). Compiling with CMake has a number of benefits that provide a streamlined experience for the Swiftest user and developer. At compilation, CMake will automatically select the set of flags that are compatible with the local compiler. CMake also allows a Swiftest developer to re-compile only the files that have been edited, instead of requiring the developer to re-compile the entire Swiftest program. Please visit the CMake website for more information on how to install CMake. - -Once CMake is installed, navigate to the topmost directory in your Swiftest repository. It is best practice to create a ```build``` directory in your topmost directory from which you will compile Swiftest. This way, temporary CMake files will not clutter up the ```swiftest/src/``` sub-directories. To create a new directory and then navigate into that directory, type the following: +***Compiling `swiftest_driver` using Docker*** +By far the simplest, most reliable way of compiling the driver program is via a Docker container. The Swiftest project contains a Dockerfile that may be used to generate an executable without needing to provide any external dependencies, other than the Docker engine itself (see [here](https://docs.docker.com/get-docker/) for instructions on obtaining Docker). Once Docker is installed and the Docker engine is running, execute: ``` -$ mkdir build -$ cd build +$ docker build --target=export_driver --output=bin --build-arg MACHINE_CODE_VALUE="Host" [--build-arg EXTRA_CMAKE_OPTIONS=["-D"] ``` +***Compiling `swiftest_driver` using CMake*** + +The Swiftest driver program is written in modern Fortran and must be compiled before it can be run. After compilation, an executable, called the `swiftest_driver``, will have been created in the ```bin/``` directory. + +Swiftest is compiled through [CMake](https://cmake.org/). Compiling with CMake has a number of benefits that provide a streamlined experience for the Swiftest user and developer. At compilation, CMake will automatically select the set of flags that are compatible with the local compiler. CMake also allows a Swiftest developer to re-compile only the files that have been edited, instead of requiring the developer to re-compile the entire Swiftest program. Please visit the CMake website for more information on how to install CMake. + As mentioned in the **System Requirements** section, Swiftest requires the NetCDF and NetCDF Fortran libraries to be installed prior to compilation. If the libraries are installed in the standard library location on your machine, CMake should be able to find the libraries without specifying the path. However, if CMake struggles to find the NetCDF libraries, there are two ways to set the path to these libraries. 1. Create an environment variable called ```NETCDF_FORTRAN_HOME``` that contains the path to the location where the libraries are installed -2. Set the path at the time of compilation using ```-CMAKE_PREFIX_PATH=/path/to/netcdf/``` +2. Set the path at the build step using ```-CMAKE_PREFIX_PATH=/path/to/netcdf/``` CMake allows the user to specify a set of compiler flags to use during compilation. We define five sets of compiler flags: release, testing, profile, math, and debug. To view and/or edit the flags included in each set, see ```swiftest/cmake/Modules/SetFortranFlags.cmake```. As a general rule, the release flags are fully optimized and best used when running Swiftest with the goal of generating results. This is the default set of flags. When making changes to the Swiftest source code, it is best to compile Swiftest using the debug set of flags. You may also define your own set of compiler flags. -To build Swiftest with the release flags (default) using the Intel fortran compiler (ifort), type the following: +Navigate to the topmost directory in your Swiftest repository. It is best practice to create a ```build``` directory in your topmost directory from which you will compile Swiftest. This way, temporary CMake files will not clutter up the ```swiftest/src/``` sub-directories. The commands to build the source code into a ```build``` directory and compile Swiftest are: + ``` -$ cmake .. +$ cmake -B build -S . +$ cmake --build build ``` -To build with the debug flags, type: +The [CMake Fortran template](https://github.com/SethMMorton/cmake_fortran_template) comes with a script that can be used to clean out any build artifacts and start from scratch: + ``` -$ cmake .. -DCMAKE_BUILD_TYPE=DEBUG +$ cmake -P distclean.cmake ``` -To build with another set of flags, simply replace ```DEBUG``` in the above line with the name of the flags you wish to use. -Add ```-CMAKE_PREFIX_PATH=/path/to/netcdf/``` to these commands as needed. +The Swiftest CMake configuration comes with several customization options: + +| Option | CMake command | +| --------------------------------|------------------------------------------------------------| +| Build type | \-DCMAKE_BUILD_TYPE=[**RELEASE**\|DEBUG\|TESTING\|PROFILE] | +| Enable/Disable OpenMP support | \-DUSE_OPENMP=[**ON**\|OFF] | +| Enable/Disable SIMD directives | \-DUSE_SIMD=[**ON**\|OFF] | +| Enable/Disable Coarray support (experimental) | \-DUSE_COARRAY=[ON\|**OFF**] | +| Set Fortran compiler path | \-DCMAKE_Fortran_COMPILER=/path/to/fortran/compiler | +| Set path to make program | \-DCMAKE_MAKE_PROGRAM=/path/to/make | +| Enable/Disable shared libraries (Intel only) | \-DBUILD_SHARED_LIBS=[**ON\|OFF] | -If using the GCC fortran compiler (gfortran), add the following flags: -``` --DCMAKE_Fortran_FLAGS="-I/usr/lib64/gfortran/modules/ -ffree-line-length-512" -``` -You can manually specify the compiler you wish to use with the following flag: -``` -c-DCMAKE_Fortran_COMPILER=$(which ifort) -``` -After building Swiftest, make the executable using: +To see a list of all possible options available to CMake: ``` -$ make +$ cmake -B build -S . -LA ``` -The Swiftest executable, called ```swiftest_driver```, should now be created in the ```/swiftest/bin/``` directory. +The Swiftest executable, called ```swiftest_driver```, should now be created in the ```bin/``` directory. + + **Download the `swiftest_driver` as a Docker or Singularity container.**