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 to two |
206 |
branches or "lines" under which development proceeds. These two lines are |
branches or "lines" under which development proceeds. These two lines are |
207 |
referred to as the "MAIN" and "ecco" versions of the code. While not |
referred to as the "MAIN" and "ecco" versions of the code. While not |
219 |
</sect2> |
</sect2> |
220 |
|
|
221 |
<sect2> |
<sect2> |
222 |
<title>Tagging</title> |
<title> Developer settings </title> |
223 |
|
|
224 |
|
<para>CVS is a convenient tool to keep up-to-date a personal copy of the |
225 |
|
MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html"> |
226 |
|
using CVS </ulink>). The same tool is used by developers to |
227 |
|
incorporate any change into the repository. However, this later |
228 |
|
function requires specific settings, as detailed here after:</para> |
229 |
|
<orderedlist> |
230 |
|
<listitem> |
231 |
|
<para> You will need an account (loggin access) to the server |
232 |
|
"mitgcm.org" with the proper group setting (e.g., |
233 |
|
group "gcmctrb" to add/modify code into MITgcm_contrib). |
234 |
|
This kind of account is granted only upon well motivated request. |
235 |
|
The access to the server mitgcm.org is through ssh-key authorization |
236 |
|
which will need to be set properly on both side (on your local machine |
237 |
|
and on your server account). You need to be able to |
238 |
|
to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename> |
239 |
|
in case of different user-name on both sides) to proceed further.</para> |
240 |
|
</listitem> |
241 |
|
|
242 |
|
<listitem> |
243 |
|
<para> You need to register to the |
244 |
|
<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs"> |
245 |
|
mitgcm-cvs </ulink> mailing list. |
246 |
|
This ensures that other developers will receive email notification |
247 |
|
when you make changes; you will also receive as well such email |
248 |
|
when others make changes to the repository. |
249 |
|
</para> |
250 |
|
</listitem> |
251 |
|
|
252 |
|
<listitem> |
253 |
|
<para> It is highly recommended that you register also to the |
254 |
|
<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel"> |
255 |
|
mitgcm-devel </ulink> mailing list (expect a short delay for |
256 |
|
this request to be processed). |
257 |
|
This list is intended for developer discussions. |
258 |
|
</para> |
259 |
|
</listitem> |
260 |
|
|
261 |
|
<listitem> |
262 |
|
<para> The standard anonymous mode (using "cvsanon", as mentionned |
263 |
|
<ulink url="http://mitgcm.org/public/source_code.html"> |
264 |
|
here </ulink>) does not allow check-in ("cvs commit") permission. |
265 |
|
Instead, you will need to set our CVS environment as follow:</para> |
266 |
|
<screen> |
267 |
|
$ export CVS_RSH=ssh |
268 |
|
$ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack' |
269 |
|
</screen> |
270 |
|
<para> After downloading a directory, e.g.: <filename>myCopy</filename>, |
271 |
|
from the CVS repository (e.g., |
272 |
|
<filename>MITgcm_contrib/thisPart</filename>) using the command:</para> |
273 |
|
<screen> |
274 |
|
$ cvs co -P -d myCopy MITgcm_contrib/thisPart |
275 |
|
</screen> |
276 |
|
<para> the type of CVS environment which has been used |
277 |
|
is stored in the file <filename>myCopy/CVS/Root</filename> |
278 |
|
and makes it difficult to re-use, for cvs-commit purpose, |
279 |
|
a cvs local copy (<filename>myCopy</filename>) which was obtained |
280 |
|
using the CVS anonymous mode.</para> |
281 |
|
</listitem> |
282 |
|
|
283 |
|
<listitem> |
284 |
|
<para> At this stage, you should be able to send your modified source |
285 |
|
file (e.g., <filename>src_file</filename>) from your local copy directory |
286 |
|
(<filename>myCopy</filename>) to the CVS repository |
287 |
|
(<filename>MITgcm_contrib/thisPart</filename>) using the command |
288 |
|
"cvs commit":</para> |
289 |
|
<screen> |
290 |
|
$ cd myCopy |
291 |
|
$ cvs -n update (optional; check if new changes have been made) |
292 |
|
$ cvs diff src_file (optional; list your changes) |
293 |
|
$ cvs commit src_file |
294 |
|
</screen> |
295 |
|
<para> It is essential that you provide a short description of the |
296 |
|
changes you made to <filename>src_file</filename> as you check-in |
297 |
|
this file (the "cvs commit" command automatically opens your standard |
298 |
|
editor for this purpose).</para> |
299 |
|
</listitem> |
300 |
|
|
301 |
|
</orderedlist> |
302 |
|
|
303 |
|
</sect2> |
304 |
|
|
305 |
|
<sect2> |
306 |
|
<title>Main code development</title> |
307 |
|
<para>(formerly named "Tagging" ; this section needs an update)</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 |
381 |
</sect1> |
</sect1> |
382 |
|
|
383 |
|
|
|
<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> |
|
|
|
|
384 |
<sect1 id="coding"> |
<sect1 id="coding"> |
385 |
<title>Coding for MITgcm</title> |
<title>Coding for MITgcm</title> |
386 |
|
|
828 |
the generic fluid dynamical engine.</para> |
the generic fluid dynamical engine.</para> |
829 |
|
|
830 |
<para>The MITgcmUV packaging structure is described below using generic |
<para>The MITgcmUV packaging structure is described below using generic |
831 |
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 |
832 |
implementing GM/Redi mixing. This code uses the package name</para> |
implementing GM/Redi mixing. This code uses the package name</para> |
833 |
|
|
834 |
</sect2> |
</sect2> |
1093 |
</sect1> |
</sect1> |
1094 |
|
|
1095 |
|
|
1096 |
|
<sect1 id="documentation"> |
1097 |
|
<title>Editing the Documentation</title> |
1098 |
|
|
1099 |
|
<sect2 id="documentation_getting"> |
1100 |
|
<title>Getting the Docs and Code</title> |
1101 |
|
|
1102 |
|
<para>The first step towards editing the documentation is to checkout a |
1103 |
|
copy of code, docs, and build scripts from the CVS server using:</para> |
1104 |
|
|
1105 |
|
<screen> |
1106 |
|
$ export CVS_RSH=ssh |
1107 |
|
$ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack' |
1108 |
|
$ mkdir scratch |
1109 |
|
$ cvs co -P MITgcm manual mitgcm.org |
1110 |
|
</screen> |
1111 |
|
|
1112 |
|
<para>These commands extract the necessary information from the CVS server |
1113 |
|
and create a temporary (called <filename>scratch</filename>) directory for |
1114 |
|
the storage of the HTML and other files that will be created. Please note |
1115 |
|
that you must either create <filename>scratch</filename> as shown or edit |
1116 |
|
the various <filename>Makefile</filename>s and scripts used to create the |
1117 |
|
documentation.</para> |
1118 |
|
</sect2> |
1119 |
|
|
1120 |
|
<sect2> |
1121 |
|
<title>Editing the Documentation</title> |
1122 |
|
|
1123 |
|
<para>The documentation is contained in the <filename>manual</filename> |
1124 |
|
directory in a raw LaTeX format. The main document is |
1125 |
|
<filename>manual.tex</filename> and it uses <command>\input{}</command>s |
1126 |
|
to include the chapters and subsections.</para> |
1127 |
|
|
1128 |
|
<para>Since the same LaTeX source is used to produce PostScript, PDF, and |
1129 |
|
HTML output, care should be taken to follow certain conventions. Two of |
1130 |
|
the most important are the usage of the <command>\filelink{}{}</command> |
1131 |
|
and <command>\varlink{}{}</command> commands. Both of these commands have |
1132 |
|
been defined to simplify the connection between the automatically |
1133 |
|
generated ("code browser") HTML and the HTML version of the manual |
1134 |
|
produced by LaTeX2HTML. They each take two arguments (corresponding to |
1135 |
|
the contents of the two sets of curly braces) which are the text that the |
1136 |
|
author wishes to be "wrapped" within the link, and a specially formatted |
1137 |
|
link thats relative to the <filename>MITgcm</filename> directory within |
1138 |
|
the CVS tree.</para> |
1139 |
|
|
1140 |
|
<para>The result is a command that resembles either</para> |
1141 |
|
|
1142 |
|
<orderedlist> |
1143 |
|
<listitem> |
1144 |
|
<para>a reference to a variable or subroutine name such as |
1145 |
|
<command>\varlink{tRef}{tRef}</command>, or </para> |
1146 |
|
</listitem> |
1147 |
|
|
1148 |
|
<listitem> |
1149 |
|
<para>a reference to a file such as |
1150 |
|
<command>\varlink{tRef}{path-to-the-file_name.F}</command> |
1151 |
|
where the absolute path to the file is of the form |
1152 |
|
<filename>/foo/MITgcm/path/to/the/file_name.F</filename></para> |
1153 |
|
<para>(please note how the leading "/foo/MITgcm" |
1154 |
|
component of the path is dropped leaving the path |
1155 |
|
<emphasis>relative</emphasis> to the head of the code |
1156 |
|
directory and each directory separator "/" is turned |
1157 |
|
into a "-")</para> |
1158 |
|
</listitem> |
1159 |
|
</orderedlist> |
1160 |
|
|
1161 |
|
|
1162 |
|
|
1163 |
|
</sect2> |
1164 |
|
|
1165 |
|
<sect2> |
1166 |
|
<title>Building the Documentation</title> |
1167 |
|
|
1168 |
|
<para>Given the directory structure of <xref |
1169 |
|
linkend="documentation_getting">, the entire documentation for the web |
1170 |
|
site can be built using:</para> |
1171 |
|
|
1172 |
|
<screen> |
1173 |
|
$ cd mitgcm.org/devel/buildweb |
1174 |
|
$ make All |
1175 |
|
</screen> |
1176 |
|
|
1177 |
|
<para>Which builds the PDF from the LaTeX source, creates the HTML output |
1178 |
|
from the LaTeX source, parses the FORTRAN code base to produce a |
1179 |
|
hyperlinked HTML version of the source, and then determines the |
1180 |
|
cross-linking between the various HTML components.</para> |
1181 |
|
|
1182 |
|
<para>If there are no errors, the result of the build process (which can |
1183 |
|
take 30+ minutes on a P4/2.5Ghz) will be contained within a single |
1184 |
|
directory called <filename>scratch/dev_docs</filename>. This is a freshly |
1185 |
|
built version of the entire on-line users manual. If you have the correct |
1186 |
|
permissions, it can be directly copied to the web server area:</para> |
1187 |
|
|
1188 |
|
<screen> |
1189 |
|
$ mv scratch/dev_docs /u/u0/httpd/html |
1190 |
|
</screen> |
1191 |
|
|
1192 |
|
<para>and the update is complete.</para> |
1193 |
|
|
1194 |
|
</sect2> |
1195 |
|
|
1196 |
|
</sect1> |
1197 |
|
|
1198 |
</article> |
</article> |
1199 |
|
|
1200 |
|
|