Difference between revisions of "build roms"

From WikiROMS
Jump to navigationJump to search
Line 34: Line 34:
Currently, the <span class="purple">build.sh</span> sets the following environmental variables:
Currently, the <span class="purple">build.sh</span> sets the following environmental variables:


* Set the CPP option defining the particular application. This will determine the name of the ".h" header file with the application CPP definitions. <div class="box"><span class="blue"> setenv</span> <span class="red">ROMS_APPLICATION</span> [[DOUBLE_GYRE]]</div>
* Set the CPP option defining the particular application. This will determine the name of the ".h" header file with the application CPP definitions. <div class="box"><span class="blue"> setenv</span> <span class="red">ROMS_APPLICATION</span>   [[DOUBLE_GYRE]]</div>


* Set a local environmental variable to define the path to the directories where all this project's files are kept.<div class="box"><span class="blue"> setenv</span> <span class="red">MY_ROOT_DIR</span>   MyRootDir<br /><span class="blue"> setenv</span> <span class="red">MY_PROJECT_DIR</span> ${<span class="red">MY_ROOT_DIR</span>}/Projects</div>
* Set a local environmental variable to define the path to the directories where all this project's files are kept.<div class="box"><span class="blue"> setenv</span> <span class="red">MY_ROOT_DIR</span>       MyRootDir<br /><span class="blue"> setenv</span><span class="red"> MY_PROJECT_DIR</span>     ${<span class="red">MY_ROOT_DIR</span>}/Projects</div>


* Set the path to the user's local current ROMS source code. If using '''svn''' locally, this would be the user's working copy path. Note that one advantage of maintaining your source code locally with '''svn''' is that when working simultaneously on multiple machines (e.g. a local workstation, a local cluster and a remote supercomputer) you can '''checkout''' the latest release and always get an up-to-date customized source on each machine. This script is designed to more easily allow for differing paths to the code and inputs on differing machines. <div class="box"><span class="blue"> setenv</span><span class="red"> MY_ROMS_SRC</span>     MyROMSsrcDir</div>
* Set the path to the user's local current ROMS source code. If using '''svn''' locally, this would be the user's working copy path. Note that one advantage of maintaining your source code locally with '''svn''' is that when working simultaneously on multiple machines (e.g. a local workstation, a local cluster and a remote supercomputer) you can '''checkout''' the latest release and always get an up-to-date customized source on each machine. This script is designed to more easily allow for differing paths to the code and inputs on differing machines. <div class="box"><span class="blue"> setenv</span><span class="red"> MY_ROMS_SRC</span>       MyROMSsrcDir</div>


* Set tunable CPP options. 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 each options here using the '''-D''' syntax. Notice also that you need to use shell's quoting syntax to enclose the definition.  Both single or double quotes works. <div class="box"><span class="blue"> setenv</span> <span class="red" style="padding-right:40px;">MY_CPP_FLAGS</span> "-D[[IS4DVAR]]"</div>to activate the Incremental, 4DVar algorithm in this particular example.
* Set tunable CPP options. 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 each options here using the '''-D''' syntax. Notice also that you need to use shell's quoting syntax to enclose the definition.  Both single or double quotes works. <div class="box"><span class="blue"> setenv</span><span class="red"> MY_CPP_FLAGS</span>       "-D[[IS4DVAR]]"</div>to activate the Incremental, 4DVar algorithm in this particular example.


* Set other [[makefile]] definitions with environmental variables.<div class="box"><span class="blue"> setenv</span><span class="red"> USE_MPI</span>            on<br /><span class="blue"> setenv</span><span class="red"> USE_MPIF90</span>        on<br /><span class="blue"> setenv</span> <span class="red" >FORT</span>              pgi<br /><br /><span class="blue">#setenv</span><span class="red"> USE_DEBUG</span>          on<br /><span class="blue"> setenv</span><span class="red"> USE_ARPACK</span>        on<br /><span class="blue"> setenv</span><span class="red"> USE_LARGE</span>          on<br /></div>
* Set other [[makefile]] definitions with environmental variables.<div class="box"><span class="blue"> setenv</span><span class="red"> USE_MPI</span>            on<br /><span class="blue"> setenv</span><span class="red"> USE_MPIF90</span>        on<br /><span class="blue"> setenv</span> <span class="red" >FORT</span>              pgi<br /><br /><span class="blue">#setenv</span><span class="red"> USE_DEBUG</span>          on<br /><span class="blue"> setenv</span><span class="red"> USE_ARPACK</span>        on<br /><span class="blue"> setenv</span><span class="red"> USE_LARGE</span>          on<br /></div>
Line 46: Line 46:
* Sets the path to the user's header file and analytical source files, if any. See the templates in User/Functionals. <div class="box"><span class="blue"> setenv</span><span class="red"> MY_HEADER_DIR</span>      ${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR<br /><span class="blue">#setenv</span><span class="red"> MY_ANALYTICAL_DIR</span>  MyAnalyticalDir</div>
* Sets the path to the user's header file and analytical source files, if any. See the templates in User/Functionals. <div class="box"><span class="blue"> setenv</span><span class="red"> MY_HEADER_DIR</span>      ${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR<br /><span class="blue">#setenv</span><span class="red"> MY_ANALYTICAL_DIR</span>  MyAnalyticalDir</div>


* Put the binary to execute in the following directory.<div class="box"><span class="blue"> setenv</span> <span class="red" style="padding-right:155px;">BINDIR</span>${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR</div>
* Put the binary to execute in the following directory.<div class="box"><span class="blue"> setenv</span><span class="red"> BINDIR</span>             ${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR</div>


* Put the f90 and other object files in a project specific Build directory to avoid conflict with other projects. <div class="box"><span class="blue"> setenv</span> <span class="red" style="padding-right:83px;">SCRATCH_DIR</span>${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR/Build</div>
* Put the f90 and other object files in a project specific Build directory to avoid conflict with other projects. <div class="box"><span class="blue"> setenv</span><span class="red"> SCRATCH_DIR</span>       ${<span class="red">MY_PROJECT_DIR</span>}/IS4DVAR/Build</div>


* Go to the users source directory to compile. The options set above will pick up the application-specific code from the appropriate place. <div class="box"><span class="blue"> cd</span> ${<span class="red">MY_PROJECT_DIR</span>}</div>
* Go to the users source directory to compile. The options set above will pick up the application-specific code from the appropriate place. <div class="box"><span class="blue"> cd</span> ${<span class="red">MY_PROJECT_DIR</span>}</div>


* If appropriate, remove build directory. <div class="box"><span class="blue"> if ( $clean == 1 ) then</span><br /> <span class="red" style="padding-left:2em;">make clean</span><br /><span class="blue">endif</span></div>
* If appropriate, remove build directory. <div class="box"><span class="blue"> if ( $clean == 1 ) then</span><br /><span class="red">   make clean</span><br /><span class="blue"> endif</span></div>


* Finally, compile application. <div class="box"><span class="blue"> if ( $parallel == 1 ) then</span><br /> <span class="red" style="padding-left:2em;">make $NCPUS</span><br /><span class="blue">else</span><br /><span class="red" style="padding-left:2em;">make</span><br /><span class="blue">endif</span></div>
* Finally, compile application. <div class="box"><span class="blue"> if ( $parallel == 1 ) then</span><br /><span class="red">   make $NCPUS</span><br /><span class="blue"> else</span><br /><span class="red">   make</span><br /><span class="blue"> endif</span></div>

Revision as of 20:43, 15 June 2007

Build Script - build.sh, build.bash

An alternative way to compile and link ROMS is to use the build.sh script located in the ROMS/Bin directory. Instead of editing the makefile often, the user may generate a build script for each of his/her applications. The build script uses environmental variables that overwrite the makefile targets defined with ?= syntax. This means that make will check whether an environment variable by that name is set in the script that calls make. The environmental variable take precedence and overwrites makefile default value. Its scope is local to the build script execution, allowing compiling different applications at the same time. There is not need to maintain separate makefiles, or frequently edit the makefile to run separated applications.

Usage:

./build.sh [options]

Options:

-j [N] Compile in parallel using N CPUs. Omit argument to compile on all availabe CPUs.
-noclean Do not clean already compiled objects.

Example:

./build.sh -j 2

The new structure of ROMS version 3.0 or higher allows user specific CPP definitions and analytical options to be set in a small number of separate standalone header files. Therefore, users no longer have to modify small blocks of code like was neccessary in previous versions of cppdefs.h and analylitical.F. This makes it easy to distribute the configuration for a specific application via a small number of source code related files plus the inputs (grid, initial conditions, and forcing NetCDF files), while allowing users of the application to keep current with central code improvements via svn. This also takes care of all licensing issues. You are free to include your own statement of your contributions in the files you distribute. The license and copyright statements by the ROMS developer group remain in the source code distributed at www.myroms.org.

We recommend users to work with a local source code that is regularly updated with the official version at the ROMS svn repository using svn update. This will allow bug fixes and new code developments to be pushed out to users and minimize the risk of a user unwittingly working with code with known flaws. There are few standalone applications in ROMS website Datasets menu. The user can download any of these set-up. Notice that these applications do not include the source code since the user can checkout the latest version of ROMS from the svn repository. We usually create a Projects root directory containing all applications. For example, the double gyre test case (double_gyre.tar.gz) has the following directory structure:

 Projects                               root directory 
         /double_gyre                   idealized double gyre test case 
                     /Data              input NetCDF files 
                     /Forward           nonlinear model, ensembles 
                     /IS4DVAR           incremental, strong contraint 4DVar 
                     /OBS               data assimilation observations

If you check the IS4DVAR sub-directory, you will find the following files:

 Projects 
          /double_gyre 
                      /IS4DVAR 
                              /build.sh
                              /double_gyre.h
                              /job_is4dvar.sh
                              /is4dvar.in
                              /ocean_double_gyre.in
                              /s4dvar.in

Notice that there is a local copy of the header file double_gyre.h containing the CPP options to use in this application. We highly recommend the user to have a local copy of the header file instead of editing the distributed files in the ROMS/Include directory. During the compilation build.sh will direct make to use the appropriate one.

Environmental Variables

Currently, the build.sh sets the following environmental variables:

  • Set the CPP option defining the particular application. This will determine the name of the ".h" header file with the application CPP definitions.
    setenv ROMS_APPLICATION DOUBLE_GYRE
  • Set a local environmental variable to define the path to the directories where all this project's files are kept.
    setenv MY_ROOT_DIR MyRootDir
    setenv MY_PROJECT_DIR ${MY_ROOT_DIR}/Projects
  • Set the path to the user's local current ROMS source code. If using svn locally, this would be the user's working copy path. Note that one advantage of maintaining your source code locally with svn is that when working simultaneously on multiple machines (e.g. a local workstation, a local cluster and a remote supercomputer) you can checkout the latest release and always get an up-to-date customized source on each machine. This script is designed to more easily allow for differing paths to the code and inputs on differing machines.
    setenv MY_ROMS_SRC MyROMSsrcDir
  • Set tunable CPP options. 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 each options here using the -D syntax. Notice also that you need to use shell's quoting syntax to enclose the definition. Both single or double quotes works.
    setenv MY_CPP_FLAGS "-DIS4DVAR"
    to activate the Incremental, 4DVar algorithm in this particular example.
  • Set other makefile definitions with environmental variables.
    setenv USE_MPI on
    setenv USE_MPIF90 on
    setenv FORT pgi

    #setenv USE_DEBUG on
    setenv USE_ARPACK on
    setenv USE_LARGE on
  • Sets the path to the user's header file and analytical source files, if any. See the templates in User/Functionals.
    setenv MY_HEADER_DIR ${MY_PROJECT_DIR}/IS4DVAR
    #setenv MY_ANALYTICAL_DIR MyAnalyticalDir
  • Put the binary to execute in the following directory.
    setenv BINDIR ${MY_PROJECT_DIR}/IS4DVAR
  • Put the f90 and other object files in a project specific Build directory to avoid conflict with other projects.
    setenv SCRATCH_DIR ${MY_PROJECT_DIR}/IS4DVAR/Build
  • Go to the users source directory to compile. The options set above will pick up the application-specific code from the appropriate place.
    cd ${MY_PROJECT_DIR}
  • If appropriate, remove build directory.
    if ( $clean == 1 ) then
    make clean
    endif
  • Finally, compile application.
    if ( $parallel == 1 ) then
    make $NCPUS
    else
    make
    endif