Ignore:
Timestamp:
Jul 21, 2024, 1:47:00 PM (4 months ago)
Author:
abarral
Message:

Fix r5093: ship new fcm source

File:
1 edited

Legend:

Unmodified
Added
Removed

  • LMDZ6/branches/Amaury_dev/tools/fcm/doc/user_guide/extract.html

    r1578 r5094  
    1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2 
     1<!DOCTYPE html>
    32<html>
    43<head>
    5   <title>FCM System User Guide: The Extract System</title>
    6   <meta name="author" content="FCM development team">
    7   <meta name="descriptions" content="User Guide - The Extract System">
    8   <meta name="keywords" content="FCM, user guide, extract, build">
    9   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    10   <link rel="stylesheet" type="text/css" href="style.css">
     4  <title>FCM: User Guide: Annex: The FCM 1 Extract System</title>
     5  <meta name="author" content="FCM team" />
     6  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     7  <link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
     8  <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
     9  <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
     10  <link href="../etc/fcm.css" rel="stylesheet" media="screen" />
    1111</head>
    12 
    1312<body>
    14   <address>
    15     <a href="index.html">FCM System User Guide</a> &gt; The Extract System
    16   </address>
    17 
    18   <h1>The Extract System</h1>
     13  <div class="navbar navbar-inverse">
     14    <div class="container-fluid">
     15      <div class="navbar-header">
     16        <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
     17      </div>
     18      <div class="collapse navbar-collapse">
     19        <ul class="nav navbar-nav">
     20          <li><a href="../installation/">Installation</a></li>
     21
     22          <li><a class="active" href="#">User Guide</a></li>
     23        </ul>
     24      </div>
     25    </div>
     26  </div>
     27
     28  <div class="page-header">
     29    <div class="fcm-page-content pull-right well well-sm"></div>
     30    <h1>FCM: User Guide: Annex: The FCM 1 Extract System</h1>
     31  </div>
     32
     33  <div class="container">
     34  <div class="row">
     35  <div class="col-md-12">
     36
     37  <h2 id="introduction">Introduction</h2>
     38
     39  <p><em>The FCM 1 extract system is deprecated. The documentation for the
     40  current extract system can be found at <a href="make.html">FCM
     41  Make</a>.</em></p>
    1942
    2043  <p>The extract system provides an interface between the revision control
    … …  
    2346  directory tree suitable for feeding into the build system. In this chapter,
    2447  we shall use many examples to explain how to use the extract system. At the
    25   end of this chapter, you will be able to extract code from the local file system
    26   as well as from different branches of different repository URLs. You will
    27   also learn how to mirror code to a remote machine. Finally, you will be given
    28   an introduction on how to specify configurations for the build system via the
    29   extract configuration file. (For further information on the build system,
    30   please see the next chapter <a href="build.html">The Build System</a>.) The
    31   last section of the chapter tells you what you can do in the case when
    32   Subversion is not available.</p>
    33 
    34   <h2><a name="command">The Extract Command</a></h2>
     48  end of this chapter, you will be able to extract code from the local file
     49  system as well as from different branches of different repository URLs. You
     50  will also learn how to mirror code to an alternate destination. Finally, you
     51  will be given an introduction on how to specify configurations for the build
     52  system via the extract configuration file. (For further information on the
     53  build system, please see the next chapter <a href="build.html">The Build
     54  System</a>.) The last section of the chapter tells you what you can do in the
     55  case when Subversion is not available.</p>
     56
     57  <h2 id="command">The Extract Command</h2>
    3558
    3659  <p>To invoke the extract system, simply issue the command:</p>
    … …  
    4063
    4164  <p>By default, the extract system searches for an extract configuration file
    42   "ext.cfg" in "$PWD" and then "$PWD/cfg". If an extract configuration file is
    43   not found in these directories, the command fails with an error. If an
    44   extract configuration file is found, the system will use the configuration
    45   specified in the file to perform the current extraction.</p>
    46 
    47   <p>If the destination of the extraction does not exist, the system performs a
    48   new full extraction to the destination. If a previous extraction already
    49   exists at the destination, the system performs an incremental extraction,
    50   updating any modifications if necessary. If a full (fresh) extraction is
    51   required for whatever reason, you can invoke the extract system using the
    52   "-f" option, (i.e. the command becomes "fcm extract -f"). For further
    53   information on the extract command, please see <a href=
    54   "command_ref.html#fcm_ext">FCM Command Reference &gt; fcm extract</a>.</p>
    55 
    56   <h2><a name="simple">Simple Usage</a></h2>
     65  <samp>ext.cfg</samp> in <samp>$PWD</samp> and then <samp>$PWD/cfg</samp>. If
     66  an extract configuration file is not found in these directories, the command
     67  fails with an error. If an extract configuration file is found, the system
     68  will use the configuration specified in the file to perform the current
     69  extract.</p>
     70
     71  <p>If the destination of the extract does not exist, the system performs a
     72  new full extract to the destination. If a previous extract already exists at
     73  the destination, the system performs an incremental extract, updating any
     74  modifications if necessary. If a full (fresh) extract is required for
     75  whatever reason, you can invoke the extract system using the <code>-f</code>
     76  option, (i.e. the command becomes <code>fcm extract -f</code>). If you simply
     77  want to remove all the items generated by a previous extract in the
     78  destination, you can invoke the extract system using the <code>--clean</code>
     79  option.</p>
     80
     81  <p>For further information on the extract command, please see <a href=
     82  "command_ref.html#fcm-extract">FCM Command Reference &gt; fcm extract</a>.</p>
     83
     84  <h2 id="simple">Simple Usage</h2>
    5785
    5886  <p>The extract configuration file is the main user interface of the extract
    … …  
    6290  file</a>.</p>
    6391
    64   <h3><a name="simple_local">Extract from a local path</a></h3>
     92  <h3 id="simple_local">Extract from a local path</h3>
    6593
    6694  <p>A simple example of a basic extract configuration file is given below:</p>
    67 
    68   <table class="pad" summary="extract_example1" border="1" width="100%">
    69     <tr>
    70       <th>Extract configuration example 1 - extract from a local path</th>
    71     </tr>
    72 
    73     <tr>
    74       <td>
    75         <pre>
     95  <pre id="example_1">
     96# Example 1
     97# ----------------------------------------------------------------------
    7698cfg::type         ext       # line 1
    7799cfg::version      1.0       # line 2
    78100                            # line 3
    79 dest::rootdir     $PWD      # line 4
     101dest              $PWD      # line 4
    80102                            # line 5
    81103repos::var::user  $HOME/var # line 6
    … …  
    83105expsrc::var::user code      # line 8
    84106</pre>
    85       </td>
    86     </tr>
    87   </table>
    88107
    89108  <p>The above demonstrates how to use the extract system to extract code from
    … …  
    91110
    92111  <ul>
    93     <li>line 1: the label "CFG::TYPE" declares the type of the configuration
    94     file. The value "ext" tells the system that it is an extract configuration
    95     file.</li>
    96 
    97     <li>line 2: the label "CFG::VERSION" declares the version of the extract
    98     configuration file. The current default is "1.0". Although it is not
    99     currently used, if we have to change the format of the configuration file
    100     at a later stage, we shall be able to use this number to determine whether
    101     we are reading a file with an older format or one with a newer format.</li>
    102 
    103     <li>line 3: a blank line or a line beginning with a "#" is a comment, and
    104     is ignored by the interpreter.</li>
    105 
    106     <li>line 4: the label "DEST::ROOTDIR" declares the destination root
    107     directory of this extraction. The value "$PWD" expands to the current
    108     working directory.</li>
    109 
    110     <li>line 5: comment line, ignored.</li>
    111 
    112     <li>line 6: the label "REPOS::&lt;pck&gt;::&lt;branch&gt;" declares the top
    113     level URL or path of a repository. The package name of the repository is
    114     given by &lt;pck&gt;. In our example, we choose "var" as the name of the
     112    <li><dfn>line 1</dfn>: the label <code>CFG::TYPE</code> declares the type
     113    of the configuration file. The value <samp>ext</samp> tells the system that
     114    it is an extract configuration file.</li>
     115
     116    <li><dfn>line 2</dfn>: the label <code>CFG::VERSION</code> declares the
     117    version of the extract configuration file. The current default is
     118    <samp>1.0</samp>. Although it is not currently used, if we have to change
     119    the format of the configuration file at a later stage, we shall be able to
     120    use this number to determine whether we are reading a file with an older
     121    format or one with a newer format.</li>
     122
     123    <li><dfn>line 3</dfn>: a blank line or a line beginning with a
     124    <code>#</code> is a comment, and is ignored by the interpreter.</li>
     125
     126    <li><dfn>line 4</dfn>: the label <code>DEST</code> declares the destination
     127    root directory of this extract. The value <samp>$PWD</samp> expands to the
     128    current working directory.</li>
     129
     130    <li><dfn>line 5</dfn>: comment line, ignored.</li>
     131
     132    <li><dfn>line 6</dfn>: the label
     133    <code>REPOS::&lt;pck&gt;::&lt;branch&gt;</code> declares the top level URL
     134    or path of a repository. The package name of the repository is given by
     135    &lt;pck&gt;. In our example, we choose <samp>var</samp> as the name of the
    115136    package. (You can choose any name you like, however, it is usually sensible
    116     to use a package name that matches the name of the project or system you are
    117     working with.) The branch name in the repository is given by &lt;branch&gt;.
    118     (Again, you can choose any name you like, however, it is usually sensible to
    119     use a name such as "trunk", "user" or something that matches your branch
    120     name.) In our example, the word "user" is normally used to denote a local
    121     user directory. Hence the statement declares that the repository path for
    122     the "var" package in the "user" branch can be found at "$HOME/var".</li>
    123 
    124     <li>line 7: comment line, ignored.</li>
    125 
    126     <li>line 8: the label "EXPSRC::&lt;pck&gt;::&lt;branch&gt;" declares an
    127     "expandable" source directory for the package &lt;pck&gt; in the branch
    128     &lt;branch&gt;. In our example, the package name is "var", and the branch
    129     name is "user". These match the package and the branch names of the
    130     repository declaration in line 6. It means that the source directory
    131     declaration is associated with the path "$HOME/var". The value of the
    132     declaration "code" is therefore a sub-directory under "$HOME/var". By
    133     declaring a source directory using an "expsrc" label, the system
     137    to use a package name that matches the name of the project or system you
     138    are working with.) The branch name in the repository is given by
     139    &lt;branch&gt;. (Again, you can choose any name you like, however, it is
     140    usually sensible to use a name such as <samp>base</samp>, <samp>user</samp>
     141    or something that matches your branch name.) In our example, the word
     142    <samp>user</samp> is normally used to denote a local user directory. Hence
     143    the statement declares that the repository path for the <samp>var</samp>
     144    package in the <samp>user</samp> branch can be found at
     145    <samp>$HOME/var</samp>.</li>
     146
     147    <li><dfn>line 7</dfn>: comment line, ignored.</li>
     148
     149    <li><dfn>line 8</dfn>: the label
     150    <code>EXPSRC::&lt;pck&gt;::&lt;branch&gt;</code> declares an
     151    <em>expandable</em> source directory for the package &lt;pck&gt; in the
     152    branch &lt;branch&gt;. In our example, the package name is
     153    <samp>var</samp>, and the branch name is <samp>user</samp>. These match the
     154    package and the branch names of the repository declaration in line 6. It
     155    means that the source directory declaration is associated with the path
     156    <samp>$HOME/var</samp>. The value of the declaration <samp>code</samp> is
     157    therefore a sub-directory under <samp>$HOME/var</samp>. By declaring a
     158    source directory using an <code>EXPSRC</code> label, the system
    134159    automatically searches for all sub-directories (recursively) under the
    135160    declared source directory.</li>
    … …  
    137162
    138163  <p>Invoking the extract system using the above configuration file will
    139   "extract" all sub-directories under "$HOME/var/code" to "$PWD/src/var/code".
    140   Note: the extract system ignores all hidden files, (i.e. directories and
    141   files beginning with a "."). It will write a build configuration file to
    142   "$PWD/cfg/bld.cfg". The configuration used for this extraction will be
    143   written to the configuration file at "$PWD/cfg/ext.cfg".</p>
    144 
    145   <table class="pad" summary="note - incremental extraction" border="1" width=
    146   "100%">
    147     <tr>
    148       <th>Note - incremental extraction</th>
    149     </tr>
    150 
    151     <tr>
    152       <td>Suppose you have already performed an extraction using the above
    153       configuration file. At a later time, you have made some changes to some
    154       of the files in the source directory. Re-running the extract system on
    155       the same configuration will trigger an incremental extraction. In an
    156       incremental extraction, the system will update only those files that are
    157       modified. In exact words, the system checks the modification time of each
    158       file in the source and destination. If a source file is newer than its
    159       corresponding destination file, it checks whether the content differs.
    160       The destination is only updated if its content differs from the
    161       source.</td>
    162     </tr>
    163   </table>
    164 
    165   <h3><a name="simple_url">Extract from a Subversion URL</a></h3>
     164  extract all sub-directories under <samp>$HOME/var/code</samp> to
     165  <samp>$PWD/src/var/code</samp>. Note: the extract system ignores symbolic
     166  links and hidden files, (i.e. file names beginning with a <samp>.</samp>). It
     167  will write a build configuration file to <samp>$PWD/cfg/bld.cfg</samp>. The
     168  configuration used for this extract will be written to the configuration file
     169  at <samp>$PWD/cfg/ext.cfg</samp>.</p>
     170
     171  <dl>
     172    <dt>Note - incremental extract</dt>
     173
     174    <dd>Suppose you have already performed an extract using the above
     175    configuration file. At a later time, you have made some changes to some of
     176    the files in the source directory. Re-running the extract system on the
     177    same configuration will trigger an incremental extract. In an incremental
     178    extract, the system will update only those files that are modified. If the
     179    last modified time (or last commit revision) of a source file in the
     180    current extract differs from that in the previous extract, the system will
     181    attempt a content comparison. The system updates the destination only if
     182    the content and/or file access permission of the source differs from that
     183    of the destination.</dd>
     184  </dl>
     185
     186  <h3 id="simple_url">Extract from a Subversion URL</h3>
    166187
    167188  <p>The next example demonstrates how to extract from a Subversion repository
    168189  URL:</p>
    169 
    170   <table class="pad" summary="extract_example2" border="1" width="100%">
    171     <tr>
    172       <th>Extract configuration example 2 - extract from a Subversion URL</th>
    173     </tr>
    174 
    175     <tr>
    176       <td>
    177         <pre>
     190  <pre id="example_2">
     191# Example 2
     192# ----------------------------------------------------------------------
    178193cfg::type           ext                    # line 1
    179194cfg::version        1.0                    # line 2
    180195                                           # line 3
    181 dest::rootdir       $PWD                   # line 4
     196dest                $PWD                   # line 4
    182197                                           # line 5
    183 repos::var::trunk   svn://server/var/trunk # line 6
    184 version::var::trunk 1234                   # line 7
     198repos::var::base    svn://server/var/trunk # line 6
     199revision::var::base 1234                   # line 7
    185200                                           # line 8
    186 expsrc::var::trunk  code                   # line 9
    187 </pre>
    188       </td>
    189     </tr>
    190   </table>
     201expsrc::var::base   code                   # line 9
     202</pre>
    191203
    192204  <ul>
    193     <li>line 1 to 5: same as example 1.</li>
    194 
    195     <li>line 6: the line declares the repository location of the "trunk" branch
    196     of the "var" package to be the Subversion URL
    197     "svn://server/var/trunk".</li>
    198 
    199     <li>line 7: the label "VERSION::&lt;pck&gt;::&lt;branch&gt;" declares the
    200     revision of the repository associated with the package &lt;pck&gt; in the
    201     branch &lt;branch&gt;. The current line tells the extract system to use
    202     revision 1234 of "svn://server/var/trunk". If the revision is not declared,
    203     the default revision "HEAD" will be assumed.</li>
    204 
    205     <li>line 8: comment line, ignored.</li>
    206 
    207     <li>line 9: the line declares an expandable source directory in the
    208     repository "svn://server/var/trunk".</li>
     205    <li><dfn>line 1-5</dfn>: same as <a href="#example_1">example 1</a>.</li>
     206
     207    <li><dfn>line 6</dfn>: the line declares the repository location of the
     208    <samp>base</samp> branch of the <samp>var</samp> package to be the
     209    Subversion URL <samp>svn://server/var/trunk</samp>.</li>
     210
     211    <li><dfn>line 7</dfn>: the label
     212    <code>REVISION::&lt;pck&gt;::&lt;branch&gt;</code> declares the revision of
     213    the repository associated with the package &lt;pck&gt; in the branch
     214    &lt;branch&gt;. The current line tells the extract system to use revision
     215    1234 of <samp>svn://server/var/trunk</samp>. It is worth noting that the
     216    declared revision must be a revision when the declared branch exists. The
     217    actual revision used is the last changed revision of the declared one. If
     218    the revision is not declared, the default is to use the last changed
     219    revision at the HEAD of the branch.</li>
     220
     221    <li><dfn>line 8</dfn>: comment line, ignored.</li>
     222
     223    <li><dfn>line 9</dfn>: the line declares an expandable source directory in
     224    the repository <samp>svn://server/var/trunk</samp>.</li>
    209225  </ul>
    210226
    211227  <p>Invoking the extract system using the above configuration file will
    212   extract all sub-directories under "svn://server/var/trunk/code" to
    213   "$PWD/src/var/code". It will write a build configuration file to
    214   "$PWD/cfg/bld.cfg". The configuration used for this extraction will be
    215   written to the configuration file at "$PWD/cfg/ext.cfg".</p>
    216 
    217   <table class="pad" summary=
    218   "note - declaration of source directories for extraction" border="1" width=
    219   "100%">
    220     <tr>
    221       <th>Note - declaration of source directories for extraction</th>
    222     </tr>
    223 
    224     <tr>
    225       <td>
    226         <strong>EXPSRC or SRC?</strong>
    227 
    228         <p>So far, we have only declared source directories using the "EXPSRC"
    229         statement, which stands for "expandable source directory". A source
    230         directory declared using this statement will trigger the system to
    231         search recursively for any sub-directories under the declared one. Any
    232         sub-directories containing regular source files will be included in the
    233         extraction. Empty directories, hidden directories and directories
    234         containing only hidden files are ignored.</p>
    235 
    236         <p>If you do not want the system to search for sub-directories
    237         underneath your declared source directory, you can declare your source
    238         directory using the "SRC" statement. The "SRC" statement is essentially
    239         the same as "EXPSRC" except that it does not trigger the automatic
    240         recursive search for source directories. In fact, the system implements
    241         the "EXPSRC" statement by expanding it into a list of "SRC"
    242         statements.</p>
    243 
    244         <p><strong>Package and sub-package</strong></p>
    245 
    246         <p>The second field of a repository, revision or source directory
    247         declaration label is the name of the container package. It is a name
    248         selected by the user to identify the system or project he/she is
    249         working on. (Therefore, it is often sensible to choose an identifier
    250         that matches the name of the project or system.) The package name
    251         provides a unique namespace for a file container. Source directories
    252         are automatically arranged into sub-packages, using the names of the
    253         sub-directories as the names of the sub-packages. For example, the
    254         declaration at line 9 in example 2 will put the source directory in the
    255         "var::code" sub-package automatically.</p>
    256 
    257         <p>The double colon "::" and the double underscore "__" (internal only)
    258         are delimiters for package names in the extract system. Please avoid
    259         using "::" and "__" for naming your files and directories.</p>
    260 
    261         <p>You can declare a sub-package name explicitly in your source
    262         directory statement. For example, the following two lines are
    263         equivalent:</p>
    264         <pre>
    265 src::var::trunk                        code/VarMod_Surface
    266 src::var::code::VarMod_Surface::trunk  code/VarMod_Surface
    267 </pre>
    268 
    269         <p>Explicit sub-package declaration should not be used normally, as it
    270         requires a lot more typing (although there are some situations where it
    271         can be useful).</p>
    272       </td>
    273     </tr>
    274   </table>
    275 
    276   <table class="pad" summary="note - the expanded extract configuration file"
    277   border="1" width="100%">
    278     <tr>
    279       <th>Note - the expanded extract configuration file</th>
    280     </tr>
    281 
    282     <tr>
    283       <td>
    284         At the end of a successful extraction, the configuration used by the
    285         current extraction is written in "cfg/ext.cfg" under the extract
    286         destination root. This file is an "expanded" version of the original,
    287         with changes in the following declarations:
    288 
    289         <ul>
    290           <li>All revision keywords are converted into revision numbers.</li>
    291 
    292           <li>If a revision is not defined for a repository, it is set to the
    293           corresponding revision number of the HEAD revision.</li>
    294 
    295           <li>All URL keywords are converted into the full URLs.</li>
    296 
    297           <li>All EXPSRC declarations are expanded into SRC declarations.</li>
    298 
    299           <li>All other variables are expanded.</li>
    300         </ul>
    301 
    302         <p>With this file, it should be possible for later extraction to
    303         re-create the current configuration even if the contents of the
    304         repository have changed. (This applies only to code stored in the
    305         repository.)</p>
    306       </td>
    307     </tr>
    308   </table>
    309 
    310   <h3><a name="simple_mirror">Mirror code to a remote machine</a></h3>
     228  extract all sub-directories under <samp>svn://server/var/trunk/code</samp> to
     229  <samp>$PWD/src/var/code</samp>. It will write a build configuration file to
     230  <samp>$PWD/cfg/bld.cfg</samp>. The configuration used for this extract will
     231  be written to the configuration file at <samp>$PWD/cfg/ext.cfg</samp>.</p>
     232
     233  <dl>
     234    <dt>EXPSRC or SRC?</dt>
     235
     236    <dd>
     237      <p>So far, we have only declared source directories using the
     238      <code>EXPSRC</code> statement, which stands for <em>expandable source
     239      directory</em>. A source directory declared using this statement will
     240      trigger the system to search recursively for any sub-directories under
     241      the declared one. Any sub-directories containing regular source files
     242      will be included in the extract. Symbolic links, hidden files and empty
     243      directories (or those containing only symbolic links and/or hidden files)
     244      are ignored.</p>
     245
     246      <p>If you do not want the system to search for sub-directories underneath
     247      your declared source directory, you can declare your source directory
     248      using the <code>SRC</code> statement. The <code>SRC</code> statement is
     249      essentially the same as <code>EXPSRC</code> except that it does not
     250      trigger the automatic recursive search for source directories. In fact,
     251      the system implements the <code>EXPSRC</code> statement by expanding it
     252      into a list of <code>SRC</code> statements.</p>
     253    </dd>
     254
     255    <dt>Package and sub-package</dt>
     256
     257    <dd>
     258      <p>The second field of a repository, revision or source directory
     259      declaration label is the name of the container package. It is a name
     260      selected by the user to identify the system or project he/she is working
     261      on. (Therefore, it is often sensible to choose an identifier that matches
     262      the name of the project or system.) The package name provides a unique
     263      namespace for a file container. Source directories are automatically
     264      arranged into sub-packages, using the names of the sub-directories as the
     265      names of the sub-packages. For example, the declaration at line 9 in
     266      <a href="#example_2">example 2</a> will put the source directory in the
     267      <samp>var/code</samp> sub-package automatically.</p>
     268
     269      <p>Note that, in additional to slash <code>/</code>, double colon
     270      <code>::</code> and double underscore <code>__</code> (internal only)
     271      also act as delimiters for package names. Please avoid using them for
     272      naming your files and directories.</p>
     273
     274      <p>You can declare a sub-package name explicitly in your source directory
     275      statement. For example, the following two lines are equivalent:</p>
     276      <pre>
     277src::var::base                      code/VarMod_Surface
     278src::var/code/VarMod_Surface::base  code/VarMod_Surface
     279</pre>
     280
     281      <p>Explicit sub-package declaration should not be used normally, as it
     282      requires a lot more typing (although there are some situations where it
     283      can be useful, e.g. if you need to re-define the package name).</p>
     284
     285      <p>Currently, the extract system only supports non-space characters in
     286      the package name, as the space character is used as a delimiter between
     287      the declaration label and its value. If there are spaces in the path name
     288      to a file or directory, you should explicity re-define the package name
     289      of that path to a package name with no space using the above method.
     290      However, we recommend that only non-space characters are used for naming
     291      directories and files to make life simpler.</p>
     292    </dd>
     293  </dl>
     294
     295  <dl>
     296    <dt>The expanded extract configuration file</dt>
     297
     298    <dd>
     299      <p>At the end of a successful extract, the configuration used by the
     300      current extract is written in <samp>cfg/ext.cfg</samp> under the extract
     301      destination root. This file is an <em>expanded</em> version of the
     302      original, with changes in the following declarations:</p>
     303
     304      <ul>
     305        <li>All revision keywords are converted into revision numbers.</li>
     306
     307        <li>If a revision is not defined for a repository, it is set to the
     308        corresponding revision number of the HEAD revision.</li>
     309
     310        <li>All URL keywords are converted into the full URLs.</li>
     311
     312        <li>All <code>EXPSRC</code> declarations are expanded into
     313        <code>SRC</code> declarations.</li>
     314
     315        <li>All other variables are expanded.</li>
     316      </ul>
     317
     318      <p>With this file, it should be possible for a later extract to re-create
     319      the current configuration even if the contents of the repository have
     320      changed. (This applies only to code stored in the repository.)</p>
     321    </dd>
     322  </dl>
     323
     324  <h3 id="simple_mirror">Mirror code to an alternate location</h3>
    311325
    312326  <p>The next example demonstrates how to extract from a repository and mirror
    313   the code to a remote machine. It is essentially the same as example 2,
    314   except that it has three new lines to describe how the system can mirror the
    315   extracted code to a remote machine.</p>
    316 
    317   <table class="pad" summary="extract_example3" border="1" width="100%">
    318     <tr>
    319       <th>Extract configuration example 3 - mirror code to remote machine</th>
    320     </tr>
    321 
    322     <tr>
    323       <td>
    324         <pre>
     327  the code to an alternate location. It is essentially the same as <a href=
     328  "#example_2">example 2</a>, except that it has three new lines to describe
     329  how the system can mirror the extracted code to an alternate location.</p>
     330  <pre id="example_3">
     331# Example 3
     332# ----------------------------------------------------------------------
    325333cfg::type           ext
    326334cfg::version        1.0
    327335
    328 dest::rootdir       $PWD
     336dest                $PWD
    329337
    330338rdest::machine      tx01                           # line 6
    331339rdest::logname      frva                           # line 7
    332 rdest::rootdir      /scratch/frva/extract/example3 # line 8
    333 
    334 repos::var::trunk   svn://server/var/trunk
    335 version::var::trunk 1234
    336 
    337 expsrc::var::trunk  code
    338 </pre>
    339       </td>
    340     </tr>
    341   </table>
     340rdest               /scratch/frva/extract/example3 # line 8
     341
     342repos::var::base    svn://server/var/trunk
     343revision::var::base 1234
     344
     345expsrc::var::base   code
     346</pre>
    342347
    343348  <p>Here is an explanation of what each line does:</p>
    344349
    345350  <ul>
    346     <li>line 6: "RDEST::MACHINE" declares the target machine to which the code
    347     will be mirrored. The example mirrors the code to the machine named
    348     "tx01".</li>
    349 
    350     <li>line 7: "RDEST::LOGNAME" declares the remote user name of the target
    351     machine, to which the user has remote login access. If this is not
     351    <li><dfn>line 6</dfn>: <code>RDEST::MACHINE</code> declares the target
     352    machine to which the code will be mirrored. The example mirrors the code to
     353    the machine named <samp>tx01</samp>.</li>
     354
     355    <li><dfn>line 7</dfn>: <code>RDEST::LOGNAME</code> declares the user name
     356    of the target machine, to which the user has login access. If this is not
    352357    declared, the system uses the login name of the current user on the local
    353358    machine.</li>
    354359
    355     <li>line 8: "RDEST::ROOTDIR" declares the root directory of the extraction
    356     on the remote target machine. This is where the mirror version of the
    357     extraction will be sent.</li>
     360    <li><dfn>line 8</dfn>: <code>RDEST</code> declares the root directory of
     361    the alternate destination, where the mirror version of the extract will be
     362    sent.</li>
    358363  </ul>
    359364
    360365  <p>Invoking the extract system on the above configuration will trigger an
    361   extraction similar to that given in example 2, but it will also attempt to
    362   mirror the contents at "$PWD/src/var/code" to
    363   "/scratch/frva/extract/example3/src" on the remote machine. It will also
    364   mirror the expanded extract configuration file "$PWD/cfg/ext.cfg" to
    365   "/scratch/frva/extract/example3/cfg/ext.cfg" and "$PWD/cfg/bld.cfg" to
    366   "/scratch/frva/extract/example3/cfg/bld.cfg". It is also worth noting that
    367   the content of the build configuration file will be slightly different, since
    368   it will include directory names appropriate for the remote system.</p>
    369 
    370   <table class="pad" summary="note - mirroring command" border="1" width=
    371   "100%">
    372     <tr>
    373       <th>Note - mirroring command</th>
    374     </tr>
    375 
    376     <tr>
    377       <td>
    378         The extract system currently supports "rdist" and "rsync" as its
    379         mirroring tool. The default is "rsync". To use "rdist" instead of
    380         "rsync", add the following line to your "$HOME/.fcm" file:
    381         <pre>
    382 set::tool::mirror  rdist
    383 </pre>
    384 
    385         <p>N.B. If you are going to mirror code to another machine, you need to
    386         ensure that your account on the remote machine is set up correctly to
    387         accept commands from the local machine. In our current settings of both
    388         "rdist" and "rsync", all you need to do is set up your "$HOME/.rhosts"
    389         file on the remote machine. For example, if you are "fred" working on
    390         the local machine "eld001", you will need to have the following entry
    391         in your "$HOME/.rhosts" on the remote machine:</p>
    392         <pre>
    393 eld001  fred
    394 </pre>
    395       </td>
    396     </tr>
    397   </table>
    398 
    399   <h2><a name="advanced">Advanced Usage</a></h2>
    400 
    401   <h3><a name="advanced_multi">Extract from multiple repositories</a></h3>
     366  extract similar to that given in <a href="#example_2">example 2</a>, but it
     367  will also attempt to mirror the contents at <samp>$PWD/src/var/code</samp> to
     368  <samp>/scratch/frva/extract/example3/src</samp> on the alternate destination.
     369  It will also mirror the expanded extract configuration file
     370  <samp>$PWD/cfg/ext.cfg</samp> to
     371  <samp>/scratch/frva/extract/example3/cfg/ext.cfg</samp> and
     372  <samp>$PWD/cfg/bld.cfg</samp> to
     373  <samp>/scratch/frva/extract/example3/cfg/bld.cfg</samp>. It is also worth
     374  noting that the content of the build configuration file will be slightly
     375  different, since it will include directory names appropriate for the
     376  alternate destination.</p>
     377
     378  <dl>
     379    <dt>Note - mirroring command</dt>
     380
     381    <dd>
     382      <p>The extract system currently supports <code>rdist</code> and
     383      <code>rsync</code> as its mirroring tool. The default is
     384      <code>rsync</code>. To use <code>rdist</code> instead of
     385      <code>rsync</code>, add the following line to your extract configuration
     386      file:</p>
     387      <pre>
     388rdest::mirror_cmd  rdist
     389</pre>
     390
     391      <p>If <code>rsync</code> is used to mirror an extract, the system needs to
     392      issue a separate remote shell command to create the container directory of
     393      the mirror destination. The default is to issue a shell command in the
     394      form <samp>ssh -n -oBatchMode=yes LOGNAME@MACHINE mkdir -p DEST</samp>.
     395      The following declarations can be used to modify the command:</p>
     396      <pre>
     397# Examples using the default settings:
     398rdest::rsh_mkdir_rsh         ssh
     399rdest::rsh_mkdir_rshflags    -n -oBatchMode=yes
     400rdest::rsh_mkdir_mkdir       mkdir
     401rdest::rsh_mkdir_mkdirflags  -p
     402</pre>
     403
     404      <p>In addition, the default <code>rsync</code> shell command is
     405      <samp>rsync -a --exclude='.*' --delete-excluded --timeout=900 --rsh='ssh
     406      -oBatchMode=yes' SOURCE DEST</samp>. The following declarations can be
     407      used to modify the command:</p>
     408      <pre>
     409# Examples using the default settings:
     410rdest::rsync       rsync
     411rdest::rsyncflags  -a --exclude='.*' --delete-excluded --timeout=900 \
     412                   --rsh='ssh -oBatchMode=yes'
     413</pre>
     414    </dd>
     415  </dl>
     416
     417  <h2 id="advanced">Advanced Usage</h2>
     418
     419  <h3 id="advanced_multi">Extract from multiple repositories</h3>
    402420
    403421  <p>So far, we have only extracted from a single location. The extract system
    404422  is not much use if that is the only thing it can do. In fact, the extract
    405   system supports extraction of multiple source directories from multiple
    406   branches in multiple repositories. The following configuration file is an
    407   example of how to extract from multiple repositories:</p>
    408 
    409   <table class="pad" summary="extract_example4" border="1" width="100%">
    410     <tr>
    411       <th>Extract configuration example 4 - extract from multiple
    412       repositories</th>
    413     </tr>
    414 
    415     <tr>
    416       <td>
    417         <pre>
     423  system supports extract of multiple source directories from multiple branches
     424  in multiple repositories. The following configuration file is an example of
     425  how to extract from multiple repositories:</p>
     426  <pre id="example_4">
     427# Example 4
     428# ----------------------------------------------------------------------
    418429cfg::type           ext
    419430cfg::version        1.0
    420431
    421 dest::rootdir       $PWD
    422 
    423 repos::var::trunk   fcm:var_tr              # line 6
    424 repos::ops::trunk   fcm:ops_tr              # line 7
    425 repos::gen::trunk   fcm:gen_tr              # line 8
    426 
    427 version::gen::trunk 2468                    # line 10
    428 
    429 expsrc::var::trunk  code                    # line 12
    430 expsrc::var::trunk  scripts                 # line 13
    431 expsrc::ops::trunk  code                    # line 14
    432 src::gen::trunk     code/GenMod_Constants   # line 15
    433 src::gen::trunk     code/GenMod_Control     # line 16
    434 src::gen::trunk     code/GenMod_FortranIO   # line 17
    435 src::gen::trunk     code/GenMod_GetEnv      # line 18
    436 src::gen::trunk     code/GenMod_ModelIO     # line 19
    437 src::gen::trunk     code/GenMod_ObsInfo     # line 20
    438 src::gen::trunk     code/GenMod_Platform    # line 21
    439 src::gen::trunk     code/GenMod_Reporting   # line 22
    440 src::gen::trunk     code/GenMod_Trace       # line 23
    441 src::gen::trunk     code/GenMod_UMConstants # line 24
    442 src::gen::trunk     code/GenMod_Utilities   # line 25
    443 </pre>
    444       </td>
    445     </tr>
    446   </table>
     432dest                $PWD
     433
     434repos::var::base    fcm:var_tr              # line 6
     435repos::ops::base    fcm:ops_tr              # line 7
     436repos::gen::base    fcm:gen_tr              # line 8
     437
     438revision::gen::base 2468                    # line 10
     439
     440expsrc::var::base   src/code                    # line 12
     441expsrc::var::base   src/scripts                 # line 13
     442expsrc::ops::base   src/code                    # line 14
     443src::gen::base      src/code/GenMod_Constants   # line 15
     444src::gen::base      src/code/GenMod_Control     # line 16
     445src::gen::base      src/code/GenMod_FortranIO   # line 17
     446src::gen::base      src/code/GenMod_GetEnv      # line 18
     447src::gen::base      src/code/GenMod_ModelIO     # line 19
     448src::gen::base      src/code/GenMod_ObsInfo     # line 20
     449src::gen::base      src/code/GenMod_Platform    # line 21
     450src::gen::base      src/code/GenMod_Reporting   # line 22
     451src::gen::base      src/code/GenMod_Trace       # line 23
     452src::gen::base      src/code/GenMod_UMConstants # line 24
     453src::gen::base      src/code/GenMod_Utilities   # line 25
     454</pre>
    447455
    448456  <p>Here is an explanation of what each line does:</p>
    449457
    450458  <ul>
    451     <li>line 6 to 8: these lines declare the repositories for the "trunk"
    452     branches of the "var", "ops" and "gen" packages respectively. It is worth
    453     noting that the values of the declarations are no longer Subversion URLs
    454     but are FCM URL keywords. These keywords are normally declared in the
    455     central configuration file of the FCM system, and will be expanded into the
    456     corresponding Subversion URLs by the FCM system. For further information on
    457     URL keywords, please see <a href=
    458     "code_management.html#svn_basic_keywords">Code Management System &gt; Using
    459     Subversion &gt; Basic Command Line Usage &gt; Repository &amp; Revision
    460     Keywords</a>.</li>
    461 
    462     <li>line 10: this line declares the revision number for the "trunk" branch
    463     of the "gen" package, i.e. for the "fcm:gen_tr" repository. It is worth
    464     noting that the revision numbers for the "var" and "ops" packages have not
    465     been declared. By default, their revision numbers will be set to
    466     "HEAD".</li>
    467 
    468     <li>line 12 to 14: these line declares the source directories for the
    469     "trunk" branches of the "var" and "ops" packages. For the "var" package, we
    470     are extracting everything from the "code" and the "scripts" sub-directory.
    471     For the "ops" package, we are extracting everything from the "code"
    472     directory.</li>
    473 
    474     <li>line 15 to 25: these line declares the source directories for the
    475     "trunk" branch of the "gen" package. The source directories declared will
    476     not be searched for sub-directories underneath the declared
    477     directories.</li>
     459    <li><dfn>line 6-8</dfn>: these lines declare the repositories for the
     460    <samp>base</samp> branches of the <samp>var</samp>, <samp>ops</samp> and
     461    <samp>gen</samp> packages respectively. It is worth noting that the values
     462    of the declarations are no longer Subversion URLs but are FCM URL keywords.
     463    These keywords are normally declared in the central configuration file of
     464    the FCM system, and will be expanded into the corresponding Subversion URLs
     465    by the FCM system. For further information on URL keywords, please see
     466    <a href="code_management.html#svn_basic_keywords">Code Management System
     467    &gt; Using Subversion &gt; Basic Command Line Usage &gt; Repository &amp;
     468    Revision Keywords</a>.</li>
     469
     470    <li><dfn>line 10</dfn>: this line declares the revision number for the
     471    <samp>base</samp> branch of the <samp>gen</samp> package, i.e. for the
     472    <samp>fcm:gen_tr</samp> repository. It is worth noting that the revision
     473    numbers for the <samp>var</samp> and <samp>ops</samp> packages have not
     474    been declared. By default, their revision numbers will be set to the last
     475    changed revision at the HEAD.</li>
     476
     477    <li><dfn>line 12-14</dfn>: these line declares the source directories for
     478    the <samp>base</samp> branches of the <samp>var</samp> and <samp>ops</samp>
     479    packages. For the <samp>var</samp> package, we are extracting everything
     480    from the <samp>code</samp> and the <samp>scripts</samp> sub-directory. For
     481    the <samp>ops</samp> package, we are extracting everything from the
     482    <samp>code</samp> directory.</li>
     483
     484    <li><dfn>line 15-25</dfn>: these line declares the source directories for
     485    the <samp>base</samp> branch of the <samp>gen</samp> package. The source
     486    directories declared will not be searched for sub-directories underneath
     487    the declared directories.</li>
    478488  </ul>
    479489
    … …  
    522532</pre>
    523533
    524   <table class="pad" summary="note - revision number" border="1" width="100%">
    525     <tr>
    526       <th>Note - revision number</th>
    527     </tr>
    528 
    529     <tr>
    530       <td>
    531         As seen in the above example, if a revision number is not specified for
    532         a repository URL, it defaults to the "HEAD" revision. The revision
    533         number can also be declared in other ways:
    534 
    535         <ul>
    536           <li>Any revision arguments acceptable by Subversion are allowed. You
    537           can use a valid revision number, a date between a pair of curly
    538           brackets (e.g. {"2005-05-01 12:00"}) or the keyword "HEAD". However,
    539           please do not use the keywords "BASE", "COMMITTED" or "PREV" as these
    540           are reserved for working copy only.</li>
    541 
    542           <li>FCM revision keywords are allowed. These must be defined for the
    543           corresponding repository URLs in either the central or the user FCM
    544           configuration file. For further information on revision keywords,
    545           please see <a href="code_management.html#svn_basic_keywords">Code
    546           Management &gt; Using Subversion &gt; Basic Command Line Usage &gt;
    547           Repository &amp; Revision Keywords</a>.</li>
    548 
    549           <li>Do not use the keyword "USER", as it is used internally by the
    550           extract system.</li>
    551         </ul>
    552       </td>
    553     </tr>
    554   </table>
    555 
    556   <h3><a name="advanced_branches">Extract from multiple branches</a></h3>
    557 
    558   <p>We have so far dealt with extraction from a single branch in any package.
    559   The extract system can be used to "combine" changes from different branches
    560   of a package. An example is given below:</p>
    561 
    562   <table class="pad" summary="extract_example5" border="1" width="100%">
    563     <tr>
    564       <th>Extract configuration example 5 - extract from multiple branches</th>
    565     </tr>
    566 
    567     <tr>
    568       <td>
    569         <pre>
     534  <dl>
     535    <dt>Note - revision number</dt>
     536
     537    <dd>
     538      <p>As seen in the above example, if a revision number is not specified
     539      for a repository URL, it defaults to the last changed revision at the
     540      HEAD of the branch. The revision number can also be declared in other
     541      ways:</p>
     542
     543      <ul>
     544        <li>Any revision arguments acceptable by Subversion are allowed. You
     545        can use a valid revision number, a date between a pair of curly
     546        brackets (e.g. <samp>{2005-05-01T12:00}</samp>) or the keyword HEAD.
     547        However, please do not use the keywords BASE, COMMITTED or PREV as
     548        these are reserved for working copy only.</li>
     549
     550        <li>FCM revision keywords are allowed. These must be defined for the
     551        corresponding repository URLs in either the central or the user FCM
     552        configuration file. For further information on revision keywords,
     553        please see <a href="code_management.html#svn_basic_keywords">Code
     554        Management &gt; Using Subversion &gt; Basic Command Line Usage &gt;
     555        Repository &amp; Revision Keywords</a>.</li>
     556
     557        <li>Do not use the keyword USER, as it is used internally by the
     558        extract system.</li>
     559      </ul>
     560
     561      <p>If a revision number is specified for a branch, the actual revision
     562      used by the extract system is the last changed revision of the branch,
     563      which may differ from the declared revision. While this behaviour is
     564      useful in most situations, some users may find it confusing to work with.
     565      It is possible to alter this behaviour so that extract will fail if the
     566      declared revision does not correspond to a changeset of the declared
     567      branch. Make the following declaration to switch on this checking:</p>
     568      <pre>
     569revmatch  true
     570</pre>
     571    </dd>
     572  </dl>
     573
     574  <h3 id="advanced_branches">Extract from multiple branches</h3>
     575
     576  <p>We have so far dealt with a single branch in any package. The extract
     577  system can be used to <em>combine</em> changes from different branches of a
     578  package. An example is given below:</p>
     579  <pre id="example_5">
     580# Example 5
     581# ----------------------------------------------------------------------
    570582cfg::type               ext
    571583cfg::version            1.0
    572584 
    573 dest::rootdir           $PWD
     585dest                    $PWD
    574586 
    575 repos::var::trunk       fcm:var_tr
    576 repos::ops::trunk       fcm:ops_tr
    577 repos::gen::trunk       fcm:gen_tr
     587repos::var::base        fcm:var_tr
     588repos::ops::base        fcm:ops_tr
     589repos::gen::base        fcm:gen_tr
    578590 
    579 version::gen::trunk     2468
     591revision::gen::base     2468
    580592 
    581 expsrc::var::trunk      code
    582 expsrc::var::trunk      scripts
    583 expsrc::ops::trunk      code
    584 src::gen::trunk         code/GenMod_Constants
    585 src::gen::trunk         code/GenMod_Control
    586 src::gen::trunk         code/GenMod_FortranIO
    587 src::gen::trunk         code/GenMod_GetEnv
    588 src::gen::trunk         code/GenMod_ModelIO
    589 src::gen::trunk         code/GenMod_ObsInfo
    590 src::gen::trunk         code/GenMod_Platform
    591 src::gen::trunk         code/GenMod_Reporting
    592 src::gen::trunk         code/GenMod_Trace
    593 src::gen::trunk         code/GenMod_UMConstants
    594 src::gen::trunk         code/GenMod_Utilities
    595 
    596 repos::var::new_stuff   fcm:var_br/frva/r1234_new_stuff   # line 27
    597 repos::var::bug_fix     fcm:var_br/frva/r1516_bug_fix     # line 28
    598 repos::ops::good_stuff  fcm:ops_br/opsrc/r3188_good_stuff # line 29
    599 </pre>
    600       </td>
    601     </tr>
    602   </table>
    603 
    604   <p>The configuration file in example 5 is similar to that of example 4 except
    605   for the last three lines. Here is an explanation of what they do:</p>
     593expsrc::var::base       src/code
     594expsrc::var::base       src/scripts
     595expsrc::ops::base       src/code
     596src::gen::base          src/code/GenMod_Constants
     597src::gen::base          src/code/GenMod_Control
     598src::gen::base          src/code/GenMod_FortranIO
     599src::gen::base          src/code/GenMod_GetEnv
     600src::gen::base          src/code/GenMod_ModelIO
     601src::gen::base          src/code/GenMod_ObsInfo
     602src::gen::base          src/code/GenMod_Platform
     603src::gen::base          src/code/GenMod_Reporting
     604src::gen::base          src/code/GenMod_Trace
     605src::gen::base          src/code/GenMod_UMConstants
     606src::gen::base          src/code/GenMod_Utilities
     607
     608repos::var::branch1     fcm:var_br/frva/r1234_new_stuff   # line 27
     609repos::var::branch2     fcm:var_br/frva/r1516_bug_fix     # line 28
     610repos::ops::branch1     fcm:ops_br/opsrc/r3188_good_stuff # line 29
     611</pre>
     612
     613  <p>The configuration file in <a href="#example_5">example 5</a> is similar to
     614  that of <a href="#example_4">example 4</a> except for the last three lines.
     615  Here is an explanation of what they do:</p>
    606616
    607617  <ul>
    608     <li>line 27: this line declares a repository URL for the "new_stuff" branch
    609     of the "var" package. From the URL of the branch, we know that the branch
    610     was created by the user "frva" based on the trunk at revision at 1234. The
    611     description of the branch is "new_stuff". The following points are worth
    612     noting:
     618    <li>
     619      <dfn>line 27</dfn>: this line declares a repository URL for the
     620      <samp>branch1</samp> branch of the <samp>var</samp> package. From the URL
     621      of the branch, we know that the branch was created by the user
     622      <samp>frva</samp> based on the trunk at revision at 1234. The description
     623      of the branch is <samp>branch1</samp>. The following points are worth
     624      noting:
    613625
    614626      <ul>
    … …  
    617629        the same Subversion repository.</li>
    618630
    619         <li>It is only by convention that the branch name "new_stuff" declared
    620         using the "REPOS::var::new_stuff" label should correspond to the branch
    621         description of the URL. It is not a requirement by the extract system.
    622         It is perfectly valid to use "REPOS::var::ham_egg" as the label of line
    623         27. In such case, the extract system will use "ham_egg" instead of
    624         "new_stuff" as the internal label of the URL.</li>
    625 
    626         <li>No revision is declared for this URL, so the default "HEAD"
    627         revision is used.</li>
     631        <li>No revision is declared for this URL, so the default is used which
     632        is the last changed revision at the HEAD of the branch.</li>
    628633
    629634        <li>No source directory is declared for this URL. By default, if no
    … …  
    631636        to use the same set of source directories as the first declared branch
    632637        of the package. In this case, the source directories declared for the
    633         "trunk" branch of the "var" package will be used.</li>
     638        <samp>base</samp> branch of the <samp>var</samp> package will be
     639        used.</li>
    634640      </ul>
    635641    </li>
    636642
    637     <li>line 28: this line declares another branch called "bug_fix" for the
    638     "var" package. No source directory is declared for this URL either, so it
    639     will use the same set of source directories declared for the "trunk"
    640     branch.</li>
    641 
    642     <li>line 29: this line declares a branch called "good_stuff" for the "ops"
    643     package. It will use the same set of source directories declared for the
    644     "ops" package "trunk" branch.</li>
     643    <li><dfn>line 28</dfn>: this line declares another branch called
     644    <samp>branch2</samp> for the <samp>var</samp> package. No source directory
     645    is declared for this URL either, so it will use the same set of source
     646    directories declared for the <samp>base</samp> branch.</li>
     647
     648    <li><dfn>line 29</dfn>: this line declares a branch called
     649    <samp>branch1</samp> for the <samp>ops</samp> package. It will use the same
     650    set of source directories declared for the <samp>ops</samp> package
     651    <samp>base</samp> branch.</li>
    645652  </ul>
    646653
    647654  <p>When we invoke the extract system, it will attempt to extract from the
    648   first declared branch of a package, if the last commit revision of the source
    649   directory is the same in all the branches. However, if the last commit
    650   revision of the source directory differs for different branches, the system
    651   will attempt to obtain an extract priority list for each source directory,
    652   using the following logic:</p>
     655  first declared branch of a package, if the last changed revision of the
     656  source directory is the same in all the branches. However, if the last
     657  changed revision of the source directory differs for different branches, the
     658  system will attempt to obtain an extract priority list for each source
     659  directory, using the following logic:</p>
    653660
    654661  <ol>
    … …  
    656663    branch to the last declared branch.</li>
    657664
    658     <li>The branch in which a source directory package is first declared is
    659     the "base" branch of the source directory package.</li>
    660 
    661     <li>The commit revision of a source directory package in a subsequently
    662     declared repository branch is compared with that of the base branch. If
    663     the commit revision is the same as that of the base branch, the source
    664     directory of this branch is discarded. Otherwise, it is placed at the end
    665     of the extract priority list.</li>
     665    <li>The branch in which a source directory package is first declared is the
     666    <samp>base</samp> branch of the source directory package.</li>
     667
     668    <li>The last changed revision of a source directory package in a
     669    subsequently declared repository branch is compared with that of the base
     670    branch. If the last changed revision is the same as that of the base
     671    branch, the source directory of this branch is discarded. Otherwise, it is
     672    placed at the end of the extract priority list.</li>
    666673  </ol>
    667674
    668   <p>For the "var" package in the above example, let us assume that we have
    669   three source directory packages X, Y and Z under "code", and their commit
    670   revisions under "trunk" are 100. Let's say we have committed some changes to
    671   X and Z in the "new_stuff" branch at revision 102, and other changes to Y
    672   and Z in the "bug_fix" branch at revision 104, the extract priority lists
    673   for X, Y and Z will look like:</p>
     675  <p>For the <samp>var</samp> package in the above example, let us assume that
     676  we have three source directory packages X, Y and Z under <samp>code</samp>,
     677  and their last changed revisions under <samp>base</samp> are 100. Let's say
     678  we have committed some changes to X and Z in the <samp>branch1</samp> branch
     679  at revision 102, and other changes to Y and Z in the <samp>branch2</samp>
     680  branch at revision 104, the extract priority lists for X, Y and Z will look
     681  like:</p>
    674682
    675683  <ul>
    676     <li>X: trunk (100, base), new_stuff (102), bug_fix (100, discarded)</li>
    677 
    678     <li>Y: trunk (100, base), new_stuff (100, discarded), bug_fix (104)</li>
    679 
    680     <li>Z: trunk (100, base), new_stuff (102), bug_fix (104)</li>
     684    <li>X: base (100, base), branch1 (102), branch2 (100, discarded)</li>
     685
     686    <li>Y: base (100, base), branch1 (100, discarded), branch2 (104)</li>
     687
     688    <li>Z: base (100, base), branch1 (102), branch2 (104)</li>
    681689  </ul>
    682690
    683   <p>Once we have an extract priority list for a source directory, we can
    684   begin the extraction of source files in the source directory. The source
    685   directory of the base branch is extracted first, followed by that in the
    686   subsequent branches. If a source file in a subsequent branch has the same
    687   content as the that in the base branch, it is discarded. Otherwise, the
    688   following logic determines the branch to use:</p>
     691  <p>Once we have an extract priority list for a source directory, we can begin
     692  extracting source files in the source directory. The source directory of the
     693  base branch is extracted first, followed by that in the subsequent branches.
     694  If a source file in a subsequent branch has the same content as the that in
     695  the base branch, it is discarded. Otherwise, the following logic determines
     696  the branch to use:</p>
    689697
    690698  <ol>
    … …  
    697705
    698706    <li>If a source file is modified in two or more subsequent branches and
    699     their modifications differ, then the behaviour depends on the override
    700     mode setting. If override mode is false, the extraction fails. Otherwise,
    701     the file in the latest declared branch takes precedence. The default
    702     override mode is false, which is the safe behaviour - conflicting changes
    703     should be resolved manually. However, this behaviour may not be the most
    704     efficient way for development. Therefore, an override mode is provided,
    705     which should be used with care. To switch on the override mode, make the
    706     following declaration in the extract configuration file:
     707    their modifications differ, then the behaviour depends on the "conflict
     708    mode" setting, which can be <code>fail</code>, <code>merge</code> (default)
     709    and <code>override</code>. If the conflict mode is <code>fail</code>, the
     710    extract fails. If the conflict mode is <code>merge</code>, the system will
     711    attempt to merge the changes using a tool such as <code>diff3</code>. The
     712    result of the merge will be used to update the destination. The extract
     713    fails only if there are unresolved conflicts in the merge. (In which case,
     714    the conflict should be resolved using the version control system before
     715    re-running the extract system.) If the conflict mode is
     716    <code>override</code>, the change in the latest declared branch takes
     717    precedence, and the changes in all other branches will be ignored. The
     718    conflict mode can be changed using the <code>CONFLICT</code> declaration in
     719    the extract configuration file. E.g:
    707720      <pre>
    708 override  1
     721conflict  fail
    709722</pre>
    710723    </li>
    711724  </ol>
    712  
     725
    713726  <p>Once the system has established which source files to use, it determines
    714   whether the destination is out of date or not. The destination is out of
    715   date if the source file does not exist or if its content differs from the
    716   version of the source file we are using. The system only updates the
    717   destination if it is considered to be out of date.</p>
     727  whether the destination file is out of date or not. The destination file is
     728  out of date if it does not exist or if its content differs from the version
     729  of the source file we are using. The system only updates the destination if
     730  it is considered to be out of date.</p>
    718731
    719732  <p>The extract system can also combine changes from branches in the Subversion
    720   repository and the local file system. The limitation is that there can only
    721   be one branch from the local file system. (By convention, the branch is named
    722   "user".)</p>
    723 
    724   <p>It is also worth bearing in mind that the "user" branch always takes
    725   precedence over branches residing in Subversion repositories. Hence, source
    726   directories from a "user" branch are always placed at the end of the extract
    727   priority list.</p>
    728 
    729   <p>Extracting from a mixture of Subversion repository and local file system
    730   is demonstrated in the next example.</p>
    731 
    732   <table class="pad" summary="extract_example6" border="1" width="100%">
    733     <tr>
    734       <th>Extract configuration example 6 - extract from multiple branches +
    735       user paths</th>
    736     </tr>
    737 
    738     <tr>
    739       <td>
    740         <pre>
     733  repository and the local file system. This is demonstrated in the next
     734  example.</p>
     735  <pre id="example_6">
     736# Example 6
     737# ----------------------------------------------------------------------
    741738cfg::type               ext
    742739cfg::version            1.0
    743740 
    744 dest::rootdir           $PWD
     741dest                    $PWD
    745742 
    746 repos::var::trunk       fcm:var_tr
    747 repos::ops::trunk       fcm:ops_tr
    748 repos::gen::trunk       fcm:gen_tr
     743repos::var::base        fcm:var_tr
     744repos::ops::base        fcm:ops_tr
     745repos::gen::base        fcm:gen_tr
    749746 
    750 version::gen::trunk     2468
     747revision::gen::base     2468
    751748 
    752 expsrc::var::trunk      code
    753 expsrc::var::trunk      scripts
    754 expsrc::ops::trunk      code
    755 src::gen::trunk         code/GenMod_Constants
    756 src::gen::trunk         code/GenMod_Control
    757 src::gen::trunk         code/GenMod_FortranIO
    758 src::gen::trunk         code/GenMod_GetEnv
    759 src::gen::trunk         code/GenMod_ModelIO
    760 src::gen::trunk         code/GenMod_ObsInfo
    761 src::gen::trunk         code/GenMod_Platform
    762 src::gen::trunk         code/GenMod_Reporting
    763 src::gen::trunk         code/GenMod_Trace
    764 src::gen::trunk         code/GenMod_UMConstants
    765 src::gen::trunk         code/GenMod_Utilities
    766 
    767 repos::var::new_stuff   fcm:var_br/frva/r1234_new_stuff
    768 repos::var::bug_fix     fcm:var_br/frva/r1516_bug_fix
    769 repos::ops::good_stuff  fcm:ops_br/opsrc/r3188_good_stuff
    770 
    771 repos::var::user        $HOME/var/src                     # line 31
    772 repos::gen::user        $HOME/gen/src                     # line 32
    773 </pre>
    774       </td>
    775     </tr>
    776   </table>
    777 
    778   <p>Example 6 is similar to example 5 except that it is also extracting from
    779   local directories. Here is an explanation of the lines:</p>
     749expsrc::var::base       src/code
     750expsrc::var::base       src/scripts
     751expsrc::ops::base       src/code
     752src::gen::base          src/code/GenMod_Constants
     753src::gen::base          src/code/GenMod_Control
     754src::gen::base          src/code/GenMod_FortranIO
     755src::gen::base          src/code/GenMod_GetEnv
     756src::gen::base          src/code/GenMod_ModelIO
     757src::gen::base          src/code/GenMod_ObsInfo
     758src::gen::base          src/code/GenMod_Platform
     759src::gen::base          src/code/GenMod_Reporting
     760src::gen::base          src/code/GenMod_Trace
     761src::gen::base          src/code/GenMod_UMConstants
     762src::gen::base          src/code/GenMod_Utilities
     763
     764repos::var::branch1     fcm:var_br/frva/r1234_new_stuff
     765repos::var::branch2     fcm:var_br/frva/r1516_bug_fix
     766repos::ops::branch1     fcm:ops_br/opsrc/r3188_good_stuff
     767
     768repos::var::user        $HOME/var                         # line 31
     769repos::gen::user        $HOME/gen                         # line 32
     770</pre>
     771
     772  <p><a href="#example_6">Example 6</a> is similar to <a href=
     773  "#example_5">example 5</a> except that it is also extracting from local
     774  directories. Here is an explanation of the lines:</p>
    780775
    781776  <ul>
    782     <li>line 31 to 32: these line declare the "repositories" for the "user"
    783     branches of the "var" and "gen" packages respectively. Both are local paths
    784     at the local file system. There are no declarations for source directories
    785     for the "user" branches, so they use the same set of source directories of
    786     the first declared branches, the "trunk" branches in both cases.</li>
     777    <li><dfn>line 31-32</dfn>: these line declare the repositories for the
     778    <samp>user</samp> branches of the <samp>var</samp> and <samp>gen</samp>
     779    packages respectively. Both are local paths at the local file system. There
     780    are no declarations for source directories for the <samp>user</samp>
     781    branches, so they use the same set of source directories of the first
     782    declared branches, the <samp>base</samp> branches in both cases.</li>
    787783  </ul>
    788784
    789   <table class="pad" summary="note - the inc statement" border="1" width=
    790   "100%">
    791     <tr>
    792       <th>Note - the INC declaration</th>
    793     </tr>
    794 
    795     <tr>
    796       <td>
    797         You have probably realised that the above examples have many repeated
    798         lines. To avoid having repeated lines in multiple extract configuration
    799         files, you can use INC declarations to "include" other extract
    800         configuration files. For example, if the configuration file of example 5
    801         is stored in the file "$HOME/var/example5/ext.cfg", line 1 to 29 of
    802         example 6 can be replaced with an INC declaration. Example 6 can then be
    803         written as:
    804         <pre>
    805 inc                     $HOME/var/example5/ext.cfg
    806 
    807 repos::var::user        $HOME/var/src
    808 repos::gen::user        $HOME/gen/src
    809 </pre>
    810 
    811         <p>Note: the INC declaration supports the special "environment variable"
    812         $HERE. If this variable is already set in the environment, it acts as a
    813         normal environment variable. However, if it is not set, it will be
    814         expanded into the container directory of the current extract
    815         configuration file. This feature is particularly useful if you are
    816         including a hierarchy of extract configurations from files in the same
    817         container directory in a repository.</p>
    818       </td>
    819     </tr>
    820   </table>
    821 
    822   <h3><a name="advanced_incremental">Incremental extract based on a previous
    823   extraction</a></h3>
    824 
    825   <p>All the examples above dealt with standalone extraction, that is, the
    826   current extraction is independent of any other extraction. If a previous
    827   extraction exists in another location, the extract system can "USE" this
    828   previous extraction in your current extraction. This works like a normal
    829   incremental extraction, except that your extraction will only contain the
    830   changes you have specified (compared with the USEd extraction) instead of the
    831   full source directory tree. This type of incremental extraction is useful in
    832   several ways. For instance:</p>
     785  <dl>
     786    <dt>Note - the INC declaration</dt>
     787
     788    <dd>
     789      You have probably realised that the above examples have many repeated
     790      lines. To avoid having repeated lines in multiple extract configuration
     791      files, you can use <code>INC</code> declarations to include other extract
     792      configuration files. For example, if the configuration file of example 5
     793      is stored in the file <samp>$HOME/example5/ext.cfg</samp>, line 1 to 29
     794      of <a href="#example_6">example 6</a> can be replaced with an
     795      <code>INC</code> declaration. <a href="#example_6">Example 6</a> can then
     796      be written as:
     797      <pre>
     798inc                     $HOME/example5/ext.cfg
     799
     800repos::var::user        $HOME/var
     801repos::gen::user        $HOME/gen
     802</pre>
     803
     804      <p>Note: the <code>INC</code> declaration supports the special
     805      environment variable <var>$HERE</var>. If this variable is already set in
     806      the environment, it acts as a normal environment variable. However, if it
     807      is not set, it will be expanded into the container directory of the
     808      current extract configuration file. This feature is particularly useful
     809      if you are including a hierarchy of extract configurations from files in
     810      the same container directory in a repository.</p>
     811    </dd>
     812  </dl>
     813
     814  <h3 id="advanced_inherit">Inherit from a previous extract</h3>
     815
     816  <p>All the examples above dealt with standalone extract, that is, the current
     817  extract is independent of any other extract. If a previous extract exists in
     818  another location, the extract system can inherit from this previous extract
     819  in your current extract. This works like a normal incremental extract, except
     820  that your extract will only contain the changes you have specified (compared
     821  with the inherited extract) instead of the full source directory tree. This
     822  type of incremental extract is useful in several ways. For instance:</p>
    833823
    834824  <ul>
    835     <li>The extraction is fast, because you only have to extract and mirror
    836     files that you have changed.</li>
     825    <li>It is fast, because you only have to extract and mirror files that you
     826    have changed.</li>
    837827
    838828    <li>The subsequent build will also be fast, since it will use incremental
    839829    build.</li>
    840830
    841     <li>You do not need write access to the original extraction. A system
     831    <li>You do not need write access to the original extract. A system
    842832    administrator can set up a stable version in a central account, which
    843     developers can then reuse.</li>
    844 
    845     <li>You want an incremental extraction, but you need to leave the original
    846     extraction unmodified.</li>
     833    developers can then inherit from.</li>
     834
     835    <li>You want an incremental extract, but you need to leave the original
     836    extract unmodified.</li>
    847837  </ul>
    848838
    849   <p>The following example is based on example 4 and 6. The assumption is that
    850   an extraction has already been performed at the directory "~frva/var/vn22.0"
    851   based on the configuration file in example 4.</p>
    852 
    853   <table class="pad" summary="extract_example7" border="1" width="100%">
    854     <tr>
    855       <th>Extract configuration example 7 - incremental extract based on a
    856       previous extraction</th>
    857     </tr>
    858 
    859     <tr>
    860       <td>
    861         <pre>
     839  <p>The following example is based on <a href="#example_4">example 4</a> and
     840  <a href="#example_6">example 6</a>. The assumption is that an extract has
     841  already been performed at the directory <samp>~frva/var/vn22.0</samp> based
     842  on the configuration file in <a href="#example_4">example 4</a>.</p>
     843  <pre id="example_7">
     844# Example 7
     845# ----------------------------------------------------------------------
    862846cfg::type               ext
    863847cfg::version            1.0
    864848 
    865 dest::rootdir           $PWD
     849dest                    $PWD
    866850
    867851use                     ~frva/var/vn22.0                  # line 6
    868852
    869 repos::var::new_stuff   fcm:var_br/frva/r1234_new_stuff   # line 8
    870 repos::var::bug_fix     fcm:var_br/frva/r1516_bug_fix     # line 9
    871 repos::ops::good_stuff  fcm:ops_br/opsrc/r3188_good_stuff # line 10
    872 
    873 repos::var::user        $HOME/var/src                     # line 12
    874 repos::gen::user        $HOME/gen/src                     # line 13
    875 </pre>
    876       </td>
    877     </tr>
    878   </table>
     853repos::var::branch1     fcm:var_br/frva/r1234_new_stuff   # line 8
     854repos::var::branch2     fcm:var_br/frva/r1516_bug_fix     # line 9
     855repos::ops::branch1     fcm:ops_br/opsrc/r3188_good_stuff # line 10
     856
     857repos::var::user        $HOME/var                         # line 12
     858repos::gen::user        $HOME/gen                         # line 13
     859</pre>
    879860
    880861  <ul>
    881     <li>line 6: this line replaces line 1 to 25 of example 6. It declares that
    882     the current extraction should be based on the previous extraction located
    883     at "~frva/var/vn22.0".</li>
     862    <li><dfn>line 6</dfn>: this line replaces line 1 to 25 of <a href=
     863    "#example_6">example 6</a>. It declares that the current extract should
     864    inherit from the previous extract located at
     865    <samp>~frva/var/vn22.0</samp>.</li>
    884866  </ul>
    885867
    886868  <p>Running the extract system using the above configuration will trigger an
    887   incremental extraction, as if you are running an incremental extraction
    888   having modified the configuration file in example 4 to that of example 6. The
    889   only difference is that the original extraction using the example 4
    890   configuration will be left untouched at "~frva/var/vn22.0", and the new
    891   extraction will contain only the changes in the branches declared from line 8
    892   to 13.</p>
    893 
    894   <p>If you are setting up an extraction to be reused, you do not have to
     869  incremental extract, as if you are running an incremental extract having
     870  modified the configuration file in <a href="#example_4">example 4</a> to that
     871  of <a href="#example_6">example 6</a>. The only difference is that the
     872  original extract using the <a href="#example_4">example 4</a> configuration
     873  will be left untouched at <samp>~frva/var/vn22.0</samp>, and the new extract
     874  will contain only the changes in the branches declared from line 8 to 13.</p>
     875
     876  <p>Note: extract inheritance allows you to add more branches to a package,
     877  but you should not redefine the <code>REPOS</code>, <code>REVISION</code>,
     878  <code>EXPSRC</code> or <code>SRC</code> declarations of a branch that is
     879  already declared (and already extracted) in the inherited extract. Although
     880  the system will not stop you from doing so, you may end up with an extract
     881  that does not quite do what it is supposed to do. For example, if the
     882  <samp>base</samp> branch in the <samp>foo</samp> package
     883  (<tt>repos::foo::base</tt>) is already defined and extracted in an extract
     884  you are inheriting from, you should not redefine any of the
     885  <tt>*::foo::base</tt> declarations in your current extract. However, you are
     886  free to add more branches for the same package with new labels (e.g.
     887  <tt>repos::foo::b1</tt>), and indeed new packages that are not already
     888  defined in the inherited extract (e.g. <tt>repos::bar::base</tt>).</p>
     889
     890  <p>If you are setting up an extract to be inherited, you do not have to
    895891  perform a build. If you don't you will still gain the benefit of incremental
    896   file extraction, but you will be performing a full build of the code.</p>
    897 
    898   <h3><a name="advanced_build">Extract - Build Configuration</a></h3>
     892  file extract, but you will be performing a full build of the code.</p>
     893
     894  <dl>
     895    <dt>Note - inherit and mirror</dt>
     896
     897    <dd>
     898      <p>It is worth bearing in mind that <tt>rdest::*</tt> settings are not
     899      inherited. If mirroring is required in the inheriting extract, it will
     900      require its own set of <tt>rdest::*</tt> declarations.</p>
     901
     902      <p>The system will, however, assume that a mirrored version of the
     903      inherited extract is available for inheritance from the mirrored
     904      destination of the current extract.</p>
     905     
     906      <p>E.g.: Consider an extract at <samp>/path/to/inherited/</samp> and an
     907      inheriting extract at <samp>/path/to/current/</samp>. If the former does
     908      not have a mirror, the latter should not have one either. If the former
     909      mirrors to <samp>machine@/path/to/inherited/mirror/</samp> and the latter
     910      mirrors to <samp>machine@/path/to/current/mirror/</samp>, the system will
     911      assume that the subsequent build at
     912      <samp>machine@/path/to/current/mirror/</samp> can inherit from the build
     913      at <samp>machine@/path/to/inherited/mirror/</samp>. This is illustrated
     914      below:</p>
     915
     916      <pre>
     917/path/to/current/       =&gt; at machine: /path/to/current/mirror/
     918use /path/to/inherited/ =&gt; at machine: use /path/to/inherited/mirror/
     919</pre>
     920    </dd>
     921  </dl>
     922
     923  <h3 id="advanced_build">Extract - Build Configuration</h3>
    899924
    900925  <p>Configuration settings for feeding into the build system can be declared
    901   through the extract configuration file using the "BLD::" prefix. Any line in
    902   an extract configuration containing a label with such a prefix will be
    903   considered a build system variable. At the end of a successful extraction,
    904   the system strips out the "BLD::" prefix before writing these variables to
    905   the build configuration file. Some example entries are given between line 17
    906   and 22 in the following configuration file:</p>
    907 
    908   <table class="pad" summary="extract_example8" border="1" width="100%">
    909     <tr>
    910       <th>Extract configuration example 8 - setting build configuration</th>
    911     </tr>
    912 
    913     <tr>
    914       <td>
    915         <pre>
     926  through the extract configuration file using the <code>BLD::</code> prefix.
     927  Any line in an extract configuration containing a label with such a prefix
     928  will be considered a build system variable. At the end of a successful
     929  extract, the system strips out the <code>BLD::</code> prefix before writing
     930  these variables to the build configuration file. Some example entries are
     931  given between line 17 and 22 in the following configuration file:</p>
     932  <pre id="example_8">
     933# Example 8
     934# ----------------------------------------------------------------------
    916935cfg::type           ext
    917936cfg::version        1.0
    918937
    919 dest::rootdir       $PWD
    920 
    921 repos::var::trunk   fcm:var_tr
    922 repos::ops::trunk   fcm:ops_tr
    923 repos::gen::trunk   fcm:gen_tr
    924 
    925 version::gen::trunk 2468
    926 
    927 expsrc::var::trunk  code
    928 expsrc::var::trunk  scripts
    929 expsrc::ops::trunk  code
    930 src::gen::trunk     code/GenMod_Constants
    931 src::gen::trunk     code/GenMod_Control
    932 src::gen::trunk     code/GenMod_FortranIO
    933 src::gen::trunk     code/GenMod_GetEnv
    934 src::gen::trunk     code/GenMod_ModelIO
    935 src::gen::trunk     code/GenMod_ObsInfo
    936 src::gen::trunk     code/GenMod_Platform
    937 src::gen::trunk     code/GenMod_Reporting
    938 src::gen::trunk     code/GenMod_Trace
    939 src::gen::trunk     code/GenMod_UMConstants
    940 src::gen::trunk     code/GenMod_Utilities
     938dest                $PWD
     939
     940repos::var::base    fcm:var_tr
     941repos::ops::base    fcm:ops_tr
     942repos::gen::base    fcm:gen_tr
     943
     944revision::gen::base 2468
     945
     946expsrc::var::base   src/code
     947expsrc::var::base   src/scripts
     948expsrc::ops::base   src/code
     949src::gen::base      src/code/GenMod_Constants
     950src::gen::base      src/code/GenMod_Control
     951src::gen::base      src/code/GenMod_FortranIO
     952src::gen::base      src/code/GenMod_GetEnv
     953src::gen::base      src/code/GenMod_ModelIO
     954src::gen::base      src/code/GenMod_ObsInfo
     955src::gen::base      src/code/GenMod_Platform
     956src::gen::base      src/code/GenMod_Reporting
     957src::gen::base      src/code/GenMod_Trace
     958src::gen::base      src/code/GenMod_UMConstants
     959src::gen::base      src/code/GenMod_Utilities
    941960
    942961bld::target         VarProg_AnalysePF.exe   # line 27
    … …  
    946965bld::tool::ld       sxmpif90                # line 31
    947966</pre>
    948       </td>
    949     </tr>
    950   </table>
    951 
    952   <p>The above example is essentially the same as example 4, apart from the
    953   additional build configuration. The following is a simple explanation of what
    954   the lines represent: (For detail of the build system, please see the next
    955   chapter on <a href="build.html">The Build System</a>.)</p>
     967
     968  <p>The above example is essentially the same as <a href="#example_4">example
     969  4</a>, apart from the additional build configuration. The following is a
     970  simple explanation of what the lines represent: (For detail of the build
     971  system, please see the next chapter on <a href="build.html">The Build
     972  System</a>.)</p>
    956973
    957974  <ul>
    958     <li>Line 27: the line declares a default target of the build.</li>
    959 
    960     <li>Line 29-31: the lines declare the Fortran compiler, the C compiler and
    961     the linker respectively.</li>
     975    <li><dfn>line 27</dfn>: the line declares a default target of the
     976    build.</li>
     977
     978    <li><dfn>line 29-31</dfn>: the lines declare the Fortran compiler, the C
     979    compiler and the linker respectively.</li>
    962980  </ul>
    963981
    964   <table class="pad" summary="note - user variable" border="1" width=
    965   "100%">
    966     <tr>
    967       <th>Note - user variable</th>
    968     </tr>
    969 
    970     <tr>
    971       <td>When you start using the extract system to define compiler flags for
     982  <dl>
     983    <dt>Note - use of variables</dt>
     984
     985    <dd>
     986      <p>When you start using the extract system to define compiler flags for
    972987      the build system, you may end up having to make a lot of long and
    973       repetitive declarations. In such case, you may want to define variables to
    974       replace the repetitive parts of the declarations. In the extract system,
    975       you can define a local variable by making a declaration with a label that
    976       begins with a percent sign "%". For example:
    977 
    978         <pre>
     988      repetitive declarations. In this case, you may want to define variables
     989      to replace the repetitive parts of the declarations.</p>
     990
     991      <p>Environment variables whose names contain only upper case latin
     992      alphabets, numbers and underscores can be referenced in a declaration
     993      value via the syntax <code>$NAME</code> or <code>${NAME}</code>. For
     994      example:</p>
     995      <pre>
     996repos::um::base    ${HOME}/svn-wc/um
     997bld::tool::fflags  $MY_FFLAGS
     998</pre>
     999     
     1000      <p>You can define a user variable by making a declaration with a label
     1001      that begins with a percent sign <code>%</code>. The value of a user
     1002      variable remains in memory until the end of the current file is reached.
     1003      You can reference a user variable in a declaration value via the syntax
     1004      <code>%NAME</code> or <code>%{NAME}</code>. For example:</p>
     1005      <pre>
    9791006# Declare a variable %fred
    9801007%fred                     -Cdebug -eC -Wf,-init heap=nan stack=nan
    … …  
    9891016# bld::tool::fflags::bar  -w -Cdebug -eC -Wf,-init heap=nan stack=nan
    9901017</pre>
    991       </td>
    992     </tr>
    993   </table>
    994 
    995   <h2><a name="verbose">Diagnostic verbose level</a></h2>
     1018
     1019      <p>Further to this, each declaration results in an internal variable of
     1020      the same name and you can also refer to any of these internal variables in
     1021      the same way. So, the example given above could also be written as
     1022      follows:</p>
     1023      <pre>
     1024bld::tool::fflags         -Cdebug -eC -Wf,-init heap=nan stack=nan
     1025bld::tool::fflags::foo    %bld::tool::fflags -f0
     1026bld::tool::fflags::bar    -w %bld::tool::fflags
     1027</pre>
     1028    </dd>
     1029
     1030    <dt>Note - as-parsed configuration</dt>
     1031
     1032    <dd>
     1033      <p>If you use a hierarchy of <code>INC</code> declarations or variables,
     1034      you may end up with a configuration file that is difficult to understand.
     1035      To help you with this, the extract system generates an as-parsed
     1036      configuration file at <samp>cfg/parsed_ext.cfg</samp> of the destination.
     1037      The content of the as-parsed configuration file is what the extract
     1038      system actually reads. It should contain everything in your original
     1039      extract configuration file, except that all <code>INC</code>
     1040      declarations, environment variables and user/internal variables are
     1041      expanded.</p>
     1042    </dd>
     1043  </dl>
     1044
     1045  <h2 id="verbose">Diagnostic verbose level</h2>
    9961046
    9971047  <p>The amount of diagnostic messages generated by the extract system is
    … …  
    10011051  diagnostic messages, you can set the verbose level to 2 or 3. You can modify
    10021052  the verbose level in two ways. The first way is to set the environment
    1003   variable FCM_VERBOSE to the desired verbose level. The second way is to
    1004   invoke the extract system with the "-v &lt;level&gt;" option. (If set, the
    1005   command line option overrides the environment variable.)</p>
     1053  variable <var>FCM_VERBOSE</var> to the desired verbose level. The second way
     1054  is to invoke the extract system with the <code>-v &lt;level&gt;</code>
     1055  option. (If set, the command line option overrides the environment
     1056  variable.)</p>
    10061057
    10071058  <p>The following is a list of diagnostic output at each verbose level:</p>
    10081059
    1009   <table class="pad" summary="List of diagnostic verbose output" border="1">
    1010     <tr>
    1011       <th>Verbose level</th>
    1012 
    1013       <th>Possible output</th>
    1014     </tr>
    1015 
    1016     <tr>
    1017       <th>0</th>
    1018 
    1019       <td>
    1020         <ul>
    1021           <li>Report the time taken to extract the code.</li>
    1022 
    1023           <li>Report the time taken to mirror the code.</li>
    1024 
    1025           <li>If "rdist" is used to mirror the code, run the command with the
    1026           "-q" option.</li>
    1027         </ul>
    1028       </td>
    1029     </tr>
    1030 
    1031     <tr>
    1032       <th>1</th>
    1033 
    1034       <td>
    1035         <ul>
    1036           <li>Everything at verbose level 0.</li>
    1037 
    1038           <li>Report the name of the extract configuration file.</li>
    1039 
    1040           <li>Report date/time at the beginning of the extract step.</li>
    1041 
    1042           <li>Report the number of directories created, number of ignored
    1043           sub-directories, number of files updated and number of removed
    1044           files.</li>
    1045 
    1046           <li>In override mode, report any files that are modified in two or
    1047           more branches.</li>
    1048 
    1049           <li>Report date/time at the beginning of the mirror step.</li>
    1050 
    1051           <li>Report total time.</li>
    1052         </ul>
    1053       </td>
    1054     </tr>
    1055 
    1056     <tr>
    1057       <th>2</th>
    1058 
    1059       <td>
    1060         <ul>
    1061           <li>Everything at verbose level 1.</li>
    1062 
    1063           <li>If the revision specified for a repository branch is not current
    1064           (i.e. the specified revision number is less than the revision number
    1065           of the last commit revision), print an information statement to
    1066           inform the user of the last commit revision of the branch.</li>
    1067 
    1068           <li>Report details of created directories, ignored sub-directories,
    1069           removed files and updated files.</li>
    1070 
    1071           <li>Report any files that have the same modifications in two or more
    1072           branches.</li>
    1073 
    1074           <li>If "rdist" is used to mirror the code, run the command without the
    1075           "-q" option.</li>
    1076         </ul>
    1077       </td>
    1078     </tr>
    1079 
    1080     <tr>
    1081       <th>3</th>
    1082 
    1083       <td>
    1084         <ul>
    1085           <li>Everything at verbose level 2.</li>
    1086 
    1087           <li>Report all shell commands invoked by the extract system with
    1088           timestamp.</li>
    1089 
    1090           <li>If "rdist" is used to mirror the code, print the "distfile"
    1091           supplied to the command.</li>
    1092 
    1093           <li>If "rsync" is used to mirror the code, invoke the command with
    1094           the "-v" option.</li>
    1095         </ul>
    1096       </td>
    1097     </tr>
    1098   </table>
    1099 
    1100   <h2><a name="nosvn">When Subversion Is Not Available</a></h2>
     1060  <dl>
     1061    <dt>Level 0</dt>
     1062
     1063    <dd>
     1064      <ul>
     1065        <li>Report the time taken to extract the code.</li>
     1066
     1067        <li>Report the time taken to mirror the code.</li>
     1068
     1069        <li>If <code>rdist</code> is used to mirror the code, run the command
     1070        with the <code>-q</code> option.</li>
     1071      </ul>
     1072    </dd>
     1073
     1074    <dt>Level 1</dt>
     1075
     1076    <dd>
     1077      <ul>
     1078        <li>Everything at verbose level 0.</li>
     1079
     1080        <li>Report the name of the extract configuration file.</li>
     1081
     1082        <li>Report the location of the extract destination.</li>
     1083
     1084        <li>Report date/time at the beginning of the extract step.</li>
     1085
     1086        <li>If the revision specified for a repository branch is not its last
     1087        changed revision, print an information statement to inform the user of
     1088        the last changed revision of the branch.</li>
     1089
     1090        <li>Summarises the destination status and the source status.</li>
     1091
     1092        <li>Report date/time at the beginning of the mirror step.</li>
     1093
     1094        <li>Report the location of the alternate destination.</li>
     1095
     1096        <li>Report total time.</li>
     1097      </ul>
     1098    </dd>
     1099
     1100    <dt>Level 2</dt>
     1101
     1102    <dd>
     1103      <ul>
     1104        <li>Everything at verbose level 1.</li>
     1105
     1106        <li>If the revision specified for a repository branch is not current
     1107        (i.e. the specified revision number is less than the revision number of
     1108        the last commit revision), print an information statement to inform the
     1109        user of the last commit revision of the branch.</li>
     1110
     1111        <li>Report the detail of each change in the destination.</li>
     1112
     1113        <li>If <code>rdist</code> is used to mirror the code, run the command
     1114        without the <code>-q</code> option.</li>
     1115      </ul>
     1116    </dd>
     1117
     1118    <dt>Level 3</dt>
     1119
     1120    <dd>
     1121      <ul>
     1122        <li>Everything at verbose level 2.</li>
     1123
     1124        <li>Report all shell commands invoked by the extract system with
     1125        timestamp.</li>
     1126
     1127        <li>If <code>rdist</code> is used to mirror the code, print the
     1128        <samp>distfile</samp> supplied to the command.</li>
     1129
     1130        <li>If <code>rsync</code> is used to mirror the code, invoke the
     1131        command with the <code>-v</code> option.</li>
     1132      </ul>
     1133    </dd>
     1134  </dl>
     1135
     1136  <h2 id="nosvn">When Subversion Is Not Available</h2>
    11011137
    11021138  <p>The extract system can still be used if Subversion is not available.
    11031139  Clearly, you can only use local repositories. However, you can still do
    1104   incremental extraction, mirror an extraction to another machine, or combine
     1140  incremental extract, mirror an extract to an alternate location, or combine
    11051141  code from multiple local repositories.</p>
    11061142
    11071143  <p>If you are using Subversion but your server is down then clearly there is
    1108   little you can do. However, if you already have an extraction then you can
    1109   re-run <tt>fcm extract</tt> as long as the extract configuration file only
    1110   refers to fixed revisions. If this is not the case then you can always use the
    1111   expanded extract configuration file which can be found in "cfg/ext.cfg" under
    1112   the extract destination root. This means that you can continue to makes changes
    1113   to local code and do incremental extractions even whilst your Subversion server
    1114   is down.</p>
    1115 
    1116   <script type="text/javascript" src="maintain.js"></script>
     1144  little you can do. However, if you already have an extract then you can
     1145  re-run <code>fcm extract</code> as long as the extract configuration file
     1146  only refers to fixed revisions. If this is not the case then you can always
     1147  use the expanded extract configuration file which can be found in
     1148  <samp>cfg/ext.cfg</samp> under the extract destination root. This means that
     1149  you can continue to makes changes to local code and do incremental extracts
     1150  even whilst your Subversion server is down.</p>
     1151
     1152  </div>
     1153  </div>
     1154  </div>
     1155
     1156  <hr/>
     1157  <div class="container-fluid text-center">
     1158    <div class="row"><div class="col-md-12">
     1159    <address><small>
     1160      Copyright &copy; 2006-2021 British Crown (Met Office) &amp; Contributors.
     1161      <a href="http://www.metoffice.gov.uk">Met Office</a>.
     1162      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
     1163      This document is released under the British <a href=
     1164      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
     1165      "license">Open Government Licence</a>.<br />
     1166    </small></address>
     1167    </div></div>
     1168  </div>
     1169
     1170  <script type="text/javascript" src="../etc/jquery.min.js"></script>
     1171  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
     1172  <script type="text/javascript" src="../etc/fcm.js"></script>
     1173  <script type="text/javascript" src="../etc/fcm-version.js"></script>
    11171174</body>
    11181175</html>
Note: See TracChangeset for help on using the changeset viewer.