/[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.12 by dimitri, Tue Apr 27 04:03:45 2010 UTC revision 1.14 by jmc, Fri May 28 01:47:32 2010 UTC
# Line 1  Line 1 
1  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2    <!--
3     $Header$
4     $Name$
5    -->
6    
7  <article id="MITgcm-Development-HOWTO">  <article id="MITgcm-Development-HOWTO">
8    
# Line 121  Line 125 
125        others.  The tree currently resembles:</para>        others.  The tree currently resembles:</para>
126    
127  <programlisting>gcmpack/  <programlisting>gcmpack/
   CS-regrid             goes into utils  
128    CVSROOT               -hidden-    CVSROOT               -hidden-
129    
130    MITgcm                code    MITgcm                code
# Line 145  Line 148 
148    
149    acesgrid.org          build acesgrid web site    acesgrid.org          build acesgrid web site
150    development           experimental stuff    development           experimental stuff
   gcmpack               an old back-up copy ?  
151    gfd_lab               -?-    gfd_lab               -?-
152    manual                -save-    manual                source of MITgcm documentation
   misc                  -?-  
153    mitgcm.org            build web site    mitgcm.org            build web site
154    mitgcmdoc  -> manual  -remove-    old_develop           old and early development source
155    models                -?-         misc                 -?-
156    packages              -?-         models               -?-
157           packages             -?-
158           preprocess           -?-
159    pdfs                  some pdfs    pdfs                  some pdfs
160    planetinabottle.org   unfinished web site    planetinabottle.org   unfinished web site
   preprocess            -?-  
   tmp                   -?-  
161    www.ecco-group.org    build ecco web site ?    www.ecco-group.org    build ecco web site ?
162  </programlisting>  </programlisting>
163    
# Line 302  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 392  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 403  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 461  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 514  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 568  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 580  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 606  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 619  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
Legend:
Removed from v.1.12  
changed lines
  Added in v.1.14
  ViewVC Help
Powered by ViewVC 1.1.22