makefile

From WikiROMS
Jump to: navigation, search
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.

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 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.
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.