makefile: Difference between revisions

From WikiROMS
Jump to navigationJump to search
← Older edit
No edit summary   (change visibility)
No edit summary   (change visibility)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="title">makefile</div>
<div class="title">makefile</div>
ROMS has a single '''makefile''' located in the top-level directory. Its generic structure facilitates the compiling of ROMS with other coupled models. The user usually needs to check/modify few definitions in the '''makefile''' before compiling a particular applications to specify application CPP option, header file directory, analytical expression directory, parallel compiling options, 64-bit floating-point number precision, Fortran compiler, and so on.
{{warning}}<span class="red">Warning: Do not edit the '''makefile'''! Use the [[build Script]].</span> This page is for informational purposes only and is not a guide for compiling ROMS source code.


This '''makefile''' builds the compiled objects in the specified scratch directory. It determines the compiling depedencies using the [[sfmakedepend]] script located in the ROMS/Bin directory. Notice that the '''makefile''' time modification in your computer is used by '''make''' to check if the dependencies are needed. If you set the definitions below with enviromental variables you need to execute '''make clean''' always. Otherwise, you will compile the incorrect code.


==User Changes to '''makefile'''==
ROMS has a single '''makefile''' located in the top-level directory. Its generic structure facilitates the compiling of ROMS with other coupled models. The user usually needs to check/modify a few definitions in the '''makefile''' or the [[build Script]] before compiling a particular application. The list of the user options is given below.


As a user, you need to check and perhaps edit the '''makefile''' to set a value or leave blank few macro definitions. Notice that the macro definitions below use the '''?=''' assigment so the environmental value has precedence. The '''makefile''' will set the value only if there is no value defined somewhere else. This is very convient and used in the compiling script [[build.sh]] located in the ROMS/Bin directory.  
This '''makefile''' builds the compiled objects in the specified build directory. It determines the compiling depedencies using the [[sfmakedepend]] script located in the '''ROMS/Bin''' directory. Notice that the '''makefile''' time modification in your computer is used by '''make''' to check if the dependencies need to be updated. If you set the definitions below through a [[build Script]], you need to execute '''make clean''' whenever changes to the user options are made.


;'''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.  
All the other gory details of the '''makefile''' are covered in [[gmake]].


;'''MY_HEADER_DIR ?=''': Application header file '''full''' directory path. Recall that a ROMS header file contains all the CPP options defining a particular application. This is the header file that it 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. This is very convient. The user may copy the distributed header file(s) into a different directory and modify it to explore different CPP options. 
==Environment Variables in the '''makefile'''==


;'''MY_ANALYTICAL_DIR ?=''': Directory containing an application analytical expressions, if any. Templates of the analytical expressions are provided in the User/Functional directory. If analytical expressions are activated, the makefile will load first the ones located in '''MY_ANALYTICAL_DIR''' and then the ones located in ROMS/Functionals. We recommended to not modify the analytical expressions in the ROMS/Functionals directory since these are the official version of these files and reported in the literature.  The user however can modify these expresions somewhere else in the directory path specified here.
ROMS has a growing list of choices the user must make about the  compilation before starting the compile process, set in user-defined variables. Since we now use '''gnu make''', it is possible to set the value of these variables in the Unix environment, rather than necessarily inside the '''Makefile''' (see [[gmake]]). The user-definable variables understood by the ROMS '''makefile''' are:


;'''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. For example, to write out time-averaged NetCDF file use '''-D'''[[AVERAGES]].
<section begin=ROMS_APPLICATION />;<span id="ROMS_APPLICATION"></span>[[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.<section end=ROMS_APPLICATION />


;'''NestedGrids ?=''': Number of ROMS nested and/or composed grids. The default value is 1. Currently, only one grid is supported. This definition is needed always since it used to dynamically allocate all ROMS arrays structures.
<section begin=MY_HEADER_DIR />;<span id="MY_HEADER_DIR"></span>[[MY_HEADER_DIR]]
: Application header file '''full''' directory path. Recall that a ROMS header file contains all the CPP options defining a particular application. This is the header file that it 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.<section end=MY_HEADER_DIR />


;'''USE_DEBUG ?=''': Used to turn on symbolic debug information with no optimization. Set it to '''on''' or leave it blank.
<section begin=MY_ANALYTICAL_DIR />;<span id="MY_ANALYTICAL_DIR"></span>[[MY_ANALYTICAL_DIR]]
: Directory containing the user's [[Functionals | analytic files]], if any. Templates of the analytic expressions are provided in the '''User/Functionals''' directory. If analytic expressions are activated, the makefile will load first 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 version of these files and updates will fight with your changes.  The user however can modify those in '''User/Functionals''' or some other directory and specify which directory with this variable.<section end=MY_ANALYTICAL_DIR />
 
<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. For example, to write out time-averaged NetCDF file use '''-D'''[[AVERAGES]].<section end=MY_CPP_FLAGS />
 
<section begin=NestedGrids />;<span id="NestedGrids"></span>[[NestedGrids]]
: Number of ROMS nested and/or composed grids, usually 1.<section end=NestedGrids />
 
===Compiler-Specific Options===
 
These flags are used by the files inside the '''Compilers''' directory.
 
<section begin=USE_DEBUG />;<span id="USE_DEBUG"></span>[[USE_DEBUG]]
: Used to turn on symbolic debug information with no optimization. Set it to '''on''' or leave it blank.<section end=USE_DEBUG />
   
   
;'''USE_MPI ?=''':  Used to turn on distributed-memory parallelization in ROMS and linking to the [http://www.llnl.gov/computing/tutorials/mpi/ Message Passing Interface (MPI)] library. Set it to '''on''' or leave it blank.
<section begin=USE_MPI />;<span id="USE_MPI"></span>[[USE_MPI]]
:  Used to turn on distributed-memory parallelization in ROMS and linking to the [http://www.llnl.gov/computing/tutorials/mpi/ Message Passing Interface (MPI)] library. Set it to '''on''' or leave it blank.<section end=USE_MPI />
 
<section begin=USE_MPIF90 />;<span id="USE_MPIF90"></span>[[USE_MPIF90]]
: Used to turn on the [http://www-unix.mcs.anl.gov/mpi/mpich1 MPICH] implementation of MPI via the compilation script '''mpif90''' which is  required in some Linux operating systems without a native MPI library ('''-lmpi'''). This definition macro is also convenient when there are several Fortran-90 compilers ('''ifort''', '''pgf90''', '''pathf90''') in the system that use the '''mpif90''' compilation command. In this case, the user needs turn on both '''MPI''' and '''MPIF90''' definitions and specify the appropriate Fortran-90 compiler in '''FORT''' macro definition. Set it to '''on''' or leave it blank.<section end=USE_MPIF90 />
 
<section begin=USE_OPENMP />;<span id="USE_OPENMP"></span>[[USE_OPENMP]]
: Used to turn on shared-memory parallelization in ROMS using the [http://www.llnl.gov/computing/tutorials/openMP/ OpenMP] compiler directives. Set it to '''on''' or leave it blank.<section end=USE_OPENMP />


;'''USE_MPIF90 ?=''': Used to turn on the [http://www-unix.mcs.anl.gov/mpi/mpich1 MPICH] implementation of MPI via the compilation script '''mpif90''' which is  required in some Linux operating systems without a native MPI library ('''-lmpi'''). This definition macro is also convinient when there are several Fortran-90 compilers ('''ifort''', '''pgf90''', '''pathf90''') in the system that use the '''mpif90''' compilation command. In this case, the user needs turn on both '''MPI''' and '''MPIF90''' definitions and specify the appropriate Fortran-90 compiler in '''FORTRAN''' macro definition. Set it to '''on''' or leave it blank.
<section begin=USE_LARGE />;<span id="USE_LARGE"></span>[[USE_LARGE]]
: Used to turn on 64-bit floating-point number precision. Set it to '''on''' or leave it blank.<section end=USE_LARGE />


;'''USE_OPENMP ?=''': Used to turn on shared-memory parallelization in ROMS using the [http://www.llnl.gov/computing/tutorials/openMP/ OpenMP] compiler directives. Set it to '''on''' or leave it blank.
<section begin=NETCDF_INCDIR />;<span id="NETCDF_INCDIR"></span>[[NETCDF_INCDIR]]
: The location of the '''netcdf.mod''' and '''typesizes.mod''' files from [http://www.unidata.ucar.edu/software/netcdf/ NetCDF].<section end=NETCDF_INCDIR />


;'''USE_ARPACK ?=''': Used to turn on linking to the [http://www.caam.rice.edu/software/ARPACK/ ARPACK] library which is used to solve large Ritz eigenvalue problems in the adjoint-based Generalized Stability Theory (GST) analysis and 4Dvar preconditioning. Set it to '''on''' or leave it blank.
<section begin=NETCDF_LIBDIR />;<span id="NETCDF_LIBDIR"></span>[[NETCDF_LIBDIR]]
: The location of the [http://www.unidata.ucar.edu/software/netcdf/ NetCDF] library.<section end=NETCDF_LIBDIR />


;'''USE_LARGE ?=''': Used to turn on 64-bit floating-point number precision. Set it to '''on''' or leave it blank.
<section begin=USE_NETCDF4 />;<span id="USE_NETCDF4"></span>[[USE_NETCDF4]]
: Set this to '''on''' if linking against the NetCDF4 library, which needs the [http://hdfgroup.com/HDF5/ HDF5] library and therefore:<section end=USE_NETCDF4 />


;'''SWAN_COUPLE ?=''': Used to turn coupling to the SWAN model. Set it to '''on''' or leave it blank.
<section begin=HDF5_LIBDIR />;<span id="HDF5_LIBDIR"></span>[[HDF5_LIBDIR]]
: The location of the [http://hdfgroup.com/HDF5/ HDF5] library.<section end=HDF5_LIBDIR />


<section begin=FORT />;<span id="FORT"></span>[[FORT]]
The user also needs to specify the appropriate Fortran-90 compiler to use.  The name of the Fortran-90 compiler depends on the operating system (see table below). This name is also used to determine the compiling configuration file to include in the '''makefile''' by concatenating the operating system ('''uname -s''') and the chosen compiler name.
The user also needs to specify the appropriate Fortran-90 compiler to use.  The name of the Fortran-90 compiler depends on the operating system (see table below). This name is also used to determine the compiling configuration file to include in the '''makefile''' by concatenating the operating system ('''uname -s''') and the chosen compiler name.


Line 64: Line 92:
|}
|}


;'''FORT ?=''': Set the Fortran-90 compiler to use.
Note that others can be added as needed, using the existing files as templates.<section end=FORT />
 
===Local File Options===
<section begin=BINDIR />;<span id="BINDIR"></span>[[BINDIR]]
: Directory path for the compiled executable.<section end=BINDIR />


;'''BINDIR ?=''': Set directory path for the compiled executable.
<section begin=BUILD_DIR />;<span id="BUILD_DIR"></span>[[BUILD_DIR]] (Fromerly SCRATCH_DIR)
: Directory for '''make''' temporary objects. By default it is set to '''Build'''. If building several projects simultaneously, you need to specify different values for each project.  Otherwise, you will compile the wrong files. This directory and the files within are removed when executing a '''make clean'''.<section end=BUILD_DIR />


;'''SCRATCH_DIR ?=''': Set directory for temporary objects. By default it is set to '''Build'''. If building several projects simultaneously, you need to specify different values for each project.  Otherwise, you will compile the wrong files. This directoy and the files within are removed whe executing a '''make clean'''.
==Providing the Environment==


See [[Gmake#Top_Level_Makefile | gmake]] for additional documentation.
Before compiling, you will need to find out some background information:
#What is the name of your compiler?
#What is returned by '''uname -s''' on your system?
#Is there a working NetCDF library?
#Where is it?
#Was it built with the above compiler?
#Do you have access to MPI or OpenMP?
As described more fully in [[gmake]], the '''makefile''' will be looking for a file in the '''Compilers''' directory with the combination of your operating system and your compiler. For instance, using Linux and the Pathscale compiler, the file would be called '''Linux-path.mk'''. Is the corresponding file for your system and compiler in the '''Compilers''' directory? If not, you will have to create it following the existing examples there.


==Compiler-dependent Changes==
Next, there are two ways to provide the location for the NetCDF files (and optional HDF5 library). One is by editing the corresponding lines in your system-compiler file. Another way is through the Unix environment variables. If you are always going to be using the same compiler on each system, you can edit your '''.profile''' or '''.login''' files to globally set them. Here is an example for '''tcsh''':
  setenv NETCDF_INCDIR /usr/local/netcdf4/include
  setenv NETCDF_LIBDIR /usr/local/netcdf4/lib
  setenv HDF5_LIBDIR /usr/local/hdf5/lib
The '''ksh/bash''' equivalent is:
  export NETCDF_INCDIR=/usr/local/netcdf4/include
  export NETCDF_LIBDIR=/usr/local/netcdf4/lib
  export HDF5_LIBDIR=/usr/local/hdf5/lib


Also as a user, you need to be aware of the files in the '''Compilers''' directory. The top-level '''makefile''' will be including one of these files, based on combining the result of '''uname -s''' with the value of '''FORT'''. For instance, it might be including '''Darwin-gfortran.mk''' if you are on a Mac and using the '''gfortran''' compiler. You need to make sure this file exists and has the correct values for the compiler options and for finding the [http://www.unidata.ucar.edu/software/netcdf/ NetCDF] library. The file should contain pointers to both the '''NetCDF library''' and '''include''' files. If the library is different for '''32-bit''' and '''64-bit''' options, that needs to be taken care of as well. See [[Gmake#Conditionals]] for an example.
For the rest, move on to [[build Script]].

Latest revision as of 18:11, 24 January 2024

makefile

WarningWarning: Do not edit the makefile! Use the build Script. This page is for informational purposes only and is not a guide for compiling ROMS source code.


ROMS has a single makefile located in the top-level directory. Its generic structure facilitates the compiling of ROMS with other coupled models. The user usually needs to check/modify a few definitions in the makefile or the build Script before compiling a particular application. The list of the user options is given below.

This makefile builds the compiled objects in the specified build directory. It determines the compiling depedencies using the sfmakedepend script located in the ROMS/Bin directory. Notice that the makefile time modification in your computer is used by make to check if the dependencies need to be updated. If you set the definitions below through a build Script, you need to execute make clean whenever changes to the user options are made.

All the other gory details of the makefile are covered in gmake.

Environment Variables in the makefile

ROMS has a growing list of choices the user must make about the compilation before starting the compile process, set in user-defined variables. Since we now use gnu make, it is possible to set the value of these variables in the Unix environment, rather than necessarily inside the Makefile (see gmake). The user-definable variables understood by the ROMS makefile are:

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_HEADER_DIR
Application header file full directory path. Recall that a ROMS header file contains all the CPP options defining a particular application. This is the header file that it 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
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 load first 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 version of these files and updates will fight with your changes. The user however can modify those in User/Functionals or some other directory and specify which directory with this variable.
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. For example, to write out time-averaged NetCDF file use -DAVERAGES.
NestedGrids
Number of ROMS nested and/or composed grids, usually 1.

Compiler-Specific Options

These flags are used by the files inside the Compilers directory.

USE_DEBUG
Used to turn on symbolic debug information with no optimization. Set it to on or leave it blank.
USE_MPI
Used to turn on distributed-memory parallelization in ROMS and linking to the Message Passing Interface (MPI) library. Set it to on or leave it blank.
USE_MPIF90
Used to turn on the MPICH implementation of MPI via the compilation script mpif90 which is required in some Linux operating systems without a native MPI library (-lmpi). This definition macro is also convenient when there are several Fortran-90 compilers (ifort, pgf90, pathf90) in the system that use the mpif90 compilation command. In this case, the user needs turn on both MPI and MPIF90 definitions and specify the appropriate Fortran-90 compiler in FORT macro definition. Set it to on or leave it blank.
USE_OPENMP
Used to turn on shared-memory parallelization in ROMS using the OpenMP compiler directives. Set it to on or leave it blank.
USE_LARGE
Used to turn on 64-bit floating-point number precision. Set it to on or leave it blank.
NETCDF_INCDIR
The location of the netcdf.mod and typesizes.mod files from NetCDF.
NETCDF_LIBDIR
The location of the NetCDF library.
USE_NETCDF4
Set this to on if linking against the NetCDF4 library, which needs the HDF5 library and therefore:
HDF5_LIBDIR
The location of the HDF5 library.
FORT

The user also needs to specify the appropriate Fortran-90 compiler to use. The name of the Fortran-90 compiler depends on the operating system (see table below). This name is also used to determine the compiling configuration file to include in the makefile by concatenating the operating system (uname -s) and the chosen compiler name.

Operating System Compiler(s)
AIX xlf
ALPHA f90
CYGWIN g95, df, ifort
Darwin f90, gfortran, xlf
Linux ftn, ifc, ifort, pgi, path, g95, gfortran
SunOS f95
SunOS/Linus ftn
UNICOS-mp ftn

Note that others can be added as needed, using the existing files as templates.

Local File Options

BINDIR
Directory path for the compiled executable.
BUILD_DIR (Fromerly SCRATCH_DIR)
Directory for make temporary objects. By default it is set to Build. If building several projects simultaneously, you need to specify different values for each project. Otherwise, you will compile the wrong files. This directory and the files within are removed when executing a make clean.

Providing the Environment

Before compiling, you will need to find out some background information:

  1. What is the name of your compiler?
  2. What is returned by uname -s on your system?
  3. Is there a working NetCDF library?
  4. Where is it?
  5. Was it built with the above compiler?
  6. Do you have access to MPI or OpenMP?

As described more fully in gmake, the makefile will be looking for a file in the Compilers directory with the combination of your operating system and your compiler. For instance, using Linux and the Pathscale compiler, the file would be called Linux-path.mk. Is the corresponding file for your system and compiler in the Compilers directory? If not, you will have to create it following the existing examples there.

Next, there are two ways to provide the location for the NetCDF files (and optional HDF5 library). One is by editing the corresponding lines in your system-compiler file. Another way is through the Unix environment variables. If you are always going to be using the same compiler on each system, you can edit your .profile or .login files to globally set them. Here is an example for tcsh: 

 setenv NETCDF_INCDIR /usr/local/netcdf4/include
 setenv NETCDF_LIBDIR /usr/local/netcdf4/lib
 setenv HDF5_LIBDIR /usr/local/hdf5/lib

The ksh/bash equivalent is: 

 export NETCDF_INCDIR=/usr/local/netcdf4/include
 export NETCDF_LIBDIR=/usr/local/netcdf4/lib
 export HDF5_LIBDIR=/usr/local/hdf5/lib

For the rest, move on to build Script.

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