[MITgcm] Annotation of /MITgcm/doc/devel

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

	ViewVC Help
Powered by ViewVC 1.1.22

Annotation of /MITgcm/doc/devel_HOWTO.sgml