/[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.13 by jmc, Sat May 15 01:44:50 2010 UTC revision 1.15 by jmc, Tue Mar 1 01:33:19 2011 UTC
# Line 303  Line 303 
303    
304      <sect2>      <sect2>
305        <title>Main code development</title>        <title>Main code development</title>
306        <para>(formerly named "Tagging" ; this section needs an update)</para>        <para><emphasis>(formerly named "Tagging" ; this section needs an update)
307            </emphasis></para>
308    
309        <para>The intent of tagging is to create "known-good" checkpoints that        <para>The intent of tagging is to create "known-good" checkpoints that
310        developers can use as references.  Traditionally, MITgcm tagging has        developers can use as references.  Traditionally, MITgcm tagging has
# Line 393  checkpoint50d_pre Line 394  checkpoint50d_pre
394          For MITgcm, the process is similar.  Typical commands are:</para>          For MITgcm, the process is similar.  Typical commands are:</para>
395    
396  <screen>  <screen>
397    $ genmake -mods=../code    $ genmake2 -mods=../code
398    $ make depend    $ make depend
399    $ make    $ make
400  </screen>  </screen>
# Line 404  checkpoint50d_pre Line 405  checkpoint50d_pre
405        <sect3 id="genmake">        <sect3 id="genmake">
406          <title>The <filename>genmake2</> Utility</title>          <title>The <filename>genmake2</> Utility</title>
407    
408          <para><emphasis>Please note that the older <filename>genmake</> is          <para><emphasis>(Note: the older <filename>genmake</>
409              deprecated and will eventually be replaced by <filename>genmake2</>.              has been replaced by <filename>genmake2</>)</emphasis></para>
             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          <para>The first step in any MITgcm build is to create a Unix-style
412            <filename>Makefile</filename> which will be parsed by            <filename>Makefile</filename> which will be parsed by
# Line 462  checkpoint50d_pre Line 462  checkpoint50d_pre
462              <para>an "options file" as specified by the command-line option              <para>an "options file" as specified by the command-line option
463                <filename>-optfile='FILENAME'</filename></para>                <filename>-optfile='FILENAME'</filename></para>
464            </listitem>            </listitem>
465              <listitem>
466                <para> a <filename>packages.conf</filename> file (in the current
467                  directory or in one of the "MODS" directories, see below)
468                  which contains the specific list of packages to compile
469                </para>
470              </listitem>
471          </orderedlist>          </orderedlist>
472    
473          <para>then checking certain dependency rules (the package dependencies),          <para>then checking certain dependency rules (the package dependencies),
# Line 515  checkpoint50d_pre Line 521  checkpoint50d_pre
521            </varlistentry>            </varlistentry>
522    
523            <varlistentry>            <varlistentry>
             <term><filename>-pdepend=/PATH/FILENAME</></term>  
   
             <listitem>  
               <para>This specifies the dependency file used for packages.  If  
               not specified, the default dependency file is  
               <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is  
               parsed on a line-by-line basis where each line containes either a  
               comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule  
               where the "+" or "-" symbol specifies a "must be used with" or a  
               "must not be used with" relationship, respectively.  If no rule is  
               specified, then it is assumed that the two packages are compatible  
               and will function either with or without each other.</para>  
             </listitem>  
           </varlistentry>  
   
           <varlistentry>  
             <term><filename>-pdefault=PKG</></term>  
             <term><filename>-pdefault='PKG1 [PKG2 PKG3 ...]'</></term>  
             <listitem>  
               <para>This option specifies the default set of packages  
               to be used.  If not set, the default package list will  
               be read from  
               <filename>$ROOTDIR/pkg/pkg_default</>.</para>  
             </listitem>  
           </varlistentry>  
   
           <varlistentry>  
524              <term><filename>-adof=/path/to/file</></term>              <term><filename>-adof=/path/to/file</></term>
525              <term><filename>-adoptfile=/path/to/file</></term>              <term><filename>-adoptfile=/path/to/file</></term>
526              <listitem>              <listitem>
# Line 569  checkpoint50d_pre Line 548  checkpoint50d_pre
548                  will be overridden by any identically-named sources within the                  will be overridden by any identically-named sources within the
549                  "MODS" directories.  The order of precedence for this                  "MODS" directories.  The order of precedence for this
550                  "name-hiding" is as follows:</para>                  "name-hiding" is as follows:</para>
                 
551                <itemizedlist>                <itemizedlist>
552                  <listitem><para>"MODS" directories (in the order given)                  <listitem><para>"MODS" directories (in the order given)
553                    </para></listitem>                    </para></listitem>
# Line 581  checkpoint50d_pre Line 559  checkpoint50d_pre
559                  <listitem><para>The "standard dirs" (which may have been                  <listitem><para>The "standard dirs" (which may have been
560                      specified by the "-standarddirs" option)</para></listitem>                      specified by the "-standarddirs" option)</para></listitem>
561                </itemizedlist>                </itemizedlist>
562                </listitem>
563              </varlistentry>
564    
565              <varlistentry>
566                <term><filename>-pgroups=/PATH/FILENAME</></term>
567                <listitem>
568                  <para>This option specifies the file where package groups are
569                  defined.  If not set, the package-groups definition will
570                  be read from
571                  <filename>$ROOTDIR/pkg/pkg_groups</>.</para>
572                  <para>
573                  It also contains the default list of packages (defined
574                  as the group <filename>"default_pkg_list"</>) which is used
575                  when no specific package list (file: <filename>packages.conf</>)
576                  is found in current directory or in any "MODS" directory.
577                  </para>
578                </listitem>
579              </varlistentry>
580    
581              <varlistentry>
582                <term><filename>-pdepend=/PATH/FILENAME</></term>
583    
584                <listitem>
585                  <para>This specifies the dependency file used for packages.  If
586                  not specified, the default dependency file is
587                  <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
588                  parsed on a line-by-line basis where each line containes either a
589                  comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
590                  where the "+" or "-" symbol specifies a "must be used with" or a
591                  "must not be used with" relationship, respectively.  If no rule is
592                  specified, then it is assumed that the two packages are compatible
593                  and will function either with or without each other.</para>
594              </listitem>              </listitem>
595            </varlistentry>            </varlistentry>
596    
# Line 607  checkpoint50d_pre Line 616  checkpoint50d_pre
616          <para>In general, it is best to use <filename>genmake2</> on a "clean"          <para>In general, it is best to use <filename>genmake2</> on a "clean"
617            directory that is free of all source (*.[F,f],*.[F,f]90) and header            directory that is free of all source (*.[F,f],*.[F,f]90) and header
618            (*.h,*.inc) files.  Generally, this can be accomplished in an            (*.h,*.inc) files.  Generally, this can be accomplished in an
619            "un-clean" directory by running "make CLEAN" followed by "make            "un-clean" directory by running "make Clean" followed by "make
620            makefile".</para>            makefile".</para>
621    
622        </sect3>        </sect3>
# Line 620  checkpoint50d_pre Line 629  checkpoint50d_pre
629            simulator) executable using:</para>            simulator) executable using:</para>
630    
631  <screen>  <screen>
632    $ make CLEAN    $ make Clean
633    $ make depend    $ make depend
634    $ make    $ make
635  </screen>  </screen>
636    
637          <para>The "make CLEAN" step will remove any stale source files, include          <para>The "make Clean" step will remove any stale source files, include
638            files, and links.  It is strongly recommended for "un-clean"            files, and links.  It is strongly recommended for "un-clean"
639            directories which may contain the (perhaps partial) results of            directories which may contain the (perhaps partial) results of
640            previous builds.  Such "debris" can interfere with the next stage of            previous builds. Such "debris" can interfere with the next stage of
641            the build.</para>            the build.
642              A more agressive cleaning option, "make CLEAN", can be used to also
643              remove the executable and output files from a previous run.</para>
644    
645          <para>The "make depend" step will create a large number of symbolic          <para>The "make depend" step will create a large number of symbolic
646            links from the local directory to the source file locations.  It also            links from the local directory to the source file locations.  It also
# Line 688  checkpoint50d_pre Line 699  checkpoint50d_pre
699        <title>The Verification Suite</title>        <title>The Verification Suite</title>
700    
701        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
702          directory) includes more than a dozen examples intended for regression          directory) includes many (> 90) examples intended for regression
703          testing.  Each one of these example directories contains "known-good"          testing.  Each one of these example directories contains "known-good"
704          output files along with all the input (including both code and data          output files along with all the input (including both code and data
705          files) required for their re-calculation.  These example directories are          files) required for their re-calculation.  These example directories are
# Line 700  checkpoint50d_pre Line 711  checkpoint50d_pre
711          <title>The <filename>testreport</> Utility</title>          <title>The <filename>testreport</> Utility</title>
712    
713          <para>Also included in <filename>$ROOTDIR/verification/</> are shell          <para>Also included in <filename>$ROOTDIR/verification/</> are shell
714            scripts for automated testing.  The newest script (which was written            scripts for automated testing.  The script (which was written
715            to work with <filename>genmake2</>) is called <filename>testreport</>.            to work with <filename>genmake2</>) is called <filename>testreport</>.
716            This script can be used to build different versions of the MITgcm            This script can be used to build different versions of the MITgcm
717            code, run the various examples, compare the output, and (if specified)            code, run the various examples, compare the output, and (if specified)
# Line 712  checkpoint50d_pre Line 723  checkpoint50d_pre
723    
724  <screen>  <screen>
725    $ cd verification    $ cd verification
726    $ ./testreport -ieee    $ ./testreport
727  </screen>  </screen>
728    
729          <para>However, some systems (those lacking or wiht a broken "/bin/sh")          <para>However, some systems (those lacking or wiht a broken "/bin/sh")
730            may require an explicit shell invocation such as:</para>            may require an explicit shell invocation such as:</para>
731    
732  <screen>  <screen>
733    $ sh ./testreport -ieee -t 'exp0 exp4'    $ sh ./testreport -t 'exp2 exp4'
734    $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'    $ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
735  </screen>  </screen>
736    
737          <para>The <filename>testreport</> script accepts a number of          <para>The <filename>testreport</> script accepts a number of
# Line 730  checkpoint50d_pre Line 741  checkpoint50d_pre
741          <variablelist>          <variablelist>
742    
743            <varlistentry>            <varlistentry>
744              <term><filename>-ieee</></term>              <term><filename>-ieee</> (default) / <filename>-noieee</></term>
745              <listitem>              <listitem>
746                <para>If allowed by the compiler (as defined in the "optfile"),                <para>If allowed by the compiler (as defined in the "optfile"),
747                  use IEEE arithmetic.  This option, along with the GCC compiler,                  use IEEE arithmetic (<filename>genmake2 -ieee</>).
748                  is how the standard results were produced.</para>                  This option, along with the gfortran / gcc compiler,
749                    is how the standard results are produced.</para>
750                </listitem>
751              </varlistentry>
752    
753              <varlistentry>
754                <term><filename>-optfile=/PATH/FILENAME</></term>
755                <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
756                <listitem>
757                  <para>This specifies a list of "options files" that will be passed
758                    to <filename>genmake2</>.  If multiple options files are used
759                    (say, to test different compilers or different sets of options
760                    for the same compiler), then each options file will be used with
761                    each of the test directories.</para>
762              </listitem>              </listitem>
763            </varlistentry>            </varlistentry>
764    
# Line 745  checkpoint50d_pre Line 769  checkpoint50d_pre
769                <para>This option specifies the test directory or list of test                <para>This option specifies the test directory or list of test
770                  directories that should be used.  Each of these entries should                  directories that should be used.  Each of these entries should
771                  exactly (note: they are case sensitive!) match the names of                  exactly (note: they are case sensitive!) match the names of
772                  directries in <filename>$ROOTDIR/verification/</>.  If this                  directories in <filename>$ROOTDIR/verification/</>.  If this
773                  option is omitted, then all directories that are properly                  option is omitted, then all directories that are properly
774                  formatted (that is, containing an <filename>input</>                  formatted (that is, containing an <filename>input</>
775                  sub-directory and a <filename>results/output.txt</> file) will                  sub-directory and a <filename>results/output.txt</> file) will
# Line 754  checkpoint50d_pre Line 778  checkpoint50d_pre
778            </varlistentry>            </varlistentry>
779    
780            <varlistentry>            <varlistentry>
             <term><filename>-optfile=/PATH/FILENAME</></term>  
             <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>  
             <listitem>  
               <para>This specifies a list of "options files" that will be passed  
                 to <filename>genmake2</>.  If multiple options files are used  
                 (say, to test different compilers or different sets of options  
                 for the same compiler), then each options file will be used with  
                 each of the test directories.</para>  
             </listitem>  
           </varlistentry>  
   
           <varlistentry>  
781              <term><filename>-addr EMAIL</></term>              <term><filename>-addr EMAIL</></term>
782              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
783              <listitem>              <listitem>
# Line 779  checkpoint50d_pre Line 791  checkpoint50d_pre
791            </varlistentry>            </varlistentry>
792    
793            <varlistentry>            <varlistentry>
794                <term><filename>-MPI NUMBER_OF_PROCS</></term>
795              <term><filename>-mpi</></term>              <term><filename>-mpi</></term>
796              <listitem>              <listitem>
797                <para>If the necessary files                <para>If the necessary file (<filename>TESTDIR/code/SIZE.h_mpi</>)
798                (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and                exists, then use it (and all <filename>TESTDIR/code/*_mpi</> files)
799                <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an                for an MPI--enabled run.  The new option (<filename>-MPI</> followed
800                MPI--enabled run.  Note that the use of MPI typically requires a                by the maximum number of processors) enable to build and run each
801                  test-experiment using variable number of MPI processors (multiple
802                  of <filename>nPx*nPy</> from <filename>TESTDIR/code/SIZE.h_mpi</>
803                  and not larger than <filename>NUMBER_OF_PROCS</>).
804                  The short option ("-mpi") can only be used to build and run on 2 MPI
805                  processors (equivalent to "<filename>-MPI 2</>").</para>
806                  <para>Note that the use of MPI typically requires a
807                special command option (see "-command" below) to invoke the MPI                special command option (see "-command" below) to invoke the MPI
808                executable.  Examples of PBS scripts using MPI with testreport can be                executable.  Examples of PBS scripts using testreport with MPI can be
809                found in the <ulink                found in the <ulink
810                url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">                url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
811                MITgcm-contrib area</ulink></para>                tools/example_scripts directory</ulink>.</para>
812              </listitem>              </listitem>
813            </varlistentry>            </varlistentry>
814    
815            <varlistentry>            <varlistentry>
816              <term><filename>-command='some command to run'</></term>              <term><filename>-command='some command to run'</></term>
817              <listitem>              <listitem>
818                <para>For some tests, particularly MPI runs, the default "make                <para>For some tests, particularly MPI runs, a specific command
819                output.txt" is not sufficient.  This option allows a more general                might be needed to run the executable. This option allows a more general
820                command (or shell script) to be invoked.  Examples of PBS scripts                command (or shell script) to be invoked.  Examples of PBS scripts
821                using MPI with testreport can be found in the <ulink                using testreport with MPI can be found in the <ulink
822                url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">                url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
823                MITgcm-contrib area</ulink></para>                tools/example_scripts directory</ulink>.</para>
824              </listitem>              </listitem>
825            </varlistentry>            </varlistentry>
826    
Legend:
Removed from v.1.13  
changed lines
  Added in v.1.15
  ViewVC Help
Powered by ViewVC 1.1.22