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