source: codes/icosagcm/branches/SATURN_DYNAMICO/ICOSAGCM/tools/FCM/doc/user_guide/annex_ext_cfg.html @ 225

Last change on this file since 225 was 225, checked in by ymipsl, 10 years ago
File size: 16.4 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <title>FCM System User Guide Annex: Declarations in FCM extract configuration
6  file</title>
7  <meta name="author" content="FCM development team">
8  <meta name="descriptions" content="User Guide Annex">
9  <meta name="keywords" content="FCM, user guide, annex">
10  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11  <link rel="stylesheet" type="text/css" href="style.css">
12</head>
13
14<body>
15  <address>
16    <a href="index.html">FCM System User Guide</a> &gt; Annex: Declarations in
17    FCM extract configuration file
18  </address>
19
20  <h1>Annex:<br>
21  Declarations in FCM extract configuration file</h1>
22
23  <p>The following is a list of supported declarations for the configuration
24  file used by the FCM extract system. Unless otherwise stated, the fields in
25  all declaration labels are not case sensitive.</p>
26
27  <table class="pad" summary="Declarations in extract configuration file"
28  width="100%" border="1">
29    <tr>
30      <th>Label</th>
31
32      <th colspan="2">Content</th>
33    </tr>
34
35    <tr>
36      <th rowspan="2">CFG::TYPE</th>
37
38      <th>Description</th>
39
40      <td>The configuration file type, the value should always be "ext" for an
41      extract configuration file. This declaration is compulsory for all
42      extract configuration files.</td>
43    </tr>
44
45    <tr>
46      <th>Example</th>
47
48      <td>
49        <pre>
50cfg::type  ext
51</pre>
52      </td>
53    </tr>
54
55    <tr>
56      <th rowspan="2">CFG::VERSION</th>
57
58      <th>Description</th>
59
60      <td>The file format version, currently "1.0" - a version is included so
61      that we shall be able to read the configuration file correctly should we
62      decide to change its format in the future.</td>
63    </tr>
64
65    <tr>
66      <th>Example</th>
67
68      <td>
69        <pre>
70cfg::version  1.0
71</pre>
72      </td>
73    </tr>
74
75    <tr>
76      <th>Label</th>
77
78      <th colspan="2">Content</th>
79    </tr>
80
81    <tr>
82      <th rowspan="2">DEST::ROOTDIR</th>
83
84      <th>Description</th>
85
86      <td>The "root" path of the destination of this extraction. This
87      declaration is compulsory for all extract configuration files.</td>
88    </tr>
89
90    <tr>
91      <th>Example</th>
92
93      <td>
94        <pre>
95dest::rootdir  $HOME/project/my_project
96</pre>
97      </td>
98    </tr>
99
100    <tr>
101      <th rowspan="2">RDEST::MACHINE</th>
102
103      <th>Description</th>
104
105      <td>The destination machine for this extraction. If set, the extraction
106      will be mirrored to a location on this machine.</td>
107    </tr>
108
109    <tr>
110      <th>Example</th>
111
112      <td>
113        <pre>
114rdest::machine  tx01
115</pre>
116      </td>
117    </tr>
118
119    <tr>
120      <th rowspan="2">RDEST::LOGNAME</th>
121
122      <th>Description</th>
123
124      <td>The login name of the user on the remote destination machine. If not
125      specified, the current login name of the user on the local platform is
126      assumed.</td>
127    </tr>
128
129    <tr>
130      <th>Example</th>
131
132      <td>
133        <pre>
134rdest::logname  frva
135</pre>
136      </td>
137    </tr>
138
139    <tr>
140      <th rowspan="2">RDEST::ROOTDIR</th>
141
142      <th>Description</th>
143
144      <td>The "root" path of the remote destination of this extraction. This
145      declaration is compulsory if this extraction requires mirroring to a
146      remote machine.</td>
147    </tr>
148
149    <tr>
150      <th>Example</th>
151
152      <td>
153        <pre>
154rdest::rootdir  /home/nwp/da/frva/project/my_project
155</pre>
156      </td>
157    </tr>
158
159    <tr>
160      <th>Label</th>
161
162      <th colspan="2">Content</th>
163    </tr>
164
165    <tr>
166      <th rowspan="2">REPOS::&lt;pck&gt;::&lt;branch&gt;</th>
167
168      <th>Description</th>
169
170      <td>This declares a URL or a local file system path for the container
171      "repository" of a branch named &lt;branch&gt; in a package named
172      &lt;pck&gt;. The package name &lt;pck&gt; must be the name of a
173      top-level package (i.e. it must not contain the double colon "::"
174      delimiter). The name &lt;branch&gt; is used internally within the
175      extract system, and so is independent of the branch name of the code
176      management system. However, it is usually desirable to use the same name
177      of the actual branch in the code management system. For declaration of a
178      local file system path, the convention is to name the branch "user".
179      Please note that both &lt;pck&gt; and &lt;branch&gt; fields are case
180      sensitive. The declared URL must be a valid Subversion URL or a valid
181      FCM repository keyword.</td>
182    </tr>
183
184    <tr>
185      <th>Example</th>
186
187      <td>
188        <pre>
189repos::var::trunk        fcm:var_tr
190repos::var::r4790_foobar fcm:var_br/frsn/r4790_foobar
191repos::var::user         $HOME/var
192</pre>
193      </td>
194    </tr>
195
196    <tr>
197      <th rowspan="2">VERSION::&lt;pck&gt;::&lt;branch&gt;</th>
198
199      <th>Description</th>
200
201      <td>The revision to be used for the URL of &lt;branch&gt; in the package
202      &lt;pck&gt;. If not specified, the revision defaults to "HEAD". Please
203      note that if the delcared "repository" is in the local file system, this
204      declaration must not be used. The value of the declaration can be a FCM
205      revision keyword or any revision argument acceptable by Subversion. You
206      can use a valid revision number, a date between a pair of curly brackets
207      (e.g. {"2005-05-01 12:00"}) or the keyword "HEAD". However, please do
208      not use the keywords "BASE", "COMMITTED" or "PREV" as these are reserved
209      for working copy only. Again, please note that both &lt;pck&gt; and
210      &lt;branch&gt; fields are case sensitive. </td>
211    </tr>
212
213    <tr>
214      <th>Example</th>
215
216      <td>
217        <pre>
218# Declare the revision with the FCM revision keyword "vn22.0"
219version::var::trunk        vn22.0
220# Declare the revision with a {date}
221version::var::r4790_foobar {2006-01-01}
222</pre>
223      </td>
224    </tr>
225
226    <tr>
227      <th rowspan="2">SRC::&lt;pcks&gt;::&lt;branch&gt;</th>
228
229      <th>Description</th>
230
231      <td>This declares a source directory for the sub-package &lt;pcks&gt;
232      of &lt;branch&gt;. If the repository is declared as a URL, the source
233      directory must be quoted as a relative path to the URL. If the
234      repository is declared as a path in the local file system, the source
235      directory can be declared as either a relative path to the "repository"
236      or a full path. If the source directory is a relative path and
237      &lt;pcks&gt; is a top-level package, the full name of the sub-package
238      will be determined automatically using the directory names of the
239      relative path as the name of the sub-packages. If the source directory
240      is a full path, the full sub-package name must be specified. The name of
241      the sub-package determines the destination path of the source directory
242      in the extraction.</td>
243    </tr>
244
245    <tr>
246      <th>Example</th>
247
248      <td>
249        <pre>
250src::var::trunk                   code/VarMod_PF
251src::var::code::VarMod_PF::user   $HOME/var/code/VarMod_PF
252</pre>
253      </td>
254    </tr>
255
256    <tr>
257      <th rowspan="2">EXPSRC::&lt;pcks&gt;::&lt;branch&gt;</th>
258
259      <th>Description</th>
260
261      <td>This declares an expandable source directory for the sub-package
262      &lt;pcks&gt; of &lt;branch&gt;. This declaration is essentially the
263      same as the SRC declaration, except that the system will attempt to
264      search recursively for sub-directories within the declared source
265      directory.</td>
266    </tr>
267
268    <tr>
269      <th>Example</th>
270
271      <td>
272        <pre>
273expsrc::var::trunk code
274expsrc::var::user  code
275</pre>
276      </td>
277    </tr>
278
279    <tr>
280      <th>Label</th>
281
282      <th colspan="2">Content</th>
283    </tr>
284
285    <tr>
286      <th rowspan="2">BLD::&lt;fields&gt;</th>
287
288      <th>Description</th>
289
290      <td>Declare a build configuration file declaration. The label
291      &lt;fields&gt; is the label of the declaration. On a successful
292      extraction, &lt;fields&gt; will be added to the build configuration
293      file. Please note that some of the &lt;fields&gt; may be case
294      sensitive.</td>
295    </tr>
296
297    <tr>
298      <th>Example</th>
299
300      <td>
301        <pre>
302bld::name     var_stable_22.0
303bld::target   VarScr_AnalysePF
304bld::tool::fc sxmpif90
305bld::tool::cc sxmpic++
306# ... and so on ...
307</pre>
308      </td>
309    </tr>
310
311    <tr>
312      <th rowspan="2">USE</th>
313
314      <th>Description</th>
315
316      <td>The declares the location of a previous successful extraction, which
317      the current extraction will base on. If the previous extraction is also
318      a build, the subsequent invocation of the build system on the current
319      extraction will automatically trigger an inherited incremental build
320      based on that build.</td>
321    </tr>
322
323    <tr>
324      <th>Example</th>
325
326      <td>
327        <pre>
328use  ~frva/var_stable_22.0
329# ... and then the settings for your current extraction ...
330</pre>
331      </td>
332    </tr>
333
334    <tr>
335      <th rowspan="2">INC</th>
336
337      <th>Description</th>
338
339      <td>This declares the name of a file containing extract configuration.
340      The lines in the declared file will be included inline to the current
341      extract configuration file.</td>
342    </tr>
343
344    <tr>
345      <th>Example</th>
346
347      <td>
348        <pre>
349inc  ~frva/var_stable_22.0/cfg/ext.cfg
350# ... and then your changes ...
351</pre>
352      </td>
353    </tr>
354
355    <tr>
356      <th rowspan="2">OVERRIDE</th>
357
358      <th>Description</th>
359
360      <td>If a file is modified by two different branches, this flag can be
361      used to specify either to allow the later branch to override (1) the
362      earlier one or to fail (0) the extraction. If not specified, the default
363      is to fail (0).</td>
364    </tr>
365
366    <tr>
367      <th>Example</th>
368
369      <td>
370        <pre>
371override  1
372</pre>
373      </td>
374    </tr>
375
376    <tr>
377      <th rowspan="2">MIRROR</th>
378
379      <th>Description</th>
380
381      <td>The extract system can mirror the extracted source to a remote
382      machine. Currently, it does this using either the <em>rdist</em> or the
383      <em>rsync</em> command. The default is <em>rsync</em>. This declaration
384      can be used to switch to using <em>rdist</em>.</td>
385    </tr>
386
387    <tr>
388      <th>Example</th>
389
390      <td>
391        <pre>
392mirror  rdist
393</pre>
394      </td>
395    </tr>
396
397    <tr>
398      <th rowspan="2">%&lt;name&gt;</th>
399
400      <th>Description</th>
401
402      <td>%&lt;name&gt; declares an internal variable &lt;name&gt; that
403      can later be re-used.</td>
404    </tr>
405
406    <tr>
407      <th>Example</th>
408
409      <td>
410        <pre>
411%my_variable      foo
412src::bar::trunk   %my_variable
413src::egg::trunk   %my_variable
414src::ham::trunk   %my_variable
415</pre>
416      </td>
417    </tr>
418
419    <tr>
420      <th>Label</th>
421
422      <th colspan="2">Content</th>
423    </tr>
424  </table>
425
426  <p class="gray">The following declarations are for reference only. They
427  should not be used in normal operations of the FCM extract system:</p>
428
429  <table class="pad" summary="Unused declarations in extract configuration file"
430  width="100%" border="1">
431    <tr class="gray">
432      <th>Label</th>
433
434      <th colspan="2">Content</th>
435    </tr>
436
437    <tr class="gray">
438      <th rowspan="2">DEST::SRCDIR</th>
439
440      <th>Description</th>
441
442      <td>This declaration is optional and is not normally required. It is the
443      "source" path of the desintation of this extraction. Source directories
444      will be extracted to this directory. The default is to extract source
445      directories to the "src/" sub-directory under the root path of the
446      destination.</td>
447    </tr>
448
449    <tr class="gray">
450      <th>Example</th>
451
452      <td>
453        <pre>
454dest::srcdir  $HOME/project/my_project/src
455</pre>
456      </td>
457    </tr>
458
459    <tr class="gray">
460      <th rowspan="2">DEST::CFGDIR</th>
461
462      <th>Description</th>
463
464      <td>This declaration is optional and is not normally required. It is the
465      "configuration" path of the destination of this extraction.
466      Configuration files such as the expanded extraction configuration file
467      and the build configuration file will be written in this location. The
468      default is to send the configuration files to the "cfg/" sub-directory
469      under the root path of the destination.</td>
470    </tr>
471
472    <tr class="gray">
473      <th>Example</th>
474
475      <td>
476        <pre>
477dest::cfgdir  $HOME/project/my_project/cfg
478</pre>
479      </td>
480    </tr>
481
482    <tr class="gray">
483      <th rowspan="2">DEST::CACHEDIR</th>
484
485      <th>Description</th>
486
487      <td>This declaration is optional and is not normally required. It is the
488      cache directory used by this extraction. Source directories and other
489      configuration files will normally be extracted and written to the cache
490      directory before being copied to the destination. This ensures fast
491      subsequent incremental extractions. It also reduces the load on the
492      repository server. The default is use the ".cache/" sub-directory under
493      the root path of the destination.</td>
494    </tr>
495
496    <tr class="gray">
497      <th>Example</th>
498
499      <td>
500        <pre>
501dest::cachedir  $HOME/project/my_project/.cache
502</pre>
503      </td>
504    </tr>
505
506    <tr class="gray">
507      <th rowspan="2">DEST::BLD_CFG</th>
508
509      <th>Description</th>
510
511      <td>This declaration is optional and is not normally required. It is the
512      destination path of the build configuration file. By default, this file
513      will be named "bld.cfg" and will be placed under the configuration
514      directory, i.e. "cfg/bld.cfg" under the root path of the
515      destination.</td>
516    </tr>
517
518    <tr class="gray">
519      <th>Example</th>
520
521      <td>
522        <pre>
523dest::bld_cfg  $HOME/project/my_project/cfg/bld.cfg
524</pre>
525      </td>
526    </tr>
527
528    <tr class="gray">
529      <th rowspan="2">DEST::EXT_CFG</th>
530
531      <th>Description</th>
532
533      <td>This declaration is optional and is not normally required. It is the
534      destination path of the output expanded extract configuration file. By
535      default, this file will be named "ext.cfg" and will be placed under the
536      configuration directory, i.e. "cfg/ext.cfg" under the root path of the
537      destination.</td>
538    </tr>
539
540    <tr class="gray">
541      <th>Example</th>
542
543      <td>
544        <pre>
545dest::ext_cfg  $HOME/project/my_project/cfg/ext.cfg
546</pre>
547      </td>
548    </tr>
549
550    <tr class="gray">
551      <th rowspan="2">RDEST::SRCDIR</th>
552
553      <th>Description</th>
554
555      <td>This declaration is optional and is not normally required. It is the
556      "source" path of the remote desintation of this extraction. Source
557      directories will be mirrored to this directory. The default is to mirror
558      source directories to the "src/" sub-directory under the root path of the
559      remote destination.</td>
560    </tr>
561
562    <tr class="gray">
563      <th>Example</th>
564
565      <td>
566        <pre>
567rdest::srcdir  /home/nwp/da/frva/project/my_project/src
568</pre>
569      </td>
570    </tr>
571
572    <tr class="gray">
573      <th rowspan="2">RDEST::CFGDIR</th>
574
575      <th>Description</th>
576
577      <td>This declaration is optional and is not normally required. It is the
578      "configuration" path of the remote destination of this extraction.
579      Configuration files such as the expanded extraction configuration file
580      and the build configuration file are mirrored in this location. The
581      default is to send the configuration files to the "cfg/" sub-directory
582      under the root path of the remote destination.</td>
583    </tr>
584
585    <tr class="gray">
586      <th>Example</th>
587
588      <td>
589        <pre>
590rdest::cfgdir  /home/nwp/da/frva/project/my_project/cfg
591</pre>
592      </td>
593    </tr>
594
595    <tr class="gray">
596      <th rowspan="2">RDEST::BLD_CFG</th>
597
598      <th>Description</th>
599
600      <td>This declaration is optional and is not normally required. It is the
601      remote destination path of the build configuration file. By default, this
602      file will be named "bld.cfg" and will be placed under the configuration
603      directory, i.e. "cfg/bld.cfg" under the root path of the remote
604      destination.</td>
605    </tr>
606
607    <tr class="gray">
608      <th>Example</th>
609
610      <td>
611        <pre>
612rdest::bld_cfg  /home/nwp/da/frva/project/my_project/cfg/bld.cfg
613</pre>
614      </td>
615    </tr>
616
617    <tr class="gray">
618      <th rowspan="2">RDEST::EXT_CFG</th>
619
620      <th>Description</th>
621
622      <td>This declaration is optional and is not normally required. It is the
623      remote destination path of the output expanded extract configuration file.
624      By default, this file will be named "ext.cfg" and will be placed under the
625      configuration directory, i.e. "cfg/ext.cfg" under the root path of the
626      remote destination.</td>
627    </tr>
628
629    <tr class="gray">
630      <th>Example</th>
631
632      <td>
633        <pre>
634rdest::ext_cfg  /home/nwp/da/frva/project/my_project/cfg/ext.cfg
635</pre>
636      </td>
637    </tr>
638  </table>
639
640  <script type="text/javascript" src="maintain.js">
641  </script>
642</body>
643</html>
Note: See TracBrowser for help on using the repository browser.