--- MITgcm/doc/devel_HOWTO.sgml 2003/11/20 00:01:42 1.4 +++ MITgcm/doc/devel_HOWTO.sgml 2003/12/10 20:44:39 1.5 @@ -2,14 +2,6 @@
- - MITgcm Development HOWTO @@ -63,17 +55,17 @@ User Manual - Before jumping into - development, please familiarize yourself with the MITgcm user - manual which is available on the main web page. This - document contains volumes of useful information and is included - here by reference. + Before jumping into development, please familiarize yourself with + the MITgcm user manual + . This document contains volumes of useful information and is + included here by reference. - Also, a "snapshot" orAlso, a "snapshot" or development version of the user manual may be available, though this is only put on the web for testing purposes. + --> @@ -300,10 +292,10 @@ server using: -$ export CVS_RSH=ssh -$ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack' -$ mkdir scratch -$ cvs co MITgcm manual mitgcm.org + $ export CVS_RSH=ssh + $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack' + $ mkdir scratch + $ cvs co MITgcm manual mitgcm.org These commands extract the necessary information from the @@ -371,8 +363,8 @@ site can be built using: -$ cd mitgcm.org/devel/buildweb -$ make All + $ cd mitgcm.org/devel/buildweb + $ make All Which builds the PDF from the LaTeX source, creates the @@ -390,7 +382,7 @@ area: -$ mv scratch/dev_docs /u/u0/httpd/html + $ mv scratch/dev_docs /u/u0/httpd/html and the update is complete. @@ -412,9 +404,9 @@ For MITgcm, the process is similar. Typical commands are: -$ genmake -mods=../code -$ make depend -$ make + $ genmake -mods=../code + $ make depend + $ make The following sections describe the individual steps in the build @@ -448,7 +440,7 @@ simple as: -$ genmake2 -mods=../code + $ genmake2 -mods=../code However, some systems (particularly commercial Unixes that lack a @@ -457,8 +449,8 @@ the following: -$ /usr/bin/sh genmake2 -make=gmake -mods=../code -$ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code + $ /usr/bin/sh genmake2 -make=gmake -mods=../code + $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code The genmake2 code has been written in a Bourne and BASH (v1) @@ -491,7 +483,7 @@ from: -$ genmake2 -help + $ genmake2 -help The most important options for genmake2 are: @@ -547,7 +539,6 @@ specified, then it is assumed that the two packages are compatible and will function either with or without each other. - @@ -562,6 +553,24 @@ + -adof=/path/to/file + -adoptfile=/path/to/file + + This option specifies the "adjoint" or automatic + differentiation options file to be used. The file is analogous + to the "optfile" defined above but it specifies information for + the AD build process. The default file is located in + $ROOTDIR/tools/adjoint_options/adjoint_default and it + defines the "TAF" and "TAMC" compilers. An alternate version is + also available at + $ROOTDIR/tools/adjoint_options/adjoint_staf that selects the + newer "STAF" compiler. As with any compilers, it is helpful to + have their directories listed in your $PATH environment + variable. + + + + -mods=DIR -mods='DIR1 [DIR2 ...]' @@ -615,15 +624,16 @@ - Using <filename>Makefile</> + Using the <filename>Makefile</> - Once a Makefile has been created, one can - build an executable using: + Once a Makefile has been created using + genmake2, one can build a "standard" (forward + simulator) executable using: -$ make CLEAN -$ make depend -$ make + $ make CLEAN + $ make depend + $ make The "make CLEAN" step will remove any stale source files, include @@ -647,10 +657,39 @@ substitutions) custom definitions such as variable types within the source files. This additional stage is necessary in order to overcome some of the inconsistencies in the sizes of objects (bytes) between - different compilers. + different compilers. The result of the build process is an executable + with the name mitgcmuv. + + In addition to the forward simulator described above, the + Makefile also has a number of targets that can be used to + produce various adjoint and tangent-linear builds for optimization and + other parameter-sensitivity problems. The additional targets within + the Makefile are: + + + + + make adall + + This target produces an mitgcmuv_ad executable + using the taf or staf adjoint + compiler. See the genmake2 "-adof" option for + compiler selection. + + + + + make ftlall + + Similar to make adall above, this + produces... + + + + - Please report compilation failures or other problems to - MITgcm-support@mitgcm.org. + Please report any compilation failures or other build problems to + the MITgcm-support@mitgcm.org list. @@ -683,16 +722,16 @@ line as simple as: -$ cd verification -$ ./testreport -ieee + $ cd verification + $ ./testreport -ieee However, some systems (those lacking or wiht a broken "/bin/sh") may require an explicit shell invocation such as: -$ sh ./testreport -ieee -t 'exp0 exp4' -$ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box' + $ sh ./testreport -ieee -t 'exp0 exp4' + $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box' The testreport script accepts a number of