| 30 |
update links. |
update links. |
| 31 |
</revremark> |
</revremark> |
| 32 |
</revision> |
</revision> |
| 33 |
|
<revision> |
| 34 |
|
<revnumber>0.03</revnumber> |
| 35 |
|
<date>2010-04-25</date> |
| 36 |
|
<authorinitials>jmc</authorinitials> |
| 37 |
|
<revremark> |
| 38 |
|
Add subsection "Developer settings" (under CVS Repository). |
| 39 |
|
</revremark> |
| 40 |
|
</revision> |
| 41 |
</revhistory> |
</revhistory> |
| 42 |
|
|
| 43 |
<abstract> |
<abstract> |
| 110 |
|
|
| 111 |
<sect1 id="cvs"> |
<sect1 id="cvs"> |
| 112 |
<title>CVS Repository</title> |
<title>CVS Repository</title> |
| 113 |
|
|
| 114 |
<sect2> |
<sect2> |
| 115 |
<title>Layout</title> |
<title>Layout</title> |
| 116 |
|
|
| 121 |
others. The tree currently resembles:</para> |
others. The tree currently resembles:</para> |
| 122 |
|
|
| 123 |
<programlisting>gcmpack/ |
<programlisting>gcmpack/ |
|
MITgcm-contrib contributed code |
|
| 124 |
CS-regrid goes into utils |
CS-regrid goes into utils |
| 125 |
cvspolicy.html -save- |
CVSROOT -hidden- |
|
CVSROOT -save- |
|
|
development experimental stuff |
|
|
manual -save- |
|
|
misc -?- |
|
| 126 |
|
|
| 127 |
MITgcm code |
MITgcm code |
| 128 |
adjoint fold into genmake |
bin empty |
| 129 |
bin stub for ecco build |
doc basic developpment documentation |
| 130 |
compare01 old from 20th century |
eesupp execution environment support code (wrapper) |
| 131 |
diags timeave f77 in pkgs now |
exe empty |
| 132 |
doc tags -- connect to real docs? |
jobs runtime shell scripts for |
| 133 |
eesupp cnh? |
various platforms (not maintained) |
| 134 |
exe ecco user build |
lsopt line search |
| 135 |
,- jobs runtime shell scripts for |
model main dynamics (core) |
| 136 |
| various platforms |
optim line search interface |
| 137 |
| lsopt line search |
pkg alternate and optional numerics, etc. |
| 138 |
m| model main dynamics (core) |
tools scripts to build (and test) |
| 139 |
e| optimization_drivers ? |
utils pre/post processing tools (matlab, ..) |
| 140 |
r| optim line search interface |
verification standard regression tests + examples |
| 141 |
g| pkg alternate and optional numerics, etc. |
+ documented examples (tutorials) |
| 142 |
e|- tools |
tutorial_examples (only in release1 branch) |
|
?| tutorial_examples documented tests |
|
|
| only populated on release1 branch |
|
|
| and not validated during "testreport" |
|
|
'- utils |
|
|
verification std tests |
|
| 143 |
|
|
| 144 |
|
MITgcm_contrib contributed code |
| 145 |
|
|
| 146 |
mitgcmdoc -> manual -remove- |
acesgrid.org build acesgrid web site |
| 147 |
|
development experimental stuff |
| 148 |
|
gcmpack an old back-up copy ? |
| 149 |
|
gfd_lab -?- |
| 150 |
|
manual -save- |
| 151 |
|
misc -?- |
| 152 |
mitgcm.org build web site |
mitgcm.org build web site |
| 153 |
|
mitgcmdoc -> manual -remove- |
| 154 |
models -?- |
models -?- |
| 155 |
packages -?- |
packages -?- |
| 156 |
|
pdfs some pdfs |
| 157 |
|
planetinabottle.org unfinished web site |
| 158 |
preprocess -?- |
preprocess -?- |
| 159 |
tmp -?- |
tmp -?- |
| 160 |
|
www.ecco-group.org build ecco web site ? |
| 161 |
</programlisting> |
</programlisting> |
| 162 |
|
|
| 163 |
|
<!-- |
| 164 |
<para>Efforts are underway to reduce the complexity.</para> |
<para>Efforts are underway to reduce the complexity.</para> |
| 165 |
|
--> |
| 166 |
|
|
| 167 |
</sect2> |
</sect2> |
| 168 |
|
|
| 201 |
<title>Branches</title> |
<title>Branches</title> |
| 202 |
|
|
| 203 |
<para>As shown in the online <ulink |
<para>As shown in the online <ulink |
| 204 |
url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index?view=graph"> |
url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph"> |
| 205 |
ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two |
ViewCVS-generated tree</ulink>, the MITgcm codebase is split into |
| 206 |
branches or "lines" under which development proceeds. These two lines are |
branches or "lines" under which development proceeds. The main line |
| 207 |
referred to as the "MAIN" and "ecco" versions of the code. While not |
of development is referred to as the "MAIN" version of the code. |
|
identical, the bulk of the MAIN and ecco lines are composed of files from |
|
|
the same codebase. |
|
| 208 |
</para> |
</para> |
| 209 |
|
|
| 210 |
<para>Periodically, a "Release" branch is formed from the "MAIN" |
<para>Periodically, a "Release" branch is formed from the "MAIN" |
| 211 |
development branch. This is done in order to create a relatively stable |
development branch. This is done in order to create a relatively stable |
| 212 |
reference point for both users and developers. The intent is that once a |
reference point for both users and developers. The intent is that once a |
| 213 |
relese branch has been created, only bug-fixes will be added to it. |
release branch has been created, only bug-fixes will be added to it. |
| 214 |
Meanwhile, development (which might "break" or otherwise render invalid |
Meanwhile, development (which might "break" or otherwise render invalid |
| 215 |
the documentation, tutorials, and/or examples contained within a release |
the documentation, tutorials, and/or examples contained within a release |
| 216 |
branch) is allowed to continue along the MAIN and ecco lines.</para> |
branch) is allowed to continue along the MAIN line.</para> |
| 217 |
|
</sect2> |
| 218 |
|
|
| 219 |
|
<sect2> |
| 220 |
|
<title> Developer settings </title> |
| 221 |
|
|
| 222 |
|
<para>CVS is a convenient tool to keep up-to-date a personal copy of the |
| 223 |
|
MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html"> |
| 224 |
|
using CVS </ulink>). The same tool is used by developers to |
| 225 |
|
incorporate any change into the repository. However, this later |
| 226 |
|
function requires specific settings, as detailed here after:</para> |
| 227 |
|
<orderedlist> |
| 228 |
|
<listitem> |
| 229 |
|
<para> You will need an account (loggin access) to the server |
| 230 |
|
"mitgcm.org" with the proper group setting (e.g., |
| 231 |
|
group "gcmctrb" to add/modify code into MITgcm_contrib). |
| 232 |
|
This kind of account is granted only upon well motivated request. |
| 233 |
|
The access to the server mitgcm.org is through ssh-key authorization |
| 234 |
|
which will need to be set properly on both side (on your local machine |
| 235 |
|
and on your server account). You need to be able to |
| 236 |
|
to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename> |
| 237 |
|
in case of different user-name on both sides) to proceed further.</para> |
| 238 |
|
</listitem> |
| 239 |
|
|
| 240 |
|
<listitem> |
| 241 |
|
<para> You need to register to the |
| 242 |
|
<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs"> |
| 243 |
|
mitgcm-cvs </ulink> mailing list. |
| 244 |
|
This ensures that other developers will receive email notification |
| 245 |
|
when you make changes; you will also receive as well such email |
| 246 |
|
when others make changes to the repository. |
| 247 |
|
</para> |
| 248 |
|
</listitem> |
| 249 |
|
|
| 250 |
|
<listitem> |
| 251 |
|
<para> It is highly recommended that you register also to the |
| 252 |
|
<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel"> |
| 253 |
|
mitgcm-devel </ulink> mailing list (expect a short delay for |
| 254 |
|
this request to be processed). |
| 255 |
|
This list is intended for developer discussions. |
| 256 |
|
</para> |
| 257 |
|
</listitem> |
| 258 |
|
|
| 259 |
|
<listitem> |
| 260 |
|
<para> The standard anonymous mode (using "cvsanon", as mentionned |
| 261 |
|
<ulink url="http://mitgcm.org/public/source_code.html"> |
| 262 |
|
here </ulink>) does not allow check-in ("cvs commit") permission. |
| 263 |
|
Instead, you will need to set our CVS environment as follow:</para> |
| 264 |
|
<screen> |
| 265 |
|
$ export CVS_RSH=ssh |
| 266 |
|
$ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack' |
| 267 |
|
</screen> |
| 268 |
|
<para> After downloading a directory, e.g.: <filename>myCopy</filename>, |
| 269 |
|
from the CVS repository (e.g., |
| 270 |
|
<filename>MITgcm_contrib/thisPart</filename>) using the command:</para> |
| 271 |
|
<screen> |
| 272 |
|
$ cvs co -P -d myCopy MITgcm_contrib/thisPart |
| 273 |
|
</screen> |
| 274 |
|
<para> the type of CVS environment which has been used |
| 275 |
|
is stored in the file <filename>myCopy/CVS/Root</filename> |
| 276 |
|
and makes it difficult to re-use, for cvs-commit purpose, |
| 277 |
|
a cvs local copy (<filename>myCopy</filename>) which was obtained |
| 278 |
|
using the CVS anonymous mode.</para> |
| 279 |
|
</listitem> |
| 280 |
|
|
| 281 |
|
<listitem> |
| 282 |
|
<para> At this stage, you should be able to send your modified source |
| 283 |
|
file (e.g., <filename>src_file</filename>) from your local copy directory |
| 284 |
|
(<filename>myCopy</filename>) to the CVS repository |
| 285 |
|
(<filename>MITgcm_contrib/thisPart</filename>) using the command |
| 286 |
|
"cvs commit":</para> |
| 287 |
|
<screen> |
| 288 |
|
$ cd myCopy |
| 289 |
|
$ cvs -n update (optional; check if new changes have been made) |
| 290 |
|
$ cvs diff src_file (optional; list your changes) |
| 291 |
|
$ cvs commit src_file |
| 292 |
|
</screen> |
| 293 |
|
<para> It is essential that you provide a short description of the |
| 294 |
|
changes you made to <filename>src_file</filename> as you check-in |
| 295 |
|
this file (the "cvs commit" command automatically opens your standard |
| 296 |
|
editor for this purpose).</para> |
| 297 |
|
</listitem> |
| 298 |
|
|
| 299 |
|
</orderedlist> |
| 300 |
|
|
| 301 |
</sect2> |
</sect2> |
| 302 |
|
|
| 303 |
<sect2> |
<sect2> |
| 304 |
<title>Tagging</title> |
<title>Main code development</title> |
| 305 |
|
<para>(formerly named "Tagging" ; this section needs an update)</para> |
| 306 |
|
|
| 307 |
<para>The intent of tagging is to create "known-good" checkpoints that |
<para>The intent of tagging is to create "known-good" checkpoints that |
| 308 |
developers can use as references. Traditionally, MITgcm tagging has |
developers can use as references. Traditionally, MITgcm tagging has |
| 379 |
</sect1> |
</sect1> |
| 380 |
|
|
| 381 |
|
|
|
<sect1 id="documentation"> |
|
|
<title>Editing the Documentation</title> |
|
|
|
|
|
<sect2 id="documentation_getting"> |
|
|
<title>Getting the Docs and Code</title> |
|
|
|
|
|
<para>The first step towards editing the documentation is to checkout a |
|
|
copy of code, docs, and build scripts from the CVS server using:</para> |
|
|
|
|
|
<screen> |
|
|
$ export CVS_RSH=ssh |
|
|
$ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack' |
|
|
$ mkdir scratch |
|
|
$ cvs co -P MITgcm manual mitgcm.org |
|
|
</screen> |
|
|
|
|
|
<para>These commands extract the necessary information from the CVS server |
|
|
and create a temporary (called <filename>scratch</filename>) directory for |
|
|
the storage of the HTML and other files that will be created. Please note |
|
|
that you must either create <filename>scratch</filename> as shown or edit |
|
|
the various <filename>Makefile</filename>s and scripts used to create the |
|
|
documentation.</para> |
|
|
</sect2> |
|
|
|
|
|
<sect2> |
|
|
<title>Editing the Documentation</title> |
|
|
|
|
|
<para>The documentation is contained in the <filename>manual</filename> |
|
|
directory in a raw LaTeX format. The main document is |
|
|
<filename>manual.tex</filename> and it uses <command>\input{}</command>s |
|
|
to include the chapters and subsections.</para> |
|
|
|
|
|
<para>Since the same LaTeX source is used to produce PostScript, PDF, and |
|
|
HTML output, care should be taken to follow certain conventions. Two of |
|
|
the most important are the usage of the <command>\filelink{}{}</command> |
|
|
and <command>\varlink{}{}</command> commands. Both of these commands have |
|
|
been defined to simplify the connection between the automatically |
|
|
generated ("code browser") HTML and the HTML version of the manual |
|
|
produced by LaTeX2HTML. They each take two arguments (corresponding to |
|
|
the contents of the two sets of curly braces) which are the text that the |
|
|
author wishes to be "wrapped" within the link, and a specially formatted |
|
|
link thats relative to the <filename>MITgcm</filename> directory within |
|
|
the CVS tree.</para> |
|
|
|
|
|
<para>The result is a command that resembles either</para> |
|
|
|
|
|
<orderedlist> |
|
|
<listitem> |
|
|
<para>a reference to a variable or subroutine name such as |
|
|
<command>\varlink{tRef}{tRef}</command>, or </para> |
|
|
</listitem> |
|
|
|
|
|
<listitem> |
|
|
<para>a reference to a file such as |
|
|
<command>\varlink{tRef}{path-to-the-file_name.F}</command> |
|
|
where the absolute path to the file is of the form |
|
|
<filename>/foo/MITgcm/path/to/the/file_name.F</filename></para> |
|
|
<para>(please note how the leading "/foo/MITgcm" |
|
|
component of the path is dropped leaving the path |
|
|
<emphasis>relative</emphasis> to the head of the code |
|
|
directory and each directory separator "/" is turned |
|
|
into a "-")</para> |
|
|
</listitem> |
|
|
</orderedlist> |
|
|
|
|
|
|
|
|
|
|
|
</sect2> |
|
|
|
|
|
<sect2> |
|
|
<title>Building the Documentation</title> |
|
|
|
|
|
<para>Given the directory structure of <xref |
|
|
linkend="documentation_getting">, the entire documentation for the web |
|
|
site can be built using:</para> |
|
|
|
|
|
<screen> |
|
|
$ cd mitgcm.org/devel/buildweb |
|
|
$ make All |
|
|
</screen> |
|
|
|
|
|
<para>Which builds the PDF from the LaTeX source, creates the HTML output |
|
|
from the LaTeX source, parses the FORTRAN code base to produce a |
|
|
hyperlinked HTML version of the source, and then determines the |
|
|
cross-linking between the various HTML components.</para> |
|
|
|
|
|
<para>If there are no errors, the result of the build process (which can |
|
|
take 30+ minutes on a P4/2.5Ghz) will be contained within a single |
|
|
directory called <filename>scratch/dev_docs</filename>. This is a freshly |
|
|
built 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> |
|
|
|
|
|
<screen> |
|
|
$ mv scratch/dev_docs /u/u0/httpd/html |
|
|
</screen> |
|
|
|
|
|
<para>and the update is complete.</para> |
|
|
|
|
|
</sect2> |
|
|
|
|
|
</sect1> |
|
|
|
|
| 382 |
<sect1 id="coding"> |
<sect1 id="coding"> |
| 383 |
<title>Coding for MITgcm</title> |
<title>Coding for MITgcm</title> |
| 384 |
|
|
| 826 |
the generic fluid dynamical engine.</para> |
the generic fluid dynamical engine.</para> |
| 827 |
|
|
| 828 |
<para>The MITgcmUV packaging structure is described below using generic |
<para>The MITgcmUV packaging structure is described below using generic |
| 829 |
package names ${pkg}. A concrete examples of a package is the code for |
package names ${pkg}. A concrete examples of a package is the code for |
| 830 |
implementing GM/Redi mixing. This code uses the package name</para> |
implementing GM/Redi mixing. This code uses the package name</para> |
| 831 |
|
|
| 832 |
</sect2> |
</sect2> |
| 1091 |
</sect1> |
</sect1> |
| 1092 |
|
|
| 1093 |
|
|
| 1094 |
|
<sect1 id="documentation"> |
| 1095 |
|
<title>Editing the Documentation</title> |
| 1096 |
|
|
| 1097 |
|
<sect2 id="documentation_getting"> |
| 1098 |
|
<title>Getting the Docs and Code</title> |
| 1099 |
|
|
| 1100 |
|
<para>The first step towards editing the documentation is to checkout a |
| 1101 |
|
copy of code, docs, and build scripts from the CVS server using:</para> |
| 1102 |
|
|
| 1103 |
|
<screen> |
| 1104 |
|
$ export CVS_RSH=ssh |
| 1105 |
|
$ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack' |
| 1106 |
|
$ mkdir scratch |
| 1107 |
|
$ cvs co -P MITgcm manual mitgcm.org |
| 1108 |
|
</screen> |
| 1109 |
|
|
| 1110 |
|
<para>These commands extract the necessary information from the CVS server |
| 1111 |
|
and create a temporary (called <filename>scratch</filename>) directory for |
| 1112 |
|
the storage of the HTML and other files that will be created. Please note |
| 1113 |
|
that you must either create <filename>scratch</filename> as shown or edit |
| 1114 |
|
the various <filename>Makefile</filename>s and scripts used to create the |
| 1115 |
|
documentation.</para> |
| 1116 |
|
</sect2> |
| 1117 |
|
|
| 1118 |
|
<sect2> |
| 1119 |
|
<title>Editing the Documentation</title> |
| 1120 |
|
|
| 1121 |
|
<para>The documentation is contained in the <filename>manual</filename> |
| 1122 |
|
directory in a raw LaTeX format. The main document is |
| 1123 |
|
<filename>manual.tex</filename> and it uses <command>\input{}</command>s |
| 1124 |
|
to include the chapters and subsections.</para> |
| 1125 |
|
|
| 1126 |
|
<para>Since the same LaTeX source is used to produce PostScript, PDF, and |
| 1127 |
|
HTML output, care should be taken to follow certain conventions. Two of |
| 1128 |
|
the most important are the usage of the <command>\filelink{}{}</command> |
| 1129 |
|
and <command>\varlink{}{}</command> commands. Both of these commands have |
| 1130 |
|
been defined to simplify the connection between the automatically |
| 1131 |
|
generated ("code browser") HTML and the HTML version of the manual |
| 1132 |
|
produced by LaTeX2HTML. They each take two arguments (corresponding to |
| 1133 |
|
the contents of the two sets of curly braces) which are the text that the |
| 1134 |
|
author wishes to be "wrapped" within the link, and a specially formatted |
| 1135 |
|
link thats relative to the <filename>MITgcm</filename> directory within |
| 1136 |
|
the CVS tree.</para> |
| 1137 |
|
|
| 1138 |
|
<para>The result is a command that resembles either</para> |
| 1139 |
|
|
| 1140 |
|
<orderedlist> |
| 1141 |
|
<listitem> |
| 1142 |
|
<para>a reference to a variable or subroutine name such as |
| 1143 |
|
<command>\varlink{tRef}{tRef}</command>, or </para> |
| 1144 |
|
</listitem> |
| 1145 |
|
|
| 1146 |
|
<listitem> |
| 1147 |
|
<para>a reference to a file such as |
| 1148 |
|
<command>\varlink{tRef}{path-to-the-file_name.F}</command> |
| 1149 |
|
where the absolute path to the file is of the form |
| 1150 |
|
<filename>/foo/MITgcm/path/to/the/file_name.F</filename></para> |
| 1151 |
|
<para>(please note how the leading "/foo/MITgcm" |
| 1152 |
|
component of the path is dropped leaving the path |
| 1153 |
|
<emphasis>relative</emphasis> to the head of the code |
| 1154 |
|
directory and each directory separator "/" is turned |
| 1155 |
|
into a "-")</para> |
| 1156 |
|
</listitem> |
| 1157 |
|
</orderedlist> |
| 1158 |
|
|
| 1159 |
|
|
| 1160 |
|
|
| 1161 |
|
</sect2> |
| 1162 |
|
|
| 1163 |
|
<sect2> |
| 1164 |
|
<title>Building the Documentation</title> |
| 1165 |
|
|
| 1166 |
|
<para>Given the directory structure of <xref |
| 1167 |
|
linkend="documentation_getting">, the entire documentation for the web |
| 1168 |
|
site can be built using:</para> |
| 1169 |
|
|
| 1170 |
|
<screen> |
| 1171 |
|
$ cd mitgcm.org/devel/buildweb |
| 1172 |
|
$ make All |
| 1173 |
|
</screen> |
| 1174 |
|
|
| 1175 |
|
<para>Which builds the PDF from the LaTeX source, creates the HTML output |
| 1176 |
|
from the LaTeX source, parses the FORTRAN code base to produce a |
| 1177 |
|
hyperlinked HTML version of the source, and then determines the |
| 1178 |
|
cross-linking between the various HTML components.</para> |
| 1179 |
|
|
| 1180 |
|
<para>If there are no errors, the result of the build process (which can |
| 1181 |
|
take 30+ minutes on a P4/2.5Ghz) will be contained within a single |
| 1182 |
|
directory called <filename>scratch/dev_docs</filename>. This is a freshly |
| 1183 |
|
built version of the entire on-line users manual. If you have the correct |
| 1184 |
|
permissions, it can be directly copied to the web server area:</para> |
| 1185 |
|
|
| 1186 |
|
<screen> |
| 1187 |
|
$ mv scratch/dev_docs /u/u0/httpd/html |
| 1188 |
|
</screen> |
| 1189 |
|
|
| 1190 |
|
<para>and the update is complete.</para> |
| 1191 |
|
|
| 1192 |
|
</sect2> |
| 1193 |
|
|
| 1194 |
|
</sect1> |
| 1195 |
|
|
| 1196 |
</article> |
</article> |
| 1197 |
|
|
| 1198 |
|
|
Parent Directory
| 
Revision Log
| 
Revision Graph
| 
Patch