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

Contents of /MITgcm/doc/devel_HOWTO.sgml

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


Revision 1.4 - (show annotations) (download) (as text)
Thu Nov 20 00:01:42 2003 UTC (20 years, 4 months ago) by edhill
Branch: MAIN
CVS Tags: branch-netcdf, checkpoint52d_pre, checkpoint52b_pre, checkpoint52b_post, checkpoint52c_post
Changes since 1.3: +272 -179 lines
File MIME type: text/x-sgml
 o update build & test description

1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2
3 <article id="MITgcm-Development-HOWTO">
4
5 <!--
6 Build commands:
7 db2ps -d ldp.dsl devel_HOWTO.sgml
8 db2pdf -d ldp.dsl devel_HOWTO.sgml
9 db2html -d ./ldp.dsl devel_HOWTO.sgml
10 db2html -u -d ./ldp.dsl devel_HOWTO.sgml
11 -->
12
13 <articleinfo>
14 <title>MITgcm Development HOWTO</title>
15
16 <author>
17 <firstname>Ed</firstname>
18 <surname>Hill III</surname>
19 <affiliation>
20 <address><email>eh3@mit.edu</email></address>
21 </affiliation>
22 </author>
23
24 <revhistory>
25 <revision>
26 <revnumber>0.01</revnumber>
27 <date>2003-08-07</date>
28 <authorinitials>eh3</authorinitials>
29 <revremark>
30 Initial version.
31 </revremark>
32 </revision>
33 </revhistory>
34
35 <abstract>
36 <para>This document describes how to develop software for the
37 MITgcm project.</para>
38 </abstract>
39 </articleinfo>
40
41 <sect1 id="intro">
42 <title>Introduction</title> <para>The purpose of this document is
43 to help new developers get "up to speed" with MITgcm
44 development.</para>
45 <sect2>
46 <title>New Versions of This Document</title> <para>You can
47 obtain the latest version of this document <ulink
48 url="http://mitgcm.org/dev_docs/devel_HOWTO/">online</ulink> in
49 various formats.</para>
50 </sect2>
51 <sect2>
52 <title>Feedback and corrections</title> <para>If you have
53 questions or comments about this document, please feel free to
54 <ulink url="mailto:MITgcm-support@mitgcm.org">contact the
55 authors</ulink>.
56 </para>
57 </sect2>
58 </sect1>
59
60 <sect1 id="background">
61 <title>Background</title>
62
63 <sect2>
64 <title>User Manual</title>
65
66 <para>Before jumping into
67 development, please familiarize yourself with the MITgcm user
68 manual which is available <ulink
69 url="http://mitgcm.org/">on the main web page</ulink>. This
70 document contains volumes of useful information and is included
71 here by reference.</para>
72
73 <para>Also, a "snapshot" or<ulink
74 url="http://mitgcm.org/dev_docs/">development version</ulink> of
75 the user manual may be available, though this is only put on the
76 web for testing purposes.</para>
77 </sect2>
78
79 <sect2>
80 <title>Prerequisites</title> <para>To develop for MITgcm project
81 you will need a UNIX or UNIX-like set of build tools including
82 the following:</para>
83 <blockquote>
84 <simplelist type="inline">
85 <member>CVS client</member>
86 <member>make or (preferably) GNU make</member>
87 <member>FORTRAN compiler</member>
88 <member>C compiler</member>
89 <member>[ba]sh and [t]csh shells</member>
90 <member>PERL</member>
91 <member>LaTeX and LaTeX2HTML</member>
92 </simplelist>
93 </blockquote>
94 <para>Essentially all of the work described here has been tested
95 on recent versions of Red Hat Linux (eg. 7.3 through 9). Except
96 where noted, all shell commands will be provided using bash
97 syntax.
98 </para>
99 </sect2>
100
101 </sect1>
102
103 <sect1 id="cvs">
104 <title>CVS Repository</title>
105 <sect2>
106 <title>Layout</title>
107
108 <para>Unlike many open source projects, the MITgcm CVS tree does
109 not follow a simple "src", "docs", "share", and "test" directory
110 layout. Instead, there are multiple higher-level directories
111 that each, to some extent, depend upon the presence of the
112 others. The tree currently resembles:</para>
113
114 <programlisting>gcmpack/
115 MITgcm-contrib contributed code
116 CS-regrid goes into utils
117 cvspolicy.html -save-
118 CVSROOT -save-
119 development experimental stuff
120 manual -save-
121 misc -?-
122
123 MITgcm code
124 adjoint fold into genmake
125 bin stub for ecco build
126 compare01 old from 20th century
127 diags timeave f77 in pkgs now
128 doc tags -- connect to real docs?
129 eesupp cnh?
130 exe ecco user build
131 ,- jobs runtime shell scripts for
132 | various platforms
133 | lsopt line search
134 m| model main dynamics (core)
135 e| optimization_drivers ?
136 r| optim line search interface
137 g| pkg alternate and optional numerics, etc.
138 e|- tools
139 ?| tutorial_examples documented tests
140 | only populated on release1 branch
141 | and not validated during "testscript"
142 '- utils
143 verification std tests
144
145
146 mitgcmdoc -> manual -remove-
147 mitgcm.org build web site
148 models -?-
149 packages -?-
150 preprocess -?-
151 tmp -?-
152 </programlisting>
153
154 <para>Efforts are underway to reduce the complexity.</para>
155
156 </sect2>
157
158 <!--
159 <sect2>
160 <title>Releases</title> <para>Currently, there are two main
161 branches:</para>
162 <itemizedlist mark="bullet">
163 <listitem>
164 <para>Development</para>
165 <itemizedlist mark="bullet">
166 <listitem>
167 <para>MAIN</para>
168 </listitem>
169 <listitem>
170 <para>ecco-branch</para>
171 </listitem>
172 </itemizedlist>
173 </listitem>
174 <listitem>
175 <para>Production</para>
176 <itemizedlist mark="bullet">
177 <listitem>
178 <para>Release1</para>
179 </listitem>
180 <listitem>
181 <para>Release2</para>
182 </listitem>
183 </itemizedlist>
184 </listitem>
185 </itemizedlist>
186 </sect2>
187 -->
188
189 <sect2>
190 <title>Branches</title>
191
192 <para>As shown in the online <ulink
193 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">ViewCVS-generated
194 tree</ulink>, the MITgcm codebase is split into to two branches
195 or "lines" under which development proceeds. These two lines
196 are referred to as the "MAIN" and "ecco" versions of the code.
197 While not identical, the bulk of the MAIN and ecco lines are
198 composed of files from the same codebase.
199 </para>
200
201 <para>Periodically, a "Release" branch is formed from the "MAIN"
202 development branch. This is done in order to create a
203 relatively stable reference point for both users and developers.
204 The intent is that once a relese branch has been created, only
205 bug-fixes will be added to it. Meanwhile, development (which
206 might "break" or otherwise render invalid the documentation,
207 tutorials, and/or examples contained within a release branch) is
208 allowed to continue along the MAIN and ecco lines.</para>
209 </sect2>
210
211 <sect2>
212 <title>Tagging</title>
213
214 <para>The intent of tagging is to create "known-good"
215 checkpoints that developers can use as references.
216 Traditionally, MITgcm tagging has maintained the following
217 conventions:</para>
218
219 <orderedlist>
220 <listitem>
221 <para>Developer checks out code into a local CVS-managed
222 directory, makes various changes/additions, tests these
223 edits, and eventually reaches a point where (s)he is
224 satisfied that the changes form a new "useful" point in the
225 evolution of the code.</para>
226 </listitem>
227
228 <listitem>
229 <para>The developer then runs the <ulink
230 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>
231 shell script to see if any problems are introduced. While
232 not intended to be exhaustive, the test cases within the
233 verification directory do provide some indication whether
234 gross errors have been introduced.
235 </para>
236 </listitem>
237
238 <listitem>
239 <para>Having satisfied him- or herself that the changes are
240 ready to be committed to the CVS repository, the developer
241 then:</para>
242 <orderedlist>
243 <listitem>
244 <para>adds a "checkpointXY_pre" comment (where X is a
245 checkpoint number and Y is a letter) to the <ulink
246 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">tag-index</ulink>
247 file and checks it into the CVS repository</para>
248 </listitem>
249 <listitem>
250 <para>submits the set of changes to the CVS repository
251 and adds comments to <filename>tag-index</filename>
252 describing what the changes are along with a matching
253 "checkpointXY_post" entry</para>
254 </listitem>
255 </orderedlist>
256 </listitem>
257 </orderedlist>
258
259 <para>The result of this tagging procedure is a sequence of
260 development checkpoints with comments which resembles:</para>
261
262 <programlisting>
263 checkpoint50e_post
264 o make KPP work with PTRACERS
265 - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
266 nearly a copy of kpp_transport_s
267 - there is no analogue to SurfaceTendencyS, so I have to use
268 gPtr(of the surface layer) instead
269 o add a new platform SunFire+mpi (SunFire 15000) to genmake
270 checkpoint50e_pre
271
272 checkpoint50d_post
273 o change kpp output from multiple-record state files to single-record state
274 files analogous to write_state.F
275 o reduce the output frequency of cg3d-related stuff to the monitor frequency,
276 analogous to the cg2d-related output.
277 o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
278 so that writing to internal file fn (with length 512) fails.
279 checkpoint50d_pre
280 </programlisting>
281
282 <para>This information can be used to refer to various stages of
283 the code development. For example, bugs can be traced to
284 individual sets of CVS checkins based upon their first
285 appearance when comparing the results from different
286 checkpoints.</para>
287
288 </sect2>
289 </sect1>
290
291
292 <sect1 id="documentation">
293 <title>Editing the Documentation</title>
294
295 <sect2 id="documentation_getting">
296 <title>Getting the Docs and Code</title>
297
298 <para>The first step towards editing the documentation is to
299 checkout a copy of code, docs, and build scripts from the CVS
300 server using:</para>
301
302 <screen>
303 $ export CVS_RSH=ssh
304 $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
305 $ mkdir scratch
306 $ cvs co MITgcm manual mitgcm.org
307 </screen>
308
309 <para>These commands extract the necessary information from the
310 CVS server and create a temporary (called
311 <filename>scratch</filename>) directory for the storage of the
312 HTML and other files that will be created. Please note that you
313 must either create <filename>scratch</filename> as shown or edit
314 the various <filename>Makefile</filename>s and scripts used to
315 create the documentation.</para>
316 </sect2>
317
318 <sect2>
319 <title>Editing the Documentation</title>
320
321 <para>The documentation is contained in the
322 <filename>manual</filename> directory in a raw LaTeX format.
323 The main document is <filename>manual.tex</filename> and it uses
324 <command>\input{}</command>s to include the chapters and
325 subsections.</para>
326
327 <para>Since the same LaTeX source is used to produce PostScript,
328 PDF, and HTML output, care should be taken to follow certain
329 conventions. Two of the most important are the usage of the
330 <command>\filelink{}{}</command> and
331 <command>\varlink{}{}</command> commands. Both of these
332 commands have been defined to simplify the connection between
333 the automatically generated ("code browser") HTML and the HTML
334 version of the manual produced by LaTeX2HTML. They each take
335 two arguments (corresponding to the contents of the two sets of
336 curly braces) which are the text that the author wishes to be
337 "wrapped" within the link, and a specially formatted link thats
338 relative to the <filename>MITgcm</filename> directory within the
339 CVS tree.</para>
340
341 <para>The result is a command that resembles either</para>
342
343 <orderedlist>
344 <listitem>
345 <para>a reference to a variable or subroutine name such as
346 <command>\varlink{tRef}{tRef}</command>, or </para>
347 </listitem>
348
349 <listitem>
350 <para>a reference to a file such as
351 <command>\varlink{tRef}{path-to-the-file_name.F}</command>
352 where the absolute path to the file is of the form
353 <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
354 <para>(please note how the leading "/foo/MITgcm"
355 component of the path is dropped leaving the path
356 <emphasis>relative</emphasis> to the head of the code
357 directory and each directory separator "/" is turned
358 into a "-")</para>
359 </listitem>
360 </orderedlist>
361
362
363
364 </sect2>
365
366 <sect2>
367 <title>Building the Documentation</title>
368
369 <para>Given the directory structure of <xref
370 linkend="documentation_getting">, the entire documentation for the web
371 site can be built using:</para>
372
373 <screen>
374 $ cd mitgcm.org/devel/buildweb
375 $ make All
376 </screen>
377
378 <para>Which builds the PDF from the LaTeX source, creates the
379 HTML output from the LaTeX source, parses the FORTRAN code base
380 to produce a hyperlinked HTML version of the source, and then
381 determines the cross-linking between the various HTML
382 components.</para>
383
384 <para>If there are no errors, the result of the build process
385 (which can take 30+ minutes on a P4/2.5Ghz) will be contained
386 within a single directory called
387 <filename>scratch/dev_docs</filename>. This is a freshly built
388 version of the entire on-line users manual. If you have the
389 correct permissions, it can be directly copied to the web server
390 area:</para>
391
392 <screen>
393 $ mv scratch/dev_docs /u/u0/httpd/html
394 </screen>
395
396 <para>and the update is complete.</para>
397
398 </sect2>
399
400 </sect1>
401
402 <sect1 id="coding">
403 <title>Coding for MITgcm</title>
404
405 <sect2 id="build_tools">
406 <title>Build Tools</title>
407
408 <para>Many Open Source projects use the "GNU Autotools" to help streamline
409 the build process for various Unix and Unix-like architectures. For a
410 user, the result is the common "configure" (that is,
411 "<filename>./configure && make && make install</filename>") commands.
412 For MITgcm, the process is similar. Typical commands are:</para>
413
414 <screen>
415 $ genmake -mods=../code
416 $ make depend
417 $ make
418 </screen>
419
420 <para>The following sections describe the individual steps in the build
421 process.</para>
422
423 <sect3 id="genmake">
424 <title>The <filename>genmake2</> Utility</title>
425
426 <para><emphasis>Please note that the older <filename>genmake</> is
427 deprecated and will eventually be replaced by <filename>genmake2</>.
428 This HOWTO only describes the newer tool.</emphasis></para>
429
430 <para>The first step in any MITgcm build is to create a Unix-style
431 <filename>Makefile</filename> which will be parsed by
432 <filename>make</filename> to specify how to compile the MITgcm source
433 files. For more detailed descriptions of what the make tools are and
434 how they are used, please see:</para>
435
436 <itemizedlist>
437 <listitem>
438 <para><ulink url="http://www.gnu.org/software/make/make.html">
439 http://www.gnu.org/software/make/make.html</></para>
440 </listitem>
441 <listitem>
442 <para><ulink url="http://www.oreilly.com/catalog/make2/">
443 http://www.oreilly.com/catalog/make2/</></para>
444 </listitem>
445 </itemizedlist>
446
447 <para>Genmake can often be invoked successfully with a command line as
448 simple as:</para>
449
450 <screen>
451 $ genmake2 -mods=../code
452 </screen>
453
454 <para>However, some systems (particularly commercial Unixes that lack a
455 more modern "/bin/sh" implementation or that have shells installed in
456 odd locations) may require an explicit shell invocation such as one of
457 the following: </para>
458
459 <screen>
460 $ /usr/bin/sh genmake2 -make=gmake -mods=../code
461 $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
462 </screen>
463
464 <para>The genmake2 code has been written in a Bourne and BASH (v1)
465 compatible syntax so it should work with most "sh" and all recent "bash"
466 implementations.</para>
467
468 <para>As the name implies, <filename>genmake2</filename> generates a
469 <filename>Makefile</filename>. It does so by first parsing the
470 information supplied from the following sources</para>
471
472 <orderedlist>
473 <listitem>
474 <para>a <filename>gm_local</filename> file in the current
475 directory</para>
476 </listitem>
477 <listitem>
478 <para>directly from command-line options</para>
479 </listitem>
480 <listitem>
481 <para>an "options file" as specified by the command-line option
482 <filename>-optfile='FILENAME'</filename></para>
483 </listitem>
484 </orderedlist>
485
486 <para>then checking certain dependency rules (the package dependencies),
487 and finally writing a <filename>Makefile</filename> based upon the
488 source code that it finds. For convenience within various Unix
489 shells, <filename>genmake2</> supports both "long"- and "short"-style
490 options. A complete list of the available options can be obtained
491 from:</para>
492
493 <screen>
494 $ genmake2 -help
495 </screen>
496
497 <para>The most important options for <filename>genmake2</> are:</para>
498
499 <variablelist>
500
501 <varlistentry>
502 <term><filename>--optfile=/PATH/FILENAME</></term>
503
504 <listitem>
505 <para>This specifies the "options file" that should be used for a
506 particular build. The options file is a convenient and
507 machine-indepenent way of specifying parameters such as the
508 FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
509 optimization flags (<filename>FFLAGS=</>), and the locations of
510 various platform- and/or machine-specific tools
511 (eg. <filename>MAKEDEPEND=</>). As with <filename>genmake2</>,
512 all options files should be written to be compatible with
513 Bourne--shell ("sh" or "BASH v1") syntax. Examples of various
514 options files can be found in
515 <filename>$ROOTDIR/tools/build_options</>.</para>
516
517 <para>If no "optfile" is specified (either through the command lin
518 or the environment variable), genmake2 will try to make a
519 reasonable guess from the list provided in
520 <filename>$ROOTDIR/tools/build_options</>. The method used for
521 making this guess is to first determine the combination of
522 operating system and hardware (eg. "linux_ia32") and then find a
523 working Fortran compiler within the user's path. When these
524 three items have been identified, genmake2 will try to find an
525 optfile that has a matching name. </para>
526
527 <para>Everyone is encouraged to submit their options files to the
528 MITgcm project for inclusion (please send to
529 <email>MITgcm-support@mitgcm.org</email>). We are particularly
530 grateful for options files tested on new or unique
531 platforms!</para>
532 </listitem>
533
534 </varlistentry>
535
536 <varlistentry>
537 <term><filename>-pdepend=/PATH/FILENAME</></term>
538
539 <listitem>
540 <para>This specifies the dependency file used for packages. If
541 not specified, the default dependency file is
542 <filename>$ROOTDIR/pkg/pkg_depend</>. The syntax for this file is
543 parsed on a line-by-line basis where each line containes either a
544 comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
545 where the "+" or "-" symbol specifies a "must be used with" or a
546 "must not be used with" relationship, respectively. If no rule is
547 specified, then it is assumed that the two packages are compatible
548 and will function either with or without each other.</para>
549 </listitem>
550
551 </varlistentry>
552
553 <varlistentry>
554 <term><filename>-pdefault=PKG</></term>
555 <term><filename>-pdefault='PKG1 [PKG2 PKG3 ...]'</></term>
556 <listitem>
557 <para>This option specifies the default set of packages
558 to be used. If not set, the default package list will
559 be read from
560 <filename>$ROOTDIR/pkg/pkg_default</>.</para>
561 </listitem>
562 </varlistentry>
563
564 <varlistentry>
565 <term><filename>-mods=DIR</></term>
566 <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
567 <listitem>
568 <para>This option specifies a list of directories containing
569 "modifications". These directories contain files with names
570 that may (or may not) exist in the main MITgcm source tree but
571 will be overridden by any identically-named sources within the
572 "MODS" directories. The order of precedence for this
573 "name-hiding" is as follows:</para>
574
575 <itemizedlist>
576 <listitem><para>"MODS" directories (in the order given)
577 </para></listitem>
578 <listitem><para>Packages either explicitly specified or
579 provided by default (in the order given)</para></listitem>
580 <listitem><para>Packages included due to package dependencies
581 (in the order that that package dependencies are
582 parsed)</para></listitem>
583 <listitem><para>The "standard dirs" (which may have been
584 specified by the "-standarddirs" option)</para></listitem>
585 </itemizedlist>
586
587 </listitem>
588 </varlistentry>
589
590 <varlistentry>
591 <term><filename>-make=/path/to/gmake</></term>
592 <listitem>
593 <para>Due to the poor handling of soft-links and other bugs common
594 with the <filename>make</> versions provided by commercial Unix
595 vendors, GNU <filename>make</filename> (sometimes called
596 <filename>gmake</filename>) should be preferred. This option
597 provides a means for specifying the make program to be
598 used.</para>
599 </listitem>
600 </varlistentry>
601
602 </variablelist>
603
604 <para>A successful run of <filename>genmake2</> will produce a
605 <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
606 various convenience files used for the automatic differentiation
607 process.</para>
608
609 <para>In general, it is best to use <filename>genmake2</> on a "clean"
610 directory that is free of all source (*.[F,f],*.[F,f]90) and header
611 (*.h,*.inc) files. Generally, this can be accomplished in an
612 "un-clean" directory by running "make CLEAN" followed by "make
613 makefile".</para>
614
615 </sect3>
616
617 <sect3 id="makefile_use">
618 <title>Using <filename>Makefile</></title>
619
620 <para>Once a <filename>Makefile</> has been created, one can
621 build an executable using:</para>
622
623 <screen>
624 $ make CLEAN
625 $ make depend
626 $ make
627 </screen>
628
629 <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 different compilers.</para>
651
652 <para>Please report compilation failures or other problems to
653 <email>MITgcm-support@mitgcm.org</email>.</para>
654
655 </sect3>
656
657 </sect2>
658
659 <sect2 id="verification">
660 <title>The Verification Suite</title>
661
662 <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
663 directory) includes more than a dozen examples intended for regression
664 testing. Each one of these example directories contains "known-good"
665 output files along with all the input (including both code and data
666 files) required for their re-calculation. These example directories are
667 further broken down into sets of subdirectories
668 (eg. <filename>/input</>, <filename>/code</>) intended to expedite the
669 testing process.</para>
670
671 <sect3 id="testreport">
672 <title>The <filename>testreport</> Utility</title>
673
674 <para>Also included in <filename>$ROOTDIR/verification/</> are shell
675 scripts for automated testing. The newest script (which was written
676 to work with <filename>genmake2</>) is called <filename>testreport</>.
677 This script can be used to build different versions of the MITgcm
678 code, run the various examples, compare the output, and (if specified)
679 email the results of each one of these tests to a central
680 repository.</para>
681
682 <para>On some systems, the testreport script can be run with a command
683 line as simple as:</para>
684
685 <screen>
686 $ cd verification
687 $ ./testreport -ieee
688 </screen>
689
690 <para>However, some systems (those lacking or wiht a broken "/bin/sh")
691 may require an explicit shell invocation such as:</para>
692
693 <screen>
694 $ sh ./testreport -ieee -t 'exp0 exp4'
695 $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
696 </screen>
697
698 <para>The <filename>testreport</> script accepts a number of
699 command-line options which can be listed using the <filename>-help</>
700 option. The most important ones are:</para>
701
702 <variablelist>
703
704 <varlistentry>
705 <term><filename>-ieee</></term>
706 <listitem>
707 <para>If allowed by the compiler (as defined in the "optfile"),
708 use IEEE arithmetic. This option, along with the GCC compiler,
709 is how the standard results were produced.</para>
710 </listitem>
711 </varlistentry>
712
713 <varlistentry>
714 <term><filename>-tdir TESTDIR</></term>
715 <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
716 <listitem>
717 <para>This option specifies the test directory or list of test
718 directories that should be used. Each of these entries should
719 exactly (note: they are case sensitive!) match the names of
720 directries in <filename>$ROOTDIR/verification/</>. If this
721 option is omitted, then all directories that are properly
722 formatted (that is, containing an <filename>input</>
723 sub-directory and a <filename>results/output.txt</> file) will
724 be used.</para>
725 </listitem>
726 </varlistentry>
727
728 <varlistentry>
729 <term><filename>-optfile=/PATH/FILENAME</></term>
730 <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
731 <listitem>
732 <para>This specifies a list of "options files" that will be passed
733 to <filename>genmake2</>. If multiple options files are used
734 (say, to test different compilers or different sets of options
735 for the same compiler), then each options file will be used with
736 each of the test directories.</para>
737 </listitem>
738 </varlistentry>
739
740 <varlistentry>
741 <term><filename>-addr EMAIL</></term>
742 <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
743 <listitem>
744 <para>Send the results (namely, <filename>output.txt</>,
745 <filename>genmake_local</>, <filename>genmake_state</>, and
746 <filename>Makefile</>) to the specified email addresses. The
747 results are gzipped, placed in a tar file, MIME encoded, and
748 sent to the specified address. If no email addresses are
749 specified, no mail is sent.</para>
750 </listitem>
751 </varlistentry>
752
753 <varlistentry>
754 <term><filename>-mpi</></term>
755 <listitem>
756 <para>If the necessary files
757 (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and
758 <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an
759 MPI--enabled run. Note that the use of MPI typically requires a
760 special command option (see "-command" below) to invoke the MPI
761 executable. Examples of PBS scripts using MPI with testreport can be
762 found in the <ulink
763 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
764 MITgcm-contrib area</ulink></para>
765 </listitem>
766 </varlistentry>
767
768 <varlistentry>
769 <term><filename>-command='some command to run'</></term>
770 <listitem>
771 <para>For some tests, particularly MPI runs, the default "make
772 output.txt" is not sufficient. This option allows a more general
773 command (or shell script) to be invoked. Examples of PBS scripts
774 using MPI with testreport can be found in the <ulink
775 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
776 MITgcm-contrib area</ulink></para>
777 </listitem>
778 </varlistentry>
779
780 </variablelist>
781
782 <para>The <filename>testreport</> script will write progress to the
783 screen (stdout) as it runs. In addition, it will create a
784 <filename>tr_out.txt</> file that contains a brief comparison of the
785 current output with the "known-good" output.</para>
786
787 </sect3>
788
789 </sect2>
790
791
792 <sect2 id="packages">
793 <title>Creating MITgcm Packages</title>
794
795 <para>Optional parts of code have been separated from the MITgcmUV core
796 driver code and organised into packages. The packaging structure
797 provides a mechanism for maintaining suites of code, specific to
798 particular classes of problems, in a way that is cleanly separated from
799 the generic fluid dynamical engine.</para>
800
801 <para>The MITgcmUV packaging structure is described below using generic
802 package names ${pkg}. A concrete examples of a package is the code for
803 implementing GM/Redi mixing. This code uses the package name</para>
804
805 </sect2>
806
807 </sect1>
808
809 <sect1>
810 <title>Chris's Notes...</title>
811
812 <programlisting>
813 MITgcmUV Packages
814 =================
815
816 Optional parts of code are separated from
817 the MITgcmUV core driver code and organised into
818 packages. The packaging structure provides a mechanism for
819 maintaining suites of code, specific to particular
820 classes of problem, in a way that is cleanly
821 separated from the generic fluid dynamical engine.
822
823 The MITgcmUV packaging structure is describe
824 below using generic package names ${pkg}.
825 A concrete examples of a package is the code
826 for implementing GM/Redi mixing. This code uses
827 the package name
828 * ${PKG} = GMREDI
829 * ${pkg} = gmredi
830 * ${Pkg} = gmRedi
831
832 Package states
833 ==============
834
835 Packages can be any one of four states, included,
836 excluded, enabled, disabled as follows:
837
838 included(excluded) compile time state which
839 includes(excludes) package
840 code and routine calls from
841 compilation/linking etc...
842
843 enabled(disabled) run-time state which
844 enables(disables) package code
845 execution.
846
847 Every call to a ${pkg}_... routine from outside the package
848 should be placed within both a
849 #ifdef ALLOW_${PKG} ... block and a
850 if ( use${Pkg} ) ... then block.
851 Package states are generally not expected to change during
852 a model run.
853
854 Package structure
855 =================
856
857 o Each package gets its runtime configuration
858 parameters from a file named "data.${pkg}"
859 Package runtime config. options are imported
860 into a common block held in a header file
861 called "${PKG}.h".
862
863 o The core driver part of the model can check
864 for runtime enabling or disabling of individual packages
865 through logical flags use${Pkg}.
866 The information is loaded from a
867 global package setup file called "data.pkg".
868 The use${Pkg} flags are not used within
869 individual packages.
870
871 o Included in "${PKG}.h" is a logical flag
872 called ${Pkg}IsOn. The "${PKG}.h" header file can be imported
873 by other packages to check dependencies and requirements
874 from other packages ( see "Package Boot Sequence" section).
875 NOTE: This procedure is not presently implemented,
876 ----- neither for kpp nor for gmRedi.
877
878 CPP Flags
879 =========
880
881 1. Within the core driver code flags of the form
882 ALLOW_${PKG} are used to include or exclude
883 whole packages. The ALLOW_${PKG} flags are included
884 from a PKG_CPP_OPTIONS block which is currently
885 held in-line in the CPP_OPTIONS.h header file.
886 e.g.
887
888 Core model code .....
889
890 #include "CPP_OPTIONS.h"
891 :
892 :
893 :
894
895 #ifdef ALLOW_${PKG}
896 if ( use${Pkg} ) CALL ${PKG}_DO_SOMETHING(...)
897 #endif
898
899 2. Within an individual package a header file,
900 "${PKG}_OPTIONS.h", is used to set CPP flags
901 specific to that package. It is not recommended
902 to include this file in "CPP_OPTIONS.h".
903
904
905 Package Boot Sequence
906 =====================
907
908 Calls to package routines within the core code timestepping
909 loop can vary. However, all packages follow a required
910 "boot" sequence outlined here:
911
912 1. S/R PACKAGES_BOOT()
913 :
914 CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
915
916
917 2. S/R PACKAGES_READPARMS()
918 :
919 #ifdef ALLOW_${PKG}
920 if ( use${Pkg} )
921 & CALL ${PKG}_READPARMS( retCode )
922 #endif
923
924 2. S/R PACKAGES_CHECK()
925 :
926 #ifdef ALLOW_${PKG}
927 if ( use${Pkg} )
928 & CALL ${PKG}_CHECK( retCode )
929 #else
930 if ( use${Pkg} )
931 & CALL PACKAGES_CHECK_ERROR('${PKG}')
932 #endif
933
934 3. S/R PACKAGES_INIT()
935 :
936 #ifdef ALLOW_${PKG}
937 if ( use${Pkg} )
938 & CALL ${PKG}_INIT( retCode )
939 #endif
940
941
942 Description
943 ===========
944
945 - ${PKG}_READPARMS()
946 is responsible for reading
947 in the package parameters file data.${pkg}, and storing
948 the package parameters in "${PKG}.h".
949 -> called in INITIALISE_FIXED
950
951 - ${PKG}_CHECK()
952 is responsible for validating
953 basic package setup and inter-package dependencies.
954 ${PKG}_CHECK can import other package parameters it may
955 need to check. This is done through header files "${PKG}.h".
956 It is assumed that parameters owned by other packages
957 will not be reset during ${PKG}_CHECK().
958 -> called in INITIALISE_FIXED
959
960 - ${PKG}_INIT()
961 is responsible for completing the
962 internal setup of a package. This routine is called after
963 the core model state has been completely initialised
964 but before the core model timestepping starts.
965 -> called in INITIALISE_VARIA
966
967 Summary
968 =======
969
970 - CPP options:
971 -----------------------
972 * ALLOW_${PKG} include/exclude package for compilation
973
974 - FORTRAN logical:
975 -----------------------
976 * use${Pkg} enable package for execution at runtime
977 -> declared in PARAMS.h
978 * ${Pkg}IsOn for package cross-dependency check
979 -> declared in ${PKG}.h
980 N.B.: Not presently used!
981
982 - header files
983 -----------------------
984 * ${PKG}_OPTIONS.h has further package-specific CPP options
985 * ${PKG}.h package-specific common block variables, fields
986
987 - FORTRAN source files
988 -----------------------
989 * ${pkg}_readparms.F reads parameters from file data.${pkg}
990 * ${pkg}_check.F checks package dependencies and consistencies
991 * ${pkg}_init.F initialises package-related fields
992 * ${pkg}_... .F package source code
993
994 - parameter file
995 -----------------------
996 * data.${pkg} parameter file
997 </programlisting>
998
999 </sect1>
1000
1001
1002 </article>

  ViewVC Help
Powered by ViewVC 1.1.22