/[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.4 by edhill, Thu Nov 20 00:01:42 2003 UTC revision 1.5 by edhill, Wed Dec 10 20:44:39 2003 UTC
# Line 2  Line 2 
2    
3  <article id="MITgcm-Development-HOWTO">  <article id="MITgcm-Development-HOWTO">
4    
 <!--  
 Build commands:  
   db2ps -d ldp.dsl devel_HOWTO.sgml  
   db2pdf -d ldp.dsl devel_HOWTO.sgml  
   db2html -d ./ldp.dsl devel_HOWTO.sgml  
   db2html -u -d ./ldp.dsl devel_HOWTO.sgml  
 -->  
   
5    <articleinfo>    <articleinfo>
6      <title>MITgcm Development HOWTO</title>      <title>MITgcm Development HOWTO</title>
7    
# Line 63  Build commands: Line 55  Build commands:
55      <sect2>      <sect2>
56        <title>User Manual</title>        <title>User Manual</title>
57    
58        <para>Before jumping into        <para>Before jumping into development, please familiarize yourself with
59        development, please familiarize yourself with the MITgcm user          the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
60        manual which is available <ulink          </ulink>.  This document contains volumes of useful information and is
61        url="http://mitgcm.org/">on the main web page</ulink>.  This          included here by reference.</para>
       document contains volumes of useful information and is included  
       here by reference.</para>  
62    
63        <para>Also, a "snapshot" or<ulink        <!--
64          <para>Also, a "snapshot" or <ulink
65        url="http://mitgcm.org/dev_docs/">development version</ulink> of        url="http://mitgcm.org/dev_docs/">development version</ulink> of
66        the user manual may be available, though this is only put on the        the user manual may be available, though this is only put on the
67        web for testing purposes.</para>        web for testing purposes.</para>
68          -->
69      </sect2>      </sect2>
70    
71      <sect2>      <sect2>
# Line 300  checkpoint50d_pre Line 292  checkpoint50d_pre
292        server using:</para>        server using:</para>
293    
294  <screen>  <screen>
295  $ export CVS_RSH=ssh    $ export CVS_RSH=ssh
296  $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'    $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
297  $ mkdir scratch    $ mkdir scratch
298  $ cvs co MITgcm manual mitgcm.org    $ cvs co MITgcm manual mitgcm.org
299  </screen>  </screen>
300    
301        <para>These commands extract the necessary information from the        <para>These commands extract the necessary information from the
# Line 371  $ cvs co MITgcm manual mitgcm.org Line 363  $ cvs co MITgcm manual mitgcm.org
363        site can be built using:</para>        site can be built using:</para>
364    
365  <screen>  <screen>
366  $ cd mitgcm.org/devel/buildweb    $ cd mitgcm.org/devel/buildweb
367  $ make All    $ make All
368  </screen>  </screen>
369    
370        <para>Which builds the PDF from the LaTeX source, creates the        <para>Which builds the PDF from the LaTeX source, creates the
# Line 390  $ make All Line 382  $ make All
382        area:</para>        area:</para>
383    
384  <screen>  <screen>
385  $ mv scratch/dev_docs /u/u0/httpd/html    $ mv scratch/dev_docs /u/u0/httpd/html
386  </screen>  </screen>
387    
388        <para>and the update is complete.</para>        <para>and the update is complete.</para>
# Line 412  $ mv scratch/dev_docs /u/u0/httpd/html Line 404  $ mv scratch/dev_docs /u/u0/httpd/html
404          For MITgcm, the process is similar.  Typical commands are:</para>          For MITgcm, the process is similar.  Typical commands are:</para>
405    
406  <screen>  <screen>
407  $ genmake -mods=../code    $ genmake -mods=../code
408  $ make depend    $ make depend
409  $ make    $ make
410  </screen>  </screen>
411    
412        <para>The following sections describe the individual steps in the build        <para>The following sections describe the individual steps in the build
# Line 448  $ make Line 440  $ make
440          simple as:</para>          simple as:</para>
441    
442  <screen>  <screen>
443  $ genmake2 -mods=../code    $ genmake2 -mods=../code
444  </screen>  </screen>
445    
446          <para>However, some systems (particularly commercial Unixes that lack a          <para>However, some systems (particularly commercial Unixes that lack a
# Line 457  $ genmake2 -mods=../code Line 449  $ genmake2 -mods=../code
449            the following: </para>            the following: </para>
450    
451  <screen>  <screen>
452  $ /usr/bin/sh genmake2 -make=gmake  -mods=../code    $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
453  $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code    $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
454  </screen>  </screen>
455    
456          <para>The genmake2 code has been written in a Bourne and BASH (v1)          <para>The genmake2 code has been written in a Bourne and BASH (v1)
# Line 491  $ /opt/gnu/bin/bash genmake2 -ieee -make Line 483  $ /opt/gnu/bin/bash genmake2 -ieee -make
483            from:</para>            from:</para>
484    
485  <screen>  <screen>
486  $ genmake2 -help    $ genmake2 -help
487  </screen>  </screen>
488    
489          <para>The most important options for <filename>genmake2</> are:</para>          <para>The most important options for <filename>genmake2</> are:</para>
# Line 547  $ genmake2 -help Line 539  $ genmake2 -help
539                specified, then it is assumed that the two packages are compatible                specified, then it is assumed that the two packages are compatible
540                and will function either with or without each other.</para>                and will function either with or without each other.</para>
541              </listitem>              </listitem>
   
542            </varlistentry>            </varlistentry>
543    
544            <varlistentry>            <varlistentry>
# Line 562  $ genmake2 -help Line 553  $ genmake2 -help
553            </varlistentry>            </varlistentry>
554    
555            <varlistentry>            <varlistentry>
556                <term><filename>-adof=/path/to/file</></term>
557                <term><filename>-adoptfile=/path/to/file</></term>
558                <listitem>
559                  <para>This option specifies the "adjoint" or automatic
560                    differentiation options file to be used.  The file is analogous
561                    to the "optfile" defined above but it specifies information for
562                    the AD build process.  The default file is located in <filename>
563                    $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
564                    defines the "TAF" and "TAMC" compilers.  An alternate version is
565                    also available at <filename>
566                    $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
567                    newer "STAF" compiler.  As with any compilers, it is helpful to
568                    have their directories listed in your $PATH environment
569                    variable.</para>
570                </listitem>
571              </varlistentry>
572    
573              <varlistentry>
574              <term><filename>-mods=DIR</></term>              <term><filename>-mods=DIR</></term>
575              <term><filename>-mods='DIR1 [DIR2 ...]'</></term>              <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
576              <listitem>              <listitem>
# Line 615  $ genmake2 -help Line 624  $ genmake2 -help
624        </sect3>        </sect3>
625    
626        <sect3 id="makefile_use">        <sect3 id="makefile_use">
627          <title>Using <filename>Makefile</></title>          <title>Using the <filename>Makefile</></title>
628    
629          <para>Once a <filename>Makefile</> has been created, one can          <para>Once a <filename>Makefile</> has been created using
630          build an executable using:</para>            <filename>genmake2</>, one can build a "standard" (forward
631              simulator) executable using:</para>
632    
633  <screen>  <screen>
634  $ make CLEAN    $ make CLEAN
635  $ make depend    $ make depend
636  $ make    $ make
637  </screen>  </screen>
638    
639          <para>The "make CLEAN" step will remove any stale source files, include          <para>The "make CLEAN" step will remove any stale source files, include
# Line 647  $ make Line 657  $ make
657            substitutions) custom definitions such as variable types within the            substitutions) custom definitions such as variable types within the
658            source files.  This additional stage is necessary in order to overcome            source files.  This additional stage is necessary in order to overcome
659            some of the inconsistencies in the sizes of objects (bytes) between            some of the inconsistencies in the sizes of objects (bytes) between
660            different compilers.</para>            different compilers. The result of the build process is an executable
661              with the name <filename>mitgcmuv</>.</para>
662    
663            <para>In addition to the forward simulator described above, the
664              <filename>Makefile</> also has a number of targets that can be used to
665              produce various adjoint and tangent-linear builds for optimization and
666              other parameter-sensitivity problems.  The additional targets within
667              the <filename>Makefile</> are:</para>
668    
669            <variablelist>
670    
671              <varlistentry>
672                <term><filename>make adall</></term>
673                <listitem>
674                  <para>This target produces an <filename>mitgcmuv_ad</> executable
675                    using the <filename>taf</> or <filename>staf</> adjoint
676                    compiler.  See the <filename>genmake2</> "-adof" option for
677                    compiler selection.</para>
678                </listitem>
679              </varlistentry>
680    
681              <varlistentry>
682                <term><filename>make ftlall</></term>
683                <listitem>
684                  <para>Similar to <filename>make adall</> above, this
685                    produces...</para>
686                </listitem>
687              </varlistentry>
688    
689            </variablelist>
690    
691          <para>Please report compilation failures or other problems to          <para>Please report any compilation failures or other build problems to
692            <email>MITgcm-support@mitgcm.org</email>.</para>            the <email>MITgcm-support@mitgcm.org</email> list.</para>
693    
694        </sect3>        </sect3>
695    
# Line 683  $ make Line 722  $ make
722          line as simple as:</para>          line as simple as:</para>
723    
724  <screen>  <screen>
725  $ cd verification    $ cd verification
726  $ ./testreport -ieee    $ ./testreport -ieee
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 -ieee -t 'exp0 exp4'
734  $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'    $ /some/path/to/bash ./testreport -ieee -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
Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5
  ViewVC Help
Powered by ViewVC 1.1.22