/[MITgcm]/MITgcm/doc/devel_HOWTO.sgml
ViewVC logotype

Annotation of /MITgcm/doc/devel_HOWTO.sgml

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph

Revision 1.12 - (hide annotations) (download) (as text)
Tue Apr 27 04:03:45 2010 UTC (13 years, 11 months ago) by dimitri
Branch: MAIN
CVS Tags: checkpoint62f
Changes since 1.11: +5 -7 lines
File MIME type: text/x-sgml 
Removed reference to outdated "ecco-branch" in "3.2. Branches".
1 edhill 1.1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2    
3     <article id="MITgcm-Development-HOWTO">
4    
5     <articleinfo>
6     <title>MITgcm Development HOWTO</title>
7    
8     <author>
9     <firstname>Ed</firstname>
10     <surname>Hill III</surname>
11     <affiliation>
12     <address><email>eh3@mit.edu</email></address>
13     </affiliation>
14     </author>
15    
16     <revhistory>
17     <revision>
18     <revnumber>0.01</revnumber>
19 edhill 1.2 <date>2003-08-07</date>
20 edhill 1.1 <authorinitials>eh3</authorinitials>
21     <revremark>
22     Initial version.
23     </revremark>
24     </revision>
25 jmc 1.10 <revision>
26     <revnumber>0.02</revnumber>
27     <date>2010-01-21</date>
28     <authorinitials>jmc</authorinitials>
29     <revremark>
30     update links.
31     </revremark>
32     </revision>
33 jmc 1.11 <revision>
34     <revnumber>0.03</revnumber>
35     <date>2010-04-25</date>
36     <authorinitials>jmc</authorinitials>
37     <revremark>
38     Add subsection "Developer settings" (under CVS Repository).
39     </revremark>
40     </revision>
41 edhill 1.1 </revhistory>
42    
43     <abstract>
44     <para>This document describes how to develop software for the
45     MITgcm project.</para>
46     </abstract>
47     </articleinfo>
48    
49     <sect1 id="intro">
50     <title>Introduction</title> <para>The purpose of this document is
51     to help new developers get "up to speed" with MITgcm
52     development.</para>
53     <sect2>
54     <title>New Versions of This Document</title> <para>You can
55     obtain the latest version of this document <ulink
56 jmc 1.10 url="http://mitgcm.org/public/docs.html">online</ulink> in
57 edhill 1.1 various formats.</para>
58     </sect2>
59     <sect2>
60     <title>Feedback and corrections</title> <para>If you have
61     questions or comments about this document, please feel free to
62     <ulink url="mailto:MITgcm-support@mitgcm.org">contact the
63     authors</ulink>.
64     </para>
65     </sect2>
66     </sect1>
67    
68     <sect1 id="background">
69     <title>Background</title>
70    
71     <sect2>
72     <title>User Manual</title>
73    
74 edhill 1.5 <para>Before jumping into development, please familiarize yourself with
75 jmc 1.10 the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
76 edhill 1.5 </ulink>. This document contains volumes of useful information and is
77     included here by reference.</para>
78 edhill 1.1
79 edhill 1.5 <!--
80     <para>Also, a "snapshot" or <ulink
81 edhill 1.1 url="http://mitgcm.org/dev_docs/">development version</ulink> of
82     the user manual may be available, though this is only put on the
83     web for testing purposes.</para>
84 edhill 1.5 -->
85 edhill 1.1 </sect2>
86    
87     <sect2>
88     <title>Prerequisites</title> <para>To develop for MITgcm project
89     you will need a UNIX or UNIX-like set of build tools including
90     the following:</para>
91     <blockquote>
92     <simplelist type="inline">
93     <member>CVS client</member>
94     <member>make or (preferably) GNU make</member>
95     <member>FORTRAN compiler</member>
96     <member>C compiler</member>
97     <member>[ba]sh and [t]csh shells</member>
98     <member>PERL</member>
99     <member>LaTeX and LaTeX2HTML</member>
100     </simplelist>
101     </blockquote>
102     <para>Essentially all of the work described here has been tested
103     on recent versions of Red Hat Linux (eg. 7.3 through 9). Except
104     where noted, all shell commands will be provided using bash
105     syntax.
106     </para>
107     </sect2>
108    
109     </sect1>
110    
111     <sect1 id="cvs">
112     <title>CVS Repository</title>
113 jmc 1.11
114 edhill 1.1 <sect2>
115     <title>Layout</title>
116    
117     <para>Unlike many open source projects, the MITgcm CVS tree does
118     not follow a simple "src", "docs", "share", and "test" directory
119     layout. Instead, there are multiple higher-level directories
120     that each, to some extent, depend upon the presence of the
121     others. The tree currently resembles:</para>
122    
123     <programlisting>gcmpack/
124     CS-regrid goes into utils
125 jmc 1.11 CVSROOT -hidden-
126 edhill 1.1
127     MITgcm code
128 jmc 1.11 bin empty
129     doc basic developpment documentation
130     eesupp execution environment support code (wrapper)
131     exe empty
132     jobs runtime shell scripts for
133     various platforms (not maintained)
134     lsopt line search
135     model main dynamics (core)
136     optim line search interface
137     pkg alternate and optional numerics, etc.
138     tools scripts to build (and test)
139     utils pre/post processing tools (matlab, ..)
140     verification standard regression tests + examples
141     + documented examples (tutorials)
142     tutorial_examples (only in release1 branch)
143 edhill 1.1
144 jmc 1.11 MITgcm_contrib contributed code
145 edhill 1.1
146 jmc 1.11 acesgrid.org build acesgrid web site
147     development experimental stuff
148     gcmpack an old back-up copy ?
149     gfd_lab -?-
150     manual -save-
151     misc -?-
152 edhill 1.1 mitgcm.org build web site
153 jmc 1.11 mitgcmdoc -> manual -remove-
154 edhill 1.1 models -?-
155     packages -?-
156 jmc 1.11 pdfs some pdfs
157     planetinabottle.org unfinished web site
158 edhill 1.1 preprocess -?-
159     tmp -?-
160 jmc 1.11 www.ecco-group.org build ecco web site ?
161 edhill 1.1 </programlisting>
162    
163 jmc 1.11 <!--
164 edhill 1.1 <para>Efforts are underway to reduce the complexity.</para>
165 jmc 1.11 -->
166 edhill 1.1
167     </sect2>
168    
169     <!--
170     <sect2>
171     <title>Releases</title> <para>Currently, there are two main
172     branches:</para>
173     <itemizedlist mark="bullet">
174     <listitem>
175     <para>Development</para>
176     <itemizedlist mark="bullet">
177     <listitem>
178     <para>MAIN</para>
179     </listitem>
180     <listitem>
181     <para>ecco-branch</para>
182     </listitem>
183     </itemizedlist>
184     </listitem>
185     <listitem>
186     <para>Production</para>
187     <itemizedlist mark="bullet">
188     <listitem>
189     <para>Release1</para>
190     </listitem>
191     <listitem>
192     <para>Release2</para>
193     </listitem>
194     </itemizedlist>
195     </listitem>
196     </itemizedlist>
197     </sect2>
198     -->
199    
200     <sect2>
201     <title>Branches</title>
202    
203     <para>As shown in the online <ulink
204 jmc 1.11 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph">
205 dimitri 1.12 ViewCVS-generated tree</ulink>, the MITgcm codebase is split into
206     branches or "lines" under which development proceeds. The main line
207     of development is referred to as the "MAIN" version of the code.
208 edhill 1.1 </para>
209    
210     <para>Periodically, a "Release" branch is formed from the "MAIN"
211 edhill 1.7 development branch. This is done in order to create a relatively stable
212     reference point for both users and developers. The intent is that once a
213 dimitri 1.12 release branch has been created, only bug-fixes will be added to it.
214 edhill 1.7 Meanwhile, development (which might "break" or otherwise render invalid
215     the documentation, tutorials, and/or examples contained within a release
216 dimitri 1.12 branch) is allowed to continue along the MAIN line.</para>
217 edhill 1.1 </sect2>
218    
219     <sect2>
220 jmc 1.11 <title> Developer settings </title>
221    
222     <para>CVS is a convenient tool to keep up-to-date a personal copy of the
223     MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html">
224     using CVS </ulink>). The same tool is used by developers to
225     incorporate any change into the repository. However, this later
226     function requires specific settings, as detailed here after:</para>
227     <orderedlist>
228     <listitem>
229     <para> You will need an account (loggin access) to the server
230     "mitgcm.org" with the proper group setting (e.g.,
231     group "gcmctrb" to add/modify code into MITgcm_contrib).
232     This kind of account is granted only upon well motivated request.
233     The access to the server mitgcm.org is through ssh-key authorization
234     which will need to be set properly on both side (on your local machine
235     and on your server account). You need to be able to
236     to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
237     in case of different user-name on both sides) to proceed further.</para>
238     </listitem>
239    
240     <listitem>
241     <para> You need to register to the
242     <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs">
243     mitgcm-cvs </ulink> mailing list.
244     This ensures that other developers will receive email notification
245     when you make changes; you will also receive as well such email
246     when others make changes to the repository.
247     </para>
248     </listitem>
249    
250     <listitem>
251     <para> It is highly recommended that you register also to the
252     <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel">
253     mitgcm-devel </ulink> mailing list (expect a short delay for
254     this request to be processed).
255     This list is intended for developer discussions.
256     </para>
257     </listitem>
258    
259     <listitem>
260     <para> The standard anonymous mode (using "cvsanon", as mentionned
261     <ulink url="http://mitgcm.org/public/source_code.html">
262     here </ulink>) does not allow check-in ("cvs commit") permission.
263     Instead, you will need to set our CVS environment as follow:</para>
264     <screen>
265     $ export CVS_RSH=ssh
266     $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
267     </screen>
268     <para> After downloading a directory, e.g.: <filename>myCopy</filename>,
269     from the CVS repository (e.g.,
270     <filename>MITgcm_contrib/thisPart</filename>) using the command:</para>
271     <screen>
272     $ cvs co -P -d myCopy MITgcm_contrib/thisPart
273     </screen>
274     <para> the type of CVS environment which has been used
275     is stored in the file <filename>myCopy/CVS/Root</filename>
276     and makes it difficult to re-use, for cvs-commit purpose,
277     a cvs local copy (<filename>myCopy</filename>) which was obtained
278     using the CVS anonymous mode.</para>
279     </listitem>
280    
281     <listitem>
282     <para> At this stage, you should be able to send your modified source
283     file (e.g., <filename>src_file</filename>) from your local copy directory
284     (<filename>myCopy</filename>) to the CVS repository
285     (<filename>MITgcm_contrib/thisPart</filename>) using the command
286     "cvs commit":</para>
287     <screen>
288     $ cd myCopy
289     $ cvs -n update (optional; check if new changes have been made)
290     $ cvs diff src_file (optional; list your changes)
291     $ cvs commit src_file
292     </screen>
293     <para> It is essential that you provide a short description of the
294     changes you made to <filename>src_file</filename> as you check-in
295     this file (the "cvs commit" command automatically opens your standard
296     editor for this purpose).</para>
297     </listitem>
298    
299     </orderedlist>
300    
301     </sect2>
302    
303     <sect2>
304     <title>Main code development</title>
305     <para>(formerly named "Tagging" ; this section needs an update)</para>
306 edhill 1.1
307 edhill 1.7 <para>The intent of tagging is to create "known-good" checkpoints that
308     developers can use as references. Traditionally, MITgcm tagging has
309     maintained the following conventions:</para>
310 edhill 1.1
311     <orderedlist>
312     <listitem>
313 edhill 1.7 <para>Developer checks out code into a local CVS-managed directory,
314     makes various changes/additions, tests these edits, and eventually
315     reaches a point where (s)he is satisfied that the changes form a new
316     "useful" point in the evolution of the code.</para>
317 edhill 1.1 </listitem>
318    
319     <listitem>
320     <para>The developer then runs the <ulink
321 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
322     testreport</ulink> shell script to see if any problems are introduced.
323 edhill 1.7 While not intended to be exhaustive, the test cases within the
324     verification directory do provide some indication whether gross errors
325     have been introduced.
326 edhill 1.1 </para>
327     </listitem>
328    
329     <listitem>
330     <para>Having satisfied him- or herself that the changes are
331     ready to be committed to the CVS repository, the developer
332     then:</para>
333     <orderedlist>
334     <listitem>
335 edhill 1.7 <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
336     number and Y is a letter) to the <ulink
337 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
338 edhill 1.7 tag-index</ulink> file and checks it into the CVS
339     repository</para>
340 edhill 1.1 </listitem>
341     <listitem>
342 edhill 1.7 <para>submits the set of changes to the CVS repository and adds
343     comments to <filename>tag-index</filename> describing what the
344     changes are along with a matching "checkpointXY_post" entry</para>
345 edhill 1.1 </listitem>
346     </orderedlist>
347     </listitem>
348     </orderedlist>
349    
350 edhill 1.7 <para>The result of this tagging procedure is a sequence of development
351     checkpoints with comments which resembles:</para>
352 edhill 1.1
353     <programlisting>
354     checkpoint50e_post
355     o make KPP work with PTRACERS
356     - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
357     nearly a copy of kpp_transport_s
358     - there is no analogue to SurfaceTendencyS, so I have to use
359     gPtr(of the surface layer) instead
360     o add a new platform SunFire+mpi (SunFire 15000) to genmake
361     checkpoint50e_pre
362    
363     checkpoint50d_post
364     o change kpp output from multiple-record state files to single-record state
365     files analogous to write_state.F
366     o reduce the output frequency of cg3d-related stuff to the monitor frequency,
367     analogous to the cg2d-related output.
368     o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
369     so that writing to internal file fn (with length 512) fails.
370     checkpoint50d_pre
371     </programlisting>
372    
373 edhill 1.7 <para>This information can be used to refer to various stages of the code
374     development. For example, bugs can be traced to individual sets of CVS
375     checkins based upon their first appearance when comparing the results from
376     different checkpoints.</para>
377 edhill 1.1
378     </sect2>
379     </sect1>
380    
381    
382 edhill 1.2 <sect1 id="coding">
383 edhill 1.3 <title>Coding for MITgcm</title>
384    
385     <sect2 id="build_tools">
386     <title>Build Tools</title>
387    
388 edhill 1.4 <para>Many Open Source projects use the "GNU Autotools" to help streamline
389     the build process for various Unix and Unix-like architectures. For a
390     user, the result is the common "configure" (that is,
391     "<filename>./configure && make && make install</filename>") commands.
392     For MITgcm, the process is similar. Typical commands are:</para>
393 edhill 1.3
394     <screen>
395 edhill 1.5 $ genmake -mods=../code
396     $ make depend
397     $ make
398 edhill 1.3 </screen>
399    
400 edhill 1.4 <para>The following sections describe the individual steps in the build
401     process.</para>
402    
403 edhill 1.3 <sect3 id="genmake">
404     <title>The <filename>genmake2</> Utility</title>
405    
406 edhill 1.4 <para><emphasis>Please note that the older <filename>genmake</> is
407     deprecated and will eventually be replaced by <filename>genmake2</>.
408     This HOWTO only describes the newer tool.</emphasis></para>
409    
410     <para>The first step in any MITgcm build is to create a Unix-style
411     <filename>Makefile</filename> which will be parsed by
412     <filename>make</filename> to specify how to compile the MITgcm source
413     files. For more detailed descriptions of what the make tools are and
414     how they are used, please see:</para>
415 edhill 1.3
416     <itemizedlist>
417     <listitem>
418 edhill 1.4 <para><ulink url="http://www.gnu.org/software/make/make.html">
419     http://www.gnu.org/software/make/make.html</></para>
420 edhill 1.3 </listitem>
421     <listitem>
422 edhill 1.4 <para><ulink url="http://www.oreilly.com/catalog/make2/">
423     http://www.oreilly.com/catalog/make2/</></para>
424 edhill 1.3 </listitem>
425     </itemizedlist>
426    
427 edhill 1.4 <para>Genmake can often be invoked successfully with a command line as
428     simple as:</para>
429    
430     <screen>
431 edhill 1.5 $ genmake2 -mods=../code
432 edhill 1.4 </screen>
433    
434     <para>However, some systems (particularly commercial Unixes that lack a
435     more modern "/bin/sh" implementation or that have shells installed in
436     odd locations) may require an explicit shell invocation such as one of
437     the following: </para>
438    
439     <screen>
440 edhill 1.5 $ /usr/bin/sh genmake2 -make=gmake -mods=../code
441     $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
442 edhill 1.4 </screen>
443    
444     <para>The genmake2 code has been written in a Bourne and BASH (v1)
445     compatible syntax so it should work with most "sh" and all recent "bash"
446     implementations.</para>
447    
448     <para>As the name implies, <filename>genmake2</filename> generates a
449     <filename>Makefile</filename>. It does so by first parsing the
450     information supplied from the following sources</para>
451 edhill 1.3
452     <orderedlist>
453     <listitem>
454 jmc 1.6 <para>a <filename>gemake_local</filename> file in the current
455 edhill 1.4 directory</para>
456 edhill 1.3 </listitem>
457     <listitem>
458     <para>directly from command-line options</para>
459     </listitem>
460     <listitem>
461 edhill 1.4 <para>an "options file" as specified by the command-line option
462     <filename>-optfile='FILENAME'</filename></para>
463 edhill 1.3 </listitem>
464     </orderedlist>
465    
466 edhill 1.4 <para>then checking certain dependency rules (the package dependencies),
467     and finally writing a <filename>Makefile</filename> based upon the
468     source code that it finds. For convenience within various Unix
469     shells, <filename>genmake2</> supports both "long"- and "short"-style
470     options. A complete list of the available options can be obtained
471     from:</para>
472 edhill 1.3
473     <screen>
474 edhill 1.5 $ genmake2 -help
475 edhill 1.3 </screen>
476    
477 edhill 1.4 <para>The most important options for <filename>genmake2</> are:</para>
478 edhill 1.3
479     <variablelist>
480    
481     <varlistentry>
482     <term><filename>--optfile=/PATH/FILENAME</></term>
483 edhill 1.4
484 edhill 1.3 <listitem>
485 edhill 1.4 <para>This specifies the "options file" that should be used for a
486     particular build. The options file is a convenient and
487     machine-indepenent way of specifying parameters such as the
488     FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
489     optimization flags (<filename>FFLAGS=</>), and the locations of
490     various platform- and/or machine-specific tools
491     (eg. <filename>MAKEDEPEND=</>). As with <filename>genmake2</>,
492     all options files should be written to be compatible with
493     Bourne--shell ("sh" or "BASH v1") syntax. Examples of various
494     options files can be found in
495     <filename>$ROOTDIR/tools/build_options</>.</para>
496    
497     <para>If no "optfile" is specified (either through the command lin
498     or the environment variable), genmake2 will try to make a
499     reasonable guess from the list provided in
500     <filename>$ROOTDIR/tools/build_options</>. The method used for
501     making this guess is to first determine the combination of
502     operating system and hardware (eg. "linux_ia32") and then find a
503     working Fortran compiler within the user's path. When these
504     three items have been identified, genmake2 will try to find an
505     optfile that has a matching name. </para>
506    
507     <para>Everyone is encouraged to submit their options files to the
508     MITgcm project for inclusion (please send to
509     <email>MITgcm-support@mitgcm.org</email>). We are particularly
510     grateful for options files tested on new or unique
511     platforms!</para>
512 edhill 1.3 </listitem>
513 edhill 1.4
514 edhill 1.3 </varlistentry>
515    
516     <varlistentry>
517     <term><filename>-pdepend=/PATH/FILENAME</></term>
518 edhill 1.4
519 edhill 1.3 <listitem>
520 edhill 1.4 <para>This specifies the dependency file used for packages. If
521     not specified, the default dependency file is
522     <filename>$ROOTDIR/pkg/pkg_depend</>. The syntax for this file is
523     parsed on a line-by-line basis where each line containes either a
524     comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
525     where the "+" or "-" symbol specifies a "must be used with" or a
526     "must not be used with" relationship, respectively. If no rule is
527     specified, then it is assumed that the two packages are compatible
528     and will function either with or without each other.</para>
529 edhill 1.3 </listitem>
530     </varlistentry>
531    
532     <varlistentry>
533     <term><filename>-pdefault=PKG</></term>
534     <term><filename>-pdefault='PKG1 [PKG2 PKG3 ...]'</></term>
535     <listitem>
536     <para>This option specifies the default set of packages
537     to be used. If not set, the default package list will
538     be read from
539     <filename>$ROOTDIR/pkg/pkg_default</>.</para>
540     </listitem>
541     </varlistentry>
542    
543     <varlistentry>
544 edhill 1.5 <term><filename>-adof=/path/to/file</></term>
545     <term><filename>-adoptfile=/path/to/file</></term>
546     <listitem>
547     <para>This option specifies the "adjoint" or automatic
548     differentiation options file to be used. The file is analogous
549     to the "optfile" defined above but it specifies information for
550     the AD build process. The default file is located in <filename>
551     $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
552     defines the "TAF" and "TAMC" compilers. An alternate version is
553     also available at <filename>
554     $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
555     newer "STAF" compiler. As with any compilers, it is helpful to
556     have their directories listed in your $PATH environment
557     variable.</para>
558     </listitem>
559     </varlistentry>
560    
561     <varlistentry>
562 edhill 1.4 <term><filename>-mods=DIR</></term>
563     <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
564 edhill 1.3 <listitem>
565 edhill 1.4 <para>This option specifies a list of directories containing
566     "modifications". These directories contain files with names
567     that may (or may not) exist in the main MITgcm source tree but
568     will be overridden by any identically-named sources within the
569     "MODS" directories. The order of precedence for this
570     "name-hiding" is as follows:</para>
571    
572     <itemizedlist>
573     <listitem><para>"MODS" directories (in the order given)
574     </para></listitem>
575     <listitem><para>Packages either explicitly specified or
576     provided by default (in the order given)</para></listitem>
577     <listitem><para>Packages included due to package dependencies
578     (in the order that that package dependencies are
579     parsed)</para></listitem>
580     <listitem><para>The "standard dirs" (which may have been
581     specified by the "-standarddirs" option)</para></listitem>
582     </itemizedlist>
583    
584     </listitem>
585     </varlistentry>
586    
587     <varlistentry>
588     <term><filename>-make=/path/to/gmake</></term>
589     <listitem>
590     <para>Due to the poor handling of soft-links and other bugs common
591     with the <filename>make</> versions provided by commercial Unix
592     vendors, GNU <filename>make</filename> (sometimes called
593     <filename>gmake</filename>) should be preferred. This option
594     provides a means for specifying the make program to be
595     used.</para>
596 edhill 1.3 </listitem>
597     </varlistentry>
598    
599     </variablelist>
600    
601 edhill 1.4 <para>A successful run of <filename>genmake2</> will produce a
602     <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
603     various convenience files used for the automatic differentiation
604     process.</para>
605    
606     <para>In general, it is best to use <filename>genmake2</> on a "clean"
607     directory that is free of all source (*.[F,f],*.[F,f]90) and header
608     (*.h,*.inc) files. Generally, this can be accomplished in an
609     "un-clean" directory by running "make CLEAN" followed by "make
610     makefile".</para>
611 edhill 1.3
612     </sect3>
613    
614     <sect3 id="makefile_use">
615 edhill 1.5 <title>Using the <filename>Makefile</></title>
616 edhill 1.3
617 edhill 1.5 <para>Once a <filename>Makefile</> has been created using
618     <filename>genmake2</>, one can build a "standard" (forward
619     simulator) executable using:</para>
620 edhill 1.3
621     <screen>
622 edhill 1.5 $ make CLEAN
623     $ make depend
624     $ make
625 edhill 1.3 </screen>
626    
627 edhill 1.4 <para>The "make CLEAN" step will remove any stale source files, include
628     files, and links. It is strongly recommended for "un-clean"
629     directories which may contain the (perhaps partial) results of
630     previous builds. Such "debris" can interfere with the next stage of
631     the build.</para>
632    
633     <para>The "make depend" step will create a large number of symbolic
634     links from the local directory to the source file locations. It also
635     parses these files and creates an extensive list of dependencies
636     within the <filename>Makefile</> itself. The links that exist at this
637     stage are mostly "large F" files (*.F and *.F90) that need to be
638     processed by a C preprocessor ("CPP"). Since "make depend" edits the
639     <filename>Makefile</>, it is important not to skip this step!</para>
640    
641     <para>The final "make" invokes the C preprocessor to produce the "little
642     f" files (*.f and *.f90) and then compiles them to object code using
643     the specified FORTRAN compiler and options. An intermediate script is
644     often used during this stage to further process (usually, make simple
645     substitutions) custom definitions such as variable types within the
646     source files. This additional stage is necessary in order to overcome
647     some of the inconsistencies in the sizes of objects (bytes) between
648 edhill 1.5 different compilers. The result of the build process is an executable
649     with the name <filename>mitgcmuv</>.</para>
650    
651     <para>In addition to the forward simulator described above, the
652     <filename>Makefile</> also has a number of targets that can be used to
653     produce various adjoint and tangent-linear builds for optimization and
654     other parameter-sensitivity problems. The additional targets within
655     the <filename>Makefile</> are:</para>
656    
657     <variablelist>
658    
659     <varlistentry>
660     <term><filename>make adall</></term>
661     <listitem>
662     <para>This target produces an <filename>mitgcmuv_ad</> executable
663     using the <filename>taf</> or <filename>staf</> adjoint
664     compiler. See the <filename>genmake2</> "-adof" option for
665     compiler selection.</para>
666     </listitem>
667     </varlistentry>
668    
669     <varlistentry>
670     <term><filename>make ftlall</></term>
671     <listitem>
672     <para>Similar to <filename>make adall</> above, this
673     produces...</para>
674     </listitem>
675     </varlistentry>
676    
677     </variablelist>
678 edhill 1.3
679 edhill 1.5 <para>Please report any compilation failures or other build problems to
680     the <email>MITgcm-support@mitgcm.org</email> list.</para>
681 edhill 1.3
682     </sect3>
683    
684     </sect2>
685    
686     <sect2 id="verification">
687     <title>The Verification Suite</title>
688    
689 edhill 1.4 <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
690     directory) includes more than a dozen examples intended for regression
691     testing. Each one of these example directories contains "known-good"
692     output files along with all the input (including both code and data
693     files) required for their re-calculation. These example directories are
694     further broken down into sets of subdirectories
695     (eg. <filename>/input</>, <filename>/code</>) intended to expedite the
696     testing process.</para>
697 edhill 1.3
698     <sect3 id="testreport">
699     <title>The <filename>testreport</> Utility</title>
700    
701 edhill 1.4 <para>Also included in <filename>$ROOTDIR/verification/</> are shell
702     scripts for automated testing. The newest script (which was written
703     to work with <filename>genmake2</>) is called <filename>testreport</>.
704     This script can be used to build different versions of the MITgcm
705     code, run the various examples, compare the output, and (if specified)
706     email the results of each one of these tests to a central
707     repository.</para>
708    
709     <para>On some systems, the testreport script can be run with a command
710     line as simple as:</para>
711    
712     <screen>
713 edhill 1.5 $ cd verification
714     $ ./testreport -ieee
715 edhill 1.4 </screen>
716    
717     <para>However, some systems (those lacking or wiht a broken "/bin/sh")
718     may require an explicit shell invocation such as:</para>
719    
720     <screen>
721 edhill 1.5 $ sh ./testreport -ieee -t 'exp0 exp4'
722     $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
723 edhill 1.4 </screen>
724 edhill 1.3
725     <para>The <filename>testreport</> script accepts a number of
726 edhill 1.4 command-line options which can be listed using the <filename>-help</>
727     option. The most important ones are:</para>
728 edhill 1.3
729     <variablelist>
730    
731     <varlistentry>
732 edhill 1.4 <term><filename>-ieee</></term>
733     <listitem>
734     <para>If allowed by the compiler (as defined in the "optfile"),
735     use IEEE arithmetic. This option, along with the GCC compiler,
736     is how the standard results were produced.</para>
737     </listitem>
738     </varlistentry>
739    
740     <varlistentry>
741 edhill 1.3 <term><filename>-tdir TESTDIR</></term>
742     <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
743     <listitem>
744 edhill 1.4 <para>This option specifies the test directory or list of test
745     directories that should be used. Each of these entries should
746     exactly (note: they are case sensitive!) match the names of
747     directries in <filename>$ROOTDIR/verification/</>. If this
748     option is omitted, then all directories that are properly
749     formatted (that is, containing an <filename>input</>
750     sub-directory and a <filename>results/output.txt</> file) will
751     be used.</para>
752 edhill 1.3 </listitem>
753     </varlistentry>
754    
755     <varlistentry>
756     <term><filename>-optfile=/PATH/FILENAME</></term>
757     <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
758     <listitem>
759 edhill 1.4 <para>This specifies a list of "options files" that will be passed
760     to <filename>genmake2</>. If multiple options files are used
761     (say, to test different compilers or different sets of options
762     for the same compiler), then each options file will be used with
763     each of the test directories.</para>
764 edhill 1.3 </listitem>
765     </varlistentry>
766    
767     <varlistentry>
768     <term><filename>-addr EMAIL</></term>
769     <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
770     <listitem>
771     <para>Send the results (namely, <filename>output.txt</>,
772 edhill 1.4 <filename>genmake_local</>, <filename>genmake_state</>, and
773     <filename>Makefile</>) to the specified email addresses. The
774     results are gzipped, placed in a tar file, MIME encoded, and
775     sent to the specified address. If no email addresses are
776     specified, no mail is sent.</para>
777     </listitem>
778     </varlistentry>
779    
780     <varlistentry>
781     <term><filename>-mpi</></term>
782     <listitem>
783     <para>If the necessary files
784     (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and
785     <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an
786     MPI--enabled run. Note that the use of MPI typically requires a
787     special command option (see "-command" below) to invoke the MPI
788     executable. Examples of PBS scripts using MPI with testreport can be
789     found in the <ulink
790 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
791 edhill 1.4 MITgcm-contrib area</ulink></para>
792     </listitem>
793     </varlistentry>
794    
795     <varlistentry>
796     <term><filename>-command='some command to run'</></term>
797     <listitem>
798     <para>For some tests, particularly MPI runs, the default "make
799     output.txt" is not sufficient. This option allows a more general
800     command (or shell script) to be invoked. Examples of PBS scripts
801     using MPI with testreport can be found in the <ulink
802 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
803 edhill 1.4 MITgcm-contrib area</ulink></para>
804 edhill 1.3 </listitem>
805     </varlistentry>
806    
807     </variablelist>
808    
809 edhill 1.4 <para>The <filename>testreport</> script will write progress to the
810     screen (stdout) as it runs. In addition, it will create a
811     <filename>tr_out.txt</> file that contains a brief comparison of the
812     current output with the "known-good" output.</para>
813 edhill 1.3
814     </sect3>
815    
816     </sect2>
817 edhill 1.2
818 edhill 1.4
819 edhill 1.2 <sect2 id="packages">
820 edhill 1.3 <title>Creating MITgcm Packages</title>
821 edhill 1.2
822 edhill 1.4 <para>Optional parts of code have been separated from the MITgcmUV core
823     driver code and organised into packages. The packaging structure
824     provides a mechanism for maintaining suites of code, specific to
825     particular classes of problems, in a way that is cleanly separated from
826     the generic fluid dynamical engine.</para>
827    
828     <para>The MITgcmUV packaging structure is described below using generic
829 jmc 1.11 package names ${pkg}. A concrete examples of a package is the code for
830 edhill 1.4 implementing GM/Redi mixing. This code uses the package name</para>
831 edhill 1.2
832     </sect2>
833    
834     </sect1>
835    
836     <sect1>
837     <title>Chris's Notes...</title>
838    
839     <programlisting>
840     MITgcmUV Packages
841     =================
842    
843     Optional parts of code are separated from
844     the MITgcmUV core driver code and organised into
845     packages. The packaging structure provides a mechanism for
846     maintaining suites of code, specific to particular
847     classes of problem, in a way that is cleanly
848     separated from the generic fluid dynamical engine.
849    
850     The MITgcmUV packaging structure is describe
851     below using generic package names ${pkg}.
852     A concrete examples of a package is the code
853     for implementing GM/Redi mixing. This code uses
854     the package name
855     * ${PKG} = GMREDI
856     * ${pkg} = gmredi
857     * ${Pkg} = gmRedi
858    
859     Package states
860     ==============
861    
862     Packages can be any one of four states, included,
863     excluded, enabled, disabled as follows:
864    
865     included(excluded) compile time state which
866     includes(excludes) package
867     code and routine calls from
868     compilation/linking etc...
869    
870     enabled(disabled) run-time state which
871     enables(disables) package code
872     execution.
873    
874     Every call to a ${pkg}_... routine from outside the package
875     should be placed within both a
876     #ifdef ALLOW_${PKG} ... block and a
877     if ( use${Pkg} ) ... then block.
878     Package states are generally not expected to change during
879     a model run.
880    
881     Package structure
882     =================
883    
884     o Each package gets its runtime configuration
885     parameters from a file named "data.${pkg}"
886     Package runtime config. options are imported
887     into a common block held in a header file
888     called "${PKG}.h".
889 jmc 1.8 Note: In some packages, the header file "${PKG}.h" is splitted
890     into "${PKG}_PARAMS.h" that contains the package parameters and
891     ${PKG}_VARS.h" for the field arrays.
892 edhill 1.2
893     o The core driver part of the model can check
894     for runtime enabling or disabling of individual packages
895     through logical flags use${Pkg}.
896     The information is loaded from a
897     global package setup file called "data.pkg".
898     The use${Pkg} flags are not used within
899     individual packages.
900    
901     o Included in "${PKG}.h" is a logical flag
902     called ${Pkg}IsOn. The "${PKG}.h" header file can be imported
903     by other packages to check dependencies and requirements
904     from other packages ( see "Package Boot Sequence" section).
905     NOTE: This procedure is not presently implemented,
906     ----- neither for kpp nor for gmRedi.
907    
908     CPP Flags
909     =========
910    
911     1. Within the core driver code flags of the form
912     ALLOW_${PKG} are used to include or exclude
913     whole packages. The ALLOW_${PKG} flags are included
914 jmc 1.8 from a PACKAGES_CONFIG.h file that is automatically
915     generated by genmake2 (see genmake2 section).
916 edhill 1.2 held in-line in the CPP_OPTIONS.h header file.
917     e.g.
918    
919     Core model code .....
920    
921 jmc 1.8 #include "PACKAGES_CONFIG.h"
922 edhill 1.2 #include "CPP_OPTIONS.h"
923     :
924     :
925     :
926    
927     #ifdef ALLOW_${PKG}
928     if ( use${Pkg} ) CALL ${PKG}_DO_SOMETHING(...)
929     #endif
930    
931     2. Within an individual package a header file,
932     "${PKG}_OPTIONS.h", is used to set CPP flags
933 jmc 1.8 specific to that package. It also includes
934     "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
935 edhill 1.2
936    
937     Package Boot Sequence
938     =====================
939    
940     Calls to package routines within the core code timestepping
941     loop can vary. However, all packages follow a required
942     "boot" sequence outlined here:
943    
944     1. S/R PACKAGES_BOOT()
945     :
946     CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
947    
948    
949     2. S/R PACKAGES_READPARMS()
950     :
951     #ifdef ALLOW_${PKG}
952     if ( use${Pkg} )
953     & CALL ${PKG}_READPARMS( retCode )
954     #endif
955    
956 jmc 1.6 3. S/R PACKAGES_INIT_FIXED()
957     :
958     #ifdef ALLOW_${PKG}
959     if ( use${Pkg} )
960     & CALL ${PKG}_INIT_FIXED( retCode )
961     #endif
962    
963     4. S/R PACKAGES_CHECK()
964 edhill 1.2 :
965     #ifdef ALLOW_${PKG}
966     if ( use${Pkg} )
967     & CALL ${PKG}_CHECK( retCode )
968     #else
969     if ( use${Pkg} )
970     & CALL PACKAGES_CHECK_ERROR('${PKG}')
971     #endif
972    
973 jmc 1.6 5. S/R PACKAGES_INIT_VARIABLES()
974 edhill 1.2 :
975     #ifdef ALLOW_${PKG}
976     if ( use${Pkg} )
977 jmc 1.6 & CALL ${PKG}_INIT_VARIA( )
978     #endif
979    
980     Package Output
981     ==============
982     6. S/R DO_THE_MODEL_IO
983    
984     #ifdef ALLOW_${PKG}
985     if ( use${Pkg} )
986 jmc 1.9 & CALL ${PKG}_OUTPUT( )
987 edhill 1.2 #endif
988    
989 jmc 1.6 7. S/R PACKAGES_WRITE_PICKUP()
990    
991     #ifdef ALLOW_${PKG}
992     if ( use${Pkg} )
993     & CALL ${PKG}_WRITE_PICKUP( )
994     #endif
995 edhill 1.2
996     Description
997     ===========
998    
999     - ${PKG}_READPARMS()
1000     is responsible for reading
1001     in the package parameters file data.${pkg}, and storing
1002 jmc 1.8 the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1003 jmc 1.6 -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1004    
1005     - ${PKG}_INIT_FIXED()
1006     is responsible for completing the internal setup of a package.
1007     -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
1008     note: 1) some pkg use instead:
1009     CALL ${PKG}_INITIALISE ( or the old form CALL ${PKG}_INIT )
1010     2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
1011 edhill 1.2
1012     - ${PKG}_CHECK()
1013     is responsible for validating
1014     basic package setup and inter-package dependencies.
1015     ${PKG}_CHECK can import other package parameters it may
1016     need to check. This is done through header files "${PKG}.h".
1017     It is assumed that parameters owned by other packages
1018     will not be reset during ${PKG}_CHECK().
1019 jmc 1.6 -> called from INITIALISE_FIXED in PACKAGES_CHECK
1020 edhill 1.2
1021 jmc 1.6 - ${PKG}_INIT_VARIA()
1022     is responsible for fill-in all package variables with an initial value.
1023     Contains eventually a call to ${PKG}_READ_PICKUP that will read
1024     from a pickup file the package variables required to restart the model.
1025     This routine is called after the core model state has been completely
1026     initialised but before the core model timestepping starts.
1027     -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1028     note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
1029     use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1030     form ${PKG}_INIT
1031    
1032 jmc 1.9 - ${PKG}_OUTPUT( )
1033 jmc 1.8 is responsible for writing time-average fields to output files
1034     (but the cumulating step is done within the package main S/R).
1035 jmc 1.6 Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1036     and write snap-shot fields that are hold in common blocks. Other
1037     temporary fields are directly dump to file where they are available.
1038 jmc 1.9 NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
1039     but is beeing replaced by ${PKG}_OUTPUT
1040 jmc 1.8 to avoid confusion with pkg/diagnostics functionality.
1041     2) the output part is not yet in a standard form and might still
1042     evolve a lot.
1043 jmc 1.6 -> called within DO_THE_MODEL_IO
1044    
1045     - ${PKG}_WRITE_PICKUP()
1046     is responsible for writing a package pickup file when necessary for
1047     a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1048     -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1049 edhill 1.2
1050     Summary
1051     =======
1052    
1053     - CPP options:
1054     -----------------------
1055     * ALLOW_${PKG} include/exclude package for compilation
1056    
1057     - FORTRAN logical:
1058     -----------------------
1059     * use${Pkg} enable package for execution at runtime
1060     -> declared in PARAMS.h
1061     * ${Pkg}IsOn for package cross-dependency check
1062     -> declared in ${PKG}.h
1063     N.B.: Not presently used!
1064    
1065     - header files
1066     -----------------------
1067     * ${PKG}_OPTIONS.h has further package-specific CPP options
1068     * ${PKG}.h package-specific common block variables, fields
1069 jmc 1.8 or ${PKG}_PARAMS.h package-specific common block parameters
1070     and ${PKG}_VARS.h package-specific common block fields
1071 edhill 1.2
1072     - FORTRAN source files
1073     -----------------------
1074 jmc 1.6 * ${pkg}_readparms.F reads parameters from file data.${pkg}
1075     * ${pkg}_init_fixed.F complete the package setup
1076     * ${pkg}_check.F checks package dependencies and consistencies
1077     * ${pkg}_init_varia.F initialises package-related fields
1078     * ${pkg}_... .F package source code
1079 jmc 1.9 * ${pkg}_output.F write output to file.
1080 jmc 1.6 * ${pkg}_write_pickup.F write a package pickup file to restart the model
1081 edhill 1.2
1082 jmc 1.8 New: Subroutine in one package (pkgA) that only contains code which
1083     is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1084     will be named: pkgA_pkgB_something.F
1085    
1086 edhill 1.2 - parameter file
1087     -----------------------
1088     * data.${pkg} parameter file
1089     </programlisting>
1090    
1091     </sect1>
1092 edhill 1.1
1093    
1094 jmc 1.11 <sect1 id="documentation">
1095     <title>Editing the Documentation</title>
1096    
1097     <sect2 id="documentation_getting">
1098     <title>Getting the Docs and Code</title>
1099    
1100     <para>The first step towards editing the documentation is to checkout a
1101     copy of code, docs, and build scripts from the CVS server using:</para>
1102    
1103     <screen>
1104     $ export CVS_RSH=ssh
1105     $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
1106     $ mkdir scratch
1107     $ cvs co -P MITgcm manual mitgcm.org
1108     </screen>
1109    
1110     <para>These commands extract the necessary information from the CVS server
1111     and create a temporary (called <filename>scratch</filename>) directory for
1112     the storage of the HTML and other files that will be created. Please note
1113     that you must either create <filename>scratch</filename> as shown or edit
1114     the various <filename>Makefile</filename>s and scripts used to create the
1115     documentation.</para>
1116     </sect2>
1117    
1118     <sect2>
1119     <title>Editing the Documentation</title>
1120    
1121     <para>The documentation is contained in the <filename>manual</filename>
1122     directory in a raw LaTeX format. The main document is
1123     <filename>manual.tex</filename> and it uses <command>\input{}</command>s
1124     to include the chapters and subsections.</para>
1125    
1126     <para>Since the same LaTeX source is used to produce PostScript, PDF, and
1127     HTML output, care should be taken to follow certain conventions. Two of
1128     the most important are the usage of the <command>\filelink{}{}</command>
1129     and <command>\varlink{}{}</command> commands. Both of these commands have
1130     been defined to simplify the connection between the automatically
1131     generated ("code browser") HTML and the HTML version of the manual
1132     produced by LaTeX2HTML. They each take two arguments (corresponding to
1133     the contents of the two sets of curly braces) which are the text that the
1134     author wishes to be "wrapped" within the link, and a specially formatted
1135     link thats relative to the <filename>MITgcm</filename> directory within
1136     the CVS tree.</para>
1137    
1138     <para>The result is a command that resembles either</para>
1139    
1140     <orderedlist>
1141     <listitem>
1142     <para>a reference to a variable or subroutine name such as
1143     <command>\varlink{tRef}{tRef}</command>, or </para>
1144     </listitem>
1145    
1146     <listitem>
1147     <para>a reference to a file such as
1148     <command>\varlink{tRef}{path-to-the-file_name.F}</command>
1149     where the absolute path to the file is of the form
1150     <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
1151     <para>(please note how the leading "/foo/MITgcm"
1152     component of the path is dropped leaving the path
1153     <emphasis>relative</emphasis> to the head of the code
1154     directory and each directory separator "/" is turned
1155     into a "-")</para>
1156     </listitem>
1157     </orderedlist>
1158    
1159    
1160    
1161     </sect2>
1162    
1163     <sect2>
1164     <title>Building the Documentation</title>
1165    
1166     <para>Given the directory structure of <xref
1167     linkend="documentation_getting">, the entire documentation for the web
1168     site can be built using:</para>
1169    
1170     <screen>
1171     $ cd mitgcm.org/devel/buildweb
1172     $ make All
1173     </screen>
1174    
1175     <para>Which builds the PDF from the LaTeX source, creates the HTML output
1176     from the LaTeX source, parses the FORTRAN code base to produce a
1177     hyperlinked HTML version of the source, and then determines the
1178     cross-linking between the various HTML components.</para>
1179    
1180     <para>If there are no errors, the result of the build process (which can
1181     take 30+ minutes on a P4/2.5Ghz) will be contained within a single
1182     directory called <filename>scratch/dev_docs</filename>. This is a freshly
1183     built version of the entire on-line users manual. If you have the correct
1184     permissions, it can be directly copied to the web server area:</para>
1185    
1186     <screen>
1187     $ mv scratch/dev_docs /u/u0/httpd/html
1188     </screen>
1189    
1190     <para>and the update is complete.</para>
1191    
1192     </sect2>
1193    
1194     </sect1>
1195    
1196 edhill 1.1 </article>
1197    
1198    
  ViewVC Help
Powered by ViewVC 1.1.22