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

Diff of /MITgcm/doc/devel_HOWTO.sgml

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

revision 1.3 by edhill, Thu Aug 28 22:44:00 2003 UTC revision 1.4 by edhill, Thu Nov 20 00:01:42 2003 UTC
# Line 128  Build commands: Line 128  Build commands:
128         doc                      tags -- connect to real docs?         doc                      tags -- connect to real docs?
129         eesupp                   cnh?         eesupp                   cnh?
130         exe                      ecco user build         exe                      ecco user build
131      *- jobs                     runtime shell scripts for      ,- jobs                     runtime shell scripts for
132      |                             various platforms      |                             various platforms
133      |  lsopt                    line search      |  lsopt                    line search
134     m|  model                    main dynamics (core)     m|  model                    main dynamics (core)
135     e|    optimization_drivers   ?     e|    optimization_drivers   ?
136     r|  optim                    line search interface     r|  optim                    line search interface
137     g|  pkg                      alternate and optional numerics, etc.     g|  pkg                      alternate and optional numerics, etc.
138     e*- tools     e|- tools
139     ?|  tutorial_examples        documented tests     ?|  tutorial_examples        documented tests
140      |                             only populated on release1 branch      |                             only populated on release1 branch
141      |                             and not validated during "testscript"      |                             and not validated during "testscript"
142      *- utils      '- utils
143         verification             std tests         verification             std tests
144    
145    
# Line 316  $ cvs co MITgcm manual mitgcm.org Line 316  $ cvs co MITgcm manual mitgcm.org
316      </sect2>      </sect2>
317    
318      <sect2>      <sect2>
319        <title>Editing</title>        <title>Editing the Documentation</title>
320    
321        <para>The documentation is contained in the        <para>The documentation is contained in the
322        <filename>manual</filename> directory in a raw LaTeX format.        <filename>manual</filename> directory in a raw LaTeX format.
# Line 364  $ cvs co MITgcm manual mitgcm.org Line 364  $ cvs co MITgcm manual mitgcm.org
364      </sect2>      </sect2>
365    
366      <sect2>      <sect2>
367        <title>Building</title> <para>Given the directory structure of        <title>Building the Documentation</title>
368        <xref linkend="documentation_getting">, the entire documentation        
369        for the web site can be built using:</para>        <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>  <screen>
374  $ cd mitgcm.org/devel/buildweb  $ cd mitgcm.org/devel/buildweb
# Line 403  $ mv scratch/dev_docs /u/u0/httpd/html Line 405  $ mv scratch/dev_docs /u/u0/httpd/html
405      <sect2 id="build_tools">      <sect2 id="build_tools">
406        <title>Build Tools</title>        <title>Build Tools</title>
407    
408        <para>Many Open Source projects use the "GNU Autotools" to help        <para>Many Open Source projects use the "GNU Autotools" to help streamline
409        streamline the build process for various Unix and Unix-like          the build process for various Unix and Unix-like architectures.  For a
410        architectures.  For a user, the result is the common "configure"          user, the result is the common "configure" (that is,
411        (that is, "<filename>./configure && make && make          "<filename>./configure && make && make install</filename>") commands.
412        install</filename>") commands.  For MITgcm, the process is          For MITgcm, the process is similar.  Typical commands are:</para>
       similar.  Typical commands are:</para>  
413    
414  <screen>  <screen>
415  $ genmake -mods=../code  $ genmake -mods=../code
# Line 416  $ make depend Line 417  $ make depend
417  $ make  $ make
418  </screen>  </screen>
419    
420        <para>The following sections describe the individual steps in        <para>The following sections describe the individual steps in the build
421        the build process.</para>          process.</para>
422          
423        <sect3 id="genmake">        <sect3 id="genmake">
424          <title>The <filename>genmake2</> Utility</title>          <title>The <filename>genmake2</> Utility</title>
425    
426          <para><emphasis>Please note that the older          <para><emphasis>Please note that the older <filename>genmake</> is
427          <filename>genmake</> is deprecated and will eventually              deprecated and will eventually be replaced by <filename>genmake2</>.
428          be replaced by <filename>genmake2</>.  This HOWTO only              This HOWTO only describes the newer tool.</emphasis></para>
429          describes the newer tool.</emphasis></para>  
430            <para>The first step in any MITgcm build is to create a Unix-style
431          <para>The first step in any MITgcm build is to create a            <filename>Makefile</filename> which will be parsed by
432          Unix-style <filename>Makefile</filename> which will be parsed            <filename>make</filename> to specify how to compile the MITgcm source
433          by <filename>make</filename> to specify how to compile the            files.  For more detailed descriptions of what the make tools are and
434          MITgcm source files.  For more detailed descriptions of what            how they are used, please see:</para>
         the make tools are and how they are used, please see:</para>  
435    
436          <itemizedlist>          <itemizedlist>
437            <listitem>            <listitem>
438              <para><ulink url="http://www.gnu.org/software/make/make.html">http://www.gnu.org/software/make/make.html</></para>              <para><ulink url="http://www.gnu.org/software/make/make.html">
439                    http://www.gnu.org/software/make/make.html</></para>
440            </listitem>            </listitem>
441            <listitem>            <listitem>
442              <para><ulink url="http://www.oreilly.com/catalog/make2/">http://www.oreilly.com/catalog/make2/</></para>              <para><ulink url="http://www.oreilly.com/catalog/make2/">
443                    http://www.oreilly.com/catalog/make2/</></para>
444            </listitem>            </listitem>
445          </itemizedlist>          </itemizedlist>
446    
447          <para>Due to the poor handling of soft-links and other bugs          <para>Genmake can often be invoked successfully with a command line as
448          common with the <filename>make</filename> versions provided by          simple as:</para>
449          commercial Unix vendors, GNU <filename>make</filename>  
450          (sometimes called <filename>gmake</filename>) should be  <screen>
451          preferred.</para>  $ genmake2 -mods=../code
452    </screen>
453          <para>As the name implies, <filename>genmake2</filename>  
454          generates a <filename>Makefile</filename>.  It does so by          <para>However, some systems (particularly commercial Unixes that lack a
455          first parsing the information supplied from the following            more modern "/bin/sh" implementation or that have shells installed in
456          sources</para>            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>          <orderedlist>
473            <listitem>            <listitem>
474              <para>a <filename>gm_local</filename> file in the current              <para>a <filename>gm_local</filename> file in the current
475              directory</para>                directory</para>
476            </listitem>            </listitem>
477            <listitem>            <listitem>
478              <para>directly from command-line options</para>              <para>directly from command-line options</para>
479            </listitem>            </listitem>
480            <listitem>            <listitem>
481              <para>an "options file" as specified by the command-line              <para>an "options file" as specified by the command-line option
482              option <filename>-optfile='FILENAME'</filename></para>                <filename>-optfile='FILENAME'</filename></para>
483            </listitem>            </listitem>
484          </orderedlist>          </orderedlist>
485    
486          <para>then checking certain dependency rules (the package          <para>then checking certain dependency rules (the package dependencies),
487          dependencies), and then writing a            and finally writing a <filename>Makefile</filename> based upon the
488          <filename>Makefile</filename> based upon the source code that            source code that it finds.  For convenience within various Unix
489          it finds.  For convenience with the various Unix shells,            shells, <filename>genmake2</> supports both "long"- and "short"-style
490          <filename>genmake2</> supports both "long"- and "shor"-style            options.  A complete list of the available options can be obtained
491          options.  A complete list of the available options can be            from:</para>
         obtained from:</para>  
492    
493  <screen>  <screen>
494  $ genmake2 -help  $ genmake2 -help
495  </screen>  </screen>
496    
497          <para>The most important options for <filename>genmake2</>          <para>The most important options for <filename>genmake2</> are:</para>
         are:</para>  
498    
499          <variablelist>          <variablelist>
500    
501            <varlistentry>            <varlistentry>
502              <term><filename>--optfile=/PATH/FILENAME</></term>              <term><filename>--optfile=/PATH/FILENAME</></term>
503    
504              <listitem>              <listitem>
505                <para>This specifies the "options file" that should be                <para>This specifies the "options file" that should be used for a
506                used for a particular build.  The options file is a                  particular build.  The options file is a convenient and
507                convenient and machine-indepenent way of specifying                  machine-indepenent way of specifying parameters such as the
508                parameters such as the FORTRAN compiler                  FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
509                (<filename>FC=</>), FORTRAN compiler optimization flags                  optimization flags (<filename>FFLAGS=</>), and the locations of
510                (<filename>FFLAGS=</>), and the locations of various                  various platform- and/or machine-specific tools
511                platform- and/or machine-specific tools                  (eg. <filename>MAKEDEPEND=</>).  As with <filename>genmake2</>,
512                (eg. <filename>MAKEDEPEND=</>).  As with                  all options files should be written to be compatible with
513                <filename>genmake2</>, all options files should be                  Bourne--shell ("sh" or "BASH v1") syntax.  Examples of various
514                written a BASH v1-compatible syntax.  Examples of                  options files can be found in
515                various options files can be found in                  <filename>$ROOTDIR/tools/build_options</>.</para>
516                <filename>$ROOTDIR/tools/build_options</>.  Everyone is  
517                encouraged to submit their options files to the MITgcm                <para>If no "optfile" is specified (either through the command lin
518                project for inclusion (please send to                  or the environment variable), genmake2 will try to make a
519                <email>MITgcm-support@mitgcm.org</email>).  We are                  reasonable guess from the list provided in
520                particularly grateful for options files tested on new or                  <filename>$ROOTDIR/tools/build_options</>.  The method used for
521                unique platforms!</para>                  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>              </listitem>
533    
534            </varlistentry>            </varlistentry>
535    
536            <varlistentry>            <varlistentry>
537              <term><filename>-pdepend=/PATH/FILENAME</></term>              <term><filename>-pdepend=/PATH/FILENAME</></term>
538    
539              <listitem>              <listitem>
540                <para>This specifies the dependency file used for                <para>This specifies the dependency file used for packages.  If
541                packages.  If not specified, the default dependency file                not specified, the default dependency file is
542                is <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for                <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
543                this file is parsed on a line-by-line basis where each                parsed on a line-by-line basis where each line containes either a
544                line containes either a comment ("#") or a simple                comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
545                "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or                where the "+" or "-" symbol specifies a "must be used with" or a
546                "-" symbol specifies a "must be used with" or a "must                "must not be used with" relationship, respectively.  If no rule is
547                not be used with" relationship, respectively.  If no                specified, then it is assumed that the two packages are compatible
548                rule is specified, then it is assumed that the two                and will function either with or without each other.</para>
               packages are compatible and will function either with or  
               without each other.</para>  
549              </listitem>              </listitem>
550    
551            </varlistentry>            </varlistentry>
552    
553            <varlistentry>            <varlistentry>
# Line 536  $ genmake2 -help Line 562  $ genmake2 -help
562            </varlistentry>            </varlistentry>
563    
564            <varlistentry>            <varlistentry>
565              <term><filename></>-mods=DIR</term>              <term><filename>-mods=DIR</></term>
566              <term><filename></>-mods='DIR1 [DIR2 ...]'</term>              <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
567              <listitem>              <listitem>
568                <para>This option specifies a list of directories                <para>This option specifies a list of directories containing
569                containing "modifications".  These are files that may                  "modifications".  These directories contain files with names
570                (or may not) exist in the main MITgcm source tree but                  that may (or may not) exist in the main MITgcm source tree but
571                will be overridden by any identically-named sources                  will be overridden by any identically-named sources within the
572                within the "MODS" directories.</para>                  "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>              </listitem>
600            </varlistentry>            </varlistentry>
601    
602          </variablelist>          </variablelist>
603                    
604          <para>A successful run of <filename>genmake2</> will produce          <para>A successful run of <filename>genmake2</> will produce a
605          both a <filename>Makefile</> and a locally modified copy of            <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
606          the specified <filename>CPP_OPTIONS.h</> file.  The local copy            various convenience files used for the automatic differentiation
607          of <filename>CPP_OPTIONS.h</> will contain a list of            process.</para>
608          <filename>genmake2</>-created #DEFINE and #UNDEF statements  
609          that reflect the list of packages that will be compiled into          <para>In general, it is best to use <filename>genmake2</> on a "clean"
610          the code (either directly through enable/disable/defaults            directory that is free of all source (*.[F,f],*.[F,f]90) and header
611          options or indirectly through dependencies).</para>            (*.h,*.inc) files.  Generally, this can be accomplished in an
612              "un-clean" directory by running "make CLEAN" followed by "make
613          <para>In general, it is best to use <filename>genmake2</> on a            makefile".</para>
         "clean" directory that is free of all source  
         (*.[F,f],*.[F,f]90) and header (*.h,*.inc) files.  Generally,  
         this can be accomplished in an "un-clean" directory by running  
         "make CLEAN" followed by "make makefile".</para>  
614    
615        </sect3>        </sect3>
616    
# Line 570  $ genmake2 -help Line 618  $ genmake2 -help
618          <title>Using <filename>Makefile</></title>          <title>Using <filename>Makefile</></title>
619    
620          <para>Once a <filename>Makefile</> has been created, one can          <para>Once a <filename>Makefile</> has been created, one can
621          build the executable using:</para>          build an executable using:</para>
622    
623  <screen>  <screen>
624  $ make CLEAN  $ make CLEAN
# Line 578  $ make depend Line 626  $ make depend
626  $ make  $ make
627  </screen>  </screen>
628    
629          <para>The "make CLEAN" step will remove any local source          <para>The "make CLEAN" step will remove any stale source files, include
630          files, include files, and links.  It is strongly recommended            files, and links.  It is strongly recommended for "un-clean"
631          for "un-clean" directories which may contain the (partial?)            directories which may contain the (perhaps partial) results of
632          results of previous builds.  Such "debris" can interfere with            previous builds.  Such "debris" can interfere with the next stage of
633          the next stage of the build.</para>            the build.</para>
634    
635          <para>The "make depend" step will create a large number of          <para>The "make depend" step will create a large number of symbolic
636          symbolic links from the local directory to the source file            links from the local directory to the source file locations.  It also
637          locations.  It also parses these files and creates an            parses these files and creates an extensive list of dependencies
638          extensive list of dependencies within the            within the <filename>Makefile</> itself.  The links that exist at this
639          <filename>Makefile</> itself.  The links that exist at this            stage are mostly "large F" files (*.F and *.F90) that need to be
640          stage are mostly "large F" files (*.F and *.F90) that need to            processed by a C preprocessor ("CPP").  Since "make depend" edits the
641          be processed by a C preprocessor ("CPP").            <filename>Makefile</>, it is important not to skip this step!</para>
642          </para>  
643            <para>The final "make" invokes the C preprocessor to produce the "little
644          <para>The final "make" invokes the C preprocessor to produce            f" files (*.f and *.f90) and then compiles them to object code using
645          the "little f" files (*.f and *.f90) and then compiles them to            the specified FORTRAN compiler and options.  An intermediate script is
646          object code using the specified FORTRAN compiler and options.            often used during this stage to further process (usually, make simple
647          An intermediate script is often used during this stage to            substitutions) custom definitions such as variable types within the
648          further process (usually, make simple substitutions) custom            source files.  This additional stage is necessary in order to overcome
649          definitions such as variable types within the source files.            some of the inconsistencies in the sizes of objects (bytes) between
650          This additional stage is necessary in order to overcome some            different compilers.</para>
         of the inconsistencies in the sizes of objects (bytes) between  
         different compilers.</para>  
651    
652          <para>Please report compilation failures or other problems to          <para>Please report compilation failures or other problems to
653          <email>MITgcm-support@mitgcm.org</email>.</para>            <email>MITgcm-support@mitgcm.org</email>.</para>
654    
655        </sect3>        </sect3>
656    
# Line 613  $ make Line 659  $ make
659      <sect2 id="verification">      <sect2 id="verification">
660        <title>The Verification Suite</title>        <title>The Verification Suite</title>
661    
662        <para>The MITgcm CVS tree (within the        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
663        <filename>$ROOTDIR/verification/</> directory) includes more          directory) includes more than a dozen examples intended for regression
664        than a dozen examples intended for regression testing.  Each one          testing.  Each one of these example directories contains "known-good"
665        of these example directories contains "known-good" output files          output files along with all the input (including both code and data
666        along with all the input (including both code and data files)          files) required for their re-calculation.  These example directories are
667        required for their re-calculation.  These example directories          further broken down into sets of subdirectories
668        are further broken down into sets of subdirectories          (eg. <filename>/input</>, <filename>/code</>) intended to expedite the
669        (eg. <filename>/input</>, <filename>/code</>) intended to          testing process.</para>
       expedite the testing process.</para>  
670    
671        <sect3 id="testreport">        <sect3 id="testreport">
672          <title>The <filename>testreport</> Utility</title>          <title>The <filename>testreport</> Utility</title>
673    
674          <para>Also included in <filename>$ROOTDIR/verification/</> are          <para>Also included in <filename>$ROOTDIR/verification/</> are shell
675          shell scripts for automated testing.  The newest script (which            scripts for automated testing.  The newest script (which was written
676          was written to work with <filename>genmake2</>) is called            to work with <filename>genmake2</>) is called <filename>testreport</>.
677          <filename>testreport</>.  Ths script can be used to build the            This script can be used to build different versions of the MITgcm
678          different versions of the MITgcm code, run the various            code, run the various examples, compare the output, and (if specified)
679          examples, compare the output, and (if specified) email the            email the results of each one of these tests to a central
680          results of each one of these tests to a central            repository.</para>
681          repository.</para>  
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          <para>The <filename>testreport</> script accepts a number of
699          command-line options which can be listed using the            command-line options which can be listed using the <filename>-help</>
700          <filename>-help</> option.  The most important ones are:</para>            option.  The most important ones are:</para>
701    
702          <variablelist>          <variablelist>
703    
704            <varlistentry>            <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>              <term><filename>-tdir TESTDIR</></term>
715              <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>              <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
716              <listitem>              <listitem>
717                <para>This option specifies the test directory or list                <para>This option specifies the test directory or list of test
718                of test directories that should be used.  Each of these                  directories that should be used.  Each of these entries should
719                entries should exactly (note: they're case sensitive!)                  exactly (note: they are case sensitive!) match the names of
720                match the names of directries in                  directries in <filename>$ROOTDIR/verification/</>.  If this
721                <filename>$ROOTDIR/verification/</>.  If this option is                  option is omitted, then all directories that are properly
722                omitted, then all directories that are properly                  formatted (that is, containing an <filename>input</>
723                formatted (that is, containing an <filename>input</>                  sub-directory and a <filename>results/output.txt</> file) will
724                sub-directory and example output) will be used.</para>                  be used.</para>
725              </listitem>              </listitem>
726            </varlistentry>            </varlistentry>
727    
# Line 660  $ make Line 729  $ make
729              <term><filename>-optfile=/PATH/FILENAME</></term>              <term><filename>-optfile=/PATH/FILENAME</></term>
730              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
731              <listitem>              <listitem>
732                <para>This specifies a list of "options files" that will                <para>This specifies a list of "options files" that will be passed
733                be passed to <filename>genmake2</>.  If multiple options                  to <filename>genmake2</>.  If multiple options files are used
734                files are used (say, to test different compilers or                  (say, to test different compilers or different sets of options
735                different sets of options for the same compiler), then                  for the same compiler), then each options file will be used with
736                each options file will be used with each of the test                  each of the test directories.</para>
               directories.</para>  
737              </listitem>              </listitem>
738            </varlistentry>            </varlistentry>
739    
# Line 674  $ make Line 742  $ make
742              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
743              <listitem>              <listitem>
744                <para>Send the results (namely, <filename>output.txt</>,                <para>Send the results (namely, <filename>output.txt</>,
745                <filename>gm_local</>, <filename>gm_state</>, and                  <filename>genmake_local</>, <filename>genmake_state</>, and
746                <filename>Makefile</>) to the specified email addresses.                  <filename>Makefile</>) to the specified email addresses.  The
747                The results are gzipped, placed in a tar file, MIME                  results are gzipped, placed in a tar file, MIME encoded, and
748                encoded, and sent to an @mitgcm.org address.  If no                  sent to the specified address.  If no email addresses are
749                email addresses are specified, no mail is sent.</para>                  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>              </listitem>
778            </varlistentry>            </varlistentry>
779    
780          </variablelist>          </variablelist>
781    
782          <para>The <filename>testreport</> script will write progress          <para>The <filename>testreport</> script will write progress to the
783          to the screen (stdout) as it runs.  In addition, it will            screen (stdout) as it runs.  In addition, it will create a
784          create a <filename>summary.txt</> file that contains a brief            <filename>tr_out.txt</> file that contains a brief comparison of the
785          comparison of the current output with the "known-good"            current output with the "known-good" output.</para>
         output.</para>  
786    
787        </sect3>        </sect3>
788    
789      </sect2>      </sect2>
790    
791    
792      <sect2 id="packages">      <sect2 id="packages">
793        <title>Creating MITgcm Packages</title>        <title>Creating MITgcm Packages</title>
794    
795        <para>Optional parts of code have been separated from the MITgcmUV        <para>Optional parts of code have been separated from the MITgcmUV core
796        core driver code and organised into packages. The packaging          driver code and organised into packages.  The packaging structure
797        structure provides a mechanism for maintaining suites of code,          provides a mechanism for maintaining suites of code, specific to
798        specific to particular classes of problems, in a way that is          particular classes of problems, in a way that is cleanly separated from
799        cleanly separated from the generic fluid dynamical          the generic fluid dynamical engine.</para>
800        engine.</para>  
801          <para>The MITgcmUV packaging structure is described below using generic
802        <para>The MITgcmUV packaging structure is described below using          package names ${pkg}.  A concrete examples of a package is the code for
803        generic package names ${pkg}.  A concrete examples of a package          implementing GM/Redi mixing. This code uses the package name</para>
       is the code for implementing GM/Redi mixing. This code uses the  
       package name</para>  
804    
805      </sect2>      </sect2>
806    
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4
  ViewVC Help
Powered by ViewVC 1.1.22