/[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.6 by jmc, Tue Dec 23 22:42:20 2003 UTC revision 1.7 by edhill, Tue Apr 6 04:12:00 2004 UTC
# Line 182  Line 182 
182        <title>Branches</title>        <title>Branches</title>
183    
184        <para>As shown in the online <ulink        <para>As shown in the online <ulink
185        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">ViewCVS-generated        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">
186        tree</ulink>, the MITgcm codebase is split into to two branches        ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two
187        or "lines" under which development proceeds.  These two lines        branches or "lines" under which development proceeds.  These two lines are
188        are referred to as the "MAIN" and "ecco" versions of the code.        referred to as the "MAIN" and "ecco" versions of the code.  While not
189        While not identical, the bulk of the MAIN and ecco lines are        identical, the bulk of the MAIN and ecco lines are composed of files from
190        composed of files from the same codebase.        the same codebase.
191        </para>        </para>
192    
193        <para>Periodically, a "Release" branch is formed from the "MAIN"        <para>Periodically, a "Release" branch is formed from the "MAIN"
194        development branch.  This is done in order to create a        development branch.  This is done in order to create a relatively stable
195        relatively stable reference point for both users and developers.        reference point for both users and developers.  The intent is that once a
196        The intent is that once a relese branch has been created, only        relese branch has been created, only bug-fixes will be added to it.
197        bug-fixes will be added to it.  Meanwhile, development (which        Meanwhile, development (which might "break" or otherwise render invalid
198        might "break" or otherwise render invalid the documentation,        the documentation, tutorials, and/or examples contained within a release
199        tutorials, and/or examples contained within a release branch) is        branch) is allowed to continue along the MAIN and ecco lines.</para>
       allowed to continue along the MAIN and ecco lines.</para>  
200      </sect2>      </sect2>
201    
202      <sect2>      <sect2>
203        <title>Tagging</title>        <title>Tagging</title>
204    
205        <para>The intent of tagging is to create "known-good"        <para>The intent of tagging is to create "known-good" checkpoints that
206        checkpoints that developers can use as references.        developers can use as references.  Traditionally, MITgcm tagging has
207        Traditionally, MITgcm tagging has maintained the following        maintained the following conventions:</para>
       conventions:</para>  
208    
209        <orderedlist>        <orderedlist>
210          <listitem>          <listitem>
211            <para>Developer checks out code into a local CVS-managed            <para>Developer checks out code into a local CVS-managed directory,
212            directory, makes various changes/additions, tests these            makes various changes/additions, tests these edits, and eventually
213            edits, and eventually reaches a point where (s)he is            reaches a point where (s)he is satisfied that the changes form a new
214            satisfied that the changes form a new "useful" point in the            "useful" point in the evolution of the code.</para>
           evolution of the code.</para>  
215          </listitem>          </listitem>
216    
217          <listitem>          <listitem>
218            <para>The developer then runs the <ulink            <para>The developer then runs the <ulink
219            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">
220            shell script to see if any problems are introduced.  While            testscript</ulink> shell script to see if any problems are introduced.
221            not intended to be exhaustive, the test cases within the            While not intended to be exhaustive, the test cases within the
222            verification directory do provide some indication whether            verification directory do provide some indication whether gross errors
223            gross errors have been introduced.            have been introduced.
224            </para>            </para>
225          </listitem>          </listitem>
226    
# Line 233  Line 230 
230            then:</para>            then:</para>
231            <orderedlist>            <orderedlist>
232              <listitem>              <listitem>
233                <para>adds a "checkpointXY_pre" comment (where X is a                <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
234                checkpoint number and Y is a letter) to the <ulink                number and Y is a letter) to the <ulink
235                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">tag-index</ulink>                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">
236                file and checks it into the CVS repository</para>                tag-index</ulink> file and checks it into the CVS
237                  repository</para>
238              </listitem>              </listitem>
239              <listitem>              <listitem>
240                <para>submits the set of changes to the CVS repository                <para>submits the set of changes to the CVS repository and adds
241                and adds comments to <filename>tag-index</filename>                comments to <filename>tag-index</filename> describing what the
242                describing what the changes are along with a matching                changes are along with a matching "checkpointXY_post" entry</para>
               "checkpointXY_post" entry</para>  
243              </listitem>              </listitem>
244            </orderedlist>            </orderedlist>
245          </listitem>          </listitem>
246        </orderedlist>        </orderedlist>
247    
248        <para>The result of this tagging procedure is a sequence of        <para>The result of this tagging procedure is a sequence of development
249        development checkpoints with comments which resembles:</para>        checkpoints with comments which resembles:</para>
250    
251  <programlisting>  <programlisting>
252  checkpoint50e_post  checkpoint50e_post
# Line 271  o fix small problem with in ptracers_wri Line 268  o fix small problem with in ptracers_wri
268  checkpoint50d_pre  checkpoint50d_pre
269  </programlisting>  </programlisting>
270    
271        <para>This information can be used to refer to various stages of        <para>This information can be used to refer to various stages of the code
272        the code development.  For example, bugs can be traced to        development.  For example, bugs can be traced to individual sets of CVS
273        individual sets of CVS checkins based upon their first        checkins based upon their first appearance when comparing the results from
274        appearance when comparing the results from different        different checkpoints.</para>
       checkpoints.</para>  
275    
276      </sect2>      </sect2>
277    </sect1>    </sect1>
# Line 287  checkpoint50d_pre Line 283  checkpoint50d_pre
283      <sect2 id="documentation_getting">      <sect2 id="documentation_getting">
284        <title>Getting the Docs and Code</title>        <title>Getting the Docs and Code</title>
285    
286        <para>The first step towards editing the documentation is to        <para>The first step towards editing the documentation is to checkout a
287        checkout a copy of code, docs, and build scripts from the CVS        copy of code, docs, and build scripts from the CVS server using:</para>
       server using:</para>  
288    
289  <screen>  <screen>
290    $ export CVS_RSH=ssh    $ export CVS_RSH=ssh
291    $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'    $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
292    $ mkdir scratch    $ mkdir scratch
293    $ cvs co MITgcm manual mitgcm.org    $ cvs co MITgcm manual mitgcm.org
294  </screen>  </screen>
295    
296        <para>These commands extract the necessary information from the        <para>These commands extract the necessary information from the CVS server
297        CVS server and create a temporary (called        and create a temporary (called <filename>scratch</filename>) directory for
298        <filename>scratch</filename>) directory for the storage of the        the storage of the HTML and other files that will be created.  Please note
299        HTML and other files that will be created.  Please note that you        that you must either create <filename>scratch</filename> as shown or edit
300        must either create <filename>scratch</filename> as shown or edit        the various <filename>Makefile</filename>s and scripts used to create the
301        the various <filename>Makefile</filename>s and scripts used to        documentation.</para>
       create the documentation.</para>  
302      </sect2>      </sect2>
303    
304      <sect2>      <sect2>
305        <title>Editing the Documentation</title>        <title>Editing the Documentation</title>
306    
307        <para>The documentation is contained in the        <para>The documentation is contained in the <filename>manual</filename>
308        <filename>manual</filename> directory in a raw LaTeX format.        directory in a raw LaTeX format.  The main document is
309        The main document is <filename>manual.tex</filename> and it uses        <filename>manual.tex</filename> and it uses <command>\input{}</command>s
310        <command>\input{}</command>s to include the chapters and        to include the chapters and subsections.</para>
311        subsections.</para>  
312          <para>Since the same LaTeX source is used to produce PostScript, PDF, and
313        <para>Since the same LaTeX source is used to produce PostScript,        HTML output, care should be taken to follow certain conventions.  Two of
314        PDF, and HTML output, care should be taken to follow certain        the most important are the usage of the <command>\filelink{}{}</command>
315        conventions.  Two of the most important are the usage of the        and <command>\varlink{}{}</command> commands.  Both of these commands have
316        <command>\filelink{}{}</command> and        been defined to simplify the connection between the automatically
317        <command>\varlink{}{}</command> commands.  Both of these        generated ("code browser") HTML and the HTML version of the manual
318        commands have been defined to simplify the connection between        produced by LaTeX2HTML.  They each take two arguments (corresponding to
319        the automatically generated ("code browser") HTML and the HTML        the contents of the two sets of curly braces) which are the text that the
320        version of the manual produced by LaTeX2HTML.  They each take        author wishes to be "wrapped" within the link, and a specially formatted
321        two arguments (corresponding to the contents of the two sets of        link thats relative to the <filename>MITgcm</filename> directory within
322        curly braces) which are the text that the author wishes to be        the CVS tree.</para>
       "wrapped" within the link, and a specially formatted link thats  
       relative to the <filename>MITgcm</filename> directory within the  
       CVS tree.</para>  
323    
324        <para>The result is a command that resembles either</para>        <para>The result is a command that resembles either</para>
325                
# Line 367  checkpoint50d_pre Line 358  checkpoint50d_pre
358    $ make All    $ make All
359  </screen>  </screen>
360    
361        <para>Which builds the PDF from the LaTeX source, creates the        <para>Which builds the PDF from the LaTeX source, creates the HTML output
362        HTML output from the LaTeX source, parses the FORTRAN code base        from the LaTeX source, parses the FORTRAN code base to produce a
363        to produce a hyperlinked HTML version of the source, and then        hyperlinked HTML version of the source, and then determines the
364        determines the cross-linking between the various HTML        cross-linking between the various HTML components.</para>
365        components.</para>  
366          <para>If there are no errors, the result of the build process (which can
367        <para>If there are no errors, the result of the build process        take 30+ minutes on a P4/2.5Ghz) will be contained within a single
368        (which can take 30+ minutes on a P4/2.5Ghz) will be contained        directory called <filename>scratch/dev_docs</filename>.  This is a freshly
369        within a single directory called        built version of the entire on-line users manual.  If you have the correct
370        <filename>scratch/dev_docs</filename>.  This is a freshly built        permissions, it can be directly copied to the web server area:</para>
       version of the entire on-line users manual.  If you have the  
       correct permissions, it can be directly copied to the web server  
       area:</para>  
371    
372  <screen>  <screen>
373    $ mv scratch/dev_docs /u/u0/httpd/html    $ mv scratch/dev_docs /u/u0/httpd/html
Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7
  ViewVC Help
Powered by ViewVC 1.1.22