build roms: Difference between revisions

From WikiROMS
Jump to navigationJump to search
← Older edit
No edit summary   (change visibility)
 
(10 intermediate revisions by 2 users not shown)
Line 13: Line 13:
There are two of these build scripts in the '''ROMS/Bin''' directory: '''build_roms.csh''' and '''build_roms.sh'''.  The build scripts use environment variables to provide values for the user-defined [[make]] variables, overwriting those found in the ROMS '''makefile'''. Just as in the multiple '''makefile''' option, you will need as many copies of the build script as you have applications. However, the scope of these variables is local to the build script, allowing you to compile different applications at the same time from the same sources as long as each '''$([[#SCRATCH_DIR|SCRATCH_DIR]])''' is unique.
There are two of these build scripts in the '''ROMS/Bin''' directory: '''build_roms.csh''' and '''build_roms.sh'''.  The build scripts use environment variables to provide values for the user-defined [[make]] variables, overwriting those found in the ROMS '''makefile'''. Just as in the multiple '''makefile''' option, you will need as many copies of the build script as you have applications. However, the scope of these variables is local to the build script, allowing you to compile different applications at the same time from the same sources as long as each '''$([[#SCRATCH_DIR|SCRATCH_DIR]])''' is unique.


:<div class="box">'''Usage:'''<br /><br /><span class="red"> ./build_roms.csh [options]</span><br /><br />'''Options:'''<br /><br /><span class="red">  -j [N]</span>    Compile in parallel using <span class="red">N</span> CPUs<br />                omit argument for all available CPUs.<br /><br /><span class="red">  -p macro</span>  Prints any Makefile macro value. For example,<br /><br />                  build.sh -p FFLAGS<br /><br /><span class="red">  -noclean</span>  Do not clean already compiled objects.<br /><br />'''Example:'''<br /><br /><span class="green">  ./build.sh -j 2</span></div>
:<div class="box">'''Usage:'''<br /><br /><span class="red"> ./build_roms.csh [options]</span><br /><br />'''Options:'''<br /><br /><span class="red">  -j [N]</span>    Compile in parallel using <span class="red">N</span> CPUs<br />                omit argument for all available CPUs.<br /><br /><span class="red">  -p macro</span>  Prints any [[makefile]] variable value. For example,<br /><br />                  build_roms.sh -p FFLAGS<br /><br /><span class="red">  -noclean</span>  Do not clean already compiled objects.<br /><br />'''Example:'''<br /><br /><span class="green">  ./build_roms.sh -j 2</span></div>


==User Definable Configuation Options==
ROMS has a growing list of choices the user must make about the compilation before starting the compile process. These user-defined variables can be set in the build script. Since we use '''gnu make''', it is possible to set the value of these variables in the Unix environment, rather than inside the '''Makefile''' (see [[gmake]]). This page describes the user-definable variables understood by the ROMS '''makefile'''.


==User Definable Compilation Options==
===Application and File Locations===
ROMS has a growing list of choices the user must make about the compilation before starting the compile process. These user-defined variables can be set in the build script. Since we use '''gnu make''', it is possible to set the value of these variables in the Unix environment, rather than inside the '''Makefile''' (see [[gmake]]). The user-definable variables understood by the ROMS '''makefile''' are:
 


<section begin=ROMS_APPLICATION />;<span id="ROMS_APPLICATION"></span>[[ROMS_APPLICATION]]
<section begin=ROMS_APPLICATION />;<span id="ROMS_APPLICATION"></span>[[ROMS_APPLICATION]]
Line 39: Line 39:
: Directory where [[make]] can find your system/compiler specific mk include files as described in [[#FORT|FORT]]. In some situations you will need to edit the appropriate mk file in the Compilers directory (i.e. '''Compilers/Linux-gfortran.mk'''). Rather than editing the mk files released with ROMS and possibly creating conflicts during updates, we suggest that you copy the appropriate system specific mk file and the '''Compilers/make_macros.mk''' to another folder and set [[COMPILERS]] to that folder.<section end=COMPILERS />
: Directory where [[make]] can find your system/compiler specific mk include files as described in [[#FORT|FORT]]. In some situations you will need to edit the appropriate mk file in the Compilers directory (i.e. '''Compilers/Linux-gfortran.mk'''). Rather than editing the mk files released with ROMS and possibly creating conflicts during updates, we suggest that you copy the appropriate system specific mk file and the '''Compilers/make_macros.mk''' to another folder and set [[COMPILERS]] to that folder.<section end=COMPILERS />


===Dynamic CPP Option Tuning===


<section begin=MY_CPP_FLAGS />;<span id="MY_CPP_FLAGS"></span>[[MY_CPP_FLAGS]]
<section begin=MY_CPP_FLAGS />;<span id="MY_CPP_FLAGS"></span>[[MY_CPP_FLAGS]]
: Additional CPP options to activate.  Sometimes it is desirable to activate one or more CPP options to run different variants of the same application without modifying its header file. If this is the case, specify such options here using the '''-D''' syntax. Notice that you need to use your shell's quoting syntax to enclose the definitions. For example:
: Additional CPP options to activate.  Sometimes it is desirable to activate one or more CPP options to run different variants of the same application without modifying its header file. If this is the case, specify such options here using the '''-D''' syntax. Notice that you need to use your shell's quoting syntax to enclose the definitions. For example:
:<div class="box">setenv [[MY_CPP_FLAGS]] "-D[[Options#AVERAGES|AVERAGES]]"<br />setenv [[MY_CPP_FLAGS]] "${[[MY_CPP_FLAGS]]} -D[[Options#ANA_INITIAL|ANA_INITIAL]]"</div>
:<div class="box">setenv [[MY_CPP_FLAGS]] "-D[[Options#AVERAGES|AVERAGES]]"<br />setenv [[MY_CPP_FLAGS]] "${[[MY_CPP_FLAGS]]} -D[[Options#ANA_INITIAL|ANA_INITIAL]]"</div>
:can be use to write time-averaged fields and use analytical initial conditions. Notice that you can have as many definitions as you want by appending values.<section end=MY_CPP_FLAGS />
:can be used to write time-averaged fields and use analytical initial conditions. Notice that you can have as many definitions as you want by appending values.<section end=MY_CPP_FLAGS />


===Compiling Options===


{{warning}}'''Warning:''' Be sure to leave environment variables meant to be off set to an empty string or commented out.  Any string value (including '''off''') will evaluate to '''TRUE''' in conditional if-statements.
{{warning}}'''Warning:''' Be sure to leave environment variables meant to be off set to an empty string or commented out.  Any string value (including '''off''') will evaluate to '''TRUE''' in conditional if-statements.


====Parallel Execution Options====


<section begin=USE_MPI />;<span id="USE_MPI"></span>[[USE_MPI]]
<section begin=USE_MPI />;<span id="USE_MPI"></span>[[USE_MPI]]
Line 64: Line 67:
: Compile your application using OpenMP librairies and compiler options. '''Note:''' you cannot set [[USE_OpenMP]] and [[#USE_MPI|USE_MPI]] at the same time.<section end=USE_OpenMP />
: Compile your application using OpenMP librairies and compiler options. '''Note:''' you cannot set [[USE_OpenMP]] and [[#USE_MPI|USE_MPI]] at the same time.<section end=USE_OpenMP />


====Compiler and Options====


<section begin=FORT />;<span id="FORT"></span>[[FORT]]
<section begin=FORT />;<span id="FORT"></span>[[FORT]]
Line 77: Line 81:
<section begin=USE_LARGE />;<span id="USE_LARGE"></span>[[USE_LARGE]]
<section begin=USE_LARGE />;<span id="USE_LARGE"></span>[[USE_LARGE]]
: If applicable, activate 64-bit compilation.<section end=USE_LARGE />
: If applicable, activate 64-bit compilation.<section end=USE_LARGE />
====Library Types and Executable====
The options in this section allow you to choose whether to build ROMS using a shared or static (or both) library. If you enable both SHARED, STATIC and EXEC, the ROMS executable will automatically choose the shared library (except in cygwin). Building the ROMS executable using the shared library <span class="red">is not recommended</span> because it requires keeping track of the matching libROMS.{so|dylib} which is located in the Build_roms or Build_romsG directory and will be lost and/or replaced with each new build. The option to build the shared version of libROMS is for use in model coupling systems.
{{note}}'''NOTE:''' If both SHARED and STATIC are unset but EXEC is set, ROMS will automatically build with the static library. If all three are unset, ROMS will default to building the roms executable with the static library.
<section begin=SHARED />;<span id="SHARED"></span>[[SHARED]]
: Build the shared library version of libROMS.<section end=SHARED />
<section begin=STATIC />;<span id="STATIC"></span>[[STATIC]]
: Build the static library version of libROMS.<section end=STATIC />
<section begin=EXEC />;<span id="EXEC"></span>[[EXEC]]
: Build the ROMS executable. In most cases you will want this on. The only time this should be off is if you are building the ROMS library for inclusion in a model coupling systems.<section end=EXEC/>
====ROMS I/O Choices====
A more complete description of the available options can be found on the [[IO]] page.  Most users will want to enable at least USE_NETCDF4 because that will instruct the ROMS build system to use nf-config to determine the necessary libraries and paths to link into the ROMS executable.




Line 97: Line 122:
<section begin=USE_HDF5 />;<span id="USE_HDF5"></span>[[USE_HDF5]]
<section begin=USE_HDF5 />;<span id="USE_HDF5"></span>[[USE_HDF5]]
: If any of the coupling components use the HDF5 Fortran API for primary I/O, we need to compile the main driver with the HDF5 Fortran library.<section end=USE_HDF5 />
: If any of the coupling components use the HDF5 Fortran API for primary I/O, we need to compile the main driver with the HDF5 Fortran library.<section end=USE_HDF5 />
====Earth Systems Models (ESM) coupling====
If coupling Earth Systems Models (ESM), set the location of the ESM component libraries and modules. The strategy is to compile and link each ESM component separately first, and then ROMS since it is driving the coupled system. Only the ESM components activated are considered and the rest are ignored.  Some components like WRF cannot be built in a directory specified by the user but in its own root directory, and cannot be moved when debugging with tools like TotalView.




Line 102: Line 130:
: WRF cannot be built in a directory specified by the user; it must be built in its own root directory and cannot be moved when debugging with tools like TotalView. If you wish to couple ROMS with the Earth Systems Model (ESM) WRF, ROMS needs to know the WRF root directory.<section end=WRF_SRC_DIR />
: WRF cannot be built in a directory specified by the user; it must be built in its own root directory and cannot be moved when debugging with tools like TotalView. If you wish to couple ROMS with the Earth Systems Model (ESM) WRF, ROMS needs to know the WRF root directory.<section end=WRF_SRC_DIR />


====Various Path options====


<section begin=USE_MY_LIBS />;<span id="USE_MY_LIBS"></span>[[USE_MY_LIBS]]
<section begin=USE_MY_LIBS />;<span id="USE_MY_LIBS"></span>[[USE_MY_LIBS]]
Line 128: Line 158:
==Build Script Debugging==
==Build Script Debugging==


{{note}}'''Note:''' The build script has the <span class="red">-p</span> option to inquire about any of environmental and local variables used in the [[makefile]] or build scripts. Usefull build commands are:
{{note}}'''Note:''' The build script has the <span class="red">-p</span> option to inquire and report about any of the environmental and local variables used in the [[makefile]] or build scripts. Usefull build commands are:
:<div class="box"><span class="red">build_roms.sh -p</span> '''LIBS'''<br /><span class="red">build_roms.sh -p</span> '''libraries'''<br /><span class="red">build_roms.sh -p</span> '''modules'''<br /><span class="red">build_roms.sh -p</span> '''includes'''<br /><span class="red">build_roms.sh -p</span> '''sources'''<br /><span class="red">build_roms.sh -p</span> '''CPPFLAGS'''<br /><span class="red">build_roms.sh -p</span> '''MY_CPP_FLAGS'''<br /><span class="red">build_roms.sh -p</span> '''MKFILE'''<br /><span class="red">build_roms.sh -p</span> '''FFLAGS'''<br /></div>
:<div class="box"><span class="red">build_roms.sh -p</span> '''LIBS'''<br /><span class="red">build_roms.sh -p</span> '''libraries'''<br /><span class="red">build_roms.sh -p</span> '''modules'''<br /><span class="red">build_roms.sh -p</span> '''includes'''<br /><span class="red">build_roms.sh -p</span> '''sources'''<br /><span class="red">build_roms.sh -p</span> '''CPPFLAGS'''<br /><span class="red">build_roms.sh -p</span> '''MY_CPP_FLAGS'''<br /><span class="red">build_roms.sh -p</span> '''MY_ROOT_DIR'''<br /><span class="red">build_roms.sh -p</span> '''MY_ROMS_SRC'''<br /><span class="red">build_roms.sh -p</span> '''MKFILE'''<br /><span class="red">build_roms.sh -p</span> '''FFLAGS'''<br /></div>
:We highly recommend to use this option to inquire your compiling your environment when having errors during compiling and linking.
:We highly recommend to use this option to inquire your environment when having errors during compiling and linking. For Example:
:<div class="box"><span class="red">build_roms.sh -p</span> '''MKFILE'''<br /><br /><br /><span class="twilightBlue">Using customized library paths from:</span>  <span class="hotPink">/Users/arango/Compilers/ROMS/my_build_paths.sh</span><br /><br /><span class="red">MKFILE</span> = /Users/arango/Compilers/ROMS/Darwin-ifort.mk</div>
:Notice that there is not a compilation, but a report about the value of local [[makefile]] variable <span class="red">MKFILE</span>.


==Library and Executable Paths==
==Library and Executable Paths==

Latest revision as of 16:44, 8 April 2022

GNU Make Build Script - build_roms.csh, build_roms.sh

As mentioned in makefile, you need to provide settings for some user-defined choices before you can compile ROMS. If you have more than one application (or more than one compiler), you may get tired of editing the makefile. One option is to have a makefile for each configuration. The recommended solution, however, is to use the ROMS build script.


Note Note: in SVN revision 1030 (April 30, 2020) the ROMS build scripts (and other shell scripts) were renamed to follow accepted naming conventions; *.sh scripts were changed to *.csh and *.bash where changed to *.sh.



Introduction

There are two of these build scripts in the ROMS/Bin directory: build_roms.csh and build_roms.sh. The build scripts use environment variables to provide values for the user-defined make variables, overwriting those found in the ROMS makefile. Just as in the multiple makefile option, you will need as many copies of the build script as you have applications. However, the scope of these variables is local to the build script, allowing you to compile different applications at the same time from the same sources as long as each $(SCRATCH_DIR) is unique.

Usage:

./build_roms.csh [options]

Options:

-j [N] Compile in parallel using N CPUs
omit argument for all available CPUs.

-p macro Prints any makefile variable value. For example,

build_roms.sh -p FFLAGS

-noclean Do not clean already compiled objects.

Example:

./build_roms.sh -j 2

User Definable Configuation Options

ROMS has a growing list of choices the user must make about the compilation before starting the compile process. These user-defined variables can be set in the build script. Since we use gnu make, it is possible to set the value of these variables in the Unix environment, rather than inside the Makefile (see gmake). This page describes the user-definable variables understood by the ROMS makefile.

Application and File Locations

ROMS_APPLICATION
CPP option defining a particular application (for example, UPWELLING). The makefile will include its associated header file which is located in either the ROMS/Include directory or the path specified in the MY_HEADER_DIR definition. The header file name is the lowercase value of ROMS_APPLICATION with the .h extension (for example, upwelling.h). Recall the CPP option defining an application must be unique.


MY_ROOT_DIR
This path is internal to the build script and has no equivalent in the makefile. It can be used to set the base path to your ROMS source code and/or your application input and output files. This variable is not strictly necessary but can make setting the necessary paths easier.


MY_PROJECT_DIR
This path is internal to the build script and has no equivalent in the makefile. MY_PROJECT_DIR is most often used to set the paths: MY_HEADER_DIR, MY_ANALYTICAL_DIR, and BINDIR and to set the base path to SCRATCH_DIR. This can be seen near the bottom of the build script.


MY_ROMS_SRC
This path is internal to the build script and has no equivalent in the makefile. It is the location of your ROMS source code and is necessary for the build script to work properly.


COMPILERS
Directory where make can find your system/compiler specific mk include files as described in FORT. In some situations you will need to edit the appropriate mk file in the Compilers directory (i.e. Compilers/Linux-gfortran.mk). Rather than editing the mk files released with ROMS and possibly creating conflicts during updates, we suggest that you copy the appropriate system specific mk file and the Compilers/make_macros.mk to another folder and set COMPILERS to that folder.

Dynamic CPP Option Tuning

MY_CPP_FLAGS
Additional CPP options to activate. Sometimes it is desirable to activate one or more CPP options to run different variants of the same application without modifying its header file. If this is the case, specify such options here using the -D syntax. Notice that you need to use your shell's quoting syntax to enclose the definitions. For example:
setenv MY_CPP_FLAGS "-DAVERAGES"
setenv MY_CPP_FLAGS "${MY_CPP_FLAGS} -DANA_INITIAL"
can be used to write time-averaged fields and use analytical initial conditions. Notice that you can have as many definitions as you want by appending values.

Compiling Options

WarningWarning: Be sure to leave environment variables meant to be off set to an empty string or commented out. Any string value (including off) will evaluate to TRUE in conditional if-statements.

Parallel Execution Options

USE_MPI
Compile your application using MPI (distributed-memory) libraries.


USE_MPIF90
If USE_MPI is activated, use this to turn on compilation via the script mpif90. This is needed in most Linux operating systems. In some systems with native MPI libraries the compilation does not require MPICH type scripts. This macro is also convenient when there are several Fortran compiliers (ifort, pgf90, pathf90) in the system that use mpif90. In this case, the user needs to select the desired compiler via the FORT variable and turn on both USE_MPI and USE_MPIF90 macros.


which_MPI
If USE_MPI and USE_MPIF90 are activated, this macro is used to determine which mpif90 to compile with. This macro is convenient when there are several Fortran compiliers (ifort, pgf90, etc.) in the system that use mpif90. The choice of which mpif90 to use will be determined by the combination of this macro and the FORT macro.


USE_OpenMP
Compile your application using OpenMP librairies and compiler options. Note: you cannot set USE_OpenMP and USE_MPI at the same time.

Compiler and Options

FORT
The ROMS make system will include a file with all the settings that depend on the system and the compiler. The name of this file is determined from the output of the uname command and the value of FORT (i.e. Linux-ifort.mk). Set your compiler here from the following list:
Operating System Compiler(s)

AIX: xlf
CYGWIN: df, g95, gfortran, ifort
Darwin: f90, gfortran, ifort, pgi, xlf
IRIX64: f90
Linux: ftn, g95, gfortran, ifc, ifort, necsx, path, pgi
MINGW: g95, gfortran
OSF1: f90
SunOS: f95, ftn
UNICOS-mk: f90
UNICOS-mp: ftn
UNICOS-sk: f90
Feel free to send us additional rule files to include!


USE_DEBUG
Activate debugging compiler options.


USE_LARGE
If applicable, activate 64-bit compilation.

Library Types and Executable

The options in this section allow you to choose whether to build ROMS using a shared or static (or both) library. If you enable both SHARED, STATIC and EXEC, the ROMS executable will automatically choose the shared library (except in cygwin). Building the ROMS executable using the shared library is not recommended because it requires keeping track of the matching libROMS.{so|dylib} which is located in the Build_roms or Build_romsG directory and will be lost and/or replaced with each new build. The option to build the shared version of libROMS is for use in model coupling systems.

NoteNOTE: If both SHARED and STATIC are unset but EXEC is set, ROMS will automatically build with the static library. If all three are unset, ROMS will default to building the roms executable with the static library.


SHARED
Build the shared library version of libROMS.


STATIC
Build the static library version of libROMS.


EXEC
Build the ROMS executable. In most cases you will want this on. The only time this should be off is if you are building the ROMS library for inclusion in a model coupling systems.

ROMS I/O Choices

A more complete description of the available options can be found on the IO page. Most users will want to enable at least USE_NETCDF4 because that will instruct the ROMS build system to use nf-config to determine the necessary libraries and paths to link into the ROMS executable.


USE_NETCDF4
If applicable, link with NetCDF-4 library. Notice that the NetCDF-4 library needs both the HDF5 and, if you want to enable parallel I/O, MPI libraries. In order to write the output files in NetCDF-4/HDF5 format, you will need to set the HDF5 CPP Option.


USE_PARALLEL_IO
Activate parallel I/O using parallel enabled NetCDF-4/HDF5 libraries. You will also need to set the HDF5 and PARALLEL_IO CPP Options to enable parallel I/O.


USE_PIO
Activate parallel I/O using Parallel IO (PIO) libraries developed at NCAR. More information can be found on on the ROMS I/O page.


USE_SCORPIO
Activate parallel I/O using the Software for Caching Output and Reads for Parallel I/O (SCORPIO) library intended for the DOE's Energy Exascale Earth Model System (E3SM). More information can be found on on the ROMS I/O page.


USE_HDF5
If any of the coupling components use the HDF5 Fortran API for primary I/O, we need to compile the main driver with the HDF5 Fortran library.

Earth Systems Models (ESM) coupling

If coupling Earth Systems Models (ESM), set the location of the ESM component libraries and modules. The strategy is to compile and link each ESM component separately first, and then ROMS since it is driving the coupled system. Only the ESM components activated are considered and the rest are ignored. Some components like WRF cannot be built in a directory specified by the user but in its own root directory, and cannot be moved when debugging with tools like TotalView.


WRF_SRC_DIR
WRF cannot be built in a directory specified by the user; it must be built in its own root directory and cannot be moved when debugging with tools like TotalView. If you wish to couple ROMS with the Earth Systems Model (ESM) WRF, ROMS needs to know the WRF root directory.


Various Path options

USE_MY_LIBS
Use custom library paths for ESMF, HDF5, NetCDF libraries, etc.


MY_PATHS
Path to your my_build_paths.csh (or .sh) file that contains custom library paths for your system.


MY_HEADER_DIR
This is the Directory where your application's header file is located. Recall that a ROMS header file contains all the CPP options defining a particular application. This is the header file that is included in cppdefs.h. Notice that if the header file is located in the ROMS/Include directory, it is possible to include the same header file name located somewhere else because the full directory path is specified here. The user may copy the distributed header file(s) into a different directory and modify it to explore different CPP options.


MY_ANALYTICAL_DIR
This is the directory containing the user's analytic files, if any. Templates of the analytic expressions are provided in the User/Functionals directory. If analytic expressions are activated, the makefile will first load the ones located in MY_ANALYTICAL_DIR and then the ones located in ROMS/Functionals. We recommended that you do not modify the analytical expressions in the ROMS/Functionals directory since these are the official versions of these files and updates will conflict with your changes. The user however can modify those in User/Functionals or some other directory and specify which directory with this variable.


BINDIR
Directory where your romsG, romsM, romsO, or romsS executable will be created.


SCRATCH_DIR
Directory where your temporary objects and files will be placed during the build process.

Build Script Debugging

NoteNote: The build script has the -p option to inquire and report about any of the environmental and local variables used in the makefile or build scripts. Usefull build commands are:

build_roms.sh -p LIBS
build_roms.sh -p libraries
build_roms.sh -p modules
build_roms.sh -p includes
build_roms.sh -p sources
build_roms.sh -p CPPFLAGS
build_roms.sh -p MY_CPP_FLAGS
build_roms.sh -p MY_ROOT_DIR
build_roms.sh -p MY_ROMS_SRC
build_roms.sh -p MKFILE
build_roms.sh -p FFLAGS
We highly recommend to use this option to inquire your environment when having errors during compiling and linking. For Example:
build_roms.sh -p MKFILE


Using customized library paths from: /Users/arango/Compilers/ROMS/my_build_paths.sh

MKFILE = /Users/arango/Compilers/ROMS/Darwin-ifort.mk
Notice that there is not a compilation, but a report about the value of local makefile variable MKFILE.

Library and Executable Paths

NoteNote: in SVN revision 933 (January 26, 2019) the custom libraries section was removed from the ROMS build script and placed in Compilers/my_build_paths.csh and Compilers/my_build_paths.sh to both streamline the ROMS build script and make setting up new applications less tedious. More information can be found in ROMS Trac ticket #794. Prior to ROMS release 933, library and executable paths where set in ROMS build script.


The path of the libraries and MPI implementations required by ROMS can be set using environment variables which take precedence over the values specified in the makefile macro definitions file (Compilers/*.mk). If so desired, set USE_MY_LIBS to yes and properly set MY_PATHS. Visit my build paths for more details.

Retrieved from "https://www.myroms.org/wiki/index.php?title=build_roms&oldid=6342"